punkshell/goals/G-069-splitter-tclparser-lint.md

G-069 Dev-time lint: cross-check punk::args record splitting against tclparser where the binary is available

Status: proposed Scope: lint surface (location settled in the work: punk::args dev helper, dev commandset, or scriptlib/developer script), src/modules/punk/args-999999.0a1.0.tm (split_definition_records as consumed, no new dependency), src/tests/modules/punk/args/ (capability-gated suite) Goal: a dev-time lint cross-checks the record boundaries produced by punk::args' definition record splitter (private::split_definition_records) against the tclparser C library's 'parse command' tokenization of the same (ANSI-stripped, dialect-adjusted) text, so drift between the definition dialect and real Tcl parsing rules is caught as the dialect grows (-&, @normalize, future continuation/normalization directives) - without punk::args itself gaining any dependency on the tclparser binary. Acceptance: a documented lint command (location decided in the work) accepts definition text and/or registered definition ids and reports record-boundary divergence between split_definition_records and tclparser 'parse command'; the comparison accounts for documented dialect features rather than flagging them (at minimum: ANSI escapes stripped before parse, -& record continuation pre-joined or classified as expected divergence); the lint is capability-gated - a clean, explicit skip/notice when the tclparser package is unavailable, never an error - and package require punk::args continues to succeed with no tclparser present; a run across all definitions registered in a punk9win kit shell (where the tclparser binary ships) yields zero unexplained divergences, with any real divergences found either fixed or recorded in this file; exercised by a capability-gated test or a documented manual run recorded here.

Context

While implementing the -& record-continuation token (G-045, archived), tclparser's 'parse' command was considered and rejected as the splitter's parsing substrate: the definition dialect legitimately deviates from Tcl (unbalanced-bracket ANSI escapes as data inside quoted values, line-based base-indent semantics, the -& token), and a binary dependency in punk::args - the module that must load everywhere, including bootsupport contexts and plain tclsh - inverts the G-004 direction. The full analysis is recorded in goals/archive/G-045-punkargs-authoring-ergonomics.md (Progress, increment 3) and in the punk::args 0.7.0 changelog.

The rejected option still has value as a diagnostic: records are shaped like Tcl commands (newline-delimited, quote/brace/backslash continuation), so where the binary is available, parse-command boundaries are an independent oracle for the splitter. As the dialect grows, an automated cross-check catches unintended divergence early - the splitter's own testsuites (recordcontinuation.test, normalize.test, defquoting.test, rendering.test) pin known behaviour but cannot flag novel drift against Tcl semantics.

Approach

• Comparison pipeline: take the definition text as the splitter receives it, produce splitter records; separately ansistrip the text, pre-join -& continuations (or classify them), then iterate tclparser 'parse command' to produce boundary ranges; compare record counts and boundary line positions, reporting divergences with context.
• Corpus: registered definitions via punk::args introspection (update_definitions + raw defs), plus ad-hoc text input for testing definition snippets during dialect work.
• Home: this is developer tooling, not runtime behaviour - candidates are a punk::args dev/diagnostic namespace proc (loaded lazily), a dev commandset command, or a scriptlib/developer script following goals_lint.tcl precedent. Decide in the work; the constraint is only that punk::args' runtime footprint is unchanged.
• The tclparser binary currently ships only in the punk9win kit (lib_tcl9); the lint is expected to run there (or any environment with the package installed). If G-070 (pure-Tcl tclparser) lands, the gate widens automatically if the lint requires 'parser' via ordinary package resolution.

Notes

• Related: G-045 (archived - origin of the rejected-then-repurposed idea and the dialect features the comparison must understand), G-070 (pure-Tcl tclparser would let the lint run without the binary), G-004 (why the runtime must stay dependency-free).