homegraph 1.1.2 → 1.1.3

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

@@ -0,0 +1,166 @@
+"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/mining/diff-parser
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeCommitDiff = analyzeCommitDiff;
+const git_scanner_1 = require("./git-scanner");
+// ---------------------------------------------------------------------------
+// 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_scanner_1.getCommitDiff)(repoPath, commitHash);
+    if (!diff) {
+        return [];
+    }
+    return _parseDiff(diff);
+}
+// ---------------------------------------------------------------------------
+// _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/mining/diff-parser.js.map

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

package/dist/spec/mining/git-scanner.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Git commit history scanning and spec↔commit pairing.
+ *
+ * Replaces `commit4spec/reverse_engineer/git_scanner.py` and
+ * `commit4spec/reverse_engineer/git_utils.py`. Discovers spec↔commit pairs via
+ * two strategies:
+ *
+ *  - **Strategy A — commit message scope:** extract conventional-commit scopes
+ *    from commit messages and resolve them to spec IDs on disk.
+ *  - **Strategy B — commit-info.md:** discover specs on disk, read their
+ *    `commit-info.md` for linked commit hashes, and verify those commits exist.
+ *
+ * All Git operations use `execFileSync` with an args array (never template
+ * strings) to avoid shell injection risks — matching the HomeGraph convention
+ * in `src/sync/git-hooks.ts` and `src/sync/worktree.ts`.
+ *
+ * @module spec/mining/git-scanner
+ */
+import { SpecConfig } from '../config';
+import { SpecMetadata } from './spec-extractor';
+export interface CommitInfo {
+    /** Full 40-char commit hash */
+    hash: string;
+    /** First line of commit message */
+    message: string;
+    /** Author name */
+    author: string;
+    /** Unix epoch milliseconds */
+    timestamp: number;
+}
+export interface SpecCommitPair {
+    specId: string;
+    commitHash: string;
+    specMetadata: SpecMetadata | null;
+    commitMetadata: CommitInfo | null;
+}
+/**
+ * Check whether `repoPath` is a git repository.
+ *
+ * Runs `git rev-parse --git-dir` and returns `true` on success, `false`
+ * when the command fails (not a repo, git not installed, etc.).
+ */
+export declare function isGitRepo(repoPath: string): boolean;
+/**
+ * Return every commit in `repoPath` as `CommitInfo` objects.
+ *
+ * Runs `git log --format='%H%n%aI%n%an%n%s%n---END---'` and parses the
+ * output one five-line block per commit.  Commits are returned in reverse
+ * chronological order (most recent first), matching Git's default.
+ *
+ * An empty repo yields an empty array.
+ */
+export declare function getAllCommits(repoPath: string): CommitInfo[];
+/**
+ * Retrieve metadata for a single commit.
+ *
+ * Runs `git show -s --format='%H%n%aI%n%an%n%s' <commitHash>`.  Returns
+ * `null` when the command fails (hash not found, invalid repo, etc.).
+ */
+export declare function getCommitInfo(repoPath: string, commitHash: string): CommitInfo | null;
+/**
+ * Return the full unified diff introduced by `commitHash`.
+ *
+ * Strategy:
+ * 1. Query the parent hash(es) via `git log --pretty=%P -n 1 <commitHash>`.
+ * 2. If a parent exists, diff it against the commit: `git diff <parent> <commitHash>`.
+ * 3. For an initial (root) commit with no parent, use `git diff <commitHash>`
+ *    which shows all files added in that commit.
+ *
+ * Returns an empty string when any Git command fails.
+ */
+export declare function getCommitDiff(repoPath: string, commitHash: string): string;
+/**
+ * Main scanning function — discovers spec↔commit pairs using two strategies.
+ *
+ * **Strategy A — commit message scope:**
+ * 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.
+ *
+ * **Strategy B — commit-info.md:**
+ * Discovers all specs on disk that were **not** already paired by Strategy A,
+ * reads their metadata (which may include a commit hash from `commit-info.md`),
+ * and verifies the commit exists in the repo. Verified pairs are added.
+ *
+ * Duplicates (identical specId + commitHash) are de-duplicated via a
+ * `Map` keyed on `"${specId}|${commitHash}"`.
+ */
+export declare function scan(repoPath: string, specStoragePath: string, config: SpecConfig): SpecCommitPair[];
+//# sourceMappingURL=git-scanner.d.ts.map

