diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md index dd40ebf..5c3369b 100644 --- a/docs/roadmap/aliases.md +++ b/docs/roadmap/aliases.md @@ -345,8 +345,42 @@ 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 and their validation, and help -presentation remain open below. +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. + +Apply target-availability rules to the final destination. An application-wide +chain contributes nothing where its final canonical flag is unavailable. A +command-scoped declaration must resolve to an available canonical flag. Reject +cycles during installation, identify the participating spellings in diagnostics, +and revalidate composition after later registration. + +Support individual short alias spellings, such as `-c → --color`, alongside +long aliases. Value handling follows the target flag. Short-option clusters +and attached-value syntax must follow CommandKit's deliberately selected grammar; +verify that grammar before settling these forms under OD-6. + +### Flag help and diagnostics + +Present aliases alongside their canonical flags in help. Show only mappings +effective in the current scope, resolve chains to their final targets, and +document each canonical input once. For example: + +```text +--color VALUE + Output color. + Aliases: --colour, -c +``` + +When identifying an invalid occurrence in diagnostics, retain the spelling +the operator supplied and identify the canonical flag where helpful. Conversion, +required-value checks, and repetition behavior continue to come from the +canonical binding. ## Work needed from the baseline @@ -370,7 +404,8 @@ presentation remain open below. resolution, later registration, argument preservation, help without 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. + mixed canonical/alias repetitions, flag chains and scope overrides, short + aliases, flag help and diagnostics, 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). @@ -379,8 +414,8 @@ 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. 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. +registration order. Remaining public API and short-option grammar details are +listed below. ## Open Decisions @@ -395,10 +430,8 @@ path validation rules accompany the selected string representation? What accessor names and representation expose the selected read-only entered and canonical invocation paths? -### OD-6: Flag alias scope and composition +### OD-6: Short-option grammar -Scope precedence, target availability, and application to built-in help are -selected above. Which short-flag forms are supported? Are flag-alias chains -supported, and how do scope precedence and target availability apply through -a chain? How are cycles validated at installation and later registration? -How are flag aliases exposed in help and diagnostic spelling? +Individual short aliases are selected above. Which short-option clusters and +attached-value forms does CommandKit's selected grammar support, and how should +short aliases participate in those forms?