@jefuriiij/synthra 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ For older versions, see [GitHub Releases](https://github.com/jefuriiij/synthra/r
 
 ---
 
+## [0.12.0] — 2026-06-24
+
+### Added
+
+- **`find_symbol(name)` — reuse before you re-implement.** Before writing a new
+  helper, ask Synthra whether one already exists: `find_symbol` returns every
+  exact-name definition (with signatures + ready `graph_read` targets), or — if
+  there's no exact match — similarly-named symbols to reuse or extend. "No symbol
+  matching … — safe to create" is the green light that it's genuinely new. The
+  injected policy now nudges the agent to check first.
+- **`duplicate_symbols` — consolidation candidates.** Lists symbol names defined
+  in more than one file (functions/classes/types; methods excluded, since shared
+  method names are normal). Advisory — duplicates can be intentional; it never
+  says "delete."
+
+Both are built on the symbol index (exact name lookup) — no false-positive risk,
+no new dependencies.
+
+---
+
+## [0.11.0] — 2026-06-24
+
+### Added
+
+- **`graph_read` now shows which tests cover a symbol.** A symbol read appends a
+  `Tests (file-level): …` line listing the test files linked to the symbol's file
+  (via the graph's `tests` edges) — so after an edit you run the *right* test
+  instead of guessing or running the whole suite. Ordinary source files with no
+  linked test get a one-line "none linked" nudge.
+- **`blast_radius` is now symbol-aware.** A `file::symbol` target returns the
+  exact caller **symbols** that transitively call it (`name → file:line`), plus a
+  line naming the test files that guard the impact — the precise view you want
+  before a rename. A bare file target keeps the existing file-level dependent
+  list. (The `graph_read` "Used by (N)" footer remains the cheap always-on
+  direct-caller summary; this is the complete, transitive, on-demand one.)
+
+---
+
 ## [0.10.0] — 2026-06-20
 
 ### Added

package/dist/cli/index.js

@@ -18,7 +18,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@jefuriiij/synthra",
-      version: "0.10.0",
+      version: "0.12.0",
       publishConfig: {
         access: "public"
       },
@@ -3017,7 +3017,7 @@ import { basename as basename5 } from "path";
 // src/hooks/claude-md.ts
 import { readFile as readFile12, writeFile as writeFile6 } from "fs/promises";
 import { basename as basename4, dirname as dirname9 } from "path";
-var POLICY_VERSION = 7;
+var POLICY_VERSION = 8;
 var POLICY_BEGIN = `<!-- synthra-policy v${POLICY_VERSION} BEGIN -->`;
 var POLICY_END = `<!-- synthra-policy v${POLICY_VERSION} END -->`;
 var ANY_BLOCK_RE = /<!--\s*synthra-policy\s+v\d+\s+BEGIN\s*-->[\s\S]*?<!--\s*synthra-policy\s+v\d+\s+END\s*-->\s*/g;
@@ -3036,7 +3036,7 @@ function policyBlock() {
     "> `mcp__synthra__graph_register_edit`. **Short names will NOT resolve**",
     "> in ToolSearch or invocation \u2014 always use the full namespaced form.",
     "> If the tools are deferred, load their schemas with ToolSearch:",
-    "> `select:mcp__synthra__graph_continue,mcp__synthra__graph_read,mcp__synthra__graph_register_edit`.",
+    "> `select:mcp__synthra__graph_continue,mcp__synthra__graph_read,mcp__synthra__graph_register_edit,mcp__synthra__find_symbol`.",
     "> Below, short names (`graph_continue` etc.) appear in prose for",
     "> readability only.",
     "",
@@ -3050,6 +3050,10 @@ function policyBlock() {
     "  symbol is ~50 tokens, reading a whole file is thousands.",
     "- **`graph_register_edit(files)`** \u2014 after you edit files, call this so",
     "  subsequent turns weight your changes and avoid stale snapshots.",
+    "- **`find_symbol(name)`** \u2014 **reuse-first**: before writing a new helper,",
+    "  util, or function, call this to check whether one already exists. If it",
+    "  returns matches, reuse or extend them instead of re-implementing; only",
+    '  "no match \u2014 safe to create" means it is genuinely new.',
     "",
     "### When to call `graph_continue` \u2014 and when to skip",
     "",
@@ -4197,11 +4201,14 @@ var TOOLS = [
   },
   {
     name: "blast_radius",
-    description: "Given a file (or 'file::symbol' target), return all files that depend on it transitively via imports, tests, and call edges (callers). Use BEFORE editing a widely-used file to see what could break. Call edges are name-resolved (precise within a file, unique-name across files) and projected to file granularity.",
+    description: "See what could break before an edit. A bare file target returns all files that depend on it transitively via imports, tests, and call edges. A 'file::symbol' target returns the exact caller SYMBOLS that transitively call it (name \u2192 file:line) plus the test files guarding the impact \u2014 the precise rename-safety view. Call edges are name-resolved (precise within a file, unique-name across files).",
     inputSchema: {
       type: "object",
       properties: {
-        target: { type: "string", description: "File path or 'file::symbol' notation." },
+        target: {
+          type: "string",
+          description: "File path (file-level dependents) or 'file::symbol' (caller symbols)."
+        },
         depth: { type: "number", description: "Max hops to traverse. Default 3." }
       },
       required: ["target"]
@@ -4216,6 +4223,27 @@ var TOOLS = [
         limit: { type: "number", description: "Cap on returned files. Default 50." }
       }
     }
+  },
+  {
+    name: "find_symbol",
+    description: "Find existing symbols by name BEFORE writing a new one \u2014 reuse beats re-implementing. Returns exact-name definitions (signatures + graph_read targets) or, if none, similarly-named symbols. 'No symbol matching \u2026 \u2014 safe to create' means it's genuinely new.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Symbol name (or near-name) to look for." }
+      },
+      required: ["name"]
+    }
+  },
+  {
+    name: "duplicate_symbols",
+    description: "List symbol names defined in more than one file (functions/classes/types; methods excluded) \u2014 consolidation candidates for review. Advisory: duplicates may be intentional.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Cap on returned names. Default 30." }
+      }
+    }
   }
 ];
 async function callTool(name, args, ctx) {
@@ -4238,6 +4266,10 @@ async function callTool(name, args, ctx) {
       return blastRadius(args, ctx);
     case "dead_code":
       return deadCode(args, ctx);
+    case "find_symbol":
+      return findSymbol(args, ctx);
+    case "duplicate_symbols":
+      return duplicateSymbols(args, ctx);
     default:
       return errorContent(`Unknown tool: ${name}`);
   }
@@ -4252,7 +4284,8 @@ function blastRadius(args, ctx) {
   const targetRaw = typeof args?.target === "string" ? args.target.trim() : "";
   const maxDepth = typeof args?.depth === "number" && args.depth > 0 ? Math.floor(args.depth) : 3;
   if (!targetRaw) return errorContent("blast_radius: 'target' (string) is required");
-  const filePath = targetRaw.split("::", 1)[0]?.trim() ?? targetRaw;
+  if (targetRaw.includes("::")) return blastRadiusSymbol(targetRaw, maxDepth, ctx);
+  const filePath = targetRaw;
   const root = ctx.graph.nodes.find((n) => n.kind === "file" && n.path === filePath);
   if (!root) return errorContent(`blast_radius: file not in graph: ${filePath}`);
   const fileIdBySymbol = /* @__PURE__ */ new Map();
@@ -4307,6 +4340,92 @@ _(no dependents \u2014 file is isolated)_`);
   }
   return textContent(lines.join("\n"));
 }
+function blastRadiusSymbol(targetRaw, maxDepth, ctx) {
+  const [rawFile, rawSym] = targetRaw.split("::", 2);
+  const filePath = (rawFile ?? "").trim();
+  const symName = (rawSym ?? "").trim();
+  if (!symName) return errorContent("blast_radius: 'file::symbol' target needs a symbol name");
+  const resolved = resolveFileTarget(ctx.graph, filePath);
+  if ("ambiguous" in resolved) {
+    const shown = resolved.ambiguous.slice(0, 5).join(", ");
+    return errorContent(
+      `blast_radius: '${filePath}' matches multiple files (${shown}). Pass a longer path.`
+    );
+  }
+  if ("none" in resolved) return errorContent(`blast_radius: file not in graph: ${filePath}`);
+  const fileNode = resolved.node;
+  const symbol = ctx.graph.nodes.find(
+    (n) => n.kind === "symbol" && n.file === fileNode.path && n.name === symName
+  );
+  if (!symbol)
+    return errorContent(`blast_radius: symbol '${symName}' not found in ${fileNode.path}`);
+  const callersBySym = /* @__PURE__ */ new Map();
+  for (const e of ctx.graph.edges) {
+    if (e.kind !== "calls" || e.from === e.to) continue;
+    const list = callersBySym.get(e.to) ?? [];
+    list.push(e.from);
+    callersBySym.set(e.to, list);
+  }
+  const symById = /* @__PURE__ */ new Map();
+  for (const n of ctx.graph.nodes) if (n.kind === "symbol") symById.set(n.id, n);
+  const visited = /* @__PURE__ */ new Set([symbol.id]);
+  const hits = [];
+  let frontier = [symbol.id];
+  for (let d = 1; d <= maxDepth; d++) {
+    const next = [];
+    for (const cur of frontier) {
+      for (const fromId of callersBySym.get(cur) ?? []) {
+        if (visited.has(fromId)) continue;
+        visited.add(fromId);
+        next.push(fromId);
+        const s = symById.get(fromId);
+        if (s) hits.push({ name: s.name, file: s.file, line: s.start_line, depth: d });
+      }
+    }
+    frontier = next;
+    if (next.length === 0) break;
+  }
+  const header = `# Blast radius for ${fileNode.path}::${symbol.name}  (callers, depth \u2264 ${maxDepth})`;
+  if (hits.length === 0) {
+    const tline2 = testsCoveringLine(ctx.graph, [fileNode.path]);
+    return textContent(
+      `${header}
+
+_(no callers \u2014 safe to rename)_${tline2 ? `
+
+${tline2}` : ""}`
+    );
+  }
+  hits.sort((a, b) => a.depth - b.depth || a.file.localeCompare(b.file) || a.line - b.line);
+  const lines = [header, "", `${hits.length} caller symbol(s):`];
+  for (const h of hits) lines.push(`- **depth ${h.depth}** \`${h.name}\` \u2192 ${h.file}:${h.line}`);
+  const tline = testsCoveringLine(ctx.graph, [fileNode.path, ...hits.map((h) => h.file)]);
+  if (tline) {
+    lines.push("");
+    lines.push(tline);
+  }
+  return textContent(lines.join("\n"));
+}
+function testsCoveringLine(graph, filePaths) {
+  const fileByPath = /* @__PURE__ */ new Map();
+  for (const n of graph.nodes) if (n.kind === "file") fileByPath.set(n.path, n);
+  const seen = /* @__PURE__ */ new Set();
+  const tests = [];
+  for (const p of new Set(filePaths)) {
+    const fn = fileByPath.get(p);
+    if (!fn) continue;
+    for (const t of findTestsForFile(graph, fn)) {
+      if (!seen.has(t.path)) {
+        seen.add(t.path);
+        tests.push(t.path);
+      }
+    }
+  }
+  if (tests.length === 0) return "";
+  const shown = tests.slice(0, TESTS_MAX_FILES);
+  const omitted = tests.length - shown.length;
+  return `Tests covering the impact: ${shown.join(" \xB7 ")}${omitted > 0 ? ` \u2026+${omitted} more` : ""}`;
+}
 var LIKELY_ENTRY_PATTERNS = [
   /(?:^|\/)main\.[a-z0-9_]+$/i,
   /(?:^|\/)index\.[a-z0-9_]+$/i,
@@ -4354,6 +4473,107 @@ _(no file is unreferenced \u2014 every file is either imported by another, has a
   );
   return textContent(lines.join("\n"));
 }
+var FIND_MAX = 12;
+var FIND_SIG_MAX = 140;
+function symbolEntry(s) {
+  const sig = s.signature.trim().slice(0, FIND_SIG_MAX);
+  return `\u2022 ${sig}   \u2192 mcp__synthra__graph_read("${s.file}::${s.name}")  [${s.symbol_kind}, L${s.start_line}]`;
+}
+var byFileLine = (a, b) => a.file === b.file ? a.start_line - b.start_line : a.file < b.file ? -1 : 1;
+function findSymbol(args, ctx) {
+  const name = typeof args?.name === "string" ? args.name.trim() : "";
+  if (!name) return errorContent("find_symbol: 'name' (string) is required");
+  const symbols = ctx.graph.nodes.filter((n) => n.kind === "symbol");
+  const lower = name.toLowerCase();
+  const exact = symbols.filter((s) => s.name === name);
+  const exactHits = exact.length > 0 ? exact : symbols.filter((s) => s.name.toLowerCase() === lower);
+  if (exactHits.length > 0) {
+    const sorted = exactHits.slice().sort(byFileLine);
+    const shown2 = sorted.slice(0, FIND_MAX);
+    const omitted2 = sorted.length - shown2.length;
+    const lines2 = [
+      `# find_symbol: "${name}"`,
+      "",
+      `Exact matches (${sorted.length}) \u2014 reuse one of these instead of writing a new one:`,
+      ...shown2.map(symbolEntry)
+    ];
+    if (omitted2 > 0) lines2.push(`\u2026+${omitted2} more`);
+    return textContent(lines2.join("\n"));
+  }
+  const tokens = new Set(tokenizeQuery(name));
+  const scored = symbols.map((s) => {
+    const n = s.name.toLowerCase();
+    let score2 = 0;
+    if (n.includes(lower) || lower.includes(n)) score2 += 2;
+    for (const t of tokens) if (n.includes(t)) score2 += 1;
+    return { s, score: score2 };
+  }).filter((x) => x.score > 0).sort((a, b) => b.score - a.score || byFileLine(a.s, b.s));
+  if (scored.length === 0) {
+    return textContent(
+      `# find_symbol: "${name}"
+
+No symbol matching "${name}" \u2014 safe to create.`
+    );
+  }
+  const shown = scored.slice(0, FIND_MAX);
+  const omitted = scored.length - shown.length;
+  const lines = [
+    `# find_symbol: "${name}"`,
+    "",
+    `No exact match. Similar names (${scored.length}) \u2014 reuse or extend one before writing new:`,
+    ...shown.map((x) => symbolEntry(x.s))
+  ];
+  if (omitted > 0) lines.push(`\u2026+${omitted} more`);
+  return textContent(lines.join("\n"));
+}
+var DUP_INCLUDE = /* @__PURE__ */ new Set([
+  "function",
+  "class",
+  "interface",
+  "type",
+  "enum",
+  "const",
+  "component"
+]);
+function duplicateSymbols(args, ctx) {
+  const limit = typeof args?.limit === "number" && args.limit > 0 ? Math.floor(args.limit) : 30;
+  const defsByName = /* @__PURE__ */ new Map();
+  const filesByName = /* @__PURE__ */ new Map();
+  for (const n of ctx.graph.nodes) {
+    if (n.kind !== "symbol" || !DUP_INCLUDE.has(n.symbol_kind)) continue;
+    (defsByName.get(n.name) ?? defsByName.set(n.name, []).get(n.name)).push({
+      file: n.file,
+      line: n.start_line
+    });
+    (filesByName.get(n.name) ?? filesByName.set(n.name, /* @__PURE__ */ new Set()).get(n.name)).add(n.file);
+  }
+  const dups = [...defsByName.entries()].filter(([name]) => (filesByName.get(name)?.size ?? 0) >= 2).map(([name, defs]) => ({
+    name,
+    defs: defs.slice().sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1)
+  })).sort((a, b) => b.defs.length - a.defs.length || a.name.localeCompare(b.name));
+  if (dups.length === 0) {
+    return textContent(
+      "# Duplicate symbols\n\n_(no top-level symbol name is defined in more than one file)_"
+    );
+  }
+  const shown = dups.slice(0, limit);
+  const lines = [
+    "# Duplicate symbols  (consolidation candidates)",
+    "",
+    `${shown.length} of ${dups.length} name(s) defined in multiple files (functions/classes/types; methods excluded):`,
+    ""
+  ];
+  for (const d of shown) {
+    lines.push(
+      `- \`${d.name}\` (${d.defs.length}): ${d.defs.map((x) => `${x.file}:${x.line}`).join(" \xB7 ")}`
+    );
+  }
+  lines.push("");
+  lines.push(
+    "_advisory: the same name in multiple files may be intentional \u2014 verify before consolidating._"
+  );
+  return textContent(lines.join("\n"));
+}
 async function graphContinue(args, ctx) {
   const query = typeof args?.query === "string" ? args.query : "";
   if (!query) return errorContent("graph_continue: 'query' (string) is required");
@@ -4384,6 +4604,7 @@ function resolveFileTarget(graph, filePath) {
 var DEPS_SIG_MAX = 140;
 var DEPS_MAX_CALLEES = 10;
 var DEPS_MAX_CALLERS = 12;
+var TESTS_MAX_FILES = 6;
 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);
@@ -4447,6 +4668,21 @@ function buildDepsFooter(symbol, graph, maxChars = loadConfig().readDepsMaxChars
   }
   return lines.join("\n");
 }
