The command line
01cartograph . · trace · blast · diff
What a repository contains, how one relationship crosses the stack, what depends on an artefact, and what a change did to the architecture.
+Command-line referenceCartograph reads a repository’s TypeScript, TSX and Python — symbols, imports, calls, HTTP requests, route declarations and ORM models — and joins them across languages that share no symbol table. One analysis core serves a CLI, a desktop application, an MCP server and a pull-request review workflow.
+Read the writeup1994
One file. One language.
You could read the whole program.
C:\> edit hello.c
#include <stdio.h>
int main(void) {
printf("hello, world\n");
return 0;
}
C:\> cc hello.c && hello
hello, world
2004
A page and a server.
2014
Then services, APIs, frameworks.
More than one language in one system.
Today
One request crosses three languages.
An import graph tells you which files import which. It doesn’t tell you what a request reaches.
Illustrative example, from the README
Surfaces
cartograph . · trace · blast · diff
What a repository contains, how one relationship crosses the stack, what depends on an artefact, and what a change did to the architecture.
+Command-line referenceTauri · Sigma
Draws the architecture graph and shows the evidence behind any edge.
+The desktop boundarymap · trace · blast · diff
An MCP server exposing the same graph over one repository identity, granted when it is launched.
+MCP boundary and authorizationcartograph diff --markdown
A workflow that posts what a change did to the architecture as a pull-request comment. It is configured for this repository’s own pull requests; no reusable action is published.
+cartograph diffOpt-in per repository
Explains already-derived evidence, and every claim must cite that evidence verbatim. No in-product way to supply an API key ships yet, so in practice it shows the evidence unexplained.
+The citation contractHow it works
tree-sitter reads TypeScript, TSX and Python: symbols, imports, calls, HTTP requests, route declarations, and ORM models with the tables they name. Only the source under the path it is given — not Git history, not a database.
Dynamically built URLs are partially evaluated, four route-declaration dialects are normalised to one shape, client calls are matched to the handlers that serve them, and models to their tables. Every stage is deterministic.
Every edge carries its provenance, a confidence and the evidence for it. An ambiguous match produces no edge; a segment that cannot be determined statically stays {unknown}.
Real output
POST /api/v2/connections/enqueue-test matched POST /api/v2/connections/enqueue-test at …/routes/public/connections.py:383 (enqueue_connection_test); exact HTTP method; every path segment static and equal
cartograph trace enqueueConnectionTest on Apache Airflow at 9b43d6a. Directory paths are shortened to “…”; everything else is verbatim. Select a hop to read its evidence. $ cartograph trace enqueueConnectionTest enqueueConnectionTest (function) .../ui/openapi-gen/requests/services.gen.ts:834 │ ↓ HTTP-CALL confidence 0.98 provenance route-matcher │ evidence POST /api/v2/connections/enqueue-test matched POST /api/v2/connections/enqueue-test │ at .../routes/public/connections.py:383 (enqueue_connection_test); │ exact HTTP method; every path segment static and equal │enqueue_connection_test (function) .../core_api/routes/public/connections.py:383 │ ↓ ORM-ACCESS confidence 0.80 provenance orm-resolution │ evidence ConnectionTestRequest(...) in enqueue_connection_test at .../connections.py:427 │ConnectionTestRequest (class) .../airflow/models/connection_test.py:82 │ ↓ QUERIES confidence 0.80 provenance orm-resolution │ evidence ConnectionTestRequest maps to table "connection_test_request" │connection_test_request (table) This path crosses the HTTP boundary and reaches a database table.An HTTP boundary, a Python handler and a SQLAlchemy model, with no shared symbol table — and every hop carries the evidence for itself.
+How the resolver worksMeasured
14,932 edges labelled. One false positive.
One false positive among 11,221 independently verified edges. 24.9% (3,711) could not be verified from source, and they concentrate where evidence is weakest — so every figure is an upper bound.
Confidence values are uncalibrated priors, not probabilities.
Calibration error 0.18, toward under-confidence. They must not be thresholded as if they were probabilities.
Recall was measured in one repository, inside a stated scope. It is not recall across the corpus and must not be quoted as such.
Principles
A plausible-looking guess is worse than a gap, because it is indistinguishable from a derived fact. Where the evidence is thin, Cartograph refuses. Contributions are welcome — real repositories that break the resolver most of all.
+Contributing guideNo language model constructs graph structure — not as a fallback, not as a hint, not behind a flag. A model may explain a finished subgraph, and nothing else.
ADR-0007 →Ambiguous candidates produce no edge, a prefix that cannot be determined statically stays {unknown}, and a call to an absolute host is never joined to a local route.
Matching →Cartograph stores the claim and how it was known. The domain model will not construct an edge without its provenance, confidence and evidence.
ADR-0004 →No accuracy or performance claim without a benchmark run on this codebase, and failures are published alongside successes.
Benchmarks →No source code leaves the machine. AI is opt-in per repository and off by default; Cartograph is fully useful with no API key and no network.
Security →Corpus