Reading the report
aburi diff writes .aburi/diff.md. This page walks you through it, from the top line down.
The summary line
**Summary**: +5 added · -3 removed · ~12 changed · 2 moved · 1 moved+changed · ?2 unknownA symbol is a function, method, or class that survived boilerplate removal. Each one lands in a single bucket:
| Bucket | Meaning |
|---|---|
added | Did not exist in the base revision. |
removed | Existed in the base revision and is gone. |
changed | Same symbol, different behaviour, or Aburi grew more or less sure of it. |
moved | Same behaviour, different file or name. |
moved+changed | Both. |
unknown | Aburi could not read one side. See Gaps. |
?N unknown shows up when that count is non-zero. When you see it, read the added and removed counts beside it as lower bounds.
-3 removed (2 duplicates) says two of the three removed symbols were duplicates: the head revision still has a symbol of the same kind with the same body, as when two identical helpers become one. --fail-on removed does not count them, and --fail-on removed:duplicate does. Only a body with something to compare counts: a guard (an if that returns or throws), a throw, a switch, a computed return value or an effect. A body that only calls something, or returns a literal, a variable or a property, never counts, and neither does a symbol a framework plugin classified, such as a route handler or a React component, because its role is not in its body.
The sections
Sections appear in a fixed order, most important first. Aburi drops the empty ones and folds Moved, Dropped changes, Syntax-only changes and Test files behind a <details>.
| Section | What it tells you | Your next move |
|---|---|---|
| ⚠ API changes | A public surface moved: signature, throws, decorators, or the names a declaration is exported under, such as a new DELETE route handler. | Check every caller. |
| 🔧 Logic changes | Control flow or effects changed inside a body. | This is the review. |
| 🧵 Slice View | The changed symbols that call one another, grouped into one slice per call chain. | Read a feature end to end. |
| ➕ Added | New symbols, rendered in full. | Read the effects and rules. |
| ➖ Removed | Symbols that disappeared. A duplicate names the symbol that still holds its body. | Confirm you meant to delete them, and that a duplicate's callers moved to the survivor. |
| ❔ Unknown | One revision never analysed the file. | Fix the scan, not the code. |
| 🚫 Not compared | Neither revision analysed the file. | A standing blind spot. |
| 🔀 Moved + Changed | Relocated and modified. | Read it like a Logic change. |
| 🔀 Moved | Relocated, behaviour identical. | Skim and move on. |
| 🧱 Component changes | A component appeared, vanished, or changed — roots, public API, frameworks, name, languages, or description. | Architectural. Worth a look. |
| 🔗 Dependency changes | A call between two symbols that appeared or went. | Watch for layering violations. |
| 💧 Dropped changes | Boilerplate that came or went. | Usually nothing. |
| 🎚 Confidence changes | Aburi is more or less sure of a symbol, and nothing it fingerprints changed. | Check the new badge (see Confidence). |
| 🎨 Syntax-only changes | Bodies reformatted, behaviour identical. | Nothing. |
| 🧪 Test files | Every change to a symbol of test code, by name, and the call edges those symbols gained or lost. A change listed here is not listed in the sections above, though a Slice that reaches from test code into the code under test still draws its test members. The Summary line ends with how many changes there are. | Open it when the tests are the point of the change. |
Learn the split between API changes and Logic changes first. An API change breaks other people's code. A logic change alters what your own code does.
An entry
### `submitOrder` *(function)*
**File**: `src/app/orders/actions.ts:18`
- signature.outputs: `Promise<Order>` → `Promise<OrderWithReceipt>`
- signature.throws added: `PaymentDeclined`An entry is named after the symbol it is about. Two names are not written in the source: <default> is a file's anonymous default export, and <module> is what a file does when it is imported, the statements at its top level that declare nothing (await seed(), process.on("SIGTERM", …)). In a CommonJS file that includes the functions assigned to module.exports or exports.handler: an assignment declares nothing, so their calls are reported under <module> rather than under a name of their own.
A change entry lists what differs. A rule, effect, call or decorator that was edited rather than added or removed sits under modified, with the old value beside the new one:
- rules modified:
- loop (`for` → `while`) (L3)
- effects modified:
- db.write: `prisma.user.create` (L5) [effects-prisma] ⚠ medium (was high)When several elements of one kind were edited at once, such as two guards, and their old values differ, that field shows only the new value.
A single value that changed reads the same way, old value first:
- signature.typeParameters: none → `<T extends Order>`
- component: `orders` → `checkout`
- visibility: `internal` → `public`For an added or removed symbol, Aburi renders the whole thing:
### `refundOrder` *(function)*
**File**: `src/app/orders/actions.ts:64`
**Rules**:
- guard: `!order.canRefund` (L67)
- throw: `RefundNotAllowed` (L68)
**Effects**:
- db.write: `prisma.order.update` (L72) [effects-prisma]Three field groups carry most of the meaning.
Boundary lists the decorators that make the symbol reachable from outside: NestJS's @Post() or @MessagePattern(), or one a frameworkHints rule marks with boundary: true. A framework without decorators, such as Next.js, records its route handlers under Derived by instead, which aburi explain shows, and the entry has no Boundary line.
Rules are the control flow Aburi kept. Guards, throws, returns, loops, branches. A removed guard line means somebody removed a condition.
Effects are what the symbol does to the world: db.read, db.write, db.transaction, event.publish, network.rpc. A method that gained db.write now writes to your database.
A framework registration also lists its Middleware, the functions an Express route or use runs before its handler, in order. Removing one is a logic change that names it:
- middleware removed: `requireAdmin`A route that lost its authorization check reads as that, not as a reformat.
A slice
The Slice View groups the changed symbols that call one another, so a feature reads end to end. Each slice is drawn as its calls, from the symbol nothing else in it calls, with each member on one line saying what happened to it:
### From `submitOrder` (3 symbols)
Files: `src/app/orders/actions.ts`, `src/lib/payments.ts`
- `submitOrder` — API and logic changed · `actions.ts:18`
- `chargeCard` — new function with network.http · `payments.ts:7`
- `recordOrder` — logic changed · `actions.ts:40`A member reached twice is written out once, and (see above) where it recurs. A call that only the base made is still drawn, since it is what joined the slice, and says (call removed). The symbols with no resolved call to or from another symbol in the view are folded under Standalone changes, one line each.
Two slices that should be one can come apart when Aburi could not tell what a call reaches. When an unresolved call looks like a call to a changed symbol in another slice, the member says so, and a note under the heading counts them:
- `submitOrder` — logic changed · `actions.ts:18` · ⚠ unresolved call to `getRepo.save`Read the slice that holds Repo.save together with this one. A call is marked only when its name matches a changed symbol in another slice, so calls into libraries and built-ins rarely are.
Confidence
Aburi flags anything it is less sure about. A symbol carries the badge on its heading; an effect, at the end of its row. When the badge on a symbol moves, the entry says so with a confidence: before → after line; when an effect's moves, its row under effects modified ends with the old one, (was high).
| Marker | Meaning |
|---|---|
| (no badge) | Confident. |
⚠ medium | The signal matched through an indirection, such as a decorator re-exported through a barrel Aburi could not trace, or an aliased import. |
⚠ low | A weak match. Verify before you rely on it. |
Gaps in the report
Two sections tell you what the report could not cover. Both point at the scan rather than the code.
❔ Unknown means one revision analysed the file and the other did not, so a symbol appears or disappears for reasons unrelated to your change. The entry names the file and the cause:
### `handleRequest` *(function)*
**File**: `src/app/api/legacy/route.ts:12`
**Why**: the head scan skipped `src/app/api/legacy/route.ts` (parse-failed), so this Symbol may still existIf git renamed the file between the two revisions, the entry reads this file under its head name (or base name) followed by the path the skipping scan used, because that is the file to fix.
A parse-timeout clears on a re-run most of the time. For the rest, fix the file or leave it out with ignore.
🚫 Not compared means neither revision could read the file, so nothing in the report says anything about it. This is often a standing property of the repository, such as a generated bundle over the size limit or a language with no plugin installed, and it will keep showing up until you change the cause.
The other reports
aburi scan writes two more documents, useful outside pull request review.
.aburi/workspace.md covers the repository at a glance: components and their roots, the most common effects, and any files the scan could not read. Hand this one to a new joiner. Its Component dependencies graph draws an arrow from one component to another wherever a file in the first imports the second, by a relative path or by its package name. A CommonJS require() call is not an import, so it draws no arrow.
.aburi/components/<id>.md covers one component in full. Every kept symbol, grouped by file, with its boundaries, signature, rules, effects, and calls.
#### `submitOrder` *(function)*
**Signature**: `(cart: Cart) → Promise<Order>` throws `EmptyCart` ⚡async
**Rules**:
- guard: `cart.items.length === 0` (L21)
- throw: `EmptyCart` (L22)
**Effects**:
- db.write: `prisma.order.create` (L34) [effects-prisma]To look at one symbol, skip the file and ask for it:
aburi explain submitOrder