@bigknoxy/hashpilot 4.6.3

package/src/core/router.ts

@@ -0,0 +1,463 @@
+import { safeWrite } from "./paths";
+import {
+  isLanguageSupported,
+  detectLanguage,
+  renameSymbol,
+  replaceBody,
+  addImport,
+  removeImport,
+  insertBeforeSymbol,
+  insertAfterSymbol,
+  findSymbols,
+  findSymbolsDetailed,
+  firstParseError,
+} from "./ast-edit";
+import { replaceHash } from "./hash-edit";
+import { readMany, readHash, computeHash } from "./read";
+import { recordEvent, ErrorCode } from "./telemetry";
+import { buildProvenanceFields } from "./provenance";
+import { loadConfig, policyForce, RoutePolicy } from "./config";
+import { addWarning } from "./envelope";
+import { acquireLock, LOCK_TIMEOUT_MS, LockAcquireError } from "./locking";
+import { readDecoded } from "./encoding";
+import { toPreview } from "./diff-engine";
+import { verboseLog } from "./output";
+
+export type EditRoute = "ast" | "hash" | "diff";
+
+export interface RouteExplanation {
+  route: EditRoute;
+  reasons: string[];
+  policyApplied: boolean;
+  policySource?: string;
+}
+
+export interface RouterResult {
+  route: EditRoute;
+  routeReason: string;
+  fallback?: string;
+  result: any;
+  elapsed_ms: number;
+  explanation?: RouteExplanation;
+}
+
+export function chooseRoute(
+  filePath: string,
+  operation: string,
+  policy?: RoutePolicy
+): { route: EditRoute; explanation: RouteExplanation } {
+  const lang = detectLanguage(filePath);
+  const reasons: string[] = [];
+  let policyApplied = false;
+  let policySource: string | undefined;
+
+  // Derive a language key from extension for policy matching (even for unsupported langs)
+  const extMatch = filePath.match(/\.([^.]+)$/);
+  const extKey = lang || (extMatch ? extMatch[1] : null);
+
+  // 1. Check policy overrides first
+  const forced = policyForce(policy, extKey, operation);
+  if (forced) {
+    const src = lang && policy?.languageOverrides?.[lang]
+      ? `language override for '${lang}'`
+      : `operation override for '${operation}'`;
+    const fromConf = lang && policy?.languageOverrides?.[lang] ? "language" : "operation";
+    reasons.push(`Policy ${fromConf} forces route '${forced}'`);
+    policyApplied = true;
+    policySource = forced !== chooseRoute(filePath, operation).route ? fromConf : undefined;
+    return { route: forced, explanation: { route: forced, reasons, policyApplied, policySource } };
+  }
+
+  // 2. Language + AST operation check
+  if (isLanguageSupported(filePath) && isASTOperation(operation)) {
+    reasons.push(`Language '${lang}' supports AST operations`);
+    return { route: "ast", explanation: { route: "ast", reasons, policyApplied: false } };
+  }
+
+  // 3. Hash operations
+  if (isHashOperation(operation)) {
+    reasons.push(`Operation '${operation}' uses hash-based editing`);
+    return { route: "hash", explanation: { route: "hash", reasons, policyApplied: false } };
+  }
+
+  // 4. Diff fallback
+  const unsupported = !isLanguageSupported(filePath)
+    ? `Language '${lang || "unknown"}' not supported for AST`
+    : `Operation '${operation}' not available via AST or hash`;
+  reasons.push(unsupported);
+  reasons.push(`Falling back to diff route`);
+  return { route: "diff", explanation: { route: "diff", reasons, policyApplied: false } };
+}
+
+function isASTOperation(op: string): boolean {
+  return [
+    "rename-symbol",
+    "replace-body",
+    "add-import",
+    "remove-import",
+    "insert-before",
+    "insert-after",
+    "find-symbols",
+  ].includes(op);
+}
+
+function isHashOperation(op: string): boolean {
+  return ["read-hash", "replace-hash"].includes(op);
+}
+
+export async function routeEdit(params: {
+  filePath: string;
+  operation: string;
+  method?: EditRoute;
+  policy?: RoutePolicy;
+  // Hash params
+  oldHash?: string;
+  newContent?: string;
+  range?: { start: number; end: number };
+  // AST params
+  oldName?: string;
+  newName?: string;
+  symbolName?: string;
+  newBody?: string;
+  importSpec?: string;
+  content?: string;
+  // Diff params (search-and-replace fallback)
+  oldContent?: string;
+  dryRun?: boolean;
+  /**
+   * Dry runs return a unified diff instead of the whole post-edit file. Set this
+   * when you genuinely want the full text back (#98).
+   */
+  includeSource?: boolean;
+  /**
+   * Internal: the caller already holds this file's advisory lock (`batch-edit`
+   * locks its whole file set up front in sorted order, then routes each file).
+   * The lock is not re-entrant on purpose — two genuinely concurrent writers in
+   * one process must still exclude each other — so nesting would self-deadlock
+   * until the timeout. Not exposed on the CLI.
+   */
+  alreadyLocked?: boolean;
+  // Provenance params
+  actor?: string;
+  taskId?: string;
+  reason?: string;
+}): Promise<RouterResult> {
+  const start = Date.now();
+  let editSource: string | undefined;
+  let editResult: string | undefined;
+  const { filePath, operation, method, policy, oldHash, newContent, range, oldName, newName, symbolName, newBody, importSpec, content: insertContent, oldContent, dryRun, includeSource, alreadyLocked, actor, taskId, reason } = params;
+
+  let route: EditRoute;
+  let explanation: RouteExplanation;
+
+  // Load config-based policy if not explicitly provided
+  const resolvedPolicy = policy || loadConfig().routePolicy;
+
+  if (method) {
+    route = method;
+    explanation = { route, reasons: [`Explicit method override: ${method}`], policyApplied: false };
+  } else {
+    const decision = chooseRoute(filePath, operation, resolvedPolicy);
+    route = decision.route;
+    explanation = decision.explanation;
+    // A downgrade to the diff route is a real degradation of edit safety, and it
+    // used to be visible only in prose inside `routeReason`. Surface it.
+    if (route === "diff" && explanation.reasons.some((r) => r.startsWith("Falling back"))) {
+      addWarning({
+        code: "ROUTE_FALLBACK",
+        message: explanation.reasons.join("; "),
+        from: "ast",
+        to: "diff",
+      });
+    }
+  }
+
+  let result: any;
+  let routeReason = explanation.reasons.join("; ");
+  let fallback: string | undefined;
+
+  if (route === "ast" && !isLanguageSupported(filePath)) {
+    if (method) {
+      result = { success: false, message: `Cannot force AST route: ${filePath} is not a supported language file` };
+    } else {
+      fallback = "AST unsupported for this file type";
+      // A silent downgrade looks identical to a successful AST edit, which is
+      // exactly the debugging problem the envelope's `warnings` exists for.
+      addWarning({ code: "ROUTE_FALLBACK", message: fallback, from: "ast", to: "hash" });
+      route = "hash";
+    }
+  }
+
+  if (route === "hash") {
+    if (!oldHash || newContent === undefined) {
+      route = "diff";
+      fallback = "Hash edit requires oldHash and newContent";
+      addWarning({ code: "ROUTE_FALLBACK", message: fallback, from: "hash", to: "diff" });
+    }
+  }
+
+  routeReason = `${explanation.reasons.join("; ")}${fallback ? `; ${fallback}` : ""}`;
+
+  // `--verbose` explains the tier choice on stderr. Routing is the single most
+  // opaque decision HashPilot makes, and a silent AST->diff downgrade is exactly
+  // what an agent needs to see while debugging (#47).
+  verboseLog(() => `route: ${route} for ${operation} on ${filePath} (${routeReason})`);
+
+  // Compare-and-swap alone cannot close the single-file race: between the hash
+  // compare and `safeWrite` another writer can land, and CAS then reports success
+  // over top of an edit it never saw. Hold the same advisory lock `batch-edit`
+  // uses across the whole read → edit → compare → write window so CAS is checking
+  // a snapshot nobody else can invalidate. `batch-edit` locked its whole file set
+  // up front and passes `alreadyLocked` so it does not wait on itself (#21/B18).
+  let releaseFileLock: (() => void) | undefined;
+  if (!result && !dryRun && !alreadyLocked) {
+    try {
+      releaseFileLock = await acquireLock(filePath, { timeoutMs: LOCK_TIMEOUT_MS });
+    } catch (e: any) {
+      // A contended lock is transient, so it stays retryable — but it is NOT a
+      // stale anchor. Reporting it as one told callers to re-read the file
+      // (which changes nothing here) and inflated the stale-anchor health
+      // metric. `batch-edit` reports LOCK_TIMEOUT for the identical condition.
+      result = {
+        success: false,
+        stale: true,
+        errorCode: ErrorCode.LOCK_TIMEOUT,
+        message:
+          e instanceof LockAcquireError
+            ? `Could not lock ${filePath}: ${e.message}`
+            : `Could not lock ${filePath}: ${e?.message ?? e}`,
+        recovery: "Another edit holds this file. Wait and retry.",
+      };
+    }
+  }
+
+  try {
+  if (!result) {
+    switch (route) {
+      case "ast": {
+        let source: string;
+        let casHash: string | undefined;
+        try {
+          source = (await readDecoded(filePath)).text;
+          editSource = source;
+          casHash = computeHash(source);
+        } catch (e: any) {
+          result = { success: false, message: `Failed to read file: ${e.message}` };
+          break;
+        }
+        try {
+        switch (operation) {
+        case "rename-symbol":
+          result = renameSymbol(source, filePath, oldName!, newName!);
+          break;
+        case "replace-body":
+          result = replaceBody(source, filePath, symbolName!, newBody!);
+          break;
+        case "add-import":
+          result = addImport(source, filePath, importSpec!);
+          break;
+        case "remove-import":
+          result = removeImport(source, filePath, importSpec!);
+          break;
+        case "insert-before":
+          result = insertBeforeSymbol(source, filePath, symbolName!, insertContent!);
+          break;
+        case "insert-after":
+          result = insertAfterSymbol(source, filePath, symbolName!, insertContent!);
+          break;
+        case "find-symbols":
+          {
+            const search = findSymbolsDetailed(source, filePath);
+            result = { success: true, symbols: search.symbols, truncated: search.truncated, message: "Symbols found" };
+          }
+          break;
+        default:
+          result = { success: false, message: `Unknown AST operation: ${operation}` };
+      }
+        } catch (e: any) {
+          // The tree-sitter binding throws bare errors (it used to throw
+          // `Invalid argument` for any source over 32KB — see #55). Whatever
+          // the cause, an AST failure is an edit failure, never an internal
+          // crash: this is the only thing standing between a parser bug and
+          // exit 70.
+          result = {
+            success: false,
+            errorCode: ErrorCode.PARSE_ERROR,
+            message: `AST parse failed for ${filePath}: ${e?.message ?? e}`,
+            recovery: "Retry with an explicit --old-content/--new-content pair to use the diff route.",
+          };
+          addWarning({
+            code: "ROUTE_FALLBACK",
+            message: `AST route failed to parse ${filePath}; a diff-route edit is the remaining option.`,
+            from: "ast",
+            to: "diff",
+          });
+        }
+      // Write result to file if successful — CAS guard prevents silent data
+      // loss when concurrent edits both read the same snapshot.
+      if (result.success && (result as any).newSource && !dryRun) {
+        const currentOnDisk = (await readDecoded(filePath)).text;
+        const nowHash = computeHash(currentOnDisk);
+        if (nowHash !== casHash) {
+          result = {
+            success: false,
+            stale: true,
+            errorCode: ErrorCode.STALE_ANCHOR,
+            message: `CAS failed for ${filePath}: file changed while editing`,
+            newCurrentHash: nowHash,
+            recovery: "Re-read the file and retry the edit.",
+          };
+        } else {
+          await safeWrite(filePath, (result as any).newSource);
+          editResult = (result as any).newSource;
+        }
+      }
+      break;
+    }
+    case "hash":
+      editSource = (await readDecoded(filePath)).text;
+      result = await replaceHash(filePath, oldHash!, newContent!, { range, dryRun });
+      editResult = ((await readDecoded(filePath)).text);
+      break;
+    case "diff": {
+      // An empty newContent is a deletion. Only oldContent must be non-empty —
+      // there is nothing to search for otherwise (#40 falsy-parameter audit).
+      if (!oldContent || newContent === undefined) {
+        result = { success: false, message: "Diff route requires oldContent and newContent" };
+        break;
+      }
+      let source: string;
+      let casHash: string | undefined;
+      try {
+        source = (await readDecoded(filePath)).text;
+        editSource = source;
+        casHash = computeHash(source);
+      } catch (e: any) {
+        result = { success: false, message: `Failed to read file: ${e.message}` };
+        break;
+      }
+      result = applyTextReplace(source, filePath, oldContent, newContent);
+      // Same post-edit parse check the AST and hash tiers apply: a search-and-
+      // replace that lands mid-expression must not reach disk (#13).
+      if (result.success && (result as any).newSource) {
+        const after = firstParseError((result as any).newSource, filePath);
+        if (after && !firstParseError(source, filePath)) {
+          result = {
+            success: false,
+            errorCode: ErrorCode.PARSE_ERROR,
+            message:
+              `Edit was discarded: the result does not parse (syntax error at line ${after.line}:${after.column} — ${after.nodeType}). ` +
+              `The file parsed cleanly before, so this replacement would have corrupted it.`,
+          };
+          break;
+        }
+      }
+      if (result.success && (result as any).newSource && !dryRun) {
+        const currentOnDisk = (await readDecoded(filePath)).text;
+        const nowHash = computeHash(currentOnDisk);
+        if (nowHash !== casHash) {
+          result = {
+            success: false,
+            stale: true,
+            errorCode: ErrorCode.STALE_ANCHOR,
+            message: `CAS failed for ${filePath}: file changed while editing`,
+            newCurrentHash: nowHash,
+            recovery: "Re-read the file and retry the edit.",
+          };
+        } else {
+          await safeWrite(filePath, (result as any).newSource);
+          editResult = (result as any).newSource;
+        }
+      }
+      break;
+    }
+    default:
+      result = { success: false, message: `Unknown route: ${route}` };
+    }
+  }
+  } finally {
+    releaseFileLock?.();
+  }
+
+  const elapsed = Date.now() - start;
+
+  let errorCode: ErrorCode | undefined;
+  if (!result.success) {
+    if (result.stale) {
+      errorCode = ErrorCode.STALE_ANCHOR;
+    } else if (result.message?.includes("not found") || result.message?.includes("ENOENT")) {
+      errorCode = ErrorCode.FILE_NOT_FOUND;
+    } else if (result.message?.includes("hash")) {
+      errorCode = ErrorCode.HASH_MISMATCH;
+    }
+  }
+
+  const provenanceFields = buildProvenanceFields({
+    actor,
+    taskId,
+    reason,
+    source: editSource,
+    newSource: editResult,
+    filePath,
+  });
+
+  recordEvent({
+    operation,
+    route,
+    file: filePath,
+    language: detectLanguage(filePath) || undefined,
+    success: result.success ?? false,
+    fallback_reason: fallback,
+    retries: result.retries,
+    elapsed_ms: elapsed,
+    errorCode,
+    ...provenanceFields,
+  });
+
+  // A dry run previews; it does not dump the file back at the caller (#98).
+  const payload = dryRun ? toPreview(result, editSource, filePath, includeSource) : result;
+
+  verboseLog(() => `result: ${result.success ? "ok" : "failed"} via ${route} in ${elapsed}ms`);
+
+  return { route, routeReason, fallback, result: payload, elapsed_ms: elapsed, explanation };
+}
+
+/**
+ * Search-and-replace fallback for the diff route.
+ * Detects duplicates and reports the count. If oldContent appears more than once,
+ * fails with a message listing occurrences so the caller can disambiguate.
+ */
+function applyTextReplace(
+  source: string,
+  filePath: string,
+  oldContent: string,
+  newContent: string
+): { success: boolean; message: string; newSource?: string } {
+  // Count exact occurrences in the full source
+  const occurrences: number[] = [];
+  let idx = 0;
+  while ((idx = source.indexOf(oldContent, idx)) !== -1) {
+    const lineNum = source.slice(0, idx).split("\n").length;
+    occurrences.push(lineNum);
+    idx += oldContent.length;
+  }
+
+  if (occurrences.length === 0) {
+    return { success: false, message: `Content not found in ${filePath}. File may have changed — re-read and retry.` };
+  }
+
+  if (occurrences.length > 1) {
+    const locs = occurrences.map((l) => `line ${l}`).join(", ");
+    return {
+      success: false,
+      message: `Content appears ${occurrences.length} times (${locs}). Provide more context to disambiguate.`,
+    };
+  }
+
+  const newSource = source.split(oldContent).join(newContent);
+  return {
+    success: true,
+    message: `Replaced content at line ${occurrences[0]}`,
+    newSource,
+  };
+}