scopecairn 0.9.0 → 0.12.0

package/README.md

@@ -24,15 +24,15 @@ No MCP server, no embeddings, no network calls, no telemetry.
   Definition of Done, so the agent changes only what matters.
 - **Change impact** — direct, indirect (2-hop), tests, and UI components
   affected by a file or symbol.
-- **Call path tracing** — `scopecairn path <A> <B>` shows the shortest
+- **Call path tracing** — `scopecairn graph <A> --to <B>` shows the shortest
   multi-hop call/dependency chain between two symbols.
 - **Centrality ranking** — weighted PageRank + betweenness cached per
-  symbol; `context` surfaces critical hotspots, `doctor` flags
+  symbol; `context` surfaces critical hotspots, `status --doctor` flags
   single points of failure.
 - **Community detection** — Louvain clustering finds real modules by
   link density (not just folders); `graph` shows each symbol's community.
 - **Cycle detection** — Tarjan SCC finds circular dependencies;
-  reported by `doctor`, warned in `context`, listed in `GRAPH.md`.
+  reported by `status --doctor` and `verify`, warned in `context`, listed in `GRAPH.md`.
 - **Auto-refresh** — `context` and `impact` re-index changed files first;
   run `scan` after editing to close the loop.
 - **Framework adapters** — Next.js (App + Pages Router routes),
@@ -40,8 +40,8 @@ No MCP server, no embeddings, no network calls, no telemetry.
 - **Multi-language** — TypeScript, JavaScript, Python, Java, Go, Rust,
   PHP, C#, C/C++, Ruby, HTML, Vue SFC (plus config/schema files as
   graph nodes).
-- **Multi-agent setup** — skills for Claude Code (plugin + marketplace
-  ready), Antigravity, Cursor, Windsurf, Copilot, Kiro, and an OpenCode
+- **Multi-agent setup** — skills for Claude Code (project skill),
+  Antigravity, Cursor, Windsurf, Copilot, Kiro, and an OpenCode
   slash command. ScopeCairn never touches your `AGENTS.md`/`CLAUDE.md` —
   those hold your repo's details, not tool instructions.
 - **`GRAPH.md` knowledge file** — `.scopecairn/GRAPH.md` is a budgeted
@@ -58,7 +58,7 @@ No MCP server, no embeddings, no network calls, no telemetry.
   click-for-details side panel (callers, callees, centrality scores).
   Nodes sized by symbols/PageRank, colored by Louvain community.
   Pan, zoom, hover inspect. Double-click to open, no server.
-- **`export` for external tools** — `scopecairn export --format
+- **Graph export for external tools** — `scopecairn graph --export
   mermaid|graphml|dot|json` writes `.scopecairn/graph.<ext>` for PR
   diagrams (Mermaid), Gephi/Cytoscape (GraphML), Graphviz (DOT),
   or custom scripts (JSON).
@@ -74,8 +74,7 @@ Requires Node.js ≥ 20.
 Upgrade later with:
 
 ```bash
-scopecairn update          # or: npm install -g scopecairn@latest
-scopecairn update --check  # only check for a new version
+npm install -g scopecairn@latest
 ```
 
 ## Agent-driven setup
@@ -88,8 +87,8 @@ it runs project setup itself.
    npx skills add <github-user>/scopecairn -g
    ```
    (fallback without a skill: add one line to your global agent
-   instructions — `~/.claude/CLAUDE.md` or equivalent: *When the user
-   writes "scopecairn \<path\>", run `scopecairn init \<path\>`.*)
+   instructions — `~/.claude/CLAUDE.md` or equivalent: _When the user
+   writes "scopecairn \<path\>", run `scopecairn init \<path\>`._)
 2. In any project chat, type:
    ```
    scopecairn ./
@@ -111,81 +110,75 @@ Claude Code (project skill, committed with the repo):
 scopecairn claude install
 ```
 
-Or as a plugin from the bundled marketplace (this repo):
-
-```
-/plugin marketplace add <github-user>/scopecairn
-/plugin install scopecairn@scopecairn
-```
-
 After setup, your agent calls ScopeCairn automatically on every coding task.
