punkshell/goals/G-050-synopsis-validity-marking.md

G-050 punk::ns::synopsis argument-validity marking and status-aware returns

Status: proposed Scope: src/modules/punk/ns-999999.0a1.0.tm (synopsis), src/modules/punk/args-999999.0a1.0.tm (synopsis renderer), src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test (synopsis pins) Goal: synopsis ('s') marks supplied argument words for validity the way cmdhelp's usage display does (goodarg/badarg styles via the G-049 parse-status structure), offers the same status machine-parsably in its dict return, and replaces the curried-alias excess-args length arithmetic (the 's pse' REVIEW note) with a parse against the resolved definition. Acceptance: 's ' renders the supplied words marked as validated and 's ' marks the offending word, while output with no argument words supplied is unchanged (the synopsis_GAP_no_argument_validity_marking pin flips); the dict return carries per-argument status; the curried-alias substitution behaviour (synopsis_curried_alias_shows_braced_target pin) is resolved to a documented presentation derived from parsing rather than list-length arithmetic; existing synopsis output tests (args testsuite synopsis.test and test::punk::args) pass; depends on G-049 for the status structure; G-044's completion/hint display is a consumer of the same status API (cross-reference, not a dependency).

Context

'i <args...>' (cmdhelp) marks supplied argument words for validity; 's <args...>' (synopsis) does not - its output is identical whether the trailing words are valid, invalid or absent (pinned 2026-07-10: synopsis_GAP_no_argument_validity_marking). The user-facing intent is parity: the synopsis line(s) should show which supplied words validated (goodarg style) and where the first problem is (badarg style), with the same info/error scheme signalling as the usage table.

Separately, synopsis's handling of curried aliases is length-arithmetic based: the excess computation (ns-999999.0a1.0.tm, "This isn't quite right.. e.g see: s pse" REVIEW comment) counts args_remaining vs supplied words and lreplaces that many leading synopsis words with resolved_args. For a curried alias the substituted command renders as the braced alias target (e.g {::ns::realcmd curriedarg} ...) rather than the alias name (pinned: synopsis_curried_alias_shows_braced_target).

Approach

Consume the G-049 parse-status structure: parse the trailing words against the resolved definition (same docid resolution as cmdhelp via cmdinfo), then render the synopsis with per-word marking derived from the status, and expose the status in the dict return. Replacing the excess-args arithmetic with an actual parse against the resolved definition is the same change - the parse knows how many words the definition consumed and how the curried words map onto leaders.

Also worth addressing while in there: the existing in-source note that treating the synopsis line as a Tcl list for lreplace is risky with ANSI content ("todo - consider always using 'punk::args::synopsis -return dict' and operating on that list to rebuild string").

Notes

• Depends on G-049 (status structure) - satisfied: achieved 2026-07-10, see goals/archive/G-049-punkargs-parse-status-model.md. G-044's hint display is a future consumer of the same API - keep the marking function reusable outside synopsis/cmdhelp rendering.
• Existing string-shape tests: args testsuite synopsis.test and the installed test::punk::args synopsis tests ("must be no leading space" convention) - marking must be ANSI-only so ansistripped output stays stable, or those tests get a documented update.