homegraph 1.4.1 → 1.5.1

package/dist/spec/mine/pipeline.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * Mine Pipeline — orchestrates the `spec mine` flow.
+ *
+ * Three-stage pipeline:
+ *   1. Scan commits (AST-level diff extraction)
+ *   2. Cluster commits (multi-signal graph clustering)
+ *   3. Generate specs (LLM-driven spec documents)
+ *
+ * Integrates with the existing meta.json anchor for incremental runs.
+ *
+ * @module spec/mine/pipeline
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMinePipeline = runMinePipeline;
+const path = __importStar(require("path"));
+const git_1 = require("../git");
+const factory_1 = require("../llm/factory");
+const utils_1 = require("../utils");
+const scanner_1 = require("./scanner");
+const clustering_1 = require("./clustering");
+const generator_1 = require("./generator");
+const errors_1 = require("../../errors");
+const persist_1 = require("./persist");
+// ---------------------------------------------------------------------------
+// Pipeline
+// ---------------------------------------------------------------------------
+/**
+ * Run the full reverse-spec pipeline.
+ *
+ * @param repoPath - Path to the git repository.
+ * @param config - Reverse pipeline configuration.
+ * @param llmConfig - LLM configuration (may be null when a coding agent
+ *   — Claude Code / Codex — is available, or when skipLlm is true).
+ * @param db - Optional SQLite database handle for persistence.
+ * @param onProgress - Optional progress callback for real-time feedback.
+ * @returns Pipeline result with stats.
+ */
+async function runMinePipeline(repoPath, config, llmConfig, db = null, onProgress) {
+    const errors = [];
+    // 1. Validate git repo
+    if (!(0, git_1.isGitRepo)(repoPath)) {
+        throw new Error(`Not a git repository: ${repoPath}`);
+    }
+    const headHash = (0, git_1.getHeadHash)(repoPath);
+    if (!headHash) {
+        throw new Error(`No HEAD commit found in ${repoPath}`);
+    }
+    // 2. Resolve commit range from meta.json
+    let fromHash = '';
+    const meta = (0, utils_1.readMeta)(repoPath);
+    if (meta?.currentCommitID) {
+        if ((0, git_1.isAncestor)(repoPath, meta.currentCommitID, headHash)) {
+            // Normal incremental case
+            fromHash = meta.currentCommitID;
+            (0, errors_1.logDebug)('Mine pipeline: incremental range', {
+                from: fromHash.slice(0, 7),
+                to: headHash.slice(0, 7),
+            });
+        }
+        else {
+            // Rebase detected — full scan
+            (0, errors_1.logWarn)('Mine pipeline: meta.json currentCommitID is not an ancestor of HEAD (possible rebase). Falling back to full scan.', {
+                metaCommit: meta.currentCommitID.slice(0, 7),
+                head: headHash.slice(0, 7),
+            });
+            fromHash = '';
+        }
+    }
+    else {
+        (0, errors_1.logDebug)('Mine pipeline: no meta.json anchor — full scan');
+    }
+    // 3. Scan commits (AST-level diff)
+    onProgress?.({ phase: 'scanning', current: 0, total: 0, message: 'Starting...' });
+    const changes = (0, scanner_1.scanCommits)(repoPath, fromHash, headHash, config.limit, onProgress);
+    if (changes.length === 0) {
+        onProgress?.({ phase: 'done', current: 1, total: 1 });
+        return {
+            commitsScanned: 0,
+            changesFound: 0,
+            clusters: 0,
+            specsGenerated: 0,
+            skippedClusters: 0,
+            specsWritten: 0,
+            commitsWritten: 0,
+            fragmentsWritten: 0,
+            relationsWritten: 0,
+            errors: ['No commits found in range.'],
+        };
+    }
+    const changesWithData = changes.filter((c) => c.fileChanges.length > 0);
+    if (changesWithData.length === 0) {
+        onProgress?.({ phase: 'done', current: 1, total: 1 });
+        return {
+            commitsScanned: changes.length,
+            changesFound: 0,
+            clusters: 0,
+            specsGenerated: 0,
+            skippedClusters: 0,
+            specsWritten: 0,
+            commitsWritten: 0,
+            fragmentsWritten: 0,
+            relationsWritten: 0,
+            errors: [`Scanned ${changes.length} commit(s) but none had structural changes.`],
+        };
+    }
+    (0, errors_1.logDebug)('Mine pipeline: scanning complete', {
+        totalCommits: changes.length,
+        commitsWithChanges: changesWithData.length,
+    });
+    // 4. Cluster commits (synchronous — one-shot; no per-item counting)
+    const clusterResult = (0, clustering_1.clusterCommits)(changesWithData, config.threshold, config.maxCluster);
+    onProgress?.({
+        phase: 'clustering',
+        current: 0,
+        total: 0,
+        message: `${changesWithData.length} commits → ${clusterResult.clusters.length} clusters`,
+    });
+    (0, errors_1.logDebug)('Mine pipeline: clustering complete', clusterResult.stats);
+    // 5. Generate specs (optional)
+    let specsGenerated = 0;
+    let skippedClusters = 0;
+    let specsWritten = 0;
+    let commitsWritten = 0;
+    let fragmentsWritten = 0;
+    let relationsWritten = 0;
+    let shouldAdvanceMeta = false;
+    const client = config.skipLlm ? undefined : (0, factory_1.createSpecLlmClient)(llmConfig);
+    if (!config.skipLlm && client) {
+        // Read custom template if provided
+        let templateContent;
+        if (config.template) {
+            try {
+                const fs = await Promise.resolve().then(() => __importStar(require('fs')));
+                templateContent = fs.readFileSync(path.resolve(config.template), 'utf-8');
+            }
+            catch (err) {
+                (0, errors_1.logWarn)('Failed to read template file — using built-in template', {
+                    template: config.template,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        const genResult = await (0, generator_1.generateSpecs)(clusterResult.clusters, client, config.outputDir, templateContent, onProgress);
+        specsGenerated = genResult.specs.length;
+        skippedClusters = genResult.skipped + genResult.errors;
+        if (genResult.errors > 0) {
+            errors.push(`${genResult.errors} LLM generation(s) failed.`);
+        }
+        // 6. Persist specs to knowledge graph
+        let persistFailed = false;
+        if (db && genResult.specs.length > 0) {
+            try {
+                const persistResult = (0, persist_1.persistToGraph)(db, repoPath, genResult.specs, clusterResult.clusters, config.outputDir, onProgress);
+                specsWritten = persistResult.specsWritten;
+                commitsWritten = persistResult.commitsWritten;
+                fragmentsWritten = persistResult.fragmentsWritten;
+                relationsWritten = persistResult.relationsWritten;
+                (0, errors_1.logDebug)('Mine pipeline: persisted to graph', { ...persistResult });
+            }
+            catch (err) {
+                persistFailed = true;
+                errors.push(`Failed to persist specs to graph: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Advance meta.json only when LLM ran, persistence did not fail,
+        // and at least one spec document was generated.
+        if (!persistFailed && genResult.specs.length > 0) {
+            shouldAdvanceMeta = true;
+        }
+    }
+    else if (!config.skipLlm && !client) {
+        errors.push('LLM generation skipped — no coding agent (Claude Code / Codex) detected and no LLM configuration found. Set up llm in configs.json or use --skip-llm.');
+    }
+    // 7. Update meta.json — only advance when specs were successfully generated
+    //    and persisted. With skipLlm or no LLM config, skip advancing so the
+    //    same commits are re-scanned when LLM is available.
+    if (shouldAdvanceMeta) {
+        try {
+            (0, utils_1.writeMeta)(repoPath, config.outputDir, headHash);
+            (0, errors_1.logDebug)('Mine pipeline: updated meta.json', {
+                currentCommitID: headHash.slice(0, 7),
+            });
+        }
+        catch (err) {
+            errors.push(`Failed to update meta.json: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    onProgress?.({ phase: 'done', current: 1, total: 1 });
+    return {
+        commitsScanned: changes.length,
+        changesFound: changesWithData.length,
+        clusters: clusterResult.clusters.length,
+        specsGenerated,
+        skippedClusters,
+        specsWritten,
+        commitsWritten,
+        fragmentsWritten,
+        relationsWritten,
+        errors,
+    };
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/spec/mine/pipeline.js.map

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

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

@@ -0,0 +1,59 @@
+/**
+ * Mining Git Scanner — AST-level diff parsing for the `spec mine` pipeline.
+ *
+ * For each commit in a range this module extracts changed files, AST-parses
+ * both the old and new versions, and computes symbol-level (structural) diffs.
+ * It reuses the existing `extractFromSource` and the git utilities from
+ * `spec/git`.
+ *
+ * @module spec/mine/scanner
+ */
+import { NodeKind, Language } from '../../types';
+import type { ProgressCallback } from '../ui';
+/** A single symbol that changed (added, removed, or modified) in a commit. */
+export interface ChangedSymbol {
+    kind: NodeKind;
+    name: string;
+    qualifiedName: string;
+    startLine: number;
+    endLine: number;
+    /** Structural fingerprint for detecting content changes even when line ranges are unchanged. */
+    fingerprint: string;
+    /** Function/method signature (e.g. "authenticate(token: string): Promise<User>"). */
+    signature?: string;
+    /** Visibility modifier. */
+    visibility?: 'public' | 'private' | 'protected' | 'internal';
+}
+/** AST-level structural changes for one file in a commit. */
+export interface FileChange {
+    filePath: string;
+    language: Language;
+    addedSymbols: ChangedSymbol[];
+    removedSymbols: ChangedSymbol[];
+    modifiedSymbols: {
+        old: ChangedSymbol;
+        new: ChangedSymbol;
+    }[];
+    /** True when the file did not exist in the parent commit. */
+    isNewFile?: boolean;
+}
+/** Aggregated AST change data for a single commit. */
+export interface CommitChange {
+    commitHash: string;
+    commitMessage: string;
+    author: string;
+    timestamp: number;
+    fileChanges: FileChange[];
+}
+/**
+ * Scan commits in a range and produce AST-level structural change data.
+ *
+ * @param repoPath - Path to the git repository.
+ * @param fromHash - Starting commit hash (exclusive). Use empty string for root.
+ * @param toHash - Ending commit hash (inclusive), typically 'HEAD'.
+ * @param limit - If set, only the most recent N commits are processed.
+ * @param onProgress - Optional progress callback (called per commit).
+ * @returns Aggregated AST change data for each commit.
+ */
+export declare function scanCommits(repoPath: string, fromHash: string, toHash: string, limit?: number, onProgress?: ProgressCallback): CommitChange[];
+//# sourceMappingURL=scanner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../../src/spec/mine/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAaH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAA0B,MAAM,aAAa,CAAC;AAGzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAM9C,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,WAAW,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;CAC9D;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,aAAa,EAAE,CAAC;IAC9B,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,eAAe,EAAE;QAAE,GAAG,EAAE,aAAa,CAAC;QAAC,GAAG,EAAE,aAAa,CAAA;KAAE,EAAE,CAAC;IAC9D,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAsPD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,gBAAgB,GAC5B,YAAY,EAAE,CA6JhB"}