-To query manually:
+To query manually (replace `src/indexer.ts` or `buildContext` with files/symbols from your codebase):
 
 ```bash
-scopecairn context "add approval workflow"
-scopecairn context ./                 # repository orientation map
-scopecairn impact src/request/RequestService.ts
-scopecairn read symbol approveRequest
-scopecairn graph RequestService
-scopecairn path handleLogin dbQuery
-scopecairn export --format mermaid
-scopecairn doctor
+scopecairn scan                             # index repository (--rebuild, --clean, --watch)
+scopecairn context "tambah fitur auth"      # AI agent task context + scope
+scopecairn impact src/indexer.ts            # blast radius & affected tests (--run-tests)
+scopecairn graph buildContext               # inspect relations, path (--to), export (--export)
+scopecairn verify                           # pre-commit safety guard (--diff, --arch)
+scopecairn status                           # index statistics & health checks (--doctor, --html)
+scopecairn read symbol indexFileSymbols     # symbol-level source excerpt
 ```
 
 Per-agent installers (instead of `init --agents …`):
 
 ```bash
 scopecairn antigravity install   # Skill + Workflow + allowlist guide
-scopecairn claude install        # project skill .claude/skills (also: cursor, windsurf, copilot, kiro)
+scopecairn claude install        # project skill .claude/skills (also: cursor, windsurf, copilot)
+scopecairn kiro install          # steering .kiro/steering + knowledge skill .kiro/skills/scopecairn-knowledge
 scopecairn opencode install      # /scopecairn slash command + permission snippet
 scopecairn claude uninstall      # clean removal, user content preserved
 scopecairn agents list
 ```
 
-## Commands
+## 6 Core Commands
+
+ScopeCairn organizes its capabilities into **6 core commands** aligned with codebase architecture:
+
+| Core Command | Description & Key Options |
+| ------------ | ------------------------- |
+| `scan` | **Index & Database Lifecycle:** Index repository. Options: `--rebuild` (rebuild from scratch), `--clean` (remove `.scopecairn/`), `--watch` (auto-refresh daemon on file save). |
+| `context "<task>"` | **AI Agent Context & Scope:** Main agent entry point with auto-refresh, task classification, relevant context, task scope, and Task Guard. Options: `--escalate`, `--mode NORMAL\|FAST\|SAFE\|AUDIT`, `--max-tokens N`, `--no-history`, `--with-diff`, `--json`. |
+| `impact <target>` | **Blast Radius & Test Selection:** Change impact analysis across direct, indirect, tests, UI components, and API clients. Options: `--run-tests` (run affected tests directly), `--tests` (list affected tests only), `--repos [list]` (cross-repo blast radius). |
+| `graph [symbol]` | **Knowledge Graph & Navigation:** Symbol relations, PageRank centrality, community clusters, and cycle status. Options: `--to <target>` (shortest multi-hop call path), `--export <fmt>` (`mermaid\|graphml\|dot\|json`). |
+| `verify` | **Pre-Commit Safety Guard:** Working tree check against protected files, task scope creep, and circular dependency regressions. Options: `--diff` (structural symbol-level diff vs HEAD), `--arch` (architectural layer rules), `--strict`, `--task <t>`. |
+| `status` | **Health & Diagnostics:** Index statistics and metadata. Options: `--doctor` (integration and adapter health check), `--verbose`, `--html` (generate local HTML dashboard). |
+
+### Helper & Setup Commands
 
 | Command | Description |
