ts-knowledge-graph 0.1.1 → 0.1.4

package/contribs/web_visualisation/web/tsconfig.json

@@ -0,0 +1,18 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "ESNext",
+		"moduleResolution": "Bundler",
+		"lib": ["ES2020", "DOM", "DOM.Iterable"],
+		"strict": true,
+		"allowJs": true,
+		"checkJs": true,
+		"noEmit": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"forceConsistentCasingInFileNames": true,
+		"skipLibCheck": true,
+		"types": []
+	},
+	"include": ["js/app.js", "types/**/*.d.ts"]
+}

package/contribs/web_visualisation/web/types/app_globals.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Ambient declarations for the static web viewer (`web/js/app.js`).
+ *
+ * The page ships as plain, build-free JavaScript and is type-checked in place
+ * with `// @ts-check`. This file gives that JavaScript precise types for the
+ * data it loads (the knowledge-graph JSONL records, mirrored from
+ * `src/schema`), and a deliberately loose surface for the Cytoscape.js library,
+ * which is loaded as a global from a CDN and has no bundled types here.
+ */
+
+/* ---------- knowledge-graph data (mirrors src/schema) ---------- */
+
+/** Source range of a symbol; mirrors `RangeSchema` in `src/schema/node.ts`. */
+interface RawRange {
+	startLine: number;
+	startColumn: number;
+	endLine: number;
+	endColumn: number;
+}
+
+/** Per-node runtime metrics attached by `enrich`, read from `metadata.runtime`. */
+interface NodeRuntime {
+	selfMs?: number;
+	samples?: number;
+	source?: string;
+}
+
+/** A graph node as serialised in `nodes.jsonl`; mirrors `GraphNodeSchema`. */
+interface RawNode {
+	id: string;
+	kind: string;
+	name: string;
+	filePath: string;
+	range?: RawRange;
+	exported?: boolean;
+	metadata?: { runtime?: NodeRuntime | null; [key: string]: unknown } | null;
+}
+
+/** A graph edge as serialised in `edges.jsonl`; mirrors `GraphEdgeSchema`. */
+interface RawEdge {
+	id: string;
+	kind: string;
+	from: string;
+	to: string;
+	metadata?: { count?: number; [key: string]: unknown } | null;
+}
+
+/** The embedded `window.GRAPH_DATA` payload written by `scripts/build-data.ts`. */
+interface GraphData {
+	nodes: RawNode[];
+	edges: RawEdge[];
+}
+
+/** The `window.KIND_DESCRIPTIONS` payload: one-line help per node/edge kind. */
+interface KindDescriptions {
+	nodes: Record<string, string>;
+	edges: Record<string, string>;
+}
+
+/** GitHub permalink descriptor; mirrors `GitHubSource` in `src/commands/web_command.ts`. */
+interface GitHubSource {
+	baseUrl: string;
+	commit: string;
+	prefix: string;
+}
+
+/** The `window.GRAPH_SOURCE` payload injected by the `web` command. */
+interface GraphSource {
+	github?: GitHubSource;
+}
+
+/** The single mutable view-model the viewer threads through its render functions. */
+interface AppState {
+	nodes: RawNode[];
+	edges: RawEdge[];
+	cy: CyCore | undefined;
+	hiddenNodeKinds: Set<string>;
+	hiddenEdgeKinds: Set<string>;
+	hideIsolated: boolean;
+	onlyMeasured: boolean;
+	droppedFiles: { nodes: RawNode[] | undefined; edges: RawEdge[] | undefined };
+	encoding: 'structural' | 'runtime';
+	runtime: { maxSelfMs: number; measuredCount: number; totalSelfMs: number };
+}
+
+/* ---------- Cytoscape.js (loaded as a CDN global, untyped) ---------- */
+
+/**
+ * A Cytoscape collection or single element. Only the surface the viewer uses is
+ * declared. `data()` is intentionally `any`: it is Cytoscape's dynamic per-element
+ * bag and the one place this otherwise-strict file crosses an untyped boundary.
+ */
+interface CyCollection {
+	length: number;
+	data(name?: string): any;
+	id(): string;
+	degree(): number;
+	closedNeighborhood(): CyCollection;
+	connectedEdges(): CyCollection;
+	source(): CyCollection;
+	target(): CyCollection;
+	addClass(names: string): CyCollection;
+	removeClass(names: string): CyCollection;
+	toggleClass(names: string, flag?: boolean): CyCollection;
+	hasClass(name: string): boolean;
+	not(selector: string): CyCollection;
+	forEach(each: (element: CyCollection, index: number) => void): void;
+	some(test: (element: CyCollection, index: number) => boolean): boolean;
+	layout(options: unknown): { run(): CyCollection };
+}
+
+/** A Cytoscape event; `target` is the element or core the event fired on. */
+interface CyEvent {
+	target: any;
+}
+
+/** The Cytoscape core instance returned by the `cytoscape(...)` factory. */
+interface CyCore {
+	destroy(): void;
+	on(events: string, handler: (event: CyEvent) => void): CyCore;
+	on(events: string, selector: string, handler: (event: CyEvent) => void): CyCore;
+	style(style?: unknown): CyCore;
+	elements(selector?: string): CyCollection;
+	nodes(selector?: string): CyCollection;
+	edges(selector?: string): CyCollection;
+	batch(callback: () => void): void;
+	getElementById(id: string): CyCollection;
+	animate(options: unknown, params?: unknown): CyCore;
+}
+
+interface CytoscapeOptions {
+	container?: HTMLElement | null;
+	elements?: unknown;
+	style?: unknown;
+	layout?: unknown;
+}
+
+declare function cytoscape(options?: CytoscapeOptions): CyCore;
+
+/* ---------- globals injected into the page ---------- */
+
+interface Window {
+	GRAPH_DATA?: GraphData;
+	KIND_DESCRIPTIONS?: KindDescriptions;
+	GRAPH_SOURCE?: GraphSource | null;
+}

