homegraph 1.2.0 → 1.5.0

package/dist/spec/llm/prompts.js

@@ -1,75 +1,125 @@
 "use strict";
 /**
- * LLM prompt templates for spec self-evolution.
- *
- * Extracted from logic-checker.ts and spec-rewriter.ts so evolve modules
- * don't contain prompt strings directly.
+ * LLM prompt templates for the spec pipelines — spec self-evolution
+ * (cluster evaluation) and spec mining (spec generation from clusters).
  *
  * @module spec/llm/prompts
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SPEC_EVALUATION_SYSTEM_PROMPT = exports.LOGIC_CHECK_SYSTEM_PROMPT = void 0;
-exports.buildLogicCheckUserPrompt = buildLogicCheckUserPrompt;
-exports.buildSpecEvaluationUserPrompt = buildSpecEvaluationUserPrompt;
+exports.SPEC_EVALUATION_CLUSTER_SYSTEM_PROMPT = exports.SPEC_GENERATION_SYSTEM_PROMPT = exports.DEFAULT_SPEC_TEMPLATE = void 0;
+exports.buildClusterSpecEvaluationUserPrompt = buildClusterSpecEvaluationUserPrompt;
+const utils_1 = require("../utils");
 // =============================================================================
-// Logic check prompt
+// Spec generation prompt + template (mine pipeline)
 // =============================================================================
-exports.LOGIC_CHECK_SYSTEM_PROMPT = `You are a code review assistant. Your task is to determine whether a git commit represents a business-logic change (as opposed to purely cosmetic, formatting, comment-only, or test-only changes).
+/** Default markdown template for generated spec documents. */
+exports.DEFAULT_SPEC_TEMPLATE = `# Spec: {{title}}
 
-A business-logic change includes:
-- Changes to algorithms, data structures, or control flow
-- Changes to business rules, validation logic, or domain behavior
-- Adding or removing functionality
-- Bug fixes that change behavior
+## Summary
+{{summary}}
 
-NOT business-logic changes:
-- Whitespace, formatting, or code style changes
-- Comment-only changes
-- Test-only changes (adding tests without changing production code)
-- Configuration changes that don't alter behavior
-- Package/dependency version bumps
+## Motivation
+{{motivation}}
 
-Respond with a JSON object:
-{
-  "is_logic_change": true/false,
-  "reason": "Brief explanation of why this is or is not a logic change"
-}`;
-function buildLogicCheckUserPrompt(commitMessage, truncatedDiff) {
-    return `Analyze this commit:
+## Specification
 
-Commit Message: ${commitMessage}
+### Functional Requirements
+{{functional_requirements}}
 
-Diff:
-${truncatedDiff}`;
-}
+### Acceptance Criteria (EARS format)
+{{acceptance_criteria}}
+
+## Implementation Notes
+
+### Related Commits
+{{commit_list}}
+
+### Affected Files
+{{file_list}}
+
+### Key Symbols
+{{symbol_list}}
+`;
+/** System prompt for LLM spec generation from a commit cluster. */
+exports.SPEC_GENERATION_SYSTEM_PROMPT = `You are a technical documentation writer specializing in software design specifications. Given a cluster of related Git commits, generate a design specification in markdown format.
+
+Guidelines:
+- Focus on WHAT was built, not HOW it was implemented
+- Use EARS (Easy Approach to Requirements Syntax) for acceptance criteria
+- Be specific — reference real symbols, files, and commit messages
+- Keep the spec concise but complete
+- Output ONLY the spec document, no preamble or commentary
+
+Output format — fill in the template exactly. Replace {{placeholders}} with real content. Do NOT include the placeholder braces in your output.`;
 // =============================================================================
-// Spec evaluation prompt
+// Cluster spec evaluation prompt
 // =============================================================================
-exports.SPEC_EVALUATION_SYSTEM_PROMPT = `You are a technical documentation maintainer. Your task is to evaluate whether a git commit requires updating a software design specification (plan.md).
+/** Maximum characters for the current spec content in the user prompt
+ *  (~16K tokens @ ~0.25 token/char). Exceedingly large spec documents are
+ *  truncated to prevent context-window overflow. */
+const MAX_SPEC_CONTENT_CHARS = 64000;
+exports.SPEC_EVALUATION_CLUSTER_SYSTEM_PROMPT = `You are a technical documentation maintainer. Your task is to evaluate whether a GROUP of related git commits requires updating a software design specification.
 
-Given the current plan content, the commit message, and the code diff, determine:
-1. Whether the plan needs to be updated (UPDATE), deprecated (DEPRECATE), or left unchanged (UNCHANGED).
-2. If UPDATE: provide the new title, subtitles (as an array of heading-preview strings), and full rewritten plan_content.
-3. If DEPRECATE: provide a brief explanation in the plan_content field.
+Given the current content and a summary of multiple commits that affect this spec, determine:
+1. Whether the spec needs to be updated (UPDATE), deprecated (DEPRECATE), or left unchanged (UNCHANGED).
+2. If UPDATE: provide the new title, subtitles (as an array of heading-preview strings), and full rewritten spec_content that incorporates the changes from all commits.
+3. If DEPRECATE: provide a brief explanation in the spec_content field.
+
+Key considerations for batch evaluation:
+- Multiple commits may partially overlap in their changes — synthesize the combined impact.
+- Some commits may be bug fixes that revert earlier changes — look for the net effect.
+- If the combined changes fundamentally alter the spec's scope, prefer DEPRECATE over UPDATE.
 
 Response format (JSON):
 {
   "action": "UPDATE" | "DEPRECATE" | "UNCHANGED",
   "title": "New spec title (for UPDATE)",
   "subtitles": ["heading1 → heading2 - preview", ...],
-  "plan_content": "Full rewritten markdown content (for UPDATE) or deprecation reason (for DEPRECATE)"
+  "spec_content": "Full rewritten markdown content (for UPDATE) or deprecation reason (for DEPRECATE)"
 }`;
