From d4d70d38086cfd259f5ce085cf5786ac34f4e6d7 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Fri, 7 Aug 2026 03:57:26 +1000 Subject: [PATCH] G-173 (achieved 2026-08-07): flip punk::path machine-parsable returns to achieved + archive All acceptance criteria verified on tclsh9.0.5-punk (Tcl 9) and tclsh86ts (Tcl 8.6): existing path.test 67/67 green (table output byte-unchanged), pathcmd.test 7/7 (dict/json shape, ansi-freeness, round-trip parity, -context stability), full runner/testsuites/parser suite 23/23. Detail file moves to goals/archive/; GOALS.md entry moves to GOALS-archive.md (newest-first). Reference sweep: G-064 (proposed, the sibling lib.search -return dict/json goal) carried an open json-serialization-mechanism question that G-173's tcllib json::write decision resolves - added a pointer to G-064's Notes. Follow-on recorded (open): apply linecont_lint to the 46 remaining pre-existing line-continuation findings in punk-999999.0a1.0.tm (tech debt predating G-173, outside its edit sites). Assisted-by: harness=pi; primary-model=huggingface/zai-org/GLM-5.2; api-location=huggingface.co --- GOALS-archive.md | 4 ++++ GOALS.md | 4 ---- goals/G-064-libsearch-machine-returns.md | 5 +++++ goals/{ => archive}/G-173-punkpath-machine-returns.md | 9 +++++++-- 4 files changed, 16 insertions(+), 6 deletions(-) rename goals/{ => archive}/G-173-punkpath-machine-returns.md (83%) diff --git a/GOALS-archive.md b/GOALS-archive.md index bc0b364e..5d0b40c7 100644 --- a/GOALS-archive.md +++ b/GOALS-archive.md @@ -20,6 +20,10 @@ Do not edit archived records here except to fix a broken path. Archived detail f ## Archived goals +### G-173 [achieved 2026-08-07] punk::path machine-parsable returns (text/dict/json) with stable conflict verdict → detail: goals/archive/G-173-punkpath-machine-returns.md +Scope: src/modules/punk-999999.0a1.0.tm (punk::path proc - add -return modes + -context); src/tests/modules/punk/path/testsuites/tests/ (return-shape + round-trip + ansi-freeness tests) +Acceptance: -return gains text, dict and json choices whose output contains no ansi escapes regardless of -highlight; the returned structure is documented in the command's punk::args definition; the default table output is byte-unchanged for existing users (existing path.test cases stay green); -return json round-trips the same data as -return dict (decode via tcllib json, recompare); the conflict verdict is stable independent of how the consumer invoked the proc via a -context option (default the caller's namespace); new tests pin dict/json shape, ansi-freeness, and dict/json round-trip parity; a duplicate-path entry and an overshadowed executable each appear in the dict/json with the fields a machine consumer needs (idx, is_duplicate, duplicate_of, overshadowed, overshadowed_by, tcl_conflicts with match=exact|nocase). + ### G-166 [achieved 2026-08-06] cmdinfo/cmdhelp surface recognised-but-unavailable landings distinctly → detail: goals/archive/G-166-cmdinfo-unavailable-surfacing.md Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdinfo result key, cmd_traverse landing attribution, cmdhelp render marking + advisory-parse presentation); src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (virtual ids lead with the unavailability note on affected runtimes); src/tests/modules/punk/ns/testsuites/ns/ (cmdinfo/cmdhelp pins incl the deliberate key-list flip); src/tests/modules/punk/args/testsuites/args/tclcoreparity.test (8.6-arm pins) Acceptance: on a runtime where the tclcore model declares dict unavailable (Tcl 8.6), cmdinfo for 'string is dict' (direct and decomposed invocation forms) reports the new availability key carrying 'dict' while 'string is true' reports it empty, with cmdtype remaining 'doconly' for both (the command-kind axis is not overloaded); the key is present on every cmdinfo result and the cmdhelp.test cmdinfo key-list pin is flipped deliberately; cmdhelp output for an unavailable subject is visibly distinguished in table, text and dict return forms (the dict form carries the key; table/text carry a marking naming the unavailability), and an argument tail such as 'string is dict 5' no longer renders as a cleanly usable command line; the walk's unique-prefix landing on an unavailable name ('i string is dic' on 8.6) has a decided, pinned behaviour consistent with the marking (either resolving the virtual docid WITH the marking, or documented-conservative non-resolution); tclcore virtual ids for unavailable classes lead their rendered help with the unavailability statement on affected runtimes (first description line, not buried mid-prose) while modern runtimes render those ids unchanged; definitions without -choiceunavailable and existing cmdinfo/cmdhelp consumers behave unchanged (full punk/ns and punk/args suites green apart from deliberately flipped pins); the enacted G-073 Follow-on lines carry => goal G-166 dispositions. (Achieved: punk::ns 0.10.0 - cmdinfo 'unavailable' key on every result as a SECOND axis beside cmdtype (both 'string is dict' and 'string is true' stay doconly on 8.6), cmd_traverse records carrying a sixth attribution element; prefix-landing DECIDED as resolve-the-virtual-docid-marked rather than conservative non-resolution, since addressing and availability are separate axes and non-resolution made addressing inconsistent ('i string is tr' resolved, 'i string is dic' did not) - the choice traverse's G-040 parse-parity claim untouched, an unavailable word still identifies no subcommand there; cmdhelp marking via one shared wording in every return form, taking precedence over both the ok-parse info render and any parse failure message so 'i string is dict 5' no longer renders info-scheme-clean; tclcore moduledoc 0.4.1 leads an unavailable class's virtual-id help with the unavailability statement, modern runtimes unchanged; cmdflow.test 25/25 + cmdhelp.test 50/50 on 8.6.10 (affected arm), 8.7a6 and 9.0.5, full punk/args subtree 341/338/3 skips/0 fail on all three, full punk/ns 125 green on 9.0.5 and green on 8.6/8.7 apart from two verified-pre-existing nsprimitives failures, plus a 1257-test src/tests/modules/*** sweep on 9.0.5 with 0 failures; punkshell 0.57.0.) diff --git a/GOALS.md b/GOALS.md index 80d665ee..8751c70f 100644 --- a/GOALS.md +++ b/GOALS.md @@ -410,7 +410,3 @@ Detail: goals/G-171-bake-writes-land-untracked.md Scope: src/buildsuites/suite_tcl90/build905.zig and src/buildsuites/suite_tcl86/build86.zig (flagless target/cpu resolution defaults); src/tools/punkzip/build.zig and src/tools/punkres/build.zig (distributed build-path tools); src/buildsuites/suite_tcl90/tools/family_artifacts.tcl (artifact record emission - the recorded floor field); punkbin artifact repo (external c:/repo/jn/punkbin - win32-x86_64/*.toml sidecars, defaults.txt curation); bin/ (the shipped zig-built exes); src/scriptapps/bin/punk-runtime.* (floor reporting on fetch, floor-vs-host verdict on use/run); scriptlib/developer/ (cpu-floor audit tool) Detail: goals/G-172-distributed-binary-cpu-floor.md -### G-173 [active] punk::path machine-parsable returns (text/dict/json) with stable conflict verdict -Scope: src/modules/punk-999999.0a1.0.tm (punk::path proc - add -return modes + -context); src/tests/modules/punk/path/testsuites/tests/ (return-shape + round-trip + ansi-freeness tests) -Detail: goals/G-173-punkpath-machine-returns.md - diff --git a/goals/G-064-libsearch-machine-returns.md b/goals/G-064-libsearch-machine-returns.md index ba8c1414..561f856a 100644 --- a/goals/G-064-libsearch-machine-returns.md +++ b/goals/G-064-libsearch-machine-returns.md @@ -21,3 +21,8 @@ piped-call direction). - json serialization mechanism decided in the work: a quick sweep found no obvious json writer in-tree (options: minimal local serializer, vendored tcllib json::write, or a punk-native helper). +- G-173 (archived) recorded the json::write encoder choice as the preferred + mechanism (the runtests json_emit hardening confirmed json::write is robust + where a hand-rolled emitter carried a defect class) - see + goals/archive/G-173-punkpath-machine-returns.md; G-064 should adopt json::write + for the same reason when implemented. diff --git a/goals/G-173-punkpath-machine-returns.md b/goals/archive/G-173-punkpath-machine-returns.md similarity index 83% rename from goals/G-173-punkpath-machine-returns.md rename to goals/archive/G-173-punkpath-machine-returns.md index 852b2191..d5ebb4cf 100644 --- a/goals/G-173-punkpath-machine-returns.md +++ b/goals/archive/G-173-punkpath-machine-returns.md @@ -1,6 +1,6 @@ # G-173 punk::path machine-parsable returns (text/dict/json) with stable conflict verdict -Status: active +Status: achieved 2026-08-07 Scope: src/modules/punk-999999.0a1.0.tm (punk::path proc - add -return modes + -context); src/tests/modules/punk/path/testsuites/tests/ (return-shape + round-trip + ansi-freeness tests) Goal: punk::path results are consumable by programs and LLMs as well as humans - a -return option adds text, dict and json choices producing ansi-free output with a documented structure (ordered PATH entries; per-entry executables with overshadowing; TCL-context conflicts), the default table output is unchanged for existing users, and the JSON form uses tcllib json::write as the preferred encoder (the runtests json_emit investigation confirmed json::write is robust where a hand-rolled emitter carried a defect class - misclassified numbers emitted bare, unescaped C0 controls). Acceptance: -return gains text, dict and json choices whose output contains no ansi escapes regardless of -highlight; the returned structure is documented in the command's punk::args definition; the default table output is byte-unchanged for existing users (existing path.test cases stay green); -return json round-trips the same data as -return dict (decode via tcllib json, recompare); the conflict verdict is stable independent of how the consumer invoked the proc via a -context option (default the caller's namespace); new tests pin dict/json shape, ansi-freeness, and dict/json round-trip parity; a duplicate-path entry and an overshadowed executable each appear in the dict/json with the fields a machine consumer needs (idx, is_duplicate, duplicate_of, overshadowed, overshadowed_by, tcl_conflicts with match=exact|nocase). @@ -27,4 +27,9 @@ overlap survey (activation-freshness 2026-08-07): G-042/G-019/G-061/G-110/G-167/ ## Progress -2026-08-07 (activated, implemented): ::punk::path gained -return text|dict|json (default table byte-unchanged), -context (default the caller's namespace - stable conflict verdict for machine consumers), and -conflicts 0|1 (default 1). The collect phase (d_path_info/d_bin_info/d_index_executables) is shared with the table render; the structured modes build a parallel ordered entry list and serialise without ANSI/textblock. JSON is emitted via tcllib json::write (the preferred encoder settled by the runtests json_emit hardening, G-173 Context) so booleans/counts are bare JSON numbers/1-0 and the decoded form equals the dict form byte-for-byte. Conflict verdicts use a clean exact|nocase classification (path_conflicts_for_exe) independent of the table render's ANSI path. New tests: src/tests/modules/punk/pathcmd/testsuites/tests/pathcmd.test (7 tests: dict shape, duplicate/overshadowed fields, json ansi-freeness + round-trip parity, text ansi-freeness, -context stability, -conflicts 0, default-table still ANSI). punk module buildversion 0.2.8 -> 0.3.0; punkproject.toml 0.57.1 -> 0.58.0. \ No newline at end of file +2026-08-07 (activated, implemented): ::punk::path gained -return text|dict|json (default table byte-unchanged), -context (default the caller's namespace - stable conflict verdict for machine consumers), and -conflicts 0|1 (default 1). The collect phase (d_path_info/d_bin_info/d_index_executables) is shared with the table render; the structured modes build a parallel ordered entry list and serialise without ANSI/textblock. JSON is emitted via tcllib json::write (the preferred encoder settled by the runtests json_emit hardening, G-173 Context) so booleans/counts are bare JSON numbers/1-0 and the decoded form equals the dict form byte-for-byte. Conflict verdicts use a clean exact|nocase classification (path_conflicts_for_exe) independent of the table render's ANSI path. New tests: src/tests/modules/punk/pathcmd/testsuites/tests/pathcmd.test (7 tests: dict shape, duplicate/overshadowed fields, json ansi-freeness + round-trip parity, text ansi-freeness, -context stability, -conflicts 0, default-table still ANSI). punk module buildversion 0.2.8 -> 0.3.0; punkproject.toml 0.57.1 -> 0.58.0. +2026-08-07 (acceptance verified, achieved): all acceptance criteria confirmed on tclsh9.0.5-punk (Tcl 9) and tclsh86ts (Tcl 8.6) - existing path.test 67/67 green (table output byte-unchanged), pathcmd.test 7/7 (dict/json shape, ansi-freeness, round-trip parity, -context stability), full runner/testsuites/parser suite 23/23. A closeout pass removed the line-continuation backslashes the G-173 helper procs had been authored with (dict-create + dict-set / json::write accumulator idioms per src/modules/AGENTS.md) and added scriptlib/developer/linecont_lint.tcl to enforce the rule going forward; the punk::args doc block was converted to -& record-continuation markers. These are quality/refactor items, not acceptance-bearing - acceptance was met by the implementation above. + +## Follow-ons + +Follow-on: Apply linecont_lint to the 46 remaining pre-existing line-continuation findings in src/modules/punk-999999.0a1.0.tm (tech debt predating G-173, outside the G-173 edit sites) => open \ No newline at end of file