homegraph 1.2.0 → 1.5.0

package/dist/spec/git/commits.js.map

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

package/dist/spec/git/exec.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared `execFileSync` options for all Git calls across the spec module.
+ *
+ * @module spec/git/exec
+ */
+/** Shared options for all `execFileSync` Git calls across the spec module. */
+export declare function gitExecOptions(repoPath: string): {
+    cwd: string;
+    encoding: "utf8";
+    stdio: (number | import("stream") | import("child_process").IOType | "ipc" | null | undefined)[];
+    windowsHide: boolean;
+};
+//# sourceMappingURL=exec.d.ts.map

package/dist/spec/git/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../../src/spec/git/exec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM;;;;;EAQ9C"}

package/dist/spec/git/exec.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Shared `execFileSync` options for all Git calls across the spec module.
+ *
+ * @module spec/git/exec
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitExecOptions = gitExecOptions;
+/** Shared options for all `execFileSync` Git calls across the spec module. */
+function gitExecOptions(repoPath) {
+    const stdio = ['ignore', 'pipe', 'ignore'];
+    return {
+        cwd: repoPath,
+        encoding: 'utf8',
+        stdio,
+        windowsHide: true,
+    };
+}
+//# sourceMappingURL=exec.js.map

package/dist/spec/git/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../../src/spec/git/exec.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAKH,wCAQC;AATD,8EAA8E;AAC9E,SAAgB,cAAc,CAAC,QAAgB;IAC7C,MAAM,KAAK,GAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzD,OAAO;QACL,GAAG,EAAE,QAAQ;QACb,QAAQ,EAAE,MAAe;QACzB,KAAK;QACL,WAAW,EAAE,IAAI;KAClB,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,9 @@
+/**
+ * Git layer for the spec module — barrel export.
+ *
+ * Low-level, spec-agnostic Git access shared by the build, mine, and evolve
+ * pipelines.
+ */
+export { gitExecOptions } from './exec';
+export { CommitInfo, isGitRepo, getHeadHash, isAncestor, getAllCommits, getCommitRange, getCommitsUpTo, getCommitInfo, getParentHashes, getCommitDiff, } from './commits';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/spec/git/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EACL,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,WAAW,CAAC"}

