stratigraph

Upgrade Spring Boot with your tests as the judge, and map large Java, Spring and Angular codebases with every claim cited.

Website: https://imashishsharma.github.io/stratigraph/ · open source, runs locally

🔁 Upgrade Spring Boot (2.7 → 3.5, 3.x → 4.0)

npx stratigraph upgrade plan --to 3.5               # read-only: what will break, with file:line citations
npx stratigraph upgrade run  --to 3.5 --ai claude-code

OpenRewrite's recipe does most of an upgrade. The upgrade agent handles what it leaves broken.

• Your tests are the judge. It records every test's result before touching the code. A change is kept only if the build gets further and no passing test turns red. Disabling or deleting a test is rejected outright.

• Layered, reviewable commits on a branch of their own: the recipe, exact known fixes, and AI fixes from Claude Code (opt-in). Application code changed to make a test pass is flagged for review.

• It knows when to stop. An authorisation rule or an HTTP contract is never chosen for you. It hands those back in upgrade-report.md with the evidence and the options.

Related MCP server: MCP Spring Boot Toolkit

🗺️ Map a codebase nobody remembers

npx stratigraph scan .        # extract, mine git history, analyse, write the report: one command

• Architecture: deployables, packages and their dependencies, cycles, and C4 diagrams at all four levels.

• Data model: an ER diagram from JPA and Liquibase/Flyway, with the drift between them.

• HTTP API and risk: endpoints, Angular → Spring call links, hotspots by recent churn × complexity, and knowledge silos.

• Every claim cites a file and line or a commit. Every view states how much of the code it was built from, and is withheld when that's too little.

• MCP server (stratigraph mcp): 13 read-only tools such as what_breaks_if, who_knows and where_is_table_written, for Claude Code, Cursor or any MCP client.

Measured on 20 public repositories against hand-labelled ground truth: entity and table recall 100%, endpoint recall 99%, DI edges resolved 95% (scorecard).

Why "stratigraph"

Stratigraphy is how archaeologists read a site: layer by layer, deducing the order things happened from what sits on top of what. stratigraph does the same to a large codebase — it reads the source, reads the git history, and reconstructs how the thing came to be shaped the way it is.

Aimed at monoliths and multi-module builds of 100k+ LOC where nobody remembers why things are the way they are. Java, Kotlin and Angular first. It runs on repositories that do not compile, have never had node_modules installed, and use layouts nobody has used since Ant — because those are exactly the repositories nobody remembers.

The codebase map, in detail

• A fact graph — packages, classes, methods, endpoints, DI edges, routes, O/R mappings — in a local SQLite file, every row citing a file and line, a commit sha, or the build file it was read from.

• History you can act on — hotspots ranked by churn × complexity, files whose history is one person, and files that change together over and over with nothing in the code connecting them.

• C4 diagrams at all four levels, an ER model read out of the O/R mappings, the HTTP surface, and a ranked findings list — as Structurizr DSL, as Mermaid, and as one self-contained HTML page: no script, no network, no CDN.

• A diff between two runs, so CI can fail a pull request for the cycle it added and stay quiet about the six hundred that were already there — the only gate a legacy monolith can switch on today.

• An MCP server, so an agent working in the codebase can ask structural questions instead of grepping for them.

• Optionally, model-written names and descriptions for the package clusters — under a citation check, enforced in code, that rejects any sentence naming something the model was not shown.

Sixty seconds

npm install -g stratigraph      # or run every command through: npx stratigraph

cd ~/work                       # the fact store lands here, not in the repo
stratigraph init    --repo ../some-monolith   # create the fact store
stratigraph extract --repo ../some-monolith   # parse the source into facts
stratigraph history --repo ../some-monolith   # mine git: churn, coupling, authors
stratigraph analyze --repo ../some-monolith --no-llm  # cycles, clusters, hotspots
stratigraph report  --repo ../some-monolith --out ./arch
open ./arch/index.html

TypeScript and Angular analysis works out of the box — the extractor ships in this package and runs on the Node you already have. Java and Kotlin need a JDK 17+ and one more command, stratigraph fetch-extractor, which downloads the extractor jar and verifies it against a checksum pinned in this package. No API key is needed for any of the above: --no-llm is the whole structural report, and a model only ever adds prose on top of it.

stratigraph doctor    # says which of these your machine can do right now

Contents

• The rule that shapes everything

• Measured on real repositories

• Install

• Set your API key — optional

• Use

  • Angular, and the endpoint it might be calling

  • History, and the coupling nobody wrote down

  • Clusters, and the packages whose name is a lie

  • Interpretation, and what stops it inventing things

  • The report you would actually show someone

  • Ask it questions from an agent — MCP

  • The JVM extractor — Java and Kotlin

  • The TypeScript extractor

  • Keeping the fact store small

  • Keeping it current

  • Upgrading Spring Boot — the upgrade agent in full

  • In a pipeline: JSON and a quality gate

  • Configuration

• Architecture

• Development

The rule that shapes everything

Static analysis produces facts. The LLM produces interpretation. The LLM never invents a fact.

Every node and edge comes from a parser, from git log, or from a build file. Every claim in a generated report carries a provenance reference — a file and line, a commit sha, or a fact-table row. When the model wants to assert something it cannot cite, the correct output is "no evidence found".

This is enforced in the schema, not only in prompts: interpretation lives in different tables from facts, edges are marked fact or inferred, and a citation row has a CHECK constraint forcing it to point at something real. See ADR-0002.

