ts-knowledge-graph 0.1.4 → 0.1.6

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,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,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,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,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAChC,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,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

package/dist/cluster/cluster_weights.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster_weights.js","sourceRoot":"","sources":["../../src/cluster/cluster_weights.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAsC;IACtE,KAAK,EAAE,CAAC;IACR,aAAa,EAAE,CAAC;IAChB,YAAY,EAAE,CAAC;IACf,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,CAAC;IACb,SAAS,EAAE,GAAG;IACd,MAAM,EAAE,GAAG;IACX,KAAK,EAAE,CAAC;IACR,SAAS,EAAE,CAAC;IACZ,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,GAAG;CACb,CAAC"}

package/dist/cluster/community_detector.d.ts

@@ -0,0 +1,61 @@
+/** A directed graph edge reduced to its endpoints and a pre-resolved weight. */
+export type WeightedEdge = {
+    from: string;
+    to: string;
+    weight: number;
+};
+/** Tuning for a {@link CommunityDetector.detect} run. */
+export type CommunityOptions = {
+    /** CPM resolution: higher splits the graph into more, smaller communities. */
+    resolution: number;
+    /** Leiden iterations per random start; each iteration moves, refines, and re-aggregates. */
+    iterations: number;
+    /** Independent random starts; the partition with the best CPM quality wins. */
+    randomStarts: number;
+};
+/** The outcome of a clustering run, keyed back to the caller's string node ids. */
+export type CommunityResult = {
+    /** Node id to community index. Nodes touched by no weighted edge are absent. */
+    communityOf: Map<string, number>;
+    /** Number of communities found. */
+    communityCount: number;
+    /** CPM quality of the chosen partition. */
+    quality: number;
+    /** Member count per community, descending. */
+    sizes: number[];
+};
+/**
+ * Defaults tuned for module-scale community detection. `resolution` is a
+ * threshold on a community's average internal edge weight; 0.1 is permissive
+ * enough to keep loosely-coupled modules together. Sweep it up (toward 1) for
+ * tighter, finer clusters.
+ */
+export declare const DEFAULT_COMMUNITY_OPTIONS: CommunityOptions;
+/**
+ * Detects communities in the knowledge graph with the Leiden algorithm,
+ * delegating the optimization to `networkanalysis-ts` (the CWTS port of the
+ * library by the authors of the Leiden paper). The algorithm guarantees every
+ * community it returns is internally connected — unlike Louvain, which can leave
+ * a community split into disconnected pieces.
+ *
+ * This module is pure: it takes weighted edges and returns a partition, with no
+ * store access, mirroring how {@link RuntimeJoin} is the pure core behind
+ * `enrich`.
+ */
+export declare class CommunityDetector {
+    /**
+     * Runs Leiden (CPM quality function) over a weighted, undirected projection of
+     * the supplied edges.
+     *
+     * Directed edges are symmetrized: every unordered endpoint pair sums its
+     * weights onto a single undirected edge, so a mutual call counts once with the
+     * combined weight. String node ids are mapped to the contiguous integer indices
+     * the `Network` requires, and the resulting community labels are mapped back.
+     */
+    static detect(edges: WeightedEdge[], options?: CommunityOptions): CommunityResult;
+    /** Assigns every node id touched by an edge a stable, contiguous integer index. */
+    private static indexNodes;
+    /** Collapses directed edges into undirected ones, summing weights per unordered pair and dropping self-loops. */
+    private static symmetrize;
+}
+//# sourceMappingURL=community_detector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"community_detector.d.ts","sourceRoot":"","sources":["../../src/cluster/community_detector.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,MAAM,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG;IAC9B,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG;IAC7B,gFAAgF;IAChF,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,gBAIvC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAC7B;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,OAAO,GAAE,gBAA4C,GAAG,eAAe;IAmD5G,mFAAmF;IACnF,OAAO,CAAC,MAAM,CAAC,UAAU;IAczB,iHAAiH;IACjH,OAAO,CAAC,MAAM,CAAC,UAAU;CA2BzB"}

package/dist/cluster/community_detector.js

