How AI Code Review Catches Bugs Across Files

Most code review tools are looking at the wrong picture. They read the diff, reason about the diff, and write comments about the diff. The bugs that matter most — the ones that take a service down at 3am — almost never live in the diff alone. They live in the gap between the diff and everything else in the repository: the caller two files away, the type defined in a shared package, the helper that quietly assumed a contract the diff just changed.

Cross-file bug detection is what makes AI code review actually useful. It's the difference between a tool that reads pull requests and a tool that understands them.

Why single-diff review misses the bugs that matter

Pull requests are a slice. They show what changed, not what depends on what changed. A 200-line diff might rename a struct field, refactor an error path, or tighten a function signature. The diff itself can look fine — and the bug is sitting in a file the PR doesn't touch.

A few common bug shapes that single-diff review can't see:

• Caller-callee contract drift. A function signature changes; one of the seventeen callers still relies on the old contract.
• Type-graph ripple. A struct field is renamed in one file. A serializer in another file builds JSON keyed off the old name. Production payloads now miss a field.
• Conditional unreachability. The diff adds a branch. A switch in a different file is supposed to handle every case, and the new branch isn't covered.
• Concurrency invariants. A lock pattern changes in one file; a helper in another file assumed the old pattern. A race appears under load.
• Configuration coupling. A default changes in one file; a migration script in another directory relied on the old default and silently writes wrong values.

A reviewer that only reads the diff will not catch these. A senior human reviewer might — by remembering the rest of the codebase. Codebase-aware review is the same trick, automated, applied consistently to every PR.

Macroscope reads the whole repo, not just the diff

When a pull request lands on a repo where Macroscope is installed, the reviewer doesn't start with the diff. It starts with the repository. Agents have full read access to the codebase — they can navigate references, follow imports, grep, read configuration files, and look at git history. The diff is one input. The rest of the codebase is the rest of the inputs.

That's the part most diff-only tools skip. It's also the part that determines whether a comment ships with real context or with a guess.

Deeper analysis on eight languages

Macroscope reviews pull requests in any codebase. For eight languages — Python, TypeScript, JavaScript, Kotlin, Java, Rust, Swift, and Go — there's a second layer underneath: native AST analysis that understands the code at the structural level, mapping how functions, types, and modules connect across files.

For repos in those eight languages, that extra structural depth is what surfaces cross-file ripples reliably: signature changes that break callers, type renames that don't propagate, control-flow gaps that span files. For repos in other languages, Macroscope still reviews every PR with full repo context — agents read the relevant files, not only the diff — just without the same structural depth.

A small example

The cleanest way to see why cross-file analysis matters is to look at a real bug. From the public Macroscope code review benchmark dataset:

• Repository: apache/commons-math (Java)
• Bug: MathUtils.gcd detected zero operands by testing u * v == 0. For non-zero inputs like 65536 × 65536, the multiplication overflows to zero, the method takes the zero-case path, and returns the wrong answer.

Read the diff alone, and the bug is hard to see. The author plausibly meant u * v == 0 as a shortcut for "either is zero." Most unit tests pass. The flaw is structural — integer overflow can produce a false zero — and it's only catchable if the reviewer knows enough about the surrounding types and call sites to recognize the input ranges that break it.

A diff-only reviewer guesses. A codebase-aware reviewer doesn't have to.

How this connects to the rest of Macroscope

Cross-file context isn't only for bug-finding. Several Macroscope features ride on top of it.

• Approvability. When the reviewer can confidently say "this PR has issues," it can also confidently say "this PR has none." Approvability auto-approves low-risk PRs whose blast radius the system judges as contained. Opt-in per repo, tunable per file pattern, dissolves queue time on the trivial half of the backlog.
• Check Run Agents. Custom rules in .macroscope/check-run-agents/*.md are written in plain English and enforced as real GitHub Check Runs. Each agent gets the same codebase context as the default reviewer — so a rule like "always log on this code path" can be checked across the repo, not just inside the diff.
• The Macroscope Agent. When a change benefits from research instead of just review, the agent explores the codebase and answers questions about it: where a behavior is implemented, why a refactor is risky, what surfaces a given module touches.

The product surface is broader than the comment thread. The codebase-awareness underneath is what makes all of it work.

Try it on your own codebase

The fastest way to see what a codebase-aware reviewer surfaces is to run it on your code.

1. Install Macroscope on a GitHub repository in under two minutes.
2. New workspaces get $100 in free usage.
3. Open a PR. Macroscope reviews it on default settings, with full repo context behind every comment.
4. Add Check Run Agents in .macroscope/check-run-agents/*.md to enforce your team's conventions.
5. Turn on Approvability if you want auto-approval for low-risk PRs.

There are no seat fees. You pay for the work Macroscope actually does.

See what cross-file review surfaces on your code

Get $100 in free usage to run Macroscope on real PRs.

Sign up

Frequently Asked Questions

What is cross-file bug detection?

Cross-file bug detection is the ability of an AI code review tool to identify bugs whose root cause spans more than the files changed in a pull request. The diff might look fine, but a caller in a different file relies on the old behavior, a type definition somewhere else doesn't match the new shape, or a config consumer is reading the wrong default. Cross-file detection requires the reviewer to reason about the codebase, not just the diff.

Does Macroscope only review the languages it has deep support for?

No. Macroscope reviews pull requests in any codebase. Agents have full read access to the repository, so reviews happen with broader context than the diff regardless of language. For eight languages — Python, TypeScript, JavaScript, Kotlin, Java, Rust, Swift, and Go — there's a deeper structural layer underneath that surfaces cross-file ripples (signature changes, type renames, control-flow gaps) more reliably.

Which languages does Macroscope have deep support for?

Python, TypeScript, JavaScript, Kotlin, Java, Rust, Swift, and Go. In those languages, Macroscope analyzes code at the structural level — understanding how functions, types, and modules connect — in addition to the LLM-driven review every codebase gets.

Why does this matter compared to a tool that only reads the diff?

Most production bugs aren't visible in the diff alone. They appear when the change interacts with something elsewhere in the repository — a caller in another file, a type defined in a shared package, a config consumer two directories away. A reviewer that only reads the diff can't see those interactions. A codebase-aware reviewer can.

How is this different from static analysis tools?

Static analyzers match patterns against code — regex, AST patterns, or DSL rules. They find syntax-level issues like missing nil checks or deprecated API usage. Macroscope is a codebase-aware AI code reviewer: it reasons about your code semantically with the repository as context, so it catches things pattern matching can't — contract drift, ripple effects across files, semantic bugs. Most teams keep their static analyzers alongside Macroscope; the two solve different problems.

What is Approvability?

Approvability is a Macroscope feature that auto-approves PRs the system can confidently classify as safe — small, low-risk changes whose blast radius is contained. It's the inverse signal of high-precision detection: if the reviewer is confident it can flag bugs, it can also be confident when there are none. Opt-in per repository and tunable per file pattern.

What are Check Run Agents?

Check Run Agents are how teams enforce their own conventions in Macroscope. Each agent is a Markdown file in .macroscope/check-run-agents/ that describes a custom rule in plain English. The agent runs as its own GitHub Check Run on every PR, sees the full repository context, and can block merge on failure — closer to writing a review note for a teammate than configuring a linter.

How does Macroscope review every PR if it doesn't only look at the diff?

Macroscope's review pipeline reads the diff, but it also reads relevant parts of the surrounding repository — the files that contain callers, definitions, related logic, and configuration tied to the change. The result is a review grounded in the codebase, not in the diff in isolation.