How CodeGraph works
Parse the estate into a typed graph, then run deterministic analyses. No LLM sits in the critical path.
The pipeline runs Fixture estate, then parse (COBOL, copybooks, JCL, DB2 DDL), then build a typed knowledge graph, then transitive-closure impact plus provenance, then the deterministic analyses, then an audit and evidence export, then the interactive dashboard. On load the app runs this live over Server-Sent Events, so each stage narrates with its real measured latency in a console, panels fill progressively, and a persistent stage rail lets you open any stage's Input, Processing, and Output trace. A single control replays the whole run.
The typed knowledge graph
Built with networkx and held in-memory plus SQLite, the graph has seven node types (program, copybook, variable, table, jcl, dataset, and an unresolved placeholder) and typed edges such as DEFINES, IMPORTS, REDEFINES, CONTROLS_TYPE_OF, WRITES_VAR, REFERENCES, CALLS, READS and WRITES, EXECUTES, USES_DATASET, and PRECEDES. On the shipped fixture the graph has 47 nodes and 70 edges: 14 programs, 5 copybooks, 17 variables, 3 DB2 tables, 3 JCL jobs, 4 datasets, and 1 unresolved node.
Four deterministic analyses
These are plain graph algorithms, not model calls, so the same fixture yields the same result every run.
1. Impact closure with provenance
The transitive dependency slice of a change, with each edge carrying its file:line source, so you can see not just what is affected but where the evidence lives.
2. Naive versus graph recall
The graph's closure scored against the fixture's known ground-truth dependency set, versus a simulated single-file window, which is what a text-based tool actually feeds a model.
3. Extraction sequencing
A coupling and blast-radius score per program (coupling weighted three, COMP-3 traps weighted two, JCL criticality weighted two, unresolved calls weighted five) that ranks a safe strangler-fig migration order.
4. Dead-code reachability and completeness gate
Every PERFORM, CALL, COPY, and DB2 reference must resolve or be flagged as needs review, never silently dropped. Unreachable paragraphs are reported as an illustration, not scored as a headline metric.
One toggle makes the difference tangible. Tick the naive AI context view and the graph dims to the single source file with a few lines of context. Six of the nine wire-transfer facts vanish, a red banner states the consequence, and flipping back restores 9/9 with receipts. That toggle is an illustration of what context the retrieval layer must supply, not the source of value.
When you are done, Export JSON writes a migration-evidence.json file, and Evidence report renders a printable Codebase Topology and Completeness Report: the node and edge summary, per-module closures with file:line provenance, the recall result and method, the ranked extraction sequence, the dead-code list, and a timestamp. We position that as a DORA ICT-asset inventory and a SOC-2 change-control receipt. An optional Pydantic-AI layer can answer questions over the closure, but it is off by default and key-gated, and the deterministic demo records the result without any key.
