ts-knowledge-graph 0.1.2 → 0.1.4

package/dist/commands/benchmark_command.js

@@ -0,0 +1,91 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import chalk from 'chalk';
+import { z } from 'zod';
+import { BenchmarkStats } from '../benchmark/benchmark_stats.js';
+import { NodeBenchmark } from '../benchmark/node_benchmark.js';
+import { KuzuStore } from '../store/kuzu_store.js';
+import { DEFAULT_DB_PATH } from './command_helpers.js';
+const METRICS = ['self-time', 'inclusive-time', 'samples'];
+/** A saved baseline is just a prior report; we only need its median back. */
+const BaselineFileSchema = z.object({ stats: z.object({ median: z.number() }) });
+export class BenchmarkCommand {
+    static register(program) {
+        program
+            .command('benchmark')
+            .description('measure a target node\'s runtime metric over N profiling runs and report the median + spread (advisory)')
+            .argument('<target>', 'symbol name to benchmark; resolved against the current graph like `find`')
+            .requiredOption('--workload <path>', 'repeatable workload entry (.ts/.js) that exercises the target under load')
+            .option('-d, --db <path>', 'Kùzu database path', DEFAULT_DB_PATH)
+            .option('-r, --root <path>', 'project root the profile paths resolve against', process.cwd())
+            .option('--by <metric>', `metric: ${METRICS.join(', ')}`, 'self-time')
+            .option('--runs <n>', 'number of profiling runs to take the median of', '5')
+            .option('--baseline <file>', 'compare against the median saved in this baseline file (advisory delta)')
+            .option('--save-baseline <file>', 'write this run as a baseline for a later --baseline comparison')
+            .option('--json', 'emit the benchmark report as JSON', false)
+            .action(async (target, options) => {
+            if (METRICS.includes(options.by) === false) {
+                console.error(chalk.red(`unknown metric '${options.by}' — choose one of: ${METRICS.join(', ')}`));
+                process.exitCode = 1;
+                return;
+            }
+            await BenchmarkCommand.run(target, options);
+        });
+    }
+    static async run(target, options) {
+        const store = new KuzuStore(resolve(options.db));
+        await store.initSchema();
+        const profileDir = await mkdtemp(join(tmpdir(), 'tkg-bench-'));
+        try {
+            const baselineMedian = options.baseline === undefined ? undefined : await BenchmarkCommand.readBaselineMedian(options.baseline);
+            const config = { workload: resolve(options.workload), root: resolve(options.root), profileDir };
+            const report = await NodeBenchmark.measure(store, { target, metric: options.by, runs: Number(options.runs), baselineMedian }, () => NodeBenchmark.profileAndEnrich(store, config));
+            if (options.saveBaseline !== undefined) {
+                await BenchmarkCommand.writeBaseline(options.saveBaseline, report);
+            }
+            BenchmarkCommand.print(report, options.json === true);
+        }
+        finally {
+            await store.close();
+            await rm(profileDir, { recursive: true, force: true });
+        }
+    }
+    static async readBaselineMedian(file) {
+        const parsed = BaselineFileSchema.parse(JSON.parse(await readFile(resolve(file), 'utf8')));
+        return parsed.stats.median;
+    }
+    static async writeBaseline(file, report) {
+        const path = resolve(file);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, JSON.stringify(report, null, 2), 'utf8');
+    }
+    static print(report, json) {
+        if (json === true) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        const target = report.target;
+        console.log(chalk.bold(target.name) + chalk.gray(`  ${target.kind} · ${target.filePath}:${target.startLine}`));
+        const stats = report.stats;
+        const median = chalk.cyan(`${BenchmarkCommand.round(stats.median)} ${report.unit}`);
+        const spread = chalk.gray(`(min ${BenchmarkCommand.round(stats.min)} · max ${BenchmarkCommand.round(stats.max)} · ` +
+            `spread ${BenchmarkCommand.round(stats.spread)} · mean ${BenchmarkCommand.round(stats.mean)} · ${stats.runs} runs)`);
+        console.log(`  ${chalk.bold(report.metric)}  median ${median}   ${spread}`);
+        if (report.delta !== null) {
+            BenchmarkCommand.printDelta(report, report.delta);
+        }
+        console.log(chalk.yellow(`  ${report.advisory}`));
+    }
+    static printDelta(report, delta) {
+        const direction = BenchmarkStats.direction(delta, report.stats.spread);
+        const colour = direction === 'improved' ? chalk.green : direction === 'regressed' ? chalk.red : chalk.gray;
+        const absolute = `${delta.absolute > 0 ? '+' : ''}${BenchmarkCommand.round(delta.absolute)} ${report.unit}`;
+        const percent = BenchmarkStats.formatPercent(delta.percent);
+        console.log(`  ${chalk.bold('Δ vs baseline')}  ${colour(`${absolute}  (${percent})`)}  ${colour(direction)}`);
+    }
+    static round(value) {
+        return Math.round(value * 1000) / 1000;
+    }
+}
+//# sourceMappingURL=benchmark_command.js.map

