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

Record flag alias scope and target availability decisions

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-19 01:21:33 +00:00
parent f526198059
commit 573a22a38e
1 changed files with 30 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/roadmap/aliases.md
View File

@@ -272,9 +272,28 @@ declaring a command alias, using the shared registration conventions above.
Support application-wide mappings and mappings scoped to a canonical command. Support application-wide mappings and mappings scoped to a canonical command.
The selected canonical command determines the applicable flag aliases, so a The selected canonical command determines the applicable flag aliases, so a
command-scoped mapping works through every command alias that reaches that command-scoped mapping works through every command alias that reaches that
target. An application-wide help alias provides the same convenience throughout target. A command-scoped mapping takes precedence over an application-wide
the application. Scope precedence and handling of targets unavailable on some mapping for the same alias spelling. Reject different-target mappings within
commands remain open. the same scope; identical duplicates are harmless. Registration order does not
choose a winner, and neither scope may overload an applicable canonical flag.
An application-wide mapping is available wherever its target flag exists and
contributes nothing elsewhere. For example, `--colour → --color` need not require
every command to define `--color`. On a command without that target, `--colour`
receives the ordinary unknown-flag error. Reusable application-wide declarations
are valid even when no currently installed command has their target flag.
A command-scoped mapping requires its named canonical command and target flag
to exist in the complete candidate installation batch. An unavailable explicit
destination is invalid configuration.
Application-wide mappings also apply to built-in flags at the application root
and on groups. In particular, `--hlep → --help` works wherever canonical
`--help` works, including help for alias-only prefixes.
Later registration repeats validation against the candidate registry. Newly
installed commands gain applicable application-wide aliases automatically;
canonical spelling collisions reject the batch under the collision rules below.
### Token interpretation ### Token interpretation
@@ -297,7 +316,7 @@ arity, boolean syntax, or option termination.
Match the complete flag name. Length precedence does not apply: `--out` and Match the complete flag name. Length precedence does not apply: `--out` and
`--output` are different names, and only `--out` participates in alias lookup in `--output` are different names, and only `--out` participates in alias lookup in
`--out=value`. Scope precedence remains a separate decision. Resolution must `--out=value`. Use the scope precedence selected above. Resolution must
be deterministic and must not depend on registration order. be deterministic and must not depend on registration order.
### Canonical flag collisions ### Canonical flag collisions
@@ -326,8 +345,8 @@ spelling accumulate in order. Alias resolution adds no second conversion or
input-preparation lifecycle. input-preparation lifecycle.
Flag aliases do not change canonical flag ownership or add new provider Flag aliases do not change canonical flag ownership or add new provider
capabilities. Short-flag support, chains, alias-to-alias scope conflicts, capabilities. Short-flag support, chains and their validation, and help
target validation, and help presentation remain open below. presentation remain open below.
## Work needed from the baseline ## Work needed from the baseline
@@ -378,10 +397,8 @@ canonical invocation paths?
### OD-6: Flag alias scope and composition ### OD-6: Flag alias scope and composition
How do application-wide and command-scoped mappings interact when both apply? Scope precedence, target availability, and application to built-in help are
How is an application-wide mapping treated on commands lacking its target flag? selected above. Which short-flag forms are supported? Are flag-alias chains
How are aliases applied to built-in help on groups and at the application root? supported, and how do scope precedence and target availability apply through
Which short-flag forms are supported? Are flag-alias chains supported, and how a chain? How are cycles validated at installation and later registration?
are alias-to-alias conflicts, cycles, and missing targets validated at installation How are flag aliases exposed in help and diagnostic spelling?
and later registration? How are flag aliases exposed in help and diagnostic
spelling?