@levnikolaevich/hex-line-mcp 1.22.0 → 1.23.1

package/dist/server.mjs

@@ -400,6 +400,57 @@ function getGraphDB(filePath, { allowStale = false } = {}) {
     return null;
   }
 }
+function diagnoseGraph(filePath) {
+  if (_driverUnavailable) return { reason: "driver_missing" };
+  try {
+    const projectRoot = findProjectRoot(filePath);
+    if (!projectRoot) return { reason: "no_project_root" };
+    const dbPath = join3(projectRoot, ".hex-skills/codegraph", "index.db");
+    if (!existsSync2(dbPath)) return { reason: "index_missing", projectRoot };
+    if (_dbs.has(dbPath)) {
+      const cached = _dbs.get(dbPath);
+      if (!isFilePathFresh(cached, projectRoot, filePath)) {
+        return { reason: "stale", projectRoot };
+      }
+      return { reason: "ok", projectRoot };
+    }
+    const require2 = createRequire(import.meta.url);
+    const Database = require2("better-sqlite3");
+    const db = new Database(dbPath, { readonly: true });
+    if (!validateContract(db)) {
+      db.close();
+      return { reason: "contract_mismatch", projectRoot };
+    }
+    if (!isFilePathFresh(db, projectRoot, filePath)) {
+      db.close();
+      return { reason: "stale", projectRoot };
+    }
+    _dbs.set(dbPath, db);
+    return { reason: "ok", projectRoot };
+  } catch {
+    _driverUnavailable = true;
+    return { reason: "driver_missing" };
+  }
+}
+function graphUnavailableHint(filePath) {
+  const { reason, projectRoot } = diagnoseGraph(filePath);
+  if (reason === "ok") return [];
+  const at = projectRoot ? ` at ${projectRoot.replace(/\\/g, "/")}` : "";
+  switch (reason) {
+    case "driver_missing":
+      return ["graph_enrichment: unavailable", "graph_fix: install better-sqlite3 in hex-line-mcp package"];
+    case "no_project_root":
+      return ["graph_enrichment: unavailable", "graph_fix: file is outside any project root (no package.json / pyproject.toml / .git marker)"];
+    case "index_missing":
+      return ["graph_enrichment: unavailable", `graph_fix: run mcp__hex-graph__index_project${at}`];
+    case "contract_mismatch":
+      return ["graph_enrichment: unavailable", `graph_fix: index built by incompatible hex-graph version; re-run mcp__hex-graph__index_project${at}`];
+    case "stale":
+      return ["graph_enrichment: unavailable", `graph_fix: file modified after last index; re-run mcp__hex-graph__index_project${at} or wait for background refresh`];
+    default:
+      return ["graph_enrichment: unavailable"];
+  }
+}
 function validateContract(db) {
   try {
     for (const viewName of REQUIRED_VIEWS) {
@@ -497,6 +548,20 @@ function ensureGraphFreshForFile(db, absoluteFilePath) {
     return true;
   }
 }
+function isGraphFreshAtMtime(db, absoluteFilePath, mtimeMs) {
+  if (!db) return false;
+  try {
+    const projectRoot = findProjectRoot(absoluteFilePath);
+    if (!projectRoot) return true;
+    const relativeFile = normalizeRelativeFile(projectRoot, absoluteFilePath);
+    if (!relativeFile) return true;
+    const indexedMtime = lookupIndexedMtime(db, relativeFile);
+    if (indexedMtime == null) return false;
+    return mtimeMs <= indexedMtime + FRESHNESS_TOLERANCE_MS;
+  } catch {
+    return true;
+  }
+}
 function fileAnnotations(db, file, { startLine = null, endLine = null, limit = 8 } = {}) {
   try {
     const hasRange = Number.isInteger(startLine) && Number.isInteger(endLine);
@@ -1267,7 +1332,7 @@ function serializeSearchBlock(block, opts = {}) {
   }
   if (block.meta.summary) lines.push(`summary: ${block.meta.summary}`);
   lines.push(...renderMetaLines(Object.fromEntries(
-    Object.entries(block.meta).filter(([key]) => key !== "matchLines" && key !== "summary")
+    Object.entries(block.meta).filter(([key]) => key !== "matchLines" && key !== "summary" && key !== "graphScore")
   )));
   lines.push(...block.entries.map((entry) => serializeSearchEntry(entry, opts)));
   lines.push(`checksum: ${block.checksum}`);
@@ -2801,7 +2866,9 @@ changed_ranges: ${describeChangedRanges(changedRanges)}`;
 summary: lines_changed=${changedSpan} diff_entries=${diffEntryCount} lines_after=${lines.length}`;
     msg2 += `
 payload_sections: ${payloadSections(displayDiff ? ["diff"] : [])}`;
-    msg2 += "\ngraph_enrichment: unavailable";
+    const hint = graphUnavailableHint(real);
+    if (hint.length > 0) msg2 += `
+${hint.join("\n")}`;
     msg2 += `
 Dry run: ${filePath} would change (${lines.length} lines)`;
     if (displayDiff) msg2 += `
@@ -2830,9 +2897,10 @@ remapped_refs:
 ${remaps.map(({ from, to }) => `${from} -> ${to}`).join("\n")}`;
   }
   let hasPostEditBlock = false;
-  let graphEnrichment = "unavailable";
   let semanticImpacts = [];
   let cloneWarnings = [];
+  let graphDbAvailable = false;
+  let graphFresh = true;
   msg += `
 Updated ${filePath} (${lines.length} lines)`;
   if (fullDiff && minLine <= maxLine) {
@@ -2859,7 +2927,8 @@ ${serializeReadBlock(block)}`;
     const db = getGraphDB(real, { allowStale: true });
     const relFile = db ? getRelativePath(real) : null;
     if (db && relFile && fullDiff && minLine <= maxLine) {
-      graphEnrichment = "available";
+      graphDbAvailable = true;
+      graphFresh = isGraphFreshAtMtime(db, real, currentSnapshot.mtimeMs);
       semanticImpacts = semanticImpact(db, relFile, minLine, maxLine);
       if (semanticImpacts.length > 0) {
         const sections = semanticImpacts.map((impact) => {
@@ -2892,7 +2961,7 @@ ${sections.join("\n")}`;
       }
       cloneWarnings = cloneWarning(db, relFile, minLine, maxLine);
       if (cloneWarnings.length > 0) {
-        const list = cloneWarnings.map((c) => `${c.file}:${c.line}`).join(", ");
+        const list = cloneWarnings.map((c) => `${c.file}:${c.line}${c.cloneType ? ` (${c.cloneType})` : ""}`).join(", ");
         msg += `
 
 \u26A0 ${cloneWarnings.length} clone(s): ${list}`;
@@ -2900,20 +2969,17 @@ ${sections.join("\n")}`;
     }
   } catch {
   }
+  if (!graphFresh) msg += "\ngraph_fresh: stale";
   const payloadKinds = [];
   if (hasPostEditBlock) payloadKinds.push("post_edit");
   if (semanticImpacts.length > 0) payloadKinds.push("semantic_impact");
   if (cloneWarnings.length > 0) payloadKinds.push("clone_warning");
   if (displayDiff) payloadKinds.push("diff");
-  const semanticFactCount = semanticImpacts.reduce((sum, impact) => sum + (impact.facts?.length || 0), 0);
   const summaryLineParts = [
     `summary: lines_changed=${changedSpan} diff_entries=${diffEntryCount} lines_after=${lines.length}${editContext.corrections.length > 0 ? ` boundary_echo_stripped=${editContext.corrections.length}` : ``}`,
-    `payload_sections: ${payloadSections(payloadKinds)}`,
-    `graph_enrichment: ${graphEnrichment}`
+    `payload_sections: ${payloadSections(payloadKinds)}`
   ];
-  if (semanticImpacts.length > 0) summaryLineParts.push(`semantic_impact_count: ${semanticImpacts.length}`);
-  if (semanticFactCount > 0) summaryLineParts.push(`semantic_fact_count: ${semanticFactCount}`);
-  if (cloneWarnings.length > 0) summaryLineParts.push(`clone_warning_count: ${cloneWarnings.length}`);
+  if (!graphDbAvailable) summaryLineParts.push(...graphUnavailableHint(real));
   const summaryLines = summaryLineParts.join("\n");
   msg = msg.replace(`
 Updated ${filePath} (${lines.length} lines)`, `
@@ -4420,9 +4486,6 @@ async function semanticGitDiff(targetPath, { baseRef = "HEAD", headRef = null }
 }
 
 // lib/changes.mjs
-function graphEnrichmentState(db) {
-  return db ? "available" : "unavailable";
-}
 function payloadSections2(sections) {
   return sections.length > 0 ? sections.join(",") : "summary_only";
 }
@@ -4467,7 +4530,7 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
   if (statSync11(real).isDirectory()) {
     const db2 = getGraphDB(join6(real, "__hex-line_probe__"));
     const diff2 = await semanticGitDiff(real, { baseRef: compareAgainst });
-    const graphEnrichment2 = graphEnrichmentState(db2);
+    const graphHint2 = graphUnavailableHint(join6(real, "__hex-line_probe__"));
     if (diff2.summary.changed_file_count === 0) {
       return [
         "status: NO_CHANGES",
@@ -4476,7 +4539,7 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
         `compare_against: ${compareAgainst}`,
         "scope: directory",
         "summary: changed_files=0",
-        `graph_enrichment: ${graphEnrichment2}`
+        ...graphHint2
       ].join("\n");
     }
     let emittedRiskCount = 0;
@@ -4490,7 +4553,7 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
       "scope: directory",
       `summary: changed_files=${diff2.summary.changed_file_count}`,
       `next_action: ${ACTION.INSPECT_FILE}`,
-      `graph_enrichment: ${graphEnrichment2}`,
+      ...graphHint2,
       ""
     ];
     for (const file2 of diff2.changed_files) {
@@ -4513,16 +4576,14 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
     if (emittedRiskCount > 0) sectionKinds2.push("risk_summary");
     if (emittedRemovedApiWarnings > 0) sectionKinds2.push("removed_api_warning");
     const spliceLines = [];
-    if (emittedRiskCount > 0) spliceLines.push(`risk_summary_count: ${emittedRiskCount}`);
-    if (emittedRemovedApiWarnings > 0) spliceLines.push(`removed_api_warning_count: ${emittedRemovedApiWarnings}`);
     if (sectionKinds2.length > 0) spliceLines.push(`payload_sections: ${payloadSections2(sectionKinds2)}`);
-    sections.splice(8, 0, ...spliceLines);
+    sections.splice(7 + graphHint2.length, 0, ...spliceLines);
     return sections.join("\n");
   }
   const db = getGraphDB(real);
   const diff = await semanticGitDiff(real, { baseRef: compareAgainst });
   const file = diff.changed_files[0];
-  const graphEnrichment = graphEnrichmentState(db);
+  const graphHint = graphUnavailableHint(real);
   if (!file) {
     return [
       "status: NO_CHANGES",
@@ -4531,7 +4592,7 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
       `compare_against: ${compareAgainst}`,
       "scope: file",
       "summary: added=0 removed=0 modified=0",
-      `graph_enrichment: ${graphEnrichment}`
+      ...graphHint
     ].join("\n");
   }
   if (!file.semantic_supported) {
@@ -4543,7 +4604,7 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
       "scope: file",
       `summary: semantic diff unavailable for ${file.extension} files`,
       `next_action: ${ACTION.INSPECT_RAW_DIFF}`,
-      `graph_enrichment: ${graphEnrichment}`
+      ...graphHint
     ].join("\n");
   }
   const relFile = getRelativePath(real) || file.path?.replace(/\\/g, "/");
@@ -4557,10 +4618,8 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
     `compare_against: ${compareAgainst}`,
     "scope: file",
     `summary: ${symbolCountSummary(file)}`,
-    `graph_enrichment: ${graphEnrichment}`
+    ...graphHint
   ];
-  if (riskLines.length > 0) parts.push(`risk_summary_count: ${riskLines.length}`);
-  if (removedApiWarnings.length > 0) parts.push(`removed_api_warning_count: ${removedApiWarnings.length}`);
   if (file.added_symbols.length) {
     sectionKinds.push("added");
     parts.push(`next_action: ${ACTION.REVIEW_RISKS}`);
@@ -4594,7 +4653,7 @@ async function fileChanges(filePath, compareAgainst = "HEAD") {
   if (riskLines.length > 0) sectionKinds.push("risk_summary");
   if (removedApiWarnings.length > 0) sectionKinds.push("removed_api_warning");
   if (sectionKinds.length > 0) {
-    const insertIdx = 7 + (riskLines.length > 0 ? 1 : 0) + (removedApiWarnings.length > 0 ? 1 : 0);
+    const insertIdx = 6 + graphHint.length;
     parts.splice(insertIdx, 0, `payload_sections: ${payloadSections2(sectionKinds)}`);
   }
   if (riskLines.length || removedApiWarnings.length) {
@@ -4749,7 +4808,7 @@ function errorResult(code, message, recovery, { large = false, extra = null } =
 }
 
 // server.mjs
-var version = true ? "1.22.0" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.23.1" : (await null).createRequire(import.meta.url)("./package.json").version;
 var STATUS_ENUM = z2.enum(["OK", "ERROR", "AUTO_REBASED", "CONFLICT", "STALE", "INVALID", "NO_CHANGES", "CHANGED", "UNSUPPORTED"]);
 var ERROR_SHAPE = z2.object({ code: z2.string(), message: z2.string(), recovery: z2.string() }).optional();
 var LINE_REPORT_KEYS = /* @__PURE__ */ new Set([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.22.0",
+  "version": "1.23.1",
   "mcpName": "io.github.levnikolaevich/hex-line-mcp",
   "type": "module",
   "description": "Hash-verified file editing MCP + token efficiency hook for AI coding agents. 9 tools: inspect_path, read, edit, write, grep, outline, verify, changes, bulk_replace.",