@levnikolaevich/hex-line-mcp 1.9.0 → 1.10.0

package/README.md

@@ -97,13 +97,15 @@ If a project already has `.hex-skills/codegraph/index.db`, `hex-line` can add li
 
 - Graph enrichment is optional. If `.hex-skills/codegraph/index.db` is missing, `hex-line` falls back to standard behavior silently.
 - `better-sqlite3` is optional. If it is unavailable, `hex-line` still works without graph hints.
-- `edit_file` reports **Call impact**, not full semantic blast radius. The warning uses call-graph callers only.
+- `edit_file` reports **Semantic impact** using explainable graph facts: external callers, downstream return/property flow, and clone peers when present.
 
 `hex-line` does not read `hex-graph` internals directly anymore. The integration uses a small read-only contract exposed by `hex-graph-mcp`:
 
-- `hex_line_contract`
-- `hex_line_symbol_annotations`
-- `hex_line_call_edges`
+- `hex_line_symbols`
+- `hex_line_line_facts`
+- `hex_line_edit_impacts`
+- `hex_line_edit_impact_facts`
+- `hex_line_clone_siblings`
 
 ## Tools Reference
 

package/dist/hook.mjs

@@ -54,7 +54,7 @@ function normalizeOutput(text, opts = {}) {
 }
 
 // hook.mjs
-import { readFileSync, statSync } from "node:fs";
+import { readFileSync, statSync, writeSync } from "node:fs";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -141,6 +141,7 @@ var TOOL_HINTS = {
   changes: "mcp__hex-line__changes (git diff with change symbols)",
   bulk: "mcp__hex-line__bulk_replace (multi-file search-replace)"
 };
+var DEFERRED_HINT = "If schemas not loaded: ToolSearch('+hex-line read edit')";
 var BASH_REDIRECTS = [
   { regex: /^cat\s+\S+/, key: "cat" },
   { regex: /^head\s+/, key: "head" },
@@ -282,16 +283,25 @@ function getHookMode() {
   }
   return _hookMode;
 }
