@jefuriiij/synthra 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -7,6 +7,46 @@ For older versions, see [GitHub Releases](https://github.com/jefuriiij/synthra/r
 
 ---
 
+## [0.13.0] — 2026-06-24
+
+### Added
+
+- **The resume digest now lists the symbols that changed since your last session.**
+  The SessionStart "Since you were last here" primer showed *files* touched; it now
+  leads its supporting context with the actual **symbols/signatures** that changed —
+  e.g. `src/auth.ts::login (function) — function login(creds: Creds): Promise<...>`.
+  Computed from a git diff against the previous session's HEAD (committed **and**
+  uncommitted changes), overlapped with the current graph. Best-effort: silently
+  omitted in non-git projects.
+- **`call_path(from, to)` — trace control flow.** Returns the shortest chain of
+  calls from one symbol to another (`handler → service → repo`), so you can see how
+  one symbol reaches another. The forward complement to `blast_radius` (callers).
+  Each of `from`/`to` is a `file::symbol` target or a bare symbol name when unique.
+
+Both reuse the existing call graph + git — no graph schema change, no new dependencies.
+
+---
+
+## [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.13.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,40 @@ 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." }
+      }
+    }
+  },
+  {
+    name: "call_path",
+    description: "Trace how one symbol reaches another through the call graph \u2014 the shortest chain of calls from 'from' to 'to'. Use to understand control flow ('how does this handler end up hitting the DB layer?'). Each of 'from'/'to' is a 'file::symbol' target or a bare symbol name when unique.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Starting symbol ('file::symbol' or unique name)." },
+        to: { type: "string", description: "Target symbol ('file::symbol' or unique name)." },
+        depth: { type: "number", description: "Max call hops to search. Default 6." }
+      },
+      required: ["from", "to"]
+    }
   }
 ];
 async function callTool(name, args, ctx) {
@@ -4241,6 +4279,12 @@ 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);
+    case "call_path":
+      return callPath(args, ctx);
     default:
       return errorContent(`Unknown tool: ${name}`);
   }
@@ -4397,6 +4441,97 @@ function testsCoveringLine(graph, filePaths) {
   const omitted = tests.length - shown.length;
   return `Tests covering the impact: ${shown.join(" \xB7 ")}${omitted > 0 ? ` \u2026+${omitted} more` : ""}`;
 }