package/dist/benchmark/benchmark_stats.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure statistics for the benchmark gate. Runtime measurement is noisy, so a
+ * single number lies: every benchmark reports the **median** of N runs plus the
+ * **spread**, and a baseline→after comparison is an advisory delta, never a
+ * deterministic guarantee. These helpers are deliberately side-effect-free so
+ * the variance handling is unit-tested directly, apart from any profiling.
+ */
+/** A node's metric distribution over N runs: the headline median plus the spread that qualifies it. */
+export type BenchmarkStatsSummary = {
+    runs: number;
+    median: number;
+    min: number;
+    max: number;
+    mean: number;
+    /** `max - min`: the observed spread, a coarse read on how noisy the measurement was. */
+    spread: number;
+    /** The raw per-run samples, in run order. */
+    values: number[];
+};
+/** A baseline→after comparison of two medians. Negative `absolute`/`percent` means the metric went down (faster / fewer). */
+export type BenchmarkDelta = {
+    baselineMedian: number;
+    currentMedian: number;
+    /** `currentMedian - baselineMedian`. */
+    absolute: number;
+    /** `absolute / baselineMedian`, e.g. `-0.38` for a 38% reduction. `NaN` when the baseline median is 0. */
+    percent: number;
+};
+export declare class BenchmarkStats {
+    /** The median of a non-empty sample set (mean of the two middle values when the count is even). */
+    static median(values: number[]): number;
+    /** Reduce per-run samples to the median + spread summary. Throws on an empty set. */
+    static summarize(values: number[]): BenchmarkStatsSummary;
+    /** Compare a prior baseline median against the current median. `percent` is `NaN` when the baseline is 0. */
+    static delta(baselineMedian: number, currentMedian: number): BenchmarkDelta;
+    /** Format a fractional change as a signed percentage, e.g. `-0.38` → `"-38.0%"`; `NaN` → `"n/a"`. */
+    static formatPercent(percent: number): string;
+    /** A one-word read on a delta for a lower-is-better metric (time / samples), within a noise tolerance. */
+    static direction(delta: BenchmarkDelta, spread: number): 'improved' | 'regressed' | 'unchanged';
+}
+//# sourceMappingURL=benchmark_stats.d.ts.map

