homegraph 1.4.1 → 1.5.1

package/dist/spec/build/diff-parser.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Unified diff parser — converts `git diff` output into structured code
+ * fragments.
+ *
+ * Replaces `commit4spec/reverse_engineer/change_analyzer.py`.  Parses
+ * unified diff output and extracts file-level change information (change
+ * type, line range, diff text).
+ *
+ * @module spec/build/diff-parser
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeCommitDiff = analyzeCommitDiff;
+exports.listChangedFiles = listChangedFiles;
+exports.parseDiff = parseDiff;
+const git_1 = require("../git");
+// ---------------------------------------------------------------------------
+// analyzeCommitDiff
+// ---------------------------------------------------------------------------
+/**
+ * Retrieve and parse the diff for a single commit.
+ *
+ * 1. Call `getCommitDiff(repoPath, commitHash)` to get raw diff text.
+ * 2. Parse the diff into structured `DiffFragment` objects.
+ * 3. Return the fragments.
+ *
+ * Returns an empty array when the diff cannot be retrieved or is empty.
+ */
+function analyzeCommitDiff(repoPath, commitHash, preFetchedDiff) {
+    const diff = preFetchedDiff ?? (0, git_1.getCommitDiff)(repoPath, commitHash);
+    if (!diff) {
+        return [];
+    }
+    return parseDiff(diff);
+}
+// ---------------------------------------------------------------------------
+// listChangedFiles
+// ---------------------------------------------------------------------------
+/**
+ * Parse changed file paths from a unified diff string.
+ *
+ * Matches `--- a/path` and `+++ b/path` headers to identify files,
+ * skipping `/dev/null`. Returns a list of unique changed file paths.
+ *
+ * Both headers are needed:
+ * - `+++ b/` captures added and modified files.  For deletions the line is
+ *   `+++ /dev/null`, which is skipped.
+ * - `--- a/` captures deleted files.  For additions the line is
+ *   `--- /dev/null`, which is skipped.
+ */
+function listChangedFiles(diff) {
+    const files = new Set();
+    const lines = diff.split('\n');
+    for (const line of lines) {
+        let match = /^\+\+\+ b\/(.+)$/.exec(line);
+        if (match) {
+            const fp = match[1];
+            if (fp !== '/dev/null') {
+                files.add(fp);
+            }
+            continue;
+        }
+        match = /^--- a\/(.+)$/.exec(line);
+        if (match) {
+            const fp = match[1];
+            if (fp !== '/dev/null') {
+                files.add(fp);
+            }
+        }
+    }
+    return Array.from(files);
+}
+// ---------------------------------------------------------------------------
+// parseDiff
+// ---------------------------------------------------------------------------
+/**
+ * State-machine parser for unified diff format.
+ *
+ * Walks through the diff line-by-line, tracking the current file, change
+ * type, and line-number range.  Accumulates lines into a buffer and emits a
+ * `DiffFragment` each time a new `diff --git` section begins (or when the
+ * input is exhausted).
+ */
+function parseDiff(diff) {
+    const lines = diff.split('\n');
+    // ---- state ----
+    const fragments = [];
+    let buf = [];
+    let currentFilePath = null;
+    let currentChangeType = 'MODIFY';
+    let currentStartLine = 0;
+    let currentEndLine = 0;
+    let inHunk = false;
+    // ---- flush helper ----
+    const _flush = () => {
+        if (buf.length === 0 || currentFilePath === null) {
+            buf = [];
+            return;
+        }
+        // DELETE files have no lines in the new version — use [0, 0].
+        let startLine;
+        let endLine;
+        if (currentChangeType === 'DELETE') {
+            startLine = 0;
+            endLine = 0;
+        }
+        else {
+            // When no hunk was ever encountered, default startLine to 1.
+            startLine = currentStartLine === 0 ? 1 : currentStartLine;
+            endLine = currentEndLine;
+        }
+        fragments.push({
+            filePath: currentFilePath,
+            changeType: currentChangeType,
+            startLine,
+            endLine,
+            codeDiff: buf.join('\n'),
+        });
+        buf = [];
+    };
+    // ---- line-by-line parser ----
+    for (const line of lines) {
+        // Rule 1 — new file section: flush the previous file.
+        if (line.startsWith('diff --git ')) {
+            _flush();
+            buf = [line];
+            currentFilePath = null;
+            currentChangeType = 'MODIFY';
+            currentStartLine = 0;
+            currentEndLine = 0;
+            inHunk = false;
+            continue;
+        }
+        // Rule 2 — new file mode → change type is ADD.
+        if (line.startsWith('new file mode ')) {
+            currentChangeType = 'ADD';
+            buf.push(line);
+            continue;
+        }
+        // Rule 3 — deleted file mode → change type is DELETE.
+        if (line.startsWith('deleted file mode ')) {
+            currentChangeType = 'DELETE';
+            buf.push(line);
+            continue;
+        }
+        // Rule 4 — file path lines (--- a/path or +++ b/path).
+        if (line.startsWith('--- a/') || line.startsWith('+++ b/')) {
+            const isPlus = line.startsWith('+++ b/');
+            // Extract the path, skipping `/dev/null`.
+            let pathPart = '';
+            if (isPlus) {
+                pathPart = line.slice(6); // '+++ b/'.length
+            }
+            else {
+                pathPart = line.slice(6); // '--- a/'.length
+            }
+            if (pathPart !== '/dev/null') {
+                currentFilePath = pathPart;
+            }
+            buf.push(line);
+            continue;
+        }
+        // Rule 5 — hunk header: @@ -oldStart[,oldCount] +newStart[,newCount] @@
+        const hunkMatch = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+        if (hunkMatch) {
+            const newStart = parseInt(hunkMatch[1], 10);
+            if (currentStartLine === 0) {
+                currentStartLine = newStart;
+            }
+            currentEndLine = newStart;
+            inHunk = true;
+            buf.push(line);
+            continue;
+        }
+        // Rule 6 — added lines (start with '+', but not '+++').
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+            if (inHunk) {
+                currentEndLine++;
+            }
+            buf.push(line);
+            continue;
+        }
+        // Rule 7 — removed lines (start with '-', but not '---').
+        if (line.startsWith('-') && !line.startsWith('---')) {
+            buf.push(line);
+            continue;
+        }
+        // Rule 8 — context lines (start with a space).
+        if (line.startsWith(' ')) {
+            if (inHunk) {
+                currentEndLine++;
+            }
+            buf.push(line);
+            continue;
+        }
+        // Rule 9 — all other lines (e.g. `rename from` / `rename to`,
+        // `similarity index`, `Binary files differ`, `\ No newline at end of
+        // file`, blank lines between sections, etc.).
+        buf.push(line);
+    }
+    // Flush the final file.
+    _flush();
+    return fragments;
+}
+//# sourceMappingURL=diff-parser.js.map