-function buildSpecEvaluationUserPrompt(planContent, commitMessage, truncatedDiff, scheduleNextSpecs) {
-    const scheduleStr = scheduleNextSpecs.length > 0 ? scheduleNextSpecs.join(', ') : 'none';
-    return `Current Plan Content:
-${planContent}
-
-Commit Message:
-${commitMessage}
-
-Code Diff:
-${truncatedDiff}
-
-Scheduled specs to be processed next (for context): ${scheduleStr}`;
+/**
+ * Build the user prompt for cluster-based spec evaluation.
+ *
+ * Presents:
+ * 1. The current spec content.
+ * 2. A cluster overview (commit count, primary files).
+ * 3. Per-commit summaries (short hash, message, changed files, truncated diff).
+ *
+ * The prompt is designed to fit within a reasonable token budget for a
+ * single LLM call even with 5-10 commits in the cluster.
+ *
+ * @param specContent    - Full current spec.md content.
+ * @param clusterContext - Pre-built cluster context from buildClusterContext.
+ * @returns Formatted user prompt string.
+ */
+function buildClusterSpecEvaluationUserPrompt(specContent, clusterContext) {
+    const parts = [];
+    // 1. Current spec
+    const truncatedSpec = (0, utils_1.truncateText)(specContent, MAX_SPEC_CONTENT_CHARS);
+    parts.push('## Current Spec Content');
+    parts.push('');
+    parts.push(truncatedSpec);
+    parts.push('');
+    // 2. Cluster overview
+    parts.push('## Commit Cluster');
+    parts.push('');
+    parts.push(`- **Commits**: ${clusterContext.commitCount}`);
+    parts.push(`- **Primary files**: ${clusterContext.primaryFiles.join(', ') || '(none)'}`);
+    parts.push('');
+    // 3. Per-commit summaries
+    parts.push('## Commit Summaries');
+    parts.push('');
+    for (const cs of clusterContext.commitSummaries) {
+        parts.push(`### ${cs.shortHash} — ${cs.message}`);
+        parts.push(`Files: ${cs.changedFiles.join(', ')}`);
+        if (cs.truncatedDiff && cs.truncatedDiff.length > 0) {
+            parts.push('');
+            parts.push('```diff');
+            parts.push(cs.truncatedDiff);
+            parts.push('```');
+        }
+        parts.push('');
+    }
+    return parts.join('\n');
 }
 //# sourceMappingURL=prompts.js.map

package/dist/spec/llm/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/spec/llm/prompts.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AA2BH,8DAUC;AAqBD,sEAmBC;AA3ED,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEnE,QAAA,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;EAmBvC,CAAC;AAEH,SAAgB,yBAAyB,CACvC,aAAqB,EACrB,aAAqB;IAErB,OAAO;;kBAES,aAAa;;;EAG7B,aAAa,EAAE,CAAC;AAClB,CAAC;AAED,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEnE,QAAA,6BAA6B,GAAG;;;;;;;;;;;;;EAa3C,CAAC;AAEH,SAAgB,6BAA6B,CAC3C,WAAmB,EACnB,aAAqB,EACrB,aAAqB,EACrB,iBAA2B;IAE3B,MAAM,WAAW,GACf,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAEvE,OAAO;EACP,WAAW;;;EAGX,aAAa;;;EAGb,aAAa;;sDAEuC,WAAW,EAAE,CAAC;AACpE,CAAC"}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/spec/llm/prompts.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AA8FH,oFAsCC;AAjID,oCAAwC;AAExC,gFAAgF;AAChF,oDAAoD;AACpD,gFAAgF;AAEhF,8DAA8D;AACjD,QAAA,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BpC,CAAC;AAEF,mEAAmE;AACtD,QAAA,6BAA6B,GAAG;;;;;;;;;gJASmG,CAAC;AAEjJ,gFAAgF;AAChF,iCAAiC;AACjC,gFAAgF;AAEhF;;oDAEoD;AACpD,MAAM,sBAAsB,GAAG,KAAK,CAAC;AAExB,QAAA,qCAAqC,GAAG;;;;;;;;;;;;;;;;;;EAkBnD,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,SAAgB,oCAAoC,CAClD,WAAmB,EACnB,cAA8B;IAE9B,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,kBAAkB;IAClB,MAAM,aAAa,GAAG,IAAA,oBAAY,EAAC,WAAW,EAAE,sBAAsB,CAAC,CAAC;IACxE,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IACtC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,sBAAsB;IACtB,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAChC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,kBAAkB,cAAc,CAAC,WAAW,EAAE,CAAC,CAAC;IAC3D,KAAK,CAAC,IAAI,CACR,wBAAwB,cAAc,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,CAC7E,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,0BAA0B;IAC1B,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAClC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,MAAM,EAAE,IAAI,cAAc,CAAC,eAAe,EAAE,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QAClD,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnD,IAAI,EAAE,CAAC,aAAa,IAAI,EAAE,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/spec/llm/retry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * LLM retry helper — error classification and delay calculation.
+ *
+ * OpenAI SDK v4 throws typed `APIError` subclasses. This module classifies
+ * them as retryable (transient) or terminal (bad request, auth failure, etc.)
+ * and computes exponential-backoff delays with jitter and Retry-After support.
+ *
+ * @module spec/llm/retry
+ */
+export interface RetryDecision {
+    /** Whether the error is safe to retry. */
+    retryable: boolean;
+    /**
+     * Recommended delay in milliseconds (from Retry-After header, if present).
+     * `undefined` means the caller should calculate backoff.
+     */
+    retryAfterMs?: number;
+}
+/**
+ * Classify an error thrown by the OpenAI SDK as retryable or terminal.
+ *
+ * Classification rules (first match wins):
+ *
+ * 1. Non-`Error` throwables → NOT retryable (safety).
+ * 2. `RateLimitError` (429) → RETRYABLE; parse Retry-After if available.
+ * 3. `InternalServerError` (500) → RETRYABLE.
+ * 4. Other `APIError` subclasses with status in `RETRYABLE_STATUSES` →
+ *    RETRYABLE.
+ * 5. `APIConnectionError` / `APIConnectionTimeoutError` → RETRYABLE.
+ * 6. Generic `Error` with `.code` in `RETRYABLE_CODES` → RETRYABLE.
+ * 7. Everything else → NOT retryable (conservative).
+ */
+export declare function classifyError(err: unknown): RetryDecision;
+/**
+ * Compute the delay before the next retry attempt.
+ *
+ * Strategy:
+ * 1. If `retryAfterMs` is available from the server (429 Retry-After), use it
+ *    as a minimum, then add jitter up to 25% of the computed backoff.
+ * 2. Otherwise: exponential backoff = `baseDelay * 2^attempt` with full-range
+ *    random jitter (`random(0, backoff)`).
+ * 3. Cap at `maxDelay`.
+ *
+ * @param retryAfterMs  - Server-suggested delay from Retry-After (optional).
+ * @param baseDelay     - Base delay in ms for backoff calculation.
+ * @param maxDelay      - Hard upper bound in ms.
+ * @param attempt       - Zero-based retry attempt index.
+ * @returns Delay in milliseconds (integer).
+ */
+export declare function computeDelay(retryAfterMs: number | undefined, baseDelay: number, maxDelay: number, attempt: number): number;
+/** Promise-based sleep. */
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/spec/llm/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/spec/llm/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAoBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAwCzD;AA0CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,MAAM,CAiBR;AAMD,2BAA2B;AAC3B,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/spec/llm/retry.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * LLM retry helper — error classification and delay calculation.
+ *
+ * OpenAI SDK v4 throws typed `APIError` subclasses. This module classifies
+ * them as retryable (transient) or terminal (bad request, auth failure, etc.)
+ * and computes exponential-backoff delays with jitter and Retry-After support.
+ *
+ * @module spec/llm/retry
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyError = classifyError;
+exports.computeDelay = computeDelay;
+exports.sleep = sleep;
+const openai_1 = __importDefault(require("openai"));
+// ---------------------------------------------------------------------------
+// Error classification
+// ---------------------------------------------------------------------------
+/** HTTP status codes that indicate a transient server error. */
+const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+/** Node.js error codes that indicate a transient network failure. */
+const RETRYABLE_CODES = new Set([
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ECONNREFUSED',
+    'ENOTFOUND',
+    'EPIPE',
+    'EAI_AGAIN',
+    'ERR_SOCKET_CONNECTION_TIMEOUT',
+]);
+/**
+ * Classify an error thrown by the OpenAI SDK as retryable or terminal.
+ *
+ * Classification rules (first match wins):
+ *
+ * 1. Non-`Error` throwables → NOT retryable (safety).
+ * 2. `RateLimitError` (429) → RETRYABLE; parse Retry-After if available.
+ * 3. `InternalServerError` (500) → RETRYABLE.
+ * 4. Other `APIError` subclasses with status in `RETRYABLE_STATUSES` →
+ *    RETRYABLE.
+ * 5. `APIConnectionError` / `APIConnectionTimeoutError` → RETRYABLE.
+ * 6. Generic `Error` with `.code` in `RETRYABLE_CODES` → RETRYABLE.
+ * 7. Everything else → NOT retryable (conservative).
+ */
+function classifyError(err) {
+    if (!(err instanceof Error)) {
+        return { retryable: false };
+    }
+    // 1. RateLimitError (429)
+    if (err instanceof openai_1.default.RateLimitError) {
+        const retryAfterMs = parseRetryAfter(err.headers);
+        return { retryable: true, retryAfterMs };
+    }
+    // 2. InternalServerError (500)
+    if (err instanceof openai_1.default.InternalServerError) {
+        return { retryable: true };
+    }
+    // 3. Other APIError with known transient status
+    if (err instanceof openai_1.default.APIError) {
+        if (err.status !== undefined && RETRYABLE_STATUSES.has(err.status)) {
+            return { retryable: true };
+        }
+        // Explicit client errors (400, 401, 403, 404, 409, 422, etc.) → terminal
+        return { retryable: false };
+    }
+    // 4. Connection-level errors
+    if (err instanceof openai_1.default.APIConnectionError ||
+        err instanceof openai_1.default.APIConnectionTimeoutError) {
+        return { retryable: true };
+    }
+    // 5. Generic Node.js network errors
+    if (RETRYABLE_CODES.has(err.code ?? '')) {
+        return { retryable: true };
+    }
+    // 6. Everything else — don't guess, just fail
+    return { retryable: false };
+}
+// ---------------------------------------------------------------------------
+// Retry-After parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse a `Retry-After` header value to milliseconds.
+ *
+ * Supports both delta-seconds (`"5"`) and HTTP-date (`"Wed, 21 Oct 2015 ..."`).
+ * Returns `undefined` if the header is missing, unparseable, or unacceptably
+ * large (> 5 minutes to avoid hiding a systemic outage).
+ */
+function parseRetryAfter(headers) {
+    if (!headers)
+        return undefined;
+    const raw = headers['retry-after'];
+    if (!raw || typeof raw !== 'string')
+        return undefined;
+    // Delta-seconds: "5" or "5.5"
+    const delta = Number(raw);
+    if (!isNaN(delta) && delta > 0) {
+        const ms = Math.round(delta * 1000);
+        return ms > 300_000 ? undefined : ms; // cap at 5 min
+    }
+    // HTTP-date
+    const date = new Date(raw).getTime();
+    if (!isNaN(date)) {
+        const ms = Math.max(0, date - Date.now());
+        return ms > 300_000 ? undefined : ms;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Delay computation
+// ---------------------------------------------------------------------------
+/**
+ * Compute the delay before the next retry attempt.
+ *
+ * Strategy:
+ * 1. If `retryAfterMs` is available from the server (429 Retry-After), use it
+ *    as a minimum, then add jitter up to 25% of the computed backoff.
+ * 2. Otherwise: exponential backoff = `baseDelay * 2^attempt` with full-range
+ *    random jitter (`random(0, backoff)`).
+ * 3. Cap at `maxDelay`.
+ *
+ * @param retryAfterMs  - Server-suggested delay from Retry-After (optional).
+ * @param baseDelay     - Base delay in ms for backoff calculation.
+ * @param maxDelay      - Hard upper bound in ms.
+ * @param attempt       - Zero-based retry attempt index.
+ * @returns Delay in milliseconds (integer).
+ */
+function computeDelay(retryAfterMs, baseDelay, maxDelay, attempt) {
+    const backoff = baseDelay * Math.pow(2, attempt);
+    let delay;
+    if (retryAfterMs !== undefined && retryAfterMs > 0) {
+        // Use Retry-After as floor, add up to 25% jitter
+        const jitter = Math.random() * Math.min(backoff * 0.25, 5000);
+        delay = retryAfterMs + jitter;
+    }
+    else {
+        // Full exponential backoff with jitter
+        delay = Math.random() * backoff;
+    }
+    // Clamp
+    delay = Math.max(0, Math.min(delay, maxDelay));
+    return Math.round(delay);
+}
+// ---------------------------------------------------------------------------
+// Sleep
+// ---------------------------------------------------------------------------
+/** Promise-based sleep. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=retry.js.map

package/dist/spec/llm/retry.js.map

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

package/dist/spec/mine/clusterer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ *
+ * Algorithm: Leiden community detection on a weighted similarity graph.
+ * Replaces Louvain and connected-components (single-linkage) to avoid chaining
+ * all commits 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 maxClusters.
+ *
+ * @module spec/mine/clusterer
+ */
+import { CommitChange } from './scanner';
+/** A cluster of semantically-related commits. */
+export interface CommitCluster {
+    id: number;
+    commits: CommitChange[];
+    primaryFiles: string[];
+    primarySymbols: string[];
+    summary: string;
+    timeRange: {
+        start: number;
+        end: number;
+    };
+}
+/** Full clustering result including unclustered outliers and stats. */
+export interface ClusterResult {
+    clusters: CommitCluster[];
+    unclustered: CommitChange[];
+    stats: {
+        totalCommits: number;
+        clusteredCommits: number;
+        clusterCount: number;
+    };
+}
+/**
+ * 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.
+ */
+export declare function clusterCommits(changes: CommitChange[], threshold: number, maxClusters: number): ClusterResult;
+//# sourceMappingURL=clusterer.d.ts.map

package/dist/spec/mine/clusterer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clusterer.d.ts","sourceRoot":"","sources":["../../../src/spec/mine/clusterer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAQzC,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,WAAW,EAAE,YAAY,EAAE,CAAC;IAC5B,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAs1BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,EAAE,EACvB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,aAAa,CA0Mf"}