ts-knowledge-graph 0.1.2 → 0.1.6

package/dist/commands/webview_command.js

@@ -0,0 +1,186 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { GitSource } from '../extract/git_source.js';
+import { SOURCE_MANIFEST_KEY, SourceManifestSchema } from '../schema/source_manifest.js';
+import { KuzuStore } from '../store/kuzu_store.js';
+import { OutputFolder } from '../store/output_folder.js';
+import { CommandHelpers } from './command_helpers.js';
+/**
+ * Static assets of the web visualisation, resolved relative to this module so
+ * the same path works from `src/` (tsx) and from `dist/` (published package).
+ */
+const WEB_ROOT = fileURLToPath(new URL('../../contribs/webview/web', import.meta.url));
+const DATA_SCRIPT_PATH = '/js_autogenerated/graph_data.js';
+const DEFAULT_PORT = '4173';
+const MIME_TYPES = {
+    '.css': 'text/css; charset=utf-8',
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+};
+/**
+ * `webview` command — serves the knowledge graph database in an interactive web
+ * visualisation. The graph is read from Kùzu once at startup and injected into
+ * the page as `/js_autogenerated/graph_data.js`; all other assets are served statically
+ * from the contribs/webview/web directory.
+ */
+export class WebviewCommand {
+    static register(program) {
+        const command = program
+            .command('webview')
+            .description('serve the knowledge graph database in a web visualisation');
+        CommandHelpers.addOutputFolderOption(command)
+            .option('-p, --port <port>', 'HTTP port to listen on', DEFAULT_PORT)
+            .option('-s, --source <dir>', 'fallback project root for GitHub links when the graph records no source', '.')
+            .action(async (options) => {
+            await WebviewCommand.run(options);
+        });
+    }
+    static async run(options) {
+        const dbPath = new OutputFolder(options.outputFolder).dbPath;
+        if (existsSync(dbPath) === false) {
+            console.error(chalk.red(`database not found at ${dbPath} — run \`extract\` then \`load\` first`));
+            process.exitCode = 1;
+            return;
+        }
+        const github = await WebviewCommand.resolveGitHubSource(dbPath, resolve(options.source));
+        const sourceScript = github === undefined ? '' : `window.GRAPH_SOURCE = ${JSON.stringify({ github })};\n`;
+        const dataScript = sourceScript + await WebviewCommand.buildDataScript(dbPath);
+        const server = createServer((request, response) => {
+            void WebviewCommand.handle(request, response, dataScript);
+        });
+        server.listen(Number(options.port), () => {
+            console.log(chalk.green(`✓ serving the knowledge graph at http://localhost:${options.port}/`));
+            console.log(chalk.gray('  press Ctrl+C to stop'));
+        });
+    }
+    /**
+     * Reads every node and edge from the database and renders them as the
+     * `window.GRAPH_DATA` script the visualisation page loads on boot.
+     */
+    static async buildDataScript(dbPath) {
+        const store = new KuzuStore(dbPath);
+        await store.initSchema();
+        try {
+            const nodeRows = await store.run('MATCH (n:GraphNode) RETURN n.id AS id, n.kind AS kind, n.name AS name, n.filePath AS filePath, n.exported AS exported, n.startLine AS startLine, n.endLine AS endLine, n.metadata AS metadata');
+            const edgeRows = await store.run('MATCH (f:GraphNode)-[e:Edge]->(t:GraphNode) RETURN f.id AS from, e.kind AS kind, t.id AS to, e.metadata AS metadata');
+            const nodes = nodeRows.map((row) => ({
+                id: String(row.id),
+                kind: String(row.kind),
+                name: String(row.name),
+                filePath: String(row.filePath),
+                exported: row.exported === true,
+                range: {
+                    startLine: Number(row.startLine),
+                    startColumn: 0,
+                    endLine: Number(row.endLine),
+                    endColumn: 0,
+                },
+                metadata: WebviewCommand.decodeMetadata(row.metadata),
+            }));
+            const edges = edgeRows.map((row, index) => ({
+                id: `e${index}`,
+                kind: String(row.kind),
+                from: String(row.from),
+                to: String(row.to),
+                metadata: WebviewCommand.decodeMetadata(row.metadata),
+            }));
+            console.log(chalk.cyan(`loaded ${nodes.length} nodes, ${edges.length} edges from ${dbPath}`));
+            return `window.GRAPH_DATA = ${JSON.stringify({ nodes, edges })};\n`;
+        }
+        finally {
+            await store.close();
+        }
+    }
+    /**
+     * Decodes the JSON `metadata` column into a record so the visualisation can
+     * read `metadata.runtime`. A missing, empty (`{}`), or malformed value yields
+     * `undefined`, which `JSON.stringify` omits — keeping the payload small and
+     * letting un-enriched nodes simply carry no metadata.
+     */
+    static decodeMetadata(value) {
+        if (typeof value !== 'string' || value.length === 0) {
+            return undefined;
+        }
+        try {
+            const parsed = JSON.parse(value);
+            if (typeof parsed === 'object' && parsed !== null && Object.keys(parsed).length > 0) {
+                return parsed;
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Resolves the GitHub source for the served graph. Prefers the provenance
+     * `extract` recorded in the database — it pins the exact commit and in-repo
+     * `prefix` that was parsed — and falls back to detecting it live from
+     * `sourceDir` for graphs built before provenance was captured. Returns
+     * `undefined` when neither is available, so the page shows plain-text paths.
+     */
+    static async resolveGitHubSource(dbPath, sourceDir) {
+        const stored = await WebviewCommand.readStoredSource(dbPath);
+        if (stored !== undefined) {
+            console.log(chalk.cyan(`linking files to ${stored.baseUrl} @ ${stored.commit.slice(0, 7)} (recorded by extract)`));
+            return stored;
+        }
+        const detected = await GitSource.detect(sourceDir);
+        if (detected === undefined) {
+            console.log(chalk.gray('no GitHub source recorded or detected — file paths will not link to source'));
+            return undefined;
+        }
+        console.log(chalk.cyan(`linking files to ${detected.baseUrl} @ ${detected.commit.slice(0, 7)} (detected from ${sourceDir})`));
+        return detected;
+    }
+    /** Reads the source provenance `load` stored in the database, or `undefined` when absent or malformed. */
+    static async readStoredSource(dbPath) {
+        const store = new KuzuStore(dbPath);
+        await store.initSchema();
+        try {
+            const raw = await store.readGraphMeta(SOURCE_MANIFEST_KEY);
+            if (raw === null) {
+                return undefined;
+            }
+            const parsed = SourceManifestSchema.safeParse(raw);
+            return parsed.success === true ? parsed.data : undefined;
+        }
+        finally {
+            await store.close();
+        }
+    }
+    static async handle(request, response, dataScript) {
+        const url = new URL(request.url ?? '/', 'http://localhost');
+        const pathname = url.pathname === '/' ? '/index.html' : url.pathname;
+        if (pathname === DATA_SCRIPT_PATH) {
+            response.writeHead(200, { 'content-type': MIME_TYPES['.js'] });
+            response.end(dataScript);
+            return;
+        }
+        const filePath = normalize(join(WEB_ROOT, pathname));
+        if (filePath.startsWith(WEB_ROOT + sep) === false) {
+            WebviewCommand.notFound(response);
+            return;
+        }
+        try {
+            const content = await readFile(filePath);
+            response.writeHead(200, { 'content-type': MIME_TYPES[extname(filePath)] ?? 'application/octet-stream' });
+            response.end(content);
+        }
+        catch {
+            WebviewCommand.notFound(response);
+        }
+    }
+    static notFound(response) {
+        response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+        response.end('not found');
+    }
+}
+//# sourceMappingURL=webview_command.js.map

package/dist/commands/webview_command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webview_command.js","sourceRoot":"","sources":["../../src/commands/webview_command.ts"],"names":[],"mappings":"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"}

package/dist/enrich/cpu_profile.d.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+/**
+ * The on-disk shape of a `node --cpu-prof` output (`.cpuprofile`). `samples`
+ * holds one profile-node id per sampling tick; `timeDeltas` holds the elapsed
+ * microseconds preceding each tick. Both are optional because some producers
+ * emit only per-node `hitCount`.
+ */
+export declare const CpuProfileSchema: z.ZodObject<{
+    nodes: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        callFrame: z.ZodObject<{
+            functionName: z.ZodString;
+            scriptId: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+            url: z.ZodString;
+            lineNumber: z.ZodNumber;
+            columnNumber: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            functionName: string;
+            url: string;
+            lineNumber: number;
+            columnNumber: number;
+            scriptId?: string | number | undefined;
+        }, {
+            functionName: string;
+            url: string;
+            lineNumber: number;
+            columnNumber: number;
+            scriptId?: string | number | undefined;
+        }>;
+        hitCount: z.ZodOptional<z.ZodNumber>;
+        children: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        id: number;
+        callFrame: {
+            functionName: string;
+            url: string;
+            lineNumber: number;
+            columnNumber: number;
+            scriptId?: string | number | undefined;
+        };
+        hitCount?: number | undefined;
+        children?: number[] | undefined;
+    }, {
+        id: number;
+        callFrame: {
+            functionName: string;
+            url: string;
+            lineNumber: number;
+            columnNumber: number;
+            scriptId?: string | number | undefined;
+        };
+        hitCount?: number | undefined;
+        children?: number[] | undefined;
+    }>, "many">;
+    startTime: z.ZodOptional<z.ZodNumber>;
+    endTime: z.ZodOptional<z.ZodNumber>;
+    samples: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    timeDeltas: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+}, "strip", z.ZodTypeAny, {
+    nodes: {
+        id: number;
+        callFrame: {
+            functionName: string;
+            url: string;
+            lineNumber: number;
+            columnNumber: number;
+            scriptId?: string | number | undefined;
+        };
+        hitCount?: number | undefined;
+        children?: number[] | undefined;
+    }[];
+    startTime?: number | undefined;
+    endTime?: number | undefined;
+    samples?: number[] | undefined;
+    timeDeltas?: number[] | undefined;
+}, {
+    nodes: {
+        id: number;
+        callFrame: {
+            functionName: string;
+            url: string;
+            lineNumber: number;
+            columnNumber: number;
+            scriptId?: string | number | undefined;
+        };
+        hitCount?: number | undefined;
+        children?: number[] | undefined;
+    }[];
+    startTime?: number | undefined;
+    endTime?: number | undefined;
+    samples?: number[] | undefined;
+    timeDeltas?: number[] | undefined;
+}>;
+export type CpuProfileData = z.infer<typeof CpuProfileSchema>;
+/**
+ * One executing location distilled from the profile: its call frame plus the
+ * self time and sample count attributed to it. `line` is converted to the
+ * one-based convention so it can be compared against graph node ranges.
+ */
+export type FrameSample = {
+    functionName: string;
+    url: string;
+    line: number;
+    column: number;
+    samples: number;
+    selfMicros: number;
+};
+/** The minimal frame identity the join needs: a function name, a script url, and a one-based line. */
+export type FrameRef = {
+    functionName: string;
+    url: string;
+    line: number;
+};
+/** One caller → callee relation from the profile's call tree, weighted by the callee's subtree samples. */
+export type RuntimeCallEdge = {
+    caller: FrameRef;
+    callee: FrameRef;
+    samples: number;
+};
+export declare class CpuProfile {
+    /**
+     * Parses and validates raw `.cpuprofile` JSON text. Throws a `ZodError` if
+     * the document does not match the V8 profile shape.
+     */
+    static parse(jsonText: string): CpuProfileData;
+    /**
+     * Collapses the profile into one {@link FrameSample} per profile node that
+     * received at least one sample.
+     *
+     * Self time is summed from `timeDeltas`, attributing `timeDeltas[i]` to
+     * `samples[i]` — the standard self-time approximation where total attributed
+     * time equals the sum of all deltas. When `samples`/`timeDeltas` are absent,
+     * it falls back to each node's `hitCount` with zero self time.
+     */
+    static aggregate(profile: CpuProfileData): FrameSample[];
+    /** Total number of sampling ticks in the profile, for coverage reporting. */
+    static totalSamples(profile: CpuProfileData): number;
+    /**
+     * Extracts the runtime call graph from the profile's call tree: one edge per
+     * parent → child relation (the parent function was on the stack directly above
+     * the child), weighted by the child's subtree sample count — how much execution
+     * flowed through that call. Frames carry one-based lines so they resolve against
+     * graph node ranges, mirroring {@link aggregate}.
+     */
+    static callEdges(profile: CpuProfileData): RuntimeCallEdge[];
+    private static frameRef;
+    /**
+     * Sample count per profile-node id: from the per-tick `samples` array when
+     * present, otherwise each node's `hitCount`. The same weight {@link aggregate}
+     * attributes, keyed here for the call-tree walk.
+     */
+    private static samplesByNode;
+    /**
+     * Total samples in each profile node's subtree (itself plus all descendants)
+     * over the call tree. Iterative post-order with an explicit stack so a deep call
+     * chain cannot overflow, and a guard so a malformed non-tree cannot loop.
+     */
+    private static subtreeSamples;
+}
+//# sourceMappingURL=cpu_profile.d.ts.map

package/dist/enrich/cpu_profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpu_profile.d.ts","sourceRoot":"","sources":["../../src/enrich/cpu_profile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsBxB;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAM3B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE9D;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,sGAAsG;AACtG,MAAM,MAAM,QAAQ,GAAG;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,2GAA2G;AAC3G,MAAM,MAAM,eAAe,GAAG;IAC7B,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,qBAAa,UAAU;IACtB;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc;IAI9C;;;;;;;;OAQG;IACH,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,WAAW,EAAE;IAyCxD,6EAA6E;IAC7E,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM;IAOpD;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,eAAe,EAAE;IAoB5D,OAAO,CAAC,MAAM,CAAC,QAAQ;IAIvB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAkB5B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;CAgC7B"}

package/dist/enrich/cpu_profile.js

@@ -0,0 +1,185 @@
+import { z } from 'zod';
+/**
+ * A single call frame as it appears in a V8 CPU profile node. Line and column
+ * numbers are **zero-based** in the V8 inspector protocol, unlike the one-based
+ * lines ts-morph (and therefore the graph's `range`) uses.
+ */
+const CallFrameSchema = z.object({
+    functionName: z.string(),
+    scriptId: z.union([z.string(), z.number()]).optional(),
+    url: z.string(),
+    lineNumber: z.number(),
+    columnNumber: z.number(),
+});
+const ProfileNodeSchema = z.object({
+    id: z.number(),
+    callFrame: CallFrameSchema,
+    hitCount: z.number().optional(),
+    children: z.array(z.number()).optional(),
+});
+/**
+ * The on-disk shape of a `node --cpu-prof` output (`.cpuprofile`). `samples`
+ * holds one profile-node id per sampling tick; `timeDeltas` holds the elapsed
+ * microseconds preceding each tick. Both are optional because some producers
+ * emit only per-node `hitCount`.
+ */
+export const CpuProfileSchema = z.object({
+    nodes: z.array(ProfileNodeSchema),
+    startTime: z.number().optional(),
+    endTime: z.number().optional(),
+    samples: z.array(z.number()).optional(),
+    timeDeltas: z.array(z.number()).optional(),
+});
+export class CpuProfile {
+    /**
+     * Parses and validates raw `.cpuprofile` JSON text. Throws a `ZodError` if
+     * the document does not match the V8 profile shape.
+     */
+    static parse(jsonText) {
+        return CpuProfileSchema.parse(JSON.parse(jsonText));
+    }
+    /**
+     * Collapses the profile into one {@link FrameSample} per profile node that
+     * received at least one sample.
+     *
+     * Self time is summed from `timeDeltas`, attributing `timeDeltas[i]` to
+     * `samples[i]` — the standard self-time approximation where total attributed
+     * time equals the sum of all deltas. When `samples`/`timeDeltas` are absent,
+     * it falls back to each node's `hitCount` with zero self time.
+     */
+    static aggregate(profile) {
+        const samplesByNode = new Map();
+        const microsByNode = new Map();
+        const samples = profile.samples;
+        if (samples !== undefined && samples.length > 0) {
+            const deltas = profile.timeDeltas ?? [];
+            for (let index = 0; index < samples.length; index += 1) {
+                const nodeId = samples[index];
+                samplesByNode.set(nodeId, (samplesByNode.get(nodeId) ?? 0) + 1);
+                const delta = deltas[index] ?? 0;
+                const safeDelta = delta > 0 ? delta : 0;
+                microsByNode.set(nodeId, (microsByNode.get(nodeId) ?? 0) + safeDelta);
+            }
+        }
+        else {
+            for (const node of profile.nodes) {
+                const hits = node.hitCount ?? 0;
+                if (hits > 0) {
+                    samplesByNode.set(node.id, hits);
+                }
+            }
+        }
+        const frames = [];
+        for (const node of profile.nodes) {
+            const sampleCount = samplesByNode.get(node.id) ?? 0;
+            if (sampleCount === 0) {
+                continue;
+            }
+            frames.push({
+                functionName: node.callFrame.functionName,
+                url: node.callFrame.url,
+                line: node.callFrame.lineNumber + 1,
+                column: node.callFrame.columnNumber,
+                samples: sampleCount,
+                selfMicros: microsByNode.get(node.id) ?? 0,
+            });
+        }
+        return frames;
+    }
+    /** Total number of sampling ticks in the profile, for coverage reporting. */
+    static totalSamples(profile) {
+        if (profile.samples !== undefined && profile.samples.length > 0) {
+            return profile.samples.length;
+        }
+        return profile.nodes.reduce((sum, node) => sum + (node.hitCount ?? 0), 0);
+    }
+    /**
+     * Extracts the runtime call graph from the profile's call tree: one edge per
+     * parent → child relation (the parent function was on the stack directly above
+     * the child), weighted by the child's subtree sample count — how much execution
+     * flowed through that call. Frames carry one-based lines so they resolve against
+     * graph node ranges, mirroring {@link aggregate}.
+     */
+    static callEdges(profile) {
+        const subtree = CpuProfile.subtreeSamples(profile);
+        const nodeById = new Map(profile.nodes.map((node) => [node.id, node]));
+        const edges = [];
+        for (const node of profile.nodes) {
+            for (const childId of node.children ?? []) {
+                const child = nodeById.get(childId);
+                if (child === undefined) {
+                    continue;
+                }
+                edges.push({
+                    caller: CpuProfile.frameRef(node.callFrame),
+                    callee: CpuProfile.frameRef(child.callFrame),
+                    samples: subtree.get(childId) ?? 0,
+                });
+            }
+        }
+        return edges;
+    }
+    static frameRef(callFrame) {
+        return { functionName: callFrame.functionName, url: callFrame.url, line: callFrame.lineNumber + 1 };
+    }
+    /**
+     * Sample count per profile-node id: from the per-tick `samples` array when
+     * present, otherwise each node's `hitCount`. The same weight {@link aggregate}
+     * attributes, keyed here for the call-tree walk.
+     */
+    static samplesByNode(profile) {
+        const counts = new Map();
+        const samples = profile.samples;
+        if (samples !== undefined && samples.length > 0) {
+            for (const nodeId of samples) {
+                counts.set(nodeId, (counts.get(nodeId) ?? 0) + 1);
+            }
+            return counts;
+        }
+        for (const node of profile.nodes) {
+            const hits = node.hitCount ?? 0;
+            if (hits > 0) {
+                counts.set(node.id, hits);
+            }
+        }
+        return counts;
+    }
+    /**
+     * Total samples in each profile node's subtree (itself plus all descendants)
+     * over the call tree. Iterative post-order with an explicit stack so a deep call
+     * chain cannot overflow, and a guard so a malformed non-tree cannot loop.
+     */
+    static subtreeSamples(profile) {
+        const self = CpuProfile.samplesByNode(profile);
+        const nodeById = new Map(profile.nodes.map((node) => [node.id, node]));
+        const subtree = new Map();
+        for (const root of profile.nodes) {
+            if (subtree.has(root.id)) {
+                continue;
+            }
+            const stack = [root.id];
+            const onStack = new Set([root.id]);
+            while (stack.length > 0) {
+                const id = stack[stack.length - 1];
+                const children = (nodeById.get(id)?.children ?? []).filter((child) => nodeById.has(child));
+                const pending = children.filter((child) => subtree.has(child) === false && onStack.has(child) === false);
+                if (pending.length > 0) {
+                    for (const child of pending) {
+                        onStack.add(child);
+                        stack.push(child);
+                    }
+                    continue;
+                }
+                let sum = self.get(id) ?? 0;
+                for (const child of children) {
+                    sum += subtree.get(child) ?? 0;
+                }
+                subtree.set(id, sum);
+                onStack.delete(id);
+                stack.pop();
+            }
+        }
+        return subtree;
+    }
+}
+//# sourceMappingURL=cpu_profile.js.map

package/dist/enrich/cpu_profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpu_profile.js","sourceRoot":"","sources":["../../src/enrich/cpu_profile.ts"],"names":[],"mappings":"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"}

package/dist/enrich/runtime_enricher.d.ts

@@ -0,0 +1,64 @@
+import { KuzuStore } from '../store/kuzu_store.js';
+import { DroppedFrameGroup } from './runtime_join.js';
+/** The telemetry source tag written into `metadata.runtime.source`. */
+export declare const RUNTIME_SOURCE_CPU_PROFILE = "v8-cpuprofile";
+/** Namespaced key under which runtime metrics are stored on a node's metadata. */
+export declare const RUNTIME_METADATA_KEY = "runtime";
+/** Edge kind under which the runtime call graph extracted from the profile is stored. */
+export declare const RUNTIME_CALL_EDGE_KIND = "CALLS_RUNTIME";
+/**
+ * The measured-weight metrics attached to a node under `metadata.runtime`. The
+ * shape is intentionally open-ended (latency, call frequency, cost, … may join
+ * later); a CPU profile populates self time and sample count.
+ */
+export type RuntimeMetrics = {
+    source: string;
+    samples: number;
+    selfMicros: number;
+    selfMs: number;
+};
+export type Hotspot = {
+    id: string;
+    name: string;
+    kind: string;
+    filePath: string;
+    selfMs: number;
+    samples: number;
+};
+export type EnrichReport = {
+    totalSamples: number;
+    matchedNodes: number;
+    matchedFrames: number;
+    matchedSamples: number;
+    matchedSelfMs: number;
+    matchedByName: number;
+    matchedByRange: number;
+    droppedFrames: number;
+    droppedSamples: number;
+    /** Runtime call edges (`CALLS_RUNTIME`) attached after both endpoints resolved to graph nodes. */
+    runtimeEdges: number;
+    /** Profile call-tree edges dropped because an endpoint resolved to no node, or to the same node (recursion). */
+    droppedCallEdges: number;
+    dropped: DroppedFrameGroup[];
+    hotspots: Hotspot[];
+};
+export type EnrichOptions = {
+    /** Project root the profile's absolute frame urls resolve against. */
+    root: string;
+};
+export declare class RuntimeEnricher {
+    /**
+     * Ingests a V8 CPU profile and attaches `metadata.runtime` (self time and
+     * sample count) onto the graph nodes whose ranges enclose the profiled
+     * frames. Existing metadata is preserved; only the `runtime` key is written,
+     * so re-running with the same profile is idempotent. Unmatched frames are
+     * counted and returned in the report rather than dropped silently.
+     */
+    static enrich(store: KuzuStore, profileText: string, options: EnrichOptions): Promise<EnrichReport>;
+    private static toMetrics;
+    /** Builds a `CALLS_RUNTIME` graph edge from a resolved runtime call edge, weighted by its sample count. */
+    private static toCallEdge;
+    /** Converts microseconds to milliseconds, rounded to microsecond precision. */
+    private static microsToMs;
+}
+//# sourceMappingURL=runtime_enricher.d.ts.map

package/dist/enrich/runtime_enricher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime_enricher.d.ts","sourceRoot":"","sources":["../../src/enrich/runtime_enricher.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAgD,MAAM,mBAAmB,CAAC;AAEpG,uEAAuE;AACvE,eAAO,MAAM,0BAA0B,kBAAkB,CAAC;AAE1D,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,kGAAkG;IAClG,YAAY,EAAE,MAAM,CAAC;IACrB,gHAAgH;IAChH,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,QAAQ,EAAE,OAAO,EAAE,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC3B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,qBAAa,eAAe;IAC3B;;;;;;OAMG;WACU,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAiEzG,OAAO,CAAC,MAAM,CAAC,SAAS;IASxB,2GAA2G;IAC3G,OAAO,CAAC,MAAM,CAAC,UAAU;IAUzB,+EAA+E;IAC/E,OAAO,CAAC,MAAM,CAAC,UAAU;CAGzB"}