Browse Source
G-143 make.tcl help depth: multi-form tool/buildsuite definitions and per-action usage - @form sections with literal action leaders so help shows which actions take <toolname>/-test, 'help <sub> <action>' renders the single form, tool dispatch becomes fully declared, buildsuite keeps its passthrough driver-args contract. G-144 punk::args auto-synopsis @cmd -name fallback for non-command ids - unblocks dropping make.tcl's hand-written ?...? @form -synopsis lines in favour of the automatic bracket notation (retires the G-030 workaround for (script):: ids). G-145 remnant-free piped usage tables - root-cause and eliminate the orphan CSI fragments ([0;1m / [0m / lone m) observed beside table borders in piped help output; extends the G-113 zero-ESC guarantee to zero sequence-fragment text. All three born from the 2026-08-01 argdoc restyle evaluation (mechanisms verified live on bootsupport punk::args 0.12.7). Overlap surveys recorded in each detail file; goals_lint clean (83 active-index goals); xref score reviewed per goal - the top term-scored unlinked pairs for G-143 (G-085, G-021) checked and judged lexical-only, no relation recorded. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.commaster
4 changed files with 83 additions and 0 deletions
@ -0,0 +1,25 @@
|
||||
# G-143 make.tcl help depth: multi-form tool/buildsuite definitions and per-action usage |
||||
|
||||
Status: proposed |
||||
Scope: src/make.tcl (::punkboot::argdoc definitions + help dispatch); src/tests/shell/testsuites/punkexe/ (new piped help characterization test) |
||||
Goal: The tool and buildsuite subcommands are declared as multi-form punk::args definitions (one @form per action with a literal action leader and per-form opts/values) so that full-subcommand help renders one synopsis line per action - making it explicit which actions accept <toolname> and -test where today's single line conflates them - 'make.tcl help <subcommand> <action>' renders that action's single-form usage, tool dispatch parses through the definition (pointed punk::args usage errors for unknown actions and flags), and buildsuite keeps its passthrough driver-args contract (forms serve its help/synopsis accuracy only). |
||||
Acceptance: 'make.tcl help tool' shows per-action synopsis lines (list; info; build with -test and toolnames; test with toolnames) instead of the single conflated line; 'make.tcl help tool build' and 'make.tcl help buildsuite build' render that form's usage table and an unknown action subject produces a punk::args usage error (exit 1); all currently-working tool invocations behave unchanged while 'make.tcl tool <unknown-action>' and unknown flags produce punk::args usage errors (exit 1); buildsuite driver-arg forwarding is unchanged (an arbitrary flag after 'buildsuite build <suite>' still reaches the driver untouched); PUNKBOOT_PLAIN=1 degraded dispatch still handles the same invocations via the plain scan; the behaviours are pinned by a piped characterization test under src/tests/shell/testsuites/punkexe/. |
||||
|
||||
## Context |
||||
|
||||
G-030 (achieved 2026-07-14 - goals/archive/G-030-maketcl-punkargs.md) made make.tcl the punk::args showcase, but its tool/buildsuite definitions document the action surface as one line ('make.tcl tool list|info|build|test ?<toolname> ...? ?-test 0|1?') that cannot say which optionals belong to which action, and 'make.tcl help tool list' is not supported - identified as underspecification of the showcase intent (user review 2026-08-01). The punk shell's 'i' (punk::ns::cmdhelp) renders per-form usage for exactly this shape; make.tcl should showcase the same depth. |
||||
|
||||
## Approach |
||||
|
||||
- Mechanisms verified live on bootsupport punk::args 0.12.7 (2026-08-01): @form sections with 'action -type literal(<name>)' leaders render per-action synopses; punk::args::usage -form <name> <id> renders a single-form table (@cmd -name in the COMMAND header); punk::args::parse auto-selects the form from the literal action word (result dict carries form/formstatus). In-tree exemplar: punk::auto_exec::hash (multi-form definition + handler form dispatch). |
||||
- help dispatch: the help subject gains an optional trailing action word mapped to usage -form; '<subcommand> <action> -help' can route the same way. |
||||
- tool becomes fully declared (its argument surface is a closed set); buildsuite build's trailing driver args stay a -type any -multiple passthrough (arbitrary driver flags must not be parsed as options). |
||||
- Definitions follow the braced -&/tstr argdoc house style (G-045 mechanisms - see src/modules/AGENTS.md "punk::args definition authoring ergonomics"). |
||||
- Same degrade contract as the existing argdoc block (guarded defines + get_spec probes; the plain fallback keeps today's passthrough behaviour). |
||||
|
||||
## Notes |
||||
|
||||
- Related: G-144 (sibling proposal) - auto-synopsis @cmd -name fallback; until it ships, per-form synopsis lines are hand-written (@form -synopsis, bracket notation preferred) or would display definition ids. |
||||
- Related: G-025 (proposed) - the future version-report subcommand should be born to these conventions (carried from G-030's notes). |
||||
- Overlap survey 2026-08-01: goals_xref paths src/make.tcl scores no intersects (make.tcl is a df-damped ubiquitous anchor); manual index sweep - the live make.tcl-scoped goals (G-005 G-006 G-012 G-019 G-023 G-026 G-027 G-028 G-029 G-063 G-065 G-067) are build/vendor mechanics with no help/dispatch overlap; punkexe-test-scoped goals (G-077 G-131 G-141) unrelated. |
||||
- Archived-goal references in this file: G-030 achieved 2026-07-14 (goals/archive/G-030-maketcl-punkargs.md); G-045 achieved 2026-07-12 (goals/archive/G-045-punkargs-authoring-ergonomics.md); G-104 achieved 2026-07-25 (goals/archive/G-104-maketcl-buildsuite-surface.md) - buildsuite surface whose passthrough contract this preserves; G-126 achieved 2026-07-27 (goals/archive/G-126-punkzip-accelerator.md) - origin of the tool subcommand. |
||||
@ -0,0 +1,24 @@
|
||||
# G-144 punk::args auto-synopsis: @cmd -name fallback for non-command ids |
||||
|
||||
Status: proposed |
||||
Scope: src/modules/punk/args-999999.0a1.0.tm (synopsis renderer + usage/arg_error synopsis display); src/tests/modules/punk/args/testsuites/args/ (synopsis pins) |
||||
Goal: Auto-generated synopses render their invocation name from @cmd -name whenever the definition id is not the command's invocation name (script-level ids like (script)::punkboot::modules and (shared)/(package)-style doc ids), falling back to the id only when no @cmd -name is declared - so consumers get the automatic bracket-notation synopsis with the real command name, and explicit @form -synopsis overrides become optional rather than mandatory for such ids. |
||||
Acceptance: a definition with @id -id (script)::x::sub and @cmd -name 'make.tcl sub' auto-renders synopsis lines beginning 'make.tcl sub' across the punk::args::synopsis, usage and arg_error surfaces (table and string renderers), with every form line of a multi-form definition carrying the name; definitions whose id equals the invocation name render byte-identical to today (existing synopsis/usage/arg_error suites pass unchanged apart from deliberately updated pins); a definition with neither a command-path id nor @cmd -name renders the id as today; the new behaviour is pinned in the args testsuite. |
||||
|
||||
## Context |
||||
|
||||
The synopsis generator produces the preferred bracket-notation lines but names the definition id verbatim: verified 2026-08-01 on punk::args 0.12.7 - '(script)::toy::flat [-test <bool>] [toolname]...'. For script-level definitions (make.tcl's (script)::punkboot::<sub>) and shared/package doc ids, that forced the explicit @form -synopsis workaround adopted in G-030 and documented in G-045's authoring ergonomics; make.tcl hand-writes Tcl-style ?...? synopses for this reason alone, while the user-preferred style is the automatic punk::args bracket notation. |
||||
|
||||
## Approach |
||||
|
||||
- Display-only change: parsing, ids, get_spec and spec caching are untouched. |
||||
- Rule to settle in the work: when to prefer @cmd -name over id (candidates: ids carrying a parenthesised origin prefix like (script)/(shared)/(autodef), or any id differing from -name beyond a leading ::). Hard constraint: existing real-command definitions (id == command path) must render unchanged. |
||||
- Consumer follow-through: make.tcl drops its per-definition @form -synopsis lines once this ships (under G-143 if active, else a small follow-on edit). |
||||
|
||||
## Notes |
||||
|
||||
- Origin: G-030 achieved 2026-07-14 (goals/archive/G-030-maketcl-punkargs.md) recorded the id-vs-name synopsis finding and mooted this exact nicety; G-045 achieved 2026-07-12 (goals/archive/G-045-punkargs-authoring-ergonomics.md) documents the explicit @form -synopsis lesson this retires for constructed/script ids. |
||||
- Related: G-050 (proposed) - synopsis validity marking; same renderer surface, independent mechanism. |
||||
- Related: G-056 (proposed) - display-time help wrapping; same renderer file, independent mechanism. |
||||
- Related: G-143 (sibling proposal) - make.tcl consumer of the fallback (auto bracket-notation synopses). |
||||
- Overlap survey 2026-08-01: goals_xref paths src/modules/punk/args-999999.0a1.0.tm lists the punkargs family (G-044 G-050 G-053 G-056 G-069 G-072 G-073 G-075 G-083 G-084 G-088); besides G-050/G-056 named above, these target parser/spec mechanisms, not synopsis name display. |
||||
@ -0,0 +1,22 @@
|
||||
# G-145 Remnant-free piped usage tables: root-cause split ANSI fragments |
||||
|
||||
Status: proposed |
||||
Scope: src/make.tcl (::punkboot::ansistrip transform); src/modules/textblock-999999.0a1.0.tm + src/modules/punk/ansi-999999.0a1.0.tm (ANSI-aware cell/width handling as implicated); src/tests/shell/testsuites/punkexe/maketclcolour.test (remnant pin) |
||||
Goal: Piped make.tcl usage/help output is free of ANSI remnant text: the orphan CSI fragments observed in piped help tables ('[0;1m', '[0m', lone 'm' beside cell borders) are root-caused (renderer-side sequence splitting vs a strip-transform edge case) and eliminated at the producing layer, extending the G-113 zero-ESC guarantee to zero orphan sequence-fragment text while leaving interactive colour output unchanged. |
||||
Acceptance: piped 'tclsh src/make.tcl help <subject>' for every declared subject plus bare 'make.tcl -help' yields output with no ESC bytes and no CSI-remnant substrings (regex {\[[0-9;:]*m}; the help corpus carries no such literal text), pinned in maketclcolour.test; the root cause and chosen fix layer are recorded in this file; existing colour-policy pins (tty/forced/nocolor modes) pass unchanged. |
||||
|
||||
## Context |
||||
|
||||
Observed 2026-08-01 while diffing before/after help captures for the argdoc restyle: piped help output intermittently carries ESC-less ANSI tails inside rendered tables (before the restyle: _toplevel x2, help, modules, vendorupdate; after: _toplevel x4, bakelist, bootsupport, help, info, libs - positions shift with table geometry, so the restyle did not introduce the class). Examples: '[0;1m' at a line end before a cell border, '[0m' at a row start, a lone 'm' beside a border. |
||||
|
||||
## Approach |
||||
|
||||
- Evidence so far: the G-113 write-side strip (::punkboot::ansistrip) already carries a trailing incomplete sequence across write chunks (per-channel carry; flush preserves it, finalize drops it), so a clean ESC-boundary split at the channel would be handled. First suspect is therefore upstream: styled content split by ANSI-aware width/cell handling before write, leaving ESC-less fragment text a byte-level strip correctly ignores. |
||||
- Piped runs do legitimately receive ANSI from module emitters (the strip is load-bearing by design - G-113); punk::args resolve caching also carries a colour-state staleness todo (cached specs can embed colour from resolve time), a possible fragment source to check. |
||||
- Diagnosis route: capture the pre-transform stream for an affected subject (transform popped, or PUNK_FORCE_COLOR run) and determine whether fragments exist pre-strip; fix in textblock/punk::ansi width handling if so, else harden the transform. |
||||
|
||||
## Notes |
||||
|
||||
- G-113 achieved 2026-07-25 (goals/archive/G-113-maketcl-tty-aware-colour.md) - the colour policy and zero-ESC pin surface (maketclcolour.test) this extends. |
||||
- Related: G-056 (proposed) - ANSI-aware wrap/width machinery ('styling in effect carries across the wrap'); if the root cause is renderer-side splitting, the fix layer coincides. |
||||
- Overlap survey 2026-08-01: goals_xref paths punk/ansi module -> G-078/G-079/G-080 (HTML rendering family, unrelated); textblock -> G-048 (table option parse), G-056 (named above), G-088 (footer rendering) - only G-056 shares the mechanism; punkexe tests -> G-077/G-131/G-141 (unrelated). |
||||
Loading…
Reference in new issue