package/dist/benchmark/benchmark_stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark_stats.d.ts","sourceRoot":"","sources":["../../src/benchmark/benchmark_stats.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uGAAuG;AACvG,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,6HAA6H;AAC7H,MAAM,MAAM,cAAc,GAAG;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,0GAA0G;IAC1G,OAAO,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,qBAAa,cAAc;IAC1B,mGAAmG;IACnG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM;IAYvC,qFAAqF;IACrF,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,qBAAqB;IAkBzD,6GAA6G;IAC7G,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc;IAM3E,qGAAqG;IACrG,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAQ7C,0GAA0G;IAC1G,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW;CAM/F"}

package/dist/benchmark/benchmark_stats.js

@@ -0,0 +1,61 @@
+/**
+ * Pure statistics for the benchmark gate. Runtime measurement is noisy, so a
+ * single number lies: every benchmark reports the **median** of N runs plus the
+ * **spread**, and a baseline→after comparison is an advisory delta, never a
+ * deterministic guarantee. These helpers are deliberately side-effect-free so
+ * the variance handling is unit-tested directly, apart from any profiling.
+ */
+export class BenchmarkStats {
+    /** The median of a non-empty sample set (mean of the two middle values when the count is even). */
+    static median(values) {
+        if (values.length === 0) {
+            throw new Error('median of an empty sample set');
+        }
+        const sorted = [...values].sort((a, b) => a - b);
+        const mid = Math.floor(sorted.length / 2);
+        if (sorted.length % 2 === 1) {
+            return sorted[mid];
+        }
+        return (sorted[mid - 1] + sorted[mid]) / 2;
+    }
+    /** Reduce per-run samples to the median + spread summary. Throws on an empty set. */
+    static summarize(values) {
+        if (values.length === 0) {
+            throw new Error('cannot summarize a benchmark with no runs');
+        }
+        const min = Math.min(...values);
+        const max = Math.max(...values);
+        const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+        return {
+            runs: values.length,
+            median: BenchmarkStats.median(values),
+            min,
+            max,
+            mean,
+            spread: max - min,
+            values: [...values],
+        };
+    }
+    /** Compare a prior baseline median against the current median. `percent` is `NaN` when the baseline is 0. */
+    static delta(baselineMedian, currentMedian) {
+        const absolute = currentMedian - baselineMedian;
+        const percent = baselineMedian === 0 ? Number.NaN : absolute / baselineMedian;
+        return { baselineMedian, currentMedian, absolute, percent };
+    }
+    /** Format a fractional change as a signed percentage, e.g. `-0.38` → `"-38.0%"`; `NaN` → `"n/a"`. */
+    static formatPercent(percent) {
+        if (Number.isNaN(percent) === true) {
+            return 'n/a';
+        }
+        const sign = percent > 0 ? '+' : '';
+        return `${sign}${(percent * 100).toFixed(1)}%`;
+    }
+    /** A one-word read on a delta for a lower-is-better metric (time / samples), within a noise tolerance. */
+    static direction(delta, spread) {
+        if (Math.abs(delta.absolute) <= spread) {
+            return 'unchanged';
+        }
+        return delta.absolute < 0 ? 'improved' : 'regressed';
+    }
+}
+//# sourceMappingURL=benchmark_stats.js.map

package/dist/benchmark/benchmark_stats.js.map

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

package/dist/benchmark/node_benchmark.d.ts

