@jefuriiij/synthra 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ For older versions, see [GitHub Releases](https://github.com/jefuriiij/synthra/r
 
 ---
 
+## [0.6.0] — 2026-06-13
+
+### Added
+
+- **`graph_read` now delivers a symbol's dependency surface.** Reading a symbol
+  appends a footer built from the call graph: **Depends on** — the symbols it
+  calls, each with its full one-line signature and a `graph_read` target, so you
+  can edit against real signatures instead of guessing parameter shapes or
+  re-reading the callee files; and **Used by** — the names of the symbols that
+  call it, so a change's blast radius is visible at a glance. Budgeted via
+  `SYN_READ_DEPS_CHARS` (default 900); leaf symbols with no calls add nothing.
+
+---
+
 ## [0.5.0] — 2026-06-13
 
 ### Added

package/dist/cli/index.js

@@ -18,7 +18,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@jefuriiij/synthra",
-      version: "0.5.0",
+      version: "0.6.0",
       publishConfig: {
         access: "public"
       },
@@ -4749,6 +4749,31 @@ async function pack(files, opts) {
   };
 }
 
+// src/shared/config.ts
+function num(name, fallback) {
+  const v = process.env[name];
+  if (!v) return fallback;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+function str(name, fallback) {
+  return process.env[name] ?? fallback;
+}
+function loadConfig() {
+  return {
+    hardMaxReadChars: num("SYN_HARD_MAX_READ_CHARS", 4e3),
+    gateHintMaxChars: num("SYN_GATE_HINT_CHARS", 1200),
+    readDepsMaxChars: num("SYN_READ_DEPS_CHARS", 900),
+    turnReadBudgetChars: num("SYN_TURN_READ_BUDGET_CHARS", 18e3),
+    fallbackMaxCallsPerTurn: num("SYN_FALLBACK_MAX_CALLS_PER_TURN", 1),
+    retrieveCacheTtlSec: num("SYN_RETRIEVE_CACHE_TTL_SEC", 900),
+    mcpPort: process.env.SYN_MCP_PORT ? num("SYN_MCP_PORT", 0) : null,
+    dashboardPort: num("SYN_DASHBOARD_PORT", 8901),
+    logLevel: str("SYN_LOG_LEVEL", "info"),
+    claudeBin: str("SYN_CLAUDE_BIN", "claude")
+  };
+}
+
 // src/server/mcp.ts
 var PROTOCOL_VERSION = "2024-11-05";
 var SERVER_INFO = { name: "synthra", version: "0.0.1" };
@@ -4788,7 +4813,7 @@ var TOOLS = [
   },
   {
     name: "graph_read",
-    description: "Return the source code for a specific file or symbol. Target is either a project-relative file path (e.g. 'src/auth.ts') or 'file::symbol' (e.g. 'src/auth.ts::AuthService').",
+    description: "Return the source code for a specific file or symbol. Target is either a project-relative file path (e.g. 'src/auth.ts') or 'file::symbol' (e.g. 'src/auth.ts::AuthService'). A symbol read also returns its dependency surface \u2014 the signatures of the symbols it calls (edit against these instead of guessing or re-reading their files) and the names of the symbols that call it.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5065,6 +5090,72 @@ function resolveFileTarget(graph, filePath) {
   if (matches.length > 1) return { ambiguous: matches.map((n) => n.path) };
   return { none: true };
 }
+var DEPS_SIG_MAX = 140;
+var DEPS_MAX_CALLEES = 10;
+var DEPS_MAX_CALLERS = 12;
+function buildDepsFooter(symbol, graph, maxChars = loadConfig().readDepsMaxChars) {
+  const symById = /* @__PURE__ */ new Map();
+  for (const n of graph.nodes) if (n.kind === "symbol") symById.set(n.id, n);
+  const calleeIds = [];
+  const callerIds = [];
+  const seenCallee = /* @__PURE__ */ new Set();
+  const seenCaller = /* @__PURE__ */ new Set();
+  for (const e of graph.edges) {
+    if (e.kind !== "calls") continue;
+    if (e.from === symbol.id && e.to !== symbol.id && !seenCallee.has(e.to)) {
+      seenCallee.add(e.to);
+      calleeIds.push(e.to);
+    } else if (e.to === symbol.id && e.from !== symbol.id && !seenCaller.has(e.from)) {
+      seenCaller.add(e.from);
+      callerIds.push(e.from);
+    }
+  }
+  const resolve6 = (ids) => ids.map((id) => symById.get(id)).filter((n) => !!n);
+  const callees = resolve6(calleeIds).sort(
+    (a, b) => a.file === b.file ? a.start_line - b.start_line : a.file < b.file ? -1 : 1
+  );
+  const callers = resolve6(callerIds);
+  if (callees.length === 0 && callers.length === 0) return "";
+  const lines = [];
+  let used = 0;
+  if (callees.length > 0) {
+    const head = "Depends on (signatures \u2014 don't guess these):";
+    lines.push(head);
+    used += head.length + 1;
+    let shown = 0;
+    for (const c of callees.slice(0, DEPS_MAX_CALLEES)) {
+      const sig = c.signature.trim().slice(0, DEPS_SIG_MAX);
+      const entry = `\u2022 ${sig}   \u2192 mcp__synthra__graph_read("${c.file}::${c.name}")`;
+      if (used + entry.length + 1 > maxChars) break;
+      lines.push(entry);
+      used += entry.length + 1;
+      shown += 1;
+    }
+    const omitted = callees.length - shown;
+    if (omitted > 0) lines.push(`\u2026+${omitted} more`);
+  }
+  if (callers.length > 0) {
+    const sep3 = lines.length > 0 ? 1 : 0;
+    const head = `Used by (${callers.length}): `;
+    const shown = [];
+    let cUsed = used + sep3 + head.length;
+    for (const c of callers.slice(0, DEPS_MAX_CALLERS)) {
+      const part = `${c.name} \u2192 ${c.file}`;
+      const join12 = shown.length > 0 ? 3 : 0;
+      if (cUsed + join12 + part.length > maxChars) break;
+      shown.push(part);
+      cUsed += join12 + part.length;
+    }
+    if (lines.length > 0) lines.push("");
+    if (shown.length > 0) {
+      const omitted = callers.length - shown.length;
+      lines.push(head + shown.join(" \xB7 ") + (omitted > 0 ? ` \u2026+${omitted} more` : ""));
+    } else {
+      lines.push(`Used by (${callers.length} callers)`);
+    }
+  }
+  return lines.join("\n");
+}
 async function graphRead(args, ctx) {
   const target = typeof args?.target === "string" ? args.target : "";
   if (!target) return errorContent("graph_read: 'target' (string) is required");
@@ -5103,10 +5194,15 @@ ${fileNode.content}`);
 
 ---
 \u270E To edit this symbol: Read("${fileNode.path}", offset=${offset}, limit=${limit}) then Edit \u2014 that satisfies Claude Code's read-gate at ~${limit} lines; do NOT re-read the whole file.`;
+  const deps = buildDepsFooter(symbol, ctx.graph);
+  const depsBlock = deps ? `
+
+---
+${deps}` : "";
   return textContent(
     `# ${fileNode.path}::${symbol.name}  (L${symbol.start_line}-${symbol.end_line})
 
-${body}${editHint}`
+${body}${depsBlock}${editHint}`
   );
 }
 var editedFiles = /* @__PURE__ */ new Set();
@@ -5353,32 +5449,6 @@ async function handleContextUpdate(req, ctx) {
 // src/server/routes/gate.ts
 import { appendFile as appendFile4, mkdir as mkdir12 } from "fs/promises";
 import { dirname as dirname13 } from "path";
-
-// src/shared/config.ts
-function num(name, fallback) {
-  const v = process.env[name];
-  if (!v) return fallback;
-  const n = Number(v);
-  return Number.isFinite(n) ? n : fallback;
-}
-function str(name, fallback) {
-  return process.env[name] ?? fallback;
-}
-function loadConfig() {
-  return {
-    hardMaxReadChars: num("SYN_HARD_MAX_READ_CHARS", 4e3),
-    gateHintMaxChars: num("SYN_GATE_HINT_CHARS", 1200),
-    turnReadBudgetChars: num("SYN_TURN_READ_BUDGET_CHARS", 18e3),
-    fallbackMaxCallsPerTurn: num("SYN_FALLBACK_MAX_CALLS_PER_TURN", 1),
-    retrieveCacheTtlSec: num("SYN_RETRIEVE_CACHE_TTL_SEC", 900),
-    mcpPort: process.env.SYN_MCP_PORT ? num("SYN_MCP_PORT", 0) : null,
-    dashboardPort: num("SYN_DASHBOARD_PORT", 8901),
-    logLevel: str("SYN_LOG_LEVEL", "info"),
-    claudeBin: str("SYN_CLAUDE_BIN", "claude")
-  };
-}
-
-// src/server/routes/gate.ts
 var BLOCKABLE_TOOLS = /* @__PURE__ */ new Set(["Grep", "Glob"]);
 var RECENT_ACTIVITY_WINDOW_MS = 5 * 60 * 1e3;
 function extractQuery(toolName, input) {