8.9 KiB
Audit remediation analysis
Status: discussion in progress; no implementation changes made.
This document owns analysis of unresolved remediation choices, in the discussion order below. The catalog owns the findings, accepted remediation 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 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. 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 |
| 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 |
F10 — Flag declaration naming
Question: should remediation document the existing naming rules, or change them first? This concerns names declared by applications, not the contents of operator-supplied flag values.
Evidence: catalog F10
and documentation audit D2.
FlagMeta, validateBindings, and validFlagName in
command.go establish the documentation gap and current
validation. Shared reporting spellings are defined in
commandmeta.
The historical accepted grammar ADR explicitly selected lowercase names with
hyphen-separated words. It is available at commit
82128463cd9649a426da7c5e3f3ce33bd37cdd9f, path
docs/adr/0006-command-grammar.md; the same commit's
docs/roadmap/initial.md carried that direction into implementation. This
supports the broad naming convention, but does not independently establish every
character-level detail of the current validator. Historical records provide
context; they do not replace the current canonical API documentation.
Current long names consist of nonempty groups of Unicode lowercase letters or digits separated by single hyphens. Names may start with digits or consist entirely of digits. Uppercase letters, underscores, dots, and leading, trailing, or repeated hyphens are rejected. Examples:
| Declaration name | Current result |
|---|---|
max-tokens, profile2, 2fa, 123, équipe |
Accepted, subject to ordinary collision checks |
maxTokens, max_tokens, max.tokens, max--tokens, -profile, profile- |
Rejected |
Core reserves help, quiet, verbose, debug, progress, and format for
its own flags. A short spelling is optional; when present it is one byte,
cannot be -, and cannot be the reserved help spelling h. The long-name
lowercase rule does not apply to short spellings. Declaration defects are
reported at installation, before command execution.
Options:
- Retain and document the current rules. This makes the shared convention explicit without introducing new validation or conversion machinery.
- Relax the stylistic restrictions, allowing application names such as
maxTokensormax_tokenswhile preserving core reservations and necessary parsing constraints. This gives applications more naming freedom but weakens the common vocabulary; its precise supported grammar would need selection. - Tighten the rules, for example to ASCII names beginning with a letter. This creates a narrower convention but removes currently accepted names without an identified operator benefit.
Recommendation: option 1. Retain lowercase, hyphen-separated long names, including current Unicode lowercase and digit support. Keep core reservations and the existing short-spelling rules. Recommend readable names without banning numeric names or adding an ASCII-only restriction. Do not automatically rewrite 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.
Decision: pending agreement. The recommendation does not authorize a change to validation behavior.
F21 — Shared ConfigKit diagnostic adaptation
Question: what concrete helper, if any, removes duplicated CLI adaptation without introducing a broader diagnostics framework?
Evidence: catalog F21 links both adapters and the original analysis.
Options to examine: a narrow public ckconfig helper returning existing core 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.
Decision: helper signature and scope pending analysis and agreement.
F16 — Shared flag consumption
Question: which consumption facts can be shared while execution and completion retain their different handling of incomplete input?
Evidence: catalog F16.
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.
Decision: pending boundary analysis and agreement.
F14–F15 — Joint source-prefix design
Question: how can discovery preparation and help lookup reuse one source structure without parallel indexes or changed routing semantics?
Evidence: catalog F14 and F15.
Options to examine: traversal and descendant lookup through the existing alias source structure, or one shared private index if the existing structure cannot serve both operations simply.
Preliminary recommendation: prefer reuse; preserve classification, authoritative resolution, deduplication, and ordering. Select the concrete traversal and ownership together. No performance test is required to justify remediation; correctness validation remains appropriate.
Decision: joint remediation selected in the catalog; concrete design pending.
F17–F20 — Proportionate private extractions
Question: which proposed extractions make responsibilities clearer without adding records, phases, or configurable mechanisms merely to shorten functions?
Evidence: catalog entries F17, F18, F19, and F20.
Options to examine: cohesive functions over existing private types, or retaining related code together where extraction only adds indirection.
Preliminary recommendation: review each extraction separately. F20 has a concrete shared rendering/error policy; keep its refactor distinct from F03's correctness repair. For F17–F19, make meaningful responsibilities and required ordering visible without treating incidental private sequences as contracts.
Decision: individual extraction choices pending review.