From b82827d837f1b28441bdf18c8074651e188fdb77 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sat, 8 Aug 2026 01:30:50 +1000 Subject: [PATCH] punk::args 0.25.2 + tclcore moduledoc 0.4.2: qualify ensemble names into ensemble_subcommands_definition - 'i ::tcl::prefix' unqualified-ns warnings gone; G-175 drafted (project 0.62.2) 'i ::tcl::prefix' emitted 12x "warning: update_definitions received unqualified ns: tcl" on stderr (6x for subcommand renders). Root cause: the tclcore moduledoc's @dynamic ::tcl::prefix definition passed the ensemble name to punk::args::ensemble_subcommands_definition UNQUALIFIED ('tcl::prefix'). The generator's space-form id_checks derive namespaces via 'namespace qualifiers' - for a relative multi-component name that yields a non-empty UNQUALIFIED namespace ('tcl') which the empty-qualifier guard ('' -> ::) never catches - and update_definitions warned once per subcommand per resolve. @dynamic definitions re-expand on every resolve and the cmdhelp pipeline resolves the id four times (parse_status spec fetch + its internal parse, cmdhelp's get_spec, arg_error/synopsis), so 4 resolves x 3 subcommands = the reported 12. tcl::prefix was the ONLY affected ensemble: all tclcore ensemble docs pass unqualified names, but the single-component ones (info/dict/file/ namespace/array/encoding/zipfs) derive an empty qualifier which was already mapped to ::. Both fixes: - tclcore call site now passes ::tcl::prefix. - ensemble_subcommands_definition normalizes its ensemble argument to fully-qualified in the CALLER's context (uplevel namespace which, :: prepend fallback) before deriving anything - covering any future relative multi-component caller. Verified: zero warnings at both depths; rendered help byte-identical (6301/5585 chars); generator snippet identical for qualified vs unqualified input. New pin ensembledef.test ensembledef_unqualified_ensemble_name_no_warnings (fixture two-component ensemble called relatively under stderr capture; capture_stderr helper added to the file). src/tests/modules/AGENTS.md index updated (ensembledef.test now listed). G-175 drafted (proposed): goals/G-175-punkargs-dynamic-resolve-multiplicity.md - the warning was the only signal of the 4x-per-render @dynamic resolve multiplicity; the goal records the verdict question (render-scoped single resolution vs pinned accept), the attributed resolve sites, the measured cost floor (redundant builder calls ~3ms on 'i ::tcl::prefix', ~22ms on 'i ::dict' steady-state; the full argdata re-processing share is unmeasured - first investigation step), and candidate mechanisms smallest-first. GOALS.md indexed. punk::args 0.25.1 -> 0.25.2, punk::args::moduledoc::tclcore 0.4.1 -> 0.4.2, project 0.62.1 -> 0.62.2 + CHANGELOG (user-visible repl stderr noise fix). Suites: testbody_lint 1688 clean; goals_lint clean (79 active / 96 archived); modules tree 1335 total / 1324 pass / 11 constraint-skipped / 0 fail (zig-built tclsh90s 9.0.5); make.tcl projectversion consistency + staleness OK. Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- CHANGELOG.md | 16 ++++ GOALS.md | 4 + ...5-punkargs-dynamic-resolve-multiplicity.md | 92 +++++++++++++++++++ punkproject.toml | 2 +- src/modules/punk/args-999999.0a1.0.tm | 13 +++ src/modules/punk/args-buildversion.txt | 3 +- .../args/moduledoc/tclcore-999999.0a1.0.tm | 2 +- .../args/moduledoc/tclcore-buildversion.txt | 3 +- src/tests/modules/AGENTS.md | 2 +- .../args/testsuites/args/ensembledef.test | 47 ++++++++++ 10 files changed, 179 insertions(+), 5 deletions(-) create mode 100644 goals/G-175-punkargs-dynamic-resolve-multiplicity.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c4ef9eb..4a8b1fb4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,22 @@ The latest `## [X.Y.Z]` header must match the `version` field in `punkproject.to Entries are newest-first; one bullet per notable change. See the root `AGENTS.md` "Project Versioning" section for the bump policy. +## [0.62.2] - 2026-08-08 + +- `i ::tcl::prefix` no longer emits 12x "warning: update_definitions + received unqualified ns: tcl" on stderr (nor 6x on subcommand renders): + the tclcore moduledoc passed the ensemble name to + `punk::args::ensemble_subcommands_definition` unqualified, and the + generator's space-form id checks derived the non-empty unqualified + namespace `tcl` from it once per subcommand per `@dynamic` re-resolve. + The tclcore call site now passes `::tcl::prefix`, and the generator + itself normalizes its ensemble argument to fully-qualified in the + caller's context - covering any future relative multi-component caller. + Rendered help verified byte-identical. tcl::prefix was the only ensemble + affected: single-component names (`info`, `dict`, `file`, ...) derive an + empty qualifier that was already mapped to `::`. (punk::args 0.25.2, + punk::args::moduledoc::tclcore 0.4.2) + ## [0.62.1] - 2026-08-08 - `grepstr` works with dash-led patterns again: the capture-group probe diff --git a/GOALS.md b/GOALS.md index f56ec4cd..554d02b0 100644 --- a/GOALS.md +++ b/GOALS.md @@ -400,3 +400,7 @@ Detail: goals/G-171-bake-writes-land-untracked.md Scope: src/modules/punk/ns-999999.0a1.0.tm (cmd_traverse/cmdinfo doc-lookup walk, cmdhelp advisory parse + synopsis consumers); src/tests/modules/punk/ns/testsuites/ns/{cmdflow,cmdhelp}.test (conservation characterisation + consumer pins); src/modules/punk/ansi-999999.0a1.0.tm (punk::ansi::a? argdoc - real-world witness, edits only if the sample-form tightening decision lands) Detail: goals/G-174-cmdtraverse-word-accounting.md +### G-175 [proposed] @dynamic resolve multiplicity - one render, one resolution (verdict + optional landing) +Scope: src/modules/punk/args-999999.0a1.0.tm (resolve @dynamic cache-skip, by-id entry points get_spec/parse_status/arg_error/synopsis); src/modules/punk/ns-999999.0a1.0.tm (cmdhelp render pipeline - the four independent by-id fetches); src/tests/modules/punk/args/testsuites/args/dynamic.test + src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test (once-per-render counter pins + cross-render freshness pins, if the landing arm is taken) +Detail: goals/G-175-punkargs-dynamic-resolve-multiplicity.md + diff --git a/goals/G-175-punkargs-dynamic-resolve-multiplicity.md b/goals/G-175-punkargs-dynamic-resolve-multiplicity.md new file mode 100644 index 00000000..a86fc3a3 --- /dev/null +++ b/goals/G-175-punkargs-dynamic-resolve-multiplicity.md @@ -0,0 +1,92 @@ +# G-175 @dynamic resolve multiplicity - one render, one resolution (verdict + optional landing) + +Status: proposed +Scope: src/modules/punk/args-999999.0a1.0.tm (resolve @dynamic cache-skip, by-id entry points get_spec/parse_status/arg_error/synopsis); src/modules/punk/ns-999999.0a1.0.tm (cmdhelp render pipeline - the four independent by-id fetches); src/tests/modules/punk/args/testsuites/args/dynamic.test + src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test (once-per-render counter pins + cross-render freshness pins, if the landing arm is taken) +Goal: a verdict with evidence on whether re-resolving @dynamic definitions multiple times within ONE user-level render (the 'i ' pipeline) is architecturally required - and if not, either a render-scoped single-resolution mechanism lands (each @dynamic definition's substitution scripts run once per cmdhelp invocation, byte-identical output, cross-render freshness untouched) or the per-pass re-resolution is pinned as a recorded decision with its measured cost, the rationale written in this file. +Acceptance: the resolve-level cost share of the multiplicity is measured (not just the subcommand-builder share - each pass re-runs full argdata processing of the definition text) and recorded here; the by-id fetch sites in the cmdhelp pipeline are enumerated with which could accept a pre-resolved spec; a decision is recorded - EITHER a landed mechanism with pins (a counter fixture proving a dynamic definition's substitution scripts run exactly once per cmdhelp render; byte-identical render output; a mutating fixture proving a SECOND render still observes changed state - the @dynamic freshness contract across renders survives) OR a pinned-as-accepted rationale; punk/args and punk/ns suites pass under the canonical runtests interpreter either way. + +## Context + +Surfaced 2026-08-08 while root-causing the 'i ::tcl::prefix' unqualified-ns stderr +warnings (12 = 4 resolves x 3 subcommands - the warning fix landed separately, +punk::args 0.25.2 / tclcore 0.4.2). The warning was the only SIGNAL that the +::tcl::prefix @dynamic definition was being re-resolved 4 times in a single 'i' +render; with it fixed, the multiplicity is silent. + +Probe evidence (trace on the tclcore tclprefix_subcommands builder, tclsh90s, +2026-08-08 - line anchors point-in-time): + + RESOLVE#1 via resolve < get_spec < parse_status < cmdhelp + RESOLVE#2 via resolve < get_dict < parse < parse_status < cmdhelp + RESOLVE#3 via resolve < get_spec < cmdhelp + RESOLVE#4 via resolve < get_spec < synopsis < arg_error < cmdhelp + +Four independent by-id fetches: parse_status resolves twice on its own (spec fetch +plus its internal parse), cmdhelp fetches the spec for rendering, and the +arg_error/synopsis path fetches again. Each fetch is correct in isolation; nothing +shares the resolved spec across the pipeline. + +Architecture (args-999999.0a1.0.tm as at 2026-08-08): resolve consults the +rawdef_cache_argdata cache ONLY for non-dynamic definitions (`if {!$is_dynamic}` +~args:2175) - a @dynamic definition re-runs its tstr command substitutions AND the +full argdata processing on every resolve. That per-resolve re-expansion is the +documented contract (define -help: "@dynamic definitions re-expand on every +resolve" / "Use @dynamic only when the value can change between resolves") and is +what keeps e.g ensemble subcommand choice-tables live when ensembles are extended +at runtime. ALL tclcore ensemble docs are @dynamic (info, encoding, dict, file, +namespace, array, zipfs, tcl::prefix), so every 'i ' pays the +multiplicity. + +Measured cost (steady-state second render, warmed lazy loads, tclsh90s): + + i ::tcl::prefix total ~196ms; subcommand-builder 4 calls = 4.4ms (2%) + i ::dict total ~701ms; subcommand-builder 4 calls = 29.8ms (4%) + +The builder share is the FLOOR of the waste (3 redundant calls of 4): the full +argdata re-processing per redundant resolve is not yet isolated - measuring it is +the first investigation step. Note the totals themselves: the multiplicity sits +inside renders already costing 200-700ms. + +## Approach + +1. Measure the resolve-level share: time resolve for a representative @dynamic + definition (tcl::prefix small, dict large) and multiply out the redundant + passes; record here. If the whole-render saving is negligible even for dict, + the pin-as-accepted arm is available cheaply. +2. Enumerate the by-id entry points in the cmdhelp pipeline (parse_status x2, + get_spec, arg_error/synopsis) and determine which can accept a pre-resolved + spec or share a resolution without API breakage (several already have + spec-shaped internal forms). +3. Candidate mechanisms, smallest-first: + a. cmdhelp resolves once and passes the resolved spec down (plumbing change, + punk::ns-side; punk::args API additions only where a by-id entry lacks a + by-spec form). + b. a render-scoped resolution context in punk::args (explicit begin/end or + token-passed), dynamic argdata memoized within the context only. + c. epoch/generation-keyed short cache - REJECT-by-default: invalidation + semantics are exactly the hard part, and the @dynamic contract is + per-resolve freshness. +4. Whichever arm: pin the outcome (once-per-render counter fixture + byte-identical + render + cross-render freshness for the landing arm; measured-cost rationale + recorded here for the accept arm). + +## Notes + +- Risk to respect: a @dynamic substitution script may observe state mutated + MID-render (in principle even by an earlier substitution). Render-scoped + memoization changes that observable - almost certainly acceptable (a render is + one logical moment), but it is the semantic delta to state explicitly in the + decision. +- The stale-colour REVIEW comment beside the non-dynamic cache consult + (~args:2176 "don't use cached version if 'colour off' vs 'colour on' + different...") shows even the static cache has known freshness caveats - any + new memoization should not widen that class. +- parse_status resolving twice by itself (spec + its internal parse) may be worth + collapsing independently of the dynamic question - it halves the multiplicity + for ALL definitions, static ones included (static hits the cache, so the win + there is small but the call-shape cleanup may pay anyway). +- Related arcs: the G-046 display-field masking (achieved, see + goals/archive/G-046-punkargs-deferred-help-and-fixes.md - expensive -help + processing deferred to display time) already splits parse-relevant from + display-relevant work - a render-scoped mechanism should compose with it, not + duplicate it. diff --git a/punkproject.toml b/punkproject.toml index 00764b03..8468b0c4 100644 --- a/punkproject.toml +++ b/punkproject.toml @@ -1,6 +1,6 @@ [project] name = "punkshell" -version = "0.62.1" +version = "0.62.2" license = "BSD-2-Clause" url = "https://www.gitea1.intx.com.au/jn/punkshell" #packager: declared identity for published artifacts (declarative, not proof - diff --git a/src/modules/punk/args-999999.0a1.0.tm b/src/modules/punk/args-999999.0a1.0.tm index 8a68e4e9..a72cb23d 100644 --- a/src/modules/punk/args-999999.0a1.0.tm +++ b/src/modules/punk/args-999999.0a1.0.tm @@ -14320,6 +14320,19 @@ tcl::namespace::eval punk::args { set opt_groupdict [dict get $optlist -groupdict] set opt_columns [dict get $optlist -columns] + if {![string match ::* $ensemble]} { + #normalize to fully-qualified in the caller's context: the id_checks below + #derive namespaces via 'namespace qualifiers' - a relative multi-component + #name (e.g 'tcl::prefix') would send an unqualified ns ('tcl') to + #update_definitions, which warns on stderr for every subcommand. + set fqensemble [uplevel 1 [list ::tcl::namespace::which $ensemble]] + if {$fqensemble ne ""} { + set ensemble $fqensemble + } else { + set ensemble ::$ensemble + } + } + #warning - circular package dependency if we try to use this function on punk::ns! package require punk::ns set subdict [uplevel 1 [list punk::ns::ensemble_subcommands -return dict $ensemble]] diff --git a/src/modules/punk/args-buildversion.txt b/src/modules/punk/args-buildversion.txt index 166b7695..202e0a0b 100644 --- a/src/modules/punk/args-buildversion.txt +++ b/src/modules/punk/args-buildversion.txt @@ -1,6 +1,7 @@ -0.25.1 +0.25.2 #First line must be a semantic version number #all other lines are ignored. +#0.25.2 - bugfix (reported 2026-08-08 as 'i ::tcl::prefix' emitting 12x 'warning: update_definitions received unqualified ns: tcl'): ensemble_subcommands_definition now normalizes its ensemble argument to fully-qualified in the CALLER's context (namespace which via uplevel, :: prepend fallback for a not-yet-existing command) before deriving anything from it. Previously a relative multi-component name (the tclcore moduledoc passed 'tcl::prefix') flowed into the space-form id_checks, whose 'namespace qualifiers' derivation produced a non-empty UNQUALIFIED namespace ('tcl') that the empty-qualifier guard did not catch - update_definitions then warned on stderr once per subcommand per call (and @dynamic definitions re-run their builders on every resolve: 4 resolves x 3 subcommands = the reported 12). Single-component ensemble names (info/dict/file/...) were never affected (empty qualifier -> :: guard). Rendered output verified byte-identical for both name forms. The tclcore moduledoc call site now passes ::tcl::prefix as well (tclcore 0.4.2). Pin: ensembledef.test ensembledef_unqualified_ensemble_name_no_warnings (fixture two-component ensemble called unqualified: zero warnings + snippet parity with the qualified call). #0.25.1 - bugfix: the -type regex|regexp validator's 'regexp -about' lacked its -- end-of-options guard, so a legitimate dash-led regex VALUE (e.g '-group', a valid ARE matching its literal self) was falsely rejected as 'requires type regexp' with regexp's own bad-option text embedded as the reason. Dash-led regexes now validate; a genuinely invalid dash-led regex still fails as a type mismatch with the real compile reason. Found via the 2026-08-08 grepstr dash-led pattern regression report (punk::ansi 0.2.1 carries the sibling 'regexp -about' fix in grepstr itself; the parse/allocation layer was verified NOT at fault). New validation.test pins: type_regexp_dashled_value (accept + real-reason-reject) and opt_dashword_seats_when_values_require_it (the starved-values dash-led seating rule grepstr relies on - no -- marker needed when word supply equals required-values demand). #0.25.0 - G-053 allocation participation (directed work, post-G-053): bounded -multiple occurrence ranges now PARTICIPATE in positional allocation for leaders and values instead of being post-loop enforcement only. Previously greedy collection overran a bounded max unless a type screen happened to stop it (untyped {3 3} followed by a -multiple tail collected 4 words and occurrencecount then reported the overrun the allocation itself created), and a later REQUIRED ranged argument was starved to a single reserved clause. Three cooperating sites: (a) get_dict_can_assign_value caps a satisfied -multiple argument at its bounded max - it yields the word (no-consume) so the caller's retreat advances to the next argument, serving both the leaders and values loops; the yield carries a G-082 rejection record of new kind 'occurrence', and both loops' overflow selection sites render it as the pointed occurrence-limit report with the G-053 occurrencecount errorcode (count = the attempted occurrence) instead of the generic toomanyarguments - so genuine over-supply keeps its pointed class; (b) reservations are min-occurrence aware - the allocator's tail_needs and the derived valmin floor (leader/value split + option-scan reservation) reserve min-occurrences x min-clause-length for a required ranged argument (e.g a following required -multiple {3 3} reserves 3 clauses; {2 2} pair clauses reserve 4 words); an explicit '@values -min' still overrides the derived floor, and legacy boolean -multiple (no MULTIPLE_RANGES entry) reserves exactly as before; (c) the greedy leader scan caps a bounded -multiple last leader at max occurrences (tracked via leader_posn_names_assigned) so remaining words flow to the opts/values sections. First occurrences are never capped (resolve guarantees range max >= 1); {0 1} at-most-once scalars are unaffected (no collection). define -help -multiple documents the allocation semantics. New multipleranges.test allocation pins: untyped/typed {3 3} cap incl the cap-beats-type-screen 4-ints case, greedy-up-to-max {1 2}, required-range and pair-clause reservations, leaders-side cap + split floor, pointed over-supply report, legacy-greed-unchanged guard. Full punk/args suite 408/0. #0.24.0 - G-084 increment 2 (parsekey completeness, part 2 - the settled cross-member design + integrity closes): -multiple on a member of a shared-parsekey OPTION group is now a DEFINE-TIME error unless ALL members belong to one @opts group marked -parsekeymode error (whose G-083 mutual exclusivity makes per-member collection well-defined; a single -multiple member with its own parsekey is unrestricted). This settles the G-084 cross-member accumulation design decision as rejection rather than accumulate-in-received-order: cross-member collection on one storage key is ambiguous (collect-vs-replace undefined; one member's collected list would silently displace another's). The check runs AFTER the G-053 -multiple canonicalisation so range forms get correct verdicts: {0 1} is replace-shape and allowed on a shared group, collect shapes (boolean 1, max>1, unbounded) are rejected. Value -parsekey integrity settled at define time: duplicate value parsekeys are rejected (trailing values consume positionally so distinct values sharing one result slot silently overwrote each other), and a dash-led value parsekey is rejected (it landed in the options namespace of the result/received dicts and ABORTED parse with an internal error in the option-shaped validation paths). parse_status/parse_report storage-key attribution: parse_status_build now resolves a storage key claimed by exactly ONE argument (a value's -parsekey, an option's declared -parsekey or its '='-suffixed trimmed tail) back to that argument, so argstatus/Source report received with the value-in-effect instead of default/0; shared-parsekey group members stay unresolved (per-member attribution does not survive the storage fold - the remaining recorded G-084 display gap, needs engine-level per-member tracking in the parse result; parse_report's display bridge still shows the group value on each member row). undefine/undefine_deflist now return "" (previously returned the final 'dict unset' expression - the WHOLE cache dict, hundreds of KB, to any caller capturing the value). define -help now documents -parsekey (storage-key rename for options and values, leader rejection, shared groups and -parsekeymode interaction, last-defined-member-wins defaults precedence, the -multiple rule, value parsekey uniqueness/non-dash rules). Internal: dead values-loop identifiers removed (val_ident/val_ident_is_parsekey/values-side seen_pks - assigned per word, never read since the api_valname keying landed), the per-parse parsekey reverse map now iterates only VAL_NAMES (leader map removed entirely - a leader -parsekey is rejected at define time), a dead parsekey-from--default derivation removed in resolve, stale pre-G-084 comments corrected. parsekey.test: parsekey_shared_key_multiple_rejected strengthened (message pins, {0 1}-allowed/{0 4}-rejected range coverage, the -parsekeymode error escape hatch incl collection and optionconflict), new parsekey_value_parsekey_integrity; parsereport.test parsereport_storagekey_attribution + parsestatus.test parsestatus_storagekey_attribution pin the attribution (incl the shared-group default/default remaining-gap row). Full punk/args suite 401/0. diff --git a/src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm b/src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm index cd1a6a77..777420f4 100644 --- a/src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm +++ b/src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm @@ -4408,7 +4408,7 @@ tcl::namespace::eval punk::args::moduledoc::tclcore { # --------------------------------------------------------------------------------------------------------------------------- proc tclprefix_subcommands {} { dict set groups "" {all longest match} - return [punk::args::ensemble_subcommands_definition -groupdict $groups -columns 1 tcl::prefix] + return [punk::args::ensemble_subcommands_definition -groupdict $groups -columns 1 ::tcl::prefix] } set DYN_TCLPREFIX_SUBCOMMANDS {${[punk::args::moduledoc::tclcore::argdoc::tclprefix_subcommands]}} lappend PUNKARGS [list { diff --git a/src/modules/punk/args/moduledoc/tclcore-buildversion.txt b/src/modules/punk/args/moduledoc/tclcore-buildversion.txt index 9f8cbfbd..066a1772 100644 --- a/src/modules/punk/args/moduledoc/tclcore-buildversion.txt +++ b/src/modules/punk/args/moduledoc/tclcore-buildversion.txt @@ -1,6 +1,7 @@ -0.4.1 +0.4.2 #First line must be a semantic version number #all other lines are ignored. +#0.4.2 - bugfix (reported 2026-08-08 as 'i ::tcl::prefix' emitting 12x 'warning: update_definitions received unqualified ns: tcl' on stderr): the ::tcl::prefix @dynamic definition's subcommands builder passed the ensemble name to punk::args::ensemble_subcommands_definition UNQUALIFIED ('tcl::prefix'). The generator's space-form id_checks derived 'namespace qualifiers' from it - 'tcl', non-empty and unqualified - and update_definitions warned once per subcommand per dynamic re-resolve (4 resolves x 3 subcommands = 12 for 'i ::tcl::prefix'; 2 x 3 = 6 for a subcommand render). tcl::prefix was the ONLY tclcore ensemble doc with a multi-component name - the single-component names (info/dict/file/...) derive an EMPTY qualifier which the generator already mapped to ::. Now passes ::tcl::prefix. Sibling hardening: punk::args 0.25.2 normalizes the ensemble argument to fully-qualified in the generator itself (caller-context namespace which), covering any future relative multi-component caller; rendered output verified byte-identical. Pin: punk/args ensembledef.test ensembledef_unqualified_ensemble_name_no_warnings. #0.4.1 - G-166: on a runtime that LACKS a curated forward class, that class's per-class virtual id now LEADS its help with the unavailability statement ('NOT AVAILABLE in this Tcl runtime (). Recognised forward class: ... but 'string is dict' is rejected by this interpreter.'), followed by a blank line and the unchanged static description. The static description already carried the version note - but at its END ('(class not present in Tcl 8.6)' is its twelfth line), so a reader of 'i string is dict' on 8.6 met the full class documentation before learning the class does not exist there. Runtimes where the class is live generate the id unchanged (the unavailable set is empty on 8.7/9.x). Pinned by tclcoreparity.test tclcoreparity_stringis_unavailable_virtualid_leads_with_note (live-derived: affected arm on 8.6, unchanged arm on 8.7/9.x). #0.4.0 - G-073 'string is' forward-class adoption: a curated forward-class list (dict; 'unicode' deliberately excluded - unreleased-8.7-only, removed in Tcl 9) is diffed against the harvested live class set at define time, and classes this runtime lacks are declared -choiceunavailable (punk::args 0.16.0 - the require gains that floor). Effect on 8.6: dict displays among the classes under the Unavailable group with its static description ("class not present in Tcl 8.6"), 'string is dict' is rejected with the tailored choiceunavailable error naming that note, 'string is di' is ambiguous (deliberately stricter than real 8.6, which accepts 'di' as digit - preparing users for 9.x where dict makes it genuinely ambiguous; recorded as a user-sanctioned parity exemption in tclcoreparity.test, full words parity-true), and 'i string is dict' documents the class via its per-class virtual id (the choicelabels build and the virtual-id loop now cover unavailable classes from the same static descriptions). Modern runtimes (8.7/9.x - dict live) compute an empty unavailable list and behave identically to 0.3.4. #0.3.4 - G-074: the documented cancelid/cancelscript overlap on ::after cancel is sanctioned via the new @form -overlapallowed key (punk::args 0.12.0) - punk::args::formcheck now reports it as an acknowledged (sanctioned) structural overlap rather than an actionable finding, leaving ::after with zero unsanctioned findings. Parse behaviour unchanged: an id-shaped 'after cancel' word still raises multipleformmatches (the runtime-liveness ambiguity real Tcl resolves by trying the id first - 0.3.0 record). ::lseq deliberately NOT sanctioned: its range/start_count and range/count overlaps are type-weakness findings (the expr-typed end slot swallows the 'count'/'by' discriminator words) - kept visible pending an expr syntax-validating type (G-069/G-070 territory, G-055 operand-typing record). diff --git a/src/tests/modules/AGENTS.md b/src/tests/modules/AGENTS.md index 24f64cc2..fb17440f 100644 --- a/src/tests/modules/AGENTS.md +++ b/src/tests/modules/AGENTS.md @@ -43,7 +43,7 @@ Unit tests for editable source modules under `src/modules/`, `src/modules_tcl8/` - `commandstack/` — commandstack (cooperative command renaming) tests (`testsuites/commandstack/commandstack.test`, 2026-08-03 - characterisation suite + the G-160 hygiene-pass contract at commandstack 0.6.0 + the 0.7.0 convenience removal forms + the 0.7.1 reload-contract state guards (G-160 follow-ons, 2026-08-04); usage-driven from punk::packagepreference/packagetrace/packagesuppress/punk-auto_execok/punk::nav::fs-cd): record shape as a contract (token first/renamer second dict key order for the lsearch -index 1/-index 3 convention, trailing `did_rename` 0|1, `{implementation {} did_rename 0}` no-rename signal), COMMANDSTACKNEXT/COMMANDSTACKNEXT_ORIGINAL delegation + the `commandstack::next` helper (caller-context parity with the manual uplevel convention pinned), unique+monotonic per-(renamer,command) tokenids (same-renamer re-renames chain and are removable by exact token, third rename succeeds), multi-renamer stacking with removal in any order (bottom-removal re-linking), builtin renames (next_implementor `original`), remove_rename's three argument forms + unknown-renamer errors, the 0.7.0 convenience removal forms (pop_rename - command form pops topmost-for-renamer and returns the removed record, bare form searches live stacks with a multi-command ambiguity error; remove_renamer - all of a renamer's entries across live stacks with correct re-linking, Rename_stack-parked stacks skipped, removed records returned keyed by command; restore_original - whole-stack unwind to the original returning the record count, deliberately registering stack-evidenced renamers so it survives a known_renamers reset while the renamer-explicit forms keep the gate; all silent with debug off), the token->implementation map get_next_command resolves through (map/stack consistency pinned across rename/remove; parked stacks keep dispatching), channel discipline (silent full cycle with debug off; warnings only under debug), debug argument validation, -renamer misplacement errors, get_stack raw-key-first retrieval of Rename_stack-parked records + Rename_stack 1/0 returns, Delete_stack live-record guard (errors; empty/missing return 1), get_IMPLEMENTOR classification incl builtin-where-cmdtype-exists (dynamic expectation - undetermined on 8.6), lib::split_body round-trip, lib::splitx, show_stack fallback render, the reload contract (a module re-source preserves ALL state - stacks/token counters/token map/known_renamers/debug each info-exists guarded; delegation and exact-token removal keep working after reload), the help overview, and lazy punk::args registration of the PUNKARGS docs. Behavioural tests run in fresh child interps per test (module sourced by path relative to the test file; a ::puts shim captures module output for silence/warning assertions and keeps runner output clean); descriptions are single-line per the tcltestrun banner-parsing style guidance in src/tests/AGENTS.md (a hard contract until G-161 made the parser multi-line tolerant). Green on tclsh90 (9.0.3) and punk86 (8.6) - `punkcheck/` — punkcheck module tests (install, summarize_install_resultdict, installtrack) - `punk/ansi/` — punk::ansi tests (`testsuites/ansi/`): ansistrip/ansimerge, plus characterization of the ANSI-at-position mechanisms (`ansistring.test`: INDEX/INDEXCODE/INDEXCHAR/RANGE/INSERT grapheme indexing with SGR-prefix merging, INDEXCOLUMNS/COLUMNINDEX double-wide column mapping, trim/VIEW; extended 2026-08-05 by the G-151 pre-modification coverage survey - VIEW -lf 0/1/2 single-line-ization modes + always-on NUL + silent unknown-option tolerance (load-bearing for overtype's '-nul 1' sites) + C1/zero-width visuals, RANGE end-relative/clamping plus the merged-code-stack re-emission and trailing-code-drop semantics a truncate primitive must respect, COUNT-vs-length combining-accent divergence, NEW object basics, and the KNOWN-DEFICIENCY pin that VIEWCODES/VIEWSTYLE raise invalid-command in a plain punk::ansi interp (bare 'a+'/'a' interactive-alias dependency; pinned in a fresh child interp); plus the TRUNCATE primitive pins landed with G-151 (punk::ansi 0.2.0) - fits-unchanged byte identity incl styled fixtures, grapheme-exact capping with marker budget participation and marker-alone truncation, SGR-reset-before-marker on styled prefixes, CJK/combining-cluster grapheme safety, and strict option errors (deliberately unlike VIEW's pinned silent tolerance)), code splitting invariants (`ta.test`: detect/detectcode distinction, split_codes/split_codes_single/split_at_codes shapes and round-trip) and single-code/effective-state semantics (`codetype.test`: is_sgr_reset/has_sgr_leadingreset, has_any/all_effective, sgr_merge, sequence_type classify), grepstr characterization (`grepstr.test`: return modes incl summarydict (linemap pinned as always-present - the -help says -n-only, reconciliation deferred to the planned hygiene pass), exact highlight SGR wrapping, -n line numbering, invert + empty-highlight strip, -C context/breaks, capture groups, the dash-led pattern fix pin (2026-08-08: the body's 'regexp -about' capture-group probe needed its -- guard - both invocation forms pinned, with and without the -- marker; punk::args seating was never at fault), and the tab deficiency: warns once per call on stderr, single-pass tab line survives - the multi-pass mangling is pinned at consumer level in punk/ns corp.test), and untabify characterization (`untabify.test`: -stops int/list/terminal, -with spaces/unicode/custom-pair, multiline, errors, plus the EXPERIMENTAL -plastic elastic-tabstop mode deliberately pinned-as-interim and retained for possible repl editbuf use). Console queries (get_tabstops/get_size + punk::console::tabwidth) are mocked per the overtype renderline.test pattern - they emit live terminal queries that block/error headless. ANSI codes in these tests are literal escape strings so results are colour-state independent -- `punk/args/` — punk::args tests (`testsuites/args/`): parsing (incl the 2026-08-08 validation.test dash-word pins: the starved-values dash-led seating rule - no -- marker needed when word supply equals required-values demand - and dash-led -type regexp values, whose validator's 'regexp -about' needed its -- guard), choices/choicegroups, forms (incl the 2026-08-05 candidacy fencing/fall-through primitive pins ahead of G-168: -regexprefail on optional value slots is form-fatal with no re-landing, unknown-option/dangling-option/option-value-fence failures fall through to sibling forms as successful parses, and the documented per-word limit - a complete option+value+file line double-matches a fenced scriptfile form and a dash-tolerant stdin form), registered-namespace lazy definition loading (`docpackages.test`, G-169 pre-work: inert registration/scan-vs-load split, id_exists never triggers loading, real_id/usage lazy resolution incl tag-prefixed script-level id families, duplicate-definer last-loaded-wins characterization), the G-168 launch-definition model parity (`punkexemodel.test`, punkexe moduledoc 0.7.0, id loading updated for the G-169 handover - the script id resolves via app-punkscript-docs from src/lib (auto_path derived from the test file location) while the moduledoc carries the core-owned ids: script/tclsh selection matrices against the real (script)::punkexe ids with the real-side dispatch/app oracle recorded in goals/archive/G-168, the bare-'-e' viable-incomplete verdict, the ./-e fence message, -encoding fall-through statuses, and the sanctioned complete-'-encoding' multipleformmatches LIMIT pins; the formcheck.test punkexe GAPs flipped to discriminated/sanctioned/selection-sound pins in the same arc), the G-151 landing report (`parsereport.test`, punk::args 0.18.0 parse_report: the canonical flag-like-word-consumed-as-VALUE attribution row, parsed-result vs words+withid entry parity, machine dict shape with declaration-section row order and absent-optional row omission, received xN multiplicity for solos/-multiple opts, type-aware always-marked elision at the default width plus the caller > @cmd -reportvaluewidth > built-in width cascade and never-elided dict returns, VIEW-style single-line-ization of control-bearing values, aliased-optionset storage-key row bridging plus the G-084 storage-key attribution pin (value-parsekey and renamed-option rows attribute received; a shared-parsekey group member row keeps the bridged value with Source default - the recorded remaining gap), bordered-table/tableobject renders, words-form failure errorcode parity with parse, and the registered two-form definition's own render), rendering/indentation characterization, synopsis display characterization (`synopsis.test`: basic italic argname/`` styling, longopt `--x=` alias forms, literal/literalprefix/stringstartswith/stringendswith type-alternates rendering unitalicised, option alternate parenthesization, multi-element clause display incl `?type?` members and argname tail-word hints, `-typesynopsis` value-element lists and option passthrough incl documenter ANSI, and the small-restricted-choice-set literal rule: 1-3 restricted choices render as unitalicised `|`-joined literals in leader/option/value positions with choicegroups counted, >3 or `-choicerestricted 0` falling back to italics, `-typesynopsis` taking precedence), usage-marking characterization (`usagemarking.test`: -parsedargs/-badarg/-parsestatus/-scheme marking primitives plus goodchoice highlighting of selected/default-in-effect choice words, asserted by SGR-parameter subset against the live colour arrays; the G-049 nocolour/colour-leak GAP pins flipped 2026-07-10 to scheme-statelessness assertions), the G-049 parse-status structure (`parsestatus.test`: punk::args::parse_status overall/per-argument statuses, badarg for type/allocation failures, -caller attribution, errorcode -argspecs stripping, and the G-084 unique-storage-key attribution pin - argstatus reports received/value through a value's -parsekey or a renamed option's declared parsekey), -parsekey characterization (`parsekey.test`: result/received/solos/multis keying, shared-key required satisfaction and defaults, mash-path and prefix-abbreviation keying, plus the G-084 settled pins (2026-08-07): value -parsekey rename support, @values-line -parsekey rejection, leader -parsekey define-time rejection, last-defined-member defaults precedence, cross-member -multiple define-time rejection (allowed only when ALL members share one @opts -parsekeymode error group; a {0 1} range replace-shape stays allowed) and value-parsekey integrity (duplicate/dash-led value parsekeys rejected at define time); `testsuites/dev/parsekey-knownbugs.test` holds no disabled pins (retained as the future punkargsKnownBug home); the parsekey/optname collision GAP is flipped (G-083, 2026-08-07: -parsekey colliding with a distinct defined arg's name is now a resolve error unless that arg shares the parsekey), and the G-083 argument-relations define-time vocabulary is pinned in `relations.test` (per-arg -conflicts target validation, @opts -parsekeymode override|error storage and the requires-group/bad-value/requires-parsekey resolve errors), plus its increment-2 parse-time enforcement (optionconflict raise for -conflicts violations and -parsekeymode error co-occurrence, defaults-never-conflict, cross-group conflicts, parse_status invalid classification), and its increment-3 usage/synopsis rendering and lsearch moduledoc adoption (conflicts-with hints appended to per-arg help rows, -parsekeymode error groups annotated 'mutually exclusive' in group headers with override groups unannotated, synopsis one-line form carrying no conflict detail; and the lsearch tclcore moduledoc modelling -sorted/-glob and -bisect/-all incompatibilities via per-arg -conflicts while -glob/-regexp stay last-wins and the 'punk::args fixes required' caveat is dropped))), the G-053 range-valued -multiple occurrence arity (`multipleranges.test`, punk::args 0.22.0: {min max} range canonicalisation into a per-form MULTIPLE_RANGES companion dict while the stored -multiple boolean keeps its hot-path list-collect meaning so legacy 0/1 stay byte-unchanged, the -optional/range-min reconciliation resolve error, the {0 1}/{2 4}/{1 -1} scalar-vs-list value shapes, parse-time occurrencecount enforcement with min-under-supply suppressed in the G-152 viability probe and classified incomplete (pure exhaustion) while over-max is invalid, the usage-table Multi column showing 0-1/2-4/1+ with the synopsis ?arg? at-most-once ellipsis distinction, and -multipleunique composition; plus the allocation-participation pins (directed work 2026-08-08, punk::args 0.25.0): bounded ranges cap greedy leader/value collection at max occurrences (incl the cap-beats-type-screen case), min-occurrence-aware reservations keep a later required ranged argument fed (single and pair clauses, the leaders-side scan cap and split floor), genuine over-supply reports the pointed occurrence limit at the overflow site, legacy boolean greed unchanged), longopt style-distinction and mash-edge characterisation (`longopts.test`, 2026-08-07 gap-fill: the gnu (`--flag=` inline-only; spaced/solo usage = badoptionformat) vs plain (`--flag` spaced-only; inline `=` = invalidoption) vs mixed (`-f|--file|--file=` both forms incl longopt prefix abbreviation) definition-grammar distinctions, first-`=`-only value splitting and empty inline values, the two `=`-member resolve-time definition errors, single-dash `-flag=value` never split at the `=`, and `@opts -any 1` adhoc passthrough where `--flag=value` splits but `-flag=value` stays a whole adhoc flagname expecting a value; the same gap-fill added to `mashopts.test`: unknown-letter-in-mash invalidoption rejection and the `-any` interplay - defined flags still mash while undefined mash-lookalike tokens are adhoc flags, never mash attempts; error-shape pins use the first three -errorcode elements), and tclcore doc/interpreter behavioural parity (`tclcoreparity.test`, G-054, gated on have_tclcoredocs: 'string is' class choices equal the live-harvested set, per-class docids exist, error-vs-ok agreement across the probe matrix; version-note labels appear when the class is live OR is a declared forward unavailable class - dict labels on every runtime since G-073, unicode keeps the live-only rule; the G-073 forward-class adoption invariants and the USER-SANCTIONED 'di' prefix-strictness exemption (the model is deliberately stricter than real 8.6, full words parity-true); and the G-166 pin that an unavailable class's per-class virtual id LEADS its help with the unavailability statement on runtimes lacking the class while modern runtimes generate it unchanged. All expectations are derived from the running interpreter, green on 8.6/8.7/9.0 through runtests.tcl on each - native Tcl 8.6 has been a supported runner interpreter since 2026-07-21) +- `punk/args/` — punk::args tests (`testsuites/args/`): parsing (incl the 2026-08-08 validation.test dash-word pins: the starved-values dash-led seating rule - no -- marker needed when word supply equals required-values demand - and dash-led -type regexp values, whose validator's 'regexp -about' needed its -- guard), choices/choicegroups, forms (incl the 2026-08-05 candidacy fencing/fall-through primitive pins ahead of G-168: -regexprefail on optional value slots is form-fatal with no re-landing, unknown-option/dangling-option/option-value-fence failures fall through to sibling forms as successful parses, and the documented per-word limit - a complete option+value+file line double-matches a fenced scriptfile form and a dash-tolerant stdin form), the ensemble_subcommands_definition generator (`ensembledef.test`: lazy-argdoc ordering - the generator loads registered-but-unloaded subcommand argdocs before its id checks; plus the 2026-08-08 unqualified-ensemble-name normalization pin - a relative multi-component name is qualified in the caller's context, zero update_definitions stderr warnings and snippet parity with the qualified call), registered-namespace lazy definition loading (`docpackages.test`, G-169 pre-work: inert registration/scan-vs-load split, id_exists never triggers loading, real_id/usage lazy resolution incl tag-prefixed script-level id families, duplicate-definer last-loaded-wins characterization), the G-168 launch-definition model parity (`punkexemodel.test`, punkexe moduledoc 0.7.0, id loading updated for the G-169 handover - the script id resolves via app-punkscript-docs from src/lib (auto_path derived from the test file location) while the moduledoc carries the core-owned ids: script/tclsh selection matrices against the real (script)::punkexe ids with the real-side dispatch/app oracle recorded in goals/archive/G-168, the bare-'-e' viable-incomplete verdict, the ./-e fence message, -encoding fall-through statuses, and the sanctioned complete-'-encoding' multipleformmatches LIMIT pins; the formcheck.test punkexe GAPs flipped to discriminated/sanctioned/selection-sound pins in the same arc), the G-151 landing report (`parsereport.test`, punk::args 0.18.0 parse_report: the canonical flag-like-word-consumed-as-VALUE attribution row, parsed-result vs words+withid entry parity, machine dict shape with declaration-section row order and absent-optional row omission, received xN multiplicity for solos/-multiple opts, type-aware always-marked elision at the default width plus the caller > @cmd -reportvaluewidth > built-in width cascade and never-elided dict returns, VIEW-style single-line-ization of control-bearing values, aliased-optionset storage-key row bridging plus the G-084 storage-key attribution pin (value-parsekey and renamed-option rows attribute received; a shared-parsekey group member row keeps the bridged value with Source default - the recorded remaining gap), bordered-table/tableobject renders, words-form failure errorcode parity with parse, and the registered two-form definition's own render), rendering/indentation characterization, synopsis display characterization (`synopsis.test`: basic italic argname/`` styling, longopt `--x=` alias forms, literal/literalprefix/stringstartswith/stringendswith type-alternates rendering unitalicised, option alternate parenthesization, multi-element clause display incl `?type?` members and argname tail-word hints, `-typesynopsis` value-element lists and option passthrough incl documenter ANSI, and the small-restricted-choice-set literal rule: 1-3 restricted choices render as unitalicised `|`-joined literals in leader/option/value positions with choicegroups counted, >3 or `-choicerestricted 0` falling back to italics, `-typesynopsis` taking precedence), usage-marking characterization (`usagemarking.test`: -parsedargs/-badarg/-parsestatus/-scheme marking primitives plus goodchoice highlighting of selected/default-in-effect choice words, asserted by SGR-parameter subset against the live colour arrays; the G-049 nocolour/colour-leak GAP pins flipped 2026-07-10 to scheme-statelessness assertions), the G-049 parse-status structure (`parsestatus.test`: punk::args::parse_status overall/per-argument statuses, badarg for type/allocation failures, -caller attribution, errorcode -argspecs stripping, and the G-084 unique-storage-key attribution pin - argstatus reports received/value through a value's -parsekey or a renamed option's declared parsekey), -parsekey characterization (`parsekey.test`: result/received/solos/multis keying, shared-key required satisfaction and defaults, mash-path and prefix-abbreviation keying, plus the G-084 settled pins (2026-08-07): value -parsekey rename support, @values-line -parsekey rejection, leader -parsekey define-time rejection, last-defined-member defaults precedence, cross-member -multiple define-time rejection (allowed only when ALL members share one @opts -parsekeymode error group; a {0 1} range replace-shape stays allowed) and value-parsekey integrity (duplicate/dash-led value parsekeys rejected at define time); `testsuites/dev/parsekey-knownbugs.test` holds no disabled pins (retained as the future punkargsKnownBug home); the parsekey/optname collision GAP is flipped (G-083, 2026-08-07: -parsekey colliding with a distinct defined arg's name is now a resolve error unless that arg shares the parsekey), and the G-083 argument-relations define-time vocabulary is pinned in `relations.test` (per-arg -conflicts target validation, @opts -parsekeymode override|error storage and the requires-group/bad-value/requires-parsekey resolve errors), plus its increment-2 parse-time enforcement (optionconflict raise for -conflicts violations and -parsekeymode error co-occurrence, defaults-never-conflict, cross-group conflicts, parse_status invalid classification), and its increment-3 usage/synopsis rendering and lsearch moduledoc adoption (conflicts-with hints appended to per-arg help rows, -parsekeymode error groups annotated 'mutually exclusive' in group headers with override groups unannotated, synopsis one-line form carrying no conflict detail; and the lsearch tclcore moduledoc modelling -sorted/-glob and -bisect/-all incompatibilities via per-arg -conflicts while -glob/-regexp stay last-wins and the 'punk::args fixes required' caveat is dropped))), the G-053 range-valued -multiple occurrence arity (`multipleranges.test`, punk::args 0.22.0: {min max} range canonicalisation into a per-form MULTIPLE_RANGES companion dict while the stored -multiple boolean keeps its hot-path list-collect meaning so legacy 0/1 stay byte-unchanged, the -optional/range-min reconciliation resolve error, the {0 1}/{2 4}/{1 -1} scalar-vs-list value shapes, parse-time occurrencecount enforcement with min-under-supply suppressed in the G-152 viability probe and classified incomplete (pure exhaustion) while over-max is invalid, the usage-table Multi column showing 0-1/2-4/1+ with the synopsis ?arg? at-most-once ellipsis distinction, and -multipleunique composition; plus the allocation-participation pins (directed work 2026-08-08, punk::args 0.25.0): bounded ranges cap greedy leader/value collection at max occurrences (incl the cap-beats-type-screen case), min-occurrence-aware reservations keep a later required ranged argument fed (single and pair clauses, the leaders-side scan cap and split floor), genuine over-supply reports the pointed occurrence limit at the overflow site, legacy boolean greed unchanged), longopt style-distinction and mash-edge characterisation (`longopts.test`, 2026-08-07 gap-fill: the gnu (`--flag=` inline-only; spaced/solo usage = badoptionformat) vs plain (`--flag` spaced-only; inline `=` = invalidoption) vs mixed (`-f|--file|--file=` both forms incl longopt prefix abbreviation) definition-grammar distinctions, first-`=`-only value splitting and empty inline values, the two `=`-member resolve-time definition errors, single-dash `-flag=value` never split at the `=`, and `@opts -any 1` adhoc passthrough where `--flag=value` splits but `-flag=value` stays a whole adhoc flagname expecting a value; the same gap-fill added to `mashopts.test`: unknown-letter-in-mash invalidoption rejection and the `-any` interplay - defined flags still mash while undefined mash-lookalike tokens are adhoc flags, never mash attempts; error-shape pins use the first three -errorcode elements), and tclcore doc/interpreter behavioural parity (`tclcoreparity.test`, G-054, gated on have_tclcoredocs: 'string is' class choices equal the live-harvested set, per-class docids exist, error-vs-ok agreement across the probe matrix; version-note labels appear when the class is live OR is a declared forward unavailable class - dict labels on every runtime since G-073, unicode keeps the live-only rule; the G-073 forward-class adoption invariants and the USER-SANCTIONED 'di' prefix-strictness exemption (the model is deliberately stricter than real 8.6, full words parity-true); and the G-166 pin that an unavailable class's per-class virtual id LEADS its help with the unavailability statement on runtimes lacking the class while modern runtimes generate it unchanged. All expectations are derived from the running interpreter, green on 8.6/8.7/9.0 through runtests.tcl on each - native Tcl 8.6 has been a supported runner interpreter since 2026-07-21) - `punk/nav/ns/` — punk::nav::ns tests (`testsuites/nav/navns.test`): the n/ n// n/// navigation state machine (ns/ transitions absolute/relative/glob-no-nav, failed-nav state preservation, quad-colon normalization, v-form content selection, ensemble annotation) and the ::punk::nav::ns::ns_current variable contract the repl/codethread/subshell seeding all consume; display content is covered in punk/ns nslist.test - `punk/repl/` — punk::repl tests (`testsuites/repl/`): opunk console backend integration (`consolebackends.test`) and repl current-namespace retention (`nscurrent.test`: real codethread via repl::init driven by synchronous runscript sends - inscope evaluation of ns_current, retention across submissions, n/-navigation retained, auto-create-with-notice for missing namespaces, the 2026-07-14 stray-namespace seeding fix pinned behaviourally plus a source-text guard on repl::start's inline template; the end-to-end piped subshell session is covered at shell level by shell/testsuites/punkexe/shellnavns.test - which found the first-subshell shared-code-interp asymmetry and the piped-inscope gap recorded there) - `punk/ns/` — punk::ns tests (`testsuites/ns/`): cmdwhich/cmdinfo/cmd_traverse doc-lookup flow (`cmdflow.test`, G-040 parity; plus the G-166 availability axis on the flowunavail/flowunavail_nodoc fixtures - the `unavailable` cmdinfo key present on every result, exact and unique-prefix landings on a `-choiceunavailable` name resolving that name's virtual docid ATTRIBUTED rather than resolving nothing, the choice traverse attributing without addressing when no virtual docid exists, and cmdtype staying unchanged throughout since availability is a second axis, never a cmdtype value), n/ display machinery characterization (`nslist.test`: tier A get_ns_dicts classification buckets as the machine contract for display reworks - incl package tail/prefix derivation, alias edge cases, usageinfo scan-dependence; tier B per-element layout-agnostic marking - underline/underdouble/underdotted namespace package styles, command type tag colours, exported/imported markers, the punkargs doc icon; tier C REWORK-flagged pins of the current hardcoded 2-col/4-col layout and nspath subtables, to flip deliberately with the planned punk-tables/width-responsive rework; plus the flipped nslist_types_default pin - bare nslist without -types displays all member types since punk::ns 0.7.1 fixed the braced-literal -types default), corp proc-retrieval and syntax/untabify interplay (`corp.test`: name edge cases, -ranges/-n line handling, basic-highlight ansistrip equivalence, -untabify spaces/unicode tab-free output, the KNOWN-DEFICIENCY pin for default -untabify none on tabbed bodies - grepstr warns per pass and brace overlays mangle tabbed lines, deterministic under mocked console tabstops - and a ::tcl::CopyDirectory -untabify spaces smoke test; precursor coverage for the planned punk::ns hygiene pass), cmdtrace characterization (`cmdtrace.test`: -pause 0 non-interactive runs, linedict line-mark keys for flat and 2-word-form nested switches as correct-mark guards, and GAP pins for the upstream nested-switch mismark - core.tcl-lang.org tktview 5d5b1052280c976ea3d4, arm bodies whose split-list index lands on a literal switch-command word report container-relative lines; mark tests gated on have_tclcoredocs because cmdtrace's arm-offset correction parses against the ::switch argdoc; plus the fixed-canary asserting punk::lib::check::has_tclbug_nestedswitch_tracelines still reports the bug - a live behavioural probe, so a fixed Tcl release fails the canary first and triggers the documented flip workflow), cmdhelp usage-rendering integration (`cmdhelp.test`: scheme selection, goodarg/badarg marking incl type/allocation failures, goodchoice highlighting of supplied/default choice words, alias path, cmdinfo result shape, queried-command failure attribution, and `-return dict` parse-status returns (G-049 - its GAP pins flipped 2026-07-10); the flipped G-051 pins for pseudo-command cmdtype (`doconly`) + space-form docid prefixes (real `string is` pins behind the have_tclcoredocs constraint); the G-166 unavailability marking on the helpstrua fixture and on the real `string is dict` subject - the `-return dict` key, the table/string marking with the info scheme suppressed so a valid argument tail no longer renders as a cleanly usable command line, and the `-return text` leading `UNAVAILABLE:` line (the two deliberate key-list flips - `cmdhelp_cmdinfo_result_shape`, `cmdhelp_return_dict_valid` - landed with it); remaining GAP pins for TclOO undocumented-method fallback (G-052) and synopsis marking absence (G-050); plus the G-150 flag-led form-narrowing + selection-soundness pins against punk::auto_exec::hash - bare-parse selection contract (incl the dash-led-name noformmatch cost), no-word/unknown-flag/ambiguity whole-render fallbacks, and hash runtime-behaviour-unchanged), and name/path primitive characterization (`nsprimitives.test`: string pins for nsparts/nsprefix/nstail/nsjoin/nsjoinall incl weird colon-run (`:::`) splitting, the trailing-colon parse ambiguity (`::x:` + `y` joins to the same string as `::x` + `:y` and reparses leading-colon-greedy), and prefix/tail/join round-trip and its absolutizing exceptions (the original twin-divergence pins for nsparts1/nsprefix1/nsprefix_orig/nstail1/nstail_orig served as safe-deletion evidence and were removed with the twins in the punk::ns 0.7.0 hygiene pass - divergence record in this file's git history, commit 0c7168a1); plus nseval fq-requirement/create-on-eval/evaluator-proc caching, the native-vs-punk `p:::x` resolution divergence (native namespace eval reaches child `x`, nseval creates/reaches literal `:x`), nseval_ifexists no-create + error propagation on plain and genuinely weird namespaces, nsexists/nschildren/nstree_raw weird-ns and relative-resolution pins, globmatchns `*`/`**`/`?` semantics (incl `*` matching a single inner colon - a formerly stale 'should be fixed' comment above nsglob_as_re was corrected in the 0.7.0 hygiene pass), and nspath_to_absolute/nspath_here_absolute caller-resolution pins; the nsjoinall error-message wart pin ('nsjoin:' prefix) flipped when punk::ns 0.7.1 fixed it) diff --git a/src/tests/modules/punk/args/testsuites/args/ensembledef.test b/src/tests/modules/punk/args/testsuites/args/ensembledef.test index 0a1d46c9..58685207 100644 --- a/src/tests/modules/punk/args/testsuites/args/ensembledef.test +++ b/src/tests/modules/punk/args/testsuites/args/ensembledef.test @@ -22,6 +22,31 @@ namespace eval ::testspace { set result "" } + #capture stderr written during script (chan push transform; popped in all paths) + proc capture_stderr {script} { + variable caught "" + chan push stderr {apply {{cmd chan args} { + switch -- $cmd { + initialize {return {initialize finalize write}} + finalize {return} + write {append ::testspace::caught [lindex $args 0]; return ""} + } + }}} + set code [catch {uplevel 1 $script} r ropts] + chan pop stderr + if {$code} { + return -options $ropts $r + } + if {[string first \x00 $caught] >= 0} { + #stderr backed by a windows console delivers a utf-16le wide-char stream to + #the transform - decode (see the sibling helpers in punk/args dynamic.test + #and punk/ansi grepstr.test) + set enc [expr {"utf-16le" in [encoding names] ? "utf-16le" : "unicode"}] + set caught [encoding convertfrom $enc $caught] + } + return $caught + } + #fixture: module-style ensemble whose subcommand argdocs are registered for lazy #loading (as punk::ansi does for ::punk::ansi::ansistring) but never explicitly #loaded by this file before the generator runs. @@ -77,5 +102,27 @@ namespace eval ::testspace { -cleanup { }\ -result [list 1 1 1] + + #added 2026-08-08 (agent) - directed work ('i ::tcl::prefix' unqualified-ns warning + #report): a RELATIVE multi-component ensemble name (like the tclcore moduledoc's + #former 'tcl::prefix') made the space-form id_checks derive namespace qualifiers + #'testspace' (non-empty, unqualified - the single-component names' empty-qualifier + #guard never caught it) and update_definitions warned on stderr once per subcommand + #per call. The generator now normalizes the ensemble argument to fully-qualified in + #the caller's context before deriving anything from it. + test ensembledef_unqualified_ensemble_name_no_warnings {an unqualified multi-component ensemble name is normalized: no update_definitions stderr warnings and output identical to the qualified call}\ + -setup $common -body { + set qualified [punk::args::ensemble_subcommands_definition -columns 1 ::testspace::ensdeflazy] + set errout [capture_stderr { + set ::testspace::relsnippet [punk::args::ensemble_subcommands_definition -columns 1 testspace::ensdeflazy] + }] + lappend result [regexp -all {warning: update_definitions received unqualified ns} $errout] + lappend result [string equal $::testspace::relsnippet $qualified] + unset ::testspace::relsnippet + set result + }\ + -cleanup { + }\ + -result [list 0 1] } tcltest::cleanupTests ;#needed to produce test summary line.