package/dist/spec/build/diff-parser.js.map

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

package/dist/spec/build/pipeline.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Build pipeline orchestrator — main entry point for building spec
+ * knowledge from Git history.
+ *
+ * Replaces `commit4spec/reverse_engineer/pipeline.py`.  Discovers spec↔commit
+ * pairs via `scan()`, persists them into the SQLite knowledge graph, and
+ * writes a `.homegraph/commit4spec/meta.json` anchor so the self-evolve pipeline can
+ * pick up where build left off.
+ *
+ * @module spec/build/pipeline
+ */
+import { SqliteDatabase } from '../../db/sqlite-adapter';
+import type { ProgressCallback } from '../ui';
+export interface BuildResult {
+    specsFound: number;
+    commitsFound: number;
+    fragmentsFound: number;
+    relationsCreated: number;
+    totalEntries: number;
+    skippedEntries: Array<{
+        specId: string;
+        reason: string;
+    }>;
+    upToDate?: boolean;
+}
+/**
+ * Run the full build pipeline.
+ *
+ * Steps (ported from `pipeline.py:49-151`):
+ *
+ * 1. Initialise the spec knowledge-graph schema in the database.
+ * 2. Discover all specs on disk (for the `totalEntries` count).
+ * 3. Scan the repository for spec↔commit pairs.
+ * 4. Sort pairs by commit timestamp ascending so that `INSERT OR REPLACE`
+ *    gives the most-recent commit the final word for each spec node.
+ * 5. Process each pair:
+ *    - Insert a SpecNode (once per specId; deduplicated by commit timestamp).
+ *    - Insert a CommitNode (once per commit hash).
+ *    - Insert a SUMMARIZED_FROM relation.
+ *    - Parse the commit diff into code fragments and persist them.
+ * 6. Build a list of specs discovered on disk but never matched to a commit.
+ * 7. Write `.homegraph/commit4spec/meta.json`.
+ * 8. Return the `BuildResult` with all counts.
+ *
+ * Edge cases:
+ * - Empty pairs → zero counts, write meta anyway, return result.
+ * - Pair with commit metadata but no spec metadata → commit and fragments
+ *   are still persisted; SpecNode and spec_commit_relation are skipped.
+ * - Pair with spec metadata but no commit metadata → entire pair is skipped.
+ * - Same spec in multiple pairs → only counted once in `specsFound`, but
+ *   every commit relation is created.
+ */
+export declare function runBuildPipeline(repoPath: string, specStoragePath: string, db: SqliteDatabase, onProgress?: ProgressCallback): BuildResult;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/spec/build/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../../src/spec/build/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAWzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAM9C,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,cAAc,EAClB,UAAU,CAAC,EAAE,gBAAgB,GAC5B,WAAW,CAoIb"}

