punkshell/goals/G-151-punkargs-annotated-success-render.md

G-151 punk::args annotated success render (received-args landing report)

Status: proposed Scope: src/modules/punk/args-999999.0a1.0.tm (parse-result presentation); src/tests/modules/punk/args/testsuites/args/ Goal: punk::args can render a SUCCESSFUL parse the way arg_error renders a failed one - the usage table (or a compact per-argument report) annotated with where each received word landed: options consumed, values attributed to the argument that took them, received distinguished from defaulted - so dry-run consumers (make.tcl help today; completion/hinting later) present authoritative landing information instead of hand-assembled summaries. Acceptance: given a successful parse result (or the words plus definition id), a punk::args surface renders per-argument received-vs-default annotation covering leaders, opts and values including -multiple aggregation - the canonical demonstration being a flag-like word consumed as a VALUE (the 'punk91 -confirm 0'-as-three-values class) visibly attributed to its consuming argument; failure-side rendering is unchanged (existing arg_error pins pass); the behaviour is pinned in the args testsuite. make.tcl retiring its interim one-line 'dry-run: line accepted ...' report in favour of this render is recorded as consumer follow-through after a bootsupport promotion, not part of this acceptance.

Context

From the G-143 dry-run help sessions (2026-08-01/02 - archived detail file): the failure side has arg_error's annotated tables, but a successful dry-run had nothing showing where the supplied words landed, so make.tcl grew an interim one-line report built from the parse result's 'received' key ('dry-run: line accepted (form build) - action = build | -test = 0 | toolname = punkzip'; before bake kitnames became choice-restricted, the value-swallow clue read 'kitname = punk91 -confirm 0'). The parse result already carries received/leaders/opts/values/multis - this goal is a presentation surface over existing data, at punk::args level where every consumer (and the repl) can share it.

Notes

• Related: G-050 (proposed) - synopsis argument-validity marking; the nearest sibling (status-aware marking over the same argument rows).
• Related: G-044 (proposed) - punk::args-driven completion; landing attribution is the same data completion hints from.
• Related: G-170 (proposed) - consumer: its launcher help dry-run arm renders this goal's landing report for accepted lines (back-pointer added 2026-08-05 with G-170's cross-link; sequencing lean recorded there).
• Related: G-149 (achieved 2026-08-05 - goals/archive/G-149-punkargs-formhint-labels.md) - configurable form-hint labels; sibling punk::args render-surface goal drafted the same session. Its landed shape (caller option on arg_error/usage + @cmd definition key, caller > definition > default precedence) is the plumbing precedent for adding a render option to the same surfaces.
• Overlap survey 2026-08-02: goals_xref paths src/modules/punk/args-999999.0a1.0.tm - the punkargs family as recorded in G-149's survey; G-050 (named above) is the closest surface, the remainder are parser/spec mechanisms.
• Design leans (user-agreed 2026-08-05, ahead of activation):
  1. Shape: a COMPACT LANDING TABLE - a separate small arg_error-styled bordered table (Argument | Source | Value) stacked under the usage render in dry-run contexts, NOT annotation of the usage table itself (the help column already dominates width and values are the one input authors cannot bound). The existing -parsedargs row marking and goodchoice word marking stay as-is and compose with it. No per-value/per-arg subtables (the -choices subtables earn their borders as static grouped documentation; received values are transient echo) - the report itself is the one bordered block; if G-088's footer mechanism lands later the same content could dock into the usage table's footer without redesign. Arg-oriented rows in declaration-section order (leaders/opts/values); a word-oriented inverse view (word -> argument) is a possible later -return variant, not the primary.
  2. Width: deterministic caps, never console-queried (piped contexts + the emit-then-query flush trap of G-007 (achieved - goals/archive/G-007-console-location-transparency.md); pinned tests want deterministic output). Value column capped ~48 for a ~80 total by default; configurable via the G-149 plumbing precedent (caller option > @cmd definition key > default). Machine-facing returns (-return dict) never truncate - elision is display-only.
  3. Elision is type-aware and always marked (display-hint honesty): strings are single-line-ized (newlines/tabs as visible escapes) then char-capped with trailing '...' plus '(len N)'; lists and -multiple aggregations are element-capped with '(+N more)'; dicts pair-capped with '(+N pairs)'. Pre-elide at data-prep level rather than relying on the textblock table class's per-column -maxwidth (recorded header-truncation TODOs there; and pre-elided strings make the plain twin and test pins trivial).
  4. The ANSI/grapheme-safe char-level truncate primitive lives in punk::ansi::ansistring (beside trim/RANGE/VIEW, per the ANSI-surgery domain rule); punk::args layers only the element/pair-count elision on top. Precondition (user direction 2026-08-05): before modifying ansistring, survey its test coverage against codebase usage and add missing characterization pins so the modification has a safety net. Survey DONE 2026-08-05 (usage-weighted: VIEW ~250 sites incl 124 '-lf 1'; VIEWSTYLE/VIEWCODES/NEW ~40 interactive sites; RANGE 8): 8 pins added to ansistring.test, green 71/71 on tclsh90+tcl87. Findings the implementation must respect: RANGE re-emits MERGED code stacks (not byte-identical round-trip) and DROPS codes trailing the last grapheme (source TODO) - a truncate building on RANGE must fetch trailing state separately (INDEXCODE end+1 works) if it matters; VIEW -lf 1 is the proven single-line-ization primitive; VIEW silently tolerates unknown option pairs (overtype's '-nul 1' sites depend on this - NUL substitution is actually always-on); VIEWCODES/VIEWSTYLE are broken headless (bare 'a+'/'a' interactive-alias dependency, known-deficiency pinned) - do not route the truncate through the class view paths.
  5. Serving the failure-side value-truncation todo recorded in the engine ("truncate/summarize values in error messages", args-999999.0a1.0.tm arg_error region) with the same helper is a FOLLOW-ON, not part of this goal's acceptance.
  6. Row policy: rows only for arguments holding a value post-parse (received, or default-in-effect - the Source column carries the received/default distinction and is the plain-mode-safe twin of the colour marking); absent optionals get no row.