@abdulmunimjemal/codescope 0.1.0 → 0.3.0

package/dist/index.js

@@ -180,15 +180,119 @@ var GraphStore = class {
          WHERE s.name = ? ORDER BY s.exported DESC, f.path LIMIT ?`
     ).all(name, clampLimit(opts.limit)).map(toSymbolRow);
   }
-  /** Symbols that call a given name (both bare `foo()` and `x.foo()`). */
+  /**
+   * Distinct callers of a name (both bare `foo()` and `x.foo()`). Multiple call
+   * sites from the same caller in the same file collapse to one row — fewer
+   * tokens and a more useful "who depends on this" answer.
+   */
   findCallers(name, opts = {}) {
     return this.db.prepare(
-      `SELECT r.id, f.path AS file, r.from_symbol, r.name, r.kind, r.start_row, r.start_col
+      `SELECT MIN(r.id) AS id, f.path AS file, r.from_symbol, r.name,
+                MIN(r.kind) AS kind, MIN(r.start_row) AS start_row, MIN(r.start_col) AS start_col
          FROM refs r JOIN files f ON f.id = r.file_id
          WHERE r.name = ? AND r.kind IN ('call', 'method')
-         ORDER BY f.path, r.start_row LIMIT ?`
+         GROUP BY f.path, r.from_symbol
+         ORDER BY f.path, start_row LIMIT ?`
     ).all(name, clampLimit(opts.limit)).map(toRefRow);
   }
+  /** The definitions that a symbol calls, resolved kind-aware to project symbols. */
+  findCallees(name, opts = {}) {
+    const limit = clampLimit(opts.limit);
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const callee of this.calleesOf(name)) {
+      const defs = this.resolveCallee(callee.name, callee.kind, 6);
+      if (!defs) continue;
+      for (const d of defs) {
+        const key = `${d.name}@${d.file}:${d.startRow}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          out.push(d);
+          if (out.length >= limit) return out;
+        }
+      }
+    }
+    return out;
+  }
+  /** How many call sites reference this name (popularity / centrality signal). */
+  callerCount(name) {
+    return this.db.prepare(
+      "SELECT COUNT(*) AS n FROM refs WHERE name = ? AND kind IN ('call','method')"
+    ).get(name)?.n ?? 0;
+  }
+  /**
+   * The blast radius of changing a symbol: its transitive callers, breadth-first,
+   * annotated with hop distance and ordered nearest-first. Answers "what could
+   * break if I change this?" without reading the codebase.
+   */
+  impact(name, opts = {}) {
+    const depth = Math.max(1, Math.min(opts.depth ?? 3, 6));
+    const limit = clampLimit(opts.limit, 300);
+    const distance = /* @__PURE__ */ new Map([[name, 0]]);
+    let frontier = [name];
+    for (let d = 0; d < depth && frontier.length > 0 && distance.size < limit; d++) {
+      const next = [];
+      for (const node of frontier) {
+        for (const caller of this.callersOf(node)) {
+          if (!distance.has(caller)) {
+            distance.set(caller, d + 1);
+            next.push(caller);
+          }
+        }
+      }
+      frontier = next;
+    }
+    const out = [];
+    for (const [n, dist] of distance) {
+      if (dist === 0) continue;
+      for (const def of this.getSymbol(n, { limit: 3 })) out.push({ ...def, distance: dist });
+    }
+    out.sort((a, b) => a.distance - b.distance || a.file.localeCompare(b.file));
+    return out.slice(0, limit);
+  }
+  /**
+   * A token-budgeted relevance map for a task: the symbols matching `query` plus
+   * their immediate call neighbourhood, ranked by call-site centrality, capped at
+   * `maxSymbols`. This is the slice of the codebase an agent needs to start a
+   * change — delivered as graph facts, not file dumps.
+   */
+  context(query, opts = {}) {
+    const maxSymbols = Math.max(5, Math.min(opts.maxSymbols ?? 30, 100));
+    const seeds = this.searchSymbols(query, { limit: Math.min(8, maxSymbols) });
+    const picked = /* @__PURE__ */ new Map();
+    const key = (s) => `${s.name}@${s.file}:${s.startRow}`;
+    for (const s of seeds) picked.set(key(s), s);
+    const candidates = /* @__PURE__ */ new Map();
+    const edges = [];
+    const edgeKeys = /* @__PURE__ */ new Set();
+    for (const seed of seeds) {
+      for (const callee of this.findCallees(seed.name, { limit: 15 })) {
+        addEdge(edges, edgeKeys, seed.name, callee.name);
+        const k = key(callee);
+        if (!picked.has(k) && !candidates.has(k)) {
+          candidates.set(k, { row: callee, score: this.callerCount(callee.name) });
+        }
+      }
+      for (const caller of this.findCallers(seed.name, { limit: 15 })) {
+        if (!caller.fromSymbol) continue;
+        addEdge(edges, edgeKeys, caller.fromSymbol, seed.name);
+        for (const def of this.getSymbol(caller.fromSymbol, { limit: 1 })) {
+          const k = key(def);
+          if (!picked.has(k) && !candidates.has(k)) {
+            candidates.set(k, { row: def, score: this.callerCount(def.name) });
+          }
+        }
+      }
+    }
+    const related = [...candidates.values()].sort((a, b) => b.score - a.score).slice(0, Math.max(0, maxSymbols - picked.size)).map((c2) => c2.row);
+    const keptNames = new Set([...seeds, ...related].map((s) => s.name));
+    return {
+      query,
+      seeds,
+      related,
+      edges: edges.filter((e) => keptNames.has(e.from) && keptNames.has(e.to))
+    };
+  }
   /** All references (calls + imports) to a name. */
   findReferences(name, opts = {}) {
     const limit = clampLimit(opts.limit);
@@ -203,6 +307,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(
@@ -579,6 +695,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,
@@ -591,7 +819,15 @@ var LANGUAGES = {
   c,
   cpp,
   csharp,
-  php
+  php,
+  scala,
+  solidity,
+  zig,
+  kotlin,
+  objc,
+  lua,
+  bash,
+  ocaml
 };
 var EXT_TO_LANG = {
   ".ts": "typescript",
@@ -616,7 +852,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) {
@@ -702,7 +950,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") {
@@ -722,9 +970,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");
@@ -969,20 +1228,79 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 
+// 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
 var format_exports = {};
 __export(format_exports, {
+  formatAffected: () => formatAffected,
+  formatContext: () => formatContext,
+  formatImpact: () => formatImpact,
   formatNeighborhood: () => formatNeighborhood,
   formatRefs: () => formatRefs,
   formatStats: () => formatStats,
   formatSymbols: () => formatSymbols
 });
+function shortSig(sig) {
+  if (!sig) return "";
+  const s = sig.length > 88 ? `${sig.slice(0, 87)}\u2026` : sig;
+  return `  \xB7  ${s}`;
+}
 function symbolLine(s) {
   const loc = `${s.file}:${s.startRow + 1}`;
   const container = s.container ? `${s.container}.` : "";
   const exp = s.exported ? "export " : "";
-  const sig = s.signature ? `  \xB7  ${s.signature}` : "";
-  return `${s.kind} ${exp}${container}${s.name} \u2014 ${loc}${sig}`;
+  return `${s.kind} ${exp}${container}${s.name} \u2014 ${loc}${shortSig(s.signature)}`;
 }
 function formatSymbols(rows) {
   if (rows.length === 0) return "No matching symbols.";
@@ -991,8 +1309,8 @@ function formatSymbols(rows) {
 function formatRefs(rows) {
   if (rows.length === 0) return "No references.";
   return rows.map((r) => {
-    const where = r.fromSymbol ? `${r.fromSymbol}` : "(top level)";
-    return `${where} \u2192 ${r.name} [${r.kind}] \u2014 ${r.file}:${r.startRow + 1}`;
+    const where = r.fromSymbol ?? "(top level)";
+    return `${r.file}:${r.startRow + 1}  ${where}`;
   }).join("\n");
 }
 function formatNeighborhood(n) {
@@ -1009,6 +1327,32 @@ function formatNeighborhood(n) {
   }
   return lines.join("\n");
 }
+function formatImpact(rows) {
+  if (rows.length === 0) return "No callers \u2014 changing this is low-risk.";
+  return rows.map((r) => `[${r.distance} hop] ${symbolLine(r)}`).join("\n");
+}
+function formatContext(b) {
+  const lines = [`context for "${b.query}":`, "", "matches:"];
+  if (b.seeds.length === 0) lines.push("  (no symbols matched)");
+  else for (const s of b.seeds) lines.push(`  ${symbolLine(s)}`);
+  if (b.related.length > 0) {
+    lines.push("", "related (ranked by call-site centrality):");
+    for (const s of b.related) lines.push(`  ${symbolLine(s)}`);
+  }
+  if (b.edges.length > 0) {
+    lines.push("", "call edges:");
+    for (const e of b.edges) lines.push(`  ${e.from} \u2192 ${e.to}`);
+  }
+  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(" ");
@@ -1021,7 +1365,7 @@ function formatStats(s) {
 }
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.3.0";
 
 // src/mcp.ts
 var KIND = z.enum(["function", "method", "class", "interface", "type", "enum", "variable"]);
@@ -1067,6 +1411,43 @@ function createServer(store) {
     },
     async ({ name, limit }) => textResult(formatRefs(store.findCallers(name, { limit })))
   );
+  server.registerTool(
+    "find_callees",
+    {
+      title: "Find callees",
+      description: "List the functions/methods that a given symbol calls (resolved to their definitions). The outgoing side of the call graph \u2014 what this symbol depends on.",
+      inputSchema: {
+        name: z.string().describe("the calling function/method name"),
+        limit: z.number().int().positive().max(500).optional()
+      }
+    },
+    async ({ name, limit }) => textResult(formatSymbols(store.findCallees(name, { limit })))
+  );
+  server.registerTool(
+    "impact",
+    {
+      title: "Change impact / blast radius",
+      description: "Show the transitive callers of a symbol \u2014 everything that could be affected if you change it \u2014 annotated with hop distance. Use before editing a widely-used function.",
+      inputSchema: {
+        name: z.string(),
+        depth: z.number().int().min(1).max(6).optional().describe("hops to expand (default 3)"),
+        limit: z.number().int().positive().max(300).optional()
+      }
+    },
+    async ({ name, depth, limit }) => textResult(formatImpact(store.impact(name, { depth, limit })))
+  );
+  server.registerTool(
+    "context",
+    {
+      title: "Build task context",
+      description: "Given a task or feature query, return a compact, ranked relevance map: the matching symbols plus their immediate call neighbourhood, ordered by how widely each is called. The fastest way to orient an agent before a change \u2014 graph facts instead of reading files.",
+      inputSchema: {
+        query: z.string().describe("a task description or symbol/feature name"),
+        maxSymbols: z.number().int().min(5).max(100).optional().describe("cap on symbols (default 30)")
+      }
+    },
+    async ({ query, maxSymbols }) => textResult(formatContext(store.context(query, { maxSymbols })))
+  );
   server.registerTool(
     "find_references",
     {
@@ -1104,6 +1485,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",
     {
@@ -1120,17 +1513,77 @@ async function runStdioServer(store) {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
+
+// 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");
+}
 export {
   GraphStore,
   Indexer,
   LANGUAGES,
+  SUPPORTED_AGENTS,
   SUPPORTED_EXTENSIONS,
   VERSION,
+  affected,
+  codexSnippet,
+  configPath,
   createServer,
   format_exports as format,
+  install,
+  installInto,
+  isTestFile,
   languageForPath,
   parseSource,
   runStdioServer,
+  serverEntry,
   watch
 };
 //# sourceMappingURL=index.js.map