package/dist/spec/build/pipeline.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * Build pipeline orchestrator — main entry point for building spec
+ * knowledge from Git history.
+ *
+ * Replaces `commit4spec/reverse_engineer/pipeline.py`.  Discovers spec↔commit
+ * pairs via `scan()`, persists them into the SQLite knowledge graph, and
+ * writes a `.homegraph/commit4spec/meta.json` anchor so the self-evolve pipeline can
+ * pick up where build left off.
+ *
+ * @module spec/build/pipeline
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBuildPipeline = runBuildPipeline;
+const config_1 = require("../config");
+const utils_1 = require("../utils");
+const schema_1 = require("../db/schema");
+const commit_node_1 = require("../db/commit-node");
+const relations_1 = require("../db/relations");
+const persist_1 = require("../db/persist");
+const scan_1 = require("./scan");
+const git_1 = require("../git");
+const diff_parser_1 = require("./diff-parser");
+const errors_1 = require("../../errors");
+// ---------------------------------------------------------------------------
+// runBuildPipeline
+// ---------------------------------------------------------------------------
+/**
+ * Run the full build pipeline.
+ *
+ * Steps (ported from `pipeline.py:49-151`):
+ *
+ * 1. Initialise the spec knowledge-graph schema in the database.
+ * 2. Discover all specs on disk (for the `totalEntries` count).
+ * 3. Scan the repository for spec↔commit pairs.
+ * 4. Sort pairs by commit timestamp ascending so that `INSERT OR REPLACE`
+ *    gives the most-recent commit the final word for each spec node.
+ * 5. Process each pair:
+ *    - Insert a SpecNode (once per specId; deduplicated by commit timestamp).
+ *    - Insert a CommitNode (once per commit hash).
+ *    - Insert a SUMMARIZED_FROM relation.
+ *    - Parse the commit diff into code fragments and persist them.
+ * 6. Build a list of specs discovered on disk but never matched to a commit.
+ * 7. Write `.homegraph/commit4spec/meta.json`.
+ * 8. Return the `BuildResult` with all counts.
+ *
+ * Edge cases:
+ * - Empty pairs → zero counts, write meta anyway, return result.
+ * - Pair with commit metadata but no spec metadata → commit and fragments
+ *   are still persisted; SpecNode and spec_commit_relation are skipped.
+ * - Pair with spec metadata but no commit metadata → entire pair is skipped.
+ * - Same spec in multiple pairs → only counted once in `specsFound`, but
+ *   every commit relation is created.
+ */
+function runBuildPipeline(repoPath, specStoragePath, db, onProgress) {
+    // Pre-check: if meta.json exists and HEAD hasn't changed since the last
+    // build, the knowledge graph is already current — skip the full rebuild.
+    const existingMeta = (0, utils_1.readMeta)(repoPath);
+    if (existingMeta?.currentCommitID) {
+        const headHash = (0, git_1.getHeadHash)(repoPath);
+        if (headHash && headHash === existingMeta.currentCommitID) {
+            (0, errors_1.logDebug)('Skipping spec build: knowledge graph is up to date', {
+                currentCommitID: existingMeta.currentCommitID,
+            });
+            return {
+                specsFound: 0,
+                commitsFound: 0,
+                fragmentsFound: 0,
+                relationsCreated: 0,
+                totalEntries: (0, utils_1.discoverSpecs)(specStoragePath).length,
+                skippedEntries: [],
+                upToDate: true,
+            };
+        }
+    }
+    // ---- Step 1: init schema ----
+    (0, schema_1.initSpecSchema)(db);
+    // ---- Step 2: discover specs (for totalEntries) ----
+    const allEntries = (0, utils_1.discoverSpecs)(specStoragePath);
+    const totalEntries = allEntries.length;
+    // ---- Step 3: scan for pairs ----
+    const pairs = (0, scan_1.scan)(repoPath, specStoragePath, (0, config_1.loadSpecConfig)(repoPath), onProgress);
+    // ---- Step 4: sort by commit timestamp ascending (oldest first) ----
+    // INSERT OR REPLACE is used for SpecNode — when the same spec appears
+    // in multiple pairs, the LAST write (most-recent commit) naturally wins.
+    pairs.sort((a, b) => {
+        const aTs = a.commitMetadata?.timestamp ?? 0;
+        const bTs = b.commitMetadata?.timestamp ?? 0;
+        return aTs - bTs;
+    });
+    // ---- Step 5: process pairs ----
+    const writtenSpecIds = new Set();
+    const seenCommitHashes = new Set();
+    let specsFound = 0;
+    let commitsFound = 0;
+    let fragmentsFound = 0;
+    let relationsCreated = 0;
+    const pairsTotal = pairs.length;
+    let pairsCurrent = 0;
+    for (const pair of pairs) {
+        pairsCurrent++;
+        onProgress?.({
+            phase: 'persisting',
+            current: pairsCurrent,
+            total: pairsTotal,
+            message: `${pair.specId} @ ${pair.commitHash.slice(0, 7)}`,
+        });
+        // Skip if no commit metadata (no data to insert).
+        const cm = pair.commitMetadata;
+        if (!cm) {
+            continue;
+        }
+        const sm = pair.specMetadata;
+        // Insert SpecNode if spec metadata is present.
+        // INSERT OR REPLACE lets the most-recent commit (last in ascending
+        // order) overwrite the timestamp. We still track writtenSpecIds to
+        // correctly count distinct specs (not overwrites).
+        if (sm) {
+            (0, errors_1.logDebug)('Processing pair: inserting SpecNode', {
+                specId: sm.specId,
+                title: sm.title,
+            });
+            (0, persist_1.upsertSpecFromMetadata)(db, sm, cm.timestamp);
+            if (!writtenSpecIds.has(pair.specId)) {
+                writtenSpecIds.add(pair.specId);
+                specsFound++;
+            }
+        }
+        // Insert CommitNode if not yet seen.
+        if (!seenCommitHashes.has(cm.hash)) {
+            (0, commit_node_1.insertCommitNode)(db, {
+                hash: cm.hash,
+                message: cm.message,
+                author: cm.author,
+                timestamp: cm.timestamp,
+            });
+            seenCommitHashes.add(cm.hash);
+            commitsFound++;
+        }
+        // Insert spec_commit_relation (only when spec metadata exists).
+        if (sm) {
+            (0, relations_1.insertSpecCommitRelation)(db, pair.specId, cm.hash, 'SUMMARIZED_FROM');
+            relationsCreated++;
+        }
+        // ---- Analyze diff and insert fragments ----
+        const preFetchedDiff = (0, git_1.getCommitDiff)(repoPath, cm.hash);
+        const fragments = (0, diff_parser_1.analyzeCommitDiff)(repoPath, cm.hash, preFetchedDiff);
+        const persisted = (0, persist_1.persistCommitFragments)(db, cm.hash, fragments);
+        fragmentsFound += persisted.fragmentsInserted;
+        relationsCreated += persisted.relationsCreated;
+    }
+    // ---- Step 6: build skipped entries ----
+    const skippedEntries = allEntries
+        .filter((e) => !writtenSpecIds.has(e.specId))
+        .map((e) => ({ specId: e.specId, reason: 'No matching commits found' }));
+    // ---- Step 7: write meta ----
+    const headHash = (0, git_1.getHeadHash)(repoPath) ?? undefined;
+    (0, utils_1.writeMeta)(repoPath, specStoragePath, headHash);
+    onProgress?.({ phase: 'done', current: 0, total: 0 });
+    // ---- Step 8: return result ----
+    return {
+        specsFound,
+        commitsFound,
+        fragmentsFound,
+        relationsCreated,
+        totalEntries,
+        skippedEntries,
+    };
+}
+//# sourceMappingURL=pipeline.js.map

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

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

