diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index 51ed78a..fedd089 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -273,9 +273,17 @@ attached/next values, boolean assignments, terminators, and unknown spellings. Shared classification helpers cover only part of the grammar, leaving changes to cross the core/backend boundary. -Share a small neutral token-consumption primitive. Keep execution normalization, -failure provenance, and partial-word completion policies in their existing -owners rather than introducing a common public parser. +**Decision:** share a small flag-consumption operation through the existing +neutral internal helpers. Share facts about flag identity, attached versus +missing values, consumption of the next argument, and short-cluster position. +Keep execution normalization, failure provenance, and partial-word completion +policies in their existing owners. Preserve explicitly empty values and current +CLI behavior; no public parser or replacement backend is selected. + +Retain caller-specific branches where combining them would require extensive +modes or special cases. Repair F06's completion fixture before validating this +refactor. The [F16 analysis](remediation-analysis.md#f16--shared-flag-consumption) +records the accepted boundary; implementation remains pending. **Original:** [03-complexity M3](03-complexity.md#m3--p3-parsing-and-completion-maintain-parallel-flag-consumption-logic). diff --git a/docs/roadmap/audit/remediation-analysis.md b/docs/roadmap/audit/remediation-analysis.md index 6d5bcc3..f98d6cc 100644 --- a/docs/roadmap/audit/remediation-analysis.md +++ b/docs/roadmap/audit/remediation-analysis.md @@ -8,7 +8,7 @@ decisions, and their status. Original audits retain detailed evidence. Record accepted conclusions in the catalog and mark the corresponding discussion here decided; a decision does not close a finding before implementation. -Existing catalog decisions for F03, F10, F11, F13–F15, and F21 remain selected. In +Existing catalog decisions for F03, F10, F11, F13–F16, and F21 remain selected. In particular, performance testing is not a prerequisite for F13–F15, and F14 and F15 are to be designed together. CommandKit is pre-release with no consumers; consumer compatibility and migration are not constraints on these choices. @@ -18,8 +18,8 @@ Straightforward correctness repairs need not wait for this discussion sequence. | --- | --- | --- | --- | | 1 | F10 | Which flag declaration rules should be documented as the intended contract? | Decided: retain and document existing rules; remediation pending | | 2 | F21 | What narrow diagnostic adaptation API would simplify both integrations? | Decided: shared public ckconfig helper; remediation pending | -| 3 | F16 | Which flag-consumption facts can parsing and completion usefully share? | Callers compared; recommendation pending agreement | -| 4 | F14–F15 | How should both operations reuse source-prefix processing? | Joint design pending; remediation selected | +| 3 | F16 | Which flag-consumption facts can parsing and completion usefully share? | Decided: shared internal mechanics, separate caller policies; remediation pending | +| 4 | F14–F15 | How should both operations reuse source-prefix processing? | Existing tree inspected; reuse recommendation pending agreement | | 5 | F17–F20 | Which private extractions materially simplify the existing code? | Individual extraction review pending | ## F10 — Flag declaration naming @@ -186,7 +186,9 @@ paths, preserving explicit empties, short clusters, and entered spelling. If a proposed extraction needs extensive caller-specific controls, narrow it and retain the remaining duplication rather than forcing complete unification. -**Decision:** recommendation pending agreement; no refactor is implemented. +**Decision:** the recommended internal sharing boundary is accepted and recorded +in the catalog. Execution and completion retain their separate policies; exact +private signatures remain implementation choices. No refactor is implemented. ## F14–F15 — Joint source-prefix design @@ -200,12 +202,47 @@ and [F15](catalog.md#f15--p3-alias-help-scans-the-entire-source-catalog-for-each alias source structure, or one shared private index if the existing structure cannot serve both operations simply. -**Preliminary recommendation:** prefer reuse; preserve classification, -authoritative resolution, deduplication, and ordering. Select the concrete -traversal and ownership together. No performance test is required to justify -remediation; correctness validation remains appropriate. +**Analysis:** the existing [alias resolver](../../../internal/alias/resolver.go) +already builds a source-path tree. Each node represents one distinct prefix, +has child links, and identifies whether a mapping ends there. Shared source +prefixes therefore already have a single structural representation. -**Decision:** joint remediation selected in the catalog; concrete design pending. +F14's `discoverFlagContexts` in [flag_aliases.go](../../../flag_aliases.go) +instead walks each declaration independently, repeatedly copying and classifying +common prefixes before deduplicating accepted results. F15's `routeHelpAliases` +in [help_view.go](../../../help_view.go) scans the full alias catalog at every +intermediate rewrite path, even when that prefix has no descendants. + +For example, sources `legacy team show` and `legacy team check` share `legacy` +and `legacy team`. Setup can examine each shared prefix once. Help at +`legacy team` can find its descendants through that tree branch without scanning +unrelated source paths. + +**Recommendation:** add narrow internal read-only operations on the existing +resolver tree for these two needs: + +1. Enumerate each distinct nonempty proper source prefix once for F14. Apply + the existing discovery classification once per candidate, retaining exclusions + for canonical paths, exact alias sources, and valid canonical operand space. +2. Find strictly descendant alias sources beneath a supplied prefix for F15. + Continue visiting the existing intermediate resolution paths. Resolve each + composed entered path through the authoritative resolver, then retain current + canonical-target checks, suffix deduplication, and output sorting. + +Keep trie nodes private and preserve captured path ownership. Reuse the tree's +existing routing-snapshot lifetime rather than creating a parallel index or a +cross-invocation result cache. Root help can continue using the complete catalog +when it actually needs all entries. No public API or routing grammar change is +needed; internal method names and return shapes remain implementation choices. + +This removes the identified repeated scans and preparation, without claiming +that all routing or installation costs become linear. Test the preserved +discovery/help behavior, including shared prefixes, chains, longer overrides, +and updated registration where relevant. As already decided, performance testing +is not a prerequisite for remediation. + +**Decision:** joint remediation is selected in the catalog; reuse of the existing +tree through these internal operations is recommended, pending agreement. ## F17–F20 — Proportionate private extractions