@abdulmunimjemal/codescope 0.1.0 → 0.2.0

package/README.md

@@ -28,15 +28,20 @@ a changed file in **~0.5 ms** — roughly **3,000× cheaper than a full re-index
 
 ## How it compares to codegraph
 
-If you know [codegraph](https://github.com/colbymchenry/codegraph) (~35k★): it's
-the mature, feature-rich option — 20+ languages, impact/test-affected analysis, a
-task-context builder, agent auto-install — and it already does incremental
-indexing and file-watching. **codescope doesn't try to out-feature it.** In a
-measured head-to-head ([BENCHMARKS.md](./BENCHMARKS.md)) codescope's edge is being
-**leaner**: ~3× smaller index DB and faster pure indexing on the same repo, a
-~1k-LOC auditable codebase, and zero-config `npx codescope mcp .`. Pick codescope
-if you want something small, fast, and easy to read; pick codegraph if you want
-the deepest feature set and widest language coverage.
+[codegraph](https://github.com/colbymchenry/codegraph) (~35k★) is the mature
+incumbent and shares codescope's architecture. In a **measured head-to-head**
+([BENCHMARKS.md](./BENCHMARKS.md), both tools run on the same repos), codescope
+**wins the efficiency axes**:
+
+- **~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`.
+
+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.
 
 ## Install
 
@@ -87,7 +92,10 @@ codescope watch .                       # keep the graph fresh, log updates
 |------|-----------------|
 | `search_symbols(query, kind?, limit?)` | fuzzy substring search over definitions — use instead of grep/glob |
 | `get_symbol(name, limit?)` | jump to a definition by exact name (kind, `file:line`, signature) |
-| `find_callers(name, limit?)` | who calls this function/method |
+| `find_callers(name, limit?)` | who calls this function/method (distinct callers) |
+| `find_callees(name, limit?)` | what this symbol calls — its outgoing dependencies |
+| `impact(name, depth?, limit?)` | transitive callers (blast radius) before you change something |
+| `context(query, maxSymbols?)` | a ranked relevance map for a task — matches + neighbours, the fastest way to orient |
 | `find_references(name, kind?, limit?)` | all calls + imports of a name |
 | `file_outline(path)` | every symbol in a file, in order — a compact alternative to reading it |
 | `neighborhood(name, depth?, limit?)` | the call neighbourhood (callers + callees) around a symbol, as a subgraph |

package/dist/cli.js

@@ -6,12 +6,16 @@ import { resolve as resolve2 } from "path";
 import pc from "picocolors";
 
 // src/format.ts
+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.";
@@ -20,8 +24,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) {
@@ -38,6 +42,24 @@ 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 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(" ");
@@ -635,7 +657,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 
 // src/mcp.ts
 var KIND = z.enum(["function", "method", "class", "interface", "type", "enum", "variable"]);
@@ -681,6 +703,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",
     {
@@ -911,15 +970,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);
@@ -1130,6 +1293,9 @@ Commands:
   search <query> [path]   Fuzzy-search symbol names.
   get <name> [path]       Look up a definition by exact name.
   callers <name> [path]   List callers of a function/method.
+  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).
   neighborhood <name>     Show the call neighbourhood around a symbol.
 
 Options:
@@ -1236,6 +1402,15 @@ async function cmdQuery(command, root, flags) {
     case "callers":
       out = formatRefs(store.findCallers(term, { limit: flags.limit }));
       break;
+    case "callees":
+      out = formatSymbols(store.findCallees(term, { limit: flags.limit }));
+      break;
+    case "impact":
+      out = formatImpact(store.impact(term, { depth: flags.depth, limit: flags.limit }));
+      break;
+    case "context":
+      out = formatContext(store.context(term, { maxSymbols: flags.limit }));
+      break;
     case "neighborhood":
       out = formatNeighborhood(store.neighborhood(term, { depth: flags.depth, limit: flags.limit }));
       break;
@@ -1307,6 +1482,9 @@ async function main() {
     case "search":
     case "get":
     case "callers":
+    case "callees":
+    case "impact":
+    case "context":
     case "neighborhood":
       return cmdQuery(command, resolve2(flags.path ?? flags.positional[1] ?? "."), flags);
     case "watch":