From 563b87cb9b1e757bb063519942e7b6c58d643d60 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sun, 2 Aug 2026 06:47:22 +1000 Subject: [PATCH] G-070 achieved flip content: index->archive swap + reference sweep All acceptance clauses met (working covered-set implementation, parity suites capability-gated + engine pins everywhere, plain-tclsh entry-point demo, auto dispatch preferring c, reference identity recorded). Status -> achieved 2026-08-02; entry moved to GOALS-archive.md. Sweep: G-019 Context/Related updated (stub now real; Goal: contract line left as-is, flagged), G-055 expr-validator notes corrected ('parse expr' NOT in the covered set), G-069 gate-widening mechanism corrected (dispatch via tclparser_prefer, not 'package require parser'). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS-archive.md | 4 +++ GOALS.md | 4 --- .../G-019-dependency-scan-module-trimming.md | 36 +++++++++++-------- goals/G-055-tclcore-regen-workflow.md | 9 +++-- goals/G-069-splitter-tclparser-lint.md | 16 ++++++--- goals/G-070-pure-tcl-tclparser.md | 2 +- 6 files changed, 45 insertions(+), 26 deletions(-) diff --git a/GOALS-archive.md b/GOALS-archive.md index 238496d4..9bcc6968 100644 --- a/GOALS-archive.md +++ b/GOALS-archive.md @@ -95,6 +95,10 @@ Acceptance: a documented probe helper yields a wsl_linux_available constraint wh Scope: LICENSE.txt (new, repo root); README.md; punkproject.toml ([project] license field); AGENTS.md (Repo-wide Notes license mention) Acceptance: LICENSE.txt exists at the repo root containing the standard BSD-2-Clause text with a real copyright line; README.md names BSD-2-Clause and points at LICENSE.txt; root AGENTS.md Repo-wide Notes names the license precisely; punkproject.toml [project] carries license = "BSD-2-Clause"; a repo-sweep for top-level license claims finds none contradicting it (sweep result recorded here). +### G-070 [achieved 2026-08-02] Pure-Tcl tclparser: parse-command API fallback with behavioural parity against the C library → detail: goals/archive/G-070-pure-tcl-tclparser.md +Scope: src/modules/punk/lib-999999.0a1.0.tm (tclparser_tcl stub + dispatch; new module if size warrants - decided in the work); src/tests/modules/punk/lib/ (parity + fallback suites); external fork repo c:/repo/jn/tclparser_punk (read-only reference snapshots + the zig-built parser dll oracle - G-154, achieved - see goals/archive/G-154-tclparser-punk-zig-build.md) +Acceptance: the punk::lib tclparser_tcl error stub is replaced by a working pure-Tcl implementation of the 'parse' subcommands punk::lib currently uses ('parse command' at minimum; the full covered set enumerated in this file during the work), returning the same parse-tree shapes (ranges, token types, expansion handling) the C library returns for those calls; a parity testsuite compares pure-Tcl output against the C tclparser across a recorded probe corpus (representative punkshell module scripts plus edge cases: {*} expansion, comments, backslash-newline continuation, nested command substitution, braces/quotes in words) - parity tests capability-gated on the binary, pure-Tcl-only tests running everywhere; a documented punk::lib analysis entry point (e.g. tclword_to_scriptlist) demonstrably works under a plain tclsh with no parser binary on the package path; dispatch prefers the C parser when available with the fallback engaging automatically otherwise; the reference source consulted (the tclparser_punk fork repo - snapshot and checkin/commit identity per its src/reference provenance table) is recorded in this file. + ### G-071 [achieved 2026-07-12] punk::args value-allocation correctness for optional elements (lseq-class arglists) + parse_status -form → detail: goals/archive/G-071-punkargs-optional-allocation.md Scope: src/modules/punk/args-999999.0a1.0.tm (get_dict value allocation, private::get_dict_can_assign_value, parse_status); src/tests/modules/punk/args/testsuites/args/ (new allocation characterization suite); src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (::lseq as the proving consumer) Acceptance: a new allocation characterization suite drives the lseq range matrix under explicit -form range - '0 10', '0 10 2', '0 10 by 2', '0 to 10 2', '0 .. 10 by 2', '1 5 by 0' parse per the lseq.n grammar (the three currently-failing cases fixed) and '0 10 2 4' still fails - plus reduced fixtures isolating the shape (optional choice value between required values + trailing optional-member clause) independent of the moduledoc; the ::if noise-word cases (mid-clause ?literal(then)?, clause-leading ?literal(else)?) keep passing - no regression to optional clause members generally; a genuinely invalid arglist's error names the failing element (the '..|to' misblame case pinned fixed); punk::args::parse_status accepts -form (single form name/index at minimum, consistent with parse) with its status structure reporting the form used; full punk::args and punk::ns suites pass with no expectations weakened; before/after results for the probe matrix recorded in this file. diff --git a/GOALS.md b/GOALS.md index 967fecd2..c1547fbe 100644 --- a/GOALS.md +++ b/GOALS.md @@ -269,10 +269,6 @@ Detail: goals/G-068-vendored-moduledoc-workflow.md 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) Detail: goals/G-069-splitter-tclparser-lint.md -### G-070 [active] Pure-Tcl tclparser: parse-command API fallback with behavioural parity against the C library -Scope: src/modules/punk/lib-999999.0a1.0.tm (tclparser_tcl stub + dispatch; new module if size warrants - decided in the work); src/tests/modules/punk/lib/ (parity + fallback suites); external fork repo c:/repo/jn/tclparser_punk (read-only reference snapshots + the zig-built parser dll oracle - G-154, achieved - see goals/archive/G-154-tclparser-punk-zig-build.md) -Detail: goals/G-070-pure-tcl-tclparser.md - ### G-072 [proposed] punk::args compound clause types: named alternates with per-element typing and per-alternate arity (try-class handlers) Scope: src/modules/punk/args-999999.0a1.0.tm (type-expression parsing, clause allocation, synopsis/help renderers); src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (::try as proving consumer; ::if/::switch as touched); src/tests/modules/punk/args/testsuites/args/ Detail: goals/G-072-punkargs-compound-clause-types.md diff --git a/goals/G-019-dependency-scan-module-trimming.md b/goals/G-019-dependency-scan-module-trimming.md index 5e88320a..142fe627 100644 --- a/goals/G-019-dependency-scan-module-trimming.md +++ b/goals/G-019-dependency-scan-module-trimming.md @@ -19,19 +19,25 @@ The candidate scanning basis is static parsing of Tcl source via the tclparser `parse` API (tclpro-descended; https://wiki.tcl-lang.org/page/tclparser). Its current availability shapes the work: -- The real implementation is the **c-only tclparser library** +- The preferred implementation is the **c-only tclparser library** (`package require parser`); punk::lib uses it opportunistically. -- punk::lib carries a same-API pure-Tcl fallback, `punk::lib::tclparser_tcl` - (src/modules/punk/lib-999999.0a1.0.tm ~3322), which is an unimplemented stub - that errors advising installation of the C library. +- punk::lib's same-API pure-Tcl fallback is now REAL (G-070, achieved + 2026-08-02 - see goals/archive/G-070-pure-tcl-tclparser.md): + `punk::lib::tclparser_tcl` delegates to the punk::tclparser engine module, + parity-tested against the c library, and `punk::lib::tclparser_prefer` + auto-dispatches (c preferred, pure-Tcl fallback wired otherwise). Note the + covered set is what punk::lib consumes (parse command/getstring/ + countnewline) - 'parse expr' and the other subcommands still require the + c library. - punk::args::moduledoc::parser documents the parse API. -Using the C library inside build tooling makes the build depend on a native -binary - intersecting the G-004/G-005/G-006 binary-provenance story (zig-built -or consent-downloaded, never committed). Completing the pure-Tcl fallback would -remove that coupling at some accuracy/performance cost. The choice (or ordering -- e.g. C library first, fallback later) is an implementation decision to record -here. +Using the C library inside build tooling previously made the build depend on +a native binary - intersecting the G-004/G-005/G-006 binary-provenance story +(zig-built or consent-downloaded, never committed). With G-070 achieved that +coupling is gone for the parse-command analysis surface: the scan can run on +any tclsh, with the c library an optional performance upgrade. (This goal's +Goal: line still describes the fallback as an unimplemented stub - contract +wording predating the G-070 flip.) ## Approach @@ -62,10 +68,12 @@ here. ## Notes -- Related: G-070 (pure-Tcl tclparser fallback; activated 2026-08-02) - directly - supplies this goal's candidate scanning basis without the native-binary - coupling: the tclparser_tcl stub this file cites becomes a working pure-Tcl - 'parse' implementation, so the scan can run inside build tooling on any tclsh. +- Related: G-070 (achieved 2026-08-02 - see + goals/archive/G-070-pure-tcl-tclparser.md) - supplies this goal's candidate + scanning basis without the native-binary coupling: tclparser_tcl is now a + working pure-Tcl 'parse' implementation (punk::tclparser engine, + tclparser_prefer dispatch), so the scan can run inside build tooling on any + tclsh. - Interacts with G-005/G-006 (how the c-only tclparser binary is provisioned if chosen) and G-018 (the spectrum of executable flavours). - G-115 relationship (recorded 2026-07-24; G-115 achieved 2026-07-31 - see diff --git a/goals/G-055-tclcore-regen-workflow.md b/goals/G-055-tclcore-regen-workflow.md index 49fe285f..fe0d8848 100644 --- a/goals/G-055-tclcore-regen-workflow.md +++ b/goals/G-055-tclcore-regen-workflow.md @@ -69,7 +69,10 @@ Per command: sanctioned with @form -overlapallowed, as adopted for ::after cancel). The result dict's 'unsanctioned' key is the gate value (must be empty). Known pre-existing exception: ::lseq's range/start_count and range/count findings - stay unsanctioned pending an expr syntax-validating type (G-069/G-070). + stay unsanctioned pending an expr syntax-validating type (G-069; note + G-070 achieved 2026-08-02 - goals/archive/G-070-pure-tcl-tclparser.md - + covers parse command/getstring/countnewline only, NOT 'parse expr', so + the expr validator still needs the c library or a covered-set extension). 4. Record provenance: the source checkin id the text was read from, noted with the definition (comment) and in the module changelog. @@ -137,7 +140,9 @@ other commands including the multi-form ::after. problem words (count/to/end) all fail Tcl's expr PARSER as invalid barewords while every real-valid shape parses - but a validator must parse without evaluating (operand exprs may contain command substitution), i.e - tclparser 'parse expr' (G-069/G-070) or equivalent, not catch{expr}. Also + tclparser 'parse expr' (G-069; 'parse expr' is NOT in achieved G-070's + covered set - c library required, or extend punk::tclparser on demand) + or equivalent, not catch{expr}. Also noted: count-position operands reject doubles where start/end accept them ('lseq 1.5' errors, 'lseq 1.5 3.5' works) - a value-dependent constraint no lexical type expresses. diff --git a/goals/G-069-splitter-tclparser-lint.md b/goals/G-069-splitter-tclparser-lint.md index 5da70c70..663e3ee5 100644 --- a/goals/G-069-splitter-tclparser-lint.md +++ b/goals/G-069-splitter-tclparser-lint.md @@ -38,15 +38,21 @@ rendering.test) pin known behaviour but cannot flag novel drift against Tcl sema 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. + is expected to run there (or any environment with the package installed). G-070 + (achieved 2026-08-02 - see goals/archive/G-070-pure-tcl-tclparser.md) widens the + substrate, but NOT via 'package require parser' - the pure-Tcl engine deliberately + does not provide that package name (it is the c-library capability probe). The + lint should dispatch via punk::lib::tclparser_prefer (or punk::tclparser + directly); the G-070 covered set (parse command/getstring/countnewline) includes + what record splitting needs. ## 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 + dialect features the comparison must understand), G-070 (achieved 2026-08-02 - + see goals/archive/G-070-pure-tcl-tclparser.md - the pure-Tcl tclparser lets the + lint run without the binary via punk::lib::tclparser_prefer dispatch, not via + 'package require parser'), G-004 (why the runtime must stay dependency-free). - G-154 (achieved 2026-08-02, archived) built first-party parser dlls for both Tcl generations from the tclparser_punk fork (c:/repo/jn/tclparser_punk) - diff --git a/goals/G-070-pure-tcl-tclparser.md b/goals/G-070-pure-tcl-tclparser.md index 620c7c8b..6b3d20fe 100644 --- a/goals/G-070-pure-tcl-tclparser.md +++ b/goals/G-070-pure-tcl-tclparser.md @@ -1,6 +1,6 @@ # G-070 Pure-Tcl tclparser: parse-command API fallback with behavioural parity against the C library -Status: active +Status: achieved 2026-08-02 Scope: src/modules/punk/lib-999999.0a1.0.tm (tclparser_tcl stub + dispatch; new module if size warrants - decided in the work); src/tests/modules/punk/lib/ (parity + fallback suites); external fork repo c:/repo/jn/tclparser_punk (read-only reference snapshots + the zig-built parser dll oracle - G-154, achieved - see goals/archive/G-154-tclparser-punk-zig-build.md) Goal: punk::lib's script-analysis machinery (tclword_to_scriptlist and the dependent analysis paths) runs on runtimes without the tclparser C binary, via a pure-Tcl implementation of the tclparser 'parse' command API covering at least the subcommands and token shapes punk::lib consumes - with behavioural parity verified against the C library rather than assumed, and the C parser still preferred where present (performance). Acceptance: the punk::lib tclparser_tcl error stub is replaced by a working pure-Tcl implementation of the 'parse' subcommands punk::lib currently uses ('parse command' at minimum; the full covered set enumerated in this file during the work), returning the same parse-tree shapes (ranges, token types, expansion handling) the C library returns for those calls; a parity testsuite compares pure-Tcl output against the C tclparser across a recorded probe corpus (representative punkshell module scripts plus edge cases: {*} expansion, comments, backslash-newline continuation, nested command substitution, braces/quotes in words) - parity tests capability-gated on the binary, pure-Tcl-only tests running everywhere; a documented punk::lib analysis entry point (e.g. tclword_to_scriptlist) demonstrably works under a plain tclsh with no parser binary on the package path; dispatch prefers the C parser when available with the fallback engaging automatically otherwise; the reference source consulted (the tclparser_punk fork repo - snapshot and checkin/commit identity per its src/reference provenance table) is recorded in this file.