homegraph 1.2.0 → 1.5.0

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/progress-handler.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Progress handler factory for `spec mine`.
+ *
+ * Provides two rendering strategies for `MineProgressCallback`:
+ *
+ * - **bar** — ANSI-based single-line progress bar with phase label and
+ *   item-level detail.  Intended for interactive TTY sessions.
+ * - **verbose** — plain-text lines with elapsed timestamps.  Identical in
+ *   style to `createVerboseProgress()` used by the indexing pipeline.
+ *   Intended for `--verbose` mode and non-TTY (pipe) output.
+ *
+ * @module spec/mine/progress-handler
+ */
+import type { MineProgressCallback } from './progress';
+/**
+ * Create a progress handler for `spec mine`.
+ *
+ * @param mode - `'bar'` for ANSI progress bar (TTY), `'verbose'` for text lines.
+ * @returns A `MineProgressCallback` or `undefined` for silent mode.
+ */
+export declare function createMineProgressHandler(mode: 'bar' | 'verbose'): MineProgressCallback;
+//# sourceMappingURL=progress-handler.d.ts.map

package/dist/spec/mine/progress-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-handler.d.ts","sourceRoot":"","sources":["../../../src/spec/mine/progress-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAgB,oBAAoB,EAAE,MAAM,YAAY,CAAC;AA6FrE;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,KAAK,GAAG,SAAS,GACtB,oBAAoB,CAKtB"}

package/dist/spec/mine/progress-handler.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Progress handler factory for `spec mine`.
+ *
+ * Provides two rendering strategies for `MineProgressCallback`:
+ *
+ * - **bar** — ANSI-based single-line progress bar with phase label and
+ *   item-level detail.  Intended for interactive TTY sessions.
+ * - **verbose** — plain-text lines with elapsed timestamps.  Identical in
+ *   style to `createVerboseProgress()` used by the indexing pipeline.
+ *   Intended for `--verbose` mode and non-TTY (pipe) output.
+ *
+ * @module spec/mine/progress-handler
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMineProgressHandler = createMineProgressHandler;
+// ---------------------------------------------------------------------------
+// Bar mode
+// ---------------------------------------------------------------------------
+/** Width of the progress bar portion (excluding label and counters). */
+const BAR_WIDTH = 20;
+const PHASE_LABELS = {
+    scanning: 'Scanning commits  ',
+    clustering: 'Clustering        ',
+    generating: 'Generating specs  ',
+    persisting: 'Persisting to DB  ',
+    done: '                  ',
+};
+function createBarHandler() {
+    let lastPhase = '';
+    return (p) => {
+        if (p.phase === 'done') {
+            // Print a trailing newline so the last progress bar stays visible
+            // and subsequent CLI output (success/info lines) starts on a fresh line.
+            if (process.stdout.isTTY)
+                process.stdout.write('\n');
+            return;
+        }
+        if (p.phase !== lastPhase) {
+            lastPhase = p.phase;
+            // Print a newline when phase changes (previous bar stays visible briefly)
+            if (process.stdout.isTTY)
+                process.stdout.write('\n');
+        }
+        const label = PHASE_LABELS[p.phase] || p.phase;
+        const total = p.total > 0 ? p.total : 0;
+        const current = p.current;
+        let bar;
+        if (total === 0) {
+            // Indeterminate — spinner-like effect
+            bar = '—'.repeat(BAR_WIDTH);
+        }
+        else {
+            const filled = Math.round((current / total) * BAR_WIDTH);
+            bar = '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled);
+        }
+        const counter = total > 0 ? ` ${String(current).padStart(String(total).length, ' ')}/${total}` : '';
+        const msg = p.message ? `  ${p.message}` : '';
+        const line = `${label} [${bar}]${counter}${msg}`;
+        process.stdout.write(`\r\x1b[K${line}`);
+    };
+}
+// ---------------------------------------------------------------------------
+// Verbose mode
+// ---------------------------------------------------------------------------
+function createVerboseHandler() {
+    const startTime = Date.now();
+    let lastPhase = '';
+    let lastPct = -1;
+    return (p) => {
+        if (p.phase === 'done')
+            return;
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+        if (p.phase !== lastPhase) {
+            lastPhase = p.phase;
+            lastPct = -1;
+            console.log(`[${elapsed}s] Phase: ${p.phase}`);
+        }
+        if (p.total > 0) {
+            const pct = Math.floor((p.current / p.total) * 100);
+            if (pct >= lastPct + 5 || p.current === p.total) {
+                lastPct = pct;
+                const msg = p.message ? ` · ${p.message}` : '';
+                console.log(`[${elapsed}s]   ${p.current}/${p.total} (${pct}%)${msg}`);
+            }
+        }
+        else if (p.message) {
+            // Phase-level message without item counts (clustering, etc.)
+            console.log(`[${elapsed}s]   ${p.message}`);
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a progress handler for `spec mine`.
+ *
+ * @param mode - `'bar'` for ANSI progress bar (TTY), `'verbose'` for text lines.
+ * @returns A `MineProgressCallback` or `undefined` for silent mode.
+ */
+function createMineProgressHandler(mode) {
+    if (mode === 'bar' && process.stdout.isTTY) {
+        return createBarHandler();
+    }
+    return createVerboseHandler();
+}
+//# sourceMappingURL=progress-handler.js.map

package/dist/spec/mine/progress-handler.js.map

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

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

@@ -0,0 +1,23 @@
+/**
+ * Progress reporting callback type for the `spec mine` pipeline.
+ *
+ * Each phase callback reports current/total progress with an optional
+ * human-readable message. The callback is purely advisory — `onProgress`
+ * is always optional and a missing callback just means "no output."
+ *
+ * @module spec/mine/progress
+ */
+/** One progress tick from any phase of the pipeline. */
+export interface MineProgress {
+    /** Current pipeline phase. */
+    phase: 'scanning' | 'clustering' | 'generating' | 'persisting' | 'done';
+    /** Current item index (1-based).  0 means the phase just started. */
+    current: number;
+    /** Total items in this phase.  0 means the total is unknown / not meaningful. */
+    total: number;
+    /** Optional human-readable label (e.g. commit hash, specId). */
+    message?: string;
+}
+/** Callback signature for progress reporting. */
+export type MineProgressCallback = (progress: MineProgress) => void;
+//# sourceMappingURL=progress.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../src/spec/mine/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,KAAK,EAAE,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,MAAM,CAAC;IACxE,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,iDAAiD;AACjD,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC"}

package/dist/spec/mine/progress.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Progress reporting callback type for the `spec mine` pipeline.
+ *
+ * Each phase callback reports current/total progress with an optional
+ * human-readable message. The callback is purely advisory — `onProgress`
+ * is always optional and a missing callback just means "no output."
+ *
+ * @module spec/mine/progress
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=progress.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../../src/spec/mine/progress.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}

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"}