@@ -0,0 +1,120 @@
+import { Clustering, LeidenAlgorithm, Network } from 'networkanalysis-ts';
+/**
+ * Defaults tuned for module-scale community detection. `resolution` is a
+ * threshold on a community's average internal edge weight; 0.1 is permissive
+ * enough to keep loosely-coupled modules together. Sweep it up (toward 1) for
+ * tighter, finer clusters.
+ */
+export const DEFAULT_COMMUNITY_OPTIONS = {
+    resolution: 0.1,
+    iterations: 10,
+    randomStarts: 10,
+};
+/**
+ * Detects communities in the knowledge graph with the Leiden algorithm,
+ * delegating the optimization to `networkanalysis-ts` (the CWTS port of the
+ * library by the authors of the Leiden paper). The algorithm guarantees every
+ * community it returns is internally connected — unlike Louvain, which can leave
+ * a community split into disconnected pieces.
+ *
+ * This module is pure: it takes weighted edges and returns a partition, with no
+ * store access, mirroring how {@link RuntimeJoin} is the pure core behind
+ * `enrich`.
+ */
+export class CommunityDetector {
+    /**
+     * Runs Leiden (CPM quality function) over a weighted, undirected projection of
+     * the supplied edges.
+     *
+     * Directed edges are symmetrized: every unordered endpoint pair sums its
+     * weights onto a single undirected edge, so a mutual call counts once with the
+     * combined weight. String node ids are mapped to the contiguous integer indices
+     * the `Network` requires, and the resulting community labels are mapped back.
+     */
+    static detect(edges, options = DEFAULT_COMMUNITY_OPTIONS) {
+        const { ids, indexOf } = CommunityDetector.indexNodes(edges);
+        if (ids.length === 0) {
+            return { communityOf: new Map(), communityCount: 0, quality: 0, sizes: [] };
+        }
+        const undirected = CommunityDetector.symmetrize(edges, indexOf);
+        // Uniform node weights (not degree) keep this classic CPM: the resolution is
+        // then a portable threshold on a community's average internal edge weight,
+        // independent of node degree. Degree weights make the usable resolution range
+        // collapse to a graph-specific sliver.
+        const network = new Network({
+            nNodes: ids.length,
+            setNodeWeightsToTotalEdgeWeights: false,
+            edges: [undirected.sources, undirected.targets],
+            edgeWeights: undirected.weights,
+            sortedEdges: false,
+            checkIntegrity: false,
+        });
+        const algorithm = new LeidenAlgorithm();
+        algorithm.setResolution(options.resolution);
+        algorithm.setNIterations(options.iterations);
+        let best;
+        let bestQuality = Number.NEGATIVE_INFINITY;
+        for (let start = 0; start < options.randomStarts; start += 1) {
+            const clustering = new Clustering({ nNodes: network.getNNodes() });
+            algorithm.improveClustering(network, clustering);
+            const quality = algorithm.calcQuality(network, clustering);
+            if (quality > bestQuality) {
+                best = clustering;
+                bestQuality = quality;
+            }
+        }
+        if (best === undefined) {
+            return { communityOf: new Map(), communityCount: 0, quality: 0, sizes: [] };
+        }
+        best.orderClustersByNNodes();
+        const labels = best.getClusters();
+        const communityOf = new Map();
+        ids.forEach((id, i) => communityOf.set(id, labels[i]));
+        return {
+            communityOf,
+            communityCount: best.getNClusters(),
+            quality: bestQuality,
+            sizes: best.getNNodesPerCluster(),
+        };
+    }
+    /** Assigns every node id touched by an edge a stable, contiguous integer index. */
+    static indexNodes(edges) {
+        const indexOf = new Map();
+        const ids = [];
+        for (const edge of edges) {
+            for (const id of [edge.from, edge.to]) {
+                if (indexOf.has(id) === false) {
+                    indexOf.set(id, ids.length);
+                    ids.push(id);
+                }
+            }
+        }
+        return { ids, indexOf };
+    }
+    /** Collapses directed edges into undirected ones, summing weights per unordered pair and dropping self-loops. */
+    static symmetrize(edges, indexOf) {
+        const merged = new Map();
+        for (const edge of edges) {
+            const a = indexOf.get(edge.from);
+            const b = indexOf.get(edge.to);
+            if (a === undefined || b === undefined || a === b) {
+                continue;
+            }
+            const low = a < b ? a : b;
+            const high = a < b ? b : a;
+            const key = `${low}:${high}`;
+            merged.set(key, (merged.get(key) ?? 0) + edge.weight);
+        }
+        const sources = [];
+        const targets = [];
+        const weights = [];
+        for (const [key, weight] of merged) {
+            const separator = key.indexOf(':');
+            sources.push(Number(key.slice(0, separator)));
+            targets.push(Number(key.slice(separator + 1)));
+            weights.push(weight);
+        }
+        return { sources, targets, weights };
+    }
+}
+//# sourceMappingURL=community_detector.js.map

