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

Record canonical collision and deterministic alias rules

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-18 21:12:53 +00:00
parent 1f3d1594c9
commit a4cf55f7a5
1 changed files with 53 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/roadmap/aliases.md
View File

@@ -69,8 +69,19 @@ Aliases can target individual commands or groups. A group alias preserves
remaining subcommand tokens. For example, `list collections` can reach remaining subcommand tokens. For example, `list collections` can reach
`promptkit list collections` through the `list` group alias. `promptkit list collections` through the `list` group alias.
Match complete argument tokens at the beginning of the command path. Resolve Match exact, complete argument tokens at the beginning of the command path;
overlapping alias paths using the longest match. Preserve trailing arguments, `list` does not match `listing`. Resolve overlapping alias paths using the
longest matching path, measured by the number of command-path tokens, not
character count. This rule applies at each command-alias lookup and is
independent of registration order. Sorting by descending token count and taking
the first matching prefix is one possible implementation; the algorithm remains
an implementation choice.
For example, with `list → promptkit list` and
`list collections → application collections`, the more specific mapping wins
for `list collections`, while `list prompts` uses the `list` mapping.
Preserve trailing arguments,
including flags, operands, explicit empty values, and `--`, for canonical including flags, operands, explicit empty values, and `--`, for canonical
parsing. Values and operands are not searched for alias text. parsing. Values and operands are not searched for alias text.
@@ -94,10 +105,15 @@ targets, collisions, and cycles produce installation errors with useful path
context. Failed installation preserves the existing application registry and context. Failed installation preserves the existing application registry and
alias mappings under the existing batch-atomicity model. alias mappings under the existing batch-atomicity model.
Reject aliases that shadow existing canonical command paths. Preserve that An alias cannot conflict with or overload a canonical command path. Reject such
protection when later registration adds commands. Detailed prefix interactions a declaration during installation as invalid application configuration. Apply
remain open below. Aliases do not create canonical parent groups, merge the same protection when later registration adds a canonical command conflicting
integration trees, or replace handlers. with an existing alias. Reject competing mappings from the same source path to
different targets; registration order must not select a winner. Whether identical
duplicate declarations are accepted remains open.
Detailed prefix interactions remain open below. Aliases do not create canonical
parent groups, merge integration trees, or replace handlers.
### Execution and help ### Execution and help
@@ -155,6 +171,20 @@ values, explicit empty strings, and operands. The routing layer cooperates with
the existing parser rather than maintaining a separate interpretation of flag the existing parser rather than maintaining a separate interpretation of flag
arity, boolean syntax, or option termination. arity, boolean syntax, or option termination.
Match the complete flag name. Length precedence does not apply: `--out` and
`--output` are different names, and only `--out` participates in alias lookup in
`--out=value`. Scope precedence remains a separate decision. Resolution must
be deterministic and must not depend on registration order.
### Canonical flag collisions
An alias cannot conflict with or overload an applicable canonical flag spelling.
Reject conflicts during installation as invalid application configuration.
Check a command-scoped alias against that command's canonical flags, and an
application-wide alias across the commands where it applies. Apply the same
checks when later registration adds canonical declarations. Failed batches
preserve existing commands and alias mappings.
### Canonical binding behavior ### Canonical binding behavior
An alias feeds the same typed binding as its canonical flag. The target retains An alias feeds the same typed binding as its canonical flag. The target retains
@@ -172,8 +202,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, collisions, installation validation, capabilities. Short-flag support, chains, alias-to-alias scope conflicts,
and help presentation remain open below. target validation, and help presentation remain open below.
## Work needed from the baseline ## Work needed from the baseline
@@ -203,24 +233,27 @@ and help presentation remain open below.
Completion means consumers can declare alternate command paths and flag Completion means consumers can declare alternate command paths and flag
spellings with minimal wiring and invoke canonical behavior and help through spellings with minimal wiring and invoke canonical behavior and help through
them while canonical ownership and binding semantics stay intact. Command alias them while canonical ownership and binding semantics stay intact. Installation
installation provides the selected validation; flag alias installation follows rejects conflicts with canonical commands and applicable flags in either
the validation rules still to be settled. registration order. Remaining flag-target and alias-composition validation
details are still to be settled.
## Open Decisions ## Open Decisions
### OD-1: Public declaration and registration API ### OD-1: Public declaration and registration API
What are the exact command- and flag-alias declaration, path representation, and installation What are the exact command- and flag-alias declaration, path representation, and
signatures? How do alias declarations compose with groups, reusable declarations, installation signatures? How do alias declarations compose with groups, reusable
and later `App.Register` calls? What are the duplicate-declaration semantics? declarations, and later `App.Register` calls? Are identical duplicate declarations
accepted?
### OD-2: Prefix interactions and canonical reachability ### OD-2: Prefix interactions and canonical reachability
How are collisions determined when alias sources or targets overlap canonical How are collisions determined when alias sources or targets overlap canonical
groups or runnable commands with children? How does longest matching interact groups or runnable commands with children? How does longest-token-path matching
with operand boundaries? Which later registrations conflict with existing interact with operand boundaries? How are indirect prefix conflicts detected
aliases? How are ambiguous paths reported? when either aliases or canonical commands are added? How are ambiguous paths
reported?
### OD-3: Chains and group aliases ### OD-3: Chains and group aliases
@@ -248,5 +281,6 @@ 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 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? 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 Which short-flag forms are supported? Are flag-alias chains supported, and how
are collisions, cycles, and missing targets validated at installation and later are alias-to-alias conflicts, cycles, and missing targets validated at installation
registration? How are flag aliases exposed in help and diagnostic spelling? and later registration? How are flag aliases exposed in help and diagnostic
spelling?