Skip to content

Return flag tokens instead of mutating a list in place#51

Merged
lesnik512 merged 2 commits into
mainfrom
worktree-uniform-flag-composition
Jul 13, 2026
Merged

Return flag tokens instead of mutating a list in place#51
lesnik512 merged 2 commits into
mainfrom
worktree-uniform-flag-composition

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Summary

  • run_flags (emit.py) composed six flag sources in ten lines using two conventions: three helpers mutated a list passed in (_add_env_flags, _add_volume_flags, _add_health_flags, all -> None), while three returned a list to concatenate (KeySpec.emit, stores.flags, deploy_resource_flags).
  • The return convention is the one every other flag source in the package follows, including pod.py's helpers (composed by pod_create_flags as a + b + c). These three were the only exceptions, sitting directly beside three return-style calls in the same function.
  • Converts them to return list[Token] and renames them (_env_flags/_volume_flags/_health_flags) since the _add_ prefix described the side effect.
  • Behavior-preserving. No bug is closed; this is a consistency fix. Candidate docs: add 0.1.1 release notes #5 (the last) from the 2026-07-13 architecture review — the review itself rated it Speculative, and it's shipped here only because it's cheap and leaves one convention instead of two.

Rationale: planning/changes/2026-07-13.09-uniform-flag-composition.md (Lightweight lane).

Test plan

  • just test-ci — 407 passed (unchanged count), 100% line coverage
  • just lint-ci — clean
  • Byte-identical output verified. Generated a script from a compose file exercising all three helpers (env vars incl. a bare passthrough; all four volume forms — relative bind, absolute bind, anonymous, named; tmpfs; a full healthcheck) with the old and new code and diffed: both the 46-line script and the stderr variable-warning note are byte-identical.
  • Subagent review — approved; independently re-ran the gates and traced the mutate→return conversion for ordering/accumulation/early-return correctness. Its one Minor finding (an imprecise line in the change file's naming rationale) is fixed in 22c7dec.

The three _add_*_flags helpers were the only flag sources in the package
that mutated a list passed in rather than returning list[Token] -- the
convention KeySpec.emit, stores.flags, deploy_resource_flags, and pod.py's
own helpers all follow. They sat beside three return-style calls in the same
ten-line run_flags body. Behavior-preserving: the generated script is
byte-identical.
…change file

pod.py's _add_host_flags returns tokens while keeping the _add_ prefix, so
the package is not uniform on this; say so rather than implying the prefix
always tracks mutation.
@lesnik512 lesnik512 merged commit 10bf175 into main Jul 13, 2026
7 checks passed
@lesnik512 lesnik512 deleted the worktree-uniform-flag-composition branch July 13, 2026 19:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant