scopecairn 0.12.1 → 0.14.1

package/README.md

@@ -76,6 +76,16 @@ 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.
+- **Decision log** — `scopecairn decide "pakai X karena Y"` records an
+  architectural decision once; it is carried into every later
+  `context` call, so the agent stops re-litigating settled choices.
+- **Definition of Done check** — `verify --dod` rates each DoD item and
+  is honest about what it cannot know: `pass` only for what the machine
+  verified (scope, index freshness), `warn`/`fail` where it has evidence,
+  `manual` for judgement calls. Never a fabricated "done".
+- **Local usage report** — `status --usage` reads the local invocation
+  log: commands used, closed-loop rate (`scan` after a task), average
+  symbols per task. Local only, never leaves the machine.
 - **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),
@@ -136,9 +146,10 @@ scopecairn scan                             # index repository (--rebuild, --cle
 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 verify --dod                     # pre-commit safety guard (--diff, --arch, --dod)
+scopecairn status --usage                   # index statistics & health checks (--doctor, --html)
 scopecairn read symbol indexFileSymbols     # symbol-level source excerpt
+scopecairn decide "graf di SQLite, tanpa embedding"   # catat keputusan arsitektur
 ```
 
 Per-agent installers (instead of `init --agents …`):
@@ -162,8 +173,8 @@ ScopeCairn organizes its capabilities into **6 core commands** aligned with code
 | `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). |