The whole pipeline runs with --no-llm and still produces a useful report.

Measured on real repositories

Quality is measured, not asserted (ADR-0035). stratigraph bench runs the whole pipeline over 20 public repositories, each pinned to a commit in bench/corpus.yaml, and scores the output against ground truth labelled without the tool — from each repository's source, build files, migrations and git log — in bench/truth/. Every number below is from bench/scorecard.md, which lists every miss by name.

The corpus spans Spring Boot monoliths and microservices (petclinic and its Kotlin, REST, legacy-XML and Angular variants, JHipster in Maven, Gradle and OAuth2 flavours, eladmin, piggymetrics, killbill, initializr, OpenMRS, nacos, Spring Cloud Gateway, Spring Boot Admin), Apache Dubbo at 4,000 Java files, and two large TypeScript workspaces (bitwarden/clients at 6,400 files, analog). The labels are only as good as their labelling: where a miss turned out to be a label contradicting the source at the pinned commit, the label was corrected and the evidence recorded in the truth file.

Run it yourself:

stratigraph bench --fetch     # clones the corpus into ~/.cache/stratigraph/corpus
stratigraph bench --private ../your-repo   # aggregates only, nothing that names a file

Install

npm install -g stratigraph

Requires Node 18.18 or newer. Nothing else, until you analyse Java — the Java extractor needs a JDK 17+ available, and tells you so rather than crashing. stratigraph doctor is the honest inventory of what your machine can do:

$ stratigraph doctor
ok   stratigraph     v1.4.0, fact-store schema v1
ok   node            v20.11.1 on darwin-arm64
ok   git             git version 2.50.1
warn java            1.8.0_432 from JAVA_HOME is below JDK 17; the Java extractor
                     will not run (this limits the analyser, not the code it can analyse)
warn jvm extractor   jar not found — see the README for the two commands that build it
ok   ts extractor    dist/extractors/typescript/main.js (built, no JDK required)
ok   config          defaults (no stratigraph.config.json found)
warn model           claude-opus-5, but no credential found
--   database        .stratigraph/my-repo.db does not exist yet — run `stratigraph init`

Every warn above still leaves a working tool: that machine can analyse any TypeScript or Angular repository, mine any git history, and produce the full structural report. stratigraph fetch-extractor clears the second warning; the first needs a JDK 17+, which the tool will find wherever it is installed rather than making you export JAVA_HOME.

For environments where you would rather not think about toolchains at all, the image carries its own JDK, git and extractor:

docker run --rm -v "$PWD:/repo:ro" -v "$PWD/out:/work" \
  ghcr.io/imashishsharma/stratigraph doctor

Set your API key

Only if you want cluster names and ADR candidates. Everything structural — the dependency graph, cycles, clusters, hotspots, coupling, the intent-vs- structure findings — runs with no key and no configuration at all. Skip this section entirely and use analyze --no-llm.

Pick one. They are tried in this order:

stratigraph config set-key sk-ant-...     # writes ~/.config/stratigraph/config.json, chmod 600

export ANTHROPIC_API_KEY=sk-ant-...       # this shell; put it in ~/.zshrc to keep it

echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env   # this directory; gitignore it

ant auth login                            # no key at all, if you use the Anthropic CLI

A Claude Pro or Max subscription is not API credit. Those cover Claude.ai and Claude Code; this tool calls api.anthropic.com, which is billed separately from the Console. A key from an account with no API balance authenticates fine and then fails with "Your credit balance is too low". ant auth login does not change this — the OAuth token carries a user:inference scope but the organisation still needs credit. Interpretation is the only part affected; everything structural runs regardless.

Then confirm — it prints where the key came from, never the key:

$ stratigraph doctor
ok   model        claude-opus-5, credential from ~/.config/stratigraph/config.json

Not sure what is picked up? stratigraph config lists every file that can affect a run, whether or not it exists, and which one won:

$ stratigraph config
Files that configure a run, weakest first. Later ones win.

found   /home/me/.config/stratigraph/config.json    you, every repository
absent  /home/me/work/stratigraph.config.json       this project, committed  (no key here)
absent  /home/me/work/stratigraph.config.local.json this project, your machine
absent  /home/me/work/.env                          environment, e.g. ANTHROPIC_API_KEY

model        claude-opus-5
credential   /home/me/.config/stratigraph/config.json

A key never goes in stratigraph.config.json. That file is meant to be committed, and the tool refuses to load one that contains a key — by the time anyone notices, it has to be rotated rather than deleted. The full reference, including per-project settings and apiKeyFile, is under Configuration.

Use

stratigraph init    --repo ../some-monolith   # create the fact store
stratigraph extract --repo ../some-monolith   # run every applicable extractor into it
stratigraph history --repo ../some-monolith   # mine git: churn, complexity, authors
stratigraph analyze --repo ../some-monolith   # cycles, clusters, coupling, hotspots, ownership
stratigraph report  --repo ../some-monolith --out ./arch   # C4 diagrams, HTML, ranked findings
stratigraph diff    --repo ../some-monolith   # what changed since the previous run
stratigraph mcp     --repo ../some-monolith   # serve it all to an agent over MCP
stratigraph prune   --repo ../some-monolith --keep 2   # drop old runs, reclaim the space

analyze --no-llm is the whole report minus the prose: clusters, mismatches, cycles, coupling, hotspots and ownership all come out of algorithms. The model adds names and readings on top of that, and never replaces any of it.

history attaches to the run extract opened, so both halves share one run_id — which is what lets analyze say exactly which co-changing files have no dependency between them. Either half works alone: on a machine with no JDK, init + history + analyze still produces a full history report, and analyze says which sections it could not fill rather than leaving them out.

analyze prints each cycle as a path with the edges that justify every hop:

1. [high] com.example.web → com.example.service → com.example.repo → com.example.web
   com.example.web → com.example.service
     imports  web.OrderController → service.OrderService  [src/web/OrderController.java:9]
   ...

Every hop names a file and a line, because a dependency cycle you cannot check is not worth reporting. Cycles are stored as findings with citations into the edges that produced them, never as facts — see ADR-0008.

extract runs every extractor the repository needs, detected from what is on disk, and writes them all into one run — which is what lets an Angular service and the Spring endpoint it calls be joined at all, since nodes are scoped by run_id. --lang java|ts|all overrides the detection. A missing JDK skips the Java half and keeps going rather than failing the command.

stratigraph extract --emit writes the raw NDJSON to stdout instead of storing it, and stratigraph ingest --from facts.ndjson replays a captured stream.

Angular, and the endpoint it might be calling

The TypeScript extractor emits components, injectables, NgModules, DI edges, routes with their lazy-loaded boundaries, and the component-to-component edges that only exist inside a template. Directories become package nodes, so cycle detection, clustering and every MCP query work on Angular with no change — a package cycle in app/admin/metrics reads exactly like one in com.example.web, with the template line cited as evidence where a template is what created it.

Then analyze matches Angular HTTP calls against Spring endpoints:

1 cross-stack HTTP call(s) — INFERRED, not observed:

  GET /api/orders/{}  ->  GET /api/orders/{id}
    web/src/app/core/order.service:OrderService#findOne()
      web/src/app/core/order.service.ts:15

  Matched by URL pattern against a declared endpoint. Nothing in either file
  says these are connected; check the cited lines before relying on one.

Every one of those edges is stored with confidence = 'inferred' and is excluded from the package graph, so no cycle can be assembled out of a string match. Only literal and template-literal URLs are matched; a computed one gets a diagnostic and no edge, and a URL matching two endpoints equally well gets a diagnostic naming both rather than a coin toss (ADR-0018). On a real JHipster monolith that honesty is visible: its Angular services build every URL dynamically, so the six candidate calls match eight endpoints equally well each — and the run records six diagnostics naming all eight, not six guessed edges.

It also reports subscriptions nothing can end — no takeUntil, no retained Subscription, no ngOnDestroy on the class. All three have to hold, so a teardown it cannot see produces silence rather than an accusation.

History, and the coupling nobody wrote down

The output worth having is the second section: files that change together over and over with nothing in the code connecting them. The static graph cannot see that by construction.

Files that change together with no dependency between them (top 20):

1. src/main/java/com/example/order/OrderService.java
   src/main/resources/db/migration/V12__order_status.sql
   31 shared commits — strength 0.86, 9.4x chance (36 and 41 commits respectively)

Every such pair is stored as a finding citing the commit shas that produced it, so git show settles any disagreement. Nothing is filtered silently: the report says how many commits were considered, how many were too broad to pair, and how many pairs each threshold removed — an empty section reads like a clean repository unless it says what was examined.

Three things decide whether that output is signal or noise, and all three are written down in ADR-0011: merge commits are excluded, commits touching more than 50 files take no part in pairing (one repo-wide reformat otherwise couples everything it touched), and a pair must co-change more often than chance, not merely often.

A fourth decides how loudly it is reported. gradle-wrapper.jar and gradlew.bat change together in 11 of 11 commits — a perfect co-change score that means one tool regenerates both. A pair is rated on its strength only when a dependency between the two files could have been observed at all: the run has a static graph, and both files are ones an extractor parses. Otherwise it is low, because the finding's own detail already says no dependency could have been seen either way, and a finding must not be rated as strongly as one whose evidence does not disclaim it. On petclinic that is the difference between 23 high findings and 7 — and between a --fail-on high gate that fires on every repository with a build wrapper and one worth turning on (ADR-0028).

Renames are followed, so a file moved three years ago has one history rather than two halves. git log --follow cannot do this — it takes exactly one pathspec — so the miner makes one whole-repository pass and resolves the rename chains itself (ADR-0009).

Alongside it: hotspots ranked by churn × complexity, and files whose history is concentrated in one person. Complexity is total indentation — a proxy, named as one, chosen because it needs no parser and therefore also scores the XML, SQL and properties files that turn up in coupling pairs constantly.

stratigraph history --repo ../some-monolith --since '3 years ago'
stratigraph analyze --repo ../some-monolith --top 40

Clusters, and the packages whose name is a lie

analyze groups packages into communities over one graph built from both layers: the dependency edges the extractor observed, and the co-change the history miner measured. History is allowed to move a package into the group it actually belongs to, which is the point of combining them at all.

3 package clusters (modularity 0.412, coupling weight 1):

1. Order handling (com.example.shop.order) — 7 packages
   Serves the order lifecycle and persists it.
     com.example.shop.order.api
     ...

coupling weight is printed because it decides the answer: at 0 the grouping is purely structural, and raising it lets history outvote the imports. Run it again with --coupling-weight 0 and see what moves. The algorithm is Louvain with every source of randomness removed, so the same facts always give the same clusters — a partition that shifted between runs would make every finding built on it unfalsifiable (ADR-0012).

The finding worth the milestone is the next one:

