Add flag alias direction to alias roadmap
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# Application-owned aliases
|
||||
|
||||
Status: command-alias direction accepted; implementation has not started.
|
||||
Public API and remaining routing details are open. Flag aliasing is under
|
||||
discussion. This roadmap records the target and work needed before implementation.
|
||||
Status: command- and flag-alias directions accepted; implementation has not
|
||||
started. Public API and remaining routing details are open. This roadmap records
|
||||
the target and work needed before implementation.
|
||||
|
||||
## Purpose and ownership
|
||||
|
||||
Make alternate command spellings and shorter paths simple for consuming
|
||||
Make alternate command paths and flag spellings simple for consuming
|
||||
applications to declare. CommandKit core owns alias registration, resolution,
|
||||
and integration with routing and help. Applications choose their aliases.
|
||||
Integrated libraries continue to own their canonical command behavior.
|
||||
@@ -17,7 +17,9 @@ commands:
|
||||
```text
|
||||
CLI argument tokens
|
||||
→ command-path alias resolution
|
||||
→ canonical command routing and parsing
|
||||
→ canonical command selection
|
||||
→ applicable flag-alias resolution using canonical flag metadata
|
||||
→ canonical parsing
|
||||
→ ordinary invocation lifecycle
|
||||
```
|
||||
|
||||
@@ -28,6 +30,10 @@ placement rules in [ADR 0011](../adr/0011-captured-declarations-and-installation
|
||||
and the [architecture policy](../policy/architecture.md) continue to govern
|
||||
canonical command installation.
|
||||
|
||||
Flag aliases likewise leave canonical flag definitions and typed bindings
|
||||
unchanged. This is one conceptual routing layer; its internal implementation
|
||||
cooperates with the existing parser to preserve token interpretation.
|
||||
|
||||
## Current baseline
|
||||
|
||||
Core captures reusable `Command` declarations and installs them through `New`
|
||||
@@ -115,45 +121,97 @@ Alias help describes the canonical target's inputs using the alias invocation
|
||||
path and identifies the canonical command. Root help presents aliases separately
|
||||
from canonical commands. Group help and discovery details remain to be specified.
|
||||
|
||||
## Selected flag-alias behavior
|
||||
|
||||
### Spellings and scopes
|
||||
|
||||
Applications can declare alternate spellings for canonical flags, including
|
||||
`--hlep` mapping to `--help`. Declaring a flag alias should be as simple as
|
||||
declaring a command alias; the exact Go API remains open.
|
||||
|
||||
Support application-wide mappings and mappings scoped to a canonical command.
|
||||
The selected canonical command determines the applicable flag aliases, so a
|
||||
command-scoped mapping works through every command alias that reaches that
|
||||
target. An application-wide help alias provides the same convenience throughout
|
||||
the application. Scope precedence and handling of targets unavailable on some
|
||||
commands remain open.
|
||||
|
||||
### Token interpretation
|
||||
|
||||
Resolve command aliases and identify the canonical command before applying its
|
||||
flag aliases. Use canonical flag metadata to distinguish flag names from values.
|
||||
Preserve the existing grammar, including flags interspersed with operands.
|
||||
|
||||
| Input | Effect |
|
||||
| --- | --- |
|
||||
| `list collections --hlep` | Resolve the command path and route `--hlep` to canonical help. |
|
||||
| `foo --colour=blue` | With `--colour` mapped to `--color`, preserve `blue` as the value. |
|
||||
| `foo --message=--hlep` | Preserve the value `--hlep`. |
|
||||
| `foo --message --hlep` | When `--message` consumes a value, preserve `--hlep` as that value. |
|
||||
| `foo -- --hlep` | Preserve the operand `--hlep` after the option terminator. |
|
||||
|
||||
Only tokens interpreted as flag names participate in flag aliasing. Preserve
|
||||
values, explicit empty strings, and operands. The routing layer cooperates with
|
||||
the existing parser rather than maintaining a separate interpretation of flag
|
||||
arity, boolean syntax, or option termination.
|
||||
|
||||
### Canonical binding behavior
|
||||
|
||||
An alias feeds the same typed binding as its canonical flag. The target retains
|
||||
its value conversion, defaults, required-value checks, presence tracking,
|
||||
repetition rules, and behavior. Mixed spellings retain invocation order:
|
||||
|
||||
```text
|
||||
foo --color red --colour blue
|
||||
```
|
||||
|
||||
With `--colour` mapped to singleton `--color`, the normal last-occurrence rule
|
||||
selects `blue`. Earlier invalid occurrences remain errors under the existing
|
||||
conversion contract. For a repeatable target, occurrences through either
|
||||
spelling accumulate in order. Alias resolution adds no second conversion or
|
||||
input-preparation lifecycle.
|
||||
|
||||
Flag aliases do not change canonical flag ownership or add new provider
|
||||
capabilities. Short-flag support, chains, collisions, installation validation,
|
||||
and help presentation remain open below.
|
||||
|
||||
## Work needed from the baseline
|
||||
|
||||
1. Settle the public alias API and the open routing details with consumer examples
|
||||
covering a command shortcut, a synonym inside an integration namespace, and
|
||||
a group shortcut.
|
||||
a group shortcut, an application-wide help flag alias, and a command-scoped
|
||||
flag alias reached through a command shortcut.
|
||||
2. Capture the durable separation between application alias routing and canonical
|
||||
namespace ownership in an ADR. Keep exact API, matching, and presentation
|
||||
command and flag ownership in an ADR. Keep exact API, matching, and presentation
|
||||
details in their appropriate contracts. No relaxation of canonical namespace
|
||||
ownership is selected.
|
||||
3. Extend installation to validate aliases and commands against the complete
|
||||
candidate batch, preserving retained errors and atomicity. Keep aliases
|
||||
independent of optional-library dependencies and backend-specific exports.
|
||||
4. Integrate alias resolution with canonical routing, help, and invocation
|
||||
identity. Reuse the existing parser and typed execution machinery.
|
||||
4. Integrate command and flag alias resolution with canonical routing, help, and
|
||||
invocation identity. Use canonical flag metadata and the existing parser to
|
||||
preserve values and operands, and reuse typed execution machinery.
|
||||
5. Add focused behavioral evidence for both example mappings, group aliases,
|
||||
longest matches, chains and cycles, collisions, missing targets, same-batch
|
||||
resolution, later registration, argument preservation, help without
|
||||
acquisition, and a single execution lifecycle.
|
||||
acquisition, and a single execution lifecycle. Cover application-wide and
|
||||
command-scoped flag mappings, attached and separate values, option termination,
|
||||
mixed canonical/alias repetitions, and unchanged typed binding semantics.
|
||||
6. Add maintained consumer examples and update GoDoc, the CLI reference, consumer
|
||||
guidance, and internal documentation when implementation lands. Validate the
|
||||
affected modules under the [developer guide](../development.md).
|
||||
|
||||
Completion means consumers can declare alternate paths with minimal wiring,
|
||||
receive installation-time feedback, and invoke canonical behavior and help
|
||||
through those paths while canonical namespace ownership stays intact.
|
||||
|
||||
## Flag aliasing under discussion
|
||||
|
||||
The same application routing concept may support alternate flag spellings,
|
||||
such as `--hlep` mapping to `--help`, while leaving canonical flags and bindings
|
||||
unchanged. The user-facing API should be comparably simple to command aliases.
|
||||
Scope, token handling, registration, and help behavior need further discussion;
|
||||
no specific flag-alias API or resolution policy is selected here.
|
||||
Completion means consumers can declare alternate command paths and flag
|
||||
spellings with minimal wiring and invoke canonical behavior and help through
|
||||
them while canonical ownership and binding semantics stay intact. Command alias
|
||||
installation provides the selected validation; flag alias installation follows
|
||||
the validation rules still to be settled.
|
||||
|
||||
## Open Decisions
|
||||
|
||||
### OD-1: Public declaration and registration API
|
||||
|
||||
What are the exact alias declaration, path representation, and installation
|
||||
What are the exact command- and flag-alias declaration, path representation, and installation
|
||||
signatures? How do alias declarations compose with groups, reusable declarations,
|
||||
and later `App.Register` calls? What are the duplicate-declaration semantics?
|
||||
|
||||
@@ -186,7 +244,9 @@ and diagnostic presentation?
|
||||
|
||||
### OD-6: Flag alias scope and composition
|
||||
|
||||
What is the flag-alias API and its installation scope? How does it compose with
|
||||
command aliases, canonical local flags, and built-in help? Which long and short
|
||||
flag forms are supported? How are values, `--`, chains, collisions, missing
|
||||
targets, help, and diagnostic spelling handled?
|
||||
How do application-wide and command-scoped mappings interact when both apply?
|
||||
How is an application-wide mapping treated on commands lacking its target flag?
|
||||
How are aliases applied to built-in help on groups and at the application root?
|
||||
Which short-flag forms are supported? Are flag-alias chains supported, and how
|
||||
are collisions, cycles, and missing targets validated at installation and later
|
||||
registration? How are flag aliases exposed in help and diagnostic spelling?
|
||||
|
||||
Reference in New Issue
Block a user