+| `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), `--dod` (Definition of Done: verified / warned / manual, never a claimed pass), `--strict`, `--task <t>`. |
+| `status` | **Health & Diagnostics:** Index statistics and metadata. Options: `--doctor` (integration and adapter health check), `--usage` (local usage & compliance report), `--verbose`, `--html` (generate local HTML dashboard). |
 
 ### Helper & Setup Commands
 
@@ -171,6 +182,7 @@ ScopeCairn organizes its capabilities into **6 core commands** aligned with code
 | ------- | ----------- |
 | `init [path]` | Initial indexing + Skill, Workflow, detected agent skills (`--agents …\|all`). |
 | `read symbol <name>` | Symbol-level source excerpt (not whole files). |
+| `decide "…"` | Record an architectural decision into `.scopecairn/decisions.md` (no argument: list them). Read back by `context`. |
 | `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`. |
 

package/dist/chunk-2MIHTOLI.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import {
+  isProtected
+} from "./chunk-JQBYQ4EF.js";
+
+// src/retrieval/classify.ts
+var FANIN_THRESHOLD = 5;
+function moduleOf(file) {
+  const i = file.indexOf("/");
+  return i === -1 ? "." : file.slice(0, i);
+}
+function classify(ranked, faninOf, threshold = 0.15, protectedPatterns) {
+  const relevant = ranked.filter((r) => r.score >= threshold);
+  const files = [...new Set(relevant.map((r) => r.file))];
+  const modules = [...new Set(files.map(moduleOf))];
+  const reasons = [];
+  const DEFINITIONAL = /* @__PURE__ */ new Set([
+    "function",
+    "class",
+    "method",
+    "component",
+    "interface",
+    "type"
+  ]);
+  const highFanin = relevant.filter((r) => DEFINITIONAL.has(r.type) && faninOf(r.id) >= FANIN_THRESHOLD).map((r) => r.name);
+  const protectedHits = files.filter(
+    (f) => protectedPatterns ? isProtected(f, protectedPatterns) : isProtected(f)
+  );
+  let complexity = "SIMPLE";
+  if (files.length >= 3) {
+    complexity = "COMPLEX";
+    reasons.push(`estimasi ${files.length} file (\u22653)`);
+  }
+  if (modules.length > 1) {
+    complexity = "COMPLEX";
+    reasons.push(`lintas modul (${modules.join(", ")})`);
+  }
+  if (highFanin.length > 0) {
+    complexity = "COMPLEX";
+    reasons.push(`simbol dipakai banyak tempat: ${highFanin.slice(0, 3).join(", ")}`);
+  }
+  if (protectedHits.length > 0) {
+    complexity = "COMPLEX";
+    reasons.push(`menyentuh area sensitif: ${protectedHits.slice(0, 3).join(", ")}`);
+  }
+  if (complexity === "SIMPLE") reasons.push(`estimasi ${files.length} file, 1 modul`);
+  return {
+    complexity,
+    estimatedFiles: files.length,
+    modules,
+    reasons,
+    highFanin,
+    protectedHits
+  };
+}
+
+export {
+  classify
+};

package/dist/{chunk-2BIPX6YJ.js → chunk-GQFBQRDD.js}

@@ -2,71 +2,10 @@
 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);
-}
+import {
+  tokenizeIdentifier,
+  tokenizeTask
+} from "./chunk-UVKHDHBU.js";
 
 // src/retrieval/history/index.ts
 function stripConventionalPrefix(subject) {
@@ -309,8 +248,6 @@ function leaveOneOut(db, shas, opts = {}) {
 }
 
 export {
-  tokenizeIdentifier,
-  tokenizeTask,
   syncCommitFts,
   HISTORY_HALF_LIFE_DAYS,
   HISTORY_MIN_SCORE,

package/dist/{chunk-QIYOLER3.js → chunk-IRYNTYZD.js}

@@ -1,17 +1,53 @@
 #!/usr/bin/env node
 import {
-  computeScope,
+  demoteHeadings
+} from "./chunk-ZV4BSIQM.js";
+import {
   isProtected,
-  loadProtectedPatterns,
-  scopeBlock
-} from "./chunk-G5RA43OH.js";
+  loadProtectedPatterns
+} from "./chunk-JQBYQ4EF.js";
 import {
   coChangeSet,
   groupHistoryFiles
-} from "./chunk-2BIPX6YJ.js";
-import {
-  demoteHeadings
-} from "./chunk-ZV4BSIQM.js";
+} from "./chunk-GQFBQRDD.js";
+
+// src/scope/scope.ts
+function computeScope(highFiles, mediumFiles, testFiles, patterns, historyOptional) {
+  const required = [];
+  const optional = [];
+  const protectedFiles = [];
+  const seen = /* @__PURE__ */ new Set();
+  const place = (f) => {
+    if (seen.has(f)) return;
+    seen.add(f);
+    if (isProtected(f, patterns)) protectedFiles.push(f);
+    else if (highFiles.includes(f)) required.push(f);
+    else optional.push(f);
+  };
+  for (const f of highFiles) place(f);
+  for (const f of mediumFiles) place(f);
+  for (const t of testFiles) {
+    if (seen.has(t)) continue;
+    seen.add(t);
+    if (isProtected(t, patterns)) protectedFiles.push(t);
+    else optional.push(t);
+  }
+  for (const h of historyOptional ?? []) {
+    if (seen.has(h)) continue;
+    seen.add(h);
+    if (isProtected(h, patterns)) protectedFiles.push(h);
+    else optional.push(h);
+  }
+  return { required, optional, protected: protectedFiles };
+}
+function scopeBlock(scope) {
+  const fmt = (xs) => xs.length > 0 ? xs.join(", ") : "-";
+  return `## Scope
+Required: ${fmt(scope.required)}
+Optional: ${fmt(scope.optional)}
+Protected: ${fmt(scope.protected)}
+`;
+}
 
 // src/scope/guard.ts
 var TASK_GUARD_RULES = [
@@ -48,6 +84,12 @@ function buildContext(db, task, result, cls, opts) {
       if (files.length >= 3) break;
     }
     const cand = files.length > 0 ? files.map((f) => `\`${f}\``).join(", ") : "pencarian langsung (tidak ada simbol cocok di index)";
