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.

Extraction is deterministic and model-free. The same commit in always yields the same facts out, so the output is diffable, cacheable, and safe to gate CI on.

pip install spine-pkg
spine extract .

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