+function resolveSymbolArg(ctx, arg) {
+  const a = arg.trim();
+  if (a.includes("::")) {
+    const [rawFile, rawSym] = a.split("::", 2);
+    const resolved = resolveFileTarget(ctx.graph, (rawFile ?? "").trim());
+    if (!("node" in resolved)) return null;
+    const name = (rawSym ?? "").trim();
+    return ctx.graph.nodes.find(
+      (n) => n.kind === "symbol" && n.file === resolved.node.path && n.name === name
+    ) ?? null;
+  }
+  const matches = ctx.graph.nodes.filter(
+    (n) => n.kind === "symbol" && n.name === a
+  );
+  return matches.length === 1 ? matches[0] : null;
+}
+function callPath(args, ctx) {
+  const fromArg = typeof args?.from === "string" ? args.from : "";
+  const toArg = typeof args?.to === "string" ? args.to : "";
+  const maxDepth = typeof args?.depth === "number" && args.depth > 0 ? Math.floor(args.depth) : 6;
+  if (!fromArg.trim() || !toArg.trim()) {
+    return errorContent("call_path: 'from' and 'to' (strings) are required");
+  }
+  const from = resolveSymbolArg(ctx, fromArg);
+  if (!from) {
+    return errorContent(
+      `call_path: could not resolve 'from': ${fromArg} (use file::symbol if the name is ambiguous)`
+    );
+  }
+  const to = resolveSymbolArg(ctx, toArg);
+  if (!to) {
+    return errorContent(
+      `call_path: could not resolve 'to': ${toArg} (use file::symbol if the name is ambiguous)`
+    );
+  }
+  if (from.id === to.id) {
+    return textContent(`# call_path
+
+\`${from.name}\` and \`${to.name}\` are the same symbol.`);
+  }
+  const calleesBy = /* @__PURE__ */ new Map();
+  for (const e of ctx.graph.edges) {
+    if (e.kind !== "calls" || e.from === e.to) continue;
+    (calleesBy.get(e.from) ?? calleesBy.set(e.from, []).get(e.from)).push(e.to);
+  }
+  const symById = /* @__PURE__ */ new Map();
+  for (const n of ctx.graph.nodes) if (n.kind === "symbol") symById.set(n.id, n);
+  const prevOf = /* @__PURE__ */ new Map();
+  const visited = /* @__PURE__ */ new Set([from.id]);
+  let frontier = [from.id];
+  let found = false;
+  for (let d = 0; d < maxDepth && !found && frontier.length > 0; d++) {
+    const next = [];
+    for (const cur2 of frontier) {
+      for (const nb of calleesBy.get(cur2) ?? []) {
+        if (visited.has(nb)) continue;
+        visited.add(nb);
+        prevOf.set(nb, cur2);
+        if (nb === to.id) {
+          found = true;
+          break;
+        }
+        next.push(nb);
+      }
+      if (found) break;
+    }
+    frontier = next;
+  }
+  if (!found) {
+    return textContent(
+      `# call_path: ${from.name} \u2192 ${to.name}
+
+_(no call path found within depth ${maxDepth})_`
+    );
+  }
+  const chain = [];
+  let cur = to.id;
+  while (cur !== void 0) {
+    chain.unshift(cur);
+    if (cur === from.id) break;
+    cur = prevOf.get(cur);
+  }
+  const syms = chain.map((id) => symById.get(id)).filter((s) => !!s);
+  const hops = syms.length - 1;
+  const rendered = syms.map((s) => `\`${s.name}\` (${s.file}:${s.start_line})`).join("\n  \u2192 ");
+  return textContent(
+    `# call_path: ${from.name} \u2192 ${to.name}  (${hops} hop${hops === 1 ? "" : "s"})
+
+${rendered}`
+  );
+}
 var LIKELY_ENTRY_PATTERNS = [
   /(?:^|\/)main\.[a-z0-9_]+$/i,
   /(?:^|\/)index\.[a-z0-9_]+$/i,
@@ -4444,6 +4579,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");
@@ -4842,11 +5078,51 @@ async function getCommitsSince(projectRoot, sinceIso) {
     return [];
   }
 }
+async function getHeadSha(projectRoot) {
+  try {
+    const { stdout } = await execFileAsync3("git", ["rev-parse", "HEAD"], { cwd: projectRoot });
+    return stdout.trim();
+  } catch {
+    return "";
+  }
+}
+function parseDiffHunks(stdout) {
+  const out = /* @__PURE__ */ new Map();
+  let current = null;
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("+++ ")) {
+      const p = line.slice(4).trim();
+      current = p === "/dev/null" ? null : p.replace(/^b\//, "");
+    } else if (current && line.startsWith("@@")) {
+      const m = /\+(\d+)(?:,(\d+))?/.exec(line);
+      if (!m) continue;
+      const start = Number(m[1]);
+      const count = m[2] === void 0 ? 1 : Number(m[2]);
+      const end = count === 0 ? start : start + count - 1;
+      const list = out.get(current) ?? [];
+      list.push([start, end]);
+      out.set(current, list);
+    }
+  }
+  return out;
+}
+async function getChangedLineRanges(projectRoot, sinceRef) {
+  if (!sinceRef) return /* @__PURE__ */ new Map();
+  try {
+    const { stdout } = await execFileAsync3("git", ["diff", "-U0", "--no-color", sinceRef, "--"], {
+      cwd: projectRoot,
+      maxBuffer: 16 * 1024 * 1024
+    });
+    return parseDiffHunks(stdout);
+  } catch {
+    return /* @__PURE__ */ new Map();
+  }
+}
 
 // src/memory/session.ts
 import { mkdir as mkdir11, readFile as readFile17, writeFile as writeFile10 } from "fs/promises";
 import { dirname as dirname13 } from "path";
