@jefuriiij/synthra 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ 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

package/dist/cli/index.js

@@ -18,7 +18,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@jefuriiij/synthra",
-      version: "0.11.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",
     "",
@@ -4219,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) {
@@ -4241,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}`);
   }
@@ -4444,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");