homegraph 1.2.0 → 1.5.0

package/dist/spec/mine/scanner.js

@@ -0,0 +1,383 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanCommits = scanCommits;
+const child_process_1 = require("child_process");
+const git_1 = require("../git");
+const diff_parser_1 = require("../build/diff-parser");
+const tree_sitter_1 = require("../../extraction/tree-sitter");
+const grammars_1 = require("../../extraction/grammars");
+const errors_1 = require("../../errors");
+const query_utils_1 = require("../../search/query-utils");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Retrieve file content at a specific commit using `git show <hash>:<path>`.
+ * Returns null when the file did not exist at that commit.
+ */
+function getFileAtCommit(repoPath, commitHash, filePath) {
+    try {
+        return (0, child_process_1.execFileSync)('git', ['show', `${commitHash}:${filePath}`], (0, git_1.gitExecOptions)(repoPath));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check whether a file can be structurally diffed.
+ *
+ * Delegates to the grammar system's `detectLanguage` + `isLanguageSupported`
+ * so the supported language set is always aligned — any language the grammar
+ * system supports is automatically supported here.
+ */
+function isDiffableFile(filePath) {
+    return (0, grammars_1.isLanguageSupported)((0, grammars_1.detectLanguage)(filePath));
+}
+/**
+ * Compute a structural fingerprint from key AST-level properties.
+ * Captures signature, docstring, visibility, decorators, type parameters,
+ * and async/static/abstract modifiers — so content changes are detected
+ * even when line ranges happen to stay the same.
+ */
+function computeFingerprint(node) {
+    const parts = [
+        node.kind,
+        node.signature ?? '',
+        node.docstring ?? '',
+        node.visibility ?? '',
+        node.isExported ? 'exported' : '',
+        node.isAsync ? 'async' : '',
+        node.isStatic ? 'static' : '',
+        node.isAbstract ? 'abstract' : '',
+        (node.decorators ?? []).join(','),
+        (node.typeParameters ?? []).join(','),
+        node.returnType ?? '',
+    ];
+    return parts.join('|');
+}
+/**
+ * Convert an ExtractionResult node to a simplified ChangedSymbol.
+ */
+function nodeToSymbol(node) {
+    return {
+        kind: node.kind,
+        name: node.name,
+        qualifiedName: node.qualifiedName,
+        startLine: node.startLine,
+        endLine: node.endLine,
+        fingerprint: computeFingerprint(node),
+        signature: node.signature,
+        visibility: node.visibility,
+    };
+}
+/**
+ * Compare two sets of symbols (from old and new file versions) and produce
+ * added / removed / modified lists.
+ *
+ * Uses two-phase matching:
+ * 1. Exact match on qualifiedName + startLine — handles overloads and
+ *    symbols that haven't moved.
+ * 2. For unmatched symbols, match by qualifiedName alone. When exactly one
+ *    old and one new symbol share a qualifiedName they are treated as the
+ *    same symbol that relocated (modified).  N:M pairs are treated as
+ *    genuine additions / removals (e.g. multiple overloads added / removed).
+ */
+function compareSymbolSets(oldSymbols, newSymbols) {
+    // Phase 1: Exact match by qualifiedName + startLine.
+    const oldMap = new Map();
+    for (const s of oldSymbols)
+        oldMap.set(`${s.qualifiedName}:${s.startLine}`, s);
+    const newMap = new Map();
+    for (const s of newSymbols)
+        newMap.set(`${s.qualifiedName}:${s.startLine}`, s);
+    const added = [];
+    const removed = [];
+    const modified = [];
+    const matchedOldKeys = new Set();
+    for (const [key, newSym] of newMap) {
+        const oldSym = oldMap.get(key);
+        if (oldSym) {
+            matchedOldKeys.add(key);
+            if (oldSym.endLine !== newSym.endLine ||
+                oldSym.fingerprint !== newSym.fingerprint) {
+                modified.push({ old: oldSym, new: newSym });
+            }
+        }
+    }
+    // Phase 2: Handle relocated symbols (same qualifiedName, different startLine).
+    const unmatchedOld = [];
+    for (const [key, sym] of oldMap) {
+        if (!matchedOldKeys.has(key))
+            unmatchedOld.push(sym);
+    }
+    const unmatchedNew = [];
+    for (const [key, sym] of newMap) {
+        if (!oldMap.has(key))
+            unmatchedNew.push(sym);
+    }
+    // Group unmatched by qualifiedName
+    const oldByName = new Map();
+    for (const s of unmatchedOld) {
+        const arr = oldByName.get(s.qualifiedName);
+        if (arr)
+            arr.push(s);
+        else
+            oldByName.set(s.qualifiedName, [s]);
+    }
+    const newByName = new Map();
+    for (const s of unmatchedNew) {
+        const arr = newByName.get(s.qualifiedName);
+        if (arr)
+            arr.push(s);
+        else
+            newByName.set(s.qualifiedName, [s]);
+    }
+    // 1:1 pairs → relocated (modified). N:M → genuine add/remove.
+    for (const [qname, oldList] of oldByName) {
+        const newList = newByName.get(qname);
+        if (newList && oldList.length === 1 && newList.length === 1) {
+            modified.push({ old: oldList[0], new: newList[0] });
+        }
+        else {
+            for (const s of oldList)
+                removed.push(s);
+        }
+    }
+    // Remaining new symbols are genuine additions
+    for (const [qname, newList] of newByName) {
+        const oldList = oldByName.get(qname);
+        if (!oldList || oldList.length !== 1 || newList.length !== 1) {
+            for (const s of newList)
+                added.push(s);
+        }
+    }
+    return { added, removed, modified };
+}
+/**
+ * Node kinds that carry structural design intent and are tracked as
+ * significant changes during commit scanning.
+ *
+ * - OOP/data containers: class, struct, trait, interface, protocol
+ * - Behaviour: function, method, component
+ * - Type system: type_alias, enum
+ * - Data: variable, constant
+ * - Organisation: namespace, module
+ * - Web API surface: route
+ */
+const SIGNIFICANT_KINDS = new Set([
+    'function', 'class', 'method', 'interface', 'type_alias',
+    'struct', 'trait', 'protocol', 'route', 'module',
+    'variable', 'constant', 'enum', 'component', 'namespace',
+]);
+function extractSignificantSymbols(result) {
+    const symbols = [];
+    for (const node of result.nodes) {
+        if (SIGNIFICANT_KINDS.has(node.kind)) {
+            symbols.push(nodeToSymbol(node));
+        }
+    }
+    return symbols;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Conventional commit prefix regex.
+ * Matches: type[(scope)][!]: description
+ * Kept groups: feat, fix, refactor, chore, docs, test, style, build, ci, perf, revert
+ */
+const CONVENTIONAL_PREFIX = /^(feat|fix|refactor|chore|docs|test|style|build|ci|perf|revert)(?:\([^)]*\))?[!]?:\s/;
+/** Conventional commit types that involve source-code structural changes
+ *  and may carry design intent worth documenting as a spec. */
+const DESIGN_RELEVANT_TYPES = new Set([
+    'feat',
+    'fix',
+    'refactor',
+    'perf',
+]);
+/**
+ * Git-generated mechanical-commit prefixes that carry no design intent.
+ *
+ * - `Revert "..."` — `git revert` undo commits
+ * - `Reapply "..."` — cherry-pick re-application of a previously reverted commit
+ */
+const MECHANICAL_COMMIT_PREFIX = /^(Revert|Reapply)\s+"/;
+/**
+ * Determine whether a commit message represents a design-relevant change.
+ *
+ * Filtered out:
+ * - Git-generated mechanical commits (Revert / Reapply).
+ * - Conventional-commit types that rarely introduce new symbols or material
+ *   design intent: chore, docs, test, style, build, ci, revert.
+ *
+ * Kept:
+ * - Conventional-commit types with structural source-code impact:
+ *   feat, fix, refactor, perf.
+ * - Non-conventional messages (no prefix match) — conservatively treated as
+ *   unstructured feature work.
+ */
+function isDesignRelevant(message) {
+    // Git mechanical commits (Revert / Reapply) — no design intent
+    if (MECHANICAL_COMMIT_PREFIX.test(message))
+        return false;
+    const m = message.match(CONVENTIONAL_PREFIX);
+    if (!m)
+        return true; // Non-standard format — keep
+    return DESIGN_RELEVANT_TYPES.has(m[1]);
+}
+/**
+ * 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.
+ */
+function scanCommits(repoPath, fromHash, toHash, limit, onProgress) {
+    let commits;
+    if (fromHash) {
+        commits = (0, git_1.getCommitRange)(repoPath, fromHash, toHash);
+    }
+    else {
+        // No anchor — get all commits reachable from toHash.
+        commits = (0, git_1.getCommitsUpTo)(repoPath, toHash);
+    }
+    if (commits.length === 0)
+        return [];
+    // Apply limit — take most recent commits
+    if (limit !== undefined && limit > 0 && commits.length > limit) {
+        commits = commits.slice(commits.length - limit);
+    }
+    // Filter to design-relevant commits (feat / fix / refactor / perf) for
+    // conventional-commit messages. Non-conventional messages are kept.
+    const before = commits.length;
+    commits = commits.filter((c) => isDesignRelevant(c.message));
+    const skipped = before - commits.length;
+    if (skipped > 0) {
+        (0, errors_1.logDebug)('Mine scan: filtered non-design commits', {
+            kept: commits.length,
+            skipped,
+        });
+    }
+    const changes = [];
+    let parseErrorCount = 0;
+    const totalCommits = commits.length;
+    for (let ci = 0; ci < commits.length; ci++) {
+        const commit = commits[ci];
+        onProgress?.({
+            phase: 'scanning',
+            current: ci + 1,
+            total: totalCommits,
+            message: `${commit.hash.slice(0, 7)} ${commit.message.slice(0, 30)}`,
+        });
+        (0, errors_1.logDebug)('Mine scan: processing commit', {
+            hash: commit.hash.slice(0, 7),
+            message: commit.message,
+        });
+        const parents = (0, git_1.getParentHashes)(repoPath, commit.hash);
+        const parentHashes = parents.length > 0 ? parents : [null];
+        // Collect file changes from all parents, deduplicating by file path.
+        // Each file uses the first parent that includes it for old-content retrieval.
+        const seenFiles = new Set();
+        const fileChanges = [];
+        for (const parentHash of parentHashes) {
+            let diff;
+            try {
+                if (parentHash) {
+                    diff = (0, child_process_1.execFileSync)('git', ['diff', parentHash, commit.hash], (0, git_1.gitExecOptions)(repoPath));
+                }
+                else {
+                    diff = (0, child_process_1.execFileSync)('git', ['diff', commit.hash], (0, git_1.gitExecOptions)(repoPath));
+                }
+            }
+            catch {
+                continue;
+            }
+            if (!diff)
+                continue;
+            const changedFiles = (0, diff_parser_1.listChangedFiles)(diff)
+                .filter(isDiffableFile)
+                .filter((fp) => !(0, query_utils_1.isTestFile)(fp))
+                .filter((fp) => !seenFiles.has(fp));
+            for (const filePath of changedFiles) {
+                seenFiles.add(filePath);
+                try {
+                    const oldContent = parentHash
+                        ? getFileAtCommit(repoPath, parentHash, filePath)
+                        : null;
+                    const newContent = getFileAtCommit(repoPath, commit.hash, filePath);
+                    if (newContent === null) {
+                        // File was deleted — no new version to parse
+                        if (oldContent !== null) {
+                            const oldResult = (0, tree_sitter_1.extractFromSource)(filePath, oldContent);
+                            const oldSymbols = extractSignificantSymbols(oldResult);
+                            fileChanges.push({
+                                filePath,
+                                language: (0, grammars_1.detectLanguage)(filePath, oldContent),
+                                addedSymbols: [],
+                                removedSymbols: oldSymbols,
+                                modifiedSymbols: [],
+                            });
+                        }
+                        continue;
+                    }
+                    const language = (0, grammars_1.detectLanguage)(filePath, newContent);
+                    const newResult = (0, tree_sitter_1.extractFromSource)(filePath, newContent);
+                    const newSymbols = extractSignificantSymbols(newResult);
+                    if (oldContent === null) {
+                        // New file — all symbols are added
+                        fileChanges.push({
+                            filePath,
+                            language,
+                            addedSymbols: newSymbols,
+                            removedSymbols: [],
+                            modifiedSymbols: [],
+                            isNewFile: true,
+                        });
+                        continue;
+                    }
+                    const oldResult = (0, tree_sitter_1.extractFromSource)(filePath, oldContent);
+                    const oldSymbols = extractSignificantSymbols(oldResult);
+                    const { added, removed, modified } = compareSymbolSets(oldSymbols, newSymbols);
+                    if (added.length > 0 || removed.length > 0 || modified.length > 0) {
+                        fileChanges.push({
+                            filePath,
+                            language,
+                            addedSymbols: added,
+                            removedSymbols: removed,
+                            modifiedSymbols: modified,
+                        });
+                    }
+                }
+                catch (err) {
+                    parseErrorCount++;
+                    (0, errors_1.logWarn)(`Mine scan: error parsing ${filePath} in commit ${commit.hash.slice(0, 7)}`, {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
+        changes.push({
+            commitHash: commit.hash,
+            commitMessage: commit.message,
+            author: commit.author,
+            timestamp: commit.timestamp,
+            fileChanges,
+        });
+    }
+    (0, errors_1.logDebug)('Mine scan: parse errors', { parseErrorCount });
+    return changes;
+}
+//# sourceMappingURL=scanner.js.map

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

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

package/dist/spec/types.d.ts

@@ -85,6 +85,7 @@ export interface SpecCommitRelation {
 export interface CommitFragmentRelation {
     commitHash: string;
     fragmentId: string;
+    relationType: RelationType;
 }
 /**
  * A link between two Specs.
@@ -120,6 +121,37 @@ export interface CommitReference {
     message: string;
     timestamp: number;
 }
+/** Per-commit summary within a cluster context. */
+export interface CommitSummary {
+    /** Full commit hash (40 chars) — used for git operations like getCommitDiff. */
+    fullHash: string;
+    /** Short hash (7 chars) — used for display in LLM prompts. */
+    shortHash: string;
+    /** First line of commit message. */
+    message: string;
+    /** Changed file paths. */
+    changedFiles: string[];
+    /** Aggregated and truncated diff for this commit (populated by caller). */
+    truncatedDiff: string;
+}
+/**
+ * Cluster-level context for LLM spec evaluation — aggregated summaries of a
+ * group of commits affecting the same spec.
+ */
+export interface ClusterContext {
+    /** Number of commits in the cluster. */
+    commitCount: number;
+    /** Individual commit summaries. */
+    commitSummaries: CommitSummary[];
+    /** Top-N most frequently changed files across all commits. */
+    primaryFiles: string[];
+}
+/** Minimal info about a commit needed to build the cluster context. */
+export interface CommitContextInput {
+    commitHash: string;
+    message?: string;
+    filePaths: string[];
+}
 /**
  * A search result for a spec with scoring metadata.
  */

package/dist/spec/types.d.ts.map

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

package/dist/spec/ui/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Presentation layer for the spec module — progress types and renderers
+ * shared by the build / mine / evolve pipelines and the CLI.
+ *
+ * @module spec/ui
+ */
+export type { ProgressTick, ProgressCallback } from './progress';
+export { createProgressHandler, createMineProgressHandler, createBuildProgressHandler, MINE_PHASE_LABELS, BUILD_PHASE_LABELS, } from './progress-handler';
+//# sourceMappingURL=index.d.ts.map

package/dist/spec/ui/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/spec/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC"}

package/dist/spec/ui/index.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Presentation layer for the spec module — progress types and renderers
+ * shared by the build / mine / evolve pipelines and the CLI.
+ *
+ * @module spec/ui
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILD_PHASE_LABELS = exports.MINE_PHASE_LABELS = exports.createBuildProgressHandler = exports.createMineProgressHandler = exports.createProgressHandler = void 0;
+var progress_handler_1 = require("./progress-handler");
+Object.defineProperty(exports, "createProgressHandler", { enumerable: true, get: function () { return progress_handler_1.createProgressHandler; } });
+Object.defineProperty(exports, "createMineProgressHandler", { enumerable: true, get: function () { return progress_handler_1.createMineProgressHandler; } });
+Object.defineProperty(exports, "createBuildProgressHandler", { enumerable: true, get: function () { return progress_handler_1.createBuildProgressHandler; } });
+Object.defineProperty(exports, "MINE_PHASE_LABELS", { enumerable: true, get: function () { return progress_handler_1.MINE_PHASE_LABELS; } });
+Object.defineProperty(exports, "BUILD_PHASE_LABELS", { enumerable: true, get: function () { return progress_handler_1.BUILD_PHASE_LABELS; } });
+//# sourceMappingURL=index.js.map

package/dist/spec/ui/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/spec/ui/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAGH,uDAM4B;AAL1B,yHAAA,qBAAqB,OAAA;AACrB,6HAAA,yBAAyB,OAAA;AACzB,8HAAA,0BAA0B,OAAA;AAC1B,qHAAA,iBAAiB,OAAA;AACjB,sHAAA,kBAAkB,OAAA"}

package/dist/spec/ui/progress-handler.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Progress handler factory for the spec pipelines.
+ *
+ * Provides two rendering strategies for `ProgressCallback`:
+ *
+ * - **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.
+ *
+ * Phase label tables for the known pipelines live here too — labels are a
+ * presentation concern and belong with the renderer.
+ *
+ * @module spec/ui/progress-handler
+ */
+import type { ProgressCallback } from './progress';
+/** Phase labels for `spec mine`. */
+export declare const MINE_PHASE_LABELS: Record<string, string>;
+/** Phase labels for `spec build`. */
+export declare const BUILD_PHASE_LABELS: Record<string, string>;
+/**
+ * Create a progress handler for a spec pipeline.
+ *
+ * @param mode - `'bar'` for ANSI progress bar (TTY), `'verbose'` for text lines.
+ * @param labels - phase → padded label map used by bar mode.
+ */
+export declare function createProgressHandler(mode: 'bar' | 'verbose', labels: Record<string, string>): ProgressCallback;
+/** Create a progress handler with the `spec mine` phase labels. */
+export declare function createMineProgressHandler(mode: 'bar' | 'verbose'): ProgressCallback;
+/** Create a progress handler with the `spec build` phase labels. */
+export declare function createBuildProgressHandler(mode: 'bar' | 'verbose'): ProgressCallback;
+//# sourceMappingURL=progress-handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"progress-handler.d.ts","sourceRoot":"","sources":["../../../src/spec/ui/progress-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,YAAY,CAAC;AAMjE,oCAAoC;AACpC,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMpD,CAAC;AAEF,qCAAqC;AACrC,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIrD,CAAC;AAqFF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,KAAK,GAAG,SAAS,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,gBAAgB,CAKlB;AAED,mEAAmE;AACnE,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS,GAAG,gBAAgB,CAEnF;AAED,oEAAoE;AACpE,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS,GAAG,gBAAgB,CAEpF"}

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

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Progress handler factory for the spec pipelines.
+ *
+ * Provides two rendering strategies for `ProgressCallback`:
+ *
+ * - **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.
+ *
+ * Phase label tables for the known pipelines live here too — labels are a
+ * presentation concern and belong with the renderer.
+ *
+ * @module spec/ui/progress-handler
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILD_PHASE_LABELS = exports.MINE_PHASE_LABELS = void 0;
+exports.createProgressHandler = createProgressHandler;
+exports.createMineProgressHandler = createMineProgressHandler;
+exports.createBuildProgressHandler = createBuildProgressHandler;
+// ---------------------------------------------------------------------------
+// Phase labels (presentation concern — owned by the UI layer)
+// ---------------------------------------------------------------------------
+/** Phase labels for `spec mine`. */
+exports.MINE_PHASE_LABELS = {
+    scanning: 'Scanning commits  ',
+    clustering: 'Clustering        ',
+    generating: 'Generating specs  ',
+    persisting: 'Persisting to DB  ',
+    done: '                  ',
+};
+/** Phase labels for `spec build`. */
+exports.BUILD_PHASE_LABELS = {
+    scanning: 'Scanning commits  ',
+    persisting: 'Building graph    ',
+    done: '                  ',
+};
+// ---------------------------------------------------------------------------
+// Bar mode
+// ---------------------------------------------------------------------------
+/** Width of the progress bar portion (excluding label and counters). */
+const BAR_WIDTH = 20;
+function createBarHandler(labels) {
+    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 = 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 a spec pipeline.
+ *
+ * @param mode - `'bar'` for ANSI progress bar (TTY), `'verbose'` for text lines.
+ * @param labels - phase → padded label map used by bar mode.
+ */
+function createProgressHandler(mode, labels) {
+    if (mode === 'bar' && process.stdout.isTTY) {
+        return createBarHandler(labels);
+    }
+    return createVerboseHandler();
+}
+/** Create a progress handler with the `spec mine` phase labels. */
+function createMineProgressHandler(mode) {
+    return createProgressHandler(mode, exports.MINE_PHASE_LABELS);
+}
+/** Create a progress handler with the `spec build` phase labels. */
+function createBuildProgressHandler(mode) {
+    return createProgressHandler(mode, exports.BUILD_PHASE_LABELS);
+}
+//# sourceMappingURL=progress-handler.js.map