ts-knowledge-graph 0.1.2 → 0.1.6

package/contribs/webview/web/js_autogenerated/.gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!kind_descriptions.js

package/contribs/webview/web/js_autogenerated/kind_descriptions.js

@@ -0,0 +1,39 @@
+// @ts-nocheck
+// Generated from src/schema by scripts/build-data.ts. Do not edit by hand.
+window.KIND_DESCRIPTIONS = {
+	"nodes": {
+		"Module": "A source file in the codebase.",
+		"Class": "A class declaration.",
+		"Interface": "An interface declaration.",
+		"TypeAlias": "A type alias declaration.",
+		"Enum": "An enum declaration.",
+		"Function": "A standalone, module-level function.",
+		"Method": "A function that belongs to a class or interface.",
+		"Property": "A field declared on a class or interface.",
+		"Parameter": "A parameter of a function or method.",
+		"Variable": "A module- or block-level variable binding.",
+		"ExternalModule": "An imported third-party or Node.js module, recorded as one opaque node per import specifier.",
+		"ConfigFlag": "An environment-variable configuration flag, detected from process.env reads.",
+		"ExternalAPI": "An outbound HTTP host called through fetch(), with one node per host.",
+		"Endpoint": "An HTTP route registered by the app, such as app.get(\"/users\", handler)."
+	},
+	"edges": {
+		"CONTAINS": "Structural nesting: the source declares or encloses the target (a module contains a class, which contains a method).",
+		"IMPORTS": "The source module imports the target.",
+		"EXPORTS": "The source module exports the target symbol.",
+		"EXTENDS": "The source class or interface extends the target (inheritance).",
+		"IMPLEMENTS": "The source class implements the target interface.",
+		"USES_TYPE": "The source references the target in a type position.",
+		"RETURNS": "The target type appears in the source function or method return type.",
+		"PARAM_TYPE": "The target type appears in one of the source parameter types.",
+		"CALLS": "The source function or method calls the target.",
+		"INSTANTIATES": "The source constructs the target class with new.",
+		"OVERRIDES": "The source method overrides the base-class member it replaces.",
+		"READS": "The source reads the value of the target variable or property.",
+		"WRITES": "The source assigns to the target variable or property.",
+		"READS_CONFIG": "The source reads the target configuration flag (an environment variable).",
+		"CALLS_EXTERNAL": "The source makes an outbound HTTP call to the target external API.",
+		"HANDLES": "Links an HTTP endpoint to the function that handles it (route to handler).",
+		"CALLS_RUNTIME": "A call observed at runtime in a CPU profile: the source function or method was on the stack directly above the target. Captures dynamic dispatch that static CALLS cannot see."
+	}
+};

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

@@ -0,0 +1,154 @@
+/**
+ * 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; community?: number | null; communityLabel?: string | 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/webview_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>;
+	hiddenCommunities: Set<number>;
+	hideIsolated: boolean;
+	onlyMeasured: boolean;
+	droppedFiles: { nodes: RawNode[] | undefined; edges: RawEdge[] | undefined };
+	encoding: 'structural' | 'runtime' | 'community';
+	runtime: { maxSelfMs: number; measuredCount: number; totalSelfMs: number };
+	communities: [number, number][];
+	communityLabels: Map<number, string>;
+}
+
+/* ---------- 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;
+declare namespace cytoscape {
+	/** Registers a Cytoscape extension (such as the fcose layout) loaded as a CDN global. */
+	function use(extension: unknown): void;
+}
+
+/* ---------- globals injected into the page ---------- */
+
+interface Window {
+	GRAPH_DATA?: GraphData;
+	KIND_DESCRIPTIONS?: KindDescriptions;
+	GRAPH_SOURCE?: GraphSource | null;
+	cytoscapeFcose?: unknown;
+}

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.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAeA,qBAAa,GAAG;IACf,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;CAqBhC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAqBA,qBAAa,GAAG;IACf,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;CA2BhC"}

package/dist/cli.js

@@ -1,16 +1,22 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { BenchmarkCommand } from './commands/benchmark_command.js';
 import { BlastRadiusCommand } from './commands/blast_radius_command.js';
 import { CallsCommand } from './commands/calls_command.js';
+import { ClusterCommand } from './commands/cluster_command.js';
+import { CostCommand } from './commands/cost_command.js';
 import { DeadExportsCommand } from './commands/dead_exports_command.js';
+import { EnrichCommand } from './commands/enrich_command.js';
 import { ExtractCommand } from './commands/extract_command.js';
 import { FindCommand } from './commands/find_command.js';
+import { HotspotsCommand } from './commands/hotspots_command.js';
 import { InstallCommand } from './commands/install_command.js';
 import { LoadCommand } from './commands/load_command.js';
 import { NeighborsCommand } from './commands/neighbors_command.js';
-import { OptimizeCommand } from './commands/optimize_command.js';
 import { ReferencesCommand } from './commands/references_command.js';
