testgraph

testgraph is a journey-level test selector. Given a git diff, it answers which user-facing flows a change could have broken and in what order they should be tested, returning a short ranked list rather than a directive to re-run everything. It deliberately does not drive browsers, generate tests or self-heal; its stated job is the layer above existing drivers, namely deciding what is worth testing. How it works A journey registry names each user journey and its entry symbols, such as route handlers or a scheduler sweep. The propose module drafts a registry for a new repo by scanning Python route decorators and Next.js conventions against the index, marking it approved false until a human reads it, so an unapproved registry runs loudly but never silently. For a diff, testgraph maps changed line ranges to the symbols that own them, the seeds; walks the CodeGraph edge graph in reverse, transitively, to every symbol that depends on a seed, the impacted set; and reports the journeys whose entry symbols fall in that set, ranked by fan-in, each carrying the confidence of the strongest edge path that reached it. Confidence is the maximum over paths of the minimum over edges, so a chain is only as trustworthy as its weakest hop while one solid route is enough. A journey reached only through weak or synthesized edges is flagged for manual verification rather than silently trusted, and is never removed from the selection. The tool is recall-first: it prefers over-selection to silently dropping a journey a change really did affect. Before answering, an integrity guard refuses to run off a corrupted or stale CodeGraph index, since a wrong graph produces a confidently wrong answer. Registry resolution searches, first hit wins: an environment variable escape hatch, then a .testgraph/journeys directory inside the repo, described as the recommended location, then a journeys directory beside the package in the project's own checkout. A registry is matched on its self-declared target rather than its filename, in every location, and one copied from another project and left unedited is refused. Prerequisites and install Python 3.11 or newer using the standard library only, with no third-party dependencies; git for diff input; and a target repo with a CodeGraph index produced by codegraph init. Install from PyPI with pip install testgraph. The wheel ships the package alone, while the measurement harness and the dogfood registries live in the repository. CLI and MCP Command-line entry points include select, with human-readable or JSON output intended for a CI gate or another agent; export, which writes a static journey map an agent reads pre-commit; propose; record; and a summary mode. The MCP stdio server exposes two tools, testgraph_impact and testgraph_journeys, and is registered per repo. It is stdlib-only and imports the analysis modules lazily, so an idle server has not loaded sqlite3, holds no database connection and keeps no index in memory. The README reports 15.2 MB RSS measured after a full handshake, against 62 to 69 MB for a typical Python MCP SDK server. Wiring and the ledger hooks/install.sh installs a pre-push hook into every repo with an approved registry, so each push prints the journeys it could have broken. The hook runs codegraph sync first, because seeds come from line ranges and an index built before the code moved would resolve a diff against stale spans; if a changed file's bytes still disagree with the indexed copy, the answer degrades and names the file. The hook never fails a push, with every path exiting zero, and can be disabled per repo with a git config setting or removed with an uninstall flag. Each run appends one selection row to a JSONL ledger; the record command writes the other half, what running a journey found, so the two joined on repo and commit can count a journey that failed on a commit whose selection did not name it, described as a silent under-selection. Status It is described as a phase-1 spike plus confidence-weighted paths, working and validated on one dogfood target: recall 1.00 across five hand-labeled commits with mean precision 0.68, and 1.00 across twenty seeded mutation sites scored against an independent AST oracle, with the integrity guard tested and schema-pinned. The scope is that single target, analysing backend and frontend files with journeys registered on backend entry points. The README also records that later measurement on two repos without a registry falsified the earlier savings claim: at 23 journeys one repo gave a histogram of zero journeys for 38 commits and 23 for 2 commits, and at 207 journeys another avoided only 54.1 percent of journey-runs once commits touching no registered surface were excluded, so the selection numbers should be read as a floor on coupling rather than a promise of savings. The same measurement did confirm the ranking, with a false-positive whole-registry selection flagged for manual verification at confidence 0.3 while a genuine large blast radius came back clean at 0.9.