package/dist/spec/git/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Git layer for the spec module — barrel export.
+ *
+ * Low-level, spec-agnostic Git access shared by the build, mine, and evolve
+ * pipelines.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCommitDiff = exports.getParentHashes = exports.getCommitInfo = exports.getCommitsUpTo = exports.getCommitRange = exports.getAllCommits = exports.isAncestor = exports.getHeadHash = exports.isGitRepo = exports.gitExecOptions = void 0;
+var exec_1 = require("./exec");
+Object.defineProperty(exports, "gitExecOptions", { enumerable: true, get: function () { return exec_1.gitExecOptions; } });
+var commits_1 = require("./commits");
+Object.defineProperty(exports, "isGitRepo", { enumerable: true, get: function () { return commits_1.isGitRepo; } });
+Object.defineProperty(exports, "getHeadHash", { enumerable: true, get: function () { return commits_1.getHeadHash; } });
+Object.defineProperty(exports, "isAncestor", { enumerable: true, get: function () { return commits_1.isAncestor; } });
+Object.defineProperty(exports, "getAllCommits", { enumerable: true, get: function () { return commits_1.getAllCommits; } });
+Object.defineProperty(exports, "getCommitRange", { enumerable: true, get: function () { return commits_1.getCommitRange; } });
+Object.defineProperty(exports, "getCommitsUpTo", { enumerable: true, get: function () { return commits_1.getCommitsUpTo; } });
+Object.defineProperty(exports, "getCommitInfo", { enumerable: true, get: function () { return commits_1.getCommitInfo; } });
+Object.defineProperty(exports, "getParentHashes", { enumerable: true, get: function () { return commits_1.getParentHashes; } });
+Object.defineProperty(exports, "getCommitDiff", { enumerable: true, get: function () { return commits_1.getCommitDiff; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/spec/git/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,+BAAwC;AAA/B,sGAAA,cAAc,OAAA;AACvB,qCAWmB;AATjB,oGAAA,SAAS,OAAA;AACT,sGAAA,WAAW,OAAA;AACX,qGAAA,UAAU,OAAA;AACV,wGAAA,aAAa,OAAA;AACb,yGAAA,cAAc,OAAA;AACd,yGAAA,cAAc,OAAA;AACd,wGAAA,aAAa,OAAA;AACb,0GAAA,eAAe,OAAA;AACf,wGAAA,aAAa,OAAA"}

package/dist/spec/git-utils.d.ts

@@ -0,0 +1,8 @@
+/** Shared options for all `execFileSync` Git calls across the spec module. */
+export declare function gitExecOptions(repoPath: string): {
+    cwd: string;
+    encoding: "utf8";
+    stdio: (number | import("stream") | import("child_process").IOType | "ipc" | null | undefined)[];
+    windowsHide: boolean;
+};
+//# sourceMappingURL=git-utils.d.ts.map

package/dist/spec/git-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-utils.d.ts","sourceRoot":"","sources":["../../src/spec/git-utils.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM;;;;;EAQ9C"}

package/dist/spec/git-utils.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitExecOptions = gitExecOptions;
+/** Shared options for all `execFileSync` Git calls across the spec module. */
+function gitExecOptions(repoPath) {
+    const stdio = ['ignore', 'pipe', 'ignore'];
+    return {
+        cwd: repoPath,
+        encoding: 'utf8',
+        stdio,
+        windowsHide: true,
+    };
+}
+//# sourceMappingURL=git-utils.js.map

package/dist/spec/git-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-utils.js","sourceRoot":"","sources":["../../src/spec/git-utils.ts"],"names":[],"mappings":";;AAGA,wCAQC;AATD,8EAA8E;AAC9E,SAAgB,cAAc,CAAC,QAAgB;IAC7C,MAAM,KAAK,GAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzD,OAAO;QACL,GAAG,EAAE,QAAQ;QACb,QAAQ,EAAE,MAAe;QACzB,KAAK;QACL,WAAW,EAAE,IAAI;KAClB,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,8 @@
+/**
+ * Spec Graph Layer — Barrel Export
+ *
+ * Composition-layer queries over the Spec→Commit→CodeFragment knowledge
+ * graph. Consumers can `import { ... } from '../spec/graph'`.
+ */
+export { getSpecContext, findSpecsByFragmentPath, findSpecsByFilePath, FindSpecsByFilePathResult, getSpecStats, searchAndGetContext, findSpecsByCodeSymbol, CodeEntityInfo, CodeEntitySpecMatch, FindSpecsByCodeSymbolResult, } from './queries';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/spec/graph/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,EACzB,YAAY,EACZ,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,WAAW,CAAC"}

package/dist/spec/graph/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Spec Graph Layer — Barrel Export
+ *
+ * Composition-layer queries over the Spec→Commit→CodeFragment knowledge
+ * graph. Consumers can `import { ... } from '../spec/graph'`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findSpecsByCodeSymbol = exports.searchAndGetContext = exports.getSpecStats = exports.findSpecsByFilePath = exports.findSpecsByFragmentPath = exports.getSpecContext = void 0;
+var queries_1 = require("./queries");
+Object.defineProperty(exports, "getSpecContext", { enumerable: true, get: function () { return queries_1.getSpecContext; } });
+Object.defineProperty(exports, "findSpecsByFragmentPath", { enumerable: true, get: function () { return queries_1.findSpecsByFragmentPath; } });
+Object.defineProperty(exports, "findSpecsByFilePath", { enumerable: true, get: function () { return queries_1.findSpecsByFilePath; } });
+Object.defineProperty(exports, "getSpecStats", { enumerable: true, get: function () { return queries_1.getSpecStats; } });
+Object.defineProperty(exports, "searchAndGetContext", { enumerable: true, get: function () { return queries_1.searchAndGetContext; } });
+Object.defineProperty(exports, "findSpecsByCodeSymbol", { enumerable: true, get: function () { return queries_1.findSpecsByCodeSymbol; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/spec/graph/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,qCAWmB;AAVjB,yGAAA,cAAc,OAAA;AACd,kHAAA,uBAAuB,OAAA;AACvB,8GAAA,mBAAmB,OAAA;AAEnB,uGAAA,YAAY,OAAA;AACZ,8GAAA,mBAAmB,OAAA;AACnB,gHAAA,qBAAqB,OAAA"}

package/dist/spec/graph/queries.d.ts

@@ -3,9 +3,15 @@
  *
  * Replaces `commit4spec/graph/queries.py`. Provides spec context retrieval,
  * stats, and search+traverse functionality.
+ *
+ * This is a pure COMPOSITION layer — following the HomeGraph convention of
+ * `src/graph` (zero SQL outside the db layer), every function here is built
+ * by composing the primitives in `../db`. Scoring, sorting, and result
+ * assembly live here; data access does not.
  */
 import { SqliteDatabase } from '../../db/sqlite-adapter';
 import { SpecContext, SpecStats } from '../types';
+export { findSpecsByFilePath, FindSpecsByFilePathResult, } from '../db/relations';
 /**
  * Retrieve full context for a Spec — the spec node itself, all linked
  * commits (with their relation types), and optionally the code fragments
@@ -31,41 +37,6 @@ export declare function getSpecContext(db: SqliteDatabase, specId: string, maxCo
  * @returns Array of distinct spec IDs.
  */
 export declare function findSpecsByFragmentPath(db: SqliteDatabase, filePath: string): string[];
-/** Result container returned by findSpecsByFilePath. */
-export interface FindSpecsByFilePathResult {
-    /** Matching spec entries (capped at maxResults). */
-    results: Array<{
-        id: string;
-        title: string;
-        status: string;
-        version: number;
-        filePath: string;
-    }>;
-    /** Number of results actually returned (<= maxResults). */
-    matched_count: number;
-    /** True when more results exist beyond the cap. */
-    truncated: boolean;
-}
-/**
- * Find specs whose code fragments reference the given file path.
- *
- * Traverses: filePath -> code_fragment_nodes -> commit_fragment_relations
- * -> commit_nodes -> spec_commit_relations -> spec_nodes.
- *
- * Uses LIKE matching against code_fragment_nodes.file_path, so partial
- * paths work (e.g. `src/auth.ts` matches `src/auth/login.ts` and
- * `app/src/auth.ts`).  LIKE metacharacters (`%`, `_`, `\`) in the
- * filePath are automatically escaped.
- *
- * An empty or whitespace-only filePath is rejected with an error
- * (it would match every spec in the graph).
- *
- * @param db         Active SQLite database handle.
- * @param filePath   File path to search for (substring LIKE match).
- * @param maxResults Maximum number of results to return (default 100).
- * @returns FindSpecsByFilePathResult with .results, .matched_count, and .truncated.
- */
-export declare function findSpecsByFilePath(db: SqliteDatabase, filePath: string, maxResults?: number): FindSpecsByFilePathResult;
 /**
  * Compute statistics about the Spec knowledge graph.
  *

package/dist/spec/graph/queries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/spec/graph/queries.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAIL,WAAW,EAEX,SAAS,EACV,MAAM,UAAU,CAAC;AAoElB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,MAAU,EACtB,gBAAgB,GAAE,OAAc,GAC/B,WAAW,GAAG,IAAI,CAyEpB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,cAAc,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,EAAE,CAaV;AASD,wDAAwD;AACxD,MAAM,WAAW,yBAAyB;IACxC,oDAAoD;IACpD,OAAO,EAAE,KAAK,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,cAAc,EAClB,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,MAAsC,GACjD,yBAAyB,CAkD3B;AAGD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,cAAc,GAAG,SAAS,CAqD1D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAW,EACjB,gBAAgB,GAAE,OAAc,GAC/B,WAAW,EAAE,CAwBf;AAMD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,WAAW,EAAE;QACX,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,kDAAkD;AAClD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;CACzB;AAwBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,cAAc,EACtB,IAAI,GAAE,MAAW,GAChB,2BAA2B,CA0J7B"}
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/spec/graph/queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAEL,WAAW,EAEX,SAAS,EAEV,MAAM,UAAU,CAAC;AAclB,OAAO,EACL,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAazB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,MAAU,EACtB,gBAAgB,GAAE,OAAc,GAC/B,WAAW,GAAG,IAAI,CA0BpB;AAMD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,cAAc,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,EAAE,CAEV;AAMD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,cAAc,GAAG,SAAS,CAW1D;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAW,EACjB,gBAAgB,GAAE,OAAc,GAC/B,WAAW,EAAE,CAwBf;AAMD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,WAAW,EAAE;QACX,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,kDAAkD;AAClD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;CACzB;AAcD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,cAAc,EACtB,IAAI,GAAE,MAAW,GAChB,2BAA2B,CA4F7B"}

package/dist/spec/graph/queries.js

@@ -4,46 +4,38 @@
  *
  * Replaces `commit4spec/graph/queries.py`. Provides spec context retrieval,
  * stats, and search+traverse functionality.
+ *
+ * This is a pure COMPOSITION layer — following the HomeGraph convention of
+ * `src/graph` (zero SQL outside the db layer), every function here is built
+ * by composing the primitives in `../db`. Scoring, sorting, and result
+ * assembly live here; data access does not.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.findSpecsByFilePath = void 0;
 exports.getSpecContext = getSpecContext;
 exports.findSpecsByFragmentPath = findSpecsByFragmentPath;
-exports.findSpecsByFilePath = findSpecsByFilePath;
 exports.getSpecStats = getSpecStats;
 exports.searchAndGetContext = searchAndGetContext;
 exports.findSpecsByCodeSymbol = findSpecsByCodeSymbol;
+const spec_node_1 = require("../db/spec-node");
+const commit_node_1 = require("../db/commit-node");
+const fragment_node_1 = require("../db/fragment-node");
+const relations_1 = require("../db/relations");
 const fts_1 = require("../db/fts");
+// Re-export so existing consumers of the graph layer keep their imports.
+var relations_2 = require("../db/relations");
+Object.defineProperty(exports, "findSpecsByFilePath", { enumerable: true, get: function () { return relations_2.findSpecsByFilePath; } });
 // ===========================================================================
-// Private helpers
+// getSpecContext
 // ===========================================================================
-/**
- * Parse a JSON string into a string array, returning [] on any failure.
- */
-function _parseSubtitles(raw) {
-    try {
-        return JSON.parse(raw || '[]');
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Convert a DB row (snake_case keys) to a SpecNode (camelCase).
- */
-function _rowToSpecNode(row) {
-    return {
-        id: row.id,
-        title: row.title,
-        subtitles: _parseSubtitles(row.subtitles),
-        status: row.status,
-        version: row.version,
-        filePath: row.file_path,
-        timestamp: row.timestamp,
-    };
+/** Relation-type priority for commit ordering (lower = earlier). */
+function relationPriority(relationType) {
+    if (relationType === 'GENERATE')
+        return 0;
+    if (relationType === 'SUMMARIZED_FROM')
+        return 1;
+    return 2;
 }
-// ===========================================================================
-// Public API
-// ===========================================================================
 /**
  * Retrieve full context for a Spec — the spec node itself, all linked
  * commits (with their relation types), and optionally the code fragments
@@ -60,66 +52,33 @@ function _rowToSpecNode(row) {
  * @returns SpecContext on success, or null when the spec is not found.
  */
 function getSpecContext(db, specId, maxCommits = 5, includeFragments = true) {
-    // 1. Look up the spec by id
-    const specRow = db
-        .prepare(`SELECT id, title, subtitles, status, version, file_path, timestamp
-       FROM spec_nodes
-       WHERE id = ?`)
-        .get(specId);
-    if (!specRow)
+    const spec = (0, spec_node_1.findSpecById)(db, specId);
+    if (!spec)
         return null;
-    const spec = _rowToSpecNode(specRow);
-    // 2. Query linked commits with priority ordering
-    const commitRows = db
-        .prepare(`SELECT c.hash, c.message, c.author, c.timestamp, r.relation_type
-       FROM spec_commit_relations r
-       JOIN commit_nodes c ON c.hash = r.commit_hash
-       WHERE r.spec_id = ?
-       ORDER BY
-         CASE r.relation_type
-           WHEN 'GENERATE' THEN 0
-           WHEN 'SUMMARIZED_FROM' THEN 1
-           ELSE 2
-         END,
-         c.timestamp DESC
-       LIMIT ?`)
-        .all(specId, maxCommits);
-    // 3. Build commit contexts (with optional fragments)
-    const commits = [];
-    for (const crow of commitRows) {
-        const commit = {
-            hash: crow.hash,
-            message: crow.message,
-            author: crow.author,
-            timestamp: crow.timestamp,
-        };
-        let fragments = [];
-        if (includeFragments) {
-            const fragRows = db
-                .prepare(`SELECT f.id, f.change_type, f.file_path, f.start_line,
-                  f.end_line, f.code_diff
-           FROM commit_fragment_relations r
-           JOIN code_fragment_nodes f ON f.id = r.fragment_id
-           WHERE r.commit_hash = ?
-           ORDER BY f.file_path, f.start_line`)
-                .all(crow.hash);
-            fragments = fragRows.map((fr) => ({
-                id: fr.id,
-                changeType: fr.change_type,
-                filePath: fr.file_path,
-                startLine: fr.start_line,
-                endLine: fr.end_line,
-                codeDiff: fr.code_diff,
-            }));
-        }
-        commits.push({
-            commit,
-            relationType: crow.relation_type,
-            fragments,
-        });
-    }
+    const linked = (0, relations_1.findCommitsBySpec)(db, specId);
+    // Order by relation-type priority, then timestamp descending.
+    const sorted = [...linked].sort((a, b) => {
+        const pa = relationPriority(a.relationType);
+        const pb = relationPriority(b.relationType);
+        if (pa !== pb)
+            return pa - pb;
+        return b.timestamp - a.timestamp;
+    });
+    const commits = sorted.slice(0, maxCommits).map((row) => ({
+        commit: {
+            hash: row.commitHash,
+            message: row.message,
+            author: row.author,
+            timestamp: row.timestamp,
+        },
+        relationType: row.relationType,
+        fragments: includeFragments ? (0, fragment_node_1.findFragmentsByCommit)(db, row.commitHash) : [],
+    }));
     return { spec, commits };
 }
+// ===========================================================================
+// findSpecsByFragmentPath
+// ===========================================================================
 /**
  * Find all spec IDs related to code fragments whose file path matches
  * the given substring.
@@ -129,76 +88,11 @@ function getSpecContext(db, specId, maxCommits = 5, includeFragments = true) {
  * @returns Array of distinct spec IDs.
  */
 function findSpecsByFragmentPath(db, filePath) {
-    const pattern = `%${filePath}%`;
-    const rows = db
-        .prepare(`SELECT DISTINCT r.spec_id
-       FROM spec_commit_relations r
-       JOIN commit_fragment_relations cfr ON cfr.commit_hash = r.commit_hash
-       JOIN code_fragment_nodes cf ON cf.id = cfr.fragment_id
-       WHERE cf.file_path LIKE ?`)
-        .all(pattern);
-    return rows.map((r) => r.spec_id);
+    return (0, relations_1.findSpecIdsByFragmentPath)(db, filePath);
 }
 // ===========================================================================
-// findSpecsByFilePath
+// getSpecStats
 // ===========================================================================
-/** Default max results returned by findSpecsByFilePath. */
-const DEFAULT_MAX_SPEC_FIND_RESULTS = 100;
-/**
- * Find specs whose code fragments reference the given file path.
- *
- * Traverses: filePath -> code_fragment_nodes -> commit_fragment_relations
- * -> commit_nodes -> spec_commit_relations -> spec_nodes.
- *
- * Uses LIKE matching against code_fragment_nodes.file_path, so partial
- * paths work (e.g. `src/auth.ts` matches `src/auth/login.ts` and
- * `app/src/auth.ts`).  LIKE metacharacters (`%`, `_`, `\`) in the
- * filePath are automatically escaped.
- *
- * An empty or whitespace-only filePath is rejected with an error
- * (it would match every spec in the graph).
- *
- * @param db         Active SQLite database handle.
- * @param filePath   File path to search for (substring LIKE match).
- * @param maxResults Maximum number of results to return (default 100).
- * @returns FindSpecsByFilePathResult with .results, .matched_count, and .truncated.
- */
-function findSpecsByFilePath(db, filePath, maxResults = DEFAULT_MAX_SPEC_FIND_RESULTS) {
-    // Guard against empty input that would match every spec
-    if (!filePath || filePath.trim().length === 0) {
-        throw new Error('Empty file path is not allowed -- it would match every spec in the knowledge graph. ' +
-            'Provide a concrete file path (e.g. "src/auth.ts") or a partial path (e.g. "src/auth").');
-    }
-    // Escape LIKE metacharacters (SQLite ESCAPE '\' is used in the query)
-    const escaped = filePath
-        .replace(/\\/g, '\\\\') // literal backslash
-        .replace(/%/g, '\\%') // percent wildcard
-        .replace(/_/g, '\\_'); // underscore wildcard
-    const pattern = `%${escaped}%`;
-    const rows = db
-        .prepare(`SELECT DISTINCT s.id, s.title, s.status, s.version, s.file_path
-       FROM spec_nodes s
-       JOIN spec_commit_relations scr ON scr.spec_id = s.id
-       JOIN commit_fragment_relations cfr ON cfr.commit_hash = scr.commit_hash
-       JOIN code_fragment_nodes cf ON cf.id = cfr.fragment_id
-       WHERE cf.file_path LIKE ? ESCAPE '\\'
-       ORDER BY s.id
-       LIMIT ?`)
-        .all(pattern, maxResults + 1);
-    const truncated = rows.length > maxResults;
-    const slice = truncated ? rows.slice(0, maxResults) : rows;
-    return {
-        results: slice.map((r) => ({
-            id: r.id,
-            title: r.title,
-            status: r.status,
-            version: r.version,
-            filePath: r.file_path,
-        })),
-        matched_count: slice.length,
-        truncated,
-    };
-}
 /**
  * Compute statistics about the Spec knowledge graph.
  *
@@ -206,35 +100,19 @@ function findSpecsByFilePath(db, filePath, maxResults = DEFAULT_MAX_SPEC_FIND_RE
  * @returns SpecStats with entity counts and relation totals.
  */
 function getSpecStats(db) {
-    const specCount = db.prepare('SELECT COUNT(*) as cnt FROM spec_nodes').get().cnt;
-    const commitCount = db.prepare('SELECT COUNT(*) as cnt FROM commit_nodes').get().cnt;
-    const fragmentCount = db
-        .prepare('SELECT COUNT(*) as cnt FROM code_fragment_nodes')
-        .get().cnt;
-    const scrCount = db
-        .prepare('SELECT COUNT(*) as cnt FROM spec_commit_relations')
-        .get().cnt;
-    const cfrCount = db
-        .prepare('SELECT COUNT(*) as cnt FROM commit_fragment_relations')
-        .get().cnt;
-    const ssrCount = db
-        .prepare('SELECT COUNT(*) as cnt FROM spec_spec_relations')
-        .get().cnt;
-    const activeSpecCount = db
-        .prepare("SELECT COUNT(*) as cnt FROM spec_nodes WHERE status = 'active'")
-        .get().cnt;
-    const deprecatedSpecCount = db
-        .prepare("SELECT COUNT(*) as cnt FROM spec_nodes WHERE status = 'deprecated'")
-        .get().cnt;
+    const { active, deprecated } = (0, spec_node_1.countSpecsByStatus)(db);
     return {
-        specCount,
-        commitCount,
-        fragmentCount,
-        relationCount: scrCount + cfrCount + ssrCount,
-        activeSpecCount,
-        deprecatedSpecCount,
+        specCount: active + deprecated,
+        commitCount: (0, commit_node_1.countCommits)(db),
+        fragmentCount: (0, fragment_node_1.countFragments)(db),
+        relationCount: (0, relations_1.countAllRelations)(db),
+        activeSpecCount: active,
+        deprecatedSpecCount: deprecated,
     };
 }
+// ===========================================================================
+// searchAndGetContext
+// ===========================================================================
 /**
  * Full-text search for specs and return full context for each match.
  *
@@ -284,15 +162,6 @@ const WEIGHTS = {
 };
 /** Maximum candidates to consider from the initial file-path JOIN. */
 const MAX_CANDIDATES = 200;
-/**
- * Escape LIKE metacharacters in a string, also escaping the escape character.
- */
-function escapeLike(str) {
-    return str
-        .replace(/\\/g, '\\\\')
-        .replace(/%/g, '\\%')
-        .replace(/_/g, '\\_');
-}
 /**
  * Find Specs associated with a code entity by multi-dimensional scoring:
  *
@@ -312,65 +181,20 @@ function escapeLike(str) {
  * @returns Ranked, scored matches with score breakdowns
  */
 function findSpecsByCodeSymbol(specDb, entity, topK = 10) {
-    const pathEscaped = escapeLike(entity.filePath);
-    const likePattern = `%${pathEscaped}%`;
-    const suffixLikePattern = `%${pathEscaped}`; // cf.file_path ends with entity's path
     // -----------------------------------------------------------------------
     // 1. Gather candidates: all specs whose fragments touch the entity's file
     // -----------------------------------------------------------------------
-    const candidateRows = specDb
-        .prepare(`
-      SELECT
-          s.id, s.title, s.status, s.version, s.file_path, s.timestamp,
-          MAX(
-            MIN(cf.end_line, @entityEnd) - MAX(cf.start_line, @entityStart) + 1,
-            0
-          ) AS overlap_lines,
-          COUNT(DISTINCT cf.id) AS fragment_count,
-          COUNT(DISTINCT scr.commit_hash) AS commit_count,
-          MAX(CASE
-            WHEN cf.file_path = @exactFilePath THEN 3
-            WHEN cf.file_path LIKE @suffixLikePattern ESCAPE '\\' THEN 2
-            ELSE 1
-          END) AS file_path_match_level
-      FROM spec_nodes s
-      JOIN spec_commit_relations scr ON scr.spec_id = s.id
-      JOIN commit_fragment_relations cfr ON cfr.commit_hash = scr.commit_hash
-      JOIN code_fragment_nodes cf ON cf.id = cfr.fragment_id
-      WHERE s.status = 'active'
-        AND cf.file_path LIKE @likePattern ESCAPE '\\'
-      GROUP BY s.id
-      ORDER BY s.timestamp DESC
-      LIMIT @maxCandidates
-    `)
-        .all({
-        entityEnd: entity.endLine,
-        entityStart: entity.startLine,
-        exactFilePath: entity.filePath,
-        suffixLikePattern,
-        likePattern,
+    const candidateRows = (0, relations_1.findSpecCandidatesByFilePath)(specDb, {
+        filePath: entity.filePath,
+        startLine: entity.startLine,
+        endLine: entity.endLine,
         maxCandidates: MAX_CANDIDATES,
     });
     // -----------------------------------------------------------------------
     // 2. Content-match signal: search code_fragments_fts for the entity name
     // -----------------------------------------------------------------------
-    const contentFragmentIds = new Set((0, fts_1.searchCodeFragments)(specDb, entity.name, 50));
-    // Map from spec_id → whether any of its fragments matched in content search
-    const contentSpecIds = new Set();
-    if (contentFragmentIds.size > 0) {
-        const fragsIn = [...contentFragmentIds].map(() => '?').join(',');
-        const contentSpecRows = specDb
-            .prepare(`
-        SELECT DISTINCT scr.spec_id
-        FROM commit_fragment_relations cfr
-        JOIN spec_commit_relations scr ON scr.commit_hash = cfr.commit_hash
-        WHERE cfr.fragment_id IN (${fragsIn})
-      `)
-            .all(...contentFragmentIds);
-        for (const r of contentSpecRows) {
-            contentSpecIds.add(r.spec_id);
-        }
-    }
+    const contentFragmentIds = (0, fts_1.searchCodeFragments)(specDb, entity.name, 50);
+    const contentSpecIds = new Set((0, relations_1.findSpecIdsByFragmentIds)(specDb, contentFragmentIds));
     // -----------------------------------------------------------------------
     // 3. Name-match signal: search specs_fts for the entity name
     // -----------------------------------------------------------------------
@@ -387,20 +211,19 @@ function findSpecsByCodeSymbol(specDb, entity, topK = 10) {
     const entityLength = Math.max(1, entity.endLine - entity.startLine + 1);
     const scored = candidateRows.map((row) => {
         // 4a. File-path score — derived from the best-matching fragment's file_path
-        // (computed in SQL as file_path_match_level: 3=exact, 2=suffix, 1=LIKE)
-        const filePathScore = row.file_path_match_level === 3 ? 1.0
-            : row.file_path_match_level === 2 ? 0.8
+        // (computed in SQL as filePathMatchLevel: 3=exact, 2=suffix, 1=LIKE)
+        const filePathScore = row.filePathMatchLevel === 3 ? 1.0
+            : row.filePathMatchLevel === 2 ? 0.8
                 : 0.6;
         // 4b. Content score
         const contentScore = contentSpecIds.has(row.id) ? 1.0 : 0;
         // 4c. Name score
         const nameScore = nameScoreMap.get(row.id) ?? 0;
-        // 4d. Recency score: MapSpec(timestamp, 0, maxTs)MapSpec => [0, 1]
+        // 4d. Recency score — decays to 0.5 after ~180 days
         const daysSinceUpdate = (now - row.timestamp) / (1000 * 60 * 60 * 24);
         const recencyScore = 1 / (1 + Math.max(0, daysSinceUpdate) / 180);
         // 4e. Overlap score
-        const overlapRatio = Math.min(1.0, row.overlap_lines / entityLength);
-        const overlapScore = overlapRatio;
+        const overlapScore = Math.min(1.0, row.overlapLines / entityLength);
         const score = filePathScore * WEIGHTS.filePath +
             contentScore * WEIGHTS.content +
             nameScore * WEIGHTS.name +
@@ -412,7 +235,7 @@ function findSpecsByCodeSymbol(specDb, entity, topK = 10) {
                 title: row.title,
                 status: row.status,
                 version: row.version,
-                filePath: row.file_path,
+                filePath: row.filePath,
                 timestamp: row.timestamp,
             },
             score,
@@ -423,8 +246,8 @@ function findSpecsByCodeSymbol(specDb, entity, topK = 10) {
                 recencyScore,
                 overlapScore,
             },
-            fragmentCount: row.fragment_count,
-            commitCount: row.commit_count,
+            fragmentCount: row.fragmentCount,
+            commitCount: row.commitCount,
         };
     });
     // -----------------------------------------------------------------------