package/dist/cluster/community_detector.js.map

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

package/dist/cluster/community_labeler.d.ts

@@ -0,0 +1,84 @@
+import { WeightedEdge } from './community_detector.js';
+/** The subset of a node's fields the labeler reasons over. */
+export type LabelableNode = {
+    id: string;
+    name: string;
+    kind: string;
+    filePath: string;
+};
+/** Everything {@link CommunityLabeler.label} needs: the partition, the nodes, and the weighted edges. */
+export type CommunityLabelInput = {
+    /** Node id to community index, as produced by {@link CommunityDetector.detect}. */
+    communityOf: Map<string, number>;
+    /** The clustered nodes; only members present in `communityOf` are labelled. */
+    nodes: LabelableNode[];
+    /** The weighted edges the clustering ran on, used to find each community's hub. */
+    edges: WeightedEdge[];
+};
+/**
+ * Derives a human-readable label for each community from its members — a
+ * deterministic, dependency-free alternative to the bare ordinal (`community 3`).
+ *
+ * The label is a composite of two signals available on every node:
+ * - the **dominant directory** the members share (code communities track module
+ *   structure), and
+ * - the **hub member** — the node with the highest internal (within-community)
+ *   weighted degree, i.e. the symbol the rest of the community couples to most.
+ *
+ * Because every part is derived from membership (never the ordinal index), the
+ * same group of nodes earns the same label across the algorithm's stochastic
+ * re-runs. This module is pure — it takes a partition and returns labels, with no
+ * store access — mirroring {@link CommunityDetector}.
+ */
+export declare class CommunityLabeler {
+    /**
+     * Returns a map from community index to a unique, human-readable label.
+     *
+     * Per community: if the members live in a single file, the label is that file's
+     * base name; otherwise it is `<directory> · <hub>` when the members concentrate
+     * in one directory, or the hub alone when they are scattered. Colliding labels
+     * are disambiguated with the hub, then the ordinal, so the result is injective.
+     */
+    static label(input: CommunityLabelInput): Map<number, string>;
+    /** Buckets the labelled nodes by their community index, dropping nodes absent from the partition. */
+    private static groupMembers;
+    /**
+     * Sums each node's weighted degree over edges that stay inside its community.
+     * Cross-community edges and self-loops are ignored, so the result ranks members
+     * by how strongly they couple to the rest of their own community.
+     */
+    private static internalDegree;
+    /**
+     * The name of the member with the greatest internal weighted degree, breaking
+     * ties by name then id so the choice is stable. Returns `undefined` only for an
+     * empty group.
+     */
+    private static hubName;
+    /**
+     * A node's human-facing name. `Module` nodes carry their file path as their
+     * name, which reads poorly as a label, so they display as the file's base name.
+     */
+    private static displayName;
+    /** Builds the un-deduplicated label for one community from its area and hub. */
+    private static composeLabel;
+    /**
+     * The directory most members share, with the fraction of members under it. Ties
+     * favour the shorter (shallower) path, then lexical order, for determinism.
+     */
+    private static dominantDirectory;
+    /**
+     * Resolves label collisions into a unique set: a duplicated label gains its
+     * community's hub (when that adds information), and any still-colliding label
+     * gains a `#index` suffix as a last resort.
+     */
+    private static dedupe;
+    /** Applies `rename` to every label that more than one community currently shares. */
+    private static disambiguate;
+    /** The directory portion of a POSIX-style path, or `''` for a bare file name. */
+    private static directoryOf;
+    /** The final segment of a directory path, or the whole path when it has no separator. */
+    private static lastSegment;
+    /** A file's base name without its directory or extension (`src/a/foo.ts` → `foo`). */
+    private static baseName;
+}
+//# sourceMappingURL=community_labeler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"community_labeler.d.ts","sourceRoot":"","sources":["../../src/cluster/community_labeler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,yGAAyG;AACzG,MAAM,MAAM,mBAAmB,GAAG;IACjC,mFAAmF;IACnF,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,+EAA+E;IAC/E,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,mFAAmF;IACnF,KAAK,EAAE,YAAY,EAAE,CAAC;CACtB,CAAC;AASF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAgB;IAC5B;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,mBAAmB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAc7D,qGAAqG;IACrG,OAAO,CAAC,MAAM,CAAC,YAAY;IAiB3B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAiB7B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,OAAO;IAkBtB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAI1B,gFAAgF;IAChF,OAAO,CAAC,MAAM,CAAC,YAAY;IAoB3B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAmBhC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,MAAM;IAQrB,qFAAqF;IACrF,OAAO,CAAC,MAAM,CAAC,YAAY;IAe3B,iFAAiF;IACjF,OAAO,CAAC,MAAM,CAAC,WAAW;IAK1B,yFAAyF;IACzF,OAAO,CAAC,MAAM,CAAC,WAAW;IAQ1B,sFAAsF;IACtF,OAAO,CAAC,MAAM,CAAC,QAAQ;CAMvB"}