+function safeExit(fd, data, code) {
+  writeSync(fd, data);
+  process.exit(code);
+}
+function debugLog(action, reason) {
+  writeSync(2, `[hex-hook] ${action}: ${reason}
+`);
+}
 function block(reason, context) {
+  const msg = context ? `${reason}
+${context}` : reason;
   const output = {
     hookSpecificOutput: {
       permissionDecision: "deny"
     },
-    systemMessage: context ? `${reason}
-${context}` : reason
+    systemMessage: msg
   };
-  process.stdout.write(JSON.stringify(output));
-  process.exit(2);
+  debugLog("BLOCK", reason);
+  safeExit(1, JSON.stringify(output), 2);
 }
 function advise(reason, context) {
   const output = {
@@ -301,8 +311,7 @@ function advise(reason, context) {
     systemMessage: context ? `${reason}
 ${context}` : reason
   };
-  process.stdout.write(JSON.stringify(output));
-  process.exit(0);
+  safeExit(1, JSON.stringify(output), 0);
 }
 function redirect(reason, context) {
   if (getHookMode() === "advisory") {
@@ -324,24 +333,20 @@ function handlePreToolUse(data) {
     if (BINARY_EXT.has(extOf(filePath))) {
       process.exit(0);
     }
-    const normalPath = filePath.replace(/\\/g, "/");
-    if (normalPath.includes(".claude/plans/") || normalPath.includes("AppData")) {
+    const resolvedNorm = resolveToolPath(filePath).replace(/\\/g, "/");
+    const cwdNorm = process.cwd().replace(/\\/g, "/");
+    const homeNorm = homedir().replace(/\\/g, "/");
+    const claudeAllow = [
+      cwdNorm + "/.claude/settings.json",
+      cwdNorm + "/.claude/settings.local.json",
+      homeNorm + "/.claude/settings.json",
+      homeNorm + "/.claude/settings.local.json"
+    ];
+    if (claudeAllow.some((p) => resolvedNorm.toLowerCase() === p.toLowerCase())) {
       process.exit(0);
     }
-    const ALLOWED_CONFIGS = /* @__PURE__ */ new Set(["settings.json", "settings.local.json"]);
-    const fileName = normalPath.split("/").pop();
-    if (ALLOWED_CONFIGS.has(fileName)) {
-      let candidate = filePath;
-      if (candidate.startsWith("~/")) {
-        candidate = homedir().replace(/\\/g, "/") + candidate.slice(1);
-      }
-      const absPath = resolve(process.cwd(), candidate).replace(/\\/g, "/");
-      const projectClaude = resolve(process.cwd(), ".claude").replace(/\\/g, "/") + "/";
-      const globalClaude = resolve(homedir(), ".claude").replace(/\\/g, "/") + "/";
-      const cmp = process.platform === "win32" ? (a, b) => a.toLowerCase().startsWith(b.toLowerCase()) : (a, b) => a.startsWith(b);
-      if (cmp(absPath, projectClaude) || cmp(absPath, globalClaude)) {
-        process.exit(0);
-      }
+    if (resolvedNorm.includes("/.claude/")) {
+      redirect("Protected .claude/ path. Use built-in tools for .claude/ config files.");
     }
     if (toolName === "Read") {
       if (isPartialRead(toolInput)) {
@@ -349,29 +354,30 @@ function handlePreToolUse(data) {
       }
       if (fileSize !== null && fileSize <= LARGE_FILE_BYTES) {
         const ext2 = filePath ? extOf(filePath) : "";
-        const hint = filePath && OUTLINEABLE_EXT.has(ext2) ? `mcp__hex-line__outline(path="${filePath}") gives a compact structural map. For edits, use mcp__hex-line__read_file(path="${filePath}") with ranges.` : filePath ? `NEXT READ: use mcp__hex-line__read_file(path="${filePath}"). Built-in Read allowed this time but wastes edit context.` : "NEXT READ: use mcp__hex-line__read_file. Built-in Read allowed this time but wastes edit context.";
-        advise(hint);
+        const hint = filePath && OUTLINEABLE_EXT.has(ext2) ? `Use mcp__hex-line__outline(path="${filePath}") for structure, then mcp__hex-line__read_file(path="${filePath}") with ranges.` : filePath ? `Use mcp__hex-line__read_file(path="${filePath}"). Built-in Read wastes edit context.` : "Use mcp__hex-line__read_file. Built-in Read wastes edit context.";
+        advise(hint, DEFERRED_HINT);
       }
       const ext = filePath ? extOf(filePath) : "";
       const outlineHint = filePath && OUTLINEABLE_EXT.has(ext) ? `Use mcp__hex-line__outline(path="${filePath}") for structure, then mcp__hex-line__read_file(path="${filePath}") with ranges to read only what you need.` : filePath ? `Use mcp__hex-line__read_file(path="${filePath}") with ranges or offset/limit` : "Use mcp__hex-line__directory_tree or mcp__hex-line__read_file";
-      redirect(outlineHint, "Do not use built-in Read for full reads of large files.");
+      redirect(outlineHint, "Do not use built-in Read for full reads of large files.\n" + DEFERRED_HINT);
     }
     if (toolName === "Edit") {
       const oldText = String(toolInput.old_string || "");
       const isLargeEdit = Boolean(toolInput.replace_all) || oldText.length > LARGE_EDIT_CHARS || fileSize !== null && fileSize > LARGE_FILE_BYTES;
       if (!isLargeEdit) {
-        process.exit(0);
+        const editHint = filePath ? `Prefer mcp__hex-line__edit_file(path="${filePath}") for hash-verified edits.` : "Prefer mcp__hex-line__edit_file for hash-verified edits.";
+        advise(editHint);
       }
       const target = filePath ? `Use mcp__hex-line__grep_search or mcp__hex-line__read_file, then mcp__hex-line__edit_file with path="${filePath}"` : "Use mcp__hex-line__grep_search or mcp__hex-line__read_file, then mcp__hex-line__edit_file";
-      redirect(target, "For large or repeated edits: locate anchors/checksums first, then call edit_file once with batched edits.");
+      redirect(target, "For large or repeated edits: locate anchors/checksums first, then call edit_file once with batched edits.\n" + DEFERRED_HINT);
     }
     if (toolName === "Write") {
       const pathNote = filePath ? ` with path="${filePath}"` : "";
-      redirect(`Use mcp__hex-line__write_file${pathNote}`, TOOL_HINTS.Write);
+      redirect(`Use mcp__hex-line__write_file${pathNote}`, TOOL_HINTS.Write + "\n" + DEFERRED_HINT);
     }
     if (toolName === "Grep") {
       const pathNote = filePath ? ` with path="${filePath}"` : "";
-      redirect(`Use mcp__hex-line__grep_search${pathNote}`, TOOL_HINTS.Grep);
+      redirect(`Use mcp__hex-line__grep_search${pathNote}`, TOOL_HINTS.Grep + "\n" + DEFERRED_HINT);
     }
   }
   if (toolName === "Bash") {
@@ -457,8 +463,7 @@ function handlePostToolUse(data) {
     `Original: ${originalCount} lines | Filtered: ${filteredCount} lines`,
     "=".repeat(50)
   ].join("\n");
-  process.stderr.write(output);
-  process.exit(2);
+  safeExit(2, output, 2);
 }
 function handleSessionStart() {
   const settingsFiles = [
@@ -479,9 +484,8 @@ function handleSessionStart() {
     }
   }
   const prefix = styleActive ? "Hex-line MCP available. Output style active.\n" : "Hex-line MCP available.\n";
-  const msg = prefix + "Call hex-line tools directly. Do not use ToolSearch for hex-line tools.\nWorkflow:\n- Discovery: outline for code and markdown files, read_file for targeted reads, grep_search for symbol/text lookup\n- Read cheaply: prefer offset/limit or ranges; avoid full-file Read on large files\n- Edit safely: read/grep first, then one batched edit_file call per file with base_revision when available\n- Verify before reread: use verify to check checksums or revision freshness\n- Multi-file rename/refactor: use bulk_replace\n- New files: use write_file\nExceptions: images, PDFs, notebooks, .claude/settings.json, .claude/settings.local.json use built-in Read. Glob is always OK.";
-  process.stdout.write(JSON.stringify({ systemMessage: msg }));
-  process.exit(0);
+  const msg = prefix + "<hex-line_instructions>\n  <deferred_loading>If hex-line schemas not loaded, run: ToolSearch('+hex-line read edit')</deferred_loading>\n  <exploration>\n    <rule>Use outline for structure (code + markdown), not Read. ~10-20 lines vs hundreds.</rule>\n    <rule>Use read_file with offset/limit or ranges for targeted reads.</rule>\n    <rule>Use grep_search before editing to get hash anchors.</rule>\n  </exploration>\n  <editing>\n    <path name='surgical'>grep_search \u2192 edit_file (fastest: hash-verified, no full read needed)</path>\n    <path name='exploratory'>outline \u2192 read_file (ranges) \u2192 edit_file with base_revision</path>\n    <path name='multi-file'>bulk_replace for text rename/refactor across files</path>\n  </editing>\n  <tips>\n    <tip>Carry revision from read_file into base_revision on edit_file.</tip>\n    <tip>If edit returns CONFLICT, call verify \u2014 only reread when STALE.</tip>\n    <tip>Batch multiple edits to same file in one edit_file call.</tip>\n    <tip>Use write_file for new files (no prior Read needed).</tip>\n  </tips>\n  <exceptions>Built-in Read OK for: images, PDFs, notebooks, Glob (always), .claude/settings.json</exceptions>\n</hex-line_instructions>";
+  safeExit(1, JSON.stringify({ systemMessage: msg }), 0);
 }
 var _norm = (p) => p.replace(/\\/g, "/");
 if (_norm(process.argv[1]) === _norm(fileURLToPath(import.meta.url))) {

package/dist/server.mjs

@@ -281,7 +281,23 @@ function validateWritePath(filePath) {
 import { existsSync as existsSync2 } from "node:fs";
 import { join as join3, dirname as dirname2, relative } from "node:path";
 import { createRequire } from "node:module";
-var HEX_LINE_CONTRACT_VERSION = 2;
+var REQUIRED_VIEWS = [
+  "hex_line_symbols",
+  "hex_line_line_facts",
+  "hex_line_edit_impacts",
+  "hex_line_edit_impact_facts",
+  "hex_line_clone_siblings"
+];
+var FACT_PRIORITY = /* @__PURE__ */ new Map([
+  ["definition", 0],
+  ["through_flow", 1],
+  ["outgoing_flow", 2],
+  ["incoming_flow", 3],
+  ["callee", 4],
+  ["caller", 5],
+  ["clone", 6],
+  ["hotspot", 7]
+]);
 var _dbs = /* @__PURE__ */ new Map();
 var _driverUnavailable = false;
 function getGraphDB(filePath) {
@@ -295,7 +311,7 @@ function getGraphDB(filePath) {
     const require2 = createRequire(import.meta.url);
     const Database = require2("better-sqlite3");
     const db = new Database(dbPath, { readonly: true });
-    if (!validateHexLineContract(db)) {
+    if (!validateContract(db)) {
       db.close();
       return null;
     }
@@ -306,25 +322,51 @@ function getGraphDB(filePath) {
     return null;
   }
 }
-function validateHexLineContract(db) {
+function validateContract(db) {
   try {
-    const contract = db.prepare("SELECT contract_version FROM hex_line_contract LIMIT 1").get();
-    if (!contract || contract.contract_version !== HEX_LINE_CONTRACT_VERSION) return false;
-    db.prepare("SELECT node_id, file, line_start, line_end, display_name, kind, callees, callers FROM hex_line_symbol_annotations LIMIT 1").all();
-    db.prepare("SELECT source_id, target_id, source_file, source_line, source_display_name, target_file, target_line, target_display_name, confidence FROM hex_line_call_edges LIMIT 1").all();
+    for (const viewName of REQUIRED_VIEWS) {
+      const row = db.prepare(
+        "SELECT name FROM sqlite_master WHERE type = 'view' AND name = ? LIMIT 1"
+      ).get(viewName);
+      if (!row) return false;
+    }
+    db.prepare("SELECT node_id, file, line_start, line_end, display_name, kind FROM hex_line_symbols LIMIT 1").all();
+    db.prepare("SELECT fact_kind, related_display_name, confidence, origin FROM hex_line_line_facts LIMIT 1").all();
+    db.prepare("SELECT symbol_node_id, external_callers_count, downstream_return_flow_count, downstream_property_flow_count, sink_reach_count FROM hex_line_edit_impacts LIMIT 1").all();
+    db.prepare("SELECT edited_symbol_id, fact_kind, target_display_name, path_kind, flow_hops FROM hex_line_edit_impact_facts LIMIT 1").all();
     return true;
   } catch {
     return false;
   }
 }
+function shortKind(kind) {
+  return { function: "fn", class: "cls", method: "mtd", variable: "var" }[kind] || kind;
+}
+function compactSymbolCounts(node) {
+  const parts = [];
+  if ((node.callees_exact || 0) > 0 || (node.callers_exact || 0) > 0) {
+    parts.push(`${node.callees_exact}\u2193 ${node.callers_exact}\u2191`);
+  }
+  const flowParts = [];
+  if ((node.incoming_flow_count || 0) > 0) flowParts.push(`${node.incoming_flow_count}in`);
+  if ((node.outgoing_flow_count || 0) > 0) flowParts.push(`${node.outgoing_flow_count}out`);
+  if ((node.through_flow_count || 0) > 0) flowParts.push(`${node.through_flow_count}thru`);
+  if (flowParts.length > 0) parts.push(`flow ${flowParts.join(" ")}`);
+  if ((node.clone_sibling_count || 0) > 0) parts.push(`clone ${node.clone_sibling_count}`);
+  return parts;
+}
 function symbolAnnotation(db, file, name) {
   try {
     const node = db.prepare(
-      "SELECT callees, callers FROM hex_line_symbol_annotations WHERE file = ? AND name = ? LIMIT 1"
+      `SELECT display_name, kind, callers_exact, callees_exact, incoming_flow_count, outgoing_flow_count, through_flow_count, clone_sibling_count
+             FROM hex_line_symbols
+             WHERE file = ? AND name = ?
+             LIMIT 1`
     ).get(file, name);
     if (!node) return null;
-    if (node.callees === 0 && node.callers === 0) return null;
-    return `[${node.callees}\u2193 ${node.callers}\u2191]`;
+    const parts = compactSymbolCounts(node);
+    const prefix = shortKind(node.kind);
+    return parts.length > 0 ? `[${prefix} ${parts.join(" | ")}]` : `[${prefix}]`;
   } catch {
     return null;
   }
@@ -332,58 +374,85 @@ function symbolAnnotation(db, file, name) {
 function fileAnnotations(db, file) {
   try {
     const nodes = db.prepare(
-      `SELECT display_name, kind, callees, callers
-             FROM hex_line_symbol_annotations
+      `SELECT display_name, kind, callers_exact, callees_exact, incoming_flow_count, outgoing_flow_count, through_flow_count, clone_sibling_count
+             FROM hex_line_symbols
              WHERE file = ?
              ORDER BY line_start`
     ).all(file);
     return nodes.map((node) => ({
       name: node.display_name,
       kind: node.kind,
-      callees: node.callees,
-      callers: node.callers
+      callers_exact: node.callers_exact,
+      callees_exact: node.callees_exact,
+      incoming_flow_count: node.incoming_flow_count,
+      outgoing_flow_count: node.outgoing_flow_count,
+      through_flow_count: node.through_flow_count,
+      clone_sibling_count: node.clone_sibling_count
     }));
   } catch {
     return [];
   }
 }
-function callImpact(db, file, startLine, endLine) {
+function formatLineFact(fact) {
+  const countParts = compactSymbolCounts(fact);
+  const suffix = countParts.length > 0 ? ` | ${countParts.join(" | ")}` : "";
+  switch (fact.fact_kind) {
+    case "definition":
+      return `[${shortKind(fact.kind)}${suffix}]`;
+    case "callee":
+      return fact.related_display_name ? `[callee:${fact.related_display_name}${suffix}]` : `[callee${suffix}]`;
+    case "caller":
+      return fact.related_display_name ? `[caller:${fact.related_display_name}${suffix}]` : `[caller${suffix}]`;
+    case "outgoing_flow":
+      return `[flow-out:${fact.target_anchor_kind || "?"}${suffix}]`;
+    case "incoming_flow":
+      return `[flow-in:${fact.target_anchor_kind || "?"}${suffix}]`;
+    case "through_flow":
+      return `[flow-through${suffix}]`;
+    case "clone":
+      return `[clone${suffix}]`;
+    case "hotspot":
+      return `[hotspot${suffix}]`;
+    default:
+      return `[${fact.fact_kind}${suffix}]`;
+  }
+}
+function priorityForFact(factKind) {
+  return FACT_PRIORITY.get(factKind) ?? 99;
+}
+function matchAnnotation(db, file, line) {
   try {
-    const modified = db.prepare(
-      `SELECT node_id
-             FROM hex_line_symbol_annotations
-             WHERE file = ?
-               AND line_start <= ?
-               AND line_end >= ?`
-    ).all(file, endLine, startLine);
-    if (modified.length === 0) return [];
-    const affected = [];
-    const seen = /* @__PURE__ */ new Set();
-    for (const node of modified) {
-      const dependents = db.prepare(
-        `SELECT source_display_name AS name, source_file AS file, source_line AS line
-                 FROM hex_line_call_edges
-                 WHERE target_id = ?
-                   AND confidence IN ('exact', 'precise')`
-      ).all(node.node_id);
-      for (const dep of dependents) {
-        const key = `${dep.file}:${dep.name}`;
-        if (!seen.has(key) && dep.file !== file) {
-          seen.add(key);
-          affected.push({ name: dep.name, file: dep.file, line: dep.line });
-        }
-      }
-    }
-    return affected.slice(0, 10);
+    const facts = db.prepare(
+      `SELECT
+                lf.display_name,
+                lf.kind,
+                lf.fact_kind,
+                lf.related_display_name,
+                lf.source_anchor_kind,
+                lf.target_anchor_kind,
+                hs.callers_exact,
+                hs.callees_exact,
+                hs.incoming_flow_count,
+                hs.outgoing_flow_count,
+                hs.through_flow_count,
+                hs.clone_sibling_count
+             FROM hex_line_line_facts lf
+             LEFT JOIN hex_line_symbols hs ON hs.node_id = lf.symbol_node_id
+             WHERE lf.file = ? AND lf.line_start <= ? AND lf.line_end >= ?
+             ORDER BY lf.line_start DESC`
+    ).all(file, line, line);
+    if (facts.length === 0) return null;
+    facts.sort((left, right) => priorityForFact(left.fact_kind) - priorityForFact(right.fact_kind));
+    return formatLineFact(facts[0]);
   } catch {
-    return [];
+    return null;
   }
 }
 function cloneWarning(db, file, startLine, endLine) {
   try {
     const modified = db.prepare(
       `SELECT node_id
-             FROM hex_line_symbol_annotations
+             FROM hex_line_symbols
              WHERE file = ?
                AND line_start <= ?
                AND line_end >= ?`
@@ -393,17 +462,20 @@ function cloneWarning(db, file, startLine, endLine) {
     const seen = /* @__PURE__ */ new Set();
     for (const node of modified) {
       const siblings = db.prepare(
-        `SELECT s2.file, s2.line_start, s2.display_name
-                 FROM hex_line_clone_siblings s1
-                 JOIN hex_line_clone_siblings s2 ON s2.norm_hash = s1.norm_hash AND s2.node_id != s1.node_id
-                 WHERE s1.node_id = ?`
+        `SELECT clone_peer_name, clone_peer_file, clone_peer_line, clone_type
+                 FROM hex_line_clone_siblings
+                 WHERE node_id = ?`
       ).all(node.node_id);
-      for (const sib of siblings) {
-        const key = `${sib.file}:${sib.display_name}`;
-        if (!seen.has(key)) {
-          seen.add(key);
-          clones.push({ name: sib.display_name, file: sib.file, line: sib.line_start });
-        }
+      for (const sibling of siblings) {
+        const key = `${sibling.clone_peer_file}:${sibling.clone_peer_name}:${sibling.clone_peer_line}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        clones.push({
+          name: sibling.clone_peer_name,
+          file: sibling.clone_peer_file,
+          line: sibling.clone_peer_line,
+          cloneType: sibling.clone_type
+        });
       }
     }
     return clones.slice(0, 10);
@@ -411,21 +483,64 @@ function cloneWarning(db, file, startLine, endLine) {
     return [];
   }
 }
-function matchAnnotation(db, file, line) {
+function semanticImpact(db, file, startLine, endLine) {
   try {
-    const node = db.prepare(
-      `SELECT display_name, kind, callees, callers
-             FROM hex_line_symbol_annotations
-             WHERE file = ? AND line_start <= ? AND line_end >= ?
-             ORDER BY line_start DESC
-             LIMIT 1`
-    ).get(file, line, line);
-    if (!node) return null;
-    const kindShort = { function: "fn", class: "cls", method: "mtd", variable: "var" }[node.kind] || node.kind;
-    if (node.callees === 0 && node.callers === 0) return `[${kindShort}]`;
-    return `[${kindShort} ${node.callees}\u2193 ${node.callers}\u2191]`;
+    const modified = db.prepare(
+      `SELECT symbol_node_id, display_name, external_callers_count, downstream_return_flow_count, downstream_property_flow_count, sink_reach_count, clone_sibling_count
+             FROM hex_line_edit_impacts
+             WHERE file = ?
+               AND line_start <= ?
+               AND line_end >= ?`
+    ).all(file, endLine, startLine);
+    if (modified.length === 0) return [];
+    return modified.map((item) => {
+      const facts = db.prepare(
+        `SELECT fact_kind, target_display_name, target_file, target_line, intermediate_display_name, path_kind, flow_hops, source_anchor_kind, target_anchor_kind, access_path_json
+                 FROM hex_line_edit_impact_facts
+                 WHERE edited_symbol_id = ?
+                 ORDER BY
+                    CASE fact_kind
+                        WHEN 'external_caller' THEN 0
+                        WHEN 'return_flow_to_symbol' THEN 1
+                        WHEN 'property_flow_to_symbol' THEN 2
+                        WHEN 'flow_reaches_terminal_anchor' THEN 3
+                        WHEN 'clone_sibling' THEN 4
+                        ELSE 9
+                    END,
+                    target_file,
+                    target_line`
+      ).all(item.symbol_node_id);
+      const seen = /* @__PURE__ */ new Set();
+      const dedupedFacts = facts.filter((fact) => {
+        const key = [
+          fact.fact_kind,
+          fact.target_display_name || "",
+          fact.target_file || "",
+          fact.target_line || "",
+          fact.path_kind || "",
+          fact.flow_hops || "",
+          fact.source_anchor_kind || "",
+          fact.target_anchor_kind || "",
+          fact.access_path_json || ""
+        ].join("|");
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      });
+      return {
+        symbol: item.display_name,
+        counts: {
+          externalCallers: item.external_callers_count,
+          downstreamReturnFlow: item.downstream_return_flow_count,
+          downstreamPropertyFlow: item.downstream_property_flow_count,
+          sinkReach: item.sink_reach_count,
+          cloneSiblings: item.clone_sibling_count
+        },
+        facts: dedupedFacts
+      };
+    });
   } catch {
-    return null;
+    return [];
   }
 }
 function getRelativePath(filePath) {
@@ -977,8 +1092,17 @@ ${text}
     const annos = fileAnnotations(db, relFile);
     if (annos.length > 0) {
       const items = annos.map((a) => {
-        const counts = a.callees || a.callers ? ` ${a.callees}\u2193 ${a.callers}\u2191` : "";
-        return `${a.name} [${a.kind}${counts}]`;
+        const parts = [];
+        if ((a.callees_exact || 0) > 0 || (a.callers_exact || 0) > 0) {
+          parts.push(`${a.callees_exact}\u2193 ${a.callers_exact}\u2191`);
+        }
+        const flow = [];
+        if ((a.incoming_flow_count || 0) > 0) flow.push(`${a.incoming_flow_count}in`);
+        if ((a.outgoing_flow_count || 0) > 0) flow.push(`${a.outgoing_flow_count}out`);
+        if ((a.through_flow_count || 0) > 0) flow.push(`${a.through_flow_count}thru`);
+        if (flow.length > 0) parts.push(`flow ${flow.join(" ")}`);
+        if ((a.clone_sibling_count || 0) > 0) parts.push(`clone ${a.clone_sibling_count}`);
+        return parts.length > 0 ? `${a.name} [${a.kind} ${parts.join(" | ")}]` : `${a.name} [${a.kind}]`;
       });
       graphLine = `
 Graph: ${items.join(" | ")}`;
@@ -1348,13 +1472,14 @@ function applyReplaceLinesEdit(edit, ctx) {
     const { start: csStart, end: csEnd, hex: csHex } = parseChecksum(rangeChecksum2);
     if (!coverage.ok) {
       const snip = buildErrorSnippet(origLines, actualStart - 1);
+      const retryChecksum = buildRangeChecksum(currentSnapshot, actualStart, actualEnd);
       throw new Error(
         `${coverage.reason}
 
 Current content (lines ${snip.start}-${snip.end}):
 ${snip.text}
 
-Tip: Use updated hashes above for retry.`
+` + (retryChecksum ? `Retry checksum: ${retryChecksum}` : "Tip: Use updated hashes above for retry.")
       );
     }
     const actual = buildRangeChecksum(currentSnapshot, csStart, csEnd);
@@ -1413,7 +1538,7 @@ function editFile(filePath, edits, opts = {}) {
   const currentSnapshot = readSnapshot(real);
   const baseSnapshot = opts.baseRevision ? getSnapshotByRevision(opts.baseRevision) : null;
   const hasBaseSnapshot = !!(baseSnapshot && baseSnapshot.path === real);
-  const staleRevision = !!opts.baseRevision && opts.baseRevision !== currentSnapshot.revision;
+  const staleRevision = !!opts.baseRevision && opts.baseRevision !== currentSnapshot.revision && hasBaseSnapshot;
   const changedRanges = staleRevision && hasBaseSnapshot ? computeChangedRanges(baseSnapshot.lines, currentSnapshot.lines) : [];
   const conflictPolicy = opts.conflictPolicy || "conservative";
   const original = currentSnapshot.content;
@@ -1594,13 +1719,30 @@ ${serializeReadBlock(block)}`;
     const db = getGraphDB(real);
     const relFile = db ? getRelativePath(real) : null;
     if (db && relFile && fullDiff && minLine <= maxLine) {
-      const affected = callImpact(db, relFile, minLine, maxLine);
-      if (affected.length > 0) {
-        const list = affected.map((a) => `${a.name} (${a.file}:${a.line})`).join(", ");
+      const impacts = semanticImpact(db, relFile, minLine, maxLine);
+      if (impacts.length > 0) {
+        const sections = impacts.map((impact) => {
+          const totals = [];
+          if (impact.counts.externalCallers > 0) totals.push(`${impact.counts.externalCallers} external callers`);
+          if (impact.counts.downstreamReturnFlow > 0) totals.push(`${impact.counts.downstreamReturnFlow} downstream return-flow`);
+          if (impact.counts.downstreamPropertyFlow > 0) totals.push(`${impact.counts.downstreamPropertyFlow} property-flow`);
+          if (impact.counts.sinkReach > 0) totals.push(`${impact.counts.sinkReach} terminal flow reach`);
+          if (impact.counts.cloneSiblings > 0) totals.push(`${impact.counts.cloneSiblings} clone siblings`);
+          const headline = totals.length > 0 ? totals.join(", ") : "no downstream graph facts";
+          const factLines = impact.facts.slice(0, 5).map((fact) => {
+            const target = fact.target_display_name ? `${fact.target_display_name} (${fact.target_file}:${fact.target_line})` : `${fact.target_file}:${fact.target_line}`;
+            const via = fact.path_kind ? ` via ${fact.path_kind}` : "";
+            return `${fact.fact_kind}: ${target}${via}`;
+          });
+          return [
+            `${impact.symbol}: ${headline}`,
+            ...factLines.map((line) => `  ${line}`)
+          ].join("\n");
+        });
         msg += `
 
-\u26A0 Call impact: ${affected.length} callers in other files
-  ${list}`;
+\u26A0 Semantic impact:
+${sections.join("\n")}`;
       }
       const clones = cloneWarning(db, relFile, minLine, maxLine);
       if (clones.length > 0) {
@@ -2846,7 +2988,7 @@ OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
 }
 
 // server.mjs
-var version = true ? "1.9.0" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.10.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
   version
@@ -2907,7 +3049,7 @@ ERROR: ${e.message}`);
 });
 server.registerTool("edit_file", {
   title: "Edit File",
-  description: "Apply verified partial edits to one file.",
+  description: "Apply hash-verified partial edits to one file. Batch multiple edits in one call. Carry base_revision from prior read/edit for auto-rebase on concurrent changes.",
   inputSchema: z2.object({
     path: z2.string().describe("File to edit"),
     edits: z2.union([z2.string(), z2.array(z2.any())]).describe(
@@ -3042,7 +3184,7 @@ server.registerTool("outline", {
 });
 server.registerTool("verify", {
   title: "Verify Checksums",
-  description: "Verify held checksums without rereading the file.",
+  description: "Check if held checksums are still valid without rereading. Use after edit_file returns CONFLICT to decide: VALID (retry), STALE (reread ranges), INVALID (reread file).",
   inputSchema: z2.object({
     path: z2.string().describe("File path"),
     checksums: z2.array(z2.string()).describe('Checksum strings, e.g. ["1-50:f7e2a1b0", "51-100:abcd1234"]'),
@@ -3062,7 +3204,7 @@ server.registerTool("verify", {
 });
 server.registerTool("directory_tree", {
   title: "Directory Tree",
-  description: "Directory tree with .gitignore support. Pattern glob to find files/dirs by name. Skips node_modules, .git, dist.",
+  description: "Gitignore-aware directory tree. Use pattern glob to find files/dirs by name instead of Bash find/ls. Skips node_modules, .git, dist.",
   inputSchema: z2.object({
     path: z2.string().describe("Directory path"),
     pattern: z2.string().optional().describe('Glob filter on names (e.g. "*-mcp", "*.mjs"). Returns flat match list instead of tree'),
@@ -3082,7 +3224,7 @@ server.registerTool("directory_tree", {
 });
 server.registerTool("get_file_info", {
   title: "File Info",
-  description: "File metadata without reading content: size, line count, modification time, type, binary detection. Use before reading large files to check size.",
+  description: "File metadata without reading content: size, line count, mtime, binary detection. Use before read_file on unknown files to decide offset/limit strategy.",
   inputSchema: z2.object({
     path: z2.string().describe("File path")
   }),
@@ -3097,7 +3239,7 @@ server.registerTool("get_file_info", {
 });
 server.registerTool("changes", {
   title: "Semantic Diff",
-  description: "Compare file or directory against git ref (default: HEAD). Shows added/removed/modified symbols or file stats.",
+  description: "Semantic diff against git ref (default: HEAD). Shows added/removed/modified symbols. Use to review changes before commit.",
   inputSchema: z2.object({
     path: z2.string().describe("File or directory path"),
     compare_against: z2.string().optional().describe('Git ref to compare against (default: "HEAD")')
@@ -3113,7 +3255,7 @@ server.registerTool("changes", {
 });
 server.registerTool("bulk_replace", {
   title: "Bulk Replace",
-  description: "Search-and-replace across multiple files with compact or full diff output.",
+  description: "Search-and-replace text across multiple files. Use for renames, refactors. Compact or full diff output.",
   inputSchema: z2.object({
     replacements: z2.union([z2.string(), replacementPairsSchema]).describe('JSON array of {old, new} pairs: [{"old":"foo","new":"bar"}]'),
     glob: z2.string().optional().describe('File glob (default: "**/*.{md,mjs,json,yml,ts,js}")'),

package/output-style.md

@@ -16,35 +16,30 @@ keep-coding-instructions: true
 | Grep | `mcp__hex-line__grep_search` | Edit-ready matches |
 | Edit (text rename) | `mcp__hex-line__bulk_replace` | Multi-file text rename/refactor |
 | Bash `find`/`tree` | `mcp__hex-line__directory_tree` | Pattern search, gitignore-aware |
+| Full code read | `mcp__hex-line__outline` then `read_file` with ranges | Structure first, read targeted |
 
-## Efficient File Reading
+**Bootstrap**: if hex-line calls fail, load schemas: `ToolSearch('+hex-line read edit')`
 
-For unfamiliar code files >100 lines, prefer:
-1. `outline` first
-2. `read_file` with `offset`/`limit` or `ranges`
-3. `paths` or `ranges` when batching several targets
+## Workflow Paths
 
-Avoid reading a large file in full. Prefer compact, targeted reads.
+| Path | When | Flow |
+|------|------|------|
+| Surgical | Know the target | `grep_search` → `edit_file` |
+| Exploratory | Need context first | `outline` → `read_file` (ranges) → `edit_file` |
+| Multi-file | Text rename/refactor | `bulk_replace` |
+| Verify | Check freshness | `verify` → reread only if STALE |
 
 Bash OK for: npm/node/git/docker/curl, pipes, compound commands.
 **Built-in OK for:** images, PDFs, notebooks, Glob (always), `.claude/settings.json`, `.claude/settings.local.json`.
 
 ## Edit Workflow
 
-Prefer:
-1. collect all known hunks for one file
-2. send one `edit_file` call with batched edits
-3. carry `revision` from `read_file` into `base_revision` on follow-up edits
-4. use `set_line`, `replace_lines`, `insert_after`, `replace_between` based on scope
-5. if edit returns CONFLICT, call `verify` with stale checksum — it reports VALID/STALE/INVALID without rereading the whole file
-6. only reread (`read_file`) when `verify` confirms STALE
-
-Post-edit output uses `block: post_edit` with checksum — use it directly for follow-up edits or verify.
-
-Avoid:
-- chained same-file `edit_file` calls when all edits are already known
-- full-file rewrites for local changes
-- using `bulk_replace` for structural block rewrites
+| Do | Don't |
+|----|-------|
+| Batch all hunks in one `edit_file` | Chain same-file `edit_file` calls |
+| Carry `revision` → `base_revision` | Full-file rewrite for local changes |
+| `verify` before reread | `bulk_replace` for block rewrites |
+| `post_edit` checksum for follow-up | — |
 
 
 ## hex-graph — Code Analysis

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "mcpName": "io.github.levnikolaevich/hex-line-mcp",
   "type": "module",
   "description": "Hash-verified file editing MCP + token efficiency hook for AI coding agents. 10 tools: read, edit, write, grep, outline, verify, directory_tree, file_info, changes, bulk_replace.",
@@ -73,6 +73,7 @@
   },
   "homepage": "https://github.com/levnikolaevich/claude-code-skills/tree/master/mcp/hex-line-mcp",
   "devDependencies": {
-    "eslint": "^10.1.0"
+    "eslint": "^10.1.0",
+    "typescript": "^6.0.2"
   }
 }