Why grep loses and a graph wins

You ask an assistant to rename getUser. It runs a search, finds eleven matches, changes them, and reports success.

It missed the one inside a template string. It changed an unrelated method on another class that happened to share the name. And it never touched the export that three other packages depend on, because that file doesn’t contain the word getUser at all — it re-exports something else entirely.

The tool worked perfectly. It answered the wrong question.

What’s actually happening?

To a search tool, a file is a flat run of characters. But the code inside it has structure: this function calls that one, this module imports that module, this route handler touches that table.

That structure is a graph — a word that sounds more academic than it is. A graph is just things, and the connections between them. Nodes are the things: files, functions, classes, routes, tables. Edges are the connections: calls, imports, extends, reads-from.

Think of the difference between a phone book and a contact tracing map. The phone book tells you every person named Smith. The map tells you who actually spoke to whom. Only one of those helps you work out what spreads.

$ grep -rn "getUser" .
api/users.js:14   export function getUser(id)
api/users.js:52     return getUser(req.params.id)
admin/panel.js:8  import { getUser } from '../api/users'
legacy/Session.js:91  getUser() { return this._u }
docs/api.md:30    `getUser(id)` returns a user

# which are the same function?
# grep cannot say.

function:getUser  (api/users.js:14)
<- called by  route:GET /users/:id
<- called by  admin/panel.js
<- imported   3 modules
-> calls      db.query
-> reads      table:users

class:Session.getUser  (legacy/Session.js:91)
# separate node. no edge to the above.

How does it get built?

You don’t write it by hand. It’s derived from the code, which is why it can’t drift out of date the way documentation always does.

function:getUser@api/users.js:14
class:Session@legacy/Session.js:3
module:admin/panel.js
route:GET /users/:id

panel.js: import { getUser } from '../api/users'
-> resolves to  function:getUser@api/users.js:14
-> NOT          class:Session.getUser

impact("function:getUser")
-> 3 modules, 1 route, 6 tests

path("route:POST /checkout", "table:orders")
-> handler -> CartService.commit
   -> db.insert -> table:orders

Why does it matter?

Here is where it stops being a nice diagram and starts being the difference between an assistant that works and one that doesn’t.

A model has a finite context window — a hard limit on how much it can hold at once. You cannot paste a large repository into it. So the real engineering question is never “how clever is the model”, it is which few thousand tokens go in.

Search answers that badly. It hands over the twenty files containing the word, ranked by nothing much. Half are irrelevant, and the file that matters most — the caller two hops away that never mentions the word at all — isn’t there.

A graph answers it well: start at the thing, walk two hops, take that subgraph. Small, complete, connected.

What are the limitations?

A graph is overhead, and it is not free. On a small codebase an assistant can simply read end to end, it buys you very little and costs you a build step.

It starts paying when the codebase is too large to read in one go, when changes have non-obvious blast radius, when you’re doing repeated structural work like migrations or dead-code removal, or when several agents work in parallel and each needs a different correct slice.

The honest costs: parsing and resolution take real engineering, resolution is genuinely hard in dynamic languages, and the graph has to be kept fresh as the code changes. A stale graph is worse than no graph, because it is confidently wrong in a way grep never is.