-var SESSION_SCHEMA_VERSION = 1;
+var SESSION_SCHEMA_VERSION = 2;
 async function readSession(path) {
   try {
     const raw = await readFile17(path, "utf8");
@@ -4875,6 +5151,7 @@ async function captureSnapshot(ctx, branchOverride) {
   for (const p of ctx.activity.recentFilePaths(TOUCHED_WINDOW_MS)) touched.add(p);
   const prev = await readSession(ctx.paths.sessionState);
   const recentCommits = await getCommitsSince(ctx.paths.projectRoot, prev?.endedAt ?? "");
+  const headSha = await getHeadSha(ctx.paths.projectRoot);
   const snapshot = {
     schema_version: SESSION_SCHEMA_VERSION,
     endedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -4885,7 +5162,8 @@ async function captureSnapshot(ctx, branchOverride) {
       tasks: tasks.entries.map((e) => e.content),
       decisions: decisions.entries.map((e) => e.content),
       next: next.entries.map((e) => e.content)
-    }
+    },
+    headSha
   };
   await writeSession(ctx.paths.sessionState, snapshot);
 }
@@ -5333,6 +5611,34 @@ var RESUME_PRIMER_MAX_CHARS = 2720;
 var MAX_FILES = 15;
 var MAX_COMMITS2 = 5;
 var MAX_BULLETS2 = 3;
+var MAX_CHANGED_SYMBOLS = 20;
+var CHANGED_SIG_MAX = 100;
+function changedSymbols(ranges, graph) {
+  if (ranges.size === 0) return [];
+  const hits = [];
+  for (const n of graph.nodes) {
+    if (n.kind !== "symbol") continue;
+    const rs = ranges.get(n.file);
+    if (!rs) continue;
+    if (rs.some(([a, b]) => a <= n.end_line && b >= n.start_line)) hits.push(n);
+  }
+  hits.sort((a, b) => a.file === b.file ? a.start_line - b.start_line : a.file < b.file ? -1 : 1);
+  return hits;
+}
+function changedSymbolsSection(ranges, graph) {
+  const hits = changedSymbols(ranges, graph);
+  if (hits.length === 0) return [];
+  const shown = hits.slice(0, MAX_CHANGED_SYMBOLS);
+  const lines = ["", "### Changed symbols (since last session)"];
+  for (const s of shown) {
+    lines.push(
+      `- \`${s.file}::${s.name}\` (${s.symbol_kind}) \u2014 ${s.signature.trim().slice(0, CHANGED_SIG_MAX)}`
+    );
+  }
+  const more = hits.length - shown.length;
+  if (more > 0) lines.push(`_(+${more} more)_`);
+  return lines;
+}
 function legacyPrimer(ctx) {
   const g = ctx.graph;
   return `Synthra context loaded for ${g.root}.
@@ -5343,7 +5649,7 @@ function hasContent(snap) {
     snap.recentCommits.length || snap.filesTouched.length || snap.summary.tasks.length || snap.summary.next.length || snap.summary.decisions.length
   );
 }
-function buildResumeDigest(snap, branchNow) {
+function buildResumeDigest(snap, branchNow, changedSymbolLines = []) {
   const plural = (n) => n === 1 ? "" : "s";
   const head = `## Since you were last here \u2014 ${snap.branch}  (${snap.recentCommits.length} commit${plural(snap.recentCommits.length)}, ${snap.filesTouched.length} file${plural(snap.filesTouched.length)} touched)`;
   const essential = [head];
@@ -5364,7 +5670,7 @@ function buildResumeDigest(snap, branchNow) {
     essential.push("", "### Recent decisions");
     for (const d of snap.summary.decisions.slice(0, MAX_BULLETS2)) essential.push(`- ${d}`);
   }
-  const extra = [];
+  const extra = [...changedSymbolLines];
   if (snap.recentCommits.length) {
     extra.push("", "### Recent commits");
     for (const c of snap.recentCommits.slice(0, MAX_COMMITS2)) {
@@ -5391,7 +5697,12 @@ async function handlePrime(ctx, port) {
     return { primer: legacy, port };
   }
   const branchNow = await currentBranch(ctx.paths.projectRoot);
-  const digest = buildResumeDigest(snap, branchNow);
+  let changedSymbolLines = [];
+  if (snap.headSha) {
+    const ranges = await getChangedLineRanges(ctx.paths.projectRoot, snap.headSha);
+    changedSymbolLines = changedSymbolsSection(ranges, ctx.graph);
+  }
+  const digest = buildResumeDigest(snap, branchNow, changedSymbolLines);
   return { primer: `${digest}
 
 ---