+    const simpleScope = computeScope(
+      files,
+      [],
+      [],
+      loadProtectedPatterns(opts?.repoRoot ?? ".")
+    );
     return {
       markdown: `# Task Context
 
@@ -63,7 +105,8 @@ Task sederhana. Gunakan pencarian langsung. Kandidat: ${cand}
       medium: [],
       tests: [],
       dependencies: [],
-      hotspots: []
+      hotspots: [],
+      scope: simpleScope
     };
   }
   const ranked = result.ranked;
@@ -97,15 +140,14 @@ Task sederhana. Gunakan pencarian langsung. Kandidat: ${cand}
     const ph = highFiles.map(() => "?").join(",");
     try {
       const rows = db.prepare(
-        `SELECT DISTINCT f2.path AS t
+        `SELECT DISTINCT f1.path AS t
            FROM relationships r
            JOIN symbols s1 ON s1.id = r.source_id
            JOIN symbols s2 ON s2.id = r.target_id
            JOIN files f1 ON f1.id = s1.file_id
            JOIN files f2 ON f2.id = s2.file_id
-           WHERE r.relationship_type = 'TESTS'
-             AND (f1.path IN (${ph}) OR f2.path IN (${ph}))`
-      ).all(...highFiles, ...highFiles);
+           WHERE r.relationship_type = 'TESTS' AND f2.path IN (${ph})`
+      ).all(...highFiles);
       for (const r of rows) testSet.add(r.t);
     } catch {
     }
@@ -270,7 +312,8 @@ ${tests.map((t) => `- ${t}`).join("\n") || "-"}
       medium: medFiles,
       tests,
       dependencies: deps,
-      hotspots
+      hotspots,
+      scope
     };
   }
   const md = `# Task Context
@@ -301,7 +344,15 @@ ${tests.map((t) => `- ${t}`).join("\n") || "-"}
 
 ` + historyBlock + cycleWarn + scopeBlock(scope) + `
 ` + guardBlock(extraDoD.length > 0 ? extraDoD : void 0);
-  return { markdown: md, high: highFiles, medium: medFiles, tests, dependencies: deps, hotspots };
+  return {
+    markdown: md,
+    high: highFiles,
+    medium: medFiles,
+    tests,
+    dependencies: deps,
+    hotspots,
+    scope
+  };
 }
 function resolveEffectiveMode(mode, cls, knowledge) {
   return mode === "NORMAL" && cls.complexity === "SIMPLE" && cls.estimatedFiles <= 1 && !knowledge ? "FAST" : mode;
@@ -339,6 +390,7 @@ function buildContextPayload(input) {
 }
 
 export {
+  DEFINITION_OF_DONE,
   buildContext,
   resolveEffectiveMode,
   buildContextPayload

package/dist/{chunk-G5RA43OH.js → chunk-JQBYQ4EF.js}

@@ -17,7 +17,7 @@ function loadDatabaseSync() {
 }
 var DATA_DIR_NAME = ".scopecairn";
 var DB_FILE_NAME = "scopecairn.db";
-var SCHEMA_VERSION = 7;
+var SCHEMA_VERSION = 8;
 function dataDir(repoRoot) {
   return path.join(repoRoot, DATA_DIR_NAME);
 }
@@ -30,6 +30,9 @@ function openDb(repoRoot) {
   const db = new DatabaseSync(dbPath(repoRoot));
   db.exec(`
     PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = NORMAL;