@@ -0,0 +1,78 @@
+import { GraphQuery } from '../query/graph_query.js';
+import { KuzuStore } from '../store/kuzu_store.js';
+import { BenchmarkDelta, BenchmarkStatsSummary } from './benchmark_stats.js';
+/**
+ * The benchmark gate: measure one target node's runtime metric over a repeatable
+ * workload, **before and after** an edit, and report the delta. It reuses the
+ * existing machinery end to end — a V8 CPU profile feeds {@link RuntimeEnricher}
+ * (the same `enrich` path) and the metric is read back through
+ * {@link GraphQuery.costAttribution} (the `cost` query).
+ *
+ * Honesty about noise is baked in: a benchmark runs the workload N times and
+ * reports the **median + spread**, and a baseline comparison is labelled
+ * **advisory** — distinct from the hard pass/fail of the `verify` gate. The
+ * profiling step is injected ({@link ProfileRun}) so the read + statistics logic
+ * is unit-tested without actually profiling.
+ */
+/** Which runtime metric to track. `self-time` is the node's own exclusive time; `inclusive-time` adds its callees. */
+export type BenchmarkMetric = 'self-time' | 'inclusive-time' | 'samples';
+export type BenchmarkTarget = {
+    id: string;
+    name: string;
+    kind: string;
+    filePath: string;
+    startLine: number;
+};
+export type BenchmarkReport = {
+    target: BenchmarkTarget;
+    metric: BenchmarkMetric;
+    unit: 'ms' | 'samples';
+    stats: BenchmarkStatsSummary;
+    /** Present only when a prior baseline median was supplied; always advisory. */
+    delta: BenchmarkDelta | null;
+    /** A human note stating the result is advisory and noisy, not a guarantee. */
+    advisory: string;
+};
+export type NodeBenchmarkOptions = {
+    /** Symbol name (or substring / kind) resolved against the current graph to pick the target node. */
+    target: string;
+    /** Default `self-time`. */
+    metric?: BenchmarkMetric;
+    /** Number of profiling runs. Default 5, clamped to [1, 50]. */
+    runs?: number;
+    /** A prior baseline median to compare the current median against (advisory delta). */
+    baselineMedian?: number;
+};
+/** Everything one real profiling run needs: the workload entry, the project root, and a scratch dir for `.cpuprofile`s. */
+export type ProfileConfig = {
+    /** Path to a repeatable workload entry (a `.ts`/`.js` file) that exercises the target under load. */
+    workload: string;
+    /** Project root the profile's absolute frame paths resolve against (passed to `enrich`). */
+    root: string;
+    /** Scratch directory for the per-run `.cpuprofile`. */
+    profileDir: string;
+};
+/** One profiling run: leave a fresh `metadata.runtime` on the graph in the store. Injectable so tests skip profiling. */
+export type ProfileRun = (run: number) => Promise<void>;
+export declare class NodeBenchmark {
+    /**
+     * Profile the workload `runs` times, reading the target's metric after each,
+     * and return the median + spread (plus an advisory delta when a baseline is
+     * given). `profileRun` defaults to a real V8 profile + enrich; tests inject a
+     * fake that writes a known metric so this method's read/stats logic is covered
+     * without profiling.
+     */
+    static measure(store: KuzuStore, options: NodeBenchmarkOptions, profileRun: ProfileRun): Promise<BenchmarkReport>;
+    /** Resolve a target name to exactly one node in the current graph, or throw with guidance. */
+    static resolveTarget(query: GraphQuery, target: string): Promise<BenchmarkTarget>;
+    /** Read the target's current metric via the cost model (the `cost` query). */
+    static readMetric(query: GraphQuery, id: string, metric: BenchmarkMetric): Promise<number>;
+    /** A real profiling run: V8-profile the workload, then enrich the graph with the measured self time. */
+    static profileAndEnrich(store: KuzuStore, config: ProfileConfig): Promise<void>;
+    private static clampRuns;
+    private static buildAdvisory;
+    private static round;
+    private static runWorkload;
+    private static newestProfile;
+}
+//# sourceMappingURL=node_benchmark.d.ts.map

