diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index fedd089..839c62e 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -245,10 +245,17 @@ The source declarations contain only Θ(RD) tokens. Traverse distinct source prefixes once and classify each once. For the audited shape, this phase can become O(RD + D²). -**Decision:** design F14 and F15 together around shared source-prefix processing, -preferably reusing the existing alias source structure rather than adding parallel -indexes. The repeated preparation and help-time scan remain distinct findings. -The performance-testing decision under F13 applies to both. +**Decision:** implement F14 and F15 together using the existing alias resolver's +source-path tree. Add narrow internal read-only operations to enumerate distinct +nonempty proper prefixes for F14 and find strictly descendant alias sources for +F15. Retain the existing discovery classification and exclusions, applying them +once per candidate prefix. + +Reuse the tree's routing-snapshot lifetime; do not introduce a parallel index or +a cross-invocation result cache. The repeated preparation and help-time scan +remain distinct findings. The [joint analysis](remediation-analysis.md#f14f15--joint-source-prefix-design) +records the accepted design. The performance-testing decision under F13 applies +to both; implementation remains pending. **Original:** [02-efficiency E3](02-efficiency.md#e3--p3-discovery-context-preparation-rebuilds-shared-prefixes-repeatedly). @@ -259,8 +266,14 @@ examinations and repeated copies even when there are no descendants. A valid single-token alias chain produces Θ(A²) work to discover an empty alias section on every such help request. -Query an immutable source-prefix index for strict descendants. The identified -discovery work becomes O(A) for that example; general cases still pay for +**Decision:** query the existing resolver tree for strict descendants through +the internal operation shared with F14's design. Continue visiting intermediate +resolution paths, resolving composed entered paths through the existing +resolver, and retaining canonical-target checks, suffix deduplication, and +output sorting. Root help may retain the complete catalog when all entries are +needed. No public API or CLI behavior change is selected. + +The identified discovery work becomes O(A) for that example; general cases still pay for matching candidates, resolution, and output sorting. Design this together with F14 under the decisions recorded there and in F13. diff --git a/docs/roadmap/audit/remediation-analysis.md b/docs/roadmap/audit/remediation-analysis.md index f98d6cc..7a1eb0e 100644 --- a/docs/roadmap/audit/remediation-analysis.md +++ b/docs/roadmap/audit/remediation-analysis.md @@ -19,8 +19,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? | 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 | +| 4 | F14–F15 | How should both operations reuse source-prefix processing? | Decided: reuse existing resolver tree; remediation pending | +| 5 | F17–F20 | Which private extractions materially simplify the existing code? | Functions reviewed; individual recommendations pending agreement | ## F10 — Flag declaration naming @@ -241,8 +241,11 @@ 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. +**Decision:** reuse of the existing resolver tree through the two internal +operations above is accepted and recorded in the catalog. Preserve existing +discovery and routing semantics; no parallel index, new cache lifecycle, public +API change, or performance-testing prerequisite is selected. Implementation +remains pending. ## F17–F20 — Proportionate private extractions @@ -257,9 +260,92 @@ and [F20](catalog.md#f20--p3-reporter-message-paths-duplicate-detail-rendering-b **Options to examine:** cohesive functions over existing private types, or retaining related code together where extraction only adds indirection. -**Preliminary recommendation:** review each extraction separately. F20 has a -concrete shared rendering/error policy; keep its refactor distinct from F03's -correctness repair. For F17–F19, make meaningful responsibilities and required -ordering visible without treating incidental private sequences as contracts. +These are maintenance improvements, not newly established incorrect CLI +outcomes. Recommendations below use existing private types and ordinary +functions. No public API, generic pipeline, or additional validation policy is +needed. Keep related work together; a lower function-length or complexity score +is not itself a completion criterion. -**Decision:** individual extraction choices pending review. +### F17 — Separate configuration suite setup responsibilities + +**Analysis:** `captureSuite` in [family.go](../../../integrations/ckconfig/family.go) +captures scope and selector declarations, validates provider wiring, attaches +selectors to scopes, determines command availability, and builds discovery +metadata. Maintaining one of those responsibilities requires understanding +several partially populated collections. + +**Recommendation:** extract cohesive scope capture/validation and selector +attachment responsibilities, then make operation bindings and discovery +inventory construction explicit. Keep related loops together and use the +existing prepared-suite types. Retain declaration ownership, accumulated +errors and their order, binding identity, and metadata-only construction. +Do not load configuration or invoke application factories during this setup. + +The benefit is making it clear where a new scope or selector rule belongs. +Exact helper boundaries can follow the implementation; do not create a helper +for each loop or new intermediate records merely to divide the function. + +### F18 — Separate ordinary configuration preparation from comparison + +**Analysis:** `prepareConfigOperation` in +[input.go](../../../integrations/ckconfig/input.go) handles command-specific flag +rules, scope/capability checks, path parsing, and both ordinary and two-sided +input preparation. The command builder also mixes several operation-specific +flag groups into its declarations. + +**Recommendation:** isolate operation-specific option checks, shared scope and +capability selection, and comparison input preparation with small private +functions. Keep an explicit orchestration function showing the actual order; +do not replace its operation branches with a rule registry. Extract flag groups +only where that makes their purpose clearer. + +Preserve bare explain's help path, aggregate capability checking before input +construction, independent left/right comparison selections, and completion of +input checks before shared state creation and acquisition. This makes it easier +to change one command without reasoning through every other command's submode. + +### F19 — Keep input-ordering machinery together + +**Analysis:** `prepareInputWithOccurrences` in [binding.go](../../../binding.go) +combines value conversion, error attribution, occurrence-position assignment, +required checks, operand allocation, and assembly of later input setters. +Captured binding replay relies on the same occurrence identities. + +**Recommendation:** start with small extractions for conversion-error +attribution and operand preparation. Keep flag preparation, occurrence identity, +and order reconstruction together as one coherent block; that block may remain +in the orchestration function if moving it requires excessive plumbing. + +For example, a conversion error should still identify the spelling the operator +actually used, and repeated/interleaved inputs should still apply in their +selected order. Preserve supplied-state distinctions, original error identity, +and conversion before application input factories run. Retain the existing +dense reconstruction and captured-replay merge algorithms. This is the most +conservative extraction recommendation of the four; introducing new state +containers or a replay framework would defeat its purpose. + +### F20 — Share detail-rendering error bookkeeping + +**Analysis:** `renderTerminalLocked` and `submitMessageLocked` in +[reporter.go](../../../reporter.go) both invoke detail callbacks through managed +writers, distinguish rendering failures from destination write failures, and +retain the first error of each kind. Their headings and visibility rules differ. + +**Recommendation:** use one private detail-rendering helper under the existing +reporting lock, returning rendering and writing errors separately. Callers keep +headings, visibility/discard selection, destination delivery observations, and +terminal timing. Preserve callback order, hidden-detail execution, sticky writer +errors, and callback non-reentrancy; add no locks or interchangeable renderers. + +This is the clearest duplication removal of the four. Keep it separately +reviewable from F03's deferred-acceptance fix and F07's writer-reference release; +it does not itself repair either defect. + +**Recommendation on sequencing:** correctness fixes remain first. Among these +maintenance changes, favor F20, then F18 and F17, with F19 kept small. Evaluate +each resulting diff by whether responsibilities are easier to follow and +existing behavioral coverage still protects the selected contracts. Tests should +not freeze new helper boundaries or incidental private call order. + +**Decision:** all four recommendations pending agreement; no refactoring has +been implemented.