From 1f3d1594c965ed6cb32f9af5de1d663c71c9741e Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 18 Oct 2026 16:09:15 +0000 Subject: [PATCH] Add flag alias direction to alias roadmap --- docs/roadmap/aliases.md | 112 ++++++++++++++++++++++++++++++---------- 1 file changed, 86 insertions(+), 26 deletions(-) diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md index 5136d34..30272b5 100644 --- a/docs/roadmap/aliases.md +++ b/docs/roadmap/aliases.md @@ -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?