package/dist/spec/build/scan.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Spec↔commit pairing — discovers which commits reference which specs via
+ * conventional-commit scope extraction.
+ *
+ * Replaces `commit4spec/reverse_engineer/git_scanner.py`'s `scan()` (Strategy
+ * A). Shared by the build pipeline and the evolve pipeline's incremental
+ * commit analyzer.
+ *
+ * @module spec/build/scan
+ */
+import { SpecConfig } from '../config';
+import { CommitInfo } from '../git';
+import type { ProgressCallback } from '../ui';
+import { SpecMetadata } from './spec-extractor';
+export interface SpecCommitPair {
+    specId: string;
+    commitHash: string;
+    specMetadata: SpecMetadata | null;
+    commitMetadata: CommitInfo | null;
+}
+/** Result of matching a single commit message against the on-disk specs. */
+export interface SpecMatch {
+    /** Resolved spec ID, or null when the commit scope matched nothing. */
+    specId: string | null;
+    /** Extracted spec metadata (null when the spec doc could not be read). */
+    metadata: SpecMetadata | null;
+}
+/**
+ * Match a single commit message to an on-disk spec: resolve the
+ * conventional-commit scope to a spec ID, then extract that spec's metadata.
+ *
+ * This is the shared per-commit matching step used by both {@link scan}
+ * (build) and the evolve pipeline's incremental analyzer.
+ */
+export declare function matchCommitToSpec(message: string, specIds: Set<string>, specStoragePath: string, config: SpecConfig): SpecMatch;
+/**
+ * Main scanning function — discovers spec↔commit pairs from commit history.
+ *
+ * Iterates every commit in the repo, extracts a conventional-commit scope from
+ * its message, normalizes it, and checks whether the resulting spec ID exists
+ * on disk. When a match is found the pair is recorded with full spec and
+ * commit metadata.
+ *
+ * Duplicates (identical specId + commitHash) are de-duplicated via a
+ * `Map` keyed on `"${specId}|${commitHash}"`.
+ */
+export declare function scan(repoPath: string, specStoragePath: string, config: SpecConfig, onProgress?: ProgressCallback): SpecCommitPair[];
+//# sourceMappingURL=scan.d.ts.map

