scopecairn 0.10.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,82 +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`, `--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 |
-| `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
@@ -210,11 +202,11 @@ Measure retrieval quality anytime: `scopecairn benchmark [--tune]`.
 
 `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`.
+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 `doctor`).
+dilaporkan `status --doctor`).
 
 ## 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-PYBIR5FP.js → chunk-AJFANTT3.js}

@@ -9,6 +9,9 @@ import {
   coChangeSet,
   groupHistoryFiles
 } from "./chunk-2BIPX6YJ.js";
+import {
+  demoteHeadings
+} from "./chunk-ZV4BSIQM.js";
 
 // src/scope/guard.ts
 var TASK_GUARD_RULES = [
@@ -214,6 +217,46 @@ Task sederhana. Gunakan pencarian langsung. Kandidat: ${cand}
   if (analogTestSha && !requiredHasTest) {
     extraDoD.push(`ubah atau tambah test, seperti pada \`${analogTestSha.shortSha}\``);
   }
+  let rulesBlock = "";
+  const rules = opts?.projectRules;
+  if (rules && rules.content) {
+    rulesBlock = `## Project Rules
+
+> Sumber: \`${rules.path}\` \u2014 konvensi proyek, berlaku untuk task ini.
+` + (rules.truncated ? `> (dipotong ke anggaran \u2014 baca file langsung untuk lengkapnya)
+` : ``) + `
+${demoteHeadings(rules.content)}
+
+`;
+  }
+  if (opts?.knowledge) {
+    const mdKnowledge = `# Task Context (Knowledge)
+
+## Task
+${task}
+
+## Complexity
+${cls.complexity} (${cls.reasons.join("; ")})
+
+` + rulesBlock + `## Ringkasan
+File relevan: ${highFiles.slice(0, 5).join(", ") || "-"}${medFiles.length > 0 ? ` (lihat juga: ${medFiles.slice(0, 5).join(", ")})` : ""}
+Simbol kunci: ${hi.slice(0, 5).map((r) => `\`${r.name}\``).join(", ") || "-"}
+
+## Kenapa (trace 2-hop)
+${deps.map((d) => `- ${d}`).join("\n") || "-"}
+
+` + (hotspots.length > 0 ? `## Hotspot arsitektur
+${hotspots.join("\n")}
+
+` : ``) + `## Cara pakai
+${hi.slice(0, 8).map(symLine).join("\n") || "-"}
+
+## Related Tests
+${tests.map((t) => `- ${t}`).join("\n") || "-"}
+
+` + historyBlock + cycleWarn;
+    return { markdown: mdKnowledge, high: highFiles, medium: medFiles, tests, dependencies: deps };
+  }
   const md = `# Task Context
 
 ## Task
@@ -222,7 +265,7 @@ ${task}
 ## Complexity
 ${cls.complexity} (${cls.reasons.join("; ")})
 
-## Relevant Files
+` + rulesBlock + `## Relevant Files
 ### HIGH
 ${highFiles.map((f) => `- ${f}`).join("\n") || "-"}
 ### MEDIUM

package/dist/chunk-ZV4BSIQM.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+// src/scope/agentsmd.ts
+import fs from "fs";
+import path from "path";
+var CANDIDATES = ["AGENTS.md", "agents.md"];
+var PROJECT_RULES_MAX_CHARS = 4e3;
+function findAgentsMd(repoRoot) {
+  for (const name of CANDIDATES) {
+    try {
+      if (fs.statSync(path.join(repoRoot, name)).isFile()) return name;
+    } catch {
+    }
+  }
+  return null;
+}
+function loadProjectRules(repoRoot, maxChars = PROJECT_RULES_MAX_CHARS) {
+  if (typeof maxChars === "number" && maxChars <= 0) return null;
+  const rel = findAgentsMd(repoRoot);
+  if (!rel) return null;
+  const cap = Math.max(
+    500,
+    Number.isFinite(maxChars) ? Math.floor(maxChars) : PROJECT_RULES_MAX_CHARS
+  );
+  const fullPath = path.join(repoRoot, rel);
+  let text;
+  let fileExceedsCap = false;
+  try {
+    const stat = fs.statSync(fullPath);
+    const bytesToRead = Math.min(stat.size, cap * 4);
+    fileExceedsCap = stat.size > bytesToRead;
+    const fd = fs.openSync(fullPath, "r");
+    try {
+      const buf = Buffer.alloc(bytesToRead);
+      const bytesRead = fs.readSync(fd, buf, 0, bytesToRead, 0);
+      text = buf.subarray(0, bytesRead).toString("utf8");
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+  text = text.replace(/\r\n/g, "\n").trim();
+  if (!text) return null;
+  if (fileExceedsCap || text.length > cap) {
+    return { path: rel, content: text.slice(0, cap).trimEnd(), truncated: true };
+  }
+  return { path: rel, content: text, truncated: false };
+}
+function demoteHeadings(markdown) {
+  let inCodeBlock = false;
+  return markdown.split("\n").map((line) => {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
+      inCodeBlock = !inCodeBlock;
+      return line;
+    }
+    if (!inCodeBlock && /^#{1,6}\s/.test(line)) {
+      return line.replace(/^(#{1,6})\s/, (_, hashes) => {
+        const nextLevel = Math.min(6, hashes.length + 2);
+        return "#".repeat(nextLevel) + " ";
+      });
+    }
+    return line;
+  }).join("\n");
+}
+
+export {
+  PROJECT_RULES_MAX_CHARS,
+  findAgentsMd,
+  loadProjectRules,
+  demoteHeadings
+};