@esneiderbravo/speclaw 0.3.0 → 0.3.1

package/dist/modules/compass/db.js

@@ -47,9 +47,17 @@ CREATE TABLE IF NOT EXISTS node_embeddings (
   model TEXT NOT NULL,
   vec BLOB NOT NULL
 );
+-- git_history_cache: memoized results of the expensive git-history scans
+-- (churn, co-change), keyed by query and invalidated when HEAD moves.
+CREATE TABLE IF NOT EXISTS git_history_cache (
+  query_key TEXT PRIMARY KEY,
+  head_sha TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  computed_at INTEGER NOT NULL
+);
 `;
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "3";
+export const SCHEMA_VERSION = "4";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -81,6 +89,7 @@ function isStale(db) {
 /** Drop every table (children first) so the current schema can be recreated cleanly. */
 function resetSchema(db) {
     db.exec(`
+    DROP TABLE IF EXISTS git_history_cache;
     DROP TABLE IF EXISTS node_embeddings;
     DROP TABLE IF EXISTS edges;
     DROP TABLE IF EXISTS nodes;

package/dist/modules/compass/git-history-cache.js

@@ -0,0 +1,65 @@
+import { churn, coChanges, headSha, } from "../../shared/git-history.js";
+import { openDb } from "./db.js";
+/**
+ * Look up a cached payload valid at the current HEAD, or compute it and store it.
+ *
+ * When `head` is `null` (no commits / not a repo) the cache is bypassed entirely
+ * and `compute()` runs directly, so an empty repo never poisons the cache.
+ *
+ * @param projectPath - Project root, whose `.speclaw/index.db` holds the cache.
+ * @param head - The current HEAD SHA, or `null` when there is none.
+ * @param queryKey - Stable key identifying this query (function + options).
+ * @param compute - Produces the fresh result on a miss.
+ * @param serialize - Turns the result into a JSON-safe payload string.
+ * @param deserialize - Rebuilds the result from a stored payload string.
+ * @returns The cached-or-freshly-computed result.
+ */
+function readThrough(projectPath, head, queryKey, compute, serialize, deserialize) {
+    if (head === null)
+        return compute();
+    const db = openDb(projectPath);
+    try {
+        const row = db
+            .prepare("SELECT head_sha, payload FROM git_history_cache WHERE query_key = ?")
+            .get(queryKey);
+        if (row && row.head_sha === head) {
+            return deserialize(row.payload);
+        }
+        const value = compute();
+        db.prepare(`INSERT INTO git_history_cache(query_key, head_sha, payload, computed_at)
+       VALUES (?, ?, ?, 0)
+       ON CONFLICT(query_key) DO UPDATE SET
+         head_sha = excluded.head_sha,
+         payload = excluded.payload,
+         computed_at = excluded.computed_at`).run(queryKey, head, serialize(value));
+        return value;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * {@link churn}, memoized in the Compass index until `HEAD` moves.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Same options as {@link churn}.
+ * @returns Per-path change counts and the shallow marker, cached per HEAD.
+ */
+export function cachedChurn(projectPath, opts = {}) {
+    const key = `churn:${JSON.stringify({ since: opts.since ?? null, pathspec: opts.pathspec ?? null })}`;
+    return readThrough(projectPath, headSha(projectPath), key, () => churn(projectPath, opts), (value) => JSON.stringify({ shallow: value.shallow, byPath: [...value.byPath] }), (payload) => {
+        const parsed = JSON.parse(payload);
+        return { shallow: parsed.shallow, byPath: new Map(parsed.byPath) };
+    });
+}
+/**
+ * {@link coChanges}, memoized in the Compass index until `HEAD` moves.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Same options as {@link coChanges}.
+ * @returns The co-change pairs and the shallow marker, cached per HEAD.
+ */
+export function cachedCoChanges(projectPath, opts = {}) {
+    const key = `coChanges:${JSON.stringify({ since: opts.since ?? null, minSupport: opts.minSupport ?? null })}`;
+    return readThrough(projectPath, headSha(projectPath), key, () => coChanges(projectPath, opts), (value) => JSON.stringify(value), (payload) => JSON.parse(payload));
+}

package/dist/shared/git-history.js

@@ -0,0 +1,204 @@
+import { spawnSync } from "node:child_process";
+/** ASCII NUL — the record/field separator git emits with `-z` and we request via `%x00`. */
+const NUL = "\0";
+/**
+ * Run git in `projectPath` and return stdout, or `null` on any failure.
+ *
+ * Best-effort like {@link isGitRepo}: git missing, not a repo, or a non-zero
+ * exit all yield `null` so callers can fail soft rather than throw.
+ */
+function git(projectPath, args) {
+    // `core.quotePath=false` keeps non-ASCII paths as raw UTF-8 instead of git's
+    // default octal-escaped, double-quoted form — so our path parsing stays exact.
+    const res = spawnSync("git", ["-C", projectPath, "-c", "core.quotePath=false", ...args], {
+        encoding: "utf8",
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (res.status !== 0 || typeof res.stdout !== "string")
+        return null;
+    return res.stdout;
+}
+/** Parse a `--numstat` count field: `-` (binary) becomes `0`, anything non-numeric too. */
+function numstat(field) {
+    if (field === "-")
+        return 0;
+    const n = Number.parseInt(field, 10);
+    return Number.isFinite(n) ? n : 0;
+}
+/**
+ * The current `HEAD` commit SHA, or `null` when the repo has no commits yet
+ * (or is not a repo / git is unavailable).
+ *
+ * @param projectPath - Directory inside the work tree to query.
+ * @returns The 40-char SHA, or `null`.
+ */
+export function headSha(projectPath) {
+    const out = git(projectPath, ["rev-parse", "HEAD"]);
+    const sha = out?.trim();
+    return sha ? sha : null;
+}
+/**
+ * Whether `projectPath` is inside a shallow clone (e.g. CI's `--depth=1`), where
+ * history is truncated and change/coupling counts would be misleadingly low.
+ *
+ * @param projectPath - Directory inside the work tree to query.
+ * @returns `true` only when git reports the repository is shallow.
+ */
+export function isShallowRepo(projectPath) {
+    const out = git(projectPath, ["rev-parse", "--is-shallow-repository"]);
+    return out?.trim() === "true";
+}
+/**
+ * The commits that touched `relPath`, most-recent first, with the line churn
+ * each introduced there.
+ *
+ * Fail-soft: a path with no history, a repo with no commits, or an unavailable
+ * git binary all yield an empty list. Records are parsed over NUL separators, so
+ * paths containing spaces or unicode are handled correctly.
+ *
+ * `since`/`until` bound the history as a **revision range** (`since..until`,
+ * `until` defaulting to `HEAD`) — the exact, deterministic form drift needs
+ * (`<archived-sha>..HEAD`), not an approximate date window. `since` is exclusive.
+ *
+ * @param projectPath - Project root to query.
+ * @param relPath - Project-relative path whose history to read.
+ * @param opts - Optional revision bounds: `since` (exclusive lower bound) and
+ *   `until` (upper bound, default `HEAD`) — any revision git accepts, e.g. a SHA.
+ * @returns The touching commits, newest first; empty when there is no history.
+ */
+export function logForPath(projectPath, relPath, opts = {}) {
+    const range = [];
+    if (opts.since)
+        range.push(`${opts.since}..${opts.until ?? "HEAD"}`);
+    else if (opts.until)
+        range.push(opts.until);
+    // Per commit: <sha>\0<ts>\0 then one numstat line per file it touched.
+    const out = git(projectPath, [
+        "log",
+        "--format=%x00%H%x00%ct%x00",
+        "--numstat",
+        ...range,
+        "--",
+        relPath,
+    ]);
+    if (out === null)
+        return [];
+    const touches = [];
+    // The stream is a sequence of "\0<sha>\0<ts>\0<numstat lines>" per commit.
+    const records = out.split(NUL);
+    // records[0] is empty (leading NUL); then repeating [sha, ts, tail...] where
+    // `tail` holds the numstat lines for that commit up to the next leading NUL.
+    for (let i = 1; i + 1 < records.length; i += 3) {
+        const sha = records[i]?.trim();
+        const ts = Number.parseInt(records[i + 1] ?? "", 10);
+        const tail = records[i + 2] ?? "";
+        if (!sha || !Number.isFinite(ts))
+            continue;
+        let added = 0;
+        let deleted = 0;
+        for (const line of tail.split("\n")) {
+            const cols = line.split("\t");
+            if (cols.length < 3)
+                continue;
+            added += numstat(cols[0]);
+            deleted += numstat(cols[1]);
+        }
+        touches.push({ sha, ts, added, deleted });
+    }
+    return touches;
+}
+/**
+ * How many commits touched each file in the window, summed from `--numstat`.
+ *
+ * Fail-soft: yields an empty map on any git failure. Does not follow renames —
+ * a renamed file is counted under its path as it appears in each commit (a safe
+ * superset, not a precise lineage). The result carries the {@link isShallowRepo}
+ * marker so consumers can degrade to "insufficient data" on a shallow clone.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Optional `since` window (any date/revision git accepts) and a
+ *   `pathspec` list to restrict which paths are considered.
+ * @returns Per-path change counts and the shallow marker.
+ */
+export function churn(projectPath, opts = {}) {
+    const shallow = isShallowRepo(projectPath);
+    const args = ["log", "--numstat", "--format=%x00"];
+    if (opts.since)
+        args.push(`--since=${opts.since}`);
+    if (opts.pathspec && opts.pathspec.length > 0)
+        args.push("--", ...opts.pathspec);
+    const out = git(projectPath, args);
+    const byPath = new Map();
+    if (out === null)
+        return { shallow, byPath };
+    for (const line of out.split("\n")) {
+        // Numstat rows are "<added>\t<deleted>\t<path>"; the %x00 format lines and
+        // blank lines have no tabs and are skipped.
+        const cols = line.split("\t");
+        if (cols.length < 3)
+            continue;
+        const path = cols[2].replace(/^\0+/, "").trim();
+        if (!path)
+            continue;
+        byPath.set(path, (byPath.get(path) ?? 0) + 1);
+    }
+    return { shallow, byPath };
+}
+/**
+ * For every pair of files that changed together, how many commits touched both.
+ *
+ * Groups each commit's changed files and emits a count per unordered pair. Pairs
+ * with fewer than `minSupport` shared commits are omitted. Fail-soft (empty on
+ * git failure) and does not follow renames. Carries the shallow marker.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Optional `since` window and `minSupport` threshold (default `1`).
+ * @returns The qualifying co-change pairs and the shallow marker.
+ */
+export function coChanges(projectPath, opts = {}) {
+    const shallow = isShallowRepo(projectPath);
+    const minSupport = opts.minSupport ?? 1;
+    const args = ["log", "--name-only", "--format=%x00"];
+    if (opts.since)
+        args.push(`--since=${opts.since}`);
+    const out = git(projectPath, args);
+    if (out === null)
+        return { shallow, pairs: [] };
+    const counts = new Map();
+    // Each commit's file list is the run of lines between two %x00 markers.
+    for (const commitBlock of out.split(NUL)) {
+        const files = commitBlock
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0);
+        const unique = [...new Set(files)].sort();
+        for (let i = 0; i < unique.length; i++) {
+            for (let j = i + 1; j < unique.length; j++) {
+                const key = `${unique[i]}\t${unique[j]}`;
+                counts.set(key, (counts.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    const pairs = [];
+    for (const [key, count] of counts) {
+        if (count < minSupport)
+            continue;
+        const [a, b] = key.split("\t");
+        pairs.push({ a: a, b: b, count });
+    }
+    pairs.sort((x, y) => y.count - x.count || x.a.localeCompare(y.a) || x.b.localeCompare(y.b));
+    return { shallow, pairs };
+}
+/**
+ * The SHA of the most recent commit that touched `relPath`, or `null` when the
+ * path has no history (or on any git failure).
+ *
+ * @param projectPath - Project root to query.
+ * @param relPath - Project-relative path.
+ * @returns The last-touching commit SHA, or `null`.
+ */
+export function lastTouch(projectPath, relPath) {
+    const out = git(projectPath, ["log", "-1", "--format=%H", "--", relPath]);
+    const sha = out?.trim();
+    return sha ? sha : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "publishConfig": {
     "access": "public"
   },