package/dist/cluster/community_labeler.js

@@ -0,0 +1,194 @@
+/**
+ * Fraction of a community's members that must share one directory before that
+ * directory is treated as the community's "area". Below this the members are too
+ * scattered for the directory to be meaningful, so the label falls back to the hub.
+ */
+const DIRECTORY_PURITY_THRESHOLD = 0.6;
+/**
+ * Derives a human-readable label for each community from its members — a
+ * deterministic, dependency-free alternative to the bare ordinal (`community 3`).
+ *
+ * The label is a composite of two signals available on every node:
+ * - the **dominant directory** the members share (code communities track module
+ *   structure), and
+ * - the **hub member** — the node with the highest internal (within-community)
+ *   weighted degree, i.e. the symbol the rest of the community couples to most.
+ *
+ * Because every part is derived from membership (never the ordinal index), the
+ * same group of nodes earns the same label across the algorithm's stochastic
+ * re-runs. This module is pure — it takes a partition and returns labels, with no
+ * store access — mirroring {@link CommunityDetector}.
+ */
+export class CommunityLabeler {
+    /**
+     * Returns a map from community index to a unique, human-readable label.
+     *
+     * Per community: if the members live in a single file, the label is that file's
+     * base name; otherwise it is `<directory> · <hub>` when the members concentrate
+     * in one directory, or the hub alone when they are scattered. Colliding labels
+     * are disambiguated with the hub, then the ordinal, so the result is injective.
+     */
+    static label(input) {
+        const groups = CommunityLabeler.groupMembers(input.communityOf, input.nodes);
+        const internalDegree = CommunityLabeler.internalDegree(input.communityOf, input.edges);
+        const base = new Map();
+        const hubs = new Map();
+        for (const [index, members] of groups) {
+            const hub = CommunityLabeler.hubName(members, internalDegree);
+            hubs.set(index, hub);
+            base.set(index, CommunityLabeler.composeLabel(index, members, hub));
+        }
+        return CommunityLabeler.dedupe(base, hubs);
+    }
+    /** Buckets the labelled nodes by their community index, dropping nodes absent from the partition. */
+    static groupMembers(communityOf, nodes) {
+        const groups = new Map();
+        for (const node of nodes) {
+            const index = communityOf.get(node.id);
+            if (index === undefined) {
+                continue;
+            }
+            const members = groups.get(index) ?? [];
+            members.push(node);
+            groups.set(index, members);
+        }
+        return groups;
+    }
+    /**
+     * Sums each node's weighted degree over edges that stay inside its community.
+     * Cross-community edges and self-loops are ignored, so the result ranks members
+     * by how strongly they couple to the rest of their own community.
+     */
+    static internalDegree(communityOf, edges) {
+        const degree = new Map();
+        for (const edge of edges) {
+            if (edge.from === edge.to) {
+                continue;
+            }
+            const from = communityOf.get(edge.from);
+            const to = communityOf.get(edge.to);
+            if (from === undefined || to === undefined || from !== to) {
+                continue;
+            }
+            degree.set(edge.from, (degree.get(edge.from) ?? 0) + edge.weight);
+            degree.set(edge.to, (degree.get(edge.to) ?? 0) + edge.weight);
+        }
+        return degree;
+    }
+    /**
+     * The name of the member with the greatest internal weighted degree, breaking
+     * ties by name then id so the choice is stable. Returns `undefined` only for an
+     * empty group.
+     */
+    static hubName(members, internalDegree) {
+        if (members.length === 0) {
+            return undefined;
+        }
+        const ranked = [...members].sort((a, b) => {
+            const degreeA = internalDegree.get(a.id) ?? 0;
+            const degreeB = internalDegree.get(b.id) ?? 0;
+            if (degreeB !== degreeA) {
+                return degreeB - degreeA;
+            }
+            if (a.name !== b.name) {
+                return a.name < b.name ? -1 : 1;
+            }
+            return a.id < b.id ? -1 : 1;
+        });
+        return CommunityLabeler.displayName(ranked[0]);
+    }
+    /**
+     * A node's human-facing name. `Module` nodes carry their file path as their
+     * name, which reads poorly as a label, so they display as the file's base name.
+     */
+    static displayName(node) {
+        return node.kind === 'Module' ? CommunityLabeler.baseName(node.filePath) : node.name;
+    }
+    /** Builds the un-deduplicated label for one community from its area and hub. */
+    static composeLabel(index, members, hub) {
+        if (members.length === 0) {
+            return `community ${index}`;
+        }
+        const files = new Set(members.map((member) => member.filePath));
+        if (files.size === 1) {
+            const fileName = CommunityLabeler.baseName(members[0].filePath);
+            return fileName.length > 0 ? fileName : (hub ?? `community ${index}`);
+        }
+        const { directory, purity } = CommunityLabeler.dominantDirectory(members);
+        const area = CommunityLabeler.lastSegment(directory);
+        if (area.length > 0 && purity >= DIRECTORY_PURITY_THRESHOLD) {
+            return hub === undefined ? area : `${area} · ${hub}`;
+        }
+        if (hub !== undefined) {
+            return hub;
+        }
+        return area.length > 0 ? area : `community ${index}`;
+    }
+    /**
+     * The directory most members share, with the fraction of members under it. Ties
+     * favour the shorter (shallower) path, then lexical order, for determinism.
+     */
+    static dominantDirectory(members) {
+        const counts = new Map();
+        for (const member of members) {
+            const directory = CommunityLabeler.directoryOf(member.filePath);
+            counts.set(directory, (counts.get(directory) ?? 0) + 1);
+        }
+        const ranked = [...counts.entries()].sort((a, b) => {
+            if (b[1] !== a[1]) {
+                return b[1] - a[1];
+            }
+            if (a[0].length !== b[0].length) {
+                return a[0].length - b[0].length;
+            }
+            return a[0] < b[0] ? -1 : 1;
+        });
+        const [directory, count] = ranked[0];
+        return { directory, purity: count / members.length };
+    }
+    /**
+     * Resolves label collisions into a unique set: a duplicated label gains its
+     * community's hub (when that adds information), and any still-colliding label
+     * gains a `#index` suffix as a last resort.
+     */
+    static dedupe(base, hubs) {
+        const withHub = CommunityLabeler.disambiguate(base, (index, label) => {
+            const hub = hubs.get(index);
+            return hub !== undefined && label.includes(hub) === false ? `${label} · ${hub}` : label;
+        });
+        return CommunityLabeler.disambiguate(withHub, (index, label) => `${label} #${index}`);
+    }
+    /** Applies `rename` to every label that more than one community currently shares. */
+    static disambiguate(labels, rename) {
+        const counts = new Map();
+        for (const label of labels.values()) {
+            counts.set(label, (counts.get(label) ?? 0) + 1);
+        }
+        const result = new Map();
+        for (const [index, label] of labels) {
+            result.set(index, (counts.get(label) ?? 0) > 1 ? rename(index, label) : label);
+        }
+        return result;
+    }
+    /** The directory portion of a POSIX-style path, or `''` for a bare file name. */
+    static directoryOf(filePath) {
+        const slash = filePath.lastIndexOf('/');
+        return slash === -1 ? '' : filePath.slice(0, slash);
+    }
+    /** The final segment of a directory path, or the whole path when it has no separator. */
+    static lastSegment(directory) {
+        if (directory.length === 0) {
+            return '';
+        }
+        const slash = directory.lastIndexOf('/');
+        return slash === -1 ? directory : directory.slice(slash + 1);
+    }
+    /** A file's base name without its directory or extension (`src/a/foo.ts` → `foo`). */
+    static baseName(filePath) {
+        const slash = filePath.lastIndexOf('/');
+        const fileName = slash === -1 ? filePath : filePath.slice(slash + 1);
+        const dot = fileName.lastIndexOf('.');
+        return dot <= 0 ? fileName : fileName.slice(0, dot);
+    }
+}
+//# sourceMappingURL=community_labeler.js.map

