ts-knowledge-graph 0.1.2 → 0.1.6

package/dist/cluster/graph_clusterer.js

@@ -0,0 +1,126 @@
+import { EDGE_KINDS } from '../schema/edge.js';
+import { CommunityDetector, DEFAULT_COMMUNITY_OPTIONS } from './community_detector.js';
+import { CommunityLabeler } from './community_labeler.js';
+/** Namespaced key under which a node's community index is stored on its metadata. */
+export const COMMUNITY_METADATA_KEY = 'community';
+/** Namespaced key under which a node's human-readable community label is stored on its metadata. */
+export const COMMUNITY_LABEL_METADATA_KEY = 'communityLabel';
+/** Graph-level metadata key under which the clustering manifest is recorded. */
+export const CLUSTERING_MANIFEST_KEY = 'clustering';
+/** The runtime call-graph edge kind (`enrich`); its weight comes from sample count, not call-site count. */
+const RUNTIME_CALL_EDGE_KIND = 'CALLS_RUNTIME';
+/**
+ * Orchestrates a clustering pass over a loaded graph: read the weighted edges,
+ * detect communities with {@link CommunityDetector}, and attach the community
+ * index onto each node's metadata. Mirrors {@link RuntimeEnricher} — the pure
+ * algorithm lives in {@link CommunityDetector}; this class owns the store I/O.
+ *
+ * Existing node metadata is preserved; only the `community` key is written, so
+ * re-running is idempotent for an unchanged graph.
+ */
+export class GraphClusterer {
+    static async cluster(store, weights = {}, options = DEFAULT_COMMUNITY_OPTIONS) {
+        const edges = await GraphClusterer.readWeightedEdges(store, weights);
+        const result = CommunityDetector.detect(edges, options);
+        const nodes = await store.readNodes();
+        const labels = CommunityLabeler.label({
+            communityOf: result.communityOf,
+            nodes: nodes.map((node) => ({ id: node.id, name: node.name, kind: node.kind, filePath: node.filePath })),
+            edges,
+        });
+        const updates = [];
+        for (const node of nodes) {
+            const index = result.communityOf.get(node.id);
+            if (index === undefined) {
+                continue;
+            }
+            updates.push({
+                id: node.id,
+                metadata: {
+                    ...node.metadata,
+                    [COMMUNITY_METADATA_KEY]: index,
+                    [COMMUNITY_LABEL_METADATA_KEY]: labels.get(index) ?? `community ${index}`,
+                },
+            });
+        }
+        await store.writeNodeMetadata(updates);
+        const orderedLabels = GraphClusterer.orderLabels(labels, result.communityCount);
+        await store.writeGraphMeta(CLUSTERING_MANIFEST_KEY, {
+            algorithm: 'leiden-cpm',
+            resolution: options.resolution,
+            communityCount: result.communityCount,
+            quality: result.quality,
+            labels: orderedLabels,
+        });
+        return {
+            nodesAssigned: updates.length,
+            communityCount: result.communityCount,
+            quality: result.quality,
+            resolution: options.resolution,
+            sizes: result.sizes,
+            labels: orderedLabels,
+        };
+    }
+    /** Flattens the per-index label map into an array aligned with community indices `0..count-1`. */
+    static orderLabels(labels, count) {
+        return Array.from({ length: count }, (_, index) => labels.get(index) ?? `community ${index}`);
+    }
+    /**
+     * Reads every edge whose kind carries a positive weight, resolving each to a
+     * {@link WeightedEdge} whose weight is the kind's coefficient times the edge's
+     * call-site `count`.
+     */
+    static async readWeightedEdges(store, weights) {
+        const kinds = EDGE_KINDS.filter((kind) => (weights[kind] ?? 0) > 0);
+        if (kinds.length === 0) {
+            return [];
+        }
+        const kindList = `[${kinds.map((kind) => `'${kind}'`).join(', ')}]`;
+        const rows = await store.run(`MATCH (source:GraphNode)-[e:Edge]->(target:GraphNode)
+			WHERE e.kind IN ${kindList}
+			RETURN source.id AS fromId, target.id AS toId, e.kind AS kind, e.metadata AS metadata`);
+        // Runtime call edges carry a sample count that dwarfs static call-site counts;
+        // normalize them by the hottest runtime edge so the runtime coefficient stays
+        // on the same scale as the static ones — the peak call path contributes its
+        // full coefficient, cooler paths proportionally less.
+        const maxRuntimeSamples = rows.reduce((max, row) => String(row.kind) === RUNTIME_CALL_EDGE_KIND
+            ? Math.max(max, GraphClusterer.edgeSamples(row.metadata))
+            : max, 0);
+        return rows.map((row) => {
+            const kind = String(row.kind);
+            const coefficient = weights[kind] ?? 0;
+            const strength = kind === RUNTIME_CALL_EDGE_KIND
+                ? (maxRuntimeSamples > 0 ? GraphClusterer.edgeSamples(row.metadata) / maxRuntimeSamples : 0)
+                : GraphClusterer.callCount(row.metadata);
+            return {
+                from: String(row.fromId),
+                to: String(row.toId),
+                weight: coefficient * strength,
+            };
+        });
+    }
+    /** Decodes an edge's call-site `count`, defaulting to 1 (the minimum the builder records). */
+    static callCount(value) {
+        const count = GraphClusterer.parseMetadata(value).count;
+        return typeof count === 'number' && count > 0 ? count : 1;
+    }
+    /** Decodes a runtime call edge's `samples` weight, defaulting to 0. */
+    static edgeSamples(value) {
+        const samples = GraphClusterer.parseMetadata(value).samples;
+        return typeof samples === 'number' && samples > 0 ? samples : 0;
+    }
+    /** Decodes the JSON `metadata` column into a record; a missing, empty, or malformed value yields an empty record. */
+    static parseMetadata(value) {
+        if (typeof value !== 'string' || value.length === 0) {
+            return {};
+        }
+        try {
+            const parsed = JSON.parse(value);
+            return typeof parsed === 'object' && parsed !== null ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+}
+//# sourceMappingURL=graph_clusterer.js.map

package/dist/cluster/graph_clusterer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_clusterer.js","sourceRoot":"","sources":["../../src/cluster/graph_clusterer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAY,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAoB,yBAAyB,EAAgB,MAAM,yBAAyB,CAAC;AACvH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,qFAAqF;AACrF,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAC;AAElD,oGAAoG;AACpG,MAAM,CAAC,MAAM,4BAA4B,GAAG,gBAAgB,CAAC;AAE7D,gFAAgF;AAChF,MAAM,CAAC,MAAM,uBAAuB,GAAG,YAAY,CAAC;AAEpD,4GAA4G;AAC5G,MAAM,sBAAsB,GAAa,eAAe,CAAC;AAczD;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAc;IAC1B,MAAM,CAAC,KAAK,CAAC,OAAO,CACnB,KAAgB,EAChB,UAA6C,EAAE,EAC/C,UAA4B,yBAAyB;QAErD,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,iBAAiB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACrE,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAExD,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,SAAS,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC;YACrC,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;YACxG,KAAK;SACL,CAAC,CAAC;QAEH,MAAM,OAAO,GAAwD,EAAE,CAAC;QACxE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC9C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACzB,SAAS;YACV,CAAC;YACD,OAAO,CAAC,IAAI,CAAC;gBACZ,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,QAAQ,EAAE;oBACT,GAAG,IAAI,CAAC,QAAQ;oBAChB,CAAC,sBAAsB,CAAC,EAAE,KAAK;oBAC/B,CAAC,4BAA4B,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,aAAa,KAAK,EAAE;iBACzE;aACD,CAAC,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAEvC,MAAM,aAAa,GAAG,cAAc,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;QAEhF,MAAM,KAAK,CAAC,cAAc,CAAC,uBAAuB,EAAE;YACnD,SAAS,EAAE,YAAY;YACvB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,aAAa;SACrB,CAAC,CAAC;QAEH,OAAO;YACN,aAAa,EAAE,OAAO,CAAC,MAAM;YAC7B,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,aAAa;SACrB,CAAC;IACH,CAAC;IAED,kGAAkG;IAC1F,MAAM,CAAC,WAAW,CAAC,MAA2B,EAAE,KAAa;QACpE,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,aAAa,KAAK,EAAE,CAAC,CAAC;IAC/F,CAAC;IAED;;;;OAIG;IACK,MAAM,CAAC,KAAK,CAAC,iBAAiB,CACrC,KAAgB,EAChB,OAA0C;QAE1C,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACpE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,CAAC;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACpE,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,CAC3B;qBACkB,QAAQ;yFAC4D,CACtF,CAAC;QAEF,+EAA+E;QAC/E,8EAA8E;QAC9E,4EAA4E;QAC5E,sDAAsD;QACtD,MAAM,iBAAiB,GAAG,IAAI,CAAC,MAAM,CACpC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,sBAAsB;YACxD,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACzD,CAAC,CAAC,GAAG,EACN,CAAC,CACD,CAAC;QAEF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;YACvB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAa,CAAC;YAC1C,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvC,MAAM,QAAQ,GAAG,IAAI,KAAK,sBAAsB;gBAC/C,CAAC,CAAC,CAAC,iBAAiB,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC5F,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC1C,OAAO;gBACN,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;gBACxB,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;gBACpB,MAAM,EAAE,WAAW,GAAG,QAAQ;aAC9B,CAAC;QACH,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,8FAA8F;IACtF,MAAM,CAAC,SAAS,CAAC,KAAgB;QACxC,MAAM,KAAK,GAAG,cAAc,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC;QACxD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,uEAAuE;IAC/D,MAAM,CAAC,WAAW,CAAC,KAAgB;QAC1C,MAAM,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC;QAC5D,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,qHAAqH;IAC7G,MAAM,CAAC,aAAa,CAAC,KAAgB;QAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrD,OAAO,EAAE,CAAC;QACX,CAAC;QACD,IAAI,CAAC;YACJ,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAiC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/F,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,EAAE,CAAC;QACX,CAAC;IACF,CAAC;CACD"}

package/dist/commands/benchmark_command.d.ts

@@ -0,0 +1,11 @@
+import { Command } from 'commander';
+export declare class BenchmarkCommand {
+    static register(program: Command): void;
+    private static run;
+    private static readBaselineMedian;
+    private static writeBaseline;
+    private static print;
+    private static printDelta;
+    private static round;
+}
+//# sourceMappingURL=benchmark_command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark_command.d.ts","sourceRoot":"","sources":["../../src/commands/benchmark_command.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBpC,qBAAa,gBAAgB;IAC5B,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;mBAuBlB,GAAG;mBAwBH,kBAAkB;mBAKlB,aAAa;IAMlC,OAAO,CAAC,MAAM,CAAC,KAAK;IAsBpB,OAAO,CAAC,MAAM,CAAC,UAAU;IAQzB,OAAO,CAAC,MAAM,CAAC,KAAK;CAGpB"}

package/dist/commands/benchmark_command.js

@@ -0,0 +1,94 @@
+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 { OutputFolder } from '../store/output_folder.js';
+import { CommandHelpers } 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) {
+        const command = 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');
+        CommandHelpers.addOutputFolderOption(command)
+            .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', 'compare against the saved baseline for <target> (advisory delta)', false)
+            .option('--save-baseline', 'save this run as the baseline for <target>', false)
+            .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 folder = new OutputFolder(options.outputFolder);
+        const baselineFile = folder.baselinePath(target);
+        const store = new KuzuStore(folder.dbPath);
+        await store.initSchema();
+        const profileDir = await mkdtemp(join(tmpdir(), 'tkg-bench-'));
+        try {
+            const baselineMedian = options.baseline === true ? await BenchmarkCommand.readBaselineMedian(baselineFile) : undefined;
+            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 === true) {
+                await BenchmarkCommand.writeBaseline(baselineFile, 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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blast_radius_command.d.ts","sourceRoot":"","sources":["../../src/commands/blast_radius_command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,qBAAa,kBAAkB;IAC9B,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;CAcvC"}
+{"version":3,"file":"blast_radius_command.d.ts","sourceRoot":"","sources":["../../src/commands/blast_radius_command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,qBAAa,kBAAkB;IAC9B,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;CAcvC"}

package/dist/commands/blast_radius_command.js

@@ -1,15 +1,16 @@
-import { CommandHelpers, DEFAULT_DB_PATH } from './command_helpers.js';
+import { OutputFolder } from '../store/output_folder.js';
+import { CommandHelpers } from './command_helpers.js';
 export class BlastRadiusCommand {
     static register(program) {
-        program
+        const command = program
             .command('blast-radius')
             .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')
+            .argument('<id>', 'node id to analyse');
+        CommandHelpers.addOutputFolderOption(command)
+            .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) => {
+            await CommandHelpers.withQuery(new OutputFolder(options.outputFolder), async (query) => {
                 CommandHelpers.printRefs(await query.blastRadius(id, Number(options.depth)), options.json === true);
             });
         });

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,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAgB,MAAM,sBAAsB,CAAC;AAMpE,MAAM,OAAO,kBAAkB;IAC9B,MAAM,CAAC,QAAQ,CAAC,OAAgB;QAC/B,MAAM,OAAO,GAAG,OAAO;aACrB,OAAO,CAAC,cAAc,CAAC;aACvB,WAAW,CAAC,0DAA0D,CAAC;aACvE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;QACzC,cAAc,CAAC,qBAAqB,CAAC,OAAO,CAAC;aAC3C,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,IAAI,YAAY,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;gBACtF,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/cluster_command.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"cluster_command.d.ts","sourceRoot":"","sources":["../../src/commands/cluster_command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC,qBAAa,cAAc;IAC1B,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;mBAYlB,GAAG;IAoBxB,OAAO,CAAC,MAAM,CAAC,KAAK;CAcpB"}

package/dist/commands/cluster_command.js

@@ -0,0 +1,55 @@
+import chalk from 'chalk';
+import { CLUSTER_EDGE_WEIGHTS } from '../cluster/cluster_weights.js';
+import { DEFAULT_COMMUNITY_OPTIONS } from '../cluster/community_detector.js';
+import { GraphClusterer } from '../cluster/graph_clusterer.js';
+import { KuzuStore } from '../store/kuzu_store.js';
+import { OutputFolder } from '../store/output_folder.js';
+import { CommandHelpers } from './command_helpers.js';
+export class ClusterCommand {
+    static register(program) {
+        const command = program
+            .command('cluster')
+            .description('detect code communities with the Leiden algorithm and attach metadata.community onto nodes');
+        CommandHelpers.addOutputFolderOption(command)
+            .option('--resolution <n>', 'CPM resolution (higher → more, smaller communities)', String(DEFAULT_COMMUNITY_OPTIONS.resolution))
+            .option('--json', 'emit the clustering report as JSON', false)
+            .action(async (options) => {
+            await ClusterCommand.run(options);
+        });
+    }
+    static async run(options) {
+        const resolution = Number(options.resolution);
+        if (Number.isFinite(resolution) === false || resolution <= 0) {
+            console.error(chalk.red(`invalid --resolution '${options.resolution}' — expected a positive number`));
+            process.exitCode = 1;
+            return;
+        }
+        const store = new KuzuStore(new OutputFolder(options.outputFolder).dbPath);
+        await store.initSchema();
+        try {
+            const report = await GraphClusterer.cluster(store, CLUSTER_EDGE_WEIGHTS, {
+                ...DEFAULT_COMMUNITY_OPTIONS,
+                resolution,
+            });
+            ClusterCommand.print(report, options.json === true);
+        }
+        finally {
+            await store.close();
+        }
+    }
+    static print(report, json) {
+        if (json === true) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        if (report.nodesAssigned === 0) {
+            console.log(chalk.yellow('! no weighted edges in graph — run `extract --semantic` and `load` first.'));
+            return;
+        }
+        console.log(chalk.green(`✓ assigned ${report.nodesAssigned} node(s) to ${report.communityCount} communities`));
+        console.log(`  resolution ${report.resolution}, CPM quality ${report.quality.toFixed(4)}`);
+        const top = report.labels.slice(0, 8).map((label, index) => `${label} (${report.sizes[index]})`);
+        console.log(`  largest communities: ${top.join(', ')}`);
+    }
+}
+//# sourceMappingURL=cluster_command.js.map

package/dist/commands/cluster_command.js.map

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

package/dist/commands/command_helpers.d.ts

@@ -1,14 +1,19 @@
 import { Command } from 'commander';
 import { GraphQuery, NeighborRef, SymbolRef } from '../query/graph_query.js';
-export declare const DEFAULT_DB_PATH = "./outputs/graph.kuzu";
-export declare const DEFAULT_GRAPH_DIR = "./outputs/graph";
+import { OutputFolder } from '../store/output_folder.js';
+export declare const DEFAULT_OUTPUT_FOLDER = "./.ts_knowledge_graph";
 export type QueryOptions = {
-    db: string;
+    outputFolder: string;
     json?: boolean;
 };
 export declare class CommandHelpers {
+    /**
+     * Register the shared `-o, --output-folder` option — the single source of
+     * every output path. Returns the command so callers can keep chaining.
+     */
+    static addOutputFolderOption(command: Command): Command;
     static registerSymbolQuery(program: Command, name: string, argSpec: string, description: string, run: (query: GraphQuery, arg: string) => Promise<SymbolRef[]>): void;
-    static withQuery(dbPath: string, fn: (query: GraphQuery) => Promise<void>): Promise<void>;
+    static withQuery(folder: OutputFolder, fn: (query: GraphQuery) => Promise<void>): Promise<void>;
     static printRefs(refs: SymbolRef[], json: boolean): void;
     static printNeighbors(neighbors: NeighborRef[], json: boolean): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"command_helpers.d.ts","sourceRoot":"","sources":["../../src/commands/command_helpers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAG7E,eAAO,MAAM,eAAe,yBAAyB,CAAC;AACtD,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAEnD,MAAM,MAAM,YAAY,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,qBAAa,cAAc;IAC1B,MAAM,CAAC,mBAAmB,CACzB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC,GAC3D,IAAI;WAcM,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/F,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAexD,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;CAepE"}
+{"version":3,"file":"command_helpers.d.ts","sourceRoot":"","sources":["../../src/commands/command_helpers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE7E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,MAAM,MAAM,YAAY,GAAG;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,qBAAa,cAAc;IAC1B;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAQvD,MAAM,CAAC,mBAAmB,CACzB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC,GAC3D,IAAI;WAaM,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrG,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAexD,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;CAepE"}

package/dist/commands/command_helpers.js

@@ -1,25 +1,30 @@
-import { resolve } from 'node:path';
 import chalk from 'chalk';
 import { GraphQuery } from '../query/graph_query.js';
 import { KuzuStore } from '../store/kuzu_store.js';
-export const DEFAULT_DB_PATH = './outputs/graph.kuzu';
-export const DEFAULT_GRAPH_DIR = './outputs/graph';
+import { OutputFolder } from '../store/output_folder.js';
+export const DEFAULT_OUTPUT_FOLDER = './.ts_knowledge_graph';
 export class CommandHelpers {
+    /**
+     * Register the shared `-o, --output-folder` option — the single source of
+     * every output path. Returns the command so callers can keep chaining.
+     */
+    static addOutputFolderOption(command) {
+        return command.option('-o, --output-folder <dir>', 'output folder holding graph/, graph.kuzu, prof/, bench/', DEFAULT_OUTPUT_FOLDER);
+    }
     static registerSymbolQuery(program, name, argSpec, description, run) {
         const command = program.command(argSpec === '' ? name : `${name} ${argSpec}`).description(description);
-        command
-            .option('-d, --db <path>', 'Kùzu database path', DEFAULT_DB_PATH)
+        CommandHelpers.addOutputFolderOption(command)
             .option('--json', 'emit raw JSON', false)
             .action(async (...args) => {
             const options = args[args.length - 2];
             const arg = argSpec === '' ? '' : args[0];
-            await CommandHelpers.withQuery(options.db, async (query) => {
+            await CommandHelpers.withQuery(new OutputFolder(options.outputFolder), async (query) => {
                 CommandHelpers.printRefs(await run(query, arg), options.json === true);
             });
         });
     }
-    static async withQuery(dbPath, fn) {
-        const store = new KuzuStore(resolve(dbPath));
+    static async withQuery(folder, fn) {
+        const store = new KuzuStore(folder.dbPath);
         await store.initSchema();
         try {
             await fn(new GraphQuery(store));

package/dist/commands/command_helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"command_helpers.js","sourceRoot":"","sources":["../../src/commands/command_helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command_helpers.js","sourceRoot":"","sources":["../../src/commands/command_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,UAAU,EAA0B,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAO7D,MAAM,OAAO,cAAc;IAC1B;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CAAC,OAAgB;QAC5C,OAAO,OAAO,CAAC,MAAM,CACpB,2BAA2B,EAC3B,yDAAyD,EACzD,qBAAqB,CACrB,CAAC;IACH,CAAC;IAED,MAAM,CAAC,mBAAmB,CACzB,OAAgB,EAChB,IAAY,EACZ,OAAe,EACf,WAAmB,EACnB,GAA6D;QAE7D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,OAAO,EAAE,CAAC,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QACvG,cAAc,CAAC,qBAAqB,CAAC,OAAO,CAAC;aAC3C,MAAM,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,CAAC;aACxC,MAAM,CAAC,KAAK,EAAE,GAAG,IAAe,EAAE,EAAE;YACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAiB,CAAC;YACtD,MAAM,GAAG,GAAG,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAE,IAAI,CAAC,CAAC,CAAY,CAAC;YACtD,MAAM,cAAc,CAAC,SAAS,CAAC,IAAI,YAAY,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;gBACtF,cAAc,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;YACxE,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,MAAoB,EAAE,EAAwC;QACpF,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,KAAK,CAAC,UAAU,EAAE,CAAC;QACzB,IAAI,CAAC;YACJ,MAAM,EAAE,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;QACjC,CAAC;gBAAS,CAAC;YACV,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;IACF,CAAC;IAED,MAAM,CAAC,SAAS,CAAC,IAAiB,EAAE,IAAa;QAChD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAC3C,OAAO;QACR,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;YAC1C,OAAO;QACR,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACxB,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9H,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,YAAY,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,CAAC,cAAc,CAAC,SAAwB,EAAE,IAAa;QAC5D,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAChD,OAAO;QACR,CAAC;QACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC;YAC7C,OAAO;QACR,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACzD,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;QAC3K,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,MAAM,UAAU,CAAC,CAAC,CAAC;IAC1D,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;AAiBpC,qBAAa,WAAW;IACvB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAmCvC,OAAO,CAAC,MAAM,CAAC,YAAY;IA+B3B,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAmC/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,139 @@
+import chalk from 'chalk';
+import { OutputFolder } from '../store/output_folder.js';
+import { CommandHelpers } from './command_helpers.js';
+const METRICS = ['self-time', 'samples'];
+const FLOWS = ['static', 'runtime'];
+const NO_RUNTIME_NOTICE = '! no runtime data in graph — run `enrich` first. Inclusive cost needs measured self cost to propagate.';
+const FELLBACK_NOTICE = '! no runtime call edges — run `enrich` first. Propagating along the static call graph instead.';
+export class CostCommand {
+    static register(program) {
+        const command = 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');
+        CommandHelpers.addOutputFolderOption(command)
+            .option('--by <metric>', `cost metric: ${METRICS.join(', ')}`, 'self-time')
+            .option('--edges <graph>', `call graph to propagate along: ${FLOWS.join(', ')}`, 'static')
+            .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;
+            }
+            if (options.edges !== undefined && FLOWS.includes(options.edges) === false) {
+                console.error(chalk.red(`unknown call graph '${options.edges}' — choose one of: ${FLOWS.join(', ')}`));
+                process.exitCode = 1;
+                return;
+            }
+            const by = options.by;
+            const edges = options.edges;
+            await CommandHelpers.withQuery(new OutputFolder(options.outputFolder), async (query) => {
+                if (id === undefined) {
+                    const report = await query.costRanking({ by, edges, limit: Number(options.limit) });
+                    CostCommand.printRanking(report, options.json === true);
+                    return;
+                }
+                const attribution = await query.costAttribution(id, { by, edges });
+                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;
+        }
+        if (report.fellBack === true) {
+            console.log(chalk.yellow(FELLBACK_NOTICE));
+        }
+        const total = CostCommand.formatAmount(report.metric, report.totalSelf);
+        const coverage = CostCommand.formatCoverage(report.coverage);
+        const flow = report.edges === 'runtime' ? ' along the runtime call graph' : '';
+        console.log(chalk.bold(`Inclusive cost by ${report.metric}${flow}`) + 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;
+        }
+        if (attribution.fellBack === true) {
+            console.log(chalk.yellow(FELLBACK_NOTICE));
+        }
+        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