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

Record diagnostic adapter decision and flag consumption analysis

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 14:45:44 +00:00
parent 2a93b45419
commit 9e0f2d28cd
2 changed files with 59 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
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, and F13–F15 remain selected. In
Existing catalog decisions for F03, F10, F11, F13–F15, 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.
@@ -17,8 +17,8 @@ Straightforward correctness repairs need not wait for this discussion sequence.
| Order | Findings | Question | Discussion status |
| --- | --- | --- | --- |
| 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? | Adapters compared; recommendation pending agreement |
| 3 | F16 | Which flag-consumption facts can parsing and completion usefully share? | Boundary analysis 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 |
| 5 | F17–F20 | Which private extractions materially simplify the existing code? | Individual extraction review pending |
@@ -135,7 +135,10 @@ core. The public function serves CLI presentation, within the integration's
ownership boundary. Compatibility and migration are not obstacles; clarity and
maintenance cost are the decision criteria.
**Decision:** recommendation and illustrative API pending agreement.
**Decision:** shared public ckconfig adaptation helper accepted and recorded in
the catalog, using the input/output shape above. Both integrations will use it;
the smaller scheduling switches remain with their callers. The function name
above is illustrative; implementation remains pending.
## F16 — Shared flag consumption
@@ -147,12 +150,43 @@ completion retain their different handling of incomplete input?
**Options to examine:** a small neutral consumption primitive or deliberate
retention of duplication where a shared helper needs extensive caller modes.
**Preliminary recommendation:** share mechanics only; keep normalization,
failure provenance, and partial-word completion in their current owners. Repair
F06's completion fixture before validating this refactor. Review a concrete
boundary before selecting an abstraction.
**Analysis:** execution's `interpretFlagTokens` in
[internal/cobra/flags.go](../../../internal/cobra/flags.go) and completion's
`walkCompletionFlags` and `completionOptionTarget` in
[completion_flags.go](../../../completion_flags.go) repeat the decisions about
short-flag clusters, attached values, boolean assignments, and whether a flag
consumes the next argument. They already share classification and lookup through
[commandmeta's flag helpers](../../../internal/commandmeta/flags.go).
**Decision:** pending boundary analysis and agreement.
Both paths need to recognize that `--profile=team` has an attached value and
`--profile team` takes the following argument. Their responses to unfinished
input differ: executing a bare `--profile` requires a missing-value error, while
completion after `--profile ` should offer values. Likewise, an unfinished
`--pro` can be useful for suggesting flag names without being a valid execution
argument. A single policy-heavy parser would obscure that difference.
**Recommendation:** extend the existing neutral internal helpers with a small
consumption operation. Given flag metadata and the current spelling/position,
it should expose facts such as the identified flag, any attached value, whether
the next argument is required, and where to continue within a short cluster.
Distinguish an explicitly empty attached value from an absent value. The exact
private signature is an implementation choice, not a new public contract.
Execution retains alias normalization, entered-spelling and occurrence tracking,
backend error handling, and typed conversion. Completion retains unfinished-word
handling, suggestion filtering, and insertion text. Existing token classification
continues to identify `--`; callers retain their appropriate end-of-options
handling. Supply each caller's existing lookup rather than extending completion
to new alias-discovery behavior. Do not add execution/completion mode flags,
callback registries, another public parser, or a replacement for Cobra/pflag.
Repair F06's fixture before validating the change. Use focused behavioral
coverage for shared grammar and the deliberately different missing/partial-value
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.
## F14–F15 — Joint source-prefix design