package/dist/spec/build/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/spec/build/scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,UAAU,EAAiB,MAAM,QAAQ,CAAC;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAE9C,OAAO,EAAuB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAOrE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,cAAc,EAAE,UAAU,GAAG,IAAI,CAAC;CACnC;AAED,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CAC/B;AAMD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EACpB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,UAAU,GACjB,SAAS,CASX;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAClB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,UAAU,EAClB,UAAU,CAAC,EAAE,gBAAgB,GAC5B,cAAc,EAAE,CA0ClB"}

package/dist/spec/build/scan.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Spec↔commit pairing — discovers which commits reference which specs via
+ * conventional-commit scope extraction.
+ *
+ * Replaces `commit4spec/reverse_engineer/git_scanner.py`'s `scan()` (Strategy
+ * A). Shared by the build pipeline and the evolve pipeline's incremental
+ * commit analyzer.
+ *
+ * @module spec/build/scan
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchCommitToSpec = matchCommitToSpec;
+exports.scan = scan;
+const git_1 = require("../git");
+const utils_1 = require("../utils");
+const scope_resolver_1 = require("./scope-resolver");
+const spec_extractor_1 = require("./spec-extractor");
+const errors_1 = require("../../errors");
+// ---------------------------------------------------------------------------
+// matchCommitToSpec
+// ---------------------------------------------------------------------------
+/**
+ * Match a single commit message to an on-disk spec: resolve the
+ * conventional-commit scope to a spec ID, then extract that spec's metadata.
+ *
+ * This is the shared per-commit matching step used by both {@link scan}
+ * (build) and the evolve pipeline's incremental analyzer.
+ */
+function matchCommitToSpec(message, specIds, specStoragePath, config) {
+    const specId = (0, scope_resolver_1.resolveScopeToSpec)(message, specIds, config);
+    if (!specId) {
+        return { specId: null, metadata: null };
+    }
+    return {
+        specId,
+        metadata: (0, spec_extractor_1.extractSpecMetadata)(specStoragePath, specId, config),
+    };
+}
+// ---------------------------------------------------------------------------
+// scan
+// ---------------------------------------------------------------------------
+/**
+ * Main scanning function — discovers spec↔commit pairs from commit history.
+ *
+ * Iterates every commit in the repo, extracts a conventional-commit scope from
+ * its message, normalizes it, and checks whether the resulting spec ID exists
+ * on disk. When a match is found the pair is recorded with full spec and
+ * commit metadata.
+ *
+ * Duplicates (identical specId + commitHash) are de-duplicated via a
+ * `Map` keyed on `"${specId}|${commitHash}"`.
+ */
+function scan(repoPath, specStoragePath, config, onProgress) {
+    const pairs = new Map();
+    // Hoist the directory read out of the per-commit loop.
+    const specIds = new Set((0, utils_1.discoverSpecs)(specStoragePath).map((e) => e.specId));
+    const commits = (0, git_1.getAllCommits)(repoPath);
+    const total = commits.length;
+    let current = 0;
+    for (const commit of commits) {
+        current++;
+        onProgress?.({
+            phase: 'scanning',
+            current,
+            total,
+            message: `${commit.hash.slice(0, 7)} ${commit.message.slice(0, 30)}`,
+        });
+        const { specId, metadata } = matchCommitToSpec(commit.message, specIds, specStoragePath, config);
+        if (!specId) {
+            (0, errors_1.logDebug)('scan: no scope match', {
+                commitHash: commit.hash.slice(0, 7),
+                message: commit.message,
+            });
+            continue;
+        }
+        const key = `${specId}|${commit.hash}`;
+        if (!pairs.has(key)) {
+            pairs.set(key, {
+                specId,
+                commitHash: commit.hash,
+                specMetadata: metadata,
+                commitMetadata: commit,
+            });
+        }
+    }
+    return Array.from(pairs.values());
+}
+//# sourceMappingURL=scan.js.map

