@abdulmunimjemal/codescope 0.2.0 → 0.3.0

package/README.md

@@ -36,12 +36,12 @@ incumbent and shares codescope's architecture. In a **measured head-to-head**
 - **~4× faster indexing** (696 ms vs 2,855 ms on a 262-file repo; 5.2 s vs 20 s on 3,500 files).
 - **3–5× smaller index** on disk (2.5 MB vs 8.2 MB; 22.9 MB vs 112.8 MB).
 - **Fewer tokens per answer** for definition lookups on every repo tested; callers is ≈parity.
-- Feature parity on the core graph queries: `callers`, `callees`, `impact`, `context`.
+- **Feature parity:** `callers`, `callees`, `impact`, `context`, **`affected`** (test-impact), and **`install`** (agent auto-wiring) — plus **20 languages**.
 
-codegraph still leads on **language breadth** (20+ vs 12), **extra tooling**
-(`affected` test-impact, agent auto-install), and **maturity/adoption**. Pick
-codescope when footprint, index speed, and token cost matter most; pick codegraph
-when you need the widest language coverage and the extra tooling.
+codegraph still leads on **maturity & adoption** (35k★, a real user base) and
+indexes a few extra node kinds (constants, properties, routes). Pick codescope
+when footprint, index speed, and token cost matter; pick codegraph for the most
+battle-tested option.
 
 ## Install
 
@@ -55,11 +55,20 @@ collides with an existing package; the installed command is still `codescope`.)
 
 ## Quick start
 
-Point your agent at codescope as an MCP server. It indexes the repo, starts
-watching for changes, and serves the graph over stdio:
+The one-liner — wire codescope into your agents automatically, from your repo:
 
 ```bash
-codescope mcp /path/to/your/repo
+npx @abdulmunimjemal/codescope install     # adds codescope to Claude Code + Cursor
+```
+
+That writes the MCP server config (non-destructively) so your agent launches
+codescope on the repo. Restart the agent and you're done. `--agent claude|cursor`
+targets one; `--global` writes to your home dir instead of the project.
+
+Prefer to wire it by hand? The server command is:
+
+```bash
+codescope mcp /path/to/your/repo            # index, watch, and serve over stdio
 ```
 
 **Claude Code** (`.mcp.json` or `claude mcp add`):
@@ -82,6 +91,10 @@ codescope index .                       # build the graph, print stats
 codescope search useState               # fuzzy symbol search
 codescope get GraphStore                # jump to a definition
 codescope callers parseSource           # who calls this
