Spine

Turn any repository into a queryable Program Knowledge Graph — symbols, calls, imports, database schema, and documentation, as universal facts that carry provenance back to the line they came from.

Everything here is deterministic and model-free — extraction and the synthesis on top of it. The same commit in always yields the same bytes out, so the output is diffable, cacheable, and safe to gate CI on.

pip install 'spine-pkg[all]'
spine understand .        # writes episteme/ — a code-true knowledge base
spine state .             # what this repo is today, and how healthy
spine extract . -q handleRequest   # who calls it, and what it touches

Because understand is deterministic, spine understand --check belongs in CI: it re-renders and diffs against the committed episteme, exiting non-zero when the docs and the code have drifted apart. That makes the knowledge base provably current rather than hopefully current.

Commands

Languages

Python works out of the box with no extra dependencies. Every other front-end lazy-imports its parser, so the base install stays small and you pay only for what you use:

pip install 'spine-pkg[java]'        # or typescript, csharp, c, cpp, go, sql
pip install 'spine-pkg[all]'         # every front-end at once

If a language's extra isn't installed, its files are invisible to the graph rather than an error — so spine extract counts them and tells you what to install:

Scanned . — 0 grounded nodes, 0 external, 0 edges.

  ! 103 Go file(s) found but NOT extracted — install the front-end:  pip install 'spine-pkg[go]'

spine languages shows the same thing ahead of time. Both warnings go to stderr, so extract --json and export stay pipe-safe.

Documents and media

Markdown, reStructuredText, plain text, and HTML parse with the standard library. PDF needs [docs]; Word and Excel need [office].

spine media extract is deliberately separate from the graph build. It MAY run a model and be slow, so it is explicit and opt-in: it creates a .spine-media directory on first run, writes reviewable artifacts there for you to commit, and the deterministic extractor only ever reads those. Image OCR ([media], plus a system tesseract binary) and --asr local ([asr]) run entirely on your machine. --asr api uploads audio and video off-machine and refuses to run without an explicit --allow-remote.

Caching

Facts are cached per commit under ~/.cache/spine/, and the cache is trusted only on a clean working tree — a dirty tree always re-extracts, because a stale graph is worse than a slow one.

Design notes

• The graph is the source of truth. Consumers render facts; they never re-derive them from paths or filenames. A new fact means extending facts.py and the front-ends, not the renderer.
• Bounded output is honest output. Aggregations cap their results and record what was elided. Exports are the exception — they are always complete, because the point of handing the graph to another tool is that its filtering is better than ours.
• Local paths only. spine scans a checkout on disk and never clones for you.
• Calls resolve where the source states a type. A method called on a variable binds when that variable has a parameter or assignment annotation, or comes from a constructor for a class in the same module. A union of two real types, a rebound variable, or a with target resolves to nothing — a fabricated edge is worse than a missing one. Annotating a local is what makes its calls visible, which is a good reason to annotate it.

License

MIT