homegraph 1.4.1 → 1.5.1

package/dist/spec/mine/clustering/index.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * Commit Clusterer — multi-signal graph clustering for the `spec mine` pipeline.
+ *
+ * Groups commits by structural (AST symbol overlap), file-path, temporal,
+ * and commit-message similarity. Pure TypeScript implementation — no native
+ * dependencies required.
+ *
+ * Orchestrates the pieces in this directory:
+ *   - `text-similarity` — tokenize / Jaccard / cosine / TF-IDF
+ *   - `features`        — per-commit feature extraction
+ *   - `leiden`          — generic Leiden community detection + tuning
+ *
+ * @module spec/mine/clustering
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clusterCommits = clusterCommits;
+const errors_1 = require("../../../errors");
+const text_similarity_1 = require("./text-similarity");
+const features_1 = require("./features");
+const leiden_1 = require("./leiden");
+// ---------------------------------------------------------------------------
+// Similarity Computation
+// ---------------------------------------------------------------------------
+/**
+ * Compute multi-signal similarity between two commits.
+ *
+ * Weights:
+ *   - Symbol overlap (Jaccard):       0.40
+ *   - Spatial proximity (Jaccard):    0.15  (max of file-path and dir-prefix)
+ *   - Message TF-IDF cosine:          0.25
+ *   - Ticket reference overlap:       0.10
+ *   - Temporal proximity:             0.10  (half-life 3 days)
+ *
+ * A cohesion penalty is applied as a multiplier when one commit has low
+ * symbol-per-file density (< 2.0), which is characteristic of mechanical
+ * refactors that should not bridge unrelated feature clusters.
+ */
+function computeSimilarity(a, b, aSymbols, bSymbols, aFiles, bFiles, aDirs, bDirs, aTickets, bTickets, msgTfidfMatrix, aIdx, bIdx) {
+    // Symbol overlap — highest weight because AST-level diff is precise
+    const symbolSim = (0, text_similarity_1.jaccard)(aSymbols, bSymbols);
+    // Spatial proximity — max of exact file-path and module-level dir-prefix
+    // overlap, so same-file edits get full credit and same-module edits also
+    // connect, without double-counting the same spatial dimension.
+    const spatialSim = Math.max((0, text_similarity_1.jaccard)(aFiles, bFiles), (0, text_similarity_1.jaccard)(aDirs, bDirs));
+    // Message TF-IDF cosine
+    const msgSim = (0, text_similarity_1.cosineSimilarity)(msgTfidfMatrix[aIdx], msgTfidfMatrix[bIdx]);
+    // Ticket reference overlap
+    const ticketSim = (0, text_similarity_1.jaccard)(aTickets, bTickets);
+    // Temporal proximity — half-life 3 days (259200 seconds)
+    const halfLife = 3 * 24 * 60 * 60 * 1000;
+    const maxTimeSpan = Math.abs(a.timestamp - b.timestamp);
+    const timeSim = Math.exp(-maxTimeSpan / halfLife);
+    // Cohesion penalty: low cohesion (many files, few symbols) = refactor-like.
+    // Penalty multiplier: 0.6 at cohesion 0 → 1.0 at cohesion ≥ 2.0
+    const minCohesion = Math.min((0, features_1.computeCohesion)(a), (0, features_1.computeCohesion)(b));
+    const cohesionPenalty = minCohesion >= 2.0
+        ? 1.0
+        : 0.6 + 0.4 * (minCohesion / 2.0);
+    const rawScore = 0.40 * symbolSim +
+        0.15 * spatialSim +
+        0.25 * msgSim +
+        0.10 * ticketSim +
+        0.10 * timeSim;
+    return rawScore * cohesionPenalty;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Cluster commits using Leiden community detection on a multi-signal
+ * similarity graph, with recursive sub-splitting for large clusters.
+ *
+ * The pipeline:
+ *   1. Build a weighted similarity graph from AST symbol, file-path,
+ *      commit-message TF-IDF, ticket-reference, and temporal signals.
+ *   2. Run Leiden community detection with auto-tuned resolution γ.
+ *   3. Greedy-merge if still too many communities.
+ *   4. Recursively split large clusters (≥ 4 commits) by running
+ *      Leiden on their sub-graphs.
+ *
+ * Replaces the previous Louvain (no refinement) and connected-components
+ * (single-linkage chaining) approaches.
+ *
+ * @param changes     - AST change data for each commit.
+ * @param threshold   - Minimum similarity (0-1) for considering an edge.
+ * @param maxClusters - Desired maximum number of top-level clusters.
+ *                      The resolution parameter γ is auto-tuned to approach
+ *                      this target. Recursive splitting may produce more
+ *                      clusters at finer granularities.
+ * @returns Clustered result with stats.
+ */
+function clusterCommits(changes, threshold, maxClusters) {
+    const n = changes.length;
+    // Edge cases: 0 or 1 commit — avoid Leiden overhead.
+    if (n === 0) {
+        return {
+            clusters: [],
+            unclustered: [],
+            stats: { totalCommits: 0, clusteredCommits: 0, clusterCount: 0 },
+        };
+    }
+    if (n === 1) {
+        const c = changes[0];
+        const totalSymbols = (0, features_1.countChangedSymbols)(c);
+        if (totalSymbols < features_1.MIN_SYMBOLS_FOR_SOLO_CLUSTER && !(0, features_1.hasNewNonTestFiles)(c)) {
+            (0, errors_1.logDebug)('Clusterer: single commit below quality threshold', {
+                hash: c.commitHash.slice(0, 7),
+                changedSymbols: totalSymbols,
+                minRequired: features_1.MIN_SYMBOLS_FOR_SOLO_CLUSTER,
+            });
+            return {
+                clusters: [],
+                unclustered: [c],
+                stats: { totalCommits: 1, clusteredCommits: 0, clusterCount: 0 },
+            };
+        }
+        const syms = (0, features_1.collectSymbolNames)(c);
+        const files = (0, features_1.collectFilePaths)(c);
+        return {
+            clusters: [
+                {
+                    id: 0,
+                    commits: [c],
+                    primaryFiles: files,
+                    primarySymbols: syms,
+                    summary: `1 commit: ${c.commitMessage}`,
+                    timeRange: { start: c.timestamp, end: c.timestamp },
+                },
+            ],
+            unclustered: [],
+            stats: { totalCommits: 1, clusteredCommits: 1, clusterCount: 1 },
+        };
+    }
+    // n >= 2: full pipeline from here.
+    // --- Pre-compute per-commit feature vectors ---
+    const messages = [];
+    const allSymbols = [];
+    const allFiles = [];
+    const allDirs = [];
+    const allTickets = [];
+    for (const change of changes) {
+        messages.push((0, text_similarity_1.tokenize)(change.commitMessage));
+        allSymbols.push((0, features_1.collectSymbolNames)(change));
+        allFiles.push((0, features_1.collectFilePaths)(change));
+        allDirs.push((0, features_1.collectDirectoryPrefixes)(change));
+        allTickets.push((0, features_1.extractTicketRefs)(change.commitMessage));
+    }
+    // --- Build TF-IDF vectors for commit messages ---
+    const tfidf = new text_similarity_1.TfidfVectorizer();
+    tfidf.fit(messages);
+    const msgTfidfMatrix = messages.map((msg) => tfidf.transform(msg));
+    // --- Build weighted similarity graph ---
+    const graph = Array.from({ length: n }, () => new Array(n).fill(0));
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            const sim = computeSimilarity(changes[i], changes[j], allSymbols[i], allSymbols[j], allFiles[i], allFiles[j], allDirs[i], allDirs[j], allTickets[i], allTickets[j], msgTfidfMatrix, i, j);
+            if (sim >= threshold) {
+                graph[i][j] = sim;
+                graph[j][i] = sim;
+            }
+        }
+    }
+    // --- Leiden community detection with auto-tuned resolution ---
+    let components = (0, leiden_1.autoTuneResolution)(graph, maxClusters);
+    // --- Greedy merge if still too many communities ---
+    if (components.length > maxClusters) {
+        (0, errors_1.logDebug)('Clusterer: post-Leiden greedy merge', {
+            beforeMerge: components.length,
+            maxClusters,
+        });
+        components = (0, leiden_1.greedyMerge)(graph, components, maxClusters);
+    }
+    // --- Recursive sub-splitting for large clusters ---
+    components = (0, leiden_1.recursiveSubSplit)(graph, components);
+    // --- Sort by size descending for deterministic output ---
+    components.sort((a, b) => b.length - a.length);
+    // --- Filter: size-1 communities go to unclustered if < MIN_SYMBOLS ---
+    const validComponents = [];
+    const unclusteredIndices = [];
+    for (const comp of components) {
+        if (comp.length === 1) {
+            const idx = comp[0];
+            const c = changes[idx];
+            if ((0, features_1.countChangedSymbols)(c) < features_1.MIN_SYMBOLS_FOR_SOLO_CLUSTER && !(0, features_1.hasNewNonTestFiles)(c)) {
+                unclusteredIndices.push(idx);
+                continue;
+            }
+        }
+        validComponents.push(comp);
+    }
+    // --- Build cluster objects ---
+    const clustered = new Set();
+    const clusters = [];
+    for (let i = 0; i < validComponents.length; i++) {
+        const comp = validComponents[i];
+        const clusterCommits = comp.map((idx) => {
+            clustered.add(idx);
+            return changes[idx];
+        });
+        // Compute primary files (appear in >50% of cluster commits)
+        const fileCounts = new Map();
+        const symbolCounts = new Map();
+        const allTimes = clusterCommits
+            .map((c) => c.timestamp)
+            .filter((t) => t > 0);
+        for (const c of clusterCommits) {
+            for (const fp of (0, features_1.collectFilePaths)(c)) {
+                fileCounts.set(fp, (fileCounts.get(fp) || 0) + 1);
+            }
+            for (const s of (0, features_1.collectSymbolNames)(c)) {
+                symbolCounts.set(s, (symbolCounts.get(s) || 0) + 1);
+            }
+        }
+        const half = clusterCommits.length / 2;
+        const primaryFiles = Array.from(fileCounts.entries())
+            .filter(([, count]) => count >= half)
+            .sort((a, b) => b[1] - a[1])
+            .map(([fp]) => fp);
+        const primarySymbols = Array.from(symbolCounts.entries())
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .map(([s]) => s);
+        // Build summary
+        const fileSummary = primaryFiles.length > 0
+            ? `changing ${primaryFiles.slice(0, 3).join(', ')}`
+            : '';
+        const summary = `${clusterCommits.length} commits ${fileSummary}`.trim();
+        clusters.push({
+            id: i,
+            commits: clusterCommits,
+            primaryFiles,
+            primarySymbols,
+            summary,
+            timeRange: {
+                start: allTimes.length > 0 ? Math.min(...allTimes) : 0,
+                end: allTimes.length > 0 ? Math.max(...allTimes) : 0,
+            },
+        });
+    }
+    // --- Unclustered commits ---
+    const unclustered = changes.filter((_, i) => !clustered.has(i));
+    (0, errors_1.logDebug)('Clusterer result', {
+        totalCommits: n,
+        clusterCount: clusters.length,
+        clusteredCommits: n - unclustered.length,
+        unclustered: unclustered.length,
+    });
+    return {
+        clusters,
+        unclustered,
+        stats: {
+            totalCommits: n,
+            clusteredCommits: n - unclustered.length,
+            clusterCount: clusters.length,
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/spec/mine/clustering/index.js.map

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

package/dist/spec/mine/clustering/leiden.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Leiden community detection on a weighted similarity graph — a generic
+ * graph-clustering implementation with no dependency on the commit domain.
+ *
+ * Replaces Louvain and connected-components (single-linkage) to avoid chaining
+ * all nodes into one giant cluster and to guarantee well-connected communities
+ * via the refinement phase. A resolution parameter γ is auto-tuned via
+ * multiplicative search so the output community count stays close to a target.
+ *
+ * @module spec/mine/clustering/leiden
+ */
+/**
+ * Weighted adjacency matrix: graph[i][j] = similarity score (0 means no edge).
+ * Always symmetric: graph[i][j] === graph[j][i].
+ */
+export type WeightedGraph = number[][];
+/**
+ * Core Leiden algorithm: iterative local-moving + refinement + aggregation.
+ *
+ * Unlike Louvain (which feeds the Phase-1 partition directly into aggregation),
+ * Leiden inserts a refinement step that splits each Phase-1 community into
+ * well-connected sub-communities. Only the refined partition is aggregated.
+ * This guarantees internally-connected communities and avoids the
+ * "disconnected community" defect of Louvain.
+ *
+ * @param graph  - Weighted undirected similarity graph.
+ * @param gamma  - Resolution parameter (default 1.0).
+ * @param depth  - Aggregation depth guard (internal use).
+ */
+export declare function leiden(graph: WeightedGraph, gamma: number, depth?: number): number[][];
+/**
+ * Recursively split large clusters by running Leiden on their sub-graphs.
+ *
+ * For each cluster with size > MIN_SUBSPLIT_SIZE, extracts its sub-graph,
+ * runs Leiden with auto-tuned γ (targeting up to min(5, floor(size/2))),
+ * and recursively splits further if sub-communities still have structure.
+ *
+ * Stop conditions:
+ *   - Cluster size ≤ MIN_SUBSPLIT_SIZE
+ *   - Sub-graph Leiden returns 1 community (no further structure)
+ *   - Max recursion depth reached (MAX_SUBSPLIT_DEPTH)
+ *
+ * @param graph       - Full original weighted graph.
+ * @param communities - Current partition (list of node-index arrays).
+ * @param depth       - Current recursion depth (internal).
+ * @returns Flat list of leaf-community node-index arrays.
+ */
+export declare function recursiveSubSplit(graph: WeightedGraph, communities: number[][], depth?: number): number[][];
+/**
+ * Adjust the resolution parameter γ so that Leiden produces approximately
+ * `targetClusters` communities.
+ *
+ * Uses multiplicative search: higher γ → more communities, lower γ → fewer.
+ */
+export declare function autoTuneResolution(graph: WeightedGraph, maxClusters: number): number[][];
+/**
+ * Greedily merge communities until count ≤ maxClusters, by repeatedly
+ * merging the pair with the highest average inter-community similarity.
+ */
+export declare function greedyMerge(graph: WeightedGraph, communities: number[][], maxClusters: number): number[][];
+//# sourceMappingURL=leiden.d.ts.map

package/dist/spec/mine/clustering/leiden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leiden.d.ts","sourceRoot":"","sources":["../../../../src/spec/mine/clustering/leiden.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,EAAE,EAAE,CAAC;AAoKvC;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CACpB,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAU,GAChB,MAAM,EAAE,EAAE,CAsGZ;AAqGD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,MAAM,EAAE,EAAE,EACvB,KAAK,GAAE,MAAU,GAChB,MAAM,EAAE,EAAE,CAiCZ;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,MAAM,GAClB,MAAM,EAAE,EAAE,CA2EZ;AAMD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,MAAM,EAAE,EAAE,EACvB,WAAW,EAAE,MAAM,GAClB,MAAM,EAAE,EAAE,CAmCZ"}