-import { WebCommand } from './commands/web_command.js';
+import { ReportCommand } from './commands/report_command.js';
+import { VerifyCommand } from './commands/verify_command.js';
+import { WebviewCommand } from './commands/webview_command.js';
 import { WhoCallsCommand } from './commands/who_calls_command.js';
 export class Cli {
     static run(argv) {
@@ -20,15 +26,21 @@ export class Cli {
             .description('Parse a TypeScript project into a knowledge graph and query it');
         ExtractCommand.register(program);
         LoadCommand.register(program);
+        EnrichCommand.register(program);
+        ClusterCommand.register(program);
         FindCommand.register(program);
         WhoCallsCommand.register(program);
         CallsCommand.register(program);
         DeadExportsCommand.register(program);
+        HotspotsCommand.register(program);
+        CostCommand.register(program);
+        VerifyCommand.register(program);
+        BenchmarkCommand.register(program);
         BlastRadiusCommand.register(program);
         NeighborsCommand.register(program);
         ReferencesCommand.register(program);
-        OptimizeCommand.register(program);
-        WebCommand.register(program);
+        ReportCommand.register(program);
+        WebviewCommand.register(program);
         InstallCommand.register(program);
         void program.parseAsync(argv);
     }

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,MAAM,OAAO,GAAG;IACf,MAAM,CAAC,GAAG,CAAC,IAAc;QACxB,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;QAC9B,OAAO;aACL,IAAI,CAAC,oBAAoB,CAAC;aAC1B,WAAW,CAAC,gEAAgE,CAAC,CAAC;QAEhF,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACjC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9B,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9B,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAClC,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC/B,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACrC,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACrC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACnC,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACpC,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAClC,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC7B,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAEjC,KAAK,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACD;AAED,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,MAAM,OAAO,GAAG;IACf,MAAM,CAAC,GAAG,CAAC,IAAc;QACxB,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;QAC9B,OAAO;aACL,IAAI,CAAC,oBAAoB,CAAC;aAC1B,WAAW,CAAC,gEAAgE,CAAC,CAAC;QAEhF,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACjC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9B,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAChC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACjC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9B,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAClC,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC/B,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACrC,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAClC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9B,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAChC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACnC,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACrC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACnC,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACpC,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAChC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACjC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAEjC,KAAK,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACD;AAED,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/cluster/cluster_weights.d.ts

@@ -0,0 +1,20 @@
+import { EdgeKind } from '../schema/edge.js';
+/**
+ * How strongly each edge kind pulls its two endpoints into the same community.
+ * The effective weight of an edge is this coefficient times the edge's
+ * `metadata.count` (how many times the relationship occurs in source). The
+ * exception is `CALLS_RUNTIME` — the runtime call graph from `enrich` — weighted
+ * by its normalized sample count instead, and given a slightly higher coefficient
+ * because an executed call is stronger evidence of coupling than a merely
+ * statically-possible one. It contributes only on an enriched graph; otherwise no
+ * such edges exist and it is a no-op.
+ *
+ * `IMPORTS` and `EXPORTS` are deliberately absent: they are module wiring, not
+ * coupling, the same reasoning {@link REFERENCE_EDGE_KINDS} uses. `CONTAINS`
+ * carries a low weight so same-file symbols lean together without overwhelming
+ * call structure; drop it for modules that may cross files freely. System-level
+ * kinds (`READS_CONFIG`, `CALLS_EXTERNAL`, `HANDLES`) are absent because their
+ * targets are synthesized nodes, not code symbols.
+ */
+export declare const CLUSTER_EDGE_WEIGHTS: Partial<Record<EdgeKind, number>>;
+//# sourceMappingURL=cluster_weights.d.ts.map

package/dist/cluster/cluster_weights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster_weights.d.ts","sourceRoot":"","sources":["../../src/cluster/cluster_weights.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAalE,CAAC"}

package/dist/cluster/cluster_weights.js

@@ -0,0 +1,32 @@
+/**
+ * How strongly each edge kind pulls its two endpoints into the same community.
+ * The effective weight of an edge is this coefficient times the edge's
+ * `metadata.count` (how many times the relationship occurs in source). The
+ * exception is `CALLS_RUNTIME` — the runtime call graph from `enrich` — weighted
+ * by its normalized sample count instead, and given a slightly higher coefficient
+ * because an executed call is stronger evidence of coupling than a merely
+ * statically-possible one. It contributes only on an enriched graph; otherwise no
+ * such edges exist and it is a no-op.
+ *
+ * `IMPORTS` and `EXPORTS` are deliberately absent: they are module wiring, not
+ * coupling, the same reasoning {@link REFERENCE_EDGE_KINDS} uses. `CONTAINS`
+ * carries a low weight so same-file symbols lean together without overwhelming
+ * call structure; drop it for modules that may cross files freely. System-level
+ * kinds (`READS_CONFIG`, `CALLS_EXTERNAL`, `HANDLES`) are absent because their
+ * targets are synthesized nodes, not code symbols.
+ */
+export const CLUSTER_EDGE_WEIGHTS = {
+    CALLS: 3,
+    CALLS_RUNTIME: 4,
+    INSTANTIATES: 2,
+    EXTENDS: 2,
+    IMPLEMENTS: 2,
+    OVERRIDES: 1.5,
+    WRITES: 1.5,
+    READS: 1,
+    USES_TYPE: 1,
+    RETURNS: 1,
+    PARAM_TYPE: 1,
+    CONTAINS: 0.5,
+};
+//# sourceMappingURL=cluster_weights.js.map