fix: make C++ semantic frontend setup actionable

[alloutflo]

Summary

• add a supported cpp extra that installs libclang
• emit actionable, once-per-updater fallback diagnostics for missing libclang and missing compile_commands.json
• include the resolved C/C++ frontend in the parser fingerprint so installing the extra invalidates stale incremental graphs
• document installation, frontend modes, compilation-database setup, and fallback behaviour

Type of Change

• Bug fix
• New feature
• Performance improvement
• Refactoring (no functional changes)
• Documentation
• CI/CD or tooling
• Dependencies

Related Issues

Fixes #1177

Test Plan

• Unit tests pass (make test-parallel or uv run pytest -n auto -m "not integration")
• New tests added
• Integration tests pass (make test-integration, requires Docker)
• Manual testing (described below)

Validation performed:

• python -m pytest -q codebase_rag/tests/test_cpp_frontend_*.py codebase_rag/tests/test_parser_fingerprint.py (58 passed)
• pre-commit run --all-files
• uv lock --check
• mkdocs build --strict
• uv build --wheel
• installed the built wheel with [cpp] into a fresh temporary Python 3.12 environment and successfully created a clang.cindex.Index

The full non-integration and Docker integration suites were left to CI; the local regressions cover packaging metadata, both fallback diagnostics, frontend availability changes in the parser fingerprint, and the existing compile-database/hybrid frontend paths.

Checklist

• PR title follows Conventional Commits format
• All pre-commit checks pass (make pre-commit)
• No hardcoded strings in non-config/non-constants files
• No # type: ignore, cast(), Any, or object type hints
• No new comments or docstrings (code should be self-documenting)

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4c22548f-ac36-4498-9a76-dc3c3dc51b30

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}