🧪 Capture marker scope association in the declarative extraction fixtures

[ubmarco]

Marker scope association — which declaration a marker attaches to — is computed by
find_associated_scope and flows into the real output, but the shared declarative fixture
harness captured nothing scope-derived, so it had no coverage in the fixture layer at all.

While fixing that, the harness turned out to be snapshotting a test-only projection of
the output rather than the output itself: filepath, remote_url, the full source_map
(columns and end positions), the type discriminator and the marker were all untested,
and only the start row survived as a synthetic line key. So this PR does both: it adds
scope coverage, and it makes the snapshots hold the real production shape.

Deliberately scoped to the existing languages so it can merge independently of the
in-flight TypeScript work; ts/tsx fixtures follow separately.

What changed

The snapshots are now the real output. Each case snapshots exactly what
SourceAnalyse.dump_marked_content() would write — the flat list of Metadata.to_dict()
dicts, sorted by (filepath, source_map.start.row) as production sorts it, built from the
same all_marked_content list production uses. Nested need payload, links as a bare
list, tagged_scope as the plain full-text string, type with its production spelling.

Two deviations, both documented in the harness and the README:

• filepath is relative to the test root (production emits an absolute path, which differs
  per run and per machine).
• tagged_scope_type is appended as an additive, test-only key — the associated node's kind
  is not in production output, but it is cheap, deterministic, and the only thing that makes
  "same construct across languages" answerable.

Warnings are a second artefact, not a key in the data. Production writes them to their
own file via dump_warnings() (with a matching load_warnings() for external consumers)
and echoes them to the console — independent of marked_content.json. The fixtures mirror
that separation: a sibling …[warnings].json snapshot per case.

New tests/data/extraction/scope.yaml — 23 cases across cpp, python, csharp, rust, go,
bash and yaml: marker above a function, marker inside a body (the enclosing-scope fallback),
no-scope, the python docstring path (which uses find_enclosing_scope rather than
find_next_scope), and yaml's bespoke structure finder for inline-same-row, leading
key/value and leading list-item association.

jsonc is intentionally not covered: its association goes through a separate bespoke finder
and belongs with a decision about data-format association generally.

Verification

• tox -e py312-sphinx8-needs5: 368 passed, 1 skipped, 155 snapshots (74 data + 74
  warnings artefacts; case count unchanged by the shape conversion)
• tox -e docs-clean: no new warnings
• pre-commit and mypy clean
• One snapshot was diffed field-by-field against a real dump_marked_content() run on the
  same source: identical keys in production's own order, identical values

What the fidelity increase surfaced

Snapshotting real positions exposed three pre-existing position defects that the reduced
shape could not show. None are fixed here — this PR deliberately only changes tests:

1. Need-ref columns are shifted. extract_marker computes start_column from the
   pre-.strip() offset but end_column from the post-.strip() length, so every
   need-ref's span is offset by the stripped whitespace. Visible in every need_refs
   snapshot.
2. Multi-line @rst blocks have a broken source_map — start.row == end.row, with
   raw offsets into the flattened comment text used as columns. Single-line RST is fine.
3. Columns are relative to the comment token's text, not the physical line, so an
   indented marker reports a column that is not its column in the file. Only became visible
   once an indented fixture case existed.

Anything consuming source_map for a need-ref, a multi-line RST block, or an indented
marker — source links, "go to code" — is working from wrong positions today.

Follow-up

Every libclang-engine case captures tagged_scope: null, because the preprocessor-aware
path nulls it outright. That looks wrong rather than intentional: libclang decides only
whether a marker is active, not which declaration it belongs to, so those markers should
carry the same scope as the tree-sitter path. Tracked separately — the fixtures now make
the gap visible instead of invisible.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 90.90909% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.37%. Comparing base (f373b3a) to head (c1542c3).

Files with missing lines	Patch %	Lines
tests/conftest.py	0.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #100      +/-   ##
==========================================
- Coverage   92.38%   92.37%   -0.01%     
==========================================
  Files          43       43              
  Lines        3743     3740       -3     
  Branches      381      381              
==========================================
- Hits         3458     3455       -3     
  Misses        172      172              
  Partials      113      113              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.