feat(ast): extract TypeScript and TSX documentation associations #1670

Objective

Deliver tsc/TypeDoc-informed declaration associations for TypeScript and TSX with precise wrapper ownership.

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

LANG coverage: Typescript, Tsx.

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/roles/typescript.rs, big-code-analysis-ast/src/roles/tsx.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/checker/js_doc_binding.rs

• big-code-analysis-ast/src/checker/{typescript,tsx}.rs

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

Implementation steps

• Normalize export/ambient owners using gated child queries and keep the after_code parameter subset explicitly scoped pending any refactor(roles): decide a Parameter row for the TS/TSX after_code DocTarget subset #1796 decision.

• Support functions/signatures, classes/interfaces, aliases/enums/modules, ambient declarations, supported members and parameters.

• Normalize export/ambient/default-anonymous wrappers while preserving the source binding node and each overload declaration's identity.

• Reuse decorator and leading-comment rules rather than applying JavaScript semantics; cover aliases and TSX-specific node IDs.

• Represent module/packageDocumentation blocks as file documentation and other virtual references per D01.

• Preserve local text/mappings and legacy source-space accounting.

Tests and edge cases

• Documented exported identifier versus undocumented exported destructuring, before/after declare/export, parameter-only after_code cases, and deep ambient/function nests without repeated ancestry scans.

• Comments before versus after export/declare/decorator tokens.

• Anonymous default function/class, namespace and ambient declarations, overload signatures with differing docs.

• Parameter-local docs, enum members and fields; TSX JSX adjacent to documentation.

• @module/@packageDocumentation, references and explicit unresolved targets.

• Markers intentionally differing from JS and assignment/destructuring exclusions.

• TypeScript and TSX each have positive owner/text cases even though one Cargo feature enables both.

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

• Each variant's owners and selection follow its own profile, not a copied JS approximation.
• Wrapper lookup and overload identity are deterministic.
• Feature, metric, scaling and fuzz cases include both variants.

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 #1717, PR #1769, PR #1774, PR #1803. These are implementation updates to the existing acceptance criteria; this review does not mark extraction work complete.

• tsdoc_target must ask the exported declaration's gated row with the child's correct context. R09 caught an in-flight regression where lists_kind let export const {x} = o become documented; preserve that negative fixture.

• The after_code parameter subset is deliberately a consumer projection of DocTarget. refactor(roles): decide a Parameter row for the TS/TSX after_code DocTarget subset #1796 tracks whether a Parameter role is justified; do not reopen every role table solely to remove that exception.

• Ambient/export ancestor queries are now cached GateLane questions. Preserve full bytes/chain and test parameter aliases and TSX independently.

• Doc marker/virtual module text helpers moved to doc_text.rs.