feat(graph): true graph data model (nodes + edges) — closes #8

[Wolfvin]

Summary

Implements issue #8 — replaces the ad-hoc flat-registry graph traversal with a true node + edge graph backed by SQLite. This unblocks structural queries like "who calls this function across the entire codebase", "blast radius if I rename this class", and "circular dependency chains" — engines no longer need to reimplement partial graph traversal logic.

Non-breaking by design. The flat registry tables and JSON files are untouched. All 56 existing CLI commands continue to work unchanged. The graph tables are additive (prefixed graph_ to avoid collisions) and derived from the flat registry during scan.

Files Touched

Created:

• scripts/graph_model.py — New module: schema init, population, BFS queries (query_callers, query_callees), introspection helpers.
• tests/test_graph_model.py — 20 test cases across 6 test classes.

Modified:

• scripts/persistent_registry.py — Calls init_graph_schema(conn) during _init_schema so graph tables always exist.
• scripts/commands/scan.py — Calls populate_graph_tables(workspace, db_path) after the flat backend registry is built. Scan output now includes a graph field.
• scripts/trace_engine.py — Pilot engine migration: trace_symbol is now a dispatcher that picks trace_via_graph (default) or trace_via_flat (fallback). Shared frontend tracing and result assembly extracted to helpers.
• scripts/commands/trace.py — Adds --use-graph (default) and --no-graph flags.
• README.md — Bumped to v8.2, added Graph Data Model to Features, added graph_model.py to architecture tree.
• CHANGELOG.md — Added [8.2.0] Unreleased section with full migration notes.
• references/agent-integration.md — Added section 10.4 "Graph Data Model (v8.2+)" with code examples and a decision table.

Graph Schema

graph_nodes(
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    node_id     TEXT NOT NULL UNIQUE,   -- matches flat registry node "id" (file:line:fn)
    node_type   TEXT NOT NULL,          -- function|class|file|module|route|type|interface
    name        TEXT NOT NULL,          -- symbol name (flat registry "fn")
    file        TEXT,
    line        INTEGER,
    extra_json  TEXT                    -- preserves original "type", "status", etc.
)

graph_edges(
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    source_id   TEXT NOT NULL,          -- references graph_nodes.node_id
    target_id   TEXT,                   -- NULL for unresolved external calls
    edge_type   TEXT NOT NULL,          -- CALLS|IMPORTS|DEFINES|INHERITS|IMPLEMENTS|USES_TYPE
    file        TEXT,                   -- file where the edge originates
    line        INTEGER,                -- line where the edge originates
    confidence  REAL NOT NULL DEFAULT 1.0,
    extra_json  TEXT                    -- preserves "ipc", "via_self", "to_fn", etc.
)

Indexes (6 total): idx_graph_nodes_type_name, idx_graph_nodes_name, idx_graph_nodes_file, idx_graph_edges_source_type, idx_graph_edges_target_type, idx_graph_edges_type.

Node types: function|class|file|module|route|type|interface.
Edge types: CALLS|IMPORTS|DEFINES|INHERITS|IMPLEMENTS|USES_TYPE. Only CALLS is populated in v8.2 (pilot); other types are reserved for future engine migrations.

Test Results

tests/test_graph_model.py — 20 passed in 0.62s

All 20 new tests pass:

• TestSchemaInit (3) — tables + indexes + idempotency
• TestPopulation (3) — population from clean_app fixture, count match, metadata preservation
• TestQueryCallers (3) — direct callers, file/line inclusion, no self-calls
• TestQueryCallees (3) — direct callees, resolved flag, expected callees of main()
• TestRepopulation (3) — no duplicates on re-populate, clear empties both, clear+repopulate restores
• TestTracePilot (5) — A/B parity (up/down/both), dispatcher default, fallback when empty, use_graph=False

Pre-existing test failures (NOT caused by this PR):

• tests/test_hybrid_engine.py — 4 failures (test_query_confidence_without_deep, test_impact_confidence_without_deep, test_ai_format_confidence_distribution, test_dead_code_confidence_fields). These assert confidence fields in hybrid engine output that don't exist on main either — pre-existing issue unrelated to the graph model.
• tests/test_integration.py — Fails due to OOM (rc=137) when scanning /home/z. Pre-existing environment issue.

Pilot Verification: trace --use-graph matches flat output

A/B verified on benchmarks/fixtures/clean_app (31 nodes, 97 edges):

trace_via_flat('get_user_by_id', direction='up',   max_depth=3) == trace_via_graph(...)  # identical chain sets
trace_via_flat('main',            direction='down', max_depth=2) == trace_via_graph(...)  # identical chain sets
trace_via_flat('process_data',    direction='both', max_depth=3) == trace_via_graph(...)  # identical chain sets

The graph path filters std-lib callees the same way the flat path does (via edge_resolver._is_std_lib_method), so chain sets match exactly by (depth, fn, resolved) tuples.

Migration Notes for Engine Authors

The flat registry remains the source of truth during scan. The graph tables are a derived projection. To migrate an engine:

1. Check graph_model.graph_tables_populated(db_path) — if False, fall back to flat (don't hard-fail).
2. Use graph_model.find_nodes_by_name(name, db_path) to find start nodes.
3. Use graph_model.query_callers / query_callees for BFS traversal.
4. Preserve the existing flat-path output shape so callers and formatters don't break. See trace_engine.trace_via_graph for a reference implementation.

Next engine migrations (post-merge): impact, circular, dependents.

Commits

• feat(graph): add graph_model.py with schema + population
• feat(scan): populate graph tables during scan
• feat(trace): migrate trace engine to graph queries (--use-graph flag)
• test(graph): add graph model + trace pilot tests
• docs(graph): update README + CHANGELOG for graph data model

closes #8

[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 failed

Failed conditions
3.3% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud