ts-knowledge-graph 0.1.2 → 0.1.6

package/dist/schema/runtime_manifest.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+/**
+ * The `GraphMeta` key under which the runtime ingest manifest is stored. It lives
+ * at the graph level — one record for the whole graph — rather than on a node,
+ * which is why it does not collide with the per-node `metadata.runtime`.
+ */
+export declare const RUNTIME_MANIFEST_KEY = "runtime";
+/**
+ * Graph-level coverage facts recorded by `enrich`: how much of the profiled cost
+ * was attributed to graph nodes versus dropped by the join. Persisted so a later
+ * query — `cost` in particular — can report **coverage** (the fraction of total
+ * measured cost the attribution actually accounts for) instead of silently
+ * presenting a partial picture. `total*` are profile-wide; `matched*` are the part
+ * attached to nodes; the difference is what the join dropped.
+ */
+export declare const RuntimeManifestSchema: z.ZodObject<{
+    source: z.ZodString;
+    totalSamples: z.ZodNumber;
+    matchedSamples: z.ZodNumber;
+    totalSelfMicros: z.ZodNumber;
+    matchedSelfMicros: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    totalSamples: number;
+    matchedSamples: number;
+    totalSelfMicros: number;
+    matchedSelfMicros: number;
+}, {
+    source: string;
+    totalSamples: number;
+    matchedSamples: number;
+    totalSelfMicros: number;
+    matchedSelfMicros: number;
+}>;
+export type RuntimeManifest = z.infer<typeof RuntimeManifestSchema>;
+//# sourceMappingURL=runtime_manifest.d.ts.map

package/dist/schema/runtime_manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime_manifest.d.ts","sourceRoot":"","sources":["../../src/schema/runtime_manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;EAMhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/schema/runtime_manifest.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+/**
+ * The `GraphMeta` key under which the runtime ingest manifest is stored. It lives
+ * at the graph level — one record for the whole graph — rather than on a node,
+ * which is why it does not collide with the per-node `metadata.runtime`.
+ */
+export const RUNTIME_MANIFEST_KEY = 'runtime';
+/**
+ * Graph-level coverage facts recorded by `enrich`: how much of the profiled cost
+ * was attributed to graph nodes versus dropped by the join. Persisted so a later
+ * query — `cost` in particular — can report **coverage** (the fraction of total
+ * measured cost the attribution actually accounts for) instead of silently
+ * presenting a partial picture. `total*` are profile-wide; `matched*` are the part
+ * attached to nodes; the difference is what the join dropped.
+ */
+export const RuntimeManifestSchema = z.object({
+    source: z.string(),
+    totalSamples: z.number(),
+    matchedSamples: z.number(),
+    totalSelfMicros: z.number(),
+    matchedSelfMicros: z.number(),
+});
+//# sourceMappingURL=runtime_manifest.js.map

package/dist/schema/runtime_manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime_manifest.js","sourceRoot":"","sources":["../../src/schema/runtime_manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE;IAC3B,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE;CAC7B,CAAC,CAAC"}

package/dist/schema/source_manifest.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+/**
+ * The `GraphMeta` key under which the source-repository manifest is stored. Like
+ * {@link RUNTIME_MANIFEST_KEY}, it is a graph-level record — one per graph — and
+ * is written by `load` from the provenance `extract` captured at parse time.
+ */
+export declare const SOURCE_MANIFEST_KEY = "source";
+/**
+ * Git provenance of the analysed project, captured by `extract` at the exact
+ * commit and root it parsed so the `web` visualisation can turn each file path
+ * into a GitHub permalink. `prefix` is the analysed root's path within the
+ * repository — `''` at the repo root, otherwise `sub/dir/` with a trailing
+ * slash — and is prepended to each node's root-relative `filePath` to form the
+ * repository-relative path.
+ */
+export declare const SourceManifestSchema: z.ZodObject<{
+    baseUrl: z.ZodString;
+    commit: z.ZodString;
+    prefix: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    baseUrl: string;
+    commit: string;
+    prefix: string;
+}, {
+    baseUrl: string;
+    commit: string;
+    prefix: string;
+}>;
+export type SourceManifest = z.infer<typeof SourceManifestSchema>;
+//# sourceMappingURL=source_manifest.d.ts.map

package/dist/schema/source_manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source_manifest.d.ts","sourceRoot":"","sources":["../../src/schema/source_manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAI/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/schema/source_manifest.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+/**
+ * The `GraphMeta` key under which the source-repository manifest is stored. Like
+ * {@link RUNTIME_MANIFEST_KEY}, it is a graph-level record — one per graph — and
+ * is written by `load` from the provenance `extract` captured at parse time.
+ */
+export const SOURCE_MANIFEST_KEY = 'source';
+/**
+ * Git provenance of the analysed project, captured by `extract` at the exact
+ * commit and root it parsed so the `web` visualisation can turn each file path
+ * into a GitHub permalink. `prefix` is the analysed root's path within the
+ * repository — `''` at the repo root, otherwise `sub/dir/` with a trailing
+ * slash — and is prepended to each node's root-relative `filePath` to form the
+ * repository-relative path.
+ */
+export const SourceManifestSchema = z.object({
+    baseUrl: z.string(),
+    commit: z.string(),
+    prefix: z.string(),
+});
+//# sourceMappingURL=source_manifest.js.map

package/dist/schema/source_manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source_manifest.js","sourceRoot":"","sources":["../../src/schema/source_manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAC"}

package/dist/store/jsonl_reader.d.ts

@@ -1,11 +1,15 @@
 import { GraphEdge } from '../schema/edge.js';
 import { GraphNode } from '../schema/node.js';
+import { SourceManifest } from '../schema/source_manifest.js';
 export type GraphData = {
     nodes: GraphNode[];
     edges: GraphEdge[];
+    source?: SourceManifest;
 };
 export declare class JsonlReader {
     static read(dir: string): Promise<GraphData>;
+    /** Reads the optional `source.json` provenance manifest; an absent or malformed file yields `undefined`. */
+    private static readSource;
     private static readLines;
 }
 //# sourceMappingURL=jsonl_reader.d.ts.map

package/dist/store/jsonl_reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsonl_reader.d.ts","sourceRoot":"","sources":["../../src/store/jsonl_reader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAE/D,MAAM,MAAM,SAAS,GAAG;IACvB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACnB,CAAC;AAEF,qBAAa,WAAW;WACV,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;mBAM7B,SAAS;CAO9B"}
+{"version":3,"file":"jsonl_reader.d.ts","sourceRoot":"","sources":["../../src/store/jsonl_reader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAwB,MAAM,8BAA8B,CAAC;AAEpF,MAAM,MAAM,SAAS,GAAG;IACvB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,cAAc,CAAC;CACxB,CAAC;AAEF,qBAAa,WAAW;WACV,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAOlD,4GAA4G;mBACvF,UAAU;mBASV,SAAS;CAO9B"}

package/dist/store/jsonl_reader.js

@@ -2,11 +2,23 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { GraphEdgeSchema } from '../schema/edge.js';
 import { GraphNodeSchema } from '../schema/node.js';
+import { SourceManifestSchema } from '../schema/source_manifest.js';
 export class JsonlReader {
     static async read(dir) {
         const nodes = await JsonlReader.readLines(join(dir, 'nodes.jsonl'), GraphNodeSchema);
         const edges = await JsonlReader.readLines(join(dir, 'edges.jsonl'), GraphEdgeSchema);
-        return { nodes, edges };
+        const source = await JsonlReader.readSource(join(dir, 'source.json'));
+        return { nodes, edges, source };
+    }
+    /** Reads the optional `source.json` provenance manifest; an absent or malformed file yields `undefined`. */
+    static async readSource(path) {
+        try {
+            const parsed = SourceManifestSchema.safeParse(JSON.parse(await readFile(path, 'utf8')));
+            return parsed.success === true ? parsed.data : undefined;
+        }
+        catch {
+            return undefined;
+        }
     }
     static async readLines(path, schema) {
         const content = await readFile(path, 'utf8');

package/dist/store/jsonl_reader.js.map

@@ -1 +1 @@
-{"version":3,"file":"jsonl_reader.js","sourceRoot":"","sources":["../../src/store/jsonl_reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAa,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAa,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAO/D,MAAM,OAAO,WAAW;IACvB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAW;QAC5B,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,eAAe,CAAC,CAAC;QACrF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,eAAe,CAAC,CAAC;QACrF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,SAAS,CAAI,IAAY,EAAE,MAAoB;QACnE,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,OAAO;aACZ,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;aACxC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;CACD"}
+{"version":3,"file":"jsonl_reader.js","sourceRoot":"","sources":["../../src/store/jsonl_reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAa,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAa,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAkB,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAQpF,MAAM,OAAO,WAAW;IACvB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAW;QAC5B,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,eAAe,CAAC,CAAC;QACrF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,eAAe,CAAC,CAAC;QACrF,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC;QACtE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACjC,CAAC;IAED,4GAA4G;IACpG,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAY;QAC3C,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;YACxF,OAAO,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1D,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,SAAS,CAAC;QAClB,CAAC;IACF,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,SAAS,CAAI,IAAY,EAAE,MAAoB;QACnE,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,OAAO;aACZ,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;aACxC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;CACD"}

package/dist/store/jsonl_store.d.ts

@@ -1,7 +1,8 @@
 import { GraphEdge } from '../schema/edge.js';
 import { GraphNode } from '../schema/node.js';
+import { SourceManifest } from '../schema/source_manifest.js';
 export declare class JsonlStore {
-    static write(outDir: string, nodes: GraphNode[], edges: GraphEdge[]): Promise<void>;
+    static write(outDir: string, nodes: GraphNode[], edges: GraphEdge[], source?: SourceManifest): Promise<void>;
     private static serialize;
 }
 //# sourceMappingURL=jsonl_store.d.ts.map

package/dist/store/jsonl_store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsonl_store.d.ts","sourceRoot":"","sources":["../../src/store/jsonl_store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,qBAAa,UAAU;WACT,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzF,OAAO,CAAC,MAAM,CAAC,SAAS;CAGxB"}
+{"version":3,"file":"jsonl_store.d.ts","sourceRoot":"","sources":["../../src/store/jsonl_store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,qBAAa,UAAU;WACT,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IASlH,OAAO,CAAC,MAAM,CAAC,SAAS;CAGxB"}

package/dist/store/jsonl_store.js

@@ -1,10 +1,13 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 export class JsonlStore {
-    static async write(outDir, nodes, edges) {
+    static async write(outDir, nodes, edges, source) {
         await mkdir(outDir, { recursive: true });
         await writeFile(join(outDir, 'nodes.jsonl'), JsonlStore.serialize(nodes), 'utf8');
         await writeFile(join(outDir, 'edges.jsonl'), JsonlStore.serialize(edges), 'utf8');
+        if (source !== undefined) {
+            await writeFile(join(outDir, 'source.json'), JSON.stringify(source) + '\n', 'utf8');
+        }
     }
     static serialize(rows) {
         return rows.map((row) => JSON.stringify(row)).join('\n') + '\n';

package/dist/store/jsonl_store.js.map

@@ -1 +1 @@
-{"version":3,"file":"jsonl_store.js","sourceRoot":"","sources":["../../src/store/jsonl_store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,MAAM,OAAO,UAAU;IACtB,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAc,EAAE,KAAkB,EAAE,KAAkB;QACxE,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QAClF,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;IACnF,CAAC;IAEO,MAAM,CAAC,SAAS,CAAC,IAAe;QACvC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjE,CAAC;CACD"}
+{"version":3,"file":"jsonl_store.js","sourceRoot":"","sources":["../../src/store/jsonl_store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAKjC,MAAM,OAAO,UAAU;IACtB,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAc,EAAE,KAAkB,EAAE,KAAkB,EAAE,MAAuB;QACjG,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QAClF,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QAClF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;QACrF,CAAC;IACF,CAAC;IAEO,MAAM,CAAC,SAAS,CAAC,IAAe;QACvC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjE,CAAC;CACD"}

package/dist/store/kuzu_store.d.ts

@@ -1,12 +1,71 @@
 import type { KuzuValue } from 'kuzu';
 import { GraphEdge } from '../schema/edge.js';
 import { GraphNode } from '../schema/node.js';
+/** A stored node read back from Kùzu, with its metadata decoded to a record. */
+export type StoredNode = {
+    id: string;
+    kind: string;
+    name: string;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    metadata: Record<string, unknown>;
+};
 export declare class KuzuStore {
     private readonly db;
     private readonly conn;
     constructor(dbPath: string);
     initSchema(): Promise<void>;
     load(nodes: GraphNode[], edges: GraphEdge[]): Promise<void>;
+    /**
+     * Inserts or updates edges by (`from`, `to`, `kind`) — the same merge `load`
+     * uses for its edge pass — onto an already-loaded graph; both endpoint nodes
+     * must already exist. Used by `enrich` to attach the runtime call graph after
+     * the static graph is loaded.
+     */
+    writeEdges(edges: GraphEdge[]): Promise<void>;
+    /**
+     * Removes every edge of a given kind. Used by `enrich` to clear the prior
+     * runtime call graph before writing a fresh one, so a re-run never leaves stale
+     * edges behind.
+     */
+    clearEdgesByKind(kind: string): Promise<void>;
+    /**
+     * Reads every node back from the store, decoding the `metadata` column. Used
+     * by enrichment to resolve profile frames against the loaded graph's ranges
+     * and to merge new metadata onto existing records.
+     */
+    readNodes(): Promise<StoredNode[]>;
+    /**
+     * Overwrites the `metadata` column for the given nodes. The caller is
+     * responsible for merging so that only the intended keys change; passing the
+     * full record keeps the write idempotent for unchanged keys.
+     */
+    writeNodeMetadata(entries: {
+        id: string;
+        metadata: Record<string, unknown>;
+    }[]): Promise<void>;
+    /**
+     * Writes a graph-level metadata record under `key` (a `GraphMeta` row), encoding
+     * the value as JSON. Used for facts about the whole graph rather than one node —
+     * e.g. the runtime ingest manifest `enrich` records for coverage reporting.
+     */
+    writeGraphMeta(key: string, value: Record<string, unknown>): Promise<void>;
+    /** Reads the graph-level metadata record stored under `key`, decoded, or null when absent. */
+    readGraphMeta(key: string): Promise<Record<string, unknown> | null>;
+    /** Removes the graph-level metadata record stored under `key`, if any. */
+    clearGraphMeta(key: string): Promise<void>;
+    /**
+     * Serializes an optional metadata record to a JSON string for storage in the
+     * `metadata` column. Absent metadata is stored as an empty object so the
+     * column is never null.
+     */
+    private static encodeMetadata;
+    /**
+     * Decodes the JSON `metadata` column back into a record. A missing, empty, or
+     * malformed value decodes to an empty object so callers always receive a record.
+     */
+    private static decodeMetadata;
     run(cypher: string, params?: Record<string, KuzuValue>): Promise<Record<string, KuzuValue>[]>;
     close(): Promise<void>;
     private static first;

package/dist/store/kuzu_store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kuzu_store.d.ts","sourceRoot":"","sources":["../../src/store/kuzu_store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAO9C,qBAAa,SAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;gBAEtB,MAAM,EAAE,MAAM;IAMpB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB3D,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;IAW7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,OAAO,CAAC,MAAM,CAAC,KAAK;IAIpB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAK3B"}
+{"version":3,"file":"kuzu_store.d.ts","sourceRoot":"","sources":["../../src/store/kuzu_store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAQF,qBAAa,SAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;gBAEtB,MAAM,EAAE,MAAM;IAMpB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BjE;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBnD;;;;OAIG;IACG,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnD;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAexC;;;;OAIG;IACG,iBAAiB,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAapG;;;;OAIG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhF,8FAA8F;IACxF,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAQzE,0EAA0E;IACpE,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAI7B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAevB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;IAW7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,OAAO,CAAC,MAAM,CAAC,KAAK;IAIpB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAK3B"}

package/dist/store/kuzu_store.js

@@ -2,8 +2,9 @@ import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { Connection, Database } from 'kuzu';
 const SCHEMA = [
-    'CREATE NODE TABLE IF NOT EXISTS GraphNode (id STRING, kind STRING, name STRING, filePath STRING, exported BOOLEAN, startLine INT64, endLine INT64, PRIMARY KEY (id))',
-    'CREATE REL TABLE IF NOT EXISTS Edge (FROM GraphNode TO GraphNode, kind STRING)',
+    'CREATE NODE TABLE IF NOT EXISTS GraphNode (id STRING, kind STRING, name STRING, filePath STRING, exported BOOLEAN, startLine INT64, endLine INT64, metadata STRING, PRIMARY KEY (id))',
+    'CREATE REL TABLE IF NOT EXISTS Edge (FROM GraphNode TO GraphNode, kind STRING, metadata STRING)',
+    'CREATE NODE TABLE IF NOT EXISTS GraphMeta (key STRING, value STRING, PRIMARY KEY (key))',
 ];
 export class KuzuStore {
     constructor(dbPath) {
@@ -17,7 +18,7 @@ export class KuzuStore {
         }
     }
     async load(nodes, edges) {
-        const nodeStmt = await this.conn.prepare('MERGE (n:GraphNode {id: $id}) SET n.kind = $kind, n.name = $name, n.filePath = $filePath, n.exported = $exported, n.startLine = $startLine, n.endLine = $endLine');
+        const nodeStmt = await this.conn.prepare('MERGE (n:GraphNode {id: $id}) SET n.kind = $kind, n.name = $name, n.filePath = $filePath, n.exported = $exported, n.startLine = $startLine, n.endLine = $endLine, n.metadata = $metadata');
         for (const node of nodes) {
             KuzuStore.closeResults(await this.conn.execute(nodeStmt, {
                 id: node.id,
@@ -27,11 +28,129 @@ export class KuzuStore {
                 exported: node.exported ?? false,
                 startLine: node.range?.startLine ?? 0,
                 endLine: node.range?.endLine ?? 0,
+                metadata: KuzuStore.encodeMetadata(node.metadata),
             }));
         }
-        const edgeStmt = await this.conn.prepare('MATCH (f:GraphNode {id: $from}), (t:GraphNode {id: $to}) MERGE (f)-[:Edge {kind: $kind}]->(t)');
+        const edgeStmt = await this.conn.prepare('MATCH (f:GraphNode {id: $from}), (t:GraphNode {id: $to}) MERGE (f)-[e:Edge {kind: $kind}]->(t) SET e.metadata = $metadata');
         for (const edge of edges) {
-            KuzuStore.closeResults(await this.conn.execute(edgeStmt, { from: edge.from, to: edge.to, kind: edge.kind }));
+            KuzuStore.closeResults(await this.conn.execute(edgeStmt, {
+                from: edge.from,
+                to: edge.to,
+                kind: edge.kind,
+                metadata: KuzuStore.encodeMetadata(edge.metadata),
+            }));
+        }
+    }
+    /**
+     * Inserts or updates edges by (`from`, `to`, `kind`) — the same merge `load`
+     * uses for its edge pass — onto an already-loaded graph; both endpoint nodes
+     * must already exist. Used by `enrich` to attach the runtime call graph after
+     * the static graph is loaded.
+     */
+    async writeEdges(edges) {
+        if (edges.length === 0) {
+            return;
+        }
+        const stmt = await this.conn.prepare('MATCH (f:GraphNode {id: $from}), (t:GraphNode {id: $to}) MERGE (f)-[e:Edge {kind: $kind}]->(t) SET e.metadata = $metadata');
+        for (const edge of edges) {
+            KuzuStore.closeResults(await this.conn.execute(stmt, {
+                from: edge.from,
+                to: edge.to,
+                kind: edge.kind,
+                metadata: KuzuStore.encodeMetadata(edge.metadata),
+            }));
+        }
+    }
+    /**
+     * Removes every edge of a given kind. Used by `enrich` to clear the prior
+     * runtime call graph before writing a fresh one, so a re-run never leaves stale
+     * edges behind.
+     */
+    async clearEdgesByKind(kind) {
+        const stmt = await this.conn.prepare('MATCH (:GraphNode)-[e:Edge {kind: $kind}]->(:GraphNode) DELETE e');
+        KuzuStore.closeResults(await this.conn.execute(stmt, { kind }));
+    }
+    /**
+     * Reads every node back from the store, decoding the `metadata` column. Used
+     * by enrichment to resolve profile frames against the loaded graph's ranges
+     * and to merge new metadata onto existing records.
+     */
+    async readNodes() {
+        const rows = await this.run('MATCH (n:GraphNode) RETURN n.id AS id, n.kind AS kind, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.metadata AS metadata');
+        return rows.map((row) => ({
+            id: String(row.id),
+            kind: String(row.kind),
+            name: String(row.name),
+            filePath: String(row.filePath),
+            startLine: Number(row.startLine),
+            endLine: Number(row.endLine),
+            metadata: KuzuStore.decodeMetadata(row.metadata),
+        }));
+    }
+    /**
+     * Overwrites the `metadata` column for the given nodes. The caller is
+     * responsible for merging so that only the intended keys change; passing the
+     * full record keeps the write idempotent for unchanged keys.
+     */
+    async writeNodeMetadata(entries) {
+        if (entries.length === 0) {
+            return;
+        }
+        const stmt = await this.conn.prepare('MATCH (n:GraphNode {id: $id}) SET n.metadata = $metadata');
+        for (const entry of entries) {
+            KuzuStore.closeResults(await this.conn.execute(stmt, {
+                id: entry.id,
+                metadata: KuzuStore.encodeMetadata(entry.metadata),
+            }));
+        }
+    }
+    /**
+     * Writes a graph-level metadata record under `key` (a `GraphMeta` row), encoding
+     * the value as JSON. Used for facts about the whole graph rather than one node —
+     * e.g. the runtime ingest manifest `enrich` records for coverage reporting.
+     */
+    async writeGraphMeta(key, value) {
+        const stmt = await this.conn.prepare('MERGE (m:GraphMeta {key: $key}) SET m.value = $value');
+        KuzuStore.closeResults(await this.conn.execute(stmt, { key, value: KuzuStore.encodeMetadata(value) }));
+    }
+    /** Reads the graph-level metadata record stored under `key`, decoded, or null when absent. */
+    async readGraphMeta(key) {
+        const rows = await this.run('MATCH (m:GraphMeta {key: $key}) RETURN m.value AS value', { key });
+        if (rows.length === 0) {
+            return null;
+        }
+        return KuzuStore.decodeMetadata(rows[0].value);
+    }
+    /** Removes the graph-level metadata record stored under `key`, if any. */
+    async clearGraphMeta(key) {
+        const stmt = await this.conn.prepare('MATCH (m:GraphMeta {key: $key}) DELETE m');
+        KuzuStore.closeResults(await this.conn.execute(stmt, { key }));
+    }
+    /**
+     * Serializes an optional metadata record to a JSON string for storage in the
+     * `metadata` column. Absent metadata is stored as an empty object so the
+     * column is never null.
+     */
+    static encodeMetadata(metadata) {
+        return JSON.stringify(metadata ?? {});
+    }
+    /**
+     * Decodes the JSON `metadata` column back into a record. A missing, empty, or
+     * malformed value decodes to an empty object so callers always receive a record.
+     */
+    static decodeMetadata(value) {
+        if (typeof value !== 'string' || value.length === 0) {
+            return {};
+        }
+        try {
+            const parsed = JSON.parse(value);
+            if (typeof parsed === 'object' && parsed !== null) {
+                return parsed;
+            }
+            return {};
+        }
+        catch {
+            return {};
         }
     }
     async run(cypher, params) {

package/dist/store/kuzu_store.js.map

@@ -1 +1 @@
-{"version":3,"file":"kuzu_store.js","sourceRoot":"","sources":["../../src/store/kuzu_store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAe,MAAM,MAAM,CAAC;AAKzD,MAAM,MAAM,GAAG;IACd,sKAAsK;IACtK,gFAAgF;CAChF,CAAC;AAEF,MAAM,OAAO,SAAS;IAIrB,YAAY,MAAc;QACzB,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,UAAU;QACf,KAAK,MAAM,SAAS,IAAI,MAAM,EAAE,CAAC;YAChC,SAAS,CAAC,YAAY,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;QAC1D,CAAC;IACF,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAkB,EAAE,KAAkB;QAChD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CACvC,kKAAkK,CAClK,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,SAAS,CAAC,YAAY,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE;gBACxD,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,KAAK;gBAChC,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC;gBACrC,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,IAAI,CAAC;aACjC,CAAC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CACvC,+FAA+F,CAC/F,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,SAAS,CAAC,YAAY,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC9G,CAAC;IACF,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,MAAc,EAAE,MAAkC;QAC3D,MAAM,MAAM,GAAG,MAAM,KAAK,SAAS;YAClC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;YAC/B,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;QACpE,IAAI,CAAC;YACJ,OAAO,MAAM,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;QAC/C,CAAC;gBAAS,CAAC;YACV,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;IACF,CAAC;IAED,KAAK,CAAC,KAAK;QACV,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QACxB,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,MAAmC;QACvD,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACK,MAAM,CAAC,YAAY,CAAC,MAAmC;QAC9D,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9D,IAAI,CAAC,KAAK,EAAE,CAAC;QACd,CAAC;IACF,CAAC;CACD"}
+{"version":3,"file":"kuzu_store.js","sourceRoot":"","sources":["../../src/store/kuzu_store.ts"],"names":[],"mappings":"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"}

package/dist/store/output_folder.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The single source of truth for the output-folder layout. Every artifact a CLI
+ * command reads or writes under the output folder is derived from one root, so
+ * callers pass `--output-folder` and never an individual file path:
+ *
+ *   <root>/graph/        nodes.jsonl, edges.jsonl, source.json   (JsonlStore / JsonlReader)
+ *   <root>/graph.kuzu    embedded Kùzu database                  (KuzuStore)
+ *   <root>/prof/         V8 .cpuprofile files                    (profile_and_enrich.sh)
+ *   <root>/bench/        <target>.baseline.json benchmark baselines
+ *
+ * The directory segment names live only here. The store classes own the JSONL
+ * filenames (a format concern), and both `KuzuStore` and `JsonlStore` create
+ * their own parent directories, so this type never touches the filesystem.
+ */
+export declare class OutputFolder {
+    private readonly root;
+    constructor(root: string);
+    /** The output folder root itself (absolute). */
+    get path(): string;
+    /** Directory holding nodes.jsonl, edges.jsonl, and source.json. */
+    get graphDir(): string;
+    /** Embedded Kùzu database path. */
+    get dbPath(): string;
+    /** Directory for V8 .cpuprofile files. */
+    get profDir(): string;
+    /** Directory for benchmark baselines. */
+    get benchDir(): string;
+    /** Baseline file for one benchmark target, e.g. `<root>/bench/titleCase.baseline.json`. */
+    baselinePath(target: string): string;
+    /**
+     * Path of the generated codebase brief for a given file extension (`md`, `pdf`,
+     * or `json`). Like {@link OutputFolder.dbPath}, the basename lives only here so
+     * every output path stays derived from the one root.
+     */
+    reportPath(extension: string): string;
+    /**
+     * Make a benchmark target name safe as a filename. Targets are symbol names
+     * (e.g. `titleCase`) but could contain path-like characters; collapse anything
+     * outside [A-Za-z0-9._-] to '_' so the baseline path stays inside benchDir.
+     */
+    private static sanitizeTarget;
+}
+//# sourceMappingURL=output_folder.d.ts.map

package/dist/store/output_folder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output_folder.d.ts","sourceRoot":"","sources":["../../src/store/output_folder.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,EAAE,MAAM;IAIxB,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mEAAmE;IACnE,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,mCAAmC;IACnC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,0CAA0C;IAC1C,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,yCAAyC;IACzC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,2FAA2F;IAC3F,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAIpC;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIrC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;CAG7B"}

package/dist/store/output_folder.js

@@ -0,0 +1,61 @@
+import { join, resolve } from 'node:path';
+/**
+ * The single source of truth for the output-folder layout. Every artifact a CLI
+ * command reads or writes under the output folder is derived from one root, so
+ * callers pass `--output-folder` and never an individual file path:
+ *
+ *   <root>/graph/        nodes.jsonl, edges.jsonl, source.json   (JsonlStore / JsonlReader)
+ *   <root>/graph.kuzu    embedded Kùzu database                  (KuzuStore)
+ *   <root>/prof/         V8 .cpuprofile files                    (profile_and_enrich.sh)
+ *   <root>/bench/        <target>.baseline.json benchmark baselines
+ *
+ * The directory segment names live only here. The store classes own the JSONL
+ * filenames (a format concern), and both `KuzuStore` and `JsonlStore` create
+ * their own parent directories, so this type never touches the filesystem.
+ */
+export class OutputFolder {
+    constructor(root) {
+        this.root = resolve(root);
+    }
+    /** The output folder root itself (absolute). */
+    get path() {
+        return this.root;
+    }
+    /** Directory holding nodes.jsonl, edges.jsonl, and source.json. */
+    get graphDir() {
+        return join(this.root, 'graph');
+    }
+    /** Embedded Kùzu database path. */
+    get dbPath() {
+        return join(this.root, 'graph.kuzu');
+    }
+    /** Directory for V8 .cpuprofile files. */
+    get profDir() {
+        return join(this.root, 'prof');
+    }
+    /** Directory for benchmark baselines. */
+    get benchDir() {
+        return join(this.root, 'bench');
+    }
+    /** Baseline file for one benchmark target, e.g. `<root>/bench/titleCase.baseline.json`. */
+    baselinePath(target) {
+        return join(this.benchDir, `${OutputFolder.sanitizeTarget(target)}.baseline.json`);
+    }
+    /**
+     * Path of the generated codebase brief for a given file extension (`md`, `pdf`,
+     * or `json`). Like {@link OutputFolder.dbPath}, the basename lives only here so
+     * every output path stays derived from the one root.
+     */
+    reportPath(extension) {
+        return join(this.root, `CODEBASE_BRIEF.${extension}`);
+    }
+    /**
+     * Make a benchmark target name safe as a filename. Targets are symbol names
+     * (e.g. `titleCase`) but could contain path-like characters; collapse anything
+     * outside [A-Za-z0-9._-] to '_' so the baseline path stays inside benchDir.
+     */
+    static sanitizeTarget(target) {
+        return target.replace(/[^A-Za-z0-9._-]+/g, '_');
+    }
+}
+//# sourceMappingURL=output_folder.js.map

package/dist/store/output_folder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output_folder.js","sourceRoot":"","sources":["../../src/store/output_folder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,YAAY;IAGxB,YAAY,IAAY;QACvB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,gDAAgD;IAChD,IAAI,IAAI;QACP,OAAO,IAAI,CAAC,IAAI,CAAC;IAClB,CAAC;IAED,mEAAmE;IACnE,IAAI,QAAQ;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,mCAAmC;IACnC,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACtC,CAAC;IAED,0CAA0C;IAC1C,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,yCAAyC;IACzC,IAAI,QAAQ;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,2FAA2F;IAC3F,YAAY,CAAC,MAAc;QAC1B,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,YAAY,CAAC,cAAc,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACpF,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,SAAiB;QAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,kBAAkB,SAAS,EAAE,CAAC,CAAC;IACvD,CAAC;IAED;;;;OAIG;IACK,MAAM,CAAC,cAAc,CAAC,MAAc;QAC3C,OAAO,MAAM,CAAC,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;CACD"}