Say you're changing the repeat-rule field on an event. Where else do you need to look? The code that expands repeats, obviously, but also each adapter for Google, iCloud, Outlook and iPhone calendars, where the field is read and written. Then there's the field in the API document, the event sheet in the iOS app, and the tests. Build that list from memory and something always slips. Whatever slips comes back as a bug after release.
Text search (grep) isn't enough either. SQL puts table names inside template strings, the iOS app calls the API by a generated function name rather than a path, and web forms write the API path as a string in the action attribute. So ikie builds a graph from its code. We call it the ontology.
Built automatically from the sources
Nobody writes facts into the graph by hand. The only hand-written part is the vocabulary of node and edge types. Every fact is read from a source that already exists.
| Source | How we read it | What comes out |
|---|---|---|
| Model declaration | Read model.ts | Fields, mappings to external calendars, sync field groups |
| Database | Apply the migrations in order to an empty in-memory Postgres (PGlite) and read the information schema | Tables, columns, foreign keys |
| API contract | The OpenAPI document | Schemas, fields, what each route accepts and returns |
| App policy and screen features | packages/policy declarations | Rules, scenarios, web and iOS files per feature |
| TypeScript | The compiler API, down to individual names | Imports, name references, API calls, SQL table names, tests |
| Swift | tree-sitter syntax trees | Types, members, extensions, protocol conformances, API calls |
Today the graph has about 26,600 nodes and 84,400 edges, across 22 node types and 28 edge types. Building it took 41 seconds in our development environment. The built graph isn't committed. The same sources must always produce the same graph, so CI builds it twice and fails if the two files differ.
When Swift code uses a common name like id or title and we can't tell the receiving type, we don't guess. The edge is recorded as "unknown". A wrong edge is worse than a missing one: once impact lists bloat, people stop trusting them.
Impact walks backwards
"What does changing this affect?" is answered by walking edges backwards, toward whatever depends on the node. We also record how many steps away each result is, so the nearest ones come first.
impact(id: string): Map<string, number> {
const seen = new Map<string, number>([[id, 0]]);
const opened = new Set([id]);
const queue = [id];
while (queue.length) {
const cur = queue.shift()!;
for (const e of this.in.get(cur) ?? []) {
if (!this.dep(e.type)) continue;
if (!seen.has(e.from)) seen.set(e.from, seen.get(cur)! + 1);
if (typeOnly(e) || opened.has(e.from)) continue;
opened.add(e.from);
queue.push(e.from);
}
}
seen.delete(id); return seen;
}
A place that uses something only as a type is included in the list, but the walk doesn't continue past it. Otherwise every file that imports one type would spread to everything that uses that file, and the list would grow uselessly large.
Here's how the graph answers the opening question. npm run onto -- impact field:recurrence reaches 30 nodes: 11 calculation functions that deal with repeats (including Google's toGoogle and fromGoogle, Outlook, CalDAV's writeUnits and the iPhone calendar adapter), 12 code names (including the three repeat fields of the sync value), one sync group and 6 tests.
It speaks up before you edit
A graph that's only used when someone thinks to ask gets forgotten fast. So the Claude Code sessions that build ikie have a hook. The moment a session is about to edit a file, the hook adds a short briefing: the rules, APIs, screens and database tables the file reaches, the tests to run, and the files that depend on it, nearest first. It's once per file per session, capped at 3 KB at a time. When the session finishes, the hook compares against the base graph and stops it once if there are new errors.
Every PR shows what changed, in meaning
A text diff shows "these lines changed". A graph diff shows "the relationship between these things changed". CI compares the PR's graph with the base graph the main build left behind. It groups changed relationships by their central node, shows how each impact size moved, and posts it all as one PR comment, along with newly introduced and newly fixed check errors. Pure moves are left out, so reviewers see only where the structure changed.
CI blocks gaps in the principles
With a graph, "this connection must exist" becomes something you can check. Here's what npm run onto -- check blocks.
- A database column not declared in the model. Every column needs a reason it's stored and its mapping to external calendars.
- An app policy rule with no implementation on a platform it declares, or with no scenario covering it.
- A rule whose implementation is called only by tests. That means the app isn't using it and is doing its own thing.
- A screen file that belongs to no screen feature, or a feature that exists on only one platform with neither a reason (differs) nor a to-do.
- A test that guards rules by reading files as text but doesn't say what it guards (
@guards). - An edge pointing at a node that doesn't exist.
We score the graph too
A plausible-looking list isn't necessarily a correct one. So we keep an answer key that people verified by reading the code. It has 27 questions with 32 answers that must appear, plus 10 answers that must not appear (over-reach), and every answer cites its evidence, usually down to the file and line.
{ id: "call-both", ask: "공통 만들기 API를 바꾸면", from: "route:POST /api/v1/items/new",
want: ["apps/web/lib/client/writes.ts", "apps/ios/Ikie/Model/BoardModel+Outbox.swift"],
why: "웹 writes.ts와 iOS BoardModel+Outbox.swift(client.createItem)가 부른다" },
(The question reads "if you change the shared create API", and the evidence says both the web's writes.ts and iOS's BoardModel+Outbox.swift call it.)
We started the key with questions the graph couldn't answer yet, so each improvement to the graph shows up as a score. Here are six stages.
The one we still miss is "changing the repeat-rule field should also reach the API document's rrule field". That's a value flowing from field to field, which edges that follow "who depends on whom" can't express. It's written down as a known limit. While answers found went up, the average size of an impact list went down from 206 to 108. It got more right while bloating less.
An answer key alone could just reward the questions we picked. So we also score against commit history: when a past commit changed a file, did the graph's impact list include the other files changed in the same commit? We set a baseline too, a simple predictor that picks "files that changed together at least twice before".
To be honest, on history the graph scores a little below the simple baseline. Many files that change together don't depend on each other in code: the web and iOS screens for the same feature, or docs and tests. So we don't use the graph to predict which files will change together. We use it to point out every place the code actually depends on, and we read the history score as a check that the list isn't losing or bloating as we change the graph.
Gaps the graph found
- Policy used only by tests. The day we added the "implementation called only by tests" check, it found three real gaps. iOS was comparing which board days to rewrite with its own code instead of the policy interpreter. The web had hard-coded the queue that sends board writes in order, instead of reading it from the policy. We made the app call the interpreter for those two, and the third was a rule only the web needs, so we corrected its declaration to web only.
- Color and travel time didn't reach the adapters. Changing the model's color field didn't bring up the Google or CalDAV adapters, because adapters read through the sync field type, not the model field. Adding an edge saying the sync field carries the model field connected them.
- The briefing never showed APIs. The hook's briefing looked for APIs under a node type that didn't exist in the graph, so the "APIs reached" line never appeared. Around the same time we found that the only iOS files in the graph were the ones reading screen features and policy, so changing an API never brought up the iOS files that call it.
- The widget's timeline linked to the app's timeline. Swift was connected by name alone, which produced 8 wrong edges, such as WidgetKit's
Timelineused by the widget linking to the app's timeline screen file. We limited edges to files in the same build target, and later looked up the receiving type through the syntax tree.
What we learned
Rules written in documents get forgotten, and rules kept by memory slip. The graph is built only from sources, so there are no hand-written facts to go stale. The checks block gaps in our principles in CI, and the answer key measures whether the graph itself is right. With all three in place, nobody has to remember to ask "did you look at this too?" The hook says it before the edit, and CI says it after the push. And we show the graph's below-baseline score on every PR without hiding it. To trust a tool, you have to know where it's wrong.