package/dist/benchmark/node_benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node_benchmark.d.ts","sourceRoot":"","sources":["../../src/benchmark/node_benchmark.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAkB,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7F;;;;;;;;;;;;GAYG;AAEH,sHAAsH;AACtH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAEzE,MAAM,MAAM,eAAe,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC7B,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,eAAe,CAAC;IACxB,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC;IACvB,KAAK,EAAE,qBAAqB,CAAC;IAC7B,+EAA+E;IAC/E,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAClC,oGAAoG;IACpG,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,2HAA2H;AAC3H,MAAM,MAAM,aAAa,GAAG;IAC3B,qGAAqG;IACrG,QAAQ,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,yHAAyH;AACzH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAMxD,qBAAa,aAAa;IACzB;;;;;;OAMG;WACU,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC;IAoBvH,8FAA8F;WACjF,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAcvF,8EAA8E;WACjE,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAShG,wGAAwG;WAC3F,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrF,OAAO,CAAC,MAAM,CAAC,SAAS;IAOxB,OAAO,CAAC,MAAM,CAAC,aAAa;IAS5B,OAAO,CAAC,MAAM,CAAC,KAAK;IAIpB,OAAO,CAAC,MAAM,CAAC,WAAW;mBAmBL,aAAa;CAclC"}

package/dist/benchmark/node_benchmark.js