+function buildTestsFooter(symbol, graph) {
+  const fileNode = graph.nodes.find(
+    (n) => n.kind === "file" && n.path === symbol.file
+  );
+  if (!fileNode) return "";
+  const tests = findTestsForFile(graph, fileNode);
+  if (tests.length > 0) {
+    const shown = tests.slice(0, TESTS_MAX_FILES).map((t) => t.path);
+    const omitted = tests.length - shown.length;
+    const more = omitted > 0 ? ` \u2026+${omitted} more` : "";
+    return `Tests (file-level): ${shown.join(" \xB7 ")}${more}  \u2014 run after editing`;
+  }
+  if (isLikelyEntry(symbol.file)) return "";
+  return "Tests: none linked to this file.";
+}
 async function graphRead(args, ctx) {
   const target = typeof args?.target === "string" ? args.target : "";
   if (!target) return errorContent("graph_read: 'target' (string) is required");
@@ -4490,10 +4726,15 @@ ${fileNode.content}`);
 
 ---
 ${deps}` : "";
+  const tests = buildTestsFooter(symbol, ctx.graph);
+  const testsBlock = tests ? `
+
+---
+${tests}` : "";
   return textContent(
     `# ${fileNode.path}::${symbol.name}  (L${symbol.start_line}-${symbol.end_line})
 
-${body}${depsBlock}${editHint}`
+${body}${depsBlock}${testsBlock}${editHint}`
   );
 }
 var editedFiles = /* @__PURE__ */ new Set();