base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 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

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

@@ -169,13 +169,19 @@ spelling, while installation enforces additional name grammar and reserved
spellings. Consumers must discover those constraints through errors or private spellings. Consumers must discover those constraints through errors or private
implementation. implementation.
Document the implemented rules once with `FlagMeta` and link related public **Decision:** retain and document the existing declaration rules. Long names use
helpers. Preserve accepted Unicode lowercase letters and digits; changing Unicode lowercase letters and digits separated by single hyphens; numeric names
validation would require a separate decision. and names beginning with digits remain allowed. Keep core-owned reserved names
and the optional one-byte short-spelling rules, excluding `-` and reserved `h`.
Do not add ASCII-only or leading-letter restrictions, or automatic rewriting of
invalid names. These rules concern flag names, not supplied values.
Document the rules once with `FlagMeta` and link related public helpers. This
remediation changes documentation, not runtime validation.
The [F10 analysis](remediation-analysis.md#f10--flag-declaration-naming) reviews The [F10 analysis](remediation-analysis.md#f10--flag-declaration-naming) reviews
the naming convention's basis and recommends retaining the existing rules; the naming convention's basis and records the accepted direction. Implementation
agreement on that precise contract is pending. of the documentation correction remains pending.
**Original:** [13-documentation D2](13-documentation.md#d2--p3-public-flag-metadata-omits-enforced-declaration-constraints). **Original:** [13-documentation D2](13-documentation.md#d2--p3-public-flag-metadata-omits-enforced-declaration-constraints).

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 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, 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 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.
@@ -16,8 +16,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? | Evidence reviewed; recommendation pending agreement | | 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? | Concrete API analysis 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 | | 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 | | 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 |
@@ -80,11 +80,13 @@ invalid names or accept alternate spellings through normalization.
Document the exact declaration contract once in `FlagMeta` GoDoc and link related Document the exact declaration contract once in `FlagMeta` GoDoc and link related
helpers, including `RenameFlag` and flag-alias declarations, as applicable. Keep helpers, including `RenameFlag` and flag-alias declarations, as applicable. Keep
operator syntax in the CLI reference. This is a documentation remediation if operator syntax in the CLI reference. This is a documentation remediation;
selected; it does not require a new ADR, parser, or validation framework. it does not require a new ADR, parser, or validation framework.
**Decision:** pending agreement. The recommendation does not authorize a change **Decision:** option 1 accepted and recorded in the catalog. Retain the current
to validation behavior. 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 ## 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 diagnostics and an explanation, or retaining private implementations if the
shared API adds more complexity than it removes. shared API adds more complexity than it removes.
**Preliminary recommendation:** compare a concrete signature against both **Analysis:** ckconfig's private `configKitDiagnosticsWithHeading` already
callers, including heading/side labels, evidence snapshots, and error identity. accepts a heading, native sources, and native diagnostic records, and returns
Keep operation-specific explanations and scheduling with their existing owners. core diagnostics and an explanation. ckprompt duplicates the evidence snapshot,
The smaller scheduling switches do not independently justify another public severity partition, source legend, and delegation to `configkit.WriteDiagnostics`.
helper. Compatibility and migration are not obstacles; clarity and maintenance Its scope and comparison-side labels can be supplied as the heading; they do not
cost are the decision criteria. 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 ## F16 — Shared flag consumption