From 367b65759cc180319cdfe844ffa45e5dce2dadc9 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Mon, 13 Jul 2026 03:19:28 +1000 Subject: [PATCH] goals: add G-075 (punk::args (package) ids - lookup fix + package documentation surface) Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 4 ++ goals/G-075-punkargs-package-ids.md | 67 +++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 goals/G-075-punkargs-package-ids.md diff --git a/GOALS.md b/GOALS.md index 6c3a6953..a04cb116 100644 --- a/GOALS.md +++ b/GOALS.md @@ -289,3 +289,7 @@ Detail: goals/G-073-punkargs-unavailable-choices.md ### G-074 [proposed] punk::args multiform ambiguity analysis: on-demand form-overlap detection with sanctioned-overlap annotation Scope: src/modules/punk/args-999999.0a1.0.tm (analysis command, @form sanction key as decided in the work), src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (::after/::lseq as proving consumers, sanction adoption), src/tests/modules/punk/args/testsuites/args/ (new suite) Detail: goals/G-074-punkargs-multiform-ambiguity-lint.md + +### G-075 [proposed] punk::args (package) ids: working lookup and a user-facing package documentation surface +Scope: src/modules/punk/args-999999.0a1.0.tm (id lookup/update_definitions prefix handling, usage/arg_error rendering of package-level ids), src/modules/punk/ns-999999.0a1.0.tm (cmdhelp/help-system surface), src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/modules/template_module-0.0.4.tm (template block as touched/verified), src/tests/modules/punk/args/testsuites/args/ + src/tests/modules/punk/ns/testsuites/ns/ (new coverage) +Detail: goals/G-075-punkargs-package-ids.md diff --git a/goals/G-075-punkargs-package-ids.md b/goals/G-075-punkargs-package-ids.md new file mode 100644 index 00000000..b3be73a2 --- /dev/null +++ b/goals/G-075-punkargs-package-ids.md @@ -0,0 +1,67 @@ +# G-075 punk::args (package) ids: working lookup and a user-facing package documentation surface + +Status: proposed +Scope: src/modules/punk/args-999999.0a1.0.tm (id lookup/update_definitions prefix handling, usage/arg_error rendering of package-level ids), src/modules/punk/ns-999999.0a1.0.tm (cmdhelp/help-system surface), src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/modules/template_module-0.0.4.tm (template block as touched/verified), src/tests/modules/punk/args/testsuites/args/ + src/tests/modules/punk/ns/testsuites/ns/ (new coverage) +Goal: the "(package)" ids that the module template (dev module.new) and the punk::args::moduledoc::* packages already declare become functional and user-visible - the id lookup path handles the (package) prefix (today punk::args::id_exists returns 0 for them and update_definitions emits an unqualified-ns warning, because only the (autodef) prefix is stripped when deriving a namespace from an id), a package-level id renders its @package -name/-help as a package documentation page through the usage machinery, and the interactive help surface reaches it ('i ' presenting the package doc when resolves to a documented package rather than a command - exact surface decided in the work), making @package -help the natural home for per-package conventions and usage notes (e.g a moduledoc's harvest/provenance conventions). +Acceptance: punk::args::id_exists returns true for a registered "(package)" id after its namespace's scan (the update_definitions "received unqualified ns" warning no longer fires for (package)-prefixed lookups); punk::args::usage renders a (package) id via the @package directive's fields (render shape decided in the work - it has no arguments table unless the definition adds directives; at minimum -name and -help present cleanly in table and string renderers); the interactive surface is decided, documented and implemented ('i ' or documented equivalent) with behaviour defined for the name-collision case (a namespace that is both a documented package and an ensemble command); the four moduledoc (package) ids (iocp, parser, tkcore, tzint) and at least one template-created module's id render through the new surface; the template's (package) block is verified as-written (or minimally corrected in step, with the template version bumped per its conventions); discoverability exists in some listed form (e.g ids matching (package)* via an existing query/listing command - decided in the work); new tests cover lookup, rendering and the interactive surface; full punk::args and punk::ns suites pass. + +## Context + +User context 2026-07-13: the (package) ids were intended somewhat as the surface for +package-level documentation/guidance but "aren't yet surfaced to the user"; they come +from the module template, so most modules created with 'dev module.new' carry one. + +Probed state (2026-07-13, tclsh 9.0.3): 45 modules under src/modules declare +@id -id "(package)" blocks with an @package -name/-help directive +(template_module-0.0.4.tm carries the canonical block). They are currently inert: + +- punk::args::id_exists "(package)punk::args::moduledoc::parser" returns 0 even with + the package loaded and registered. +- The lookup emits: warning: update_definitions received unqualified ns: + (package)punk::args::moduledoc - real_id derives a namespace from the id's + qualifiers, and only the (autodef) prefix is special-cased/stripped; the (package) + prefix flows into the namespace name. +- The resolver itself understands the @package directive (the spec dict carries a + package_info key alongside cmd_info/doc_info) - the gap is lookup and surfacing, + not definition storage. + +The immediate motivation is the guidance-space discussion (recorded in G-055 and the +punk::args 0.11.1 define doc): system-wide authoring mechanics now live in the +punk::args::define help, and per-package conventions (harvests, provenance, version +adaptivity of a moduledoc) belong with the package - @package -help is the declared +place, once reachable. + +## Approach + +- Lookup: extend the prefix handling where namespaces are derived from ids + (real_id/update_definitions) so "(package)" is recognised like "(autodef)" - + the namespace for scan purposes is the id minus the prefix. Verify tail-colon + handling ((package) ids name namespaces, not commands - the id has no command + tail). +- Rendering: punk::args::usage on a (package) id - drive the existing arg_error + machinery with package_info (title/name/help; no Arg table rows unless the + definition declares arguments). Check interaction with the synopsis section + (suppress or render a package-appropriate header). +- Interactive surface: punk::ns::cmdhelp fallback - when the query word is not a + command but matches a documented package/namespace, present the package page. + Collision rule (documented): a real command (e.g an ensemble named for the + namespace) wins; the package doc is reachable explicitly (spelling decided - + e.g 'i (package)foo::bar' at minimum). +- Discoverability: a listing of documented packages (existing id query/listing + machinery filtered on the prefix, or a punk::args::status extension). +- Template: verify the template block round-trips through the fixed path; the + moduledoc (package) blocks likewise (tclcore notably has none - adding one is + a natural but optional step recorded either way). + +## Notes + +- Related: G-055 (per-package conventions/provenance belong in @package -help once + surfaced; its workflow doc should point there when this lands), G-042 (subshell + help topics - adjacent help-surface work; keep the surfaces consistent), + G-017/G-068 (package-level documentation consumers). +- The punk::args::define help (0.11.1) documents registration styles and defspace + rules system-wide; this goal's surface is where the per-package layer of that + guidance becomes reachable. +- 45 declaring modules found 2026-07-13 via grep for '"(package)' under src/modules + (plus decktemplates vendor copies); count will drift - the acceptance names the + four moduledocs + one template-created module as the proving set, not all 45.