@dreamtree-org/graphify 1.1.3 → 1.3.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;
@@ -651,4 +705,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 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 RewiredSymbol, type RulesConfig, type SavedResult, type SerializedGraph, type TestSelection, type TraversalEdge, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, deserializeGraph, diffGraphs, 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;
@@ -651,4 +705,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 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 RewiredSymbol, type RulesConfig, type SavedResult, type SerializedGraph, type TestSelection, type TraversalEdge, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, deserializeGraph, diffGraphs, 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,10 +24,12 @@ import {
   saveResult,
   validateExtraction,
   validateRules
-} from "./chunk-NS5HB65S.js";
+} from "./chunk-UBXYMMXJ.js";
 import {
+  LocalFileGraphStore,
   affectedBy,
   buildContextPack,
+  deserializeGraph,
   explainNode,
   isTestFile,
   loadGraph,
@@ -36,10 +38,11 @@ import {
   renderContextPack,
   resolveNode,
   scoreNodes,
+  serializeGraph,
   shortestPath,
   testsForChangedFiles,
   testsForNode
-} from "./chunk-ZK3TA6FW.js";
+} from "./chunk-K322XB4U.js";
 import {
   extractMysql
 } from "./chunk-ZPB37LLQ.js";
@@ -49,6 +52,7 @@ export {
   ExtractionCache,
   ExtractionResultSchema,
   ExtractionValidationError,
+  LocalFileGraphStore,
   affectedBy,
   analyze,
   buildContextPack,
@@ -56,6 +60,7 @@ export {
   checkRules,
   cluster,
   collectFiles,
+  deserializeGraph,
   diffGraphs,
   explainNode,
   exportGraph,
@@ -79,6 +84,7 @@ export {
   runPipeline,
   saveResult,
   scoreNodes,
+  serializeGraph,
   shortestPath,
   testsForChangedFiles,
   testsForNode,

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