+codescope callees indexAll              # what it calls
+codescope impact GraphStore             # blast radius before a change
+codescope context "auth flow"           # ranked relevance map for a task
+codescope affected src/store.ts         # which tests are affected by a change
 codescope neighborhood handleRequest --depth 3
 codescope watch .                       # keep the graph fresh, log updates
 ```
@@ -127,7 +140,10 @@ The index lives in `.codescope/graph.db` (add `.codescope/` to your
 
 ## Languages
 
-TypeScript, JavaScript, TSX/JSX, Python, Go, Rust, Java, Ruby, C, C++, C#, PHP.
+20 languages: TypeScript, JavaScript, TSX/JSX, Python, Go, Rust, Java, Ruby, C,
+C++, C#, PHP, Scala, Solidity, Zig, Kotlin, Objective-C, Lua, Bash, and OCaml.
+Definition extraction (functions, classes, methods, …) works for all; call and
+import edges are available for the languages whose grammars expose them.
 
 ## Programmatic API
 

package/dist/cli.js

@@ -1,10 +1,62 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { mkdirSync } from "fs";
+import { mkdirSync as mkdirSync2 } from "fs";
 import { resolve as resolve2 } from "path";
 import pc from "picocolors";
 
+// src/affected.ts
+var TEST_PATTERNS = [
+  /(^|\/)(tests?|spec|specs|__tests__|e2e|integration)\//i,
+  /\.(test|spec)\.[a-z]+$/i,
+  // foo.test.ts, foo.spec.js
+  /_test\.[a-z]+$/i,
+  // foo_test.go, foo_test.py, foo_test.rs
+  /(^|\/)test_[^/]+\.(py|rb)$/i,
+  // test_foo.py
+  /(Test|Tests|Spec)\.[a-z]+$/i,
+  // FooTest.java, FooTests.cs, FooSpec.scala
+  /_spec\.rb$/i
+  // foo_spec.rb
+];
+function isTestFile(path) {
+  return TEST_PATTERNS.some((re) => re.test(path));
+}
+function moduleBasename(path) {
+  const base = path.slice(path.lastIndexOf("/") + 1);
+  const dot = base.indexOf(".");
+  return dot === -1 ? base : base.slice(0, dot);
+}
+function affected(store, changedPaths, opts = {}) {
+  const depth = opts.depth ?? 4;
+  const impactedFiles = new Set(changedPaths);
+  for (const path of changedPaths) {
+    for (const sym of store.fileOutline(path)) {
+      for (const caller of store.impact(sym.name, { depth })) {
+        impactedFiles.add(caller.file);
+      }
+    }
+  }
+  let frontier = [...changedPaths];
+  for (let d = 0; d < depth && frontier.length > 0; d++) {
+    const next = [];
+    for (const path of frontier) {
+      for (const importer of store.findImporters(moduleBasename(path))) {
+        if (!impactedFiles.has(importer)) {
+          impactedFiles.add(importer);
+          next.push(importer);
+        }
+      }
+    }
+    frontier = next;
+  }
+  return {
+    changed: changedPaths,
+    impactedFiles: [...impactedFiles].sort(),
+    tests: [...impactedFiles].filter(isTestFile).sort()
+  };
+}
+
 // src/format.ts
 function shortSig(sig) {
   if (!sig) return "";
@@ -60,6 +112,14 @@ function formatContext(b) {
   }
   return lines.join("\n");
 }
+function formatAffected(r) {
+  if (r.tests.length === 0) {
+    return `No test files appear affected by ${r.changed.length} changed file(s).`;
+  }
+  const lines = [`${r.tests.length} test file(s) affected by your changes:`, ""];
+  for (const t of r.tests) lines.push(`  ${t}`);
+  return lines.join("\n");
+}
 function formatStats(s) {
   const kinds = Object.entries(s.byKind).sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k}=${n}`).join(" ");
   const langs = Object.entries(s.byLang).sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k}=${n}`).join(" ");
@@ -290,6 +350,118 @@ var php = {
   importRules: [{ type: "namespace_use_declaration", childTypes: ["namespace_use_clause"] }],
   exportTypes: /* @__PURE__ */ new Set()
 };
+var scala = {
+  id: "scala",
+  wasm: "scala",
+  defs: {
+    class_definition: { kind: "class" },
+    object_definition: { kind: "class" },
+    trait_definition: { kind: "interface" },
+    function_definition: { kind: "method" },
+    type_definition: { kind: "type" }
+  },
+  functionBindings: /* @__PURE__ */ new Set(),
+  nestedFunctionsAreMethods: false,
+  callRules: [
+    { type: "call_expression", fnField: "function", memberTypes: ["field_expression"], memberField: "field" }
+  ],
+  importRules: [{ type: "import_declaration", childTypes: ["stable_identifier", "identifier"] }],
+  exportTypes: /* @__PURE__ */ new Set()
+};
+var solidity = {
+  id: "solidity",
+  wasm: "solidity",
+  defs: {
+    contract_declaration: { kind: "class" },
+    interface_declaration: { kind: "interface" },
+    library_declaration: { kind: "class" },
+    function_definition: { kind: "method" },
+    modifier_definition: { kind: "function" },
+    struct_declaration: { kind: "class" },
+    enum_declaration: { kind: "enum" }
+  },
+  functionBindings: /* @__PURE__ */ new Set(),
+  nestedFunctionsAreMethods: false,
+  callRules: [{ type: "call_expression", fnField: "function" }],
+  importRules: [{ type: "import_directive", field: "source" }],
+  exportTypes: /* @__PURE__ */ new Set()
+};
+var zig = {
+  id: "zig",
+  wasm: "zig",
+  defs: { function_declaration: { kind: "function" } },
+  functionBindings: /* @__PURE__ */ new Set(),
+  nestedFunctionsAreMethods: false,
+  callRules: [{ type: "call_expression", fnField: "function" }],
+  importRules: [],
+  exportTypes: /* @__PURE__ */ new Set()
+};
+var kotlin = {
+  id: "kotlin",
+  wasm: "kotlin",
+  defs: {
+    class_declaration: { kind: "class", name: "first_typed", nameTypes: ["type_identifier"] },
+    object_declaration: { kind: "class", name: "first_typed", nameTypes: ["type_identifier"] },
+    function_declaration: { kind: "function", name: "first_typed", nameTypes: ["simple_identifier"] }
+  },
+  functionBindings: /* @__PURE__ */ new Set(),
+  nestedFunctionsAreMethods: true,
+  callRules: [],
+  importRules: [{ type: "import_header", childTypes: ["identifier"] }],
+  exportTypes: /* @__PURE__ */ new Set()
+};
+var objc = {
+  id: "objc",
+  wasm: "objc",
+  defs: {
+    class_interface: { kind: "class", name: "first_typed", nameTypes: ["identifier"] },
+    class_implementation: { kind: "class", name: "first_typed", nameTypes: ["identifier"] },
+    method_declaration: { kind: "method", name: "first_typed", nameTypes: ["identifier"] },
+    method_definition: { kind: "method", name: "first_typed", nameTypes: ["identifier"] }
+  },
+  functionBindings: /* @__PURE__ */ new Set(),
+  nestedFunctionsAreMethods: false,
+  callRules: [{ type: "call_expression", fnField: "function" }],
+  importRules: [{ type: "preproc_include", field: "path" }],
+  exportTypes: /* @__PURE__ */ new Set()
+};
+var lua = {
+  id: "lua",
+  wasm: "lua",
+  defs: {
+    function_definition_statement: { kind: "function" },
+    local_function_definition_statement: { kind: "function" }
+  },
+  functionBindings: /* @__PURE__ */ new Set(),
+  nestedFunctionsAreMethods: false,
+  callRules: [],
+  importRules: [],
+  exportTypes: /* @__PURE__ */ new Set()
+};
+var bash = {
+  id: "bash",
+  wasm: "bash",
+  defs: { function_definition: { kind: "function" } },
+  functionBindings: /* @__PURE__ */ new Set(),
+  nestedFunctionsAreMethods: false,
+  callRules: [],
+  importRules: [],
+  exportTypes: /* @__PURE__ */ new Set()
+};
+var ocaml = {
+  id: "ocaml",
+  wasm: "ocaml",
+  defs: {
+    let_binding: { kind: "function", name: "field", nameField: "pattern" },
+    module_definition: { kind: "class" },
+    type_definition: { kind: "type" }
+  },
+  functionBindings: /* @__PURE__ */ new Set(),
+  nestedFunctionsAreMethods: false,
+  callRules: [],
+  importRules: [],
+  exportTypes: /* @__PURE__ */ new Set()
+};
 var LANGUAGES = {
   typescript,
   tsx,
@@ -302,7 +474,15 @@ var LANGUAGES = {
   c,
   cpp,
   csharp,
-  php
+  php,
+  scala,
+  solidity,
+  zig,
+  kotlin,
+  objc,
+  lua,
+  bash,
+  ocaml
 };
 var EXT_TO_LANG = {
   ".ts": "typescript",
@@ -327,7 +507,19 @@ var EXT_TO_LANG = {
   ".hpp": "cpp",
   ".hh": "cpp",
   ".cs": "csharp",
-  ".php": "php"
+  ".php": "php",
+  ".scala": "scala",
+  ".sc": "scala",
+  ".sol": "solidity",
+  ".zig": "zig",
+  ".kt": "kotlin",
+  ".kts": "kotlin",
+  ".m": "objc",
+  ".lua": "lua",
+  ".sh": "bash",
+  ".bash": "bash",
+  ".ml": "ocaml",
+  ".mli": "ocaml"
 };
 var SUPPORTED_EXTENSIONS = Object.keys(EXT_TO_LANG);
 function languageForPath(path) {
@@ -413,7 +605,7 @@ function classify(node, lang) {
   return null;
 }
 function buildSymbol(node, rule, container, containerKind, lang) {
-  const name = symbolName(node, rule.name ?? "field");
+  const name = symbolName(node, rule);
   if (!name) return null;
   let kind = rule.kind;
   if (kind === "function" && lang.nestedFunctionsAreMethods && containerKind === "class") {
@@ -433,9 +625,20 @@ function buildSymbol(node, rule, container, containerKind, lang) {
     endByte: node.endIndex
   };
 }
-function symbolName(node, strategy) {
-  if (strategy === "c_declarator") return cDeclaratorName(node);
-  return node.childForFieldName("name")?.text ?? null;
+function symbolName(node, rule) {
+  switch (rule.name ?? "field") {
+    case "c_declarator":
+      return cDeclaratorName(node);
+    case "first_typed": {
+      const types = rule.nameTypes ?? [];
+      for (const child of node.namedChildren) {
+        if (types.includes(child.type)) return child.text;
+      }
+      return null;
+    }
+    default:
+      return node.childForFieldName(rule.nameField ?? "name")?.text ?? null;
+  }
 }
 function cDeclaratorName(node) {
   let decl = node.childForFieldName("declarator");
@@ -651,13 +854,65 @@ function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
 
+// src/install.ts
+import { existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var PACKAGE = "@abdulmunimjemal/codescope";
+var MCP_SERVER_NAME = "codescope";
+var SUPPORTED_AGENTS = ["claude", "cursor"];
+function serverEntry(serveTarget = ".") {
+  return { command: "npx", args: ["-y", PACKAGE, "mcp", serveTarget] };
+}
+function configPath(agent, root, global = false) {
+  switch (agent) {
+    case "claude":
+      return global ? join(homedir(), ".mcp.json") : join(root, ".mcp.json");
+    case "cursor":
+      return global ? join(homedir(), ".cursor", "mcp.json") : join(root, ".cursor", "mcp.json");
+  }
+}
+function readJson(path) {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function installInto(agent, root, opts = {}) {
+  const path = configPath(agent, root, opts.global ?? false);
+  const config = readJson(path);
+  const existing = config.mcpServers;
+  const servers = existing && typeof existing === "object" ? existing : {};
+  const existed = Object.prototype.hasOwnProperty.call(servers, MCP_SERVER_NAME);
+  servers[MCP_SERVER_NAME] = serverEntry(opts.serveTarget);
+  config.mcpServers = servers;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}
+`);
+  return { agent, path, action: existed ? "updated" : "added" };
+}
+function install(root, opts = {}) {
+  const agents = opts.agents ?? [...SUPPORTED_AGENTS];
+  return agents.map((agent) => installInto(agent, root, opts));
+}
+function codexSnippet(serveTarget = ".") {
+  return [
+    "[mcp_servers.codescope]",
+    'command = "npx"',
+    `args = ["-y", "${PACKAGE}", "mcp", "${serveTarget}"]`
+  ].join("\n");
+}
+
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 
 // src/mcp.ts
 var KIND = z.enum(["function", "method", "class", "interface", "type", "enum", "variable"]);
