akm-cli 0.7.5 → 0.8.0-rc.11

package/dist/indexer/ensure-index.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Auto-index: silently run an incremental `akm index` when the local index
  * is stale or absent, so that `search`, `show`, and `feedback` always operate
@@ -9,9 +12,67 @@
  * behind a single entry point.
  */
 import fs from "node:fs";
+import path from "node:path";
+import { ASSET_SPECS, TYPE_DIRS } from "../core/asset-spec";
 import { getDbPath } from "../core/paths";
 import { warn } from "../core/warn";
 import { closeDatabase, getEntryCount, getMeta, openExistingDatabase } from "./db";
+function getIndexableFiles(root, spec) {
+    if (!fs.existsSync(root))
+        return [];
+    const files = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name === ".stash.json")
+                continue;
+            const fullPath = path.join(current, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith("."))
+                    continue;
+                stack.push(fullPath);
+                continue;
+            }
+            if (entry.isFile() && spec.isRelevantFile(entry.name)) {
+                files.push(fullPath);
+            }
+        }
+    }
+    return files;
+}
+function hasNewerIndexableFiles(stashDir, builtAt) {
+    if (!builtAt)
+        return true;
+    const builtAtMs = new Date(builtAt).getTime();
+    if (!Number.isFinite(builtAtMs))
+        return true;
+    for (const [type, spec] of Object.entries(ASSET_SPECS)) {
+        const typeRoot = path.join(stashDir, TYPE_DIRS[type] ?? spec.stashDir);
+        const files = getIndexableFiles(typeRoot, spec);
+        for (const file of files) {
+            try {
+                if (fs.statSync(file).mtimeMs > builtAtMs)
+                    return true;
+            }
+            catch {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 /**
  * Check whether the local index is stale relative to the given stash directory.
  * Returns `true` when the index is missing, empty, or was built against a
@@ -27,6 +88,9 @@ export function isIndexStale(stashDir) {
         const entryCount = getEntryCount(db);
         if (entryCount === 0)
             return true;
+        const builtAt = getMeta(db, "builtAt");
+        if (hasNewerIndexableFiles(stashDir, builtAt))
+            return true;
         const storedStashDir = getMeta(db, "stashDir");
         if (storedStashDir !== stashDir) {
             // Check if the incoming stashDir appears in the stored stashDirs array

package/dist/indexer/file-context.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Flexible asset resolution system.
  *

package/dist/indexer/graph-boost.js

@@ -1,24 +1,43 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { loadStoredGraphMeta, loadStoredGraphSnapshot } from "./graph-db";
+function normalizeGraphName(value) {
+    return value.trim().toLowerCase();
+}
+let cachedParsedGraph;
 /**
- * Search-time graph-boost integration for the `akm index` graph pass (#207).
+ * Clear the module-level parsed-graph cache.
  *
- * This module is the consumer half of the graph-extraction pass. It loads
- * the persisted `graph.json` (when present) and exposes a single helper,
- * {@link computeGraphBoost}, that the existing FTS5+boosts loop in
- * `src/indexer/db-search.ts` calls per-entry to obtain an additive boost
- * value.
+ * The cache keeps the most recently parsed `ParsedGraphContext` keyed by
+ * (stashPath, generatedAt) tuples so back-to-back search invocations within
+ * the same process don't re-read the SQLite snapshot from disk. The cache
+ * persists across calls — which is the desired behaviour in production but
+ * pathological for tests that swap the underlying stash directory between
+ * test cases without bumping `generatedAt`. Such tests can observe stale
+ * graph nodes from a previous test's stash.
  *
- * CLAUDE.md / v1 spec compliance:
- *   - The graph signal feeds the **single** FTS5+boosts pipeline as one
- *     additive boost component. There is no parallel scoring track.
- *   - There is no second `SearchHit` scorer. `searchDatabase` continues to
- *     own ranking; this module just answers "what additive boost does the
- *     graph contribute for this (query, entry) pair?".
- *   - Missing/stale/unparseable `graph.json` → boost is `0`. The pipeline
- *     degrades gracefully to its non-graph behaviour, exactly as today.
+ * Tests (and any tooling that swaps stash backings) should call this between
+ * setups to guarantee the next `loadGraphBoostContext` reads fresh state.
+ * Recommended placement: `beforeEach` for test files that mutate graph
+ * state, or after `deleteStoredGraph` / `replaceStoredGraph` calls that
+ * intentionally invalidate the cache.
  */
-import fs from "node:fs";
-import { warn } from "../core/warn";
-import { GRAPH_FILE_SCHEMA_VERSION, getGraphFilePath } from "./graph-extraction";
+export function resetGraphBoostCache() {
+    cachedParsedGraph = undefined;
+}
+function resolveGraphBoostWeights(config) {
+    const configured = config?.search?.graphBoost;
+    return {
+        directBoostPerEntity: configured?.directBoostPerEntity ?? GRAPH_DIRECT_BOOST_PER_ENTITY,
+        directBoostCap: configured?.directBoostCap ?? GRAPH_DIRECT_BOOST_CAP,
+        hopBoostPerEntity: configured?.hopBoostPerEntity ?? GRAPH_HOP_BOOST_PER_ENTITY,
+        hopBoostCap: configured?.hopBoostCap ?? GRAPH_HOP_BOOST_CAP,
+        maxHops: Math.min(Math.max(configured?.maxHops ?? GRAPH_MAX_HOPS, 1), GRAPH_MAX_HOPS_HARD_CAP),
+        confidenceMode: configured?.confidenceMode ?? GRAPH_CONFIDENCE_MODE,
+        confidenceWeight: configured?.confidenceWeight ?? GRAPH_CONFIDENCE_WEIGHT,
+    };
+}
 /**
  * Per-entry weights, exposed as constants so tests can read them and so the
  * single-source-of-truth for "how much does the graph contribute" is here
@@ -29,20 +48,47 @@ export const GRAPH_DIRECT_BOOST_PER_ENTITY = 0.25;
 export const GRAPH_DIRECT_BOOST_CAP = 0.75;
 export const GRAPH_HOP_BOOST_PER_ENTITY = 0.1;
 export const GRAPH_HOP_BOOST_CAP = 0.3;
+export const GRAPH_MAX_HOPS = 1;
+export const GRAPH_CONFIDENCE_MODE = "blend";
+export const GRAPH_CONFIDENCE_WEIGHT = 0.2;
+const GRAPH_MAX_HOPS_HARD_CAP = 3;
+function normalizeConfidence(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return undefined;
+    return Math.max(0, Math.min(1, raw));
+}
+function combineConfidence(...parts) {
+    let out;
+    for (const part of parts) {
+        const value = normalizeConfidence(part);
+        if (value === undefined)
+            continue;
+        out = out === undefined ? value : out * value;
+    }
+    return out;
+}
+function toConfidenceMultiplier(rawConfidence, weights) {
+    if (weights.confidenceMode === "off")
+        return 1;
+    const confidence = normalizeConfidence(rawConfidence) ?? 1;
+    if (weights.confidenceMode === "multiply")
+        return confidence;
+    const blendWeight = Math.max(0, Math.min(1, weights.confidenceWeight));
+    return 1 - blendWeight + blendWeight * confidence;
+}
 /**
  * Load the graph file for a stash root and pre-compute everything that's
  * shared across all entries scored for one query. Returns `null` when:
- *   - `graph.json` does not exist.
- *   - The file fails to parse.
- *   - The schema version doesn't match (treated like "missing" so an old
- *     index keeps working until the next `akm index --full`).
+ *   - No graph snapshot exists in SQLite.
  *   - The query produces no token-level entity matches (no boost is
  *     possible, so we skip the per-entry overhead entirely).
  */
-export function loadGraphBoostContext(stashRoot, query) {
-    const graph = readGraphFile(stashRoot);
-    if (!graph)
+export function loadGraphBoostContext(stashRoot, query, config, db) {
+    const stashRoots = Array.isArray(stashRoot) ? stashRoot : [stashRoot];
+    const parsed = readParsedGraphContext(stashRoots, db);
+    if (!parsed)
         return null;
+    const weights = resolveGraphBoostWeights(config);
     const queryTokens = query
         .toLowerCase()
         .split(/[\s\-_/]+/)
@@ -53,20 +99,21 @@ export function loadGraphBoostContext(stashRoot, query) {
     // is small (capped per-asset at extract time) and lets the per-entry
     // path do a single set membership test.
     const allEntities = new Set();
-    const nodesByPath = new Map();
-    for (const node of graph.files) {
-        nodesByPath.set(node.path, node);
+    for (const node of parsed.graph.files) {
         for (const entity of node.entities)
             allEntities.add(entity);
     }
     // An entity matches the query when any of its sub-tokens equals or
-    // contains a query token. Cheap and forgiving — exact substring match is
-    // sufficient because both sides are already lower-cased at extract time.
+    // contains a query token. Matching is case-insensitive; the graph keeps
+    // canonical display strings and we normalize only for comparisons here.
     const matchedEntities = new Set();
     for (const entity of allEntities) {
-        const entityTokens = entity.split(/[\s\-_/]+/).filter(Boolean);
+        const normalizedEntity = normalizeGraphName(entity);
+        const entityTokens = normalizedEntity.split(/[\s\-_/]+/).filter(Boolean);
         for (const qt of queryTokens) {
-            if (entity === qt || entity.includes(qt) || entityTokens.some((et) => et === qt)) {
+            if (normalizedEntity === qt ||
+                normalizedEntity.includes(qt) ||
+                entityTokens.some((et) => et === qt || et.includes(qt))) {
                 matchedEntities.add(entity);
                 break;
             }
@@ -74,20 +121,47 @@ export function loadGraphBoostContext(stashRoot, query) {
     }
     if (matchedEntities.size === 0)
         return null;
-    // One-hop neighbours: any entity that appears on the other end of a
-    // relation whose other endpoint is in matchedEntities.
-    const oneHopEntities = new Set();
-    for (const node of graph.files) {
-        for (const rel of node.relations) {
-            if (matchedEntities.has(rel.from) && !matchedEntities.has(rel.to)) {
-                oneHopEntities.add(rel.to);
-            }
-            else if (matchedEntities.has(rel.to) && !matchedEntities.has(rel.from)) {
-                oneHopEntities.add(rel.from);
+    const connectedEntities = new Set();
+    const connectedConfidence = new Map();
+    const visited = new Set();
+    let frontier = new Map();
+    for (const entity of matchedEntities) {
+        const seed = parsed.entityConfidence.get(entity) ?? 1;
+        frontier.set(entity, seed);
+        visited.add(entity);
+    }
+    for (let hop = 1; hop <= weights.maxHops; hop += 1) {
+        const next = new Map();
+        for (const [entity, pathConfidence] of frontier.entries()) {
+            const neighbors = parsed.adjacency.get(entity);
+            if (!neighbors)
+                continue;
+            for (const [neighbor, edgeConfidence] of neighbors.entries()) {
+                const neighborPathConfidence = Math.max(0, Math.min(1, pathConfidence * edgeConfidence));
+                const currentBest = connectedConfidence.get(neighbor) ?? 0;
+                if (neighborPathConfidence > currentBest)
+                    connectedConfidence.set(neighbor, neighborPathConfidence);
+                if (visited.has(neighbor))
+                    continue;
+                visited.add(neighbor);
+                next.set(neighbor, Math.max(next.get(neighbor) ?? 0, neighborPathConfidence));
+                connectedEntities.add(neighbor);
             }
         }
+        if (next.size === 0)
+            break;
+        frontier = next;
     }
-    return { nodesByPath, matchedEntities, oneHopEntities };
+    return {
+        graph: parsed.graph,
+        nodesByPath: parsed.nodesByPath,
+        matchedEntities,
+        connectedEntities,
+        connectedConfidence,
+        entityConfidence: parsed.entityConfidence,
+        adjacency: parsed.adjacency,
+        weights,
+    };
 }
 /**
  * Compute the graph-boost contribution for a single scored entry.
@@ -100,80 +174,281 @@ export function computeGraphBoost(context, filePath) {
     const node = context.nodesByPath.get(filePath);
     if (!node)
         return 0;
-    let directHits = 0;
-    let hopHits = 0;
+    let directBoostRaw = 0;
+    let hopBoostRaw = 0;
     for (const entity of node.entities) {
-        if (context.matchedEntities.has(entity))
-            directHits += 1;
-        else if (context.oneHopEntities.has(entity))
-            hopHits += 1;
+        if (context.matchedEntities.has(entity)) {
+            const directConfidence = combineConfidence(node.confidence, context.entityConfidence.get(entity));
+            directBoostRaw +=
+                context.weights.directBoostPerEntity * toConfidenceMultiplier(directConfidence, context.weights);
+        }
+        else if (context.connectedEntities.has(entity)) {
+            const hopConfidence = combineConfidence(node.confidence, context.entityConfidence.get(entity), context.connectedConfidence.get(entity));
+            hopBoostRaw += context.weights.hopBoostPerEntity * toConfidenceMultiplier(hopConfidence, context.weights);
+        }
     }
-    const directBoost = Math.min(GRAPH_DIRECT_BOOST_CAP, directHits * GRAPH_DIRECT_BOOST_PER_ENTITY);
-    const hopBoost = Math.min(GRAPH_HOP_BOOST_CAP, hopHits * GRAPH_HOP_BOOST_PER_ENTITY);
+    const directBoost = Math.min(context.weights.directBoostCap, directBoostRaw);
+    const hopBoost = Math.min(context.weights.hopBoostCap, hopBoostRaw);
     return directBoost + hopBoost;
 }
+export function collectGraphRelatedHit(context, filePath) {
+    const node = context.nodesByPath.get(filePath);
+    if (!node)
+        return null;
+    const entities = [];
+    for (const entity of node.entities) {
+        if (context.matchedEntities.has(entity)) {
+            entities.push({
+                name: entity,
+                kind: "matched",
+                ...(context.entityConfidence.get(entity) !== undefined
+                    ? { confidence: context.entityConfidence.get(entity) }
+                    : {}),
+            });
+            continue;
+        }
+        if (context.connectedEntities.has(entity)) {
+            entities.push({
+                name: entity,
+                kind: "connected",
+                ...(context.connectedConfidence.get(entity) !== undefined
+                    ? { confidence: context.connectedConfidence.get(entity) }
+                    : {}),
+            });
+        }
+    }
+    if (entities.length === 0)
+        return null;
+    const relatedNames = new Set(entities.map((entity) => entity.name));
+    const relations = node.relations
+        .filter((relation) => relatedNames.has(relation.from) || relatedNames.has(relation.to))
+        .map((relation) => ({
+        from: relation.from,
+        to: relation.to,
+        ...(relation.type ? { type: relation.type } : {}),
+        ...(normalizeConfidence(relation.confidence) !== undefined
+            ? { confidence: normalizeConfidence(relation.confidence) }
+            : {}),
+    }));
+    return {
+        path: filePath,
+        type: node.type,
+        entities: entities.sort((a, b) => a.name.localeCompare(b.name)),
+        relations,
+    };
+}
 /**
- * Lightweight reader — extracted so the boost loader and tests share one
- * code path. Tolerant of missing files (returns null) but logs a warning
- * when an existing file fails to parse so corruption is visible.
+ * Find graph files that share entities with the given file.
+ *
+ * Implementation: SQL self-join on graph_file_entities, scoped by stash_root,
+ * grouped by entry_id, ordered by shared-entity count desc. Touches ~50-200
+ * rows instead of loading the entire snapshot into memory. Cold-call latency
+ * drops from ~30-60ms (full snapshot parse) to ~2-5ms on typical stashes.
+ *
+ * The returned `ref` field carries the canonical asset ref (`type:name`)
+ * resolved from entries.entry_key when the entry is indexed. Callers should
+ * fall back to formatting `path` when `ref` is undefined (orphan graph row).
  */
-function readGraphFile(stashRoot) {
-    const target = getGraphFilePath(stashRoot);
-    let raw;
+export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
+    if (!db) {
+        // Fallback: opening a transient DB here is not currently a use case (all
+        // callers pass a handle), so degrade to empty rather than reopening.
+        return [];
+    }
+    // Resolve target's entry_id from the stash_root + file_path. The graph rows
+    // are keyed on entry_id; without it we can't run the join.
+    let targetEntryId;
     try {
-        raw = fs.readFileSync(target, "utf8");
+        const row = db
+            .prepare("SELECT entry_id FROM graph_files WHERE stash_root = ? AND file_path = ? LIMIT 1")
+            .get(stashRoot, filePath);
+        targetEntryId = row?.entry_id;
     }
     catch {
-        // Missing → no boost. Not an error: the user simply hasn't enabled
-        // graph extraction yet, or the pass hasn't run.
-        return null;
+        return [];
     }
-    let parsed;
+    if (targetEntryId == null)
+        return [];
+    const effectiveLimit = Math.max(1, limit);
+    // Shared-entity count per candidate entry_id.
+    let candidateRows;
     try {
-        parsed = JSON.parse(raw);
+        candidateRows = db
+            .prepare(`SELECT gf.entry_id    AS entry_id,
+                gf.file_path   AS file_path,
+                gf.file_type   AS file_type,
+                COUNT(*)       AS shared
+            FROM graph_file_entities target
+            JOIN graph_file_entities e
+              ON e.stash_root = target.stash_root
+             AND e.entity_norm = target.entity_norm
+             AND e.entry_id  != target.entry_id
+            JOIN graph_files gf
+              ON gf.entry_id = e.entry_id
+          WHERE target.entry_id  = ?
+            AND target.stash_root = ?
+          GROUP BY gf.entry_id
+          ORDER BY shared DESC, gf.file_path ASC
+          LIMIT ?`)
+            .all(targetEntryId, stashRoot, effectiveLimit);
     }
-    catch (err) {
-        warn(`graph boost: failed to parse ${target}: ${err instanceof Error ? err.message : String(err)}`);
-        return null;
+    catch {
+        return [];
     }
-    if (!isGraphFile(parsed) || parsed.schemaVersion !== GRAPH_FILE_SCHEMA_VERSION) {
-        return null;
+    if (candidateRows.length === 0)
+        return [];
+    const candidateIds = candidateRows.map((r) => r.entry_id);
+    const placeholders = candidateIds.map(() => "?").join(",");
+    // Pull the shared entity names (joined by normalized casing) for display.
+    const sharedRows = db
+        .prepare(`SELECT e.entry_id AS entry_id, e.entity AS entity
+         FROM graph_file_entities e
+         JOIN graph_file_entities target
+           ON target.stash_root = e.stash_root
+           AND target.entity_norm = e.entity_norm
+         WHERE e.entry_id IN (${placeholders})
+           AND target.entry_id = ?
+           AND target.stash_root = ?`)
+        .all(...candidateIds, targetEntryId, stashRoot);
+    const sharedByEntry = new Map();
+    for (const row of sharedRows) {
+        let bucket = sharedByEntry.get(row.entry_id);
+        if (!bucket) {
+            bucket = new Set();
+            sharedByEntry.set(row.entry_id, bucket);
+        }
+        bucket.add(row.entity);
+    }
+    // Relation count for each candidate (relations where either endpoint
+    // matches one of the shared entities).
+    const relationCountByEntry = new Map();
+    const relationRows = db
+        .prepare(`SELECT entry_id, from_entity, to_entity
+         FROM graph_file_relations
+        WHERE entry_id IN (${placeholders})`)
+        .all(...candidateIds);
+    for (const row of relationRows) {
+        const shared = sharedByEntry.get(row.entry_id);
+        if (!shared)
+            continue;
+        if (shared.has(row.from_entity) || shared.has(row.to_entity)) {
+            relationCountByEntry.set(row.entry_id, (relationCountByEntry.get(row.entry_id) ?? 0) + 1);
+        }
     }
-    return parsed;
+    // Optional: ref lookup via entries.entry_key. entry_key is stored as
+    // `${stash_dir}:${type}:${name}` — strip the stash-dir prefix to get the
+    // user-facing `type:name`.
+    const refByEntryId = new Map();
+    try {
+        const entryRows = db
+            .prepare(`SELECT id, entry_key, stash_dir FROM entries WHERE id IN (${placeholders})`)
+            .all(...candidateIds);
+        for (const row of entryRows) {
+            const ref = stripStashPrefix(row.entry_key, row.stash_dir);
+            if (ref)
+                refByEntryId.set(row.id, ref);
+        }
+    }
+    catch {
+        /* ignore — refs are best-effort */
+    }
+    return candidateRows.map((row) => {
+        const sharedSet = sharedByEntry.get(row.entry_id) ?? new Set();
+        const sharedEntities = [...sharedSet].sort((a, b) => a.localeCompare(b));
+        const ref = refByEntryId.get(row.entry_id);
+        return {
+            ...(ref ? { ref } : {}),
+            path: row.file_path,
+            type: row.file_type,
+            sharedEntities,
+            relationCount: relationCountByEntry.get(row.entry_id) ?? 0,
+        };
+    });
 }
-function isGraphFile(value) {
-    if (typeof value !== "object" || value === null)
-        return false;
-    const obj = value;
-    if (typeof obj.schemaVersion !== "number")
-        return false;
-    if (typeof obj.generatedAt !== "string")
-        return false;
-    if (typeof obj.stashRoot !== "string")
-        return false;
-    if (!Array.isArray(obj.files))
-        return false;
-    for (const f of obj.files) {
-        if (typeof f !== "object" || f === null)
-            return false;
-        const node = f;
-        if (typeof node.path !== "string")
-            return false;
-        if (typeof node.type !== "string")
-            return false;
-        if (!Array.isArray(node.entities) || !node.entities.every((e) => typeof e === "string"))
-            return false;
-        if (!Array.isArray(node.relations))
-            return false;
-        for (const r of node.relations) {
-            if (typeof r !== "object" || r === null)
-                return false;
-            const rel = r;
-            if (typeof rel.from !== "string" || typeof rel.to !== "string")
-                return false;
-            if (rel.type !== undefined && typeof rel.type !== "string")
-                return false;
+/**
+ * Convert an entries.entry_key to a user-facing asset ref. Entry keys are
+ * stored as `${stash_dir}:${type}:${name}`; strip the stash-dir prefix.
+ */
+function stripStashPrefix(entryKey, stashDir) {
+    const prefix = `${stashDir}:`;
+    if (entryKey.startsWith(prefix))
+        return entryKey.slice(prefix.length);
+    // Fall back to last two colon-separated segments.
+    const lastColon = entryKey.lastIndexOf(":");
+    if (lastColon < 0)
+        return entryKey;
+    const prevColon = entryKey.lastIndexOf(":", lastColon - 1);
+    if (prevColon < 0)
+        return entryKey;
+    return entryKey.slice(prevColon + 1);
+}
+/**
+ * Load and normalize graph data from SQLite once, then reuse it across all
+ * per-entry boost lookups in the current query.
+ */
+function readParsedGraphContext(stashRoots, db) {
+    const sortedRoots = [...new Set(stashRoots)].sort((a, b) => a.localeCompare(b));
+    if (sortedRoots.length === 0)
+        return null;
+    const metas = sortedRoots
+        .map((stashRoot) => loadStoredGraphMeta(stashRoot, db))
+        .filter((meta) => meta !== null);
+    if (metas.length === 0)
+        return null;
+    const cacheKey = metas.map((meta) => `${meta.stashPath}\u0000${meta.generatedAt}`).join("\u0001");
+    if (cachedParsedGraph && cachedParsedGraph.cacheKey === cacheKey)
+        return cachedParsedGraph.context;
+    const snapshots = metas
+        .map((meta) => loadStoredGraphSnapshot(meta.stashPath, db))
+        .filter((snapshot) => snapshot !== null);
+    if (snapshots.length === 0)
+        return null;
+    const graph = {
+        schemaVersion: Math.max(...snapshots.map((snapshot) => snapshot.schemaVersion)),
+        generatedAt: snapshots
+            .map((snapshot) => snapshot.generatedAt)
+            .sort()
+            .at(-1) ?? new Date(0).toISOString(),
+        stashRoot: snapshots[0]?.stashPath ?? "",
+        files: snapshots.flatMap((snapshot) => snapshot.files),
+        entities: [...new Set(snapshots.flatMap((snapshot) => snapshot.entities))],
+        relations: snapshots.flatMap((snapshot) => snapshot.relations),
+    };
+    const nodesByPath = new Map();
+    const entityConfidence = new Map();
+    const adjacency = new Map();
+    function setBestEntityConfidence(entity, confidence) {
+        const normalized = normalizeConfidence(confidence);
+        if (normalized === undefined)
+            return;
+        const current = entityConfidence.get(entity);
+        if (current === undefined || normalized > current)
+            entityConfidence.set(entity, normalized);
+    }
+    function setBestEdgeConfidence(from, to, confidence) {
+        const normalized = normalizeConfidence(confidence);
+        if (!adjacency.has(from))
+            adjacency.set(from, new Map());
+        const neighbors = adjacency.get(from);
+        if (!neighbors)
+            return;
+        const current = neighbors.get(to);
+        const next = normalized ?? 1;
+        if (current === undefined || next > current)
+            neighbors.set(to, next);
+    }
+    for (const node of graph.files) {
+        nodesByPath.set(node.path, node);
+        for (const entity of node.entities) {
+            setBestEntityConfidence(entity, node.confidence);
+        }
+        for (const rel of node.relations) {
+            const edgeConfidence = combineConfidence(node.confidence, rel.confidence);
+            setBestEdgeConfidence(rel.from, rel.to, edgeConfidence);
+            setBestEdgeConfidence(rel.to, rel.from, edgeConfidence);
         }
     }
-    return true;
+    const context = { graph, nodesByPath, entityConfidence, adjacency };
+    cachedParsedGraph = { cacheKey, context };
+    return context;
 }