package/dist/spec/build/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../../src/spec/build/scan.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AAwCH,8CAcC;AAiBD,oBA+CC;AAnHD,gCAAmD;AACnD,oCAAyC;AAEzC,qDAAsD;AACtD,qDAAqE;AACrE,yCAAwC;AAqBxC,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAC/B,OAAe,EACf,OAAoB,EACpB,eAAuB,EACvB,MAAkB;IAElB,MAAM,MAAM,GAAG,IAAA,mCAAkB,EAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO;QACL,MAAM;QACN,QAAQ,EAAE,IAAA,oCAAmB,EAAC,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,OAAO;AACP,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,SAAgB,IAAI,CAClB,QAAgB,EAChB,eAAuB,EACvB,MAAkB,EAClB,UAA6B;IAE7B,MAAM,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAEhD,uDAAuD;IACvD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAA,qBAAa,EAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAE7E,MAAM,OAAO,GAAG,IAAA,mBAAa,EAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC;IAC7B,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;QACV,UAAU,EAAE,CAAC;YACX,KAAK,EAAE,UAAU;YACjB,OAAO;YACP,KAAK;YACL,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;SACrE,CAAC,CAAC;QAEH,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,iBAAiB,CAC5C,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,CACjD,CAAC;QACF,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAA,iBAAQ,EAAC,sBAAsB,EAAE;gBAC/B,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;gBACnC,OAAO,EAAE,MAAM,CAAC,OAAO;aACxB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QACvC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;gBACb,MAAM;gBACN,UAAU,EAAE,MAAM,CAAC,IAAI;gBACvB,YAAY,EAAE,QAAQ;gBACtB,cAAc,EAAE,MAAM;aACvB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;AACpC,CAAC"}

