docs(traceability): trace the preprocessor-aware C/C++ engine

[ubmarco]

Follow-up to #97. Adds the traceability artifacts for the substantial features that landed since 1.3.0 without any.

Audit

Every merged PR in the 1.3.0 → 1.4.0 window, checked against features.rst and the @ markers in src/:

PR	Substantial feature?	Traceability
#92 Bash language support	yes	✅ FE_BASH + FAULT_BASH_1/2 + IMPL_BASH_1/2/3 + added to IMPL_LANG_1
#85 Preprocessor-aware C/C++ engine (libclang)	yes	❌ none — no feature need, no markers
#89 Marker anchoring fix	no (fix to existing traced code, IMPL_OLP_1)	n/a
#83 Declarative fixture tests	no (test infra, no src/ change)	n/a
#84 / #86 Dependency caps	no	n/a

So the libclang engine was the one gap: 4 new modules and 353 lines in analyse/preproc/, plus wiring in analyse.py / config.py / cmd.py / src_trace.py, with zero traceability.

Changes

docs/source/components/features.rst — new FE_PREPROC feature need, placed after the language-support block, with three fault children:

• FAULT_PREPROC_1 — objects in inactive branches are extracted (false positives, the defect the engine exists to prevent)
• FAULT_PREPROC_2 — objects in active branches are dropped (false negatives)
• FAULT_PREPROC_3 — flags resolved from the wrong compilation database entry, so the wrong branches evaluate as active

Six @ markers, one per capability listed in the need, so the mapping is 1:1 and reviewable:

Marker	Site	Capability
IMPL_PREPROC_1	analyse.py::create_src_objects_libclang	engine entry / opt-in
IMPL_PREPROC_2	preproc/libclang_parser.py::extract_active_comments	drop inactive-branch comments
IMPL_PREPROC_3	preproc/compile_db.py::find_compile_db	walk-up database discovery
IMPL_PREPROC_4	preproc/compile_db.py::load_flags_map	per-file compiler flags
IMPL_PREPROC_5	preproc/compile_db.py::defines_to_args	standalone header parsing
IMPL_PREPROC_6	preproc/loader.py::load_clang_cindex	optional-dependency guard

Comments only — no logic touched.

Verification

A green -nW build alone would not prove the markers work: a marker that fails to parse produces no need and no error. So the built output was checked directly.

$ tox -e docs-clean          # sphinx-build -nW --keep-going
build succeeded.

$ grep -o 'id="IMPL_PREPROC_[0-9]"' docs/_build/html/development/traceability.html | sort -u
id="IMPL_PREPROC_1" … id="IMPL_PREPROC_6"        # all six needs materialized

$ grep -o 'href="[^"]*#FE_PREPROC"[^>]*title="IMPL_PREPROC_[0-9]"' … | sort -u
IMPL_PREPROC_1 … IMPL_PREPROC_6                  # all six link to the feature

• tox -e py312-sphinx8-needs5 — 345 passed, 1 skipped, 58 snapshots passed
• tox -e mypy — no issues in 20 source files
• pre-commit run --files … — all hooks pass

Deliberately out of scope

Pre-existing gaps, all predating the 1.3.0 → 1.4.0 window this PR was scoped to. Flagging rather than fixing, since each is a separate judgment call:

• FE_CSHARP is an orphan. It has no incoming impl link — it is missing from the IMPL_LANG_1 list in analyse/utils.py:110 even though init_tree_sitter handles CommentType.cs (utils.py:122). C# is the only supported language whose implementation is untraced. One-word fix if you want it here.
• No feature need for the src-trace directive, nor for source-link URL generation (local-url / remote-url), while the CLI has three (FE_CLI_*). This asymmetry may be intentional — capability-level needs covering what is traced regardless of interface — so changing it is a feature-model decision, not a gap fix.
• The test-needs layer is empty. docs/ubproject.toml defines a test type and development/traceability.rst runs a src-trace over the tests project, but tests/ carries no @ markers, so zero TEST_ needs exist.

Note on sequencing

No changelog entry here, deliberately: this PR is based on main, where the Unreleased heading still holds the Bash entry that #97 converts into the dated 1.4.0 section. Editing it would conflict with the open release PR. Since these artifacts document a feature already listed in the 1.4.0 notes, either fold a line into #97 before merging it, or let the next release's notes pick this up — your call on the order.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.38%. Comparing base (935d8df) to head (f99ab61).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #98   +/-   ##
=======================================
  Coverage   92.38%   92.38%           
=======================================
  Files          43       43           
  Lines        3743     3743           
  Branches      381      381           
=======================================
  Hits         3458     3458           
  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.