Skip to content

Collocation: fold src/cli-schema into src/commands/schema, move batch-steps into src/commands/batch #2679

Closed

Description

@thymikee

Purpose

Split out from #2677: the collocation plan posted there proposes a sequence of src/-touching file moves ("PR A/B/C") derived from the coupling/legibility measures that issue builds. Per a follow-up note, guard 9 on #2677 keeps that issue tooling-only (nothing under src//packages/ changes there), so the moves themselves belong in their own issue(s) rather than under #2677.

This issue tracks "PR A" from the plan: move 1 plus the bundled small move.

Scope

  • Fold src/cli-schema/* (8 production + 8 colocated test files) into src/commands/schema/*. cli-schema is a standalone zone with Q ≈ 0, out/in flow 30, touching 29 of 39 families, and reader-condition legibility in the high-30s/low-40s depending on measurement — the plan's clearest "wrongly-a-family" candidate. It exists only to render the command facets commands/ already owns (refactor(cli-schema): orient the schema layer below commands #2543 declared that direction).
  • Move src/cli/batch-steps.ts into src/commands/batch/batch-steps.ts (its only relative import and only real importer already live under src/commands/).
  • Pure move, no behavior change: update every import site, the literal owner-files path in src/cli/command-explain.ts, the layering model's zone ranking (folded files resolve to the commands zone by directory, so the standalone cli-schema rank entry is dropped), fallow-baselines/health.json's path-keyed findings, and doc pointers (AGENTS.md, docs/agents/cli-flags.md).

Sequencing note

Per the same follow-up comment, this move should be rebased onto apex/module-shape-measures (the branch implementing #2677's Layer A/B tooling — pnpm coupling / pnpm legibility) so the before/after coupling and legibility numbers are attributable to the move alone, not confounded by the tooling landing separately.

At the time of writing, apex/module-shape-measures (86741f2) is 4 commits behind main, including #2665 (feat(cli): open --wait, flag suggestions, and refusals that name what to run), which also touches src/cli/parser/command-suggestions.ts — one of the files this move touches. Rebasing onto apex/module-shape-measures as-is produces a real conflict there (not just a mechanical one: apex is missing #2665's new suggestFlagFor/flag-suggestion code entirely, so the conflict isn't resolvable by picking a side without either dropping this move's import-path fix for that file or pulling in unrelated feature work). Rebasing cleanly needs apex/module-shape-measures refreshed against current main first.

Acceptance

  • All import sites updated, no stray cli-schema or old batch-steps.ts path references
  • pnpm lint, pnpm typecheck, pnpm format:check, pnpm check:layering, pnpm check:gate-manifest pass
  • pnpm test:unit passes (pre-existing unrelated failures excepted)
  • Rebased onto an up-to-date apex/module-shape-measures, with pnpm coupling before/after numbers in the PR description
  • Base/head SHAs handed off for the pnpm legibility (Jev) before/after measurement, per the offer in Add report-only module-shape measures: placement legibility (Jev) and change-coupling modularity #2677 (comment)

Activity

  1. thymikee commented on Sep 21, 2026

    @thymikee
    MemberAuthor

    Closed against main at 45e4c594a1 (0.21.8). PR #2678 (8bbf7c67a5) delivered the move.

    Verified on the current tree:

    • src/cli-schema/ and src/cli/batch-steps.ts do not exist; src/commands/schema/ (8 production + 8 colocated tests) and src/commands/batch/batch-steps.ts do.
    • Layering: the standalone cli-schema rank entry is gone and scripts/layering/zone-policy.ts:48-50 records why the row was dropped; the folded direction is pinned by scripts/layering/commands-schema-boundary.ts with commands-schema-boundary.test.ts.
    • fallow-baselines/health.json is re-keyed — no findings remain under the old path.
    • Doc pointers moved: AGENTS.md, docs/agents/cli-flags.md.
    • No live path reference to cli-schema survives. What stays is historical: docs/adr/0019-request-bound-platform-runtime.md:946, docs/dependency-graph-findings.md:377, and explanatory comments in scripts/layering/*. One stale comment in scripts/help-conformance-cases.mjs:36 still names src/cli-schema/cli-help.ts as the help-topic source.

    Acceptance items 1-3 are satisfied by the gates that ran on the merged commit.

    Items 4 and 5 are unsatisfiable as written, not skipped: apex/module-shape-measures (86741f2be2) was never merged and has no PR, so pnpm coupling and pnpm legibility do not exist on main to measure with. The move merged directly to main instead of stacking. If #2677 lands later, its baselines will simply capture the folded layout, and this move's before/after delta is unrecoverable — which is the cost this sequencing note was trying to prevent. Recording it here rather than leaving the issue open for a measurement that can no longer be taken.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions