Stratigraph

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), Maven or Gradle

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, on Maven and Gradle builds alike.

• 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.

Tried it? Tell us what you upgraded, and what it got wrong, in Discussions. Upgrading a fleet of Boot 2.x services? Become a design partner and run it on real code with the maintainer.

🗺️ 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)