diff --git a/binding.go b/binding.go index 8dccc7c..af0829e 100644 --- a/binding.go +++ b/binding.go @@ -64,6 +64,7 @@ func OccurrenceFlag[I, V any](meta FlagMeta, parse func(string) (V, error), set // RenameFlag returns an independent binding with a new long name and no short // spelling. Parsing, defaults, completion, requiredness, and setters are retained. +// The name follows the declaration rules in [FlagMeta]. func RenameFlag[I any](flag Flag[I], name string) Flag[I] { binding := flag.binding binding.meta.Name = name diff --git a/command.go b/command.go index 14187df..cf39ff6 100644 --- a/command.go +++ b/command.go @@ -90,10 +90,14 @@ type Supplied[T any] struct { // FlagMeta describes a command flag. Required applies when execution prepares // the selected command; help reports the metadata without requiring the value. +// Invalid declarations are reported when installed. type FlagMeta struct { - // Name is the flag name without leading dashes. + // Name is a nonempty long name without leading dashes. It consists of + // Unicode lowercase letters or digits in segments separated by single + // hyphens; digit-leading and numeric-only names are valid. The names help, + // quiet, verbose, debug, progress and format are reserved. Name string - // Short is an optional one-byte spelling. + // Short is an optional one-byte spelling other than '-' or the reserved 'h'. Short string // Usage briefly describes the flag. Usage string @@ -352,6 +356,7 @@ func Alias(path, target string) RoutingRule { // wherever its canonical target flag is available and contributes nothing on // commands without that flag. Identical mappings are accepted; different // targets for the same source spelling in this scope are installation errors. +// Long and short spelling forms follow the grammar described by [FlagMeta]. func FlagAlias(spelling, target string) RoutingRule { record := &routingRuleRecord{ kind: globalFlagAliasRule, @@ -368,6 +373,7 @@ func FlagAlias(spelling, target string) RoutingRule { // available in the complete installation. Scoped mappings take precedence over // application-wide mappings with the same source spelling. Identical mappings // are accepted; competing targets in the same scope are installation errors. +// Long and short spelling forms follow the grammar described by [FlagMeta]. func FlagAliasFor(commandPath, spelling, target string) RoutingRule { record := &routingRuleRecord{ kind: scopedFlagAliasRule, diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index 04fbf99..5ccb909 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -1,6 +1,6 @@ # Consolidated audit catalog -Status: **16 distinct open findings: 16 P3**, consolidated from 30 +Status: **15 distinct open findings: 15 P3**, consolidated from 30 numbered entries in seven audit documents. Reviewed audit state: `db732e3a1de55c844f77870e1c6db683c2685d5d`. @@ -207,6 +207,10 @@ unused explanation-writer requirement in F11. ## F10 — P3: Public flag metadata omits enforced naming and reserved-spelling rules +**Complete.** FlagMeta documents the existing declaration rules and related +rename and alias GoDoc refers to them. The prose was checked against the +installation validator; no runtime rule changed. + `FlagMeta` describes names without leading dashes and an optional short spelling, while installation enforces additional name grammar and reserved spellings. Consumers must discover those constraints through errors or private @@ -223,8 +227,7 @@ 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 naming convention's basis and records the accepted direction. Implementation -of the documentation correction remains pending. +the naming convention's basis and records the accepted direction. **Original:** [13-documentation D2](13-documentation.md#d2--p3-public-flag-metadata-omits-enforced-declaration-constraints). diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 361b9aa..9bc6466 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # Audit remediation implementation plan -Status: in progress; Stages 1–9 complete. +Status: in progress; Stages 1–10 complete. Baseline: `d492c7747175c01a53261206c2b4356e53453621`. Before this sprint, intervening changes recorded decisions and retired the completed older @@ -357,6 +357,11 @@ F09, and acquisition-only provider wiring with preserved rendering for F11. ## Stage 10 — Document the selected flag declaration contract +**Complete.** FlagMeta describes the existing Unicode long-name grammar, +reserved names and short spellings; rename and alias guidance links to it. +Reviewed against `validateBindings`, `validFlagName`, and the accepted catalog +decision. No runtime validation was changed. + Findings: F10. Source: `command.go` FlagMeta and related rename/alias GoDoc. 1. Define long names once with FlagMeta: nonempty Unicode lowercase-letter or