From 93ee3287791ab8893f3811ebde7f5ad5d8c8f42c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 19 Oct 2026 14:06:10 +0000 Subject: [PATCH] Clarify alias routing interactions and implementation checks --- docs/roadmap/aliases.md | 82 +++++++++++++++++++++++++++++++++-------- 1 file changed, 66 insertions(+), 16 deletions(-) diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md index d0a1fff..7b89420 100644 --- a/docs/roadmap/aliases.md +++ b/docs/roadmap/aliases.md @@ -17,10 +17,10 @@ commands: ```text CLI argument tokens → command-path alias resolution - → canonical command selection - → applicable flag-alias resolution using canonical flag metadata - → canonical parsing - → ordinary invocation lifecycle + → canonical command or discovery-help context selection + → applicable flag-alias resolution using that context's flag metadata + → input parsing + → ordinary invocation lifecycle or discovery help ``` Alias declarations do not install new handlers or modify the canonical command @@ -111,7 +111,7 @@ app, err := commandkit.New( ckprompt.Command(suite), commandkit.Alias("list collections", "promptkit list collections"), commandkit.FlagAlias("--hlep", "--help"), - commandkit.FlagAliasFor("promptkit show prompt", "--ver", "--version"), + commandkit.FlagAliasFor("promptkit show prompt", "--fmt", "--format"), ) ``` @@ -227,6 +227,14 @@ composition so these configuration errors are caught before invocation. An arbitrary runtime hop limit is not a substitute for installation validation and must not reject an otherwise valid long chain. +A dependency-graph cycle or repeated use of a declaration does not by itself +establish nontermination. With canonical group `group`, the mappings `a → group` +and `group again → a` allow `a again again` to terminate: each round consumes +an `again` token. Validate actual prefix-resolution behavior, including +terminating repetitions, suffix-dependent cycles, and growing expansions. +Establish focused evidence for this validation before building the rest of +routing around the algorithm. + ### Installation and collisions Use the shared declaration and installation conventions above for aliases, @@ -238,6 +246,11 @@ targets, collisions, and cycles produce installation errors with useful path context. Failed installation preserves the existing application registry and alias mappings under the existing batch-atomicity model. +A declared target must resolve entirely to a canonical command or group, +without leftover operand tokens. For example, reject +`Alias("fast", "run production")` when canonical `run` takes `production` as +an operand. Command aliases do not inject fixed operands. + An alias cannot conflict with or overload a canonical command path. Reject such a declaration during installation as invalid application configuration. Apply the same protection when later registration adds a canonical command conflicting @@ -268,6 +281,13 @@ consumption of canonical operands. Sharing a runnable ancestor alone does not establish a conflict: check whether the proposed route intercepts that ancestor's operands or an existing canonical child route. +Explicit longer aliases beneath an alternate spelling still use longest-match +precedence. With canonical `run TARGET`, `r → run`, and `r full → inspect`, +`r full` invokes canonical `inspect`; canonical `run full` retains its operand +meaning. If only `r → run` exists, `r full` reaches `run` with operand `full`, +which is not searched for aliases after the route resolves. Canonical operand +protection does not reserve the operand space of every alternate spelling. + Check these conflicts against the complete candidate registry when adding either aliases or canonical commands, including later registration. Report the conflicting paths and preserve batch atomicity. Apply the chain and group @@ -324,6 +344,11 @@ and `list --help` display the available routes. This help view is derived from alias declarations and creates no canonical group or namespace ownership. Bare `list` reports an incomplete command and points to that help. +Routing can select this discovery-help context without selecting a canonical +command. It uses core's help metadata and applicable application-wide flag +aliases, so `list --hlep` can request the same help. It neither inherits flags +from descendant commands nor creates a canonical command node. + Usage errors use the entered path and identify the canonical target when one has been resolved, while preserving the canonical command's diagnostic content: @@ -342,6 +367,8 @@ without assigning a canonical identity. 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, using the shared registration conventions above. +Validate each source and target as an individual flag spelling; declarations +do not accept clusters, attached values, or other argument expressions. Support application-wide mappings and mappings scoped to a canonical command. The selected canonical command determines the applicable flag aliases, so a @@ -371,9 +398,10 @@ canonical spelling collisions reject the batch under the collision rules below. ### 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. +Resolve command aliases and select the canonical command or discovery-help +context before applying its flag aliases. Use that context's flag metadata to +distinguish flag names from values. Preserve the existing grammar, including +flags interspersed with operands. | Input | Effect | | --- | --- | @@ -423,10 +451,19 @@ capabilities. ### Chains and short spellings -Support flag-alias chains, such as `--colour → --hue → --color`. At each step, -use the selected command's effective mappings, with command-scoped mappings -taking precedence over application-wide mappings. Resolve to the final -canonical flag and use its binding. +Support flag-alias chains, such as `--colour → --hue → --color`. When resolving +a target, an existing canonical flag spelling terminates the chain. Otherwise, +look up the next alias using the selected context's effective mappings, with +command-scoped mappings taking precedence over application-wide mappings. +Resolve to the final canonical flag and use its binding. Validate applicable +alias-source collisions separately; a canonical endpoint does not excuse a +conflicting source declaration. + +For example, given canonical `--color` and global mappings +`--color → --missing` and `--colour → --color`, the first mapping contributes +nothing while `--missing` is unavailable. The second still reaches canonical +`--color`. If later registration makes `--missing` available in that context, +the first mapping becomes a canonical spelling collision and the batch fails. Apply target-availability rules to the final destination. An application-wide chain contributes nothing where its final canonical flag is unavailable. A @@ -497,16 +534,22 @@ canonical binding. 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. Implement the selected declaration types and shared path primitives. Extend +3. Establish termination-validation behavior with focused evidence for valid + repetitions, suffix-dependent cycles, and growing prefix expansions before + building the rest of routing around the algorithm. +4. Implement the selected declaration types and shared path primitives. Define + and verify installation handling for nil declarations and zero `RoutingRule` + values alongside the existing invalid-zero and explicit-absence command + contracts. Validate flag declarations as individual spellings. 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 command and flag alias resolution with canonical routing, help, and +5. 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. Apply the selected short-option grammar and correct explicit empty values for canonical short spellings and aliases together. -5. Add focused behavioral evidence for both example mappings, group aliases, +6. Add focused behavioral evidence for both example mappings, group aliases, longest matches, chains, group composition, cycles and nonterminating prefix expansion, collisions, missing targets, same-batch resolution, later registration, argument preservation, help without @@ -515,9 +558,16 @@ canonical binding. mixed canonical/alias repetitions, flag chains and scope overrides, short aliases, mixed clusters, attached values, explicit empty-value correction, flag help and diagnostics, and unchanged typed binding semantics. -6. Add maintained consumer examples and update GoDoc, the CLI reference, consumer + Include discovery-help contexts without canonical commands, longer aliases + beneath operand-taking command shortcuts, rejection of operand-bearing + targets, and canonical flag endpoints alongside inactive global mappings. +7. 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). +8. Document migration from `...Command` to `...Declaration`, including slice + conversion, and the explicit empty-value correction. Include the compatibility + impact and required consumer action in release notes under the + [release policy](../policy/release.md#versioning-and-compatibility). Completion means consumers can declare alternate command paths and flag spellings with minimal wiring and invoke canonical behavior and help through