How index works

What it does for you

index reads a repository or a whole workspace and draws its shape: which modules import which, who calls a function, and how repositories depend on each other, with the file and line behind every edge. It writes one self-contained HTML file per view, with no server, account, model or network. A wiki it writes is sealed to the commit, and a later check tells you whether the code still matches it.

Edges with a witnessEvery dependency edge records the file, line and import text that shows it.
A wiki with no prose to inventindex wiki derives its pages from the extracted graph and writes no generated prose.
Re-check a map laterindex wiki --verify answers MATCH, DRIFT or UNVERIFIABLE, with exit codes 0, 1 and 2.
Architecture as a testDeclare the shape you meant in .index.toml, and index check fails when the code breaks it.

Source: README.md at 50069a8 (release 2.16.0)

Watch

Re-derive it. Don't take it on trust. (2 min 5 s, narrated, captioned). Index re-derives its sealed wiki from the code and says when the two disagree. Transcript, sources and recall questions.

Video walkthrough: coming with the next release.

How it works, one step at a time

Scroll, or use the step buttons. The panel follows a three-module Python package, shop, built for this page: web calls service, which calls core. Every line is output from index at commit 50069a8, run offline.

01
A small package to map

shop has three modules. core prices an order, service imports it to quote, and web imports service to answer a request. The intended direction runs one way: web, then service, then core.

Source: the package written for this page; README.md, "What it does"
02
Every edge cites its line

index internals reads the real imports. It finds four modules and two internal edges, and each edge carries the file, the line and the import text. Coverage is marked complete: no parse errors and no dynamic imports it could not follow.

Source: src/index_graph/internals
03
Who calls this function?

index symbols price --refs resolves references from the call graph. One caller: quote in service.py, line 5. A reference it cannot resolve comes back empty; it never guesses a jump.

Source: src/index_graph/symbols
04
Write a sealed wiki

index wiki writes one HTML file: an overview, a page per module with its imports and dependents, a page per function with callers and callees, and an architecture diagram drawn from the graph. It is pinned to the commit and sealed.

Verify it against the tree it was made from: 10 pages, 4 edges, MATCH.

Source: src/index_graph/wiki
05
Someone adds a back-import

Now core.py imports handler from web. The graph gains an edge that closes a loop: core, service, web, back to core.

index internals --cycles names the cycle. Nothing else had to be told what to look for.

Source: src/index_graph/internals
06
The rule you declared fails the build

.index.toml declares max_cycles = 0. Before the back-import, index check --internals reported MATCH with no findings. Now it reports DRIFT and exits 1, so it can sit in CI.

The rules file can also declare layers between repositories, forbidden imports and required ones.

Source: src/index_graph/arch; README.md, the section on index check
07
The sealed wiki now disagrees with the code

Verify the old wiki against the changed tree and it reads DRIFT: its diagram and overview show structure the code no longer has. Remove the back-import and it reads MATCH again. Delete the file and it reads UNVERIFIABLE, exit 2, because there is nothing to check.

Source: src/index_graph/wiki; README.md, "Try it in 5 minutes"

Walkthrough

Install it, run it once, then use the main feature. Each command below is real, and so is its output.

Install
Install from PyPI. Python 3.11 or newer; everything runs offline.
```
$ pip install index-graph
```
First run: write a sealed wiki
Map one repository into an offline wiki whose pages and edges are sealed.
```
$ index wiki --root . --out wiki.html
wrote wiki.html
```
Verify it against the code
Later, verify the wiki against the code as it is now.
```
$ index wiki --verify wiki.html --root .
verdict=MATCH pages=10 edges=4
```

Ask who calls a function

Every edge cites the file and line it came from.

$ index symbols price --root . --refs
symbol query: price  (repo shop)
references (1 resolved, 0 unresolved):
  shop/service::quote  shop/service.py:5  [cross_module, moderate]

The verify line shows the result for the shop package above. Output from index at 50069a8, run from source; index-graph 2.16.0 is the current PyPI release.

What it does not do

index maps structure from imports and manifests. It does not run the code, so behaviour that only appears at runtime is outside the map.
Dynamic imports are listed in the coverage record when found. An import built from a string at runtime may still be missed.
Symbol navigation covers Python. Other ecosystems are mapped at the module and repository level.
The LSP server's fast path trusts unchanged file metadata for two seconds, so an edit that restores size and timestamp inside that window can go unnoticed.
A MATCH says the map agrees with the tree. It does not say the architecture is a good one.

Source: README.md at 50069a8, "What it does" and "The surfaces"

Check what stuck

Answer each one in your head before you open it.

What does an edge in index's graph carry besides its two ends?

The file, the line and the import text that shows it.

Why does index wiki write no prose?

Its pages are derived from the graph it extracted, so there is no generated text that could describe structure that is not there.

After a back-import, why do both index check and the wiki verify fail?

The check finds a cycle above the declared ceiling of 0. The wiki's diagram and overview no longer match the graph of the changed tree.

What exit code does wiki --verify give for a missing file, and why not 1?

2, UNVERIFIABLE. There is nothing to compare, which is different from a comparison that disagrees.

What it does for you

Watch

How it works, one step at a time

A small package to map

Every edge cites its line

Who calls this function?

Write a sealed wiki

Someone adds a back-import

The rule you declared fails the build

The sealed wiki now disagrees with the code

Walkthrough

Install

First run: write a sealed wiki

Verify it against the code

Ask who calls a function

What it does not do

Check what stuck