base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Record flag consumption decision and joint alias analysis

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 14:49:56 +00:00
parent 9e0f2d28cd
commit 485a27a662
2 changed files with 57 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
docs/roadmap/audit/remediation-analysis.md
View File

@@ -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