feat(ast): extract Csharp XML declaration documentation #1667

Objective

Associate C# documentation comments with source declarations while preserving XML markup and existing trivia rules.

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

LANG coverage: Csharp.

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/csharp.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/csharp.rs

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

• src/metrics/loc/dloc.rs

Implementation steps

• Resolve C# owners through role/context projections while preserving accessor gating and the existing leading-trivia selector.

• Cover documented types/delegates, methods/constructors/destructors/operators, fields/events/properties/indexers and enum members.

• Reuse leading-trivia selection around attributes/directives and normalize owners for expression-bodied and signature forms.

• Preserve XML as local text with mappings; inheritdoc/include references are not expanded.

• Record the fix(loc): tool-vs-bca doc-comment attachment divergences left by #1613 #1646 conditional-member case as an explicit profile/legacy decision with concrete evidence, not an incidental metric fix.

Tests and edge cases

• Both indexer/property body forms, getter/setter trivia, gated-out opener candidates and accessor-search counters; each must assert exact owners as well as legacy rows.

• Attributes before/after comments, ordinary trivia separating doc blocks, line/block forms and joined runs.

• Expression-bodied property/indexer/operator and constructor/destructor owners.

• Accessor and function-body placements that current rules exclude.

• Doc before #if with candidate members; exact owner or uncertainty and legacy reading.

• XML with code examples/escaped markup/empty summary; inheritdoc remains literal.

• Same-row owners, EOF/CRLF and explicit source mapping; perturb leading-trivia guards.

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

• Owner and XML local content expectations are independent from row metrics.
• Existing C# DLOC behavior preserved unless a separately documented correction is approved.
• Trivia-width/depth probes and representative fuzz seeds pass.

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

• C# role rows now encode candidate targets, gated FuncOpener/Member behavior and residual HoldsDocInBody. Preserve row-before-callable ordering where it avoids repeated accessor searches.

• The role-series test retirement briefly omitted expression-bodied indexer coverage from its replacement corpus. Keep both accessor-bodied and expression-bodied properties/indexers in this issue's own fixtures; a derived parity pass over one form does not cover the other.

• refactor(roles): rename HoldsDocInBody or declare the full set and subtract in the Checker #1797 is an open residual-row modeling decision. Use the current full Checker composition and explicit XML-documentation semantics, not the residual row alone.