-|---|---|
-| `init [path]` | Initial indexing + Skill, Workflow, detected agent skills (`--agents …\|all`; never writes `AGENTS.md`) |
-| `scan` / `rebuild` / `clean` | Manual index management (`scan` incremental; `rebuild` from scratch; `clean` removes `.scopecairn/`) |
-| `status` / `doctor` | Index status (incl. adapters, invocations) and health checks |
-| `context "<task>"` | Main entry point: context + scope (`--escalate`, `--no-refresh`, `--mode NORMAL|FAST|SAFE|AUDIT`, `--max-tokens N`); a path task returns an orientation map |
-| `impact <path\|symbol>` | Change impact: direct, indirect, tests (via TESTS edges + static CALLS backward reachability), UI, queries, routes. Edge evidence tagged EXTRACTED/INFERRED/AMBIGUOUS |
-| `graph <symbol>` | Symbol relations (+ PageRank, community, cycle status) |
-| `path <from> <to>` | Shortest multi-hop call/dependency path between two symbols |
-| `export --format <fmt>` | Graph export: `mermaid`, `graphml`, `dot`, or `json` (default `.scopecairn/graph.<ext>`, override with `--out`) |
-| `read symbol <name>` | Symbol-level source excerpt (not whole files) |
-| `<agent> install` | Per-agent setup: `antigravity`, `claude`, `gemini`, `cursor`, `windsurf`, `copilot`, `kiro` (each also `uninstall`; `agents list` to see all) |
-| `dashboard` | Generate local HTML dashboard at `.scopecairn/dashboard.html` |
-| `test-select <target> [--run]` | List affected test files via graph dependency traversal & runner detection (`--run` executes runner) |
-| `verify [--task <t>] [--strict]` | Post-edit guard: check modified protected files, task scope creep, and circular dependency regressions |
-| `diff` | Structural symbol-level diff of working tree vs HEAD with breaking impact alerts |
-| `arch-check [--init]` | Check architectural layer rules & disallowed import boundaries (`--init` scaffolds `.scopecairn/arch.json`) |
-| `watch [--debounce <ms>]` | Daemon mode: auto-refresh index in background on file saves |
-| `doctor --verbose` | Also surface adapter/graph errors from `.scopecairn/last-run.log` to stderr |
-| `benchmark [--tune]` | Retrieval recall, irrelevant ratio, context reduction + weight calibration |
-| `update [--check]` | Update ScopeCairn to the latest npm release (`--check` only checks) |
-
-Agent commands (`context`, `impact`, `read`, `graph`, `status`, `doctor`, `verify`, `diff`, `test-select`, `arch-check`)
-are read-only toward source and only write to `.scopecairn/` — safe to
-allowlist. `init`, `scan`, `rebuild`, and `watch` are manual/user-side commands.
+| ------- | ----------- |
+| `init [path]` | Initial indexing + Skill, Workflow, detected agent skills (`--agents …\|all`). |
+| `read symbol <name>` | Symbol-level source excerpt (not whole files). |
+| `benchmark [--tune]` | Retrieval recall, irrelevant ratio, context reduction + weight tuning (dev-only, hidden from `--help`). |
+| `<agent> install` | Agent installers: `antigravity`, `claude`, `cursor`, `windsurf`, `copilot`, `kiro`, `opencode`. |
+
+> [!NOTE]
+> **Backward Compatibility:** All previous standalone commands (`rebuild`, `clean`, `watch`, `doctor`, `dashboard`, `test-select`, `path`, `export`, `diff`, `arch-check`, `history`) are preserved as hidden aliases mapped directly into these 6 core commands — they still work but no longer appear in `--help`. `update` is deprecated (use `npm install -g scopecairn@latest`).
+
+Agent commands (`context`, `impact`, `read`, `graph`, `status`, `verify`)
+are read-only toward source code and safe to allowlist. `init` and `scan`
+are user-side setup/lifecycle commands.
 
 ## Framework adapters
 
 Detected automatically during `scan` (shown in output and `status`).
 No configuration needed.
 
