feat(ast): extract static Tcl Ruff documentation #1678

Objective

Extract source-visible Ruff! documentation for Tcl procedures and methods without runtime introspection.

Umbrella: #1654 · Planning ID: D21
Completion prerequisites: D25: #1662, D26: #1663

LANG coverage: Tcl.

Development can start after D05/D06 interfaces exist. Completion is blocked by D25/D26 infrastructure and requires this adapter's own conformance cases, scaling probes for new work and fuzz seeds.

Shared architecture and constraints

Follow the umbrella's shared contracts. AST recognition serves two consumers: exact legacy convention/coverage streaming for root LOC, and richer source documentation for owner lookup and local text. Source attachment, profile eligibility and physical metric ownership are separate. Preserve the legacy candidate view before run selection, original emission timing, and metrics-only early exits.

Documentation fragments, logical documents and convention-qualified owner edges have separate identities. Source offsets refer to the actual parsed buffer and included ranges. The index is caller-owned, immutable and source-bound; lookup validates tree/index identity. Complete text means local decoded/cleaned content with forward source mapping, not inherited or generator-expanded documentation.

Implementation touchpoints

• big-code-analysis-ast/src/lang_helpers/tcl_family.rs: script/literal slot classification and memoization.

• big-code-analysis-ast/src/roles/tcl.rs: current shared role recognition; read the contributor reference in roles/mod.rs.

• big-code-analysis-ast/src/roles/doc_tests/: existing per-language recognition fixtures; add independent owner/text expectations.

• big-code-analysis-ast/src/lang_helpers/tcl.rs

• big-code-analysis-ast/src/checker/tcl.rs

• big-code-analysis-ast/src/documentation Tcl adapter

Implementation steps

• Re-derive Ruff comment boundaries against fix(tcl): a \-continued comment parses its next row as code #1802 and current argument-slot memoization; record any separately required grammar dependency rather than hiding it in the adapter.

• Recognize leading procedure/method-body comment blocks and #ruff continuation blocks using exact Ruff! boundaries.

• Resolve static proc/TclOO method/constructor forms using command roles rather than fixed child offsets.

• Support the source-visible namespace/class forms selected in D01; computed preambles and runtime hooks remain explicit unavailable evidence.

• Preserve nested scope, blank-line and command-boundary rules; provide local comment text and mappings.

• New extraction conventions do not automatically alter existing DLOC.

Tests and edge cases

• # comment ending in backslash followed by text/proc-like source, CRLF bare continuation, marked #ruff continuation and malformed argument lists with mixed script/literal roles; assert no fabricated concrete owner.

• Leading blank rows before docs versus a source blank row ending a block; blank comment rows inside docs.

• Later ordinary comments excluded while explicit #ruff blocks join under the profile.

• Procedures, methods, constructors and nested command bodies with differing owner names.

• Dynamic declaration names/preamble hooks, comment-looking strings and #ruff outside supported scopes.

• Two unrelated valid docs survive a malformed neighbor; precise source ranges and provenance.

Use independently specified expected owners, fragment counts/order, byte ranges, text and availability. Pair them with separate legacy metric assertions where relevant. Do not sort/trim observed results, rely only on facade/delegate equality, or accept generated snapshots without an expected-value anchor. Use verbatim source for EOF/CRLF cases. Perturb the decision-bearing expression and confirm the intended assertion fails; use the maintained utils/perturb.py only on tracked, clean targets, recording or stashing real work first. Multi-target cargo runs require --no-fail-fast; include the mutated crate and dependent crates before claiming a unique guard. Keep irreproducible fixtures/manifests in tests, maintained utils or an issue attachment, following .claude/rules/temp-files.md.

Acceptance criteria

• Static Tcl procedure/method ownership and nonempty text meet the inventory.
• No runtime execution or guessed dynamic owner.
• Command/scope probes and Tcl seeds pass with preserved legacy metrics.

Verification and completion evidence

• Follow current role-census/role-coverage/role-bypass requirements and applicable role-parity-corpus checks. Preserve independent semantic fixtures; refresh .role-coverage-observed.txt when any sampled corpus gitlink changes.

• Put revisions, exact commands, tool versions and durable input links beside parity/coverage claims; host-local evidence paths are not citations.

• Recheck current source and the prerequisite contracts/baseline applicable to this issue; record intentional changes to the premises.

• Run focused production-path tests and affected language siblings. Use package-isolated -p big-code-analysis-ast / -p big-code-analysis feature builds; workspace feature unification is not isolation.

• Run the repository's required checks for the touched surfaces. For implementation changes: make worktree-setup, make pre-commit read from its BCA_GATE: verdict, and relevant test-language membership comparison. Add scaling and chain-audit checks for traversal changes; run make fuzz-check and seed replay for fuzz changes.

• Record exact test/perturbation/probe evidence in a completion comment and update this body. Review unexpected metric drift before snapshot acceptance; follow baseline and integration-submodule discipline if behavior deliberately changes.

• Land public API documentation, re-export/stability review and changelog entries with the originating API change. Keep unrelated CLI/web/Python surfaces outside this issue unless explicitly listed.

Revalidation against main (2026-11-04)

Source baseline inspected: 07822c69211fe851c452ac6c0ebbd99cf92589a5. Relevant landed work: PR #1689, PR #1717, PR #1775, PR #1804. These are implementation updates to the existing acceptance criteria; this review does not mark extraction work complete.

• Tcl braced-word/body/argument classification already has a per-word_list memo and visited-node word cache. Use roles/tcl.rs plus lang_helpers/tcl_family.rs with for_walk context; derived queries must preserve caches.

• fix(tcl): a \-continued comment parses its next row as code #1802 is now a concrete source-extraction hazard: a backslash-continued comment's next text row is parsed as a command, and some CRLF continuations become words. A Ruff block must not attach to a fake declaration or stop at a false boundary.

• Keep this issue open until it either consumes a landed grammar repair or supplies an explicitly bounded source-aware projection with uncertainty for unsupported cases. Do not silently reinterpret every command after a comment. The root's bare-gap CLOC fix alone does not solve textual continuation.

• Root metric gap scanners are not an AST dependency. LF, raw CRLF and normalized file inputs need separate expectations.