feat(index): resolve cross-file references via a project-wide symbol table

[r0h1tb]

Refs #35

This is the step-4 work I proposed in my analysis on #35 — the piece that turns the call graph from "same file only" into something usable.

Stacked on #50. That PR fixes for n in [], without which no CALLS edge is emitted at all and none of this is observable. Review #50 first; this branch contains it.

Problem

EdgeExtractor.extract_edges resolved references against:

name_to_id = {n.name: n.id for n in nodes}

nodes is the node list for the file currently being parsed, so a callee defined in another file was never in the map and the edge was dropped.

I sized the gap using ground truth from parsers with no shared code with tree-sitter — Python's stdlib ast here, and javalang on a Spring Boot service — so the system isn't graded against its own output:

codebase	intra-file calls	cross-file	unreachable
this repo	507	2,521	83%
Spring Boot service	116	2,063	95%

In layered Java (controller → service → repository) essentially every interesting call crosses a file, which is why the Java number is so stark.

Approach

Indexing becomes two-phase:

1. Collect — parse every file, extract nodes, build a project-wide name -> id map
2. Resolve — walk the parsed files again, extracting edges against that map

extract_edges takes an optional global_symbols, and the local map is applied last:

name_to_id = dict(global_symbols or {})
name_to_id.update({n.name: n.id for n in nodes})

so a file-local symbol always shadows a same-named symbol from elsewhere. Omitting global_symbols preserves the old behaviour exactly, so index-folder and any other caller are unaffected.

First definition of a name wins in the global map, and files are walked in a stable order, so the choice is deterministic across runs.

Results on this repo

	before	after
CALLS edges	498	1,412
of which cross-file	0	914
total edges	2,387	3,782

Retrieval quality over the 15 most-called symbols, scored against the stdlib ast oracle across all call relationships rather than just same-file ones:

symbol                      expected   raged      P      R     F1
run                               93      93   1.00   1.00   1.00
session                           82      82   1.00   1.00   1.00
_make_sentinel_tree               37      34   0.97   0.89   0.93
ParserManager                     34      34   1.00   1.00   1.00
ASTEdge                           25      15   1.00   0.60   0.75
...
MEAN                                           0.99   0.95   0.97

Precision holding at 0.99 is the load-bearing result. Name-based global resolution could plausibly have produced false positives across same-named symbols in different files; on this codebase it does not. run and session are heavily cross-file and both score 1.00.

Recall isn't 1.00 — ASTEdge at 0.60 is the weakest. Those are attribute-style call sites the calls query doesn't capture, which is a separate gap from resolution and I left it alone.

Known limitation

Resolution is by bare name, not qualified name. Two distinct Config.load() in different modules will collapse to whichever was indexed first. That didn't bite on this repo (precision 0.99), but it will on a codebase with heavy name reuse.

The principled fix is qualified-name resolution with a bare-name fallback, plus a lower confidence on fallback matches — the edge model already carries confidence. I've deliberately not done that here so the change stays reviewable and the measurement stays interpretable. Happy to follow up if you want it before this lands.

Tests

4 in tests/test_global_symbol_resolution.py: the unresolved baseline, cross-file resolution, local-shadows-global, and that an unrelated global table leaves same-file behaviour byte-identical.

Verification

pytest tests/          3 failed, 188 passed, 1 xfailed
ruff check             All checks passed!

Baseline on main is 3 failed, 174 passed — same three pre-existing failures (fixed in #51), plus the new tests.

CI will be red at Lint with ruff until #51 lands; that's the pre-existing breakage, not this change.

[r0h1tb]

Rebased onto current main. Two things worth flagging, since the rebase wasn't purely mechanical:

1. I resolved a real conflict in ast_rag/cli.py, and it changed the code. This branch still drove the index loop with console.status(...), but #54 landed _index_progress() progress bars on main in the meantime. I kept main's progress bars and put the two-phase index inside them, rather than reverting #54's UI. I also converted this PR's second phase (reference resolution) from console.status to the same progress bar — resolution is exactly the kind of multi-minute phase #54's docstring says should report count/elapsed/ETA, and having phase 1 be a bar and phase 2 a spinner would have looked broken. Shout if you'd rather I left phase 2 as a spinner.

2. ruff format wanted one change in ast_rag_api.py (argument wrapping in the call_kinds commit). Amended in, so --check is clean.

Verified locally against main (6f71a9b):

	main	this branch
ruff check / ruff format --check	pass	pass
pytest tests/	209 passed, 1 skipped, 1 xfailed	216 passed, 1 skipped, 1 xfailed

The +7 are this PR's tests/test_global_symbol_resolution.py. Nothing pre-existing changed state.

Note on ordering: #60 is stacked on this branch, so this one should go in first.