@dreamtree-org/graphify 1.2.0 → 1.4.0

package/dist/index.d.cts

@@ -172,6 +172,30 @@ declare function renderReport(graph: Graph, analysis: Analysis, now?: Date): str
  */
 declare function exportGraph(graph: Graph, options: ExportOptions, report?: string): Promise<void>;
 
+/**
+ * Graphology's node-link JSON — exactly the shape `graph.json` has always
+ * contained, derived from Graph#export() rather than imported from
+ * graphology-types so consumers of our .d.ts don't need that package.
+ */
+type SerializedGraph = ReturnType<Graph['export']>;
+/**
+ * Where a graph lives between runs. Graphify defines the interface and
+ * ships LocalFileGraphStore (the classic graphify-out/ behavior); callers
+ * that persist graphs elsewhere — a DB row, an object-store key, anything
+ * that can hold JSON — implement it over their own storage with
+ * serializeGraph()/deserializeGraph(). Graphify never instantiates a
+ * remote store itself (see docs/KB-PROVIDER.md).
+ *
+ * `ref` is an opaque caller-defined locator. For LocalFileGraphStore it is
+ * an outDir path; for a provider it is whatever routes to one graph, e.g.
+ * `${companyId}/${knowledgeBaseId}`.
+ */
+interface GraphStore {
+    /** Resolves null when no graph exists yet at `ref` — not an error. */
+    load(ref: string): Promise<Graph | null>;
+    save(ref: string, graph: Graph): Promise<void>;
+}
+
 interface PipelineOptions {
     /** Where to write graph.json/graph.html/GRAPH_REPORT.md. Defaults to `<root>/graphify-out`. */
     outDir?: string;
@@ -197,6 +221,13 @@ interface PipelineOptions {
     update?: boolean;
     /** Called with a short progress message after each stage (e.g. for CLI stderr output). */
     onProgress?: (message: string) => void;
+    /**
+     * Also save the built graph through a caller-supplied GraphStore (e.g. a
+     * DB-backed store — see docs/KB-PROVIDER.md), in addition to the regular
+     * graphify-out/ export. Keyed by `storeRef` (defaults to the outDir path).
+     */
+    store?: GraphStore;
+    storeRef?: string;
 }
 interface PipelineResult {
     manifest: FileManifest;
@@ -215,12 +246,35 @@ declare function runPipeline(root: string, options?: PipelineOptions): Promise<P
 
 /**
  * Load a previously-exported graph.json back into a graphology Graph.
- * Always goes through security.validateGraphPath() (path-traversal guard —
- * see SECURITY.md) so a caller-supplied `outDir`/CLI arg can never make
- * this read outside the graphify-out/ directory it resolves to.
+ * Thin wrapper over LocalFileGraphStore (which enforces the path-traversal
+ * guard — see SECURITY.md) that throws when no graph exists, because every
+ * CLI/MCP caller treats "no graph yet" as a hard error. Library callers who
+ * want the null-on-missing contract should use a GraphStore directly.
  */
 declare function loadGraph(outDir?: string): Promise<Graph>;
 
+/**
+ * The reference GraphStore: one graph.json per directory, `ref` = the
+ * outDir path. Reproduces the classic graphify-out/ behavior byte-for-byte
+ * (same pretty-printed JSON exportGraph() writes) and routes every path
+ * through security.validateGraphPath(), so a caller-supplied ref — or a
+ * symlinked graph.json — can never read or write outside the directory it
+ * resolves to.
+ */
+declare class LocalFileGraphStore implements GraphStore {
+    load(ref: string): Promise<Graph | null>;
+    save(ref: string, graph: Graph): Promise<void>;
+}
+
+/**
+ * The stable serialization contract for graphs at rest: graphology's
+ * node-link JSON. exportGraph() has always written exactly this shape to
+ * graph.json, so anything serialized here stays loadable by every existing
+ * consumer (and vice versa).
+ */
+declare function serializeGraph(graph: Graph): SerializedGraph;
+declare function deserializeGraph(data: SerializedGraph): Graph;
+
 interface NodeMatch {
     id: string;
     label: string;
@@ -304,6 +358,73 @@ interface ExplainResult {
 /** Plain-language-ready explanation of the node that best matches `query`. */
 declare function explainNode(graph: Graph, query: string): ExplainResult | null;
 
+/**
+ * Graph-augmented retrieval (docs/KB-PROVIDER.md §4): the caller has
+ * already done similarity search (vector, keyword, hybrid — their
+ * pipeline, their embeddings); expandRetrieval() takes those hits and adds
+ * what similarity can't see — the nodes *structurally connected* to them.
+ * Pure and synchronous like every query function: Graph in, data out; no
+ * store access, no embedding calls.
+ */
+/**
+ * One hit from the caller's own search. `nodeId` when the caller stored
+ * graph node ids alongside its records at ingest time; otherwise `text`,
+ * resolved against the graph lexically (same resolver queryGraph uses).
+ */
+interface RetrievalHit {
+    nodeId?: string;
+    text?: string;
+    /** The caller's similarity score, echoed through to rank seeds. */
+    score?: number;
+}
+interface ExpandOptions {
+    /** Approximate cap, in tokens (~4 chars each), on the result. Default 2000. */
+    tokenBudget?: number;
+    maxHops?: number;
+    /** Restrict traversal (and reported edges) to these relations, e.g. ['contains', 'references']. */
+    relations?: Relation[];
+}
+interface ExpandedNode {
+    id: string;
+    label: string;
+    /** Node kind attr (chunk|section|entity|document|...) — absent on classic code nodes. */
+    kind?: string;
+    sourceFile: string;
+    sourceLocation: string;
+    /** 0 = was a seed (or an unresolvable hit echoed through). */
+    hops: number;
+    /** The edge that first led the traversal here (absent for seeds). */
+    via?: TraversalEdge;
+    /** The caller's similarity score — seeds only. */
+    seedScore?: number;
+}
+interface ExpandedContext {
+    /**
+     * Union of seed nodes and discovered neighbors, ranked: seeds first (by
+     * caller score desc), then by (hops asc, degree desc). Deduped across
+     * seeds. Hits that resolve to no graph node are echoed through with
+     * hops 0 and no expansion, so adopting this on a partially-ingested
+     * corpus never does worse than flat retrieval.
+     */
+    nodes: ExpandedNode[];
+    /** Every edge between included nodes — provenance for citations. */
+    edges: TraversalEdge[];
+    communities: Array<{
+        id: number;
+        label: string;
+        seedCount: number;
+    }>;
+    /** True when the token budget stopped the traversal before the frontier was exhausted. */
+    truncated: boolean;
+}
+/**
+ * Expand the caller's top-K hits through the graph: one joint,
+ * token-budgeted BFS seeded from every hit at once, so overlapping
+ * neighborhoods dedupe and the budget is shared across seeds. Deterministic
+ * (lexical neighbor order, stable ranking) like the rest of the query layer.
+ */
+declare function expandRetrieval(graph: Graph, hits: RetrievalHit[], options?: ExpandOptions): ExpandedContext;
+
 interface AffectedNode {
     id: string;
     label: string;
@@ -651,4 +772,4 @@ declare class ExtractionValidationError extends Error {
  */
 declare function validateExtraction(value: unknown, context?: string): ExtractionResult;
 
-export { type AffectedNode, type Analysis, type ChangedSymbol, type ClusterAlgorithm, type ClusterOptions, type Confidence, type ContextOptions, type ContextPack, type ContextSnippet, type DependencyRule, type DsnQueryFn, EXTRACTOR_REGISTRY, type ExplainResult, type ExportOptions, ExtractionCache, type ExtractionResult, ExtractionResultSchema, ExtractionValidationError, type ExtractionValidationIssue, type FileCategory, type FileManifest, type GraphDiff, type GraphEdge, type GraphNode, type ImpactOptions, type ImpactResult, type MergeEntry, type NodeMatch, type PathResult, type PipelineOptions, type PipelineResult, type QueryOptions, type QueryResult, type ReflectOptions, type Relation, type ResolveStats, type ResultOutcome, type ResultType, type RewiredSymbol, type RulesConfig, type SavedResult, type TestSelection, type TraversalEdge, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, diffGraphs, explainNode, exportGraph, extract, extractMysql, globToRegExp, graphForDirectory, isTestFile, loadGraph, loadResults, mergeGraphs, queryGraph, rankForTask, renderContextPack, renderLessons, renderReport, renderReview, resolveCrossFileReferences, resolveNode, reviewRevisions, runPipeline, saveResult, scoreNodes, shortestPath, testsForChangedFiles, testsForNode, validateExtraction, validateRules };
+export { type AffectedNode, type Analysis, type ChangedSymbol, type ClusterAlgorithm, type ClusterOptions, type Confidence, type ContextOptions, type ContextPack, type ContextSnippet, type DependencyRule, type DsnQueryFn, EXTRACTOR_REGISTRY, type ExpandOptions, type ExpandedContext, type ExpandedNode, type ExplainResult, type ExportOptions, ExtractionCache, type ExtractionResult, ExtractionResultSchema, ExtractionValidationError, type ExtractionValidationIssue, type FileCategory, type FileManifest, type GraphDiff, type GraphEdge, type GraphNode, type GraphStore, type ImpactOptions, type ImpactResult, LocalFileGraphStore, type MergeEntry, type NodeMatch, type PathResult, type PipelineOptions, type PipelineResult, type QueryOptions, type QueryResult, type ReflectOptions, type Relation, type ResolveStats, type ResultOutcome, type ResultType, type RetrievalHit, type RewiredSymbol, type RulesConfig, type SavedResult, type SerializedGraph, type TestSelection, type TraversalEdge, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, deserializeGraph, diffGraphs, expandRetrieval, explainNode, exportGraph, extract, extractMysql, globToRegExp, graphForDirectory, isTestFile, loadGraph, loadResults, mergeGraphs, queryGraph, rankForTask, renderContextPack, renderLessons, renderReport, renderReview, resolveCrossFileReferences, resolveNode, reviewRevisions, runPipeline, saveResult, scoreNodes, serializeGraph, shortestPath, testsForChangedFiles, testsForNode, validateExtraction, validateRules };

package/dist/index.d.ts

@@ -172,6 +172,30 @@ declare function renderReport(graph: Graph, analysis: Analysis, now?: Date): str
  */
 declare function exportGraph(graph: Graph, options: ExportOptions, report?: string): Promise<void>;
 
+/**
+ * Graphology's node-link JSON — exactly the shape `graph.json` has always
+ * contained, derived from Graph#export() rather than imported from
+ * graphology-types so consumers of our .d.ts don't need that package.
+ */
+type SerializedGraph = ReturnType<Graph['export']>;
+/**
+ * Where a graph lives between runs. Graphify defines the interface and
+ * ships LocalFileGraphStore (the classic graphify-out/ behavior); callers
+ * that persist graphs elsewhere — a DB row, an object-store key, anything
+ * that can hold JSON — implement it over their own storage with
+ * serializeGraph()/deserializeGraph(). Graphify never instantiates a
+ * remote store itself (see docs/KB-PROVIDER.md).
+ *
+ * `ref` is an opaque caller-defined locator. For LocalFileGraphStore it is
+ * an outDir path; for a provider it is whatever routes to one graph, e.g.
+ * `${companyId}/${knowledgeBaseId}`.
+ */
+interface GraphStore {
+    /** Resolves null when no graph exists yet at `ref` — not an error. */
+    load(ref: string): Promise<Graph | null>;
+    save(ref: string, graph: Graph): Promise<void>;
+}
+
 interface PipelineOptions {
     /** Where to write graph.json/graph.html/GRAPH_REPORT.md. Defaults to `<root>/graphify-out`. */
     outDir?: string;
@@ -197,6 +221,13 @@ interface PipelineOptions {
     update?: boolean;
     /** Called with a short progress message after each stage (e.g. for CLI stderr output). */
     onProgress?: (message: string) => void;
+    /**
+     * Also save the built graph through a caller-supplied GraphStore (e.g. a
+     * DB-backed store — see docs/KB-PROVIDER.md), in addition to the regular
+     * graphify-out/ export. Keyed by `storeRef` (defaults to the outDir path).
+     */
+    store?: GraphStore;
+    storeRef?: string;
 }
 interface PipelineResult {
     manifest: FileManifest;
@@ -215,12 +246,35 @@ declare function runPipeline(root: string, options?: PipelineOptions): Promise<P
 
 /**
  * Load a previously-exported graph.json back into a graphology Graph.
- * Always goes through security.validateGraphPath() (path-traversal guard —
- * see SECURITY.md) so a caller-supplied `outDir`/CLI arg can never make
- * this read outside the graphify-out/ directory it resolves to.
+ * Thin wrapper over LocalFileGraphStore (which enforces the path-traversal
+ * guard — see SECURITY.md) that throws when no graph exists, because every
+ * CLI/MCP caller treats "no graph yet" as a hard error. Library callers who
+ * want the null-on-missing contract should use a GraphStore directly.
  */
 declare function loadGraph(outDir?: string): Promise<Graph>;
 
+/**
+ * The reference GraphStore: one graph.json per directory, `ref` = the
+ * outDir path. Reproduces the classic graphify-out/ behavior byte-for-byte
+ * (same pretty-printed JSON exportGraph() writes) and routes every path
+ * through security.validateGraphPath(), so a caller-supplied ref — or a
+ * symlinked graph.json — can never read or write outside the directory it
+ * resolves to.
+ */
+declare class LocalFileGraphStore implements GraphStore {
+    load(ref: string): Promise<Graph | null>;
+    save(ref: string, graph: Graph): Promise<void>;
+}
+
+/**
+ * The stable serialization contract for graphs at rest: graphology's
+ * node-link JSON. exportGraph() has always written exactly this shape to
+ * graph.json, so anything serialized here stays loadable by every existing
+ * consumer (and vice versa).
+ */
+declare function serializeGraph(graph: Graph): SerializedGraph;
+declare function deserializeGraph(data: SerializedGraph): Graph;
+
 interface NodeMatch {
     id: string;
     label: string;
@@ -304,6 +358,73 @@ interface ExplainResult {
 /** Plain-language-ready explanation of the node that best matches `query`. */
 declare function explainNode(graph: Graph, query: string): ExplainResult | null;
 
+/**
+ * Graph-augmented retrieval (docs/KB-PROVIDER.md §4): the caller has
+ * already done similarity search (vector, keyword, hybrid — their
+ * pipeline, their embeddings); expandRetrieval() takes those hits and adds
+ * what similarity can't see — the nodes *structurally connected* to them.
+ * Pure and synchronous like every query function: Graph in, data out; no
+ * store access, no embedding calls.
+ */
+/**
+ * One hit from the caller's own search. `nodeId` when the caller stored
+ * graph node ids alongside its records at ingest time; otherwise `text`,
+ * resolved against the graph lexically (same resolver queryGraph uses).
+ */
+interface RetrievalHit {
+    nodeId?: string;
+    text?: string;
+    /** The caller's similarity score, echoed through to rank seeds. */
+    score?: number;
+}
+interface ExpandOptions {
+    /** Approximate cap, in tokens (~4 chars each), on the result. Default 2000. */
+    tokenBudget?: number;
+    maxHops?: number;
+    /** Restrict traversal (and reported edges) to these relations, e.g. ['contains', 'references']. */
+    relations?: Relation[];
+}
+interface ExpandedNode {
+    id: string;
+    label: string;
+    /** Node kind attr (chunk|section|entity|document|...) — absent on classic code nodes. */
+    kind?: string;
+    sourceFile: string;
+    sourceLocation: string;
+    /** 0 = was a seed (or an unresolvable hit echoed through). */
+    hops: number;
+    /** The edge that first led the traversal here (absent for seeds). */
+    via?: TraversalEdge;
+    /** The caller's similarity score — seeds only. */
+    seedScore?: number;
+}
+interface ExpandedContext {
+    /**
+     * Union of seed nodes and discovered neighbors, ranked: seeds first (by
+     * caller score desc), then by (hops asc, degree desc). Deduped across
+     * seeds. Hits that resolve to no graph node are echoed through with
+     * hops 0 and no expansion, so adopting this on a partially-ingested
+     * corpus never does worse than flat retrieval.
+     */
+    nodes: ExpandedNode[];
+    /** Every edge between included nodes — provenance for citations. */
+    edges: TraversalEdge[];
+    communities: Array<{
+        id: number;
+        label: string;
+        seedCount: number;
+    }>;
+    /** True when the token budget stopped the traversal before the frontier was exhausted. */
+    truncated: boolean;
+}
+/**
+ * Expand the caller's top-K hits through the graph: one joint,
+ * token-budgeted BFS seeded from every hit at once, so overlapping
+ * neighborhoods dedupe and the budget is shared across seeds. Deterministic
+ * (lexical neighbor order, stable ranking) like the rest of the query layer.
+ */
+declare function expandRetrieval(graph: Graph, hits: RetrievalHit[], options?: ExpandOptions): ExpandedContext;
+
 interface AffectedNode {
     id: string;
     label: string;
@@ -651,4 +772,4 @@ declare class ExtractionValidationError extends Error {
  */
 declare function validateExtraction(value: unknown, context?: string): ExtractionResult;
 
-export { type AffectedNode, type Analysis, type ChangedSymbol, type ClusterAlgorithm, type ClusterOptions, type Confidence, type ContextOptions, type ContextPack, type ContextSnippet, type DependencyRule, type DsnQueryFn, EXTRACTOR_REGISTRY, type ExplainResult, type ExportOptions, ExtractionCache, type ExtractionResult, ExtractionResultSchema, ExtractionValidationError, type ExtractionValidationIssue, type FileCategory, type FileManifest, type GraphDiff, type GraphEdge, type GraphNode, type ImpactOptions, type ImpactResult, type MergeEntry, type NodeMatch, type PathResult, type PipelineOptions, type PipelineResult, type QueryOptions, type QueryResult, type ReflectOptions, type Relation, type ResolveStats, type ResultOutcome, type ResultType, type RewiredSymbol, type RulesConfig, type SavedResult, type TestSelection, type TraversalEdge, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, diffGraphs, explainNode, exportGraph, extract, extractMysql, globToRegExp, graphForDirectory, isTestFile, loadGraph, loadResults, mergeGraphs, queryGraph, rankForTask, renderContextPack, renderLessons, renderReport, renderReview, resolveCrossFileReferences, resolveNode, reviewRevisions, runPipeline, saveResult, scoreNodes, shortestPath, testsForChangedFiles, testsForNode, validateExtraction, validateRules };
+export { type AffectedNode, type Analysis, type ChangedSymbol, type ClusterAlgorithm, type ClusterOptions, type Confidence, type ContextOptions, type ContextPack, type ContextSnippet, type DependencyRule, type DsnQueryFn, EXTRACTOR_REGISTRY, type ExpandOptions, type ExpandedContext, type ExpandedNode, type ExplainResult, type ExportOptions, ExtractionCache, type ExtractionResult, ExtractionResultSchema, ExtractionValidationError, type ExtractionValidationIssue, type FileCategory, type FileManifest, type GraphDiff, type GraphEdge, type GraphNode, type GraphStore, type ImpactOptions, type ImpactResult, LocalFileGraphStore, type MergeEntry, type NodeMatch, type PathResult, type PipelineOptions, type PipelineResult, type QueryOptions, type QueryResult, type ReflectOptions, type Relation, type ResolveStats, type ResultOutcome, type ResultType, type RetrievalHit, type RewiredSymbol, type RulesConfig, type SavedResult, type SerializedGraph, type TestSelection, type TraversalEdge, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, deserializeGraph, diffGraphs, expandRetrieval, explainNode, exportGraph, extract, extractMysql, globToRegExp, graphForDirectory, isTestFile, loadGraph, loadResults, mergeGraphs, queryGraph, rankForTask, renderContextPack, renderLessons, renderReport, renderReview, resolveCrossFileReferences, resolveNode, reviewRevisions, runPipeline, saveResult, scoreNodes, serializeGraph, shortestPath, testsForChangedFiles, testsForNode, validateExtraction, validateRules };

package/dist/index.js

@@ -24,31 +24,171 @@ import {
   saveResult,
   validateExtraction,
   validateRules
-} from "./chunk-NS5HB65S.js";
+} from "./chunk-QEB7A5KB.js";
 import {
+  LocalFileGraphStore,
   affectedBy,
   buildContextPack,
+  deserializeGraph,
   explainNode,
   isTestFile,
   loadGraph,
+  nodeTokenCost,
   queryGraph,
   rankForTask,
   renderContextPack,
   resolveNode,
   scoreNodes,
+  serializeGraph,
   shortestPath,
   testsForChangedFiles,
   testsForNode
-} from "./chunk-ZK3TA6FW.js";
+} from "./chunk-7LTO76UD.js";
 import {
   extractMysql
 } from "./chunk-ZPB37LLQ.js";
 import "./chunk-6JLEILYF.js";
+
+// src/retrieval.ts
+var DEFAULT_TOKEN_BUDGET = 2e3;
+var DEFAULT_MAX_HOPS = 2;
+function resolveSeeds(graph, hits) {
+  const seeds = /* @__PURE__ */ new Map();
+  for (const hit of hits) {
+    let id = null;
+    if (hit.nodeId !== void 0 && graph.hasNode(hit.nodeId)) {
+      id = hit.nodeId;
+    } else if (hit.text !== void 0) {
+      id = resolveNode(graph, hit.text)?.id ?? null;
+    }
+    const key = id ?? hit.nodeId ?? hit.text ?? "";
+    if (key === "") continue;
+    const existing = seeds.get(key);
+    if (existing) {
+      if (hit.score !== void 0 && (existing.score === void 0 || hit.score > existing.score)) {
+        existing.score = hit.score;
+      }
+      continue;
+    }
+    seeds.set(key, { id: key, score: hit.score, inGraph: id !== null, text: hit.text });
+  }
+  return [...seeds.values()];
+}
+function expandRetrieval(graph, hits, options = {}) {
+  const tokenBudget = options.tokenBudget ?? DEFAULT_TOKEN_BUDGET;
+  const maxHops = options.maxHops ?? DEFAULT_MAX_HOPS;
+  const relations = options.relations ? new Set(options.relations) : null;
+  const seeds = resolveSeeds(graph, hits);
+  const graphSeeds = seeds.filter((s) => s.inGraph);
+  const seedScore = new Map(graphSeeds.map((s) => [s.id, s.score]));
+  const hops = /* @__PURE__ */ new Map();
+  const via = /* @__PURE__ */ new Map();
+  const frontier = [];
+  let spentTokens = 0;
+  for (const seed of graphSeeds) {
+    hops.set(seed.id, 0);
+    frontier.push(seed.id);
+    spentTokens += nodeTokenCost(graph, seed.id);
+  }
+  let truncated = false;
+  while (frontier.length > 0) {
+    const current = frontier.shift();
+    const currentHops = hops.get(current);
+    if (currentHops >= maxHops) continue;
+    const candidates = [];
+    graph.forEachEdge(current, (_key, attrs, source, target) => {
+      const relation = String(attrs.relation);
+      if (relations && !relations.has(relation)) return;
+      const neighbor = source === current ? target : source;
+      candidates.push({
+        neighbor,
+        edge: { source, target, relation, confidence: String(attrs.confidence) }
+      });
+    });
+    candidates.sort((a, b) => a.neighbor.localeCompare(b.neighbor));
+    for (const { neighbor, edge } of candidates) {
+      if (hops.has(neighbor)) continue;
+      const cost = nodeTokenCost(graph, neighbor);
+      if (spentTokens + cost > tokenBudget) {
+        truncated = true;
+        continue;
+      }
+      spentTokens += cost;
+      hops.set(neighbor, currentHops + 1);
+      via.set(neighbor, edge);
+      frontier.push(neighbor);
+    }
+  }
+  const degree = (id) => graph.degree(id);
+  const nodes = [...hops.entries()].map(([id, hopCount]) => {
+    const attrs = graph.getNodeAttributes(id);
+    return {
+      id,
+      label: attrs.label ?? id,
+      ...attrs.kind !== void 0 ? { kind: String(attrs.kind) } : {},
+      sourceFile: attrs.sourceFile ?? "",
+      sourceLocation: attrs.sourceLocation ?? "",
+      hops: hopCount,
+      ...via.has(id) ? { via: via.get(id) } : {},
+      ...hopCount === 0 && seedScore.get(id) !== void 0 ? { seedScore: seedScore.get(id) } : {}
+    };
+  });
+  for (const seed of seeds) {
+    if (seed.inGraph) continue;
+    nodes.push({
+      id: seed.id,
+      label: seed.text ?? seed.id,
+      sourceFile: "",
+      sourceLocation: "",
+      hops: 0,
+      ...seed.score !== void 0 ? { seedScore: seed.score } : {}
+    });
+  }
+  nodes.sort((a, b) => {
+    if (a.hops !== b.hops) return a.hops - b.hops;
+    if (a.hops === 0) {
+      return (b.seedScore ?? -Infinity) - (a.seedScore ?? -Infinity) || a.id.localeCompare(b.id);
+    }
+    const degreeDiff = (graph.hasNode(b.id) ? degree(b.id) : 0) - (graph.hasNode(a.id) ? degree(a.id) : 0);
+    return degreeDiff || a.id.localeCompare(b.id);
+  });
+  const included = /* @__PURE__ */ new Set([...hops.keys()]);
+  const edges = [];
+  graph.forEachEdge((_key, attrs, source, target) => {
+    if (!included.has(source) || !included.has(target)) return;
+    const relation = String(attrs.relation);
+    if (relations && !relations.has(relation)) return;
+    edges.push({ source, target, relation, confidence: String(attrs.confidence) });
+  });
+  edges.sort(
+    (a, b) => a.source.localeCompare(b.source) || a.target.localeCompare(b.target) || a.relation.localeCompare(b.relation)
+  );
+  const communities = /* @__PURE__ */ new Map();
+  for (const id of included) {
+    const attrs = graph.getNodeAttributes(id);
+    const community = attrs.community;
+    if (community === void 0) continue;
+    const entry = communities.get(community) ?? {
+      id: community,
+      label: attrs.communityLabel ?? String(community),
+      seedCount: 0
+    };
+    if (hops.get(id) === 0) entry.seedCount += 1;
+    communities.set(community, entry);
+  }
+  return {
+    nodes,
+    edges,
+    communities: [...communities.values()].sort((a, b) => b.seedCount - a.seedCount || a.id - b.id),
+    truncated
+  };
+}
 export {
   EXTRACTOR_REGISTRY,
   ExtractionCache,
   ExtractionResultSchema,
   ExtractionValidationError,
+  LocalFileGraphStore,
   affectedBy,
   analyze,
   buildContextPack,
@@ -56,7 +196,9 @@ export {
   checkRules,
   cluster,
   collectFiles,
+  deserializeGraph,
   diffGraphs,
+  expandRetrieval,
   explainNode,
   exportGraph,
   extract,
@@ -79,6 +221,7 @@ export {
   runPipeline,
   saveResult,
   scoreNodes,
+  serializeGraph,
   shortestPath,
   testsForChangedFiles,
   testsForNode,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/retrieval.ts"],"sourcesContent":["import type Graph from 'graphology';\nimport { nodeTokenCost, resolveNode, type TraversalEdge } from './query.js';\nimport type { Relation } from './types.js';\n\n/**\n * Graph-augmented retrieval (docs/KB-PROVIDER.md §4): the caller has\n * already done similarity search (vector, keyword, hybrid — their\n * pipeline, their embeddings); expandRetrieval() takes those hits and adds\n * what similarity can't see — the nodes *structurally connected* to them.\n * Pure and synchronous like every query function: Graph in, data out; no\n * store access, no embedding calls.\n */\n\n/**\n * One hit from the caller's own search. `nodeId` when the caller stored\n * graph node ids alongside its records at ingest time; otherwise `text`,\n * resolved against the graph lexically (same resolver queryGraph uses).\n */\nexport interface RetrievalHit {\n  nodeId?: string;\n  text?: string;\n  /** The caller's similarity score, echoed through to rank seeds. */\n  score?: number;\n}\n\nexport interface ExpandOptions {\n  /** Approximate cap, in tokens (~4 chars each), on the result. Default 2000. */\n  tokenBudget?: number;\n  maxHops?: number;\n  /** Restrict traversal (and reported edges) to these relations, e.g. ['contains', 'references']. */\n  relations?: Relation[];\n}\n\nexport interface ExpandedNode {\n  id: string;\n  label: string;\n  /** Node kind attr (chunk|section|entity|document|...) — absent on classic code nodes. */\n  kind?: string;\n  sourceFile: string;\n  sourceLocation: string;\n  /** 0 = was a seed (or an unresolvable hit echoed through). */\n  hops: number;\n  /** The edge that first led the traversal here (absent for seeds). */\n  via?: TraversalEdge;\n  /** The caller's similarity score — seeds only. */\n  seedScore?: number;\n}\n\nexport interface ExpandedContext {\n  /**\n   * Union of seed nodes and discovered neighbors, ranked: seeds first (by\n   * caller score desc), then by (hops asc, degree desc). Deduped across\n   * seeds. Hits that resolve to no graph node are echoed through with\n   * hops 0 and no expansion, so adopting this on a partially-ingested\n   * corpus never does worse than flat retrieval.\n   */\n  nodes: ExpandedNode[];\n  /** Every edge between included nodes — provenance for citations. */\n  edges: TraversalEdge[];\n  communities: Array<{ id: number; label: string; seedCount: number }>;\n  /** True when the token budget stopped the traversal before the frontier was exhausted. */\n  truncated: boolean;\n}\n\nconst DEFAULT_TOKEN_BUDGET = 2000;\nconst DEFAULT_MAX_HOPS = 2;\n\ninterface Seed {\n  id: string;\n  score: number | undefined;\n  inGraph: boolean;\n  /** Fallback label for hits that resolve to no graph node. */\n  text?: string;\n}\n\n/**\n * Resolve hits to seed nodes: exact id when it exists in the graph, else\n * lexical resolution of `text`. Duplicate resolutions collapse into one\n * seed keeping the best caller score. Hits that resolve nowhere are kept\n * as out-of-graph seeds so the caller sees every hit accounted for.\n */\nfunction resolveSeeds(graph: Graph, hits: RetrievalHit[]): Seed[] {\n  const seeds = new Map<string, Seed>();\n  for (const hit of hits) {\n    let id: string | null = null;\n    if (hit.nodeId !== undefined && graph.hasNode(hit.nodeId)) {\n      id = hit.nodeId;\n    } else if (hit.text !== undefined) {\n      id = resolveNode(graph, hit.text)?.id ?? null;\n    }\n\n    const key = id ?? hit.nodeId ?? hit.text ?? '';\n    if (key === '') continue; // an entirely empty hit carries nothing to resolve or echo\n    const existing = seeds.get(key);\n    if (existing) {\n      if (hit.score !== undefined && (existing.score === undefined || hit.score > existing.score)) {\n        existing.score = hit.score;\n      }\n      continue;\n    }\n    seeds.set(key, { id: key, score: hit.score, inGraph: id !== null, text: hit.text });\n  }\n  return [...seeds.values()];\n}\n\n/**\n * Expand the caller's top-K hits through the graph: one joint,\n * token-budgeted BFS seeded from every hit at once, so overlapping\n * neighborhoods dedupe and the budget is shared across seeds. Deterministic\n * (lexical neighbor order, stable ranking) like the rest of the query layer.\n */\nexport function expandRetrieval(graph: Graph, hits: RetrievalHit[], options: ExpandOptions = {}): ExpandedContext {\n  const tokenBudget = options.tokenBudget ?? DEFAULT_TOKEN_BUDGET;\n  const maxHops = options.maxHops ?? DEFAULT_MAX_HOPS;\n  const relations = options.relations ? new Set<string>(options.relations) : null;\n\n  const seeds = resolveSeeds(graph, hits);\n  const graphSeeds = seeds.filter((s) => s.inGraph);\n  const seedScore = new Map(graphSeeds.map((s) => [s.id, s.score]));\n\n  const hops = new Map<string, number>(); // id -> hop distance\n  const via = new Map<string, TraversalEdge>();\n  const frontier: string[] = [];\n  let spentTokens = 0;\n  for (const seed of graphSeeds) {\n    hops.set(seed.id, 0);\n    frontier.push(seed.id);\n    spentTokens += nodeTokenCost(graph, seed.id);\n  }\n\n  let truncated = false;\n  while (frontier.length > 0) {\n    const current = frontier.shift() as string;\n    const currentHops = hops.get(current) as number;\n    if (currentHops >= maxHops) continue;\n\n    // Collect candidate edges (not bare neighbors) so the relations filter\n    // applies and `via` can record how each node was reached.\n    const candidates: Array<{ neighbor: string; edge: TraversalEdge }> = [];\n    graph.forEachEdge(current, (_key, attrs, source, target) => {\n      const relation = String(attrs.relation);\n      if (relations && !relations.has(relation)) return;\n      const neighbor = source === current ? target : source;\n      candidates.push({\n        neighbor,\n        edge: { source, target, relation, confidence: String(attrs.confidence) },\n      });\n    });\n    candidates.sort((a, b) => a.neighbor.localeCompare(b.neighbor));\n\n    for (const { neighbor, edge } of candidates) {\n      if (hops.has(neighbor)) continue;\n      const cost = nodeTokenCost(graph, neighbor);\n      if (spentTokens + cost > tokenBudget) {\n        truncated = true;\n        continue;\n      }\n      spentTokens += cost;\n      hops.set(neighbor, currentHops + 1);\n      via.set(neighbor, edge);\n      frontier.push(neighbor);\n    }\n  }\n\n  const degree = (id: string): number => graph.degree(id);\n  const nodes: ExpandedNode[] = [...hops.entries()].map(([id, hopCount]) => {\n    const attrs = graph.getNodeAttributes(id);\n    return {\n      id,\n      label: (attrs.label as string | undefined) ?? id,\n      ...(attrs.kind !== undefined ? { kind: String(attrs.kind) } : {}),\n      sourceFile: (attrs.sourceFile as string | undefined) ?? '',\n      sourceLocation: (attrs.sourceLocation as string | undefined) ?? '',\n      hops: hopCount,\n      ...(via.has(id) ? { via: via.get(id) as TraversalEdge } : {}),\n      ...(hopCount === 0 && seedScore.get(id) !== undefined ? { seedScore: seedScore.get(id) as number } : {}),\n    };\n  });\n\n  // Out-of-graph hits: echoed through so the result never covers less than\n  // the caller's own flat retrieval did.\n  for (const seed of seeds) {\n    if (seed.inGraph) continue;\n    nodes.push({\n      id: seed.id,\n      label: seed.text ?? seed.id,\n      sourceFile: '',\n      sourceLocation: '',\n      hops: 0,\n      ...(seed.score !== undefined ? { seedScore: seed.score } : {}),\n    });\n  }\n\n  nodes.sort((a, b) => {\n    if (a.hops !== b.hops) return a.hops - b.hops;\n    if (a.hops === 0) {\n      return (b.seedScore ?? -Infinity) - (a.seedScore ?? -Infinity) || a.id.localeCompare(b.id);\n    }\n    const degreeDiff = (graph.hasNode(b.id) ? degree(b.id) : 0) - (graph.hasNode(a.id) ? degree(a.id) : 0);\n    return degreeDiff || a.id.localeCompare(b.id);\n  });\n\n  const included = new Set([...hops.keys()]);\n  const edges: TraversalEdge[] = [];\n  graph.forEachEdge((_key, attrs, source, target) => {\n    if (!included.has(source) || !included.has(target)) return;\n    const relation = String(attrs.relation);\n    if (relations && !relations.has(relation)) return;\n    edges.push({ source, target, relation, confidence: String(attrs.confidence) });\n  });\n  edges.sort(\n    (a, b) => a.source.localeCompare(b.source) || a.target.localeCompare(b.target) || a.relation.localeCompare(b.relation),\n  );\n\n  const communities = new Map<number, { id: number; label: string; seedCount: number }>();\n  for (const id of included) {\n    const attrs = graph.getNodeAttributes(id);\n    const community = attrs.community as number | undefined;\n    if (community === undefined) continue;\n    const entry = communities.get(community) ?? {\n      id: community,\n      label: (attrs.communityLabel as string | undefined) ?? String(community),\n      seedCount: 0,\n    };\n    if ((hops.get(id) as number) === 0) entry.seedCount += 1;\n    communities.set(community, entry);\n  }\n\n  return {\n    nodes,\n    edges,\n    communities: [...communities.values()].sort((a, b) => b.seedCount - a.seedCount || a.id - b.id),\n    truncated,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/mcp/server.cjs

@@ -442,9 +442,10 @@ function renderContextPack(pack) {
 }
 
 // src/graphStore.ts
-var fs2 = __toESM(require("fs/promises"), 1);
 var path = __toESM(require("path"), 1);
-var import_graphology = __toESM(require("graphology"), 1);
+
+// src/store/localFile.ts
+var fs2 = __toESM(require("fs/promises"), 1);
 
 // src/security.ts
 var import_node_crypto = require("crypto");
@@ -479,12 +480,48 @@ function validateGraphPath(path3, base) {
   return realCandidate;
 }
 
+// src/store/serialize.ts
+var import_graphology = __toESM(require("graphology"), 1);
+function serializeGraph(graph) {
+  return graph.export();
+}
+function deserializeGraph(data) {
+  return import_graphology.default.from(data);
+}
+
+// src/store/localFile.ts
+var LocalFileGraphStore = class {
+  async load(ref) {
+    let jsonPath;
+    try {
+      jsonPath = validateGraphPath("graph.json", ref);
+    } catch (error) {
+      if (error.message.startsWith("Base directory does not exist")) return null;
+      throw error;
+    }
+    let raw;
+    try {
+      raw = await fs2.readFile(jsonPath, "utf-8");
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+    return deserializeGraph(JSON.parse(raw));
+  }
+  async save(ref, graph) {
+    await fs2.mkdir(ref, { recursive: true });
+    const jsonPath = validateGraphPath("graph.json", ref);
+    await fs2.writeFile(jsonPath, JSON.stringify(serializeGraph(graph), null, 2), "utf-8");
+  }
+};
+
 // src/graphStore.ts
 async function loadGraph(outDir = path.join(process.cwd(), "graphify-out")) {
-  const jsonPath = validateGraphPath("graph.json", outDir);
-  const raw = await fs2.readFile(jsonPath, "utf-8");
-  const data = JSON.parse(raw);
-  return import_graphology.default.from(data);
+  const graph = await new LocalFileGraphStore().load(outDir);
+  if (graph === null) {
+    throw new Error(`No graph found in ${outDir} \u2014 run \`graphify <path>\` to build one first.`);
+  }
+  return graph;
 }
 
 // src/impact.ts