Import Graph

You are working on the import graph system — static analysis that parses JS/TS and Python source files to produce dependency graphs, plus persistence/query layers for runtime use.

Domain purpose

The graph turns raw source into a queryable map of "what depends on what" so other aspens features (doc-init, doc-sync, doc-impact, the graph context hook) can rank files by importance, surface hubs, detect domain clusters, and inject just the relevant neighborhood into prompts. It is the substrate that makes context generation deterministic and code-aware rather than guess-based.

Key Concepts

graph-builder.js — buildRepoGraph(repoPath, languages?) runs a 9-step pipeline:

1. Walk source files → 2. Parse imports → 3. Reverse edges → 4. Git churn → 5. Per-file metrics → 6. Priority ranking → 7. Hub detection → 8. Domain clustering → 9. Hotspots

graph-persistence.js — Persistence and query layer:

• serializeGraph() converts raw graph to indexed format (O(1) lookups, file→cluster mapping)
• persistGraphArtifacts(repoPath, rawGraph, options?) writes .claude/graph.json + .claude/code-map.md + .claude/graph-index.json + auto-gitignores them. Target-aware: if options.target.supportsGraph === false, returns serialized data without writing files.
• extractSubgraph(graph, filePaths) returns 1-hop neighborhood of mentioned files + relevant hubs/hotspots/clusters
• formatNavigationContext(subgraph) renders compact markdown (~50 line budget) for prompt injection
• extractFileReferences(prompt, graph) tiered extraction: explicit paths → bare filenames → cluster keywords
• generateCodeMap() / writeCodeMap() standalone overview for graph hook consumption — emits a Domain clusters block (via formatDomainClusters) and framework entry points only; cross-domain coupling, hotspots, and the totals/date footer are intentionally omitted because they churn on every sync
• formatDomainClusters(clusters, files) — exported helper that renders the canonical Domain clusters block: clusters are merged by label, single-file clusters dropped, files per cluster capped at 5 and sorted by fanIn desc then path asc for sync stability; no per-cluster (N files) counts
• generateGraphIndex() / saveGraphIndex() tiny inverted index (export names → files, hub basenames, cluster labels)

doc-graph.js — Target-aware: reads .aspens.json config, passes target to persistGraphArtifacts(). Shows different completion message for Codex target (artifacts not written).

Critical Rules

• await init before any parseJsImports call. es-module-lexer requires WASM initialization.
• Priority formula is load-bearing: fanIn * 3.0 + exportCount * 1.5 + (isEntry ? 10.0 : 0) + churn * 2.0 + (1/(depth+1)) * 1.0. Downstream consumers depend on this ranking.
• All paths are repo-relative strings, never absolute. Resolution functions convert abs→relative.
• Graph artifacts are gitignored — ensureGraphGitignore() (internal to persistence) adds .claude/graph.json, .claude/graph-index.json, .claude/code-map.md to prevent commit loops.
• Graph artifacts are Claude-only — when target has supportsGraph: false, persistGraphArtifacts returns serialized data for embedding (e.g., condensed code-map in root AGENTS.md) but writes no files.
• Errors are swallowed, not thrown in graph-builder — parse failures return empty/null. The graph must always complete.
• extractSubgraph logic is mirrored in graph-context-prompt.mjs (buildNeighborhood()). Keep both in sync.
• doc-sync rebuilds graph on every sync — calls buildRepoGraph + persistGraphArtifacts (with target) to keep it fresh.
• Code-map output is sync-stable — no totals, no dates, no hotspot churn counts, no +N more suffixes. Anything that varies between syncs without a real code change must stay out of generated context.

References

• Hook mirror: src/templates/hooks/graph-context-prompt.mjs

Last Updated: 2026-05-11