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

Record flag naming decision and diagnostic adapter analysis

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

58
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, F11, and F13–F15 remain selected. In
Existing catalog decisions for F03, F10, F11, and F13–F15 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.
@@ -16,8 +16,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? | Evidence reviewed; recommendation pending agreement |
| 2 | F21 | What narrow diagnostic adaptation API would simplify both integrations? | Concrete API analysis 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 |
| 3 | F16 | Which flag-consumption facts can parsing and completion usefully share? | Boundary analysis pending |
| 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 |
@@ -80,11 +80,13 @@ invalid names or accept alternate spellings through normalization.
Document the exact declaration contract once in `FlagMeta` GoDoc and link related
helpers, including `RenameFlag` and flag-alias declarations, as applicable. Keep
operator syntax in the CLI reference. This is a documentation remediation if
selected; it does not require a new ADR, parser, or validation framework.
operator syntax in the CLI reference. This is a documentation remediation;
it does not require a new ADR, parser, or validation framework.
**Decision:** pending agreement. The recommendation does not authorize a change
to validation behavior.
**Decision:** option 1 accepted and recorded in the catalog. Retain the current
long-name grammar, Unicode lowercase and digit support, reservations, and
short-spelling rules. No runtime validation change or name normalization is
selected. F10 remains open until its public documentation is corrected.
## F21 — Shared ConfigKit diagnostic adaptation
@@ -98,14 +100,42 @@ links both adapters and the original analysis.
diagnostics and an explanation, or retaining private implementations if the
shared API adds more complexity than it removes.
**Preliminary recommendation:** compare a concrete signature against both
callers, including heading/side labels, evidence snapshots, and error identity.
Keep operation-specific explanations and scheduling with their existing owners.
The smaller scheduling switches do not independently justify another public
helper. Compatibility and migration are not obstacles; clarity and maintenance
cost are the decision criteria.
**Analysis:** ckconfig's private `configKitDiagnosticsWithHeading` already
accepts a heading, native sources, and native diagnostic records, and returns
core diagnostics and an explanation. ckprompt duplicates the evidence snapshot,
severity partition, source legend, and delegation to `configkit.WriteDiagnostics`.
Its scope and comparison-side labels can be supplied as the heading; they do not
require another shared options type. See
[ckconfig's adapter](../../../integrations/ckconfig/configkit_adapter.go) and
[ckprompt's adapter](../../../integrations/ckprompt/adapters.go).
**Decision:** helper signature and scope pending analysis and agreement.
**Recommendation:** expose the existing adaptation responsibility through one
narrow ckconfig function and have both integrations use it. An illustrative
signature, not an implemented API, is:
```go
func AdaptDiagnostics(
heading string,
sources []configkit.SourceInfo,
records []configkit.Diagnostic,
) ([]commandkit.Diagnostic, commandkit.Explanation)
```
Retain the existing evidence snapshot and severity treatment, ordering within
each group, source labels, and native record formatting. Return evidence ready
for CLI reporting; do not print immediately, select an invocation outcome, or
load or validate configuration. Callers supply headings and operation-specific
explanations and retain their error causes. Reporter remains responsible for
visibility and delivery.
Keep scheduling with the callers. The smaller scheduling switches do not
independently justify another public helper. ckprompt already depends on
ckconfig; this introduces no new module dependency or ConfigKit dependency in
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.
## F16 — Shared flag consumption