feat(context): optional LSP-backed find-references under --deep (closes #255)

[Wolfvin]

Approach

When --deep is active and an LSP server is available, context --check trace --direction up (and --direction both) uses LSP textDocument/references as the precision source for callers, annotated trace_source: "lsp". Otherwise (no --deep, no live LSP, or symbol unresolvable) the existing graph path is used unchanged, annotated trace_source: "graph". Zero-config keeps working with no regression and no LSP dependency.

Reuses existing infra only (issue constraint): lsp_client.find_references, hybrid_engine._find_symbol_definition / _find_symbol_char / _filter_external_references. No new LSP plumbing; LSP never becomes a hard dependency.

Changes

• scripts/hybrid_engine.py — new HybridEngine.find_references_for_symbol(): resolves symbol → def (file,line,char), calls find_references(include_declaration=False), filters the def site, returns 1-indexed refs (or None when LSP inactive / unresolved). Never raises.
• scripts/commands/trace.py — execute() applies the opt-in LSP overlay only when deep + direction in (up, both); _apply_lsp_trace_up() rewrites chains.up to LSP entries + trace_source: lsp + graph/lsp_callers_found, else keeps graph. Always cleanup()s.
• trace_engine.py untouched — graph/flat backend + output shape unchanged; the overlay sits at the command boundary.
• docs/design/0255-lsp-find-references.md.

Verification: live vs mock (explicit)

Live-verified (real CLI, this environment):

• No --deep → trace_source: graph, callers found — zero-config unaffected.
• With --deep → lsp_available: true, but the live server returned no usable references for the symbol, so it degraded to trace_source: graph — no hang, no error, exit 0.
• Graceful-degradation live tests (scan a real workspace, trace with/without --deep).

Mock-verified only (NOT claimed live): the LSP happy path (trace_source: lsp with real references). Mirrors #253 / PR #259 — rust-analyzer (only server installed) does not respond to initialize within 60s, so the happy path is covered by mocked create_hybrid_engine / find_references, not a live server.

Test output

tests/test_issue255_lsp_references.py — 8 passed (2 live degradation, 6 mocked happy-path/resolution).

python -m pytest ../tests/test_graph_accuracy_golden.py ../tests/test_issue255_lsp_references.py ../tests/test_diagnostics_command.py -q
21 passed

No regression to the graph trace path (golden accuracy harness green). Pre-existing unrelated failures in test_compact_format.py (search/path-stripping) exist on main and are untouched by this diff (diff is scoped to hybrid_engine.py, commands/trace.py, the new test, and the design doc).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud