From 9e0f2d28cdd4ad3961a461aece5249918120cb33 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 7 Nov 2026 14:45:44 +0000 Subject: [PATCH] Record diagnostic adapter decision and flag consumption analysis --- docs/roadmap/audit/catalog.md | 26 ++++++----- docs/roadmap/audit/remediation-analysis.md | 52 ++++++++++++++++++---- 2 files changed, 59 insertions(+), 19 deletions(-) diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index 1ca5075..51ed78a 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -338,17 +338,23 @@ ckconfig and ckprompt independently snapshot ConfigKit diagnostic evidence, partition severities, construct detail callbacks, label sources, and delegate native text formatting. Related Reporter scheduling switches are duplicated too. -Consider a narrow public ckconfig adaptation helper returning existing core -diagnostic/explanation values. Any exported helper needs an API decision; -preserve snapshot ownership, ordering, error identity, and diagnostic timing -rather than introducing a universal framework. +**Decision:** expose one narrow public ckconfig diagnostic adaptation helper +and use it in both integrations. Reuse the existing private helper's shape: +accept a caller-supplied heading, native sources, and native diagnostic records; +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. -Compatibility and consumer migration are therefore not constraints on this -remediation. The remaining design question is whether a concrete, narrow CLI -adaptation API simplifies both integrations enough to justify maintaining it. -The helper's signature and scope remain to be selected; this clarification does -not itself approve a new public API or a separate reporting-scheduler helper. +Callers retain operation-specific context, outcomes, error causes, and message +scheduling. Core retains visibility and delivery. Leave the smaller scheduling +switches with their callers; no additional public scheduling API or general +diagnostics framework is selected. ckprompt already depends on ckconfig, so no +new module dependency is needed. + +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). Also discussed in the [responsibility assessment](A1-responsibility.md#machinery-worth-retaining-under-the-selected-contracts). diff --git a/docs/roadmap/audit/remediation-analysis.md b/docs/roadmap/audit/remediation-analysis.md index ee06d4c..6d5bcc3 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, 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