diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md index 30272b5..64a36dd 100644 --- a/docs/roadmap/aliases.md +++ b/docs/roadmap/aliases.md @@ -69,8 +69,19 @@ Aliases can target individual commands or groups. A group alias preserves remaining subcommand tokens. For example, `list collections` can reach `promptkit list collections` through the `list` group alias. -Match complete argument tokens at the beginning of the command path. Resolve -overlapping alias paths using the longest match. Preserve trailing arguments, +Match exact, complete argument tokens at the beginning of the command path; +`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 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 alias mappings under the existing batch-atomicity model. -Reject aliases that shadow existing canonical command paths. Preserve that -protection when later registration adds commands. Detailed prefix interactions -remain open below. Aliases do not create canonical parent groups, merge -integration trees, or replace handlers. +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 +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 @@ -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 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 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. 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. +capabilities. Short-flag support, chains, alias-to-alias scope conflicts, +target validation, and help presentation remain open below. ## 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 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. +them while canonical ownership and binding semantics stay intact. Installation +rejects conflicts with canonical commands and applicable flags in either +registration order. Remaining flag-target and alias-composition validation +details are still to be settled. ## Open Decisions ### OD-1: Public declaration and registration API -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? +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? Are identical duplicate declarations +accepted? ### OD-2: Prefix interactions and canonical reachability How are collisions determined when alias sources or targets overlap canonical -groups or runnable commands with children? How does longest matching interact -with operand boundaries? Which later registrations conflict with existing -aliases? How are ambiguous paths reported? +groups or runnable commands with children? How does longest-token-path matching +interact with operand boundaries? How are indirect prefix conflicts detected +when either aliases or canonical commands are added? How are ambiguous paths +reported? ### 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 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? +are alias-to-alias conflicts, cycles, and missing targets validated at installation +and later registration? How are flag aliases exposed in help and diagnostic +spelling?