scopecairn 0.8.0 → 0.10.0

package/README.md

@@ -36,7 +36,7 @@ No MCP server, no embeddings, no network calls, no telemetry.
 - **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),
-  Prisma models, and Drizzle tables/queries detected automatically.
+  Prisma models, Drizzle tables/queries, Express, FastAPI, NestJS (controllers, routes, injectables), Django (urls, models), SQLAlchemy, and Vue SFC detected automatically.
 - **Multi-language** — TypeScript, JavaScript, Python, Java, Go, Rust,
   PHP, C#, C/C++, Ruby, HTML, Vue SFC (plus config/schema files as
   graph nodes).
@@ -149,7 +149,8 @@ scopecairn agents list
 | `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 |
+| `context "<task>"` | Main entry point: context + scope (`--escalate`, `--no-refresh`, `--mode NORMAL|FAST|SAFE|AUDIT`, `--max-tokens N`, `--no-history`, `--with-diff`); a path task returns an orientation map |
+| `history "<task>" [--limit N] [--json] [--with-diff]` | Analog commit lama paling mirip (BM25 + recency half-life 180 hari + co-change); co-change set ikut ke Optional di `context` |
 | `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 |
@@ -157,14 +158,18 @@ scopecairn agents list
 | `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>` | List test files affected by a file/symbol change target |
+| `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`)
+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`, and `rebuild` are manual/user-side commands.
+allowlist. `init`, `scan`, `rebuild`, and `watch` are manual/user-side commands.
 
 ## Framework adapters
 
@@ -178,6 +183,8 @@ No configuration needed.
 | `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 |
 
@@ -199,6 +206,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`/`export` (sering di-commit dan
+dibagikan) — riwayat hanya hidup di database lokal dan output `context`/`history`.
+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 `doctor`).
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

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
+};