package/dist/commands/benchmark_command.js.map

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

package/dist/commands/blast_radius_command.js

@@ -6,7 +6,7 @@ export class BlastRadiusCommand {
             .description('list every symbol transitively impacted by changing <id>')
             .argument('<id>', 'node id to analyse')
             .option('-d, --db <path>', 'Kùzu database path', DEFAULT_DB_PATH)
-            .option('--depth <n>', 'maximum traversal depth', '10')
+            .option('--depth <n>', 'maximum traversal depth (clamped to 1–30)', '10')
             .option('--json', 'emit raw JSON', false)
             .action(async (id, options) => {
             await CommandHelpers.withQuery(options.db, async (query) => {

package/dist/commands/blast_radius_command.js.map

@@ -1 +1 @@
-{"version":3,"file":"blast_radius_command.js","sourceRoot":"","sources":["../../src/commands/blast_radius_command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAgB,MAAM,sBAAsB,CAAC;AAMrF,MAAM,OAAO,kBAAkB;IAC9B,MAAM,CAAC,QAAQ,CAAC,OAAgB;QAC/B,OAAO;aACL,OAAO,CAAC,cAAc,CAAC;aACvB,WAAW,CAAC,0DAA0D,CAAC;aACvE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;aACtC,MAAM,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,CAAC;aAChE,MAAM,CAAC,aAAa,EAAE,yBAAyB,EAAE,IAAI,CAAC;aACtD,MAAM,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,CAAC;aACxC,MAAM,CAAC,KAAK,EAAE,EAAU,EAAE,OAAqB,EAAE,EAAE;YACnD,MAAM,cAAc,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;gBAC1D,cAAc,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;YACrG,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACD"}
+{"version":3,"file":"blast_radius_command.js","sourceRoot":"","sources":["../../src/commands/blast_radius_command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAgB,MAAM,sBAAsB,CAAC;AAMrF,MAAM,OAAO,kBAAkB;IAC9B,MAAM,CAAC,QAAQ,CAAC,OAAgB;QAC/B,OAAO;aACL,OAAO,CAAC,cAAc,CAAC;aACvB,WAAW,CAAC,0DAA0D,CAAC;aACvE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;aACtC,MAAM,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,CAAC;aAChE,MAAM,CAAC,aAAa,EAAE,2CAA2C,EAAE,IAAI,CAAC;aACxE,MAAM,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,CAAC;aACxC,MAAM,CAAC,KAAK,EAAE,EAAU,EAAE,OAAqB,EAAE,EAAE;YACnD,MAAM,cAAc,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;gBAC1D,cAAc,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;YACrG,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACD"}

package/dist/commands/cost_command.d.ts

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+export declare class CostCommand {
+    static register(program: Command): void;
+    private static printRanking;
+    private static printAttribution;
+    private static printFlows;
+    private static formatAmount;
+    private static formatShare;
+    private static formatCoverage;
+    /** A one-line gloss under the ranking: what coverage means, or how to record it when missing. */
+    private static printCoverageHint;
+}
+//# sourceMappingURL=cost_command.d.ts.map

package/dist/commands/cost_command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost_command.d.ts","sourceRoot":"","sources":["../../src/commands/cost_command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,qBAAa,WAAW;IACvB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IA4BvC,OAAO,CAAC,MAAM,CAAC,YAAY;IA2B3B,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAgC/B,OAAO,CAAC,MAAM,CAAC,UAAU;IAazB,OAAO,CAAC,MAAM,CAAC,YAAY;IAK3B,OAAO,CAAC,MAAM,CAAC,WAAW;IAI1B,OAAO,CAAC,MAAM,CAAC,cAAc;IAI7B,iGAAiG;IACjG,OAAO,CAAC,MAAM,CAAC,iBAAiB;CAUhC"}

package/dist/commands/cost_command.js

@@ -0,0 +1,122 @@
+import chalk from 'chalk';
+import { CommandHelpers, DEFAULT_DB_PATH } from './command_helpers.js';
+const METRICS = ['self-time', 'samples'];
+const NO_RUNTIME_NOTICE = '! no runtime data in graph — run `enrich` first. Inclusive cost needs measured self cost to propagate.';
+export class CostCommand {
+    static register(program) {
+        program
+            .command('cost')
+            .description('propagate runtime self cost into inclusive cost and rank nodes by share of total')
+            .argument('[id]', 'node id to break down causally; omit to rank the whole graph')
+            .option('-d, --db <path>', 'Kùzu database path', DEFAULT_DB_PATH)
+            .option('--by <metric>', `cost metric: ${METRICS.join(', ')}`, 'self-time')
+            .option('--limit <n>', 'maximum number of ranked nodes to return', '20')
+            .option('--json', 'emit raw JSON', false)
+            .action(async (id, options) => {
+            if (options.by !== undefined && METRICS.includes(options.by) === false) {
+                console.error(chalk.red(`unknown metric '${options.by}' — choose one of: ${METRICS.join(', ')}`));
+                process.exitCode = 1;
+                return;
+            }
+            const by = options.by;
+            await CommandHelpers.withQuery(options.db, async (query) => {
+                if (id === undefined) {
+                    const report = await query.costRanking({ by, limit: Number(options.limit) });
+                    CostCommand.printRanking(report, options.json === true);
+                    return;
+                }
+                const attribution = await query.costAttribution(id, { by });
+                CostCommand.printAttribution(attribution, options.json === true);
+            });
+        });
+    }
+    static printRanking(report, json) {
+        if (json === true) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        if (report.enriched === false) {
+            console.log(chalk.yellow(NO_RUNTIME_NOTICE));
+            return;
+        }
+        const total = CostCommand.formatAmount(report.metric, report.totalSelf);
+        const coverage = CostCommand.formatCoverage(report.coverage);
+        console.log(chalk.bold(`Inclusive cost by ${report.metric}`) + chalk.gray(` (total self ${total} · coverage ${coverage})`));
+        if (report.nodes.length === 0) {
+            console.log(chalk.yellow('(no results)'));
+            return;
+        }
+        report.nodes.forEach((node, index) => {
+            const rank = chalk.gray(`${String(index + 1).padStart(2)}.`);
+            const inclusive = chalk.cyan(CostCommand.formatAmount(report.metric, node.inclusiveCost).padStart(14));
+            const share = chalk.green(CostCommand.formatShare(node.shareOfTotal).padStart(7));
+            const mark = node.cyclic === true ? chalk.magenta(' ↺') : '';
+            console.log(`${rank} ${inclusive} ${share}  ${chalk.gray(node.kind.padEnd(10))} ${chalk.bold(node.name)}${mark}  ${chalk.gray(`${node.filePath}:${node.startLine}`)}`);
+        });
+        console.log(chalk.gray(`\n${report.nodes.length} node(s) · share is of total self cost · ↺ = in a call cycle`));
+        CostCommand.printCoverageHint(report.coverage, report.metric);
+    }
+    static printAttribution(attribution, json) {
+        if (json === true) {
+            console.log(JSON.stringify(attribution, null, 2));
+            return;
+        }
+        if (attribution.node === null) {
+            console.log(chalk.yellow('(no such node — resolve an id with `find` first)'));
+            return;
+        }
+        if (attribution.enriched === false) {
+            console.log(chalk.yellow(NO_RUNTIME_NOTICE));
+            return;
+        }
+        const node = attribution.node;
+        const metric = attribution.metric;
+        console.log(chalk.bold(node.name) + chalk.gray(`  ${node.kind} · ${node.filePath}:${node.startLine}`));
+        console.log(`  self ${chalk.cyan(CostCommand.formatAmount(metric, node.selfCost))}`
+            + `  ·  inclusive ${chalk.cyan(CostCommand.formatAmount(metric, node.inclusiveCost))}`
+            + `  ·  share of total ${chalk.green(CostCommand.formatShare(node.shareOfTotal))}`);
+        const coverageLine = attribution.coverage === null
+            ? 'graph coverage: unknown — re-run `enrich` to record it'
+            : `graph coverage: ${CostCommand.formatCoverage(attribution.coverage)} of profiled ${metric} is attributed to nodes`;
+        console.log(chalk.gray(`  ${coverageLine}`));
+        if (node.cyclic === true) {
+            console.log(chalk.magenta(`  ↺ part of a ${node.cycleSize}-node call cycle — inclusive cost is the cycle total, shared by its members`));
+        }
+        CostCommand.printFlows('Cost flows into (callees)', attribution.callees, metric, '->');
+        CostCommand.printFlows('Attributed to callers', attribution.callers, metric, '<-');
+    }
+    static printFlows(title, flows, metric, arrow) {
+        console.log(chalk.bold(`\n${title}`));
+        if (flows.length === 0) {
+            console.log(chalk.gray('  (none)'));
+            return;
+        }
+        for (const flow of flows) {
+            const amount = chalk.cyan(CostCommand.formatAmount(metric, flow.amount).padStart(14));
+            const share = chalk.green(CostCommand.formatShare(flow.share).padStart(7));
+            console.log(`  ${chalk.gray(arrow)} ${amount} ${share}  ${chalk.bold(flow.name)}  ${chalk.gray(`${flow.filePath}:${flow.startLine}`)}`);
+        }
+    }
+    static formatAmount(metric, value) {
+        const rounded = Math.round(value * 1000) / 1000;
+        return metric === 'self-time' ? `${rounded} ms` : `${rounded} samples`;
+    }
+    static formatShare(share) {
+        return `${(share * 100).toFixed(1)}%`;
+    }
+    static formatCoverage(coverage) {
+        return coverage === null ? 'unknown' : `${(coverage * 100).toFixed(0)}%`;
+    }
+    /** A one-line gloss under the ranking: what coverage means, or how to record it when missing. */
+    static printCoverageHint(coverage, metric) {
+        if (coverage === null) {
+            console.log(chalk.gray('coverage unknown — re-run `enrich` to record what fraction of the profile lands on the graph'));
+            return;
+        }
+        const outsidePct = Math.round((1 - coverage) * 100);
+        if (outsidePct > 0) {
+            console.log(chalk.gray(`coverage = ${CostCommand.formatCoverage(coverage)} of profiled ${metric} attributed to the graph; ${outsidePct}% fell outside it (dropped by the join)`));
+        }
+    }
+}
+//# sourceMappingURL=cost_command.js.map

package/dist/commands/cost_command.js.map

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

package/dist/commands/{load.d.ts → enrich_command.d.ts}

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
-export declare class Load {
+export declare class EnrichCommand {
     static register(program: Command): void;
     private static run;
+    private static print;
 }
-//# sourceMappingURL=load.d.ts.map
+//# sourceMappingURL=enrich_command.d.ts.map

package/dist/commands/enrich_command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrich_command.d.ts","sourceRoot":"","sources":["../../src/commands/enrich_command.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,qBAAa,aAAa;IACzB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;mBAalB,GAAG;IAaxB,OAAO,CAAC,MAAM,CAAC,KAAK;CAqCpB"}

package/dist/commands/enrich_command.js

@@ -0,0 +1,62 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { RuntimeEnricher } from '../enrich/runtime_enricher.js';
+import { KuzuStore } from '../store/kuzu_store.js';
+import { DEFAULT_DB_PATH } from './command_helpers.js';
+export class EnrichCommand {
+    static register(program) {
+        program
+            .command('enrich')
+            .description('ingest a V8 CPU profile and attach runtime metrics onto graph nodes')
+            .argument('<profile>', 'path to a V8 .cpuprofile file (node --cpu-prof)')
+            .option('-d, --db <path>', 'Kùzu database path', DEFAULT_DB_PATH)
+            .option('-r, --root <path>', 'project root the profile paths resolve against', process.cwd())
+            .option('--json', 'emit the enrichment report as JSON', false)
+            .action(async (profile, options) => {
+            await EnrichCommand.run(profile, options);
+        });
+    }
+    static async run(profile, options) {
+        const profilePath = resolve(profile);
+        const profileText = await readFile(profilePath, 'utf8');
+        const store = new KuzuStore(resolve(options.db));
+        await store.initSchema();
+        try {
+            const report = await RuntimeEnricher.enrich(store, profileText, { root: resolve(options.root) });
+            EnrichCommand.print(report, options.json === true);
+        }
+        finally {
+            await store.close();
+        }
+    }
+    static print(report, json) {
+        if (json === true) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        const coverage = report.totalSamples > 0
+            ? Math.round((report.matchedSamples / report.totalSamples) * 100)
+            : 0;
+        console.log(chalk.green(`✓ enriched ${report.matchedNodes} node(s) with metadata.runtime`));
+        console.log(`  attributed ${chalk.bold(report.matchedSamples)} / ${report.totalSamples} samples (${coverage}%), ` +
+            `${chalk.bold(`${report.matchedSelfMs} ms`)} self time`);
+        console.log(`  joined ${chalk.bold(report.matchedFrames)} frame(s): ` +
+            `${report.matchedByName} by name, ${report.matchedByRange} by range`);
+        console.log(`  dropped ${chalk.bold(report.droppedFrames)} frame(s), ${report.droppedSamples} sample(s) — not in graph`);
+        if (report.hotspots.length > 0) {
+            console.log(chalk.bold('\nTop self time'));
+            for (const hotspot of report.hotspots.slice(0, 10)) {
+                console.log(`  ${chalk.gray(`${hotspot.selfMs} ms`.padStart(10))}  ${chalk.bold(hotspot.name)} ` +
+                    `${chalk.gray(`(${hotspot.samples} samples)`)}  ${chalk.gray(hotspot.filePath)}`);
+            }
+        }
+        if (report.dropped.length > 0) {
+            console.log(chalk.bold('\nTop unattributed'));
+            for (const group of report.dropped.slice(0, 5)) {
+                console.log(`  ${chalk.gray(`${group.samples} samples`.padStart(12))}  ${chalk.gray(group.label)}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=enrich_command.js.map

package/dist/commands/enrich_command.js.map

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

package/dist/commands/hotspots_command.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+export declare class HotspotsCommand {
+    static register(program: Command): void;
+    private static print;
+    private static formatScore;
+}
+//# sourceMappingURL=hotspots_command.d.ts.map

package/dist/commands/hotspots_command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hotspots_command.d.ts","sourceRoot":"","sources":["../../src/commands/hotspots_command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,qBAAa,eAAe;IAC3B,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IA0BvC,OAAO,CAAC,MAAM,CAAC,KAAK;IAsBpB,OAAO,CAAC,MAAM,CAAC,WAAW;CAe1B"}

package/dist/commands/hotspots_command.js

@@ -0,0 +1,67 @@
+import chalk from 'chalk';
+import { CommandHelpers, DEFAULT_DB_PATH } from './command_helpers.js';
+const METRICS = ['self-time', 'samples', 'callers', 'call-count', 'blast-radius'];
+export class HotspotsCommand {
+    static register(program) {
+        program
+            .command('hotspots')
+            .description('rank nodes by optimization leverage (runtime self-time, fan-in, call-count, or blast radius)')
+            .option('-d, --db <path>', 'Kùzu database path', DEFAULT_DB_PATH)
+            .option('--by <metric>', `ranking metric: ${METRICS.join(', ')} (default: self-time when enriched, else callers)`)
+            .option('--limit <n>', 'maximum number of hotspots to return', '20')
+            .option('--measured-only', 'restrict ranking to nodes that carry runtime metrics', false)
+            .option('--json', 'emit raw JSON', false)
+            .action(async (options) => {
+            if (options.by !== undefined && METRICS.includes(options.by) === false) {
+                console.error(chalk.red(`unknown metric '${options.by}' — choose one of: ${METRICS.join(', ')}`));
+                process.exitCode = 1;
+                return;
+            }
+            await CommandHelpers.withQuery(options.db, async (query) => {
+                const report = await query.hotspots({
+                    by: options.by,
+                    limit: Number(options.limit),
+                    measuredOnly: options.measuredOnly === true,
+                });
+                HotspotsCommand.print(report, options.json === true);
+            });
+        });
+    }
+    static print(report, json) {
+        if (json === true) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        if (report.fellBack === true) {
+            console.log(chalk.yellow('! no runtime data in graph — run `enrich` first. Ranking by `callers` (static fan-in) instead.'));
+        }
+        const scope = report.measuredOnly === true ? chalk.gray(' (measured nodes only)') : '';
+        console.log(chalk.bold(`Hotspots by ${report.metric}`) + scope);
+        if (report.hotspots.length === 0) {
+            console.log(chalk.yellow('(no results)'));
+            return;
+        }
+        report.hotspots.forEach((hotspot, index) => {
+            const rank = chalk.gray(`${String(index + 1).padStart(2)}.`);
+            const score = chalk.cyan(HotspotsCommand.formatScore(report.metric, hotspot.score).padStart(14));
+            console.log(`${rank} ${score}  ${chalk.gray(hotspot.kind.padEnd(10))} ${chalk.bold(hotspot.name)}  ${chalk.gray(`${hotspot.filePath}:${hotspot.startLine}`)}`);
+        });
+        console.log(chalk.gray(`\n${report.hotspots.length} hotspot(s)`));
+    }
+    static formatScore(metric, score) {
+        if (metric === 'self-time') {
+            return `${score} ms`;
+        }
+        if (metric === 'samples') {
+            return `${score} samples`;
+        }
+        if (metric === 'callers') {
+            return `${score} callers`;
+        }
+        if (metric === 'call-count') {
+            return `${score} calls`;
+        }
+        return `${score} impacted`;
+    }
+}
+//# sourceMappingURL=hotspots_command.js.map

package/dist/commands/hotspots_command.js.map

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

package/dist/commands/install_command.d.ts

@@ -7,9 +7,8 @@ export declare class InstallCommand {
     static register(program: Command): void;
     private static run;
     /**
-     * Resolves the bundled SKILL.md relative to this module. The `../../` prefix
-     * reaches the package root from both `src/commands` (run via tsx) and
-     * `dist/commands` (run from the built output).
+     * Resolves the bundled SKILL.md from the package root, which works whether
+     * running via tsx from `src` or from the built `dist` output.
      */
     private static sourceSkillPath;
 }

package/dist/commands/install_command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install_command.d.ts","sourceRoot":"","sources":["../../src/commands/install_command.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC;;;GAGG;AACH,qBAAa,cAAc;IAC1B,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;mBAWlB,GAAG;IAcxB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;CAI9B"}
+{"version":3,"file":"install_command.d.ts","sourceRoot":"","sources":["../../src/commands/install_command.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC;;;GAGG;AACH,qBAAa,cAAc;IAC1B,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;mBAWlB,GAAG;IAcxB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;CAG9B"}

package/dist/commands/install_command.js

@@ -1,8 +1,9 @@
 import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
-const SKILL_RELATIVE_PATH = 'skills/ts-knowledge-graph/SKILL.md';
+import { PROJECT_ROOT } from '../project_root.js';
+const SKILL_SOURCE_PATH = 'dotclaude_folder/skills/code-graph-query/SKILL.md';
+const SKILL_TARGET_PATH = 'skills/code-graph-query/SKILL.md';
 /**
  * Installs the bundled Claude Code skill into a target project so an agent can
  * query the knowledge graph through the ts-knowledge-graph CLI.
@@ -20,7 +21,7 @@ export class InstallCommand {
     }
     static async run(destFolder, options) {
         const source = InstallCommand.sourceSkillPath();
-        const target = resolve(destFolder, SKILL_RELATIVE_PATH);
+        const target = resolve(destFolder, SKILL_TARGET_PATH);
         if (existsSync(target) === true && options.force === false) {
             console.log(chalk.yellow(`✗ ${target} already exists — pass --force to overwrite`));
             return;
@@ -30,13 +31,11 @@ export class InstallCommand {
         console.log(chalk.green(`✓ installed skill -> ${target}`));
     }
     /**
-     * Resolves the bundled SKILL.md relative to this module. The `../../` prefix
-     * reaches the package root from both `src/commands` (run via tsx) and
-     * `dist/commands` (run from the built output).
+     * Resolves the bundled SKILL.md from the package root, which works whether
+     * running via tsx from `src` or from the built `dist` output.
      */
     static sourceSkillPath() {
-        const here = dirname(fileURLToPath(import.meta.url));
-        return resolve(here, '..', '..', SKILL_RELATIVE_PATH);
+        return resolve(PROJECT_ROOT, SKILL_SOURCE_PATH);
     }
 }
 //# sourceMappingURL=install_command.js.map

package/dist/commands/install_command.js.map

@@ -1 +1 @@
-{"version":3,"file":"install_command.js","sourceRoot":"","sources":["../../src/commands/install_command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,MAAM,mBAAmB,GAAG,oCAAoC,CAAC;AAMjE;;;GAGG;AACH,MAAM,OAAO,cAAc;IAC1B,MAAM,CAAC,QAAQ,CAAC,OAAgB;QAC/B,OAAO;aACL,OAAO,CAAC,SAAS,CAAC;aAClB,WAAW,CAAC,iEAAiE,CAAC;aAC9E,QAAQ,CAAC,cAAc,EAAE,wCAAwC,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;aACjF,MAAM,CAAC,SAAS,EAAE,gCAAgC,EAAE,KAAK,CAAC;aAC1D,MAAM,CAAC,KAAK,EAAE,UAAkB,EAAE,OAAuB,EAAE,EAAE;YAC7D,MAAM,cAAc,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,UAAkB,EAAE,OAAuB;QACnE,MAAM,MAAM,GAAG,cAAc,CAAC,eAAe,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,mBAAmB,CAAC,CAAC;QAExD,IAAI,UAAU,CAAC,MAAM,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;YAC5D,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,MAAM,6CAA6C,CAAC,CAAC,CAAC;YACpF,OAAO;QACR,CAAC;QAED,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED;;;;OAIG;IACK,MAAM,CAAC,eAAe;QAC7B,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACrD,OAAO,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,CAAC,CAAC;IACvD,CAAC;CACD"}
+{"version":3,"file":"install_command.js","sourceRoot":"","sources":["../../src/commands/install_command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,iBAAiB,GAAG,mDAAmD,CAAC;AAC9E,MAAM,iBAAiB,GAAG,kCAAkC,CAAC;AAM7D;;;GAGG;AACH,MAAM,OAAO,cAAc;IAC1B,MAAM,CAAC,QAAQ,CAAC,OAAgB;QAC/B,OAAO;aACL,OAAO,CAAC,SAAS,CAAC;aAClB,WAAW,CAAC,iEAAiE,CAAC;aAC9E,QAAQ,CAAC,cAAc,EAAE,wCAAwC,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;aACjF,MAAM,CAAC,SAAS,EAAE,gCAAgC,EAAE,KAAK,CAAC;aAC1D,MAAM,CAAC,KAAK,EAAE,UAAkB,EAAE,OAAuB,EAAE,EAAE;YAC7D,MAAM,cAAc,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,UAAkB,EAAE,OAAuB;QACnE,MAAM,MAAM,GAAG,cAAc,CAAC,eAAe,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;QAEtD,IAAI,UAAU,CAAC,MAAM,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;YAC5D,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,MAAM,6CAA6C,CAAC,CAAC,CAAC;YACpF,OAAO;QACR,CAAC;QAED,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED;;;OAGG;IACK,MAAM,CAAC,eAAe;QAC7B,OAAO,OAAO,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;IACjD,CAAC;CACD"}

package/dist/commands/load_command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load_command.d.ts","sourceRoot":"","sources":["../../src/commands/load_command.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,qBAAa,WAAW;IACvB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;mBAWlB,GAAG;CAUxB"}
+{"version":3,"file":"load_command.d.ts","sourceRoot":"","sources":["../../src/commands/load_command.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,qBAAa,WAAW;IACvB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;mBAWlB,GAAG;CAWxB"}

package/dist/commands/load_command.js

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 import chalk from 'chalk';
+import { RUNTIME_MANIFEST_KEY } from '../schema/runtime_manifest.js';
 import { JsonlReader } from '../store/jsonl_reader.js';
 import { KuzuStore } from '../store/kuzu_store.js';
 import { DEFAULT_DB_PATH, DEFAULT_GRAPH_DIR } from './command_helpers.js';
@@ -21,6 +22,7 @@ export class LoadCommand {
         const store = new KuzuStore(resolvedDb);
         await store.initSchema();
         await store.load(nodes, edges);
+        await store.clearGraphMeta(RUNTIME_MANIFEST_KEY);
         await store.close();
         console.log(chalk.green(`✓ loaded ${nodes.length} nodes, ${edges.length} edges`));
     }

package/dist/commands/load_command.js.map

@@ -1 +1 @@
-{"version":3,"file":"load_command.js","sourceRoot":"","sources":["../../src/commands/load_command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE1E,MAAM,OAAO,WAAW;IACvB,MAAM,CAAC,QAAQ,CAAC,OAAgB;QAC/B,OAAO;aACL,OAAO,CAAC,MAAM,CAAC;aACf,WAAW,CAAC,mDAAmD,CAAC;aAChE,QAAQ,CAAC,YAAY,EAAE,+CAA+C,EAAE,iBAAiB,CAAC;aAC1F,MAAM,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,CAAC;aAChE,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,OAAuB,EAAE,EAAE;YAC3D,MAAM,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,QAAgB,EAAE,MAAc;QACxD,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QACnC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,OAAO,CAAC,QAAQ,CAAC,SAAS,UAAU,MAAM,CAAC,CAAC,CAAC;QAC/E,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QACnE,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC;QACxC,MAAM,KAAK,CAAC,UAAU,EAAE,CAAC;QACzB,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC/B,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,KAAK,CAAC,MAAM,WAAW,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC;IACnF,CAAC;CACD"}
+{"version":3,"file":"load_command.js","sourceRoot":"","sources":["../../src/commands/load_command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE1E,MAAM,OAAO,WAAW;IACvB,MAAM,CAAC,QAAQ,CAAC,OAAgB;QAC/B,OAAO;aACL,OAAO,CAAC,MAAM,CAAC;aACf,WAAW,CAAC,mDAAmD,CAAC;aAChE,QAAQ,CAAC,YAAY,EAAE,+CAA+C,EAAE,iBAAiB,CAAC;aAC1F,MAAM,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,CAAC;aAChE,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,OAAuB,EAAE,EAAE;YAC3D,MAAM,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,QAAgB,EAAE,MAAc;QACxD,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QACnC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,OAAO,CAAC,QAAQ,CAAC,SAAS,UAAU,MAAM,CAAC,CAAC,CAAC;QAC/E,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QACnE,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC;QACxC,MAAM,KAAK,CAAC,UAAU,EAAE,CAAC;QACzB,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC/B,MAAM,KAAK,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC;QACjD,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,KAAK,CAAC,MAAM,WAAW,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC;IACnF,CAAC;CACD"}

package/dist/commands/verify_command.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+export declare class VerifyCommand {
+    static register(program: Command): void;
+    private static print;
+    private static printCheck;
+    private static printFailureOutput;
+}
+//# sourceMappingURL=verify_command.d.ts.map

package/dist/commands/verify_command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_command.d.ts","sourceRoot":"","sources":["../../src/commands/verify_command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,qBAAa,aAAa;IACzB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAuBvC,OAAO,CAAC,MAAM,CAAC,KAAK;IAapB,OAAO,CAAC,MAAM,CAAC,UAAU;IAUzB,OAAO,CAAC,MAAM,CAAC,kBAAkB;CASjC"}

package/dist/commands/verify_command.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { ProjectVerifier } from '../verify/project_verifier.js';
+export class VerifyCommand {
+    static register(program) {
+        program
+            .command('verify')
+            .description('run the project type-check + test gates and return one keep/revert verdict for an edit')
+            .option('-C, --cwd <path>', 'project directory whose package.json scripts are run', process.cwd())
+            .option('--typecheck-script <name>', 'npm script for the type-check gate', 'typecheck')
+            .option('--test-script <name>', 'npm script for the test gate', 'test')
+            .option('--skip-typecheck', 'skip the type-check gate', false)
+            .option('--skip-tests', 'skip the test gate (degrades to type-check-only)', false)
+            .option('--json', 'emit the verdict as JSON', false)
+            .action(async (options) => {
+            const report = await ProjectVerifier.verify({
+                cwd: options.cwd,
+                typecheckScript: options.typecheckScript,
+                testScript: options.testScript,
+                skipTypecheck: options.skipTypecheck === true,
+                skipTests: options.skipTests === true,
+            });
+            VerifyCommand.print(report, options.json === true);
+            process.exitCode = report.ok === true ? 0 : 1;
+        });
+    }
+    static print(report, json) {
+        if (json === true) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        for (const check of report.checks) {
+            VerifyCommand.printCheck(check);
+        }
+        const verdict = report.ok === true ? chalk.green('✓') : chalk.red('✗');
+        console.log(`\n${verdict} ${report.summary}`);
+        VerifyCommand.printFailureOutput(report);
+    }
+    static printCheck(check) {
+        if (check.status === 'skipped') {
+            console.log(`${chalk.yellow('•')} ${chalk.bold(check.name.padEnd(10))} ${chalk.yellow('skipped')}  ${chalk.gray(check.skippedReason ?? '')}`);
+            return;
+        }
+        const mark = check.status === 'pass' ? chalk.green('✓') : chalk.red('✗');
+        const timing = chalk.gray(`${(check.durationMs / 1000).toFixed(1)}s`);
+        console.log(`${mark} ${chalk.bold(check.name.padEnd(10))} ${chalk.gray(check.command ?? '')}  ${timing}`);
+    }
+    static printFailureOutput(report) {
+        if (report.ok === true) {
+            return;
+        }
+        for (const check of report.checks.filter((candidate) => candidate.status === 'fail')) {
+            console.log(chalk.bold(`\n— ${check.name} output (tail) —`));
+            console.log(check.output.trimEnd());
+        }
+    }
+}
+//# sourceMappingURL=verify_command.js.map