1. [high] shop.billing.report is named under shop.billing but clusters with shop.admin
   All of the 3 packages named under shop.billing sit in shop.billing:
   shop.billing.invoice, shop.billing.ledger, shop.billing.payment.
   This one sits in shop.admin instead.
   connected to shop.admin.role: imports shop.billing.report.A → shop.admin.role.A
     (src/shop/billing/report/A.java:201)

A package name is a path, so the packages sharing its parent path are its declared neighbourhood, and "named alongside these three, clustered with those three" is arithmetic — not a model's opinion about what report sounds like. The model may later describe what the two responsibilities appear to be; it never decides that a mismatch exists (ADR-0014).

Interpretation, and what stops it inventing things

Names, descriptions and ADR candidates are the only things a model writes, and they are written under a contract enforced in code rather than in the prompt.

Each cluster is packed into a numbered list of evidence — packages, edges with file and line, files with their churn, commits — where every item carries an opaque, pack-local id (e12, not the database's edge id). A model that guesses a database id lands on a real row, so guessing fails open. A model that guesses e99 in a pack of twelve lands on nothing.

Four rules reject a response outright:

1. a citation that is not an id in the pack;

2. a claim that cites nothing;

3. any identifier, path or commit sha in the prose that the pack did not contain — this is the one that catches a real citation attached to a sentence about a class that does not exist;

4. an ADR candidate whose evidence does not resolve.

A rejected response is retried once with the violations attached, then discarded. Nothing rejected is ever stored, and every give-up leaves a diagnostic row — because a cluster nobody could describe must not read like one nobody tried to describe (ADR-0013).

Interpretation by claude-opus-5 — 12 of 14 clusters described.
  Names and descriptions above this line are inference, not observation.
  2 description(s) failed the citation check and were discarded — see the diagnostic table.

What the check cannot do is verify that the evidence supports the sentence. A model can cite seven genuine imports and draw the wrong conclusion from all of them. That is exactly why the mismatch claim above stays algorithmic, and why everything model-authored is stored with authored_by = 'model', the model id that answered, and a report that says which lines are inference.

Without a credential — or with --no-llm — analyze says so in one line and prints the structural report unchanged.

The report you would actually show someone

stratigraph report --repo ../some-monolith --out ./arch

arch/index.html                 self-contained: no script, no network, no CDN
arch/workspace.dsl              Structurizr, all three views, with provenance
arch/c4-context.mmd             Mermaid, level 1
arch/c4-container.mmd           level 2
arch/c4-component-<module>.mmd  level 3, one per container
arch/c4-code-<package>.mmd      level 4, one class diagram per package
arch/data-model.mmd             the ER model, from the declared O/R mappings
arch/findings.md                the ranked list, for pasting into an issue

The HTML page carries all of that plus the HTTP surface, a package dependency matrix and ranked hotspots — with a contents list, and a panel of the numbers worth knowing before you read the rest.

C4 is a projection of the fact graph, not a new model. A container is a deployable — a module whose build file applies the Spring Boot plugin, packages a WAR or declares an Angular/Nx application, or that holds a @SpringBootApplication class — and cites that proof; aggregator POMs, BOMs and libraries are not containers, and a library's packages are drawn inside each container that uses it (ADR-0040). A component is a package — in an Angular workspace, a project, NgModule or lazy route boundary rather than a directory (ADR-0042); a data store exists because a @Table mapping was read; an external system exists because an extractor read an absolute URL out of a literal. Where C4 asks for something no fact supplies, the diagram omits the box and says so on the page:

No fact in this run identifies a person, a role or a user, so no actor is drawn. C4 normally puts one here; this diagram shows only what a parser read.

Every C4 diagram you have seen has a stick figure in the top left. Drawing one here would take four lines of code and nobody would question it — and it would be a box in an architecture map that no parser ever produced (ADR-0019).

The HTML renders its own SVG rather than bundling a renderer or shelling out to a headless browser, so a 40 KB page opens from a file share, survives being emailed, and works with scripting disabled. The layout is deterministic to the pixel — the same run produces the same bytes, which is what lets a fixture test assert the whole SVG rather than that it contains a <rect> (ADR-0020).

Findings are ranked by severity, then observation before inference, then how much evidence there is, then rule name, then id — arithmetic over stored columns, total, and reproducible. No weighted score, because a constant invented in the report layer is a judgement nobody can argue with. And this is where the promise the schema has carried since M0 is finally kept: a finding with no citation is not published, it is excluded from every count, and the number excluded is printed (ADR-0021).

Level 4 is one class diagram per package — a package is something the source states, where a cluster is something an algorithm decided, and the level where a reader is closest to the code is the wrong place to introduce a grouping that is not in the code. Boxes carry stereotypes, fields and methods as declared; generalisation, realisation and association are drawn as UML draws them.

The data model is read out of the O/R mappings. The entity is the table, its columns are the mapped class's fields including the ones it inherits — JPA maps a mapped-superclass chain into the subclass's table, so without that owners would have no primary key — and cardinality comes from the JPA annotation rather than from a field being plural.

That last part cost an extractor change worth recording. List<Pet> erases to java.util.List for the fqn, and has to, or two overloads differing only by type argument become two nodes. It also destroys the only thing that says what the collection holds: on petclinic, three of four entity associations had a readable cardinality and an unreadable target. The extractor now records the type arguments beside the erased type — no fqn changes — and all four relationships come out (ADR-0022). An association whose target still cannot be read gets a row in its own table saying why, never a line to a plausible one.

Run against spring-petclinic — 49 Java sources, 1,040 commits — it produces 6 tables with 4 relationships, 6 class diagrams, 17 endpoints, and 44 findings, every one carrying either a file:line or a commit sha, and each one states its own limits inline:

mvnw and mvnw.cmd change together — 11 of the 11 commits touching either file touch both, 65.1× what independent files would share. No extractor parses mvnw or mvnw.cmd, so no dependency could have been observed between them either way. This is co-change without a checkable explanation, not a demonstrated absence of coupling in the code.

Ask it questions from an agent

stratigraph mcp serves the fact store over MCP on stdio, so an agent working in the codebase can ask structural questions instead of grepping for them.

claude mcp add stratigraph -- stratigraph mcp --repo ../some-monolith

Thirteen tools, all read-only:

The server only reads. It opens the database read-only and never starts an extractor: a stale store is reported as stale, not silently rebuilt, because a tool call is a bad place to start a JVM over 4,000 files. Every answer ends by naming the files that changed on disk since the run read them. When a newer run completes, for example after stratigraph scan in another terminal, the server moves to it, and the first answer after the move says so, naming both runs. That way a transcript shows where answers stop agreeing. --run <id> pins one run for the session instead (ADR-0046).

Every result carries a file and line, an fqn or a sha. Anything a model wrote comes back labelled authoredBy: "model" and is never blended into the structural answer. And every tool that can return nothing says which kind of nothing it is — found for "that name is not in this run", covered for "this run could not have answered that" — because to an agent an empty array reads as "there is no such thing" either way (ADR-0015).

Pointed at dubbo, with the repository itself out of context, it answered five structural questions correctly — a cycle with both directions cited, the sole call site of a method, a bus-factor file, a package summary — and each answer was checked by hand against the lines it cited. One of its numbers disagreed with git log --follow, and the tool turned out to be right; the run is recorded in the ADR.

Keeping it current

Run stratigraph scan again after changing code. Extractors whose inputs did not change are skipped: their stored facts are replayed instead. An input is every file the extractor could read, tracked or not, plus the extractor itself. If HEAD has not moved, the history mined last time is reused too. Both are exact, not approximate. A replayed stream is byte-for-byte what the extractor would print, and the run records facts reused from run N. On nacos (5,600 files), a TypeScript-only edit refreshes in about 15 s instead of about 78 s.

The limit: the Java extractor parses the whole program at once, so any .java or .kt change re-parses all of it. --no-reuse on extract, history or scan turns reuse off.

The JVM extractor — Java and Kotlin

Needs a JDK 17+ to run in; it parses source of any vintage, including Java 8. It parses the source set and never runs or resolves your build (ADR-0006), so it works on a repository that does not compile, has no build file, or uses a layout nobody has used since Ant. Plain core Java with no framework at all gets the full structural output — package graph, cycles and all.

Kotlin is read by the same extractor, in the same run. That last part is the point: Kotlin turns up inside Java repositories — a Spring Boot service with a Kotlin test module, a team migrating package by package — and two separate analyses could not join a Kotlin service to the Java repository it calls, because nodes are scoped by run_id. One run, one graph.

Everything built on the fact graph therefore works on Kotlin without knowing about it. On a four-file Kotlin fixture:

node  class     com.example.shop.service.OrderService
edge  annotated_with  OrderService -> org.springframework.stereotype.Service
edge  injects         OrderService -> repo.OrderRepository
node  endpoint  GET /api/orders/{id}
edge  handles         OrderController#byId(long) -> GET /api/orders/{id}
edge  maps_to         domain.Order -> orders

— constructor injection, the HTTP surface, and an ER model with Long id PK read out of @Entity and @Id. --lang kotlin, kt and jvm all name this extractor; .kt files select it with no flag at all. A build.gradle.kts is read as a module's identity, never as a source file.

What the J model has no place for is read as its nearest Java shape or not at all: extension functions appear as methods, and coroutines and object declarations have no distinct representation yet. Nothing is guessed (ADR-0029).

One boundary is worth knowing before you rely on a mixed repository. The two languages are parsed by different parsers that cannot see each other's sources, so a Kotlin class injecting a Java one resolves — that comes from the import and the declared type — while a call from Kotlin into a Java method does not:

edge  injects  com.example.NewService -> com.example.LegacyRepository   ✓
info: 1 call site(s) could not be resolved to a declaring type and were
      not recorded as edges

Closing that would mean compiling the Java half and handing the Kotlin parser a classpath, which is the one thing this extractor will not do. So it is an absence with a diagnostic attached, never a guessed edge.

The npm package does not ship the jar — it is 22 MB of JVM bytecode, and most installs never analyse a line of Java. One command downloads it:

stratigraph fetch-extractor

It is verified against a SHA-256 written into the npm package by the same release job that built and attached the jar, so the digest never arrives from the same place as the file it describes. A mismatch writes nothing and says so. There is no flag to skip the check. The jar is cached per version under ~/.cache/stratigraph/ — keyed by version, so installing an older stratigraph cannot silently run a newer extractor — and every command finds it there afterwards with no flag.

This is the only thing in the tool that touches the network, and it is a command rather than something extract does on your behalf. Extraction and history mining are entirely local; keeping that true is worth one extra line (ADR-0004).

--dry-run prints the URL, the target path and the pinned digest without downloading. For an air-gapped machine, fetch the jar somewhere else and drop it in — STRATIGRAPH_CACHE_HOME points the cache anywhere:

STRATIGRAPH_CACHE_HOME=/mnt/share/stratigraph stratigraph extract --repo ../monolith

Building it yourself still works and still wins over a downloaded jar, because a developer who has just run maven means the jar they just built:

git clone https://github.com/imashishsharma/stratigraph
cd stratigraph/extractors/java && ./mvnw package

You can also point at one with --extractor-jar <path>, java.jar in the config file, or STRATIGRAPH_JAVA_JAR. stratigraph doctor reports which of these it found, and when the jar was built.

Or skip the toolchain question entirely

The image carries its own JDK 17, git and the extractor, so nothing on the host matters:

docker run --rm -v "$PWD:/repo:ro" -v "$PWD/out:/work" \
  ghcr.io/imashishsharma/stratigraph extract --repo /repo

The repository is mounted read-only and the fact store is written to /work, never inside the repository being analysed — the same rule the CLI follows.

Wildcard imports are refused, then earned. @GetMapping under import org.springframework.web.bind.annotation.*; is genuinely ambiguous from one file's source — a repository can declare its own GetMapping — so the extractor does not guess. Since v1.4 the resolution is earned instead (ADR-0023): the name resolves when the known-annotation table places it in the one wildcard-imported package and no type of that name is declared anywhere in the parsed source set. Facts resolved this way carry resolution: "wildcard-import" so they can always be told apart from a single-type import, and every refusal that remains names the condition that failed — the competing wildcard imports, or the shadowing declaration and the file it sits in. On JHipster's generated controllers this is the difference between 2 endpoints and 41.

What it cannot see without a classpath is stated rather than guessed: meta-annotated custom stereotypes, members inherited from third-party supertypes, anything an annotation processor generates, and bean wiring defined in XML. Each of those produces a diagnostic and an absence, never a wrong edge.

The TypeScript extractor

Needs no JDK and no download — it ships inside this package and runs on the Node already executing, as a separate process so that a parser exhausting memory on a huge workspace takes down one extractor rather than the analysis.

It parses the source set and never installs or type-checks your project (ADR-0016), which is why it does not use @angular/compiler-cli: NgtscProgram needs installed node_modules, a resolvable tsconfig.json and a project that compiles, and the repositories this tool exists for routinely have none of the three. tsconfig.json is read as plain JSON for compilerOptions.paths and nothing else — those aliases matter, because in an Nx workspace they are the only way cross-project imports are ever written.

What it cannot see is stated rather than guessed: anything declared in a package you have not installed (an is_stub node, named by the import that introduced it), template type-checking, and DI through a factory or an InjectionToken. Each produces a diagnostic and an absence, never a wrong edge.

The fact store defaults to .stratigraph/<repo-name>.db under your current directory, never inside the repository being analysed.

Keeping the fact store small

Every extract, history and ingest opens a run, and a run holds a whole copy of the graph for the commit it read. That is what lets you keep last quarter's structure next to today's — and it means a store analysed on a schedule grows without bound.

$ stratigraph prune --repo ../some-monolith --keep 2
run 1    2026-08-12T22:00:06.038Z      343 nodes      205 commits  delete
run 2    2026-08-12T22:03:23.143Z      343 nodes        0 commits  delete
run 3    2026-08-12T22:03:25.010Z      343 nodes        0 commits  delete
run 4    2026-08-13T03:25:56.552Z      343 nodes        0 commits  keep
run 5    2026-08-13T03:25:58.507Z      343 nodes        0 commits  keep
3 run(s) deleted. 2.1 MB -> 792.0 KB (1.3 MB reclaimed).

Every run is listed with what it holds and what is about to happen to it, because a destructive command reporting only a total gives you no way to notice it took the wrong two. --dry-run prints exactly that table and writes nothing. --keep defaults to 3 and must be at least 1; if you want no runs at all, delete the file.

The space is actually returned rather than left on SQLite's free list — the delete cascades through every table, then the store is vacuumed and the write-ahead log folded back in, so the file on disk shrinks.

Recency is the wrong axis for one thing, and it says so. history attaches to the run extract opened, so two bare extracts leave the newest runs with no commits and all the mined history on an older one. Pruning by recency would then delete it, and re-mining a large repository is minutes rather than seconds — so that case is a warning before it happens:

warning: every run being deleted carries the git history and none of the kept
runs has any. After this the store has no commits, and hotspots, churn and
co-change all become unavailable until you run `stratigraph history` again.

Nothing prunes automatically. A tool that silently discarded the run you were about to compare against would be worse than a large file.

Upgrading Spring Boot

stratigraph upgrade upgrades a Maven project's Spring Boot version: 2.7 → 3.5, or 3.x → 4.0. It runs OpenRewrite's upgrade recipe, then works through what the recipe leaves broken. It never decides anything that is really your choice (ADR-0047).

stratigraph upgrade plan --to 3.5          # read-only: versions, JDKs, and where trouble is expected, cited
stratigraph upgrade run --to 3.5           # recipe + known fixes + verification, on a new branch
stratigraph upgrade run --to 3.5 --ai claude-code   # ...and let Claude Code attempt the rest

What run does:

1. Baseline. It creates a new branch, then builds and tests the project as it is. The result is the reference: afterwards, "red" means passed before, fails now. A test that already failed before the upgrade (one that needs Docker, say) is not the upgrade's problem, and the report says so.

2. The recipe, as one commit, so you can review it separately.

3. The loop. It builds, reads each failure, and sorts it into a category:

   • mechanical: a known fix exists (a moved class, a missing -parameters, a formatter, a module Flyway split out…);

   • judgment: the fix needs someone to read the code;

   • decision: any fix changes behaviour you have to choose, such as an authorisation rule or an HTTP contract.

   Known fixes run first. With --ai claude-code, the Claude Code CLI then attempts the judgment failures. It never touches decisions. A change is kept only if the rebuild has fewer failures and no newly red test. A change that disables or deletes a test is rejected outright.

4. The report. upgrade-report.md is committed on the branch. It shows:

   • the status;

   • every test compared with its baseline result;

   • each layer's commits (recipe, known fixes, AI);

   • which test files changed;

   • for everything left, the evidence, what was already tried, and, for a decision, the options.

Why it works this way: on 10 public applications, OpenRewrite alone got 0/10 to a green build. It left 44 breakages, 9 of them introduced by the recipe itself. See bench/upgrade-gap/.

Recipe versions. By default the run uses rewrite-spring 6.37.1 and rewrite-maven-plugin 6.46.1. Those are the last releases on Maven Central: OpenRewrite now publishes new releases to the authenticated Code Genome Project. To use newer recipes, add that repository and its credentials to your ~/.m2/settings.xml (as a repository and a plugin repository), then pass --rewrite-spring <version> --rewrite-plugin <version>. The report records which versions ran.

Unlike the rest of stratigraph, upgrade builds your project, so Maven downloads the new versions. It also commits, but only on its own branch, and it never pushes. Without --ai, no source leaves the machine. With it, the Claude Code CLI reads the source under your own account.

In a pipeline: JSON and a quality gate

--format json is global. Every command that produces a result emits one document on stdout; progress stays on stderr, so a pipe carries only the document:

$ stratigraph analyze --repo ../monolith --no-llm --format json | jq '.findings.bySeverity'
{
  "high": 9,
  "medium": 35,
  "low": 10
}

Every document carries format: 1. That number moves only for a change a parser could trip over, so a consumer can say which shape it understands.

Three things in the shape are worth knowing about, and all three exist for the same reason the rest of the tool does:

• run.coverage and run.gaps travel with the findings. An empty findings.items and a clean repository are otherwise the same document (ADR-0026).

• findings.shown and findings.truncated say when the item list is capped by --top while the counts describe the whole run. Totals that do not add up should be explained by the document, not discovered by the reader.

• findings.unpublishable counts findings withheld for carrying no citation, rather than dropping them silently (ADR-0021).

Failing the build

--fail-on <severity> on analyze or report exits 3 when any publishable finding reaches that severity:

$ stratigraph analyze --repo . --no-llm --fail-on high
error: 9 finding(s) at or above `high` (9 high). Run `stratigraph report` for the evidence behind each one.
$ echo $?
3

Three, not one. A pipeline has to tell "this build has nine high findings" from "the tool could not run" — and a broken analyser read as a clean repository is the CI version of the mistake this whole project is written against. The codes are 0 success, 1 unexpected error, 2 a reported error, 3 the gate.

The gate counts exactly what the report publishes: a finding with no citation fails no build, because it is a claim the report itself refuses to show. And the document is written before the non-zero exit — a gate that failed still hands the pipeline the findings that failed it.

Failing only on what got worse

--fail-on has a problem on the codebases this tool exists for: a 100k-LOC monolith nobody remembers has hundreds of findings on day one, so a gate that fails from the first commit gets deleted from the pipeline in a week.

stratigraph diff compares two runs, and --fail-on-new gates on the difference:

$ stratigraph diff --repo ../monolith --fail-on-new high
run 41 (a3f19c2e04, 2026-08-06T09:14:02Z) -> run 47 (7b02de1188, 2026-08-13T09:02:55Z)

Findings
  new           3  2 high, 1 medium
  resolved      1  1 high
  unchanged   612

New since the earlier run:
  [high] Package cycle: com.shop.web ⇄ com.shop.billing
  ...

error: 2 new finding(s) at or above `high` since run 41 (2 high). Findings that
were already there do not count.

That gate can be switched on today by a repository that would fail --fail-on on every commit for a year. The two answer different questions — "is this codebase acceptable" and "did this change make it worse" — and only the second one can be asked of a monolith on day one.

Findings are matched across runs by rule and title, which every rule builds deterministically from the entities involved. Cycles are matched on their set of packages, because the title names the shortest path through a component and that path rotates when an unrelated edge appears — same cycle, different sentence. Two analyses of an unchanged repository produce an empty diff; on spring-petclinic that is 44 findings, 0 new, 0 resolved, in 0.13s.

What it cannot see is a finding whose wording changes while the problem stays: renaming a package reports its old findings resolved and new ones added. That is the deliberate trade — matching fuzzily would report a genuinely new cycle as an old one under a new name, and a gate that quietly does not fire is worse than one that reports a rename (ADR-0027).

A pipeline that works on a repository with existing debt

- uses: actions/checkout@v4
  with: { fetch-depth: 0 }        # a shallow clone understates every history metric

# The base commit, so there is something to compare against.
- run: |
    git checkout -q ${{ github.event.pull_request.base.sha }}
    npx stratigraph init    --repo .
    npx stratigraph extract --repo .
    npx stratigraph history --repo .
    npx stratigraph analyze --repo . --no-llm

# Then this one. Both land in the same store as consecutive runs.
- run: |
    git checkout -q ${{ github.sha }}
    npx stratigraph extract --repo .
    npx stratigraph history --repo .
    npx stratigraph analyze --repo . --no-llm

- run: npx stratigraph diff --repo . --fail-on-new high --format json > diff.json

- if: always()
  run: npx stratigraph report --repo . --out ./arch
- if: always()
  uses: actions/upload-artifact@v4
  with: { name: architecture, path: ./arch }

history reports "shallow": true in its document when the clone is shallow, so a pipeline can catch a missing fetch-depth: 0 rather than silently comparing understated numbers.

Keep the store between runs (cache .stratigraph/) and stratigraph prune --keep 10 on a schedule; keep it per-job and the base analysis above is what gives diff its second run.

Configuration

No config file is required. stratigraph analyze --no-llm needs none at all, and every value below has a working default. You create a file to change something — see Set your API key for the common case.

stratigraph config                      # what is in play right now
stratigraph init --write-config         # scaffold stratigraph.config.json

init --write-config writes the defaults spelled out, so the file is a menu of what can be changed rather than decisions made on your behalf. It never overwrites an existing one.

Where the files go

Four places, none of which exists until you create it, merged weakest first:

The project files and .env are looked up in the working directory first, then in the repository being analysed — so cd ~/work && stratigraph analyze --repo ../monolith reads ~/work/stratigraph.config.json, then falls back to ../monolith/stratigraph.config.json. --config <path> overrides the lookup.

On Windows the user file is %APPDATA%\stratigraph\config.json. XDG_CONFIG_HOME and STRATIGRAPH_CONFIG_HOME are both honoured.

Precedence, highest first: CLI flags → local → project → user → defaults. A project pinning "model": "claude-opus-5" beats your personal default; your .local.json beats the project. A variable already exported always beats .env, so a committed .env cannot override a secret CI set.

Unknown keys are an error, not a shrug. An explicit null means "use the default", which is why the scaffolded file can spell every option out.

The credential, in full

A configured apiKeyFile that cannot be read is an error, rather than a quiet fall-through to whatever else is lying around: silently using a different credential than the one you asked for is how the wrong account gets billed.

Without a credential, analyze prints one line saying so — with the three commands that would fix it — and the structural report is unchanged.

What you can set

The full shape is in stratigraph.config.example.json, which ships with the package. The three worth knowing:

• llm.model — defaults to claude-opus-5. --model <id> overrides it per run. Whichever model answered is recorded on every row it writes.

• interpret.couplingWeight — decides the clustering, so analyze prints the value it used. 0 clusters on structure alone.

• interpret.maxClusters — caps how many clusters are sent to the model, so a large repository cannot run away with your bill.

llm.sendSource is off by default and loudly logged when on. Extraction and history mining are entirely local; only the interpretation layer talks to a model API, and only about structural metadata unless you opt in.

Architecture

Five layers, strictly one-directional. Layers do not reach backwards; presenters never call extractors.

extractors ──NDJSON──▶ fact store ──▶ history miner ──▶ interpreters ──▶ presenters
 (Java: JVM)            (SQLite)        (git log)      (clustering + LLM)   (MCP server,
 (TS: compiler API)                                                          Structurizr,
                                                                             Mermaid, SVG,
                                                                             HTML, Markdown)

Presenters read the store and derive nothing. stratigraph report opens the database read-only, and every diagram it draws is a projection of rows that extract, history and analyze already wrote — so a report cannot disagree with the analyze run that produced it, and two reports of one run are byte-identical.

Extractors are separate processes that emit newline-delimited JSON on stdout. The core never links against a parser, which is why a JVM-only Java parser and a Node-only Angular parser can coexist without either infecting the core (ADR-0001, ADR-0003). The TypeScript extractor is Node like the core, so the boundary is enforced by the build rather than by convention: it compiles under its own rootDir, and an import from src/ into it fails to compile.

Development

npm install
npm test           # vitest
npm run typecheck
npm run build
npm run stratigraph -- doctor      # run the CLI from source

cd extractors/java && ./mvnw verify # the extractor and its golden tests

The TypeScript suite never needs a JDK — the core is tested against a fake extractor that prints canned NDJSON, because the protocol is the whole contract. The extractor's own suite asserts exact fact output for every fixture, and CI runs one job where a real jar meets the real fact store.

It needs git for exactly one test, which builds its own repository with fixed dates and authors. Everything else about history is driven from a captured git log in fixtures/git-log/ or from seeded rows, so the three-OS matrix depends on no binary it did not install.

Contributing

CONTRIBUTING.md has the conventions, and they are stricter than most: a parser change without a fixture test does not get merged, every non-obvious decision gets an ADR, and nothing may state a fact it cannot cite.

The most useful contribution right now is not code. Run it against a repository I have never seen and tell me what it got wrong — a wrong edge, a missed endpoint, a finding that is noise. A confidently wrong dependency map is the failure this project is built to avoid, so a fact that should not be there is as valuable a report as one that is missing. There is an issue template for exactly that.

Security reports go through SECURITY.md, never a public issue. CHANGELOG.md is what changed and why.

Conventions:

• Test-first for anything in the fact layer. A parser change without a fixture test does not get committed.

• Fixtures in fixtures/ are tiny, hand-written, and assert exact fact output. The one exception is fixtures/git-log/, captured from a real git — it asserts what git emits, and inventing that from memory is how a parser ends up handling a format nobody produces.

• No speculative abstraction: two concrete implementations before an interface.

• Every non-obvious decision gets an ADR in docs/adr/.

Licence

Apache-2.0.