package/dist/spec/build/scope-resolver.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Commit message scope parsing and resolution.
+ *
+ * Replaces `commit4spec/reverse_engineer/scope_resolver.py`.
+ * Extracts conventional-commit scopes, normalizes them, and resolves them to
+ * spec IDs found on disk.
+ *
+ * @module spec/build/scope-resolver
+ */
+import { SpecConfig } from '../config';
+/**
+ * Extract a scope from a commit message using the configured regex.
+ *
+ * Only searches the **first line** of the commit message.  Returns the
+ * contents of the first capture group (the scope), or `null` when there is
+ * no match or the regex has no capture group.
+ */
+export declare function extractScope(message: string, scopeRegex: string): string | null;
+/**
+ * Normalize a scope string.
+ *
+ * Steps applied in order:
+ *
+ * 1. **Strip prefixes** — for each prefix in `stripPrefixes`, if `scope`
+ *    starts with it, remove it and stop (only the first matching prefix is
+ *    stripped).
+ * 2. **Lowercase** — if `lowercase` is `true`, convert to lower case.
+ * 3. **Pad spec number** — if `padSpecNumber` is `true`, match the pattern
+ *    `/^spec(\d+)$/i` and zero-pad the numeric portion to 2 digits
+ *    (e.g. `spec3` → `spec03`).
+ */
+export declare function normalizeScope(scope: string, config: {
+    stripPrefixes: string[];
+    lowercase: boolean;
+    padSpecNumber: boolean;
+}): string;
+/**
+ * Extract a scope from a commit message, normalize it, then check whether the
+ * resulting spec ID exists among the known on-disk spec IDs.
+ *
+ * @param message - Commit message (only the first line is searched).
+ * @param specIds - Known spec IDs (from `discoverSpecs`, hoisted by the
+ *   caller so scanning N commits does not re-read the directory N times).
+ * @param config  - Spec configuration (commitScope section).
+ *
+ * Returns the normalized spec ID when the scope resolves to an existing spec,
+ * otherwise `null`.
+ */
+export declare function resolveScopeToSpec(message: string, specIds: Set<string>, config: SpecConfig): string | null;
+//# sourceMappingURL=scope-resolver.d.ts.map

package/dist/spec/build/scope-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-resolver.d.ts","sourceRoot":"","sources":["../../../src/spec/build/scope-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAOvC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkB/E;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE;IAAE,aAAa,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAE,GAC9E,MAAM,CAyBR;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EACpB,MAAM,EAAE,UAAU,GACjB,MAAM,GAAG,IAAI,CASf"}