-| Adapter | Detects | Produces |
-|---|---|---|
-| `nextjs` | `app/`, `pages/`, `next.config.*` | Route symbols (`GET /api/x`, `PAGE /y` incl. route groups, dynamic segments), `ROUTES_TO` handler edges, `QUERIES` handler→model edges |
-| `prisma` | `schema.prisma` | `model` symbols for `QUERIES` resolution |
-| `drizzle` | `drizzle*` paths/config, `db/` schemas | `model` symbols from `pgTable`/`sqliteTable`/`mysqlTable`; `QUERIES` from `db.query.*` relational and `db.select/insert/update/delete` builder calls |
-| `express` | `package.json` deps | Route symbols from `app/router.METHOD(path)`, handler edges |
-| `fastapi` | `.py` routes, requirements/pyproject | Route symbols from `@app.METHOD("/path")` decorators |
-| `nestjs` | `*.controller.ts`, `*.service.ts`, `nest-cli.json` | Route symbols from `@Controller` and `@Get/@Post/...` decorators, `ROUTES_TO` handler edges, `@Injectable()` service providers |
-| `django` | `manage.py`, `urls.py`, `models.py` | Route symbols from `path()`/`re_path()` in `urls.py`, `ROUTES_TO` handler edges, `model` symbols from `models.Model` |
-| `sqlalchemy` | requirements/pyproject | `model` symbols from `class X(Base)`/`__tablename__`; `QUERIES` from `session.query/select` |
-| `vue` | `.vue` SFCs, `package.json` deps | `component` symbols per SFC; `IMPORTS` edges from used components in template |
+| Adapter      | Detects                                            | Produces                                                                                                                                             |
+| ------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nextjs`     | `app/`, `pages/`, `next.config.*`                  | Route symbols (`GET /api/x`, `PAGE /y` incl. route groups, dynamic segments), `ROUTES_TO` handler edges, `QUERIES` handler→model edges               |
+| `prisma`     | `schema.prisma`                                    | `model` symbols for `QUERIES` resolution                                                                                                             |
+| `drizzle`    | `drizzle*` paths/config, `db/` schemas             | `model` symbols from `pgTable`/`sqliteTable`/`mysqlTable`; `QUERIES` from `db.query.*` relational and `db.select/insert/update/delete` builder calls |
+| `express`    | `package.json` deps                                | Route symbols from `app/router.METHOD(path)`, handler edges                                                                                          |
+| `fastapi`    | `.py` routes, requirements/pyproject               | Route symbols from `@app.METHOD("/path")` decorators                                                                                                 |
+| `nestjs`     | `*.controller.ts`, `*.service.ts`, `nest-cli.json` | Route symbols from `@Controller` and `@Get/@Post/...` decorators, `ROUTES_TO` handler edges, `@Injectable()` service providers                       |
+| `django`     | `manage.py`, `urls.py`, `models.py`                | Route symbols from `path()`/`re_path()` in `urls.py`, `ROUTES_TO` handler edges, `model` symbols from `models.Model`                                 |
+| `sqlalchemy` | requirements/pyproject                             | `model` symbols from `class X(Base)`/`__tablename__`; `QUERIES` from `session.query/select`                                                          |
+| `vue`        | `.vue` SFCs, `package.json` deps                   | `component` symbols per SFC; `IMPORTS` edges from used components in template                                                                        |
 
 Limits (honest): non-Prisma/Drizzle/SQLAlchemy ORMs, inter-table
 references, raw SQL strings, and fully dynamic table names are not mapped
@@ -205,6 +198,16 @@ prompt → scopecairn context (refresh at start) → agent edits code
 
 Measure retrieval quality anytime: `scopecairn benchmark [--tune]`.
 
+## History privacy
+
+`scan` mengindeks pesan commit git lokal ke tabel `commits`/`commit_files` di
+`.scopecairn/scopecairn.db` (dilewati commit >40 file, lockfile, dan generated).
+Isi commit **tidak** masuk `GRAPH.md`/`GRAPH.html`/`graph --export` (sering di-commit dan
+dibagikan) — riwayat hanya hidup di database lokal dan output `context`.
+Pesan commit bisa memuat info sensitif; karena tidak keluar dari mesin, risikonya
+kecil. Repo tanpa git atau clone dangkal tetap didukung (riwayat parsial/absen,
+dilaporkan `status --doctor`).
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/agentsmd-GS2DHP65.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import {
+  PROJECT_RULES_MAX_CHARS,
+  demoteHeadings,
+  findAgentsMd,
+  loadProjectRules
+} from "./chunk-ZV4BSIQM.js";
+export {
+  PROJECT_RULES_MAX_CHARS,
+  demoteHeadings,
+  findAgentsMd,
+  loadProjectRules
+};

package/dist/chunk-2BIPX6YJ.js

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+import {
+  logError
+} from "./chunk-OPA4TMAT.js";
+
+// src/retrieval/tokenize.ts
+var STOP = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "of",
+  "to",
+  "in",
+  "for",
+  "on",
+  "with",
+  "and",
+  "or",
+  "src",
+  "lib",
+  "app",
+  "test",
+  "tests",
+  "spec"
+]);
+function stemVariants(t) {
+  const out = /* @__PURE__ */ new Set([t]);
+  if (t.endsWith("ies") && t.length > 4) out.add(t.slice(0, -3) + "y");
+  else if (t.endsWith("es") && t.length > 4 && /(s|x|z|ch|sh)es$/.test(t)) out.add(t.slice(0, -2));
+  else if (t.endsWith("s") && t.length > 3 && !t.endsWith("ss")) out.add(t.slice(0, -1));
+  if (t.endsWith("ing") && t.length > 5) {
+    const base = t.slice(0, -3);
+    out.add(base);
+    out.add(base + "e");
+  }
+  if (t.endsWith("ation") && t.length > 7) {
+    const base = t.slice(0, -5);
+    out.add(base);
+  }
+  return [...out];
+}
+var EXPLICIT_STEM = /* @__PURE__ */ new Map([
+  ["configuration", "config"],
+  ["configurations", "config"],
+  ["configured", "config"],
+  ["ranking", "rank"],
+  ["ranked", "rank"],
+  ["weights", "weight"],
+  ["dependencies", "dependency"],
+  ["dependency", "depend"],
+  ["extraction", "extract"],
+  ["extracted", "extract"]
+]);
+function tokenizeIdentifier(raw) {
+  const parts = raw.replace(/[\\/]/g, " ").replace(/[.:\-_"']/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/g).filter((t) => t.length >= 2 && !STOP.has(t));
+  const out = /* @__PURE__ */ new Set();
+  for (const t of parts) {
+    out.add(t);
+    for (const v of stemVariants(t)) {
+      if (v.length >= 2 && !STOP.has(v)) out.add(v);
+    }
+    const e = EXPLICIT_STEM.get(t);
+    if (e && !STOP.has(e)) out.add(e);
+  }
+  return [...out];
+}
+function tokenizeTask(text) {
+  return tokenizeIdentifier(text);
+}
+
+// src/retrieval/history/index.ts
+function stripConventionalPrefix(subject) {
+  return subject.replace(/^[a-z]+(\([^)]*\))?(!)?:\s*/i, "").replace(/^\[\w+\]\s*/, "").trim();
+}
+function isPoorSubject(subject) {
+  const clean = stripConventionalPrefix(subject);
+  if (/^merge\s+(pr|pull request)\s*#?\d*/i.test(clean)) return true;
+  if (/^(update|updates|wip|tmp|test|fix|patch|changes?)$/i.test(clean)) return true;
+  return tokenizeIdentifier(clean).length < 2;
+}
+function commitTokens(subject, body, paths) {
+  const out = /* @__PURE__ */ new Set();
+  const cleanSubject = stripConventionalPrefix(subject);
+  for (const t of tokenizeIdentifier(cleanSubject)) out.add(t);
+  if (!isPoorSubject(subject)) {
+    for (const t of tokenizeIdentifier(body.slice(0, 2e3))) out.add(t);
+  }
+  for (const p of paths) {
+    for (const t of tokenizeIdentifier(p)) out.add(t);
+  }
+  return [...out];
+}
+function syncCommitFts(db, shas) {
+  let n = 0;
+  try {
+    const del = db.prepare(`DELETE FROM commit_fts WHERE sha = ?`);
+    const ins = db.prepare(`INSERT INTO commit_fts(sha, subject, body, paths) VALUES (?, ?, ?, ?)`);
+    const getCommit = db.prepare(`SELECT subject, body FROM commits WHERE sha = ?`);
+    const getPaths = db.prepare(`SELECT path FROM commit_files WHERE sha = ?`);
+    for (const sha of shas) {
+      const c = getCommit.get(sha);
+      if (!c) continue;
+      const paths = getPaths.all(sha).map((r) => r.path);
+      del.run(sha);
+      ins.run(sha, c.subject, c.body.slice(0, 4e3), paths.join(" "));
+      n++;
+    }
+  } catch (err) {
+    logError("history", err);
+  }
+  return n;
+}
+
+// src/retrieval/history/search.ts
+var HISTORY_HALF_LIFE_DAYS = 180;
+var HISTORY_MIN_SCORE = 0.05;
+var HISTORY_MAX_FILES = 40;
+var BM25_LIMIT = 20;
+function recencyScore(ts, nowSec, halfLifeDays) {
+  if (ts <= 0) return 0.5;
+  const ageDays = Math.max(0, (nowSec - ts) / 86400);
+  return Math.pow(0.5, ageDays / Math.max(1, halfLifeDays));
+}
+function sizePenalty(nFiles) {
+  return 1 / Math.log(2 + Math.max(0, nFiles));
+}
+function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let inter = 0;
+  for (const x of a) if (b.has(x)) inter++;
+  const union = a.size + b.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+function resolveCurrentPath(db, path) {
+  let cur = path;
+  try {
+    const stmt = db.prepare(`SELECT path FROM commit_files WHERE old_path = ? ORDER BY rowid DESC LIMIT 1`);
+    for (let i = 0; i < 5; i++) {
+      const row = stmt.get(cur);
+      if (!row || row.path === cur) break;
+      cur = row.path;
+    }
+  } catch {
+  }
+  return cur;
+}
+function candidates(db, tokens, asOfTs, excludeShas) {
+  const excluded = new Set(excludeShas ?? []);
+  if (tokens.length === 0) return [];
+  const q = tokens.map((t) => `"${t.replace(/"/g, "")}"`).join(" OR ");
+  try {
+    const rows = db.prepare(
+      `SELECT sha, bm25(commit_fts) AS rank FROM commit_fts
+         WHERE commit_fts MATCH ? ORDER BY rank LIMIT ${BM25_LIMIT}`
+    ).all(q);
+    if (rows.length === 0) return [];
+    const filt = rows.filter((r) => !excluded.has(r.sha));
+    if (filt.length === 0) return [];
+    const worst = Math.min(...filt.map((r) => r.rank));
+    const range = Math.max(1e-9, 0 - worst + 1);
+    void asOfTs;
+    return filt.map((r) => ({
+      sha: r.sha,
+      bm25norm: Math.max(0, Math.min(1, (0 - r.rank + 0.5) / range))
+    }));
+  } catch (err) {
+    logError("history", err);
+  }
+  try {
+    let rows = db.prepare(`SELECT sha, subject, ts FROM commits`).all();
+    if (asOfTs !== void 0) rows = rows.filter((r) => r.ts <= asOfTs);
+    rows = rows.filter((r) => !excluded.has(r.sha));
+    const tset = new Set(tokens);
+    const scored = rows.map((r) => {
+      let paths = [];
+      try {
+        paths = db.prepare(`SELECT path FROM commit_files WHERE sha = ?`).all(r.sha).map((x) => x.path);
+      } catch {
+      }
+      const doc = new Set(commitTokens(r.subject, "", paths));
+      let hit = 0;
+      for (const t of tset) if (doc.has(t)) hit++;
+      return { sha: r.sha, bm25norm: tset.size === 0 ? 0 : hit / tset.size };
+    }).filter((r) => r.bm25norm > 0);
+    scored.sort((a, b) => b.bm25norm - a.bm25norm || (a.sha < b.sha ? -1 : 1));
+    return scored.slice(0, BM25_LIMIT);
+  } catch (err) {
+    logError("history", err);
+    return [];
+  }
+}
+function historySearch(db, task, opts = {}) {
+  const seedFiles = new Set(opts.seedFiles ?? []);
+  const limit = Math.max(1, Math.min(10, opts.limit ?? 3));
+  const halfLife = opts.halfLifeDays ?? HISTORY_HALF_LIFE_DAYS;
+  const minScore = opts.minScore ?? HISTORY_MIN_SCORE;
+  const nowSec = opts.nowSec ?? Math.floor(Date.now() / 1e3);
+  const tokens = tokenizeTask(task);
+  if (tokens.length === 0) return [];
+  let cands;
+  try {
+    cands = candidates(db, tokens, opts.asOfTs, opts.excludeShas);
+  } catch (err) {
+    logError("history", err);
+    return [];
+  }
+  if (cands.length === 0) return [];
+  const out = [];
+  try {
+    const getCommit = db.prepare(`SELECT ts, subject FROM commits WHERE sha = ?`);
+    const getFiles = db.prepare(`SELECT path FROM commit_files WHERE sha = ?`);
+    const fileExists = db.prepare(`SELECT 1 AS ok FROM files WHERE path = ? LIMIT 1`);
+    for (const c of cands) {
+      const commit = getCommit.get(c.sha);
+      if (!commit) continue;
+      if (opts.asOfTs !== void 0 && commit.ts > opts.asOfTs) continue;
+      const rawFiles = getFiles.all(c.sha).map((r) => r.path);
+      if (rawFiles.length > HISTORY_MAX_FILES) continue;
+      const live = [];
+      for (const p of rawFiles) {
+        const cur = resolveCurrentPath(db, p);
+        try {
+          const hit = fileExists.get(cur);
+          if (hit) {
+            if (!live.includes(cur)) live.push(cur);
+          }
+        } catch {
+        }
+      }
+      if (live.length === 0) continue;
+      const rec = recencyScore(commit.ts, nowSec, halfLife);
+      const pen = sizePenalty(rawFiles.length);
+      const ov = jaccard(new Set(live), seedFiles);
+      const score = c.bm25norm * rec * pen * (1 + ov);
+      if (score < minScore) continue;
+      const d = new Date(commit.ts * 1e3);
+      out.push({
+        sha: c.sha,
+        shortSha: c.sha.slice(0, 7),
+        ts: commit.ts,
+        date: Number.isNaN(d.getTime()) ? "-" : d.toISOString().slice(0, 10),
+        subject: commit.subject,
+        files: [...live].sort(),
+        score,
+        sortTs: commit.ts
+      });
+    }
+  } catch (err) {
+    logError("history", err);
+    return [];
+  }
+  out.sort((a, b) => b.score - a.score || b.sortTs - a.sortTs || (a.sha < b.sha ? -1 : a.sha > b.sha ? 1 : 0));
+  return out.slice(0, limit).map(({ sortTs: _s, ...rest }) => rest);
+}
+function coChangeSet(analogs) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const a of analogs) {
+    for (const f of new Set(a.files)) counts.set(f, (counts.get(f) ?? 0) + 1);
+  }
+  return [...counts.entries()].filter(([, n]) => n >= 2).map(([path, count]) => ({ path, count })).sort((a, b) => b.count - a.count || (a.path < b.path ? -1 : 1));
+}
+function groupHistoryFiles(files) {
+  const source = [];
+  const test = [];
+  const config = [];
+  const docs = [];
+  for (const f of files) {
+    const base = f.split("/").pop() ?? f;
+    const lower = f.toLowerCase();
+    if (f.includes(".test.") || f.includes(".spec.") || f.includes("__tests__") || base.startsWith("test_") || base.endsWith("_test.py") || lower.startsWith("tests/")) {
+      test.push(f);
+    } else if (/\.(json|ya?ml|toml|ini|cfg)$/.test(lower) || ["package.json", "dockerfile", "makefile"].includes(base.toLowerCase())) {
+      config.push(f);
+    } else if (/\.mdx?$/.test(lower) || lower.startsWith("docs/")) {
+      docs.push(f);
+    } else {
+      source.push(f);
+    }
+  }
+  return { source, test, config, docs };
+}
+function leaveOneOut(db, shas, opts = {}) {
+  const out = [];
+  try {
+    const getCommit = db.prepare(`SELECT ts, subject FROM commits WHERE sha = ?`);
+    const getFiles = db.prepare(`SELECT path FROM commit_files WHERE sha = ?`);
+    for (const sha of shas) {
+      const commit = getCommit.get(sha);
+      if (!commit) continue;
+      const expected = getFiles.all(sha).map((r) => r.path);
+      const seeds = opts.seedFilesOf ? opts.seedFilesOf(sha) : [];
+      const analogs = historySearch(db, commit.subject, {
+        seedFiles: seeds,
+        limit: opts.limit ?? 3,
+        asOfTs: commit.ts - 1,
+        excludeShas: [sha],
+        nowSec: opts.nowSec
+      });
+      const recalledFiles = /* @__PURE__ */ new Set();
+      for (const a of analogs) for (const f of a.files) recalledFiles.add(f);
+      for (const c of coChangeSet(analogs)) recalledFiles.add(c.path);
+      const recalled = expected.filter((f) => recalledFiles.has(f));
+      out.push({ sha, subject: commit.subject, recalled, expected, recall: expected.length === 0 ? 1 : recalled.length / expected.length });
+    }
+  } catch (err) {
+    logError("history", err);
+  }
+  return out;
+}
+
+export {
+  tokenizeIdentifier,
+  tokenizeTask,
+  syncCommitFts,
+  HISTORY_HALF_LIFE_DAYS,
+  HISTORY_MIN_SCORE,
+  HISTORY_MAX_FILES,
+  recencyScore,
+  sizePenalty,
+  jaccard,
+  resolveCurrentPath,
+  historySearch,
+  coChangeSet,
+  groupHistoryFiles,
+  leaveOneOut
+};