LLvator

Where it earns its place

Six situations, one graph.

Mezzanine does one thing — it turns a repository into a typed graph and answers questions about it. What changes is which question you are stuck on. These are the situations where that turns out to be the expensive part of the week.

Worked example

Inheriting a legacy codebase

“Two projects, both legacy, in a stack I don’t know — and I switch between them daily.”

The oldest version of the problem and still the most expensive: undocumented domain vocabulary, logic hiding in config files, and no author left to ask. A derived map removes the structural half of every reload, which is the half you were rebuilding by reading.

  1. Read the domain map before any code — or map one folder, never the root
  2. Cross complexity with churn to find where the risk actually sits
  3. Check blast radius and existing tests before touching anything
overviewmaphotspotsimpacttests_for
The full breakdown, point by point →

Reviewing code you didn’t write

“A thousand generated lines landed in my queue and the author has no memory of writing them.”

Style a reviewer can judge from the diff. Structure they cannot: what else calls this, what the new coupling does to the module, whether this is the third copy of a helper that already exists twice. Those are graph questions, and they are the ones that matter.

  1. Diff the working tree against the base — metric deltas and smell churn, not opinions
  2. Check the blast radius of anything the diff touches
  3. Search for the thing before accepting a new implementation of it
assess_changeimpactsimilarquality
Why review became the bottleneck →

Onboarding — someone else, or yourself

“I need to be useful in this repository by the end of the week.”

The first two weeks are spent rebuilding a model that already exists implicitly in the code. Reading it out of the graph instead compresses that to an afternoon, and produces the same picture for everyone rather than a different one per person.

  1. Domain map first: what the product does, and which folder claims each part
  2. Structural map of the one area you were pointed at
  3. Open the graph at landmark level, then filter down
overviewmaptracethe graph
The twenty-minute version, step by step →

Giving a coding agent the map

“My agent re-reads six files every turn to work out what calls what.”

An agent pays by the token and the global view never fits in its window. Serving it structure directly — ranked, capped, explicitly truncated — replaces the file-reading it does to reconstruct exactly that. And because it optimises for the change compiling rather than the folder staying followable, it needs telling when the second one slipped.

  1. Ground the task in the domain before opening anything
  2. Map and context instead of reading files one at a time
  3. Impact and tests before the edit; self-review and reshape on the diff after
MCP · 13 read-only tools
The nine-step agent loop →

Planning a refactor you can defend

“Everything looks scary, and I have one sprint to make it less scary.”

Complexity alone ranks the ugly. Crossed with git churn it ranks the expensive — code that is convoluted and edited every week, rather than convoluted and untouched since 2019. That difference is the whole argument you take to planning.

  1. Rank by churn × complexity to get a shortlist, not a wall
  2. Name what is wrong there — smells with remediation hints
  3. Size each candidate by blast radius before committing to it
hotspotsqualityimpactdead_code
The metrics and smells behind the ranking →

Keeping structure as the codebase grows

“It was clean six months ago. Nobody made it messy — it just stopped being followable.”

Nothing decides to tangle a codebase; it arrives one locally-reasonable import at a time, and no review catches it because no diff contains it. Scoring the shape of every folder turns that from a feeling into a named blocker with a next move — and puts a number on the thing that was previously argued about in adjectives.

  1. Read the shape report: what is short of fractal, deepest actionable folder first
  2. Reshape one folder one rung — break the loop, or nothing else yet
  3. Declare the bars you actually agree with, and let check hold them in CI
qualityreshapemezz check
The ladder, the gates and the evidence behind them →

Keeping documentation true

“Our ADRs are good. Nobody can tell which ones still describe code that exists.”

Decision records age well and say nothing about the present; diagrams say something about the present and are redrawn by hand, which means never. The fix is to make every claim an anchor a machine can check — and to fail the build when one dangles.

  1. Sketch the map one line at a time; deepen only the branch you touched
  2. Point features at the code, and at the decisions that govern them
  3. Let check and drift be the radar — errors fail, hints are a to-do list
elevator --check--drift--code-mapcr.adr:
How it sits next to ADRs, C4 and glossaries →

The other half of the answer

What this is the wrong tool for.

A graph built from source knows what the code is. Every question about what it does at runtime is somebody else's job, and pretending otherwise is how tools like this get abandoned in month two.

Anything at runtime

Why it's slow, why it crashed under load, which branch actually executed. No traces, no profiler, no coverage of its own. Use a profiler and an APM; Mezzanine tells you what the suspect code is wired to, not what it did last Tuesday.

Whether the behaviour is correct

It can tell you which tests reach an entity and what a change did to complexity. It cannot tell you the change is right. That's still tests, types and review — the graph just makes each of those land in the right place.

The user's journey

The most common gap in every conversation that leads people here: you haven't used the product you're modifying. Fifteen minutes watching someone complete the workflow beats any amount of static analysis, and nothing here replaces it.

Recognise one of these?

The install is a clone and a script, the analysis runs on your machine, and the first useful answer arrives about a minute later.

Install See the exact calls →