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

26
docs/roadmap/audit/catalog.md
View File

@@ -338,17 +338,23 @@ ckconfig and ckprompt independently snapshot ConfigKit diagnostic evidence,
partition severities, construct detail callbacks, label sources, and delegate partition severities, construct detail callbacks, label sources, and delegate
native text formatting. Related Reporter scheduling switches are duplicated too. native text formatting. Related Reporter scheduling switches are duplicated too.
Consider a narrow public ckconfig adaptation helper returning existing core **Decision:** expose one narrow public ckconfig diagnostic adaptation helper
diagnostic/explanation values. Any exported helper needs an API decision; and use it in both integrations. Reuse the existing private helper's shape:
preserve snapshot ownership, ordering, error identity, and diagnostic timing accept a caller-supplied heading, native sources, and native diagnostic records;
rather than introducing a universal framework. return existing core diagnostics and an explanation ready for CLI reporting.
Preserve evidence snapshots, severity treatment, ordering within each group,
source labels, and delegation to ConfigKit's native formatter.
**Decision context:** CommandKit is still pre-release with no consumers. Callers retain operation-specific context, outcomes, error causes, and message
Compatibility and consumer migration are therefore not constraints on this scheduling. Core retains visibility and delivery. Leave the smaller scheduling
remediation. The remaining design question is whether a concrete, narrow CLI switches with their callers; no additional public scheduling API or general
adaptation API simplifies both integrations enough to justify maintaining it. diagnostics framework is selected. ckprompt already depends on ckconfig, so no
The helper's signature and scope remain to be selected; this clarification does new module dependency is needed.
not itself approve a new public API or a separate reporting-scheduler helper.
CommandKit is pre-release with no consumers; compatibility and migration are
not constraints. The [F21 analysis](remediation-analysis.md#f21--shared-configkit-diagnostic-adaptation)
records the accepted scope and illustrative signature. Implementation remains
pending.
**Original:** [03-complexity M5](03-complexity.md#m5--p3-configuration-diagnostic-adaptation-is-maintained-in-both-integrations). **Original:** [03-complexity M5](03-complexity.md#m5--p3-configuration-diagnostic-adaptation-is-maintained-in-both-integrations).
Also discussed in the [responsibility assessment](A1-responsibility.md#machinery-worth-retaining-under-the-selected-contracts). Also discussed in the [responsibility assessment](A1-responsibility.md#machinery-worth-retaining-under-the-selected-contracts).

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 accepted conclusions in the catalog and mark the corresponding discussion here
decided; a decision does not close a finding before implementation. 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 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; F15 are to be designed together. CommandKit is pre-release with no consumers;
consumer compatibility and migration are not constraints on these choices. 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 | | 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 | | 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 | | 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? | Boundary analysis 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 | | 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 | | 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 ownership boundary. Compatibility and migration are not obstacles; clarity and
maintenance cost are the decision criteria. 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 ## 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 **Options to examine:** a small neutral consumption primitive or deliberate
retention of duplication where a shared helper needs extensive caller modes. retention of duplication where a shared helper needs extensive caller modes.
**Preliminary recommendation:** share mechanics only; keep normalization, **Analysis:** execution's `interpretFlagTokens` in
failure provenance, and partial-word completion in their current owners. Repair [internal/cobra/flags.go](../../../internal/cobra/flags.go) and completion's
F06's completion fixture before validating this refactor. Review a concrete `walkCompletionFlags` and `completionOptionTarget` in
boundary before selecting an abstraction. [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 ## F14–F15 — Joint source-prefix design