package/dist/spec/mining/git-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-scanner.d.ts","sourceRoot":"","sources":["../../../src/spec/mining/git-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,OAAO,EAAuB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAOrE,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,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;AA8BD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOnD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAkC5D;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,UAAU,GAAG,IAAI,CA4BnB;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAmC1E;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,IAAI,CAClB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,UAAU,GACjB,cAAc,EAAE,CA+ElB"}

package/dist/spec/mining/git-scanner.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * Git commit history scanning and spec↔commit pairing.
+ *
+ * Replaces `commit4spec/reverse_engineer/git_scanner.py` and
+ * `commit4spec/reverse_engineer/git_utils.py`. Discovers spec↔commit pairs via
+ * two strategies:
+ *
+ *  - **Strategy A — commit message scope:** extract conventional-commit scopes
+ *    from commit messages and resolve them to spec IDs on disk.
+ *  - **Strategy B — commit-info.md:** discover specs on disk, read their
+ *    `commit-info.md` for linked commit hashes, and verify those commits exist.
+ *
+ * All Git operations use `execFileSync` with an args array (never template
+ * strings) to avoid shell injection risks — matching the HomeGraph convention
+ * in `src/sync/git-hooks.ts` and `src/sync/worktree.ts`.
+ *
+ * @module spec/mining/git-scanner
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGitRepo = isGitRepo;
+exports.getAllCommits = getAllCommits;
+exports.getCommitInfo = getCommitInfo;
+exports.getCommitDiff = getCommitDiff;
+exports.scan = scan;
+const child_process_1 = require("child_process");
+const utils_1 = require("../utils");
+const scope_resolver_1 = require("./scope-resolver");
+const spec_extractor_1 = require("./spec-extractor");
+const errors_1 = require("../../errors");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Shared options for all `execFileSync` Git calls. */
+function gitExecOptions(repoPath) {
+    const stdio = ['ignore', 'pipe', 'ignore'];
+    return {
+        cwd: repoPath,
+        encoding: 'utf8',
+        stdio,
+        windowsHide: true,
+    };
+}
+/**
+ * Convert an ISO-8601 string to Unix epoch milliseconds.
+ * Returns 0 for invalid or unparseable strings.
+ */
+function parseISOTimestamp(isoString) {
+    const ts = new Date(isoString).getTime();
+    return isNaN(ts) ? 0 : ts;
+}
+// ---------------------------------------------------------------------------
+// isGitRepo
+// ---------------------------------------------------------------------------
+/**
+ * Check whether `repoPath` is a git repository.
+ *
+ * Runs `git rev-parse --git-dir` and returns `true` on success, `false`
+ * when the command fails (not a repo, git not installed, etc.).
+ */
+function isGitRepo(repoPath) {
+    try {
+        (0, child_process_1.execFileSync)('git', ['rev-parse', '--git-dir'], gitExecOptions(repoPath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// getAllCommits
+// ---------------------------------------------------------------------------
+/**
+ * Return every commit in `repoPath` as `CommitInfo` objects.
+ *
+ * Runs `git log --format='%H%n%aI%n%an%n%s%n---END---'` and parses the
+ * output one five-line block per commit.  Commits are returned in reverse
+ * chronological order (most recent first), matching Git's default.
+ *
+ * An empty repo yields an empty array.
+ */
+function getAllCommits(repoPath) {
+    let stdout;
+    try {
+        stdout = (0, child_process_1.execFileSync)('git', ['log', "--format=%H%n%aI%n%an%n%s%n---END---"], gitExecOptions(repoPath));
+    }
+    catch {
+        return [];
+    }
+    const lines = stdout.trim().split('\n');
+    const commits = [];
+    // Each commit occupies 5 lines: hash, ISO timestamp, author, subject, separator.
+    for (let i = 0; i + 4 < lines.length; i += 5) {
+        const hash = lines[i].trim();
+        const isoString = lines[i + 1].trim();
+        const author = lines[i + 2].trim();
+        const message = lines[i + 3].trim();
+        // lines[i+4] is the ---END--- separator — skip it.
+        if (!hash)
+            continue;
+        commits.push({
+            hash,
+            message,
+            author,
+            timestamp: parseISOTimestamp(isoString),
+        });
+    }
+    return commits;
+}
+// ---------------------------------------------------------------------------
+// getCommitInfo
+// ---------------------------------------------------------------------------
+/**
+ * Retrieve metadata for a single commit.
+ *
+ * Runs `git show -s --format='%H%n%aI%n%an%n%s' <commitHash>`.  Returns
+ * `null` when the command fails (hash not found, invalid repo, etc.).
+ */
+function getCommitInfo(repoPath, commitHash) {
+    let stdout;
+    try {
+        stdout = (0, child_process_1.execFileSync)('git', ['show', '-s', "--format=%H%n%aI%n%an%n%s", commitHash], gitExecOptions(repoPath));
+    }
+    catch {
+        return null;
+    }
+    const lines = stdout.trim().split('\n');
+    if (lines.length < 4)
+        return null;
+    const hash = lines[0].trim();
+    const isoString = lines[1].trim();
+    const author = lines[2].trim();
+    const message = lines[3].trim();
+    if (!hash)
+        return null;
+    return {
+        hash,
+        message,
+        author,
+        timestamp: parseISOTimestamp(isoString),
+    };
+}
+// ---------------------------------------------------------------------------
+// getCommitDiff
+// ---------------------------------------------------------------------------
+/**
+ * Return the full unified diff introduced by `commitHash`.
+ *
+ * Strategy:
+ * 1. Query the parent hash(es) via `git log --pretty=%P -n 1 <commitHash>`.
+ * 2. If a parent exists, diff it against the commit: `git diff <parent> <commitHash>`.
+ * 3. For an initial (root) commit with no parent, use `git diff <commitHash>`
+ *    which shows all files added in that commit.
+ *
+ * Returns an empty string when any Git command fails.
+ */
+function getCommitDiff(repoPath, commitHash) {
+    // Step 1 — get parent hashes.
+    let parentStdout;
+    try {
+        parentStdout = (0, child_process_1.execFileSync)('git', ['log', '--pretty=%P', '-n', '1', commitHash], gitExecOptions(repoPath));
+    }
+    catch {
+        return '';
+    }
+    const parents = parentStdout.trim().split(/\s+/).filter(Boolean);
+    // Step 2 & 3 — run the appropriate diff.
+    try {
+        if (parents.length > 0) {
+            const parent = parents[0];
+            return (0, child_process_1.execFileSync)('git', ['diff', parent, commitHash], gitExecOptions(repoPath));
+        }
+        // Initial commit — no parent.
+        return (0, child_process_1.execFileSync)('git', ['diff', commitHash], gitExecOptions(repoPath));
+    }
+    catch {
+        return '';
+    }
+}
+// ---------------------------------------------------------------------------
+// scan
+// ---------------------------------------------------------------------------
+/**
+ * Main scanning function — discovers spec↔commit pairs using two strategies.
+ *
+ * **Strategy A — commit message scope:**
+ * 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.
+ *
+ * **Strategy B — commit-info.md:**
+ * Discovers all specs on disk that were **not** already paired by Strategy A,
+ * reads their metadata (which may include a commit hash from `commit-info.md`),
+ * and verifies the commit exists in the repo. Verified pairs are added.
+ *
+ * Duplicates (identical specId + commitHash) are de-duplicated via a
+ * `Map` keyed on `"${specId}|${commitHash}"`.
+ */
+function scan(repoPath, specStoragePath, config) {
+    const pairs = new Map();
+    // ---- Strategy A: commit message scope ----
+    const commits = getAllCommits(repoPath);
+    for (const commit of commits) {
+        const specId = (0, scope_resolver_1.resolveScopeToSpec)(commit.message, specStoragePath, config);
+        if (!specId) {
+            (0, errors_1.logDebug)('Strategy A: no scope match', {
+                commitHash: commit.hash.slice(0, 7),
+                message: commit.message,
+            });
+            continue;
+        }
+        const specMetadata = (0, spec_extractor_1.extractSpecMetadata)(specStoragePath, specId, config);
+        const key = `${specId}|${commit.hash}`;
+        if (!pairs.has(key)) {
+            pairs.set(key, {
+                specId,
+                commitHash: commit.hash,
+                specMetadata,
+                commitMetadata: commit,
+            });
+        }
+    }
+    // ---- Strategy B: commit-info.md ----
+    // Collect specIds already paired by Strategy A.
+    const pairedSpecIds = new Set();
+    for (const pair of pairs.values()) {
+        pairedSpecIds.add(pair.specId);
+    }
+    const specs = (0, utils_1.discoverSpecs)(specStoragePath);
+    for (const spec of specs) {
+        if (pairedSpecIds.has(spec.specId)) {
+            continue;
+        }
+        const metadata = (0, spec_extractor_1.extractSpecMetadata)(specStoragePath, spec.specId, config);
+        if (!metadata) {
+            // extractSpecMetadata already logs the reason.
+            continue;
+        }
+        if (!metadata.commitHash) {
+            (0, errors_1.logDebug)('Strategy B: no commit hash in spec metadata', {
+                specId: spec.specId,
+            });
+            continue;
+        }
+        const commitInfo = getCommitInfo(repoPath, metadata.commitHash);
+        if (!commitInfo) {
+            (0, errors_1.logWarn)('Strategy B: commit-info.md hash does not match any known commit', {
+                specId: spec.specId,
+                commitHash: metadata.commitHash,
+            });
+            continue;
+        }
+        const key = `${spec.specId}|${metadata.commitHash}`;
+        if (!pairs.has(key)) {
+            pairs.set(key, {
+                specId: spec.specId,
+                commitHash: metadata.commitHash,
+                specMetadata: metadata,
+                commitMetadata: commitInfo,
+            });
+        }
+    }
+    return Array.from(pairs.values());
+}
+//# sourceMappingURL=git-scanner.js.map

package/dist/spec/mining/git-scanner.js.map

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

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

@@ -0,0 +1,53 @@
+/**
+ * Mining pipeline orchestrator — main entry point for reverse-mining 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 mining left off.
+ *
+ * @module spec/mining/pipeline
+ */
+import { SqliteDatabase } from '../../db/sqlite-adapter';
+import { SpecConfig } from '../config';
+export interface MiningResult {
+    specsFound: number;
+    commitsFound: number;
+    fragmentsFound: number;
+    relationsCreated: number;
+    totalEntries: number;
+    skippedEntries: Array<{
+        specId: string;
+        reason: string;
+    }>;
+}
+/**
+ * Run the full reverse-mining 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 `MiningResult` 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 runMiningPipeline(repoPath: string, specStoragePath: string, db: SqliteDatabase, config?: SpecConfig): MiningResult;
+//# sourceMappingURL=pipeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../../src/spec/mining/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAkB,MAAM,WAAW,CAAC;AAkBvD,MAAM,WAAW,YAAY;IAC3B,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;CAC3D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,cAAc,EAClB,MAAM,CAAC,EAAE,UAAU,GAClB,YAAY,CA6Hd"}