@@ -0,0 +1,112 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readdir, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { RuntimeEnricher } from '../enrich/runtime_enricher.js';
+import { GraphQuery } from '../query/graph_query.js';
+import { BenchmarkStats } from './benchmark_stats.js';
+const DEFAULT_RUNS = 5;
+const MIN_RUNS = 1;
+const MAX_RUNS = 50;
+export class NodeBenchmark {
+    /**
+     * Profile the workload `runs` times, reading the target's metric after each,
+     * and return the median + spread (plus an advisory delta when a baseline is
+     * given). `profileRun` defaults to a real V8 profile + enrich; tests inject a
+     * fake that writes a known metric so this method's read/stats logic is covered
+     * without profiling.
+     */
+    static async measure(store, options, profileRun) {
+        const query = new GraphQuery(store);
+        const target = await NodeBenchmark.resolveTarget(query, options.target);
+        const metric = options.metric ?? 'self-time';
+        const runs = NodeBenchmark.clampRuns(options.runs ?? DEFAULT_RUNS);
+        const values = [];
+        for (let run = 0; run < runs; run += 1) {
+            await profileRun(run);
+            values.push(await NodeBenchmark.readMetric(query, target.id, metric));
+        }
+        const stats = BenchmarkStats.summarize(values);
+        const delta = options.baselineMedian === undefined
+            ? null
+            : BenchmarkStats.delta(options.baselineMedian, stats.median);
+        const unit = metric === 'samples' ? 'samples' : 'ms';
+        return { target, metric, unit, stats, delta, advisory: NodeBenchmark.buildAdvisory(stats, unit) };
+    }
+    /** Resolve a target name to exactly one node in the current graph, or throw with guidance. */
+    static async resolveTarget(query, target) {
+        const matches = await query.find(target);
+        if (matches.length === 0) {
+            throw new Error(`no node matches "${target}" — resolve a symbol name with \`find\` first`);
+        }
+        const exact = matches.filter((match) => match.name === target);
+        const chosen = exact.length === 1 ? exact[0] : matches.length === 1 ? matches[0] : null;
+        if (chosen === null) {
+            const candidates = (exact.length > 0 ? exact : matches).slice(0, 8).map((match) => match.id).join(', ');
+            throw new Error(`"${target}" is ambiguous — narrow it to one of: ${candidates}`);
+        }
+        return { id: chosen.id, name: chosen.name, kind: chosen.kind, filePath: chosen.filePath, startLine: chosen.startLine };
+    }
+    /** Read the target's current metric via the cost model (the `cost` query). */
+    static async readMetric(query, id, metric) {
+        const by = metric === 'samples' ? 'samples' : 'self-time';
+        const attribution = await query.costAttribution(id, { by });
+        if (attribution.node === null) {
+            throw new Error(`target node ${id} is no longer in the graph — rebuild after the edit`);
+        }
+        return metric === 'inclusive-time' ? attribution.node.inclusiveCost : attribution.node.selfCost;
+    }
+    /** A real profiling run: V8-profile the workload, then enrich the graph with the measured self time. */
+    static async profileAndEnrich(store, config) {
+        await rm(config.profileDir, { recursive: true, force: true });
+        await mkdir(config.profileDir, { recursive: true });
+        const profilePath = await NodeBenchmark.runWorkload(config);
+        const profileText = await readFile(profilePath, 'utf8');
+        await RuntimeEnricher.enrich(store, profileText, { root: config.root });
+    }
+    static clampRuns(runs) {
+        if (Number.isFinite(runs) === false) {
+            return DEFAULT_RUNS;
+        }
+        return Math.min(MAX_RUNS, Math.max(MIN_RUNS, Math.floor(runs)));
+    }
+    static buildAdvisory(stats, unit) {
+        const spread = `${NodeBenchmark.round(stats.spread)} ${unit}`;
+        return (`Advisory — runtime measurement is noisy. This is the median of ${stats.runs} run(s) ` +
+            `(spread ${spread}), not a deterministic guarantee. Unlike the verify gate (hard pass/fail), ` +
+            `a benchmark delta is indicative, not proof.`);
+    }
+    static round(value) {
+        return Math.round(value * 1000) / 1000;
+    }
+    static runWorkload(config) {
+        return new Promise((resolvePromise, reject) => {
+            const args = ['--cpu-prof', '--cpu-prof-dir', config.profileDir, '--import', 'tsx', config.workload];
+            const child = spawn('node', args, { cwd: config.root, stdio: ['ignore', 'ignore', 'pipe'] });
+            let stderr = '';
+            child.stderr.on('data', (chunk) => {
+                stderr += chunk.toString();
+            });
+            child.on('error', reject);
+            child.on('close', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`workload "${config.workload}" exited with code ${code}\n${stderr.trim()}`));
+                    return;
+                }
+                NodeBenchmark.newestProfile(config.profileDir).then(resolvePromise, reject);
+            });
+        });
+    }
+    static async newestProfile(profileDir) {
+        const entries = (await readdir(profileDir)).filter((name) => name.endsWith('.cpuprofile'));
+        if (entries.length === 0) {
+            throw new Error(`no .cpuprofile written to ${profileDir} — did the workload run under --cpu-prof?`);
+        }
+        const withMtime = await Promise.all(entries.map(async (name) => {
+            const path = join(profileDir, name);
+            return { path, mtimeMs: (await stat(path)).mtimeMs };
+        }));
+        withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
+        return withMtime[0].path;
+    }
+}
+//# sourceMappingURL=node_benchmark.js.map

package/dist/benchmark/node_benchmark.js.map

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

package/dist/cli.d.ts

@@ -1,14 +1,5 @@
 #!/usr/bin/env node
 export declare class Cli {
     static run(argv: string[]): void;
-    private static registerQuery;
-    private static extract;
-    private static load;
-    private static optimize;
-    private static withQuery;
-    private static printRefs;
-    private static printNeighbors;
-    private static printBreakdown;
-    private static countBy;
 }
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAmCA,qBAAa,GAAG;IACf,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAoFhC,OAAO,CAAC,MAAM,CAAC,aAAa;mBAoBP,OAAO;mBAkBP,IAAI;mBAWJ,QAAQ;mBAuCR,SAAS;IAU9B,OAAO,CAAC,MAAM,CAAC,SAAS;IAexB,OAAO,CAAC,MAAM,CAAC,cAAc;IAgB7B,OAAO,CAAC,MAAM,CAAC,cAAc;IAW7B,OAAO,CAAC,MAAM,CAAC,OAAO;CAOtB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAmBA,qBAAa,GAAG;IACf,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;CAyBhC"}