🕸️ aspark-graph

A lean, local knowledge graph that joins a repo's code to its delivery artifacts — so agents and humans can trace a user story to the code that implements it, and see the story-level blast radius of a change.

aspark-graph reads one repository — its source code and its aSPARK .spark/ delivery trail (specs, plans, reviews, QA reports) — and builds a single queryable graph, served over a CLI and an MCP server. It is deterministic (tree-sitter + declared artifact links; no LLM, no network) and disposable (the graph is a rebuildable read model, never a source of truth).

The two questions it exists to answer

Everything else is in service of these:

Related MCP server: NOMIK

Why this exists

When an AI agent (or the developer supervising it) works on an aSPARK-managed repo too large to hold in your head, those two questions are exactly the ones aSPARK's own review and QA gates depend on — and today the only way to answer them is Grep/Glob plus reading .spark/ files by hand.

The spec → plan → review → QA trail is machine-parseable, and it is linked to code by intent. But nothing joins the two, so an agent re-derives the link every time it greps: slowly, incompletely, and non-reproducibly. aspark-graph computes that join once, deterministically, and lets you query it.

It does this by deliberately doing less on the code side than a general code graph, and adding the one thing general graphs don't have: the delivery artifacts. That artifact layer is what makes story tracing, gate-aware impact, and orphan detection possible at all.

When to use it — and when not

• ✅ Use it on an aSPARK repo big enough that "read every relevant file" isn't viable, when you need a fast, reproducible answer before opening files.

• ❌ Skip it on a repo small enough to hold in your head (just read the files), or a repo with no .spark/ artifacts (the artifact layer is the whole point).

• 🤝 Want a broad semantic code graph too? Run Graphify alongside it — different scope, no conflict. aspark-graph is an accelerant for aSPARK, not a replacement for a code-search tool.

Using aspark-graph in aSPARK gates? See docs/aspark-integration.md for drop-in CLAUDE.md blocks that wire the /peer-review and /demo-day gates to the query tools.

The graph model (read this to interpret any result)

The graph is a typed, directed multigraph. Every node id is stable and deterministic, derived only from content and location, so two builds of an unchanged repo produce byte-identical ids and a byte-identical graph.json.

Node types

Edge types

Confidence tiers — every artifact/code link carries a tier, and impact reports the weakest link on the strongest path so you can trust a result appropriately:

Reading a result: an impact hit tagged inferred reached the story only through a git-history guess; a declared hit rests on an author-written link. The tier never raises confidence — it reports the weakest step, so an inferred edge can only ever lower a path's trust, never mask a real one.

Node id schemes (useful when constructing get_node/shortest_path queries):

file:<relpath>                     e.g. file:src/aspark_graph/queries.py
def:<relpath>::<qualname>          e.g. def:src/foo.py::Widget.render
feature:<name>                     e.g. feature:aspark-graph
story:<feature>:<id>               e.g. story:aspark-graph:US-1
ac:<feature>:<id>                  e.g. ac:aspark-graph:AC-1.2
task:<feature>:<id>                e.g. task:aspark-graph:T3
finding:<feature>:<id>             e.g. finding:aspark-graph:F1
qa:<feature>:<ac>#<index>          e.g. qa:aspark-graph:AC-1.1#0

Install

Requires Python ≥ 3.11 and uv. aspark-graph is not yet published to a package index, so install it from a checkout of this repository:

git clone https://github.com/a-lottes/aSPARK-graph.git aspark-graph
cd aspark-graph
uv sync                       # installs into a local .venv
uv run aspark-graph build .   # build the graph for the current repo

Add it to Claude Code as an MCP server, pointing at your checkout:

claude mcp add aspark-graph -- uv run --directory /path/to/aspark-graph aspark-graph serve

Until aspark-graph is published to a package index, the from-source path above is the supported install.

Build the graph

aspark-graph build [path]     # scans code + .spark/, writes .aspark-graph/graph.json

The graph is written to .aspark-graph/graph.json at the repo root (gitignore it — it's rebuildable). Re-running build on an unchanged repo produces a byte-identical graph. Parsing fails loudly on .spark/ template drift (it names the file and the mismatch) rather than silently guessing.

Query

Every query is available on both the CLI and MCP, and they return identical answers by construction (all query logic lives in one shared module; the CLI and server are thin adapters over it, and a parity test enforces it). Output is JSON.

CLI

# The two headline queries
aspark-graph query story_trace US-2 --feature my-feature
aspark-graph query impact src/foo.py src/bar.py
aspark-graph query impact --diff HEAD~1..HEAD      # blast radius of a change range

# Gate & freshness
aspark-graph query gate_health my-feature          # are this feature's ACs covered / passing?
aspark-graph query staleness                        # does the graph still match the repo on disk?

# Graph navigation
aspark-graph query get_node "file:src/foo.py"
aspark-graph query find_nodes Widget --type Class
aspark-graph query get_neighbors "story:my-feature:US-1" --edge-type has_ac
aspark-graph query shortest_path "task:my-feature:T1" "ac:my-feature:AC-1.1"

MCP

The same operations are exposed as MCP tools: build_graph, story_trace, impact, gate_health, staleness, get_node, find_nodes, get_neighbors, shortest_path. Querying before a build (or any domain error) returns a clean {"found": false, ...}-shaped result — never a raw traceback.

Linking code to stories

impact and story_trace are only as useful as the implements (task→code) links they can find. aspark-graph establishes those links three ways, strongest to weakest confidence:

Recommendation for aSPARK repos: make one commit per task whose message names the task and story ids (the convention aSPARK's own workflow already encourages). That alone lets impact answer on a repo that was never hand-annotated.

Inference is deterministic (it reads only committed state — file paths and message ids, never timestamps) and offline; if git is unavailable it is simply skipped. When multiple .spark/ features reuse the same T<n>/US-<n> numbering, a commit is resolved to a single feature before linking (by the .spark/<feature>/ tree it touched, or by a unique task→story pairing in its message); a genuinely ambiguous commit contributes no edge — an honest absence over a wrong cross-feature link.

Supported languages

Code extraction covers TypeScript/JavaScript, Python and Java (tree-sitter). Files in other languages are recorded as unparsed File nodes — the build never fails on an unknown language.

Design guarantees (why you can trust the output)

• Deterministic. Byte-identical rebuild on an unchanged repo; parse-affecting dependencies are pinned exactly; a double-build test enforces it.

• Offline & LLM-free. No network, no model calls — just AST parsing and artifact-template parsing.

• Fails loudly, never silently. Template drift raises a named error; it never skips or guesses.

• Clean errors. Domain errors (drift, graph-not-built) surface as one-line messages with a non-zero exit / a structured dict — never a stack trace.

• Disposable. The graph is a read model. Delete .aspark-graph/ and rebuild; the source of truth is always the code and the .spark/ files.

Out of scope (v0.1.0)

More languages, an LLM/natural-language layer, precise call-graph resolution, incremental updates, a visualization UI, exports (Neo4j/GraphML/Obsidian), and HTTP/team mode are all out of scope. See .spark/aspark-graph/spec.md for the full, honest Out-of-Scope list.

Development

uv sync --extra dev
uv run pytest

The project dogfoods itself: its own .spark/aspark-graph/ trail is the primary test fixture, so touching the parser or a query is checked against a real aSPARK trail.

License

MIT © Andreas Lottes. Part of the aSPARK product family. Code-graph prior art: Graphify — different scope.