+    PRAGMA temp_store = MEMORY;
+    PRAGMA cache_size = -64000;
     PRAGMA foreign_keys = ON;
     CREATE TABLE IF NOT EXISTS files (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -85,6 +88,17 @@ function openDb(repoRoot) {
       reason TEXT NOT NULL DEFAULT ''
     );
     CREATE INDEX IF NOT EXISTS idx_task_context_task ON task_context(task_id);
+    -- Scope yang DIRENDER ke agent (Required/Optional/Protected), disimpan
+    -- per task. Tanpa ini verify --task harus menghitung ulang scope dari
+    -- task string, dan hasilnya bisa berbeda dari yang benar-benar dilihat
+    -- agent (co-change history, --escalate, task SIMPLE) \u2192 false positive.
+    CREATE TABLE IF NOT EXISTS task_scope (
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      path TEXT NOT NULL,
+      tier TEXT NOT NULL,
+      PRIMARY KEY (task_id, path)
+    );
+    CREATE INDEX IF NOT EXISTS idx_task_scope_task ON task_scope(task_id);
     -- Fase 5: invocation log untuk compliance rate (AI-5, \xA718).
     CREATE TABLE IF NOT EXISTS invocations (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -138,6 +152,15 @@ function openDb(repoRoot) {
     );
     CREATE INDEX IF NOT EXISTS idx_commit_files_sha ON commit_files(sha);
     CREATE INDEX IF NOT EXISTS idx_commit_files_path ON commit_files(path);
+    -- Cache fan-in (jumlah relasi masuk per simbol). Dipakai ranking
+    -- retrieval: tanpa cache, retrieve() menghitung ulang
+    -- GROUP BY target_id di seluruh tabel relationships pada SETIAP
+    -- pemanggilan \u2014 O(E) penuh, dan itu bottleneck utama di repo besar.
+    -- Dipopulate ulang di akhir scanRepository (satu lintasan GROUP BY).
+    CREATE TABLE IF NOT EXISTS fanin (
+      node_id INTEGER PRIMARY KEY,
+      n INTEGER NOT NULL
+    );
     CREATE VIRTUAL TABLE IF NOT EXISTS commit_fts USING fts5(
       sha UNINDEXED, subject, body, paths
     );
@@ -157,10 +180,17 @@ function openDb(repoRoot) {
     `UPDATE relationships SET evidence = 'INFERRED'
      WHERE relationship_type IN ('QUERIES','ROUTES_TO','TESTS') AND evidence = 'EXTRACTED'`
   );
-  db.exec(
-    `UPDATE relationships SET evidence = 'AMBIGUOUS'
-     WHERE relationship_type = 'CALLS' AND confidence < 1.0 AND evidence = 'EXTRACTED'`
-  );
+  const CALLS_BACKFILL_KEY = "migration_calls_evidence_v1";
+  const callsBackfilled = db.prepare(`SELECT value FROM meta WHERE key = ?`).get(CALLS_BACKFILL_KEY);
+  if (!callsBackfilled) {
+    db.exec(
+      `UPDATE relationships SET evidence = 'AMBIGUOUS'
+       WHERE relationship_type = 'CALLS' AND confidence < 1.0 AND evidence = 'EXTRACTED'`
+    );
+    db.prepare(`INSERT INTO meta(key, value) VALUES (?, '1') ON CONFLICT(key) DO NOTHING`).run(
+      CALLS_BACKFILL_KEY
+    );
+  }
   return db;
 }
 function hashContent(buf) {
@@ -295,54 +325,17 @@ function ensureProtectedFile(repoRoot) {
   }
 }
 
-// src/scope/scope.ts
-function computeScope(highFiles, mediumFiles, testFiles, patterns, historyOptional) {
-  const required = [];
-  const optional = [];
-  const protectedFiles = [];
-  const seen = /* @__PURE__ */ new Set();
-  const place = (f) => {
-    if (seen.has(f)) return;
-    seen.add(f);
-    if (isProtected(f, patterns)) protectedFiles.push(f);
-    else if (highFiles.includes(f)) required.push(f);
-    else optional.push(f);
-  };
-  for (const f of highFiles) place(f);
-  for (const f of mediumFiles) place(f);
-  for (const t of testFiles) {
-    if (seen.has(t)) continue;
-    seen.add(t);
-    if (isProtected(t, patterns)) protectedFiles.push(t);
-    else optional.push(t);
-  }
-  for (const h of historyOptional ?? []) {
-    if (seen.has(h)) continue;
-    seen.add(h);
-    if (isProtected(h, patterns)) protectedFiles.push(h);
-    else optional.push(h);
-  }
-  return { required, optional, protected: protectedFiles };
-}
-function scopeBlock(scope) {
-  const fmt = (xs) => xs.length > 0 ? xs.join(", ") : "-";
-  return `## Scope
-Required: ${fmt(scope.required)}
-Optional: ${fmt(scope.optional)}
-Protected: ${fmt(scope.protected)}
-`;
-}
-
 export {
   dataDir,
   dbPath,
   openDb,
   hashContent,
+  DEFAULT_PROTECTED_PATTERNS,
   matchPattern,
   loadProtectedPatterns,
   isProtected,
+  SECRET_PATTERNS,
+  isSecretFile,
   isIndexableMetaFile,
-  ensureProtectedFile,
-  computeScope,
-  scopeBlock
+  ensureProtectedFile
 };