@@ -777,6 +1032,18 @@ function createServer(store) {
     },
     async ({ name, depth, limit }) => textResult(formatNeighborhood(store.neighborhood(name, { depth, limit })))
   );
+  server.registerTool(
+    "affected",
+    {
+      title: "Affected tests",
+      description: "Given a list of changed files, return the test files likely affected \u2014 the symbols those files define, walked through their transitive callers, filtered to tests. Use before running a suite to know what's worth re-running.",
+      inputSchema: {
+        files: z.array(z.string()).describe("repo-relative paths of the changed files"),
+        depth: z.number().int().min(1).max(6).optional()
+      }
+    },
+    async ({ files, depth }) => textResult(formatAffected(affected(store, files, { depth })))
+  );
   server.registerTool(
     "stats",
     {
@@ -1097,6 +1364,18 @@ var GraphStore = class {
     ).all(name, limit);
     return rows.map(toRefRow);
   }
+  /**
+   * Files whose imports reference a module basename (e.g. `store` for
+   * `src/store.ts`). Matches `import … from "./store"`, `"../src/store.js"`,
+   * etc. Used by affected-test analysis to follow import edges, which — unlike
+   * call edges — reliably reach test files (tests import the module under test).
+   */
+  findImporters(moduleBasename2) {
+    return this.db.prepare(
+      `SELECT DISTINCT f.path FROM refs r JOIN files f ON f.id = r.file_id
+         WHERE r.kind = 'import' AND (r.name = ? OR r.name LIKE ? OR r.name LIKE ?)`
+    ).all(moduleBasename2, `%/${moduleBasename2}`, `%/${moduleBasename2}.%`).map((r) => r.path);
+  }
   /** The symbols defined in a file, in source order. */
   fileOutline(path) {
     return this.db.prepare(
@@ -1285,6 +1564,7 @@ Usage:
   codescope <command> [path] [options]
 
 Commands:
+  install [path]          Wire codescope into your agents (Claude Code, Cursor) automatically.
   mcp [path]              Index, watch for changes, and serve the graph over MCP (stdio).
                           This is what you wire into Claude Code / Cursor / Codex.
   index [path]            Build (or refresh) the on-disk graph and print stats.
@@ -1296,9 +1576,12 @@ Commands:
   callees <name> [path]   List what a function/method calls.
   impact <name> [path]    Transitive callers (blast radius) of a symbol.
   context <query> [path]  Ranked relevance map for a task (matches + neighbours).
+  affected <files...>     Test files affected by a set of changed files.
   neighborhood <name>     Show the call neighbourhood around a symbol.
 
 Options:
+  --agent <name>          install target: claude | cursor | all (default all).
+  --global                install: write to your home dir instead of the project.
   --path <dir>            Repository root (default: current directory or the positional path).
   --db <file>            SQLite graph location (default: <root>/.codescope/graph.db).
   --memory               Use an in-memory graph (not persisted).
@@ -1315,13 +1598,19 @@ Examples:
   codescope mcp .            # add this command to your agent's MCP config
 `;
 function parseArgs(argv) {
-  const flags = { positional: [], memory: false };
+  const flags = { positional: [], memory: false, global: false };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     switch (arg) {
       case "--memory":
         flags.memory = true;
         break;
+      case "--global":
+        flags.global = true;
+        break;
+      case "--agent":
+        flags.agent = argv[++i];
+        break;
       case "--path":
         flags.path = argv[++i];
         break;
@@ -1349,7 +1638,7 @@ function rootDir(flags, positionalRootIndex = 0) {
 function openStore(root, flags) {
   if (flags.memory) return new GraphStore(":memory:");
   const dir = resolve2(root, ".codescope");
-  mkdirSync(dir, { recursive: true });
+  mkdirSync2(dir, { recursive: true });
   return new GraphStore(flags.db ?? resolve2(dir, "graph.db"));
 }
 async function ensureIndexed(indexer, store) {
@@ -1421,6 +1710,32 @@ async function cmdQuery(command, root, flags) {
 `);
   store.close();
 }
+async function cmdAffected(root, flags) {
+  const files = flags.positional;
+  if (files.length === 0) fail("'affected' needs one or more changed file paths. See --help.");
+  const store = openStore(root, flags);
+  const indexer = new Indexer(store, root);
+  await ensureIndexed(indexer, store);
+  const rels = files.map((f) => indexer.rel(resolve2(root, f)));
+  process.stdout.write(`${formatAffected(affected(store, rels, { depth: flags.depth }))}
+`);
+  store.close();
+}
+function cmdInstall(root, flags) {
+  const agents = !flags.agent || flags.agent === "all" ? [...SUPPORTED_AGENTS] : SUPPORTED_AGENTS.includes(flags.agent) ? [flags.agent] : fail(`unknown --agent '${flags.agent}'. Use: ${SUPPORTED_AGENTS.join(", ")}, or all.`);
+  const results = install(root, { agents, global: flags.global });
+  for (const r of results) {
+    process.stdout.write(`${pc.green("\u2713")} ${r.action} codescope for ${pc.bold(r.agent)} \u2192 ${r.path}
+`);
+  }
+  process.stdout.write(
+    `
+${pc.dim("Restart your agent to pick up the change.")}
+${pc.dim("Codex (TOML config) \u2014 add this to ~/.codex/config.toml:")}
+${codexSnippet()}
+`
+  );
+}
 async function cmdWatch(root, flags) {
   const store = openStore(root, flags);
   const indexer = new Indexer(store, root);
@@ -1487,6 +1802,10 @@ async function main() {
     case "context":
     case "neighborhood":
       return cmdQuery(command, resolve2(flags.path ?? flags.positional[1] ?? "."), flags);
+    case "affected":
+      return cmdAffected(resolve2(flags.path ?? "."), flags);
+    case "install":
+      return cmdInstall(rootDir(flags), flags);
     case "watch":
       return cmdWatch(rootDir(flags), flags);
     case "mcp":