package/dist/cluster/community_labeler.js.map

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

package/dist/cluster/graph_clusterer.d.ts

@@ -0,0 +1,47 @@
+import { EdgeKind } from '../schema/edge.js';
+import { KuzuStore } from '../store/kuzu_store.js';
+import { CommunityOptions } from './community_detector.js';
+/** Namespaced key under which a node's community index is stored on its metadata. */
+export declare const COMMUNITY_METADATA_KEY = "community";
+/** Namespaced key under which a node's human-readable community label is stored on its metadata. */
+export declare const COMMUNITY_LABEL_METADATA_KEY = "communityLabel";
+/** Graph-level metadata key under which the clustering manifest is recorded. */
+export declare const CLUSTERING_MANIFEST_KEY = "clustering";
+/** The summary `cluster` returns and prints. */
+export type ClusterReport = {
+    nodesAssigned: number;
+    communityCount: number;
+    quality: number;
+    resolution: number;
+    /** Member count per community, descending. */
+    sizes: number[];
+    /** Human-readable label per community, aligned with {@link ClusterReport.sizes}. */
+    labels: string[];
+};
+/**
+ * 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 declare class GraphClusterer {
+    static cluster(store: KuzuStore, weights?: Partial<Record<EdgeKind, number>>, options?: CommunityOptions): Promise<ClusterReport>;
+    /** Flattens the per-index label map into an array aligned with community indices `0..count-1`. */
+    private static orderLabels;
+    /**
+     * 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`.
+     */
+    private static readWeightedEdges;
+    /** Decodes an edge's call-site `count`, defaulting to 1 (the minimum the builder records). */
+    private static callCount;
+    /** Decodes a runtime call edge's `samples` weight, defaulting to 0. */
+    private static edgeSamples;
+    /** Decodes the JSON `metadata` column into a record; a missing, empty, or malformed value yields an empty record. */
+    private static parseMetadata;
+}
+//# sourceMappingURL=graph_clusterer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_clusterer.d.ts","sourceRoot":"","sources":["../../src/cluster/graph_clusterer.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAqB,gBAAgB,EAA2C,MAAM,yBAAyB,CAAC;AAGvH,qFAAqF;AACrF,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAElD,oGAAoG;AACpG,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAKpD,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,oFAAoF;IACpF,MAAM,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,cAAc;WACb,OAAO,CACnB,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAM,EAC/C,OAAO,GAAE,gBAA4C,GACnD,OAAO,CAAC,aAAa,CAAC;IAgDzB,kGAAkG;IAClG,OAAO,CAAC,MAAM,CAAC,WAAW;IAI1B;;;;OAIG;mBACkB,iBAAiB;IAwCtC,8FAA8F;IAC9F,OAAO,CAAC,MAAM,CAAC,SAAS;IAKxB,uEAAuE;IACvE,OAAO,CAAC,MAAM,CAAC,WAAW;IAK1B,qHAAqH;IACrH,OAAO,CAAC,MAAM,CAAC,aAAa;CAW5B"}