@backbencher/brain 0.0.0-stage → 0.1.0

package/dist/chunk-CW4XXSNN.js

@@ -0,0 +1,1479 @@
+import {
+  reindexFilesParallel
+} from "./chunk-PJTNGD3Z.js";
+import {
+  assertFreshFiles,
+  extractIdentifierOccurrences,
+  parseForSafety
+} from "./chunk-YI6FF2ZR.js";
+import {
+  checkSymbolFreshness,
+  fileUnchangedSince
+} from "./chunk-QLK6ED4Q.js";
+import {
+  BrainDatabase
+} from "./chunk-KLK3PBTO.js";
+import {
+  ASTEngine
+} from "./chunk-V44PGPA6.js";
+import {
+  bbDataDir
+} from "./chunk-2BSKD7O3.js";
+import {
+  EXTENSION_LANGUAGE
+} from "./chunk-KCDECRJY.js";
+
+// src/intelligence/edit/edit-engine.ts
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, realpathSync, renameSync, rmSync, writeFileSync as writeFileSync2, statSync, chmodSync } from "fs";
+import { createHash } from "crypto";
+import path2 from "path";
+import { randomUUID } from "crypto";
+
+// src/ast/brain-surgical-patcher.ts
+import * as fs from "fs";
+import { execFile } from "child_process";
+import * as path from "path";
+var FORMAT_TIMEOUT_MS = 1500;
+var BrainSurgicalPatcher = class _BrainSurgicalPatcher {
+  static async patch(absolutePath, startIndex, endIndex, newContent, isDelete = false, format = true) {
+    if (!fs.existsSync(absolutePath)) {
+      throw new Error(`[BrainSurgicalPatcher] File not found: ${absolutePath}`);
+    }
+    if (startIndex < 0 || endIndex < 0 || startIndex > endIndex) {
+      throw new Error(`[BrainSurgicalPatcher] Invalid bounds: [${startIndex}, ${endIndex}]`);
+    }
+    const originalContent = fs.readFileSync(absolutePath, "utf8");
+    if (endIndex > originalContent.length) {
+      throw new Error(`[BrainSurgicalPatcher] endIndex (${endIndex}) exceeds file length (${originalContent.length})`);
+    }
+    let actualStart = startIndex;
+    let actualEnd = endIndex;
+    let finalContent = newContent;
+    if (isDelete) {
+      while (actualStart > 0) {
+        const char = originalContent[actualStart - 1];
+        if (char === " " || char === "	") {
+          actualStart--;
+        } else {
+          break;
+        }
+      }
+      const isAtLineStart = actualStart === 0 || originalContent[actualStart - 1] === "\n";
+      if (isAtLineStart) {
+        if (actualEnd < originalContent.length && originalContent[actualEnd] === "\r") {
+          actualEnd++;
+        }
+        if (actualEnd < originalContent.length && originalContent[actualEnd] === "\n") {
+          actualEnd++;
+        }
+      }
+    } else {
+      let baseIndent = "";
+      let tempStart = startIndex;
+      while (tempStart > 0) {
+        const char = originalContent[tempStart - 1];
+        if (char === "\n") break;
+        if (char === " " || char === "	") {
+          baseIndent = char + baseIndent;
+        } else {
+          baseIndent = "";
+        }
+        tempStart--;
+      }
+      if (baseIndent.length > 0 && finalContent.includes("\n")) {
+        const lines = finalContent.split("\n");
+        const secondLine = lines.length > 1 ? lines[1] : "";
+        const hasOwnIndent = secondLine.startsWith(" ") || secondLine.startsWith("	");
+        if (!hasOwnIndent && secondLine.trim().length > 0) {
+          for (let i = 1; i < lines.length; i++) {
+            if (lines[i].trim().length > 0) {
+              lines[i] = baseIndent + lines[i];
+            }
+          }
+          finalContent = lines.join("\n");
+        }
+      }
+    }
+    const before = originalContent.substring(0, actualStart);
+    const after = originalContent.substring(actualEnd);
+    const patchedContent = before + finalContent + after;
+    fs.writeFileSync(absolutePath, patchedContent, "utf8");
+    if (format) {
+      void _BrainSurgicalPatcher.tryAutoFormat(absolutePath);
+    }
+    return true;
+  }
+  /**
+   * D5: the extension → formatter mapping, as data rather than a built shell string.
+   *
+   * The invocation is argv, never a command line that interpolates the path:
+   * `exec(\`npx prettier --write "${absolutePath}"\`)`. Two consequences, both
+   * measured before the rewrite (script/m71/probe-format-truth.ts):
+   *
+   *   1. `npx` without a local install is an INSTALL attempt. On a machine with no
+   *      prettier it hit the network and was killed by the 1500ms timeout —
+   *      1573ms of wall time per edited file, on a tool whose performance claim is
+   *      "only affected files are written", with the result saying
+   *      `formatted: true` regardless.
+   *   2. A filename is not trusted input. `resolveSafeEditPath` validates
+   *      containment, not characters, so a file NAMED `inj$(touch pwned).ts` is a
+   *      legal in-project path — and the shell expanded the substitution. The
+   *      marker file appeared; that is command execution triggered by the name of
+   *      a file being formatted, through the public edit path.
+   *
+   * So the binary is resolved explicitly (nearest node_modules/.bin walking up from
+   * the file, then PATH) and invoked with execFile: an argv array, no shell, and
+   * nothing in the path can be expanded.
+   */
+  static FORMATTERS = [
+    { ext: [".ts", ".tsx", ".js", ".jsx", ".json", ".html", ".css", ".md"], candidates: [{ name: "prettier", args: ["--write"] }] },
+    { ext: [".rs"], candidates: [{ name: "rustfmt", args: [] }] },
+    { ext: [".go"], candidates: [{ name: "gofmt", args: ["-w"] }] },
+    { ext: [".c", ".cpp", ".h", ".hpp"], candidates: [{ name: "clang-format", args: ["-i"] }] },
+    { ext: [".py"], candidates: [{ name: "black", args: [] }, { name: "ruff", args: ["format"] }] }
+  ];
+  /** Executable `<name>` in the nearest node_modules/.bin at or above `startDir`. */
+  static resolveInNodeModules(startDir, name) {
+    let dir = startDir;
+    for (; ; ) {
+      const candidate = path.join(dir, "node_modules", ".bin", name);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      } catch {
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) return null;
+      dir = parent;
+    }
+  }
+  /** Executable `<name>` on PATH. */
+  static resolveOnPath(name) {
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+      if (!dir) continue;
+      const candidate = path.join(dir, name);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      } catch {
+      }
+    }
+    return null;
+  }
+  static async tryAutoFormat(absolutePath) {
+    const ext = path.extname(absolutePath);
+    const mapping = _BrainSurgicalPatcher.FORMATTERS.find((m) => m.ext.includes(ext));
+    if (!mapping) return { formatter: null, ran: false, ok: false, reason: `no formatter mapped for ${ext}` };
+    const names = mapping.candidates.map((candidate) => candidate.name);
+    let endOfLine = [];
+    try {
+      const head = fs.readFileSync(absolutePath).subarray(0, 4096).toString("utf8");
+      const crlf = (head.match(/\r\n/g) ?? []).length;
+      const lf = (head.match(/(?<!\r)\n/g) ?? []).length;
+      if (crlf > lf || crlf > 0 && lf === 0) endOfLine = ["--end-of-line", "crlf"];
+    } catch {
+    }
+    let firstFailure = null;
+    for (const candidate of mapping.candidates) {
+      const bin = _BrainSurgicalPatcher.resolveInNodeModules(path.dirname(absolutePath), candidate.name) ?? _BrainSurgicalPatcher.resolveOnPath(candidate.name);
+      if (!bin) continue;
+      const args = [...candidate.args, ...candidate.name === "prettier" ? endOfLine : [], absolutePath];
+      const outcome = await new Promise((resolve) => {
+        execFile(bin, args, { cwd: path.dirname(absolutePath), timeout: FORMAT_TIMEOUT_MS, windowsHide: true }, (error, _stdout, stderr) => {
+          if (!error) return resolve({ formatter: candidate.name, ran: true, ok: true });
+          if (error.killed || error.signal) {
+            return resolve({ formatter: candidate.name, ran: true, ok: false, reason: `${candidate.name} timed out after ${FORMAT_TIMEOUT_MS}ms` });
+          }
+          const code = error.code;
+          const detail = String(stderr ?? "").split("\n").map((line) => line.trim()).filter(Boolean)[0] ?? error.message;
+          const how = typeof code === "number" ? `exited ${code}` : code === "ENOENT" ? "could not be started" : "failed";
+          resolve({ formatter: candidate.name, ran: true, ok: false, reason: `${candidate.name} ${how}: ${detail.slice(0, 160)}` });
+        });
+      });
+      if (outcome.ok) return outcome;
+      if (!firstFailure) firstFailure = outcome;
+    }
+    return firstFailure ?? {
+      formatter: names[0] ?? null,
+      ran: false,
+      ok: false,
+      reason: `no formatter found: tried ${names.join(", ")} in node_modules/.bin (walking up from the file) and on PATH`
+    };
+  }
+};
+
+// src/ast/import-pruner.ts
+var PRUNABLE_LANGUAGES = Object.freeze(["typescript", "javascript", "tsx", "jsx"]);
+var ImportPruner = class _ImportPruner {
+  /**
+   * Remove import bindings that the `delete` made unreferenced, and report what
+   * was and was not attempted so the delete result can declare it.
+   *
+   * A file this module cannot parse, or whose language is outside
+   * PRUNABLE_LANGUAGES, is returned EXACTLY as given: a leftover import never
+   * breaks a build, and an import removed on a guess does. When pruning is not
+   * attempted the report says so and names the language; the edit is correct
+   * either way, and the caller is never left to assume cleanup happened.
+   */
+  static async pruneWithReport(fileContent, filePath) {
+    const language = ASTEngine.detectLanguage(filePath);
+    if (!language) {
+      return { attempted: false, language: null, removedBindings: [], reason: "the file's language is not recognised, so no import syntax could be read", content: fileContent };
+    }
+    if (!PRUNABLE_LANGUAGES.includes(language)) {
+      return {
+        attempted: false,
+        language,
+        removedBindings: [],
+        reason: `import pruning is implemented for TypeScript/JavaScript only; ${language} imports were left unchanged rather than pattern-matched`,
+        content: fileContent
+      };
+    }
+    let tree = null;
+    try {
+      const parsed = await ASTEngine.parseTree(filePath, fileContent);
+      tree = parsed.tree;
+      const occurrences = extractIdentifierOccurrences(tree, fileContent);
+      const statements = _ImportPruner.importStatements(tree);
+      if (statements.length === 0) {
+        return { attempted: true, language, removedBindings: [], content: fileContent };
+      }
+      const isInsideImport = (index) => statements.some((s) => index >= s.start && index < s.end);
+      const usedOutsideImports = new Set(occurrences.filter((o) => !isInsideImport(o.startIndex)).map((o) => o.text));
+      const removedBindings = _ImportPruner.unusedBindings(statements, usedOutsideImports);
+      return { attempted: true, language, removedBindings, content: _ImportPruner.rewrite(fileContent, statements, usedOutsideImports) };
+    } catch (error) {
+      return {
+        attempted: false,
+        language,
+        removedBindings: [],
+        reason: `the file could not be parsed for import pruning (${error?.message ?? String(error)}), so its imports were left unchanged`,
+        content: fileContent
+      };
+    } finally {
+      try {
+        if (tree && typeof tree.delete === "function") tree.delete();
+      } catch {
+      }
+    }
+  }
+  /** Remove import bindings that the `delete` made unreferenced. */
+  static async prune(fileContent, filePath) {
+    return (await _ImportPruner.pruneWithReport(fileContent, filePath)).content ?? fileContent;
+  }
+  /** Local names of the bindings no live occurrence refers to. */
+  static unusedBindings(statements, used) {
+    const out = [];
+    for (const statement of statements) {
+      for (const binding of statement.bindings) if (!used.has(binding.localName)) out.push(binding.localName);
+    }
+    return out;
+  }
+  /** Every top-level import statement with its bindings, in source order. */
+  static importStatements(tree) {
+    const out = [];
+    const children = tree?.rootNode?.children ?? [];
+    for (const node of children) {
+      if (node?.type !== "import_statement") continue;
+      const clause = (node.children ?? []).find((c) => c.type === "import_clause");
+      const bindings = [];
+      if (clause) {
+        for (const child of clause.children ?? []) {
+          if (child.type === "identifier") {
+            bindings.push({ localName: child.text, start: child.startIndex, end: child.endIndex, kind: "default" });
+          } else if (child.type === "named_imports") {
+            for (const spec of child.children ?? []) {
+              if (spec.type !== "import_specifier") continue;
+              const identifiers = (spec.children ?? []).filter((c) => c.type === "identifier");
+              const local = identifiers.length > 1 ? identifiers[identifiers.length - 1] : identifiers[0];
+              if (!local) continue;
+              bindings.push({ localName: local.text, start: spec.startIndex, end: spec.endIndex, kind: "named" });
+            }
+          } else if (child.type === "namespace_import") {
+            const id = (child.children ?? []).find((c) => c.type === "identifier");
+            if (id) bindings.push({ localName: id.text, start: child.startIndex, end: child.endIndex, kind: "namespace" });
+          }
+        }
+      }
+      out.push({ start: node.startIndex, end: node.endIndex, bindings });
+    }
+    return out;
+  }
+  /** Apply statement/specifier removals bottom-up so byte offsets stay valid. */
+  static rewrite(content, statements, used) {
+    const removals = [];
+    for (const statement of statements) {
+      if (statement.bindings.length === 0) continue;
+      const unused = statement.bindings.filter((binding) => !used.has(binding.localName));
+      if (unused.length === 0) continue;
+      if (unused.length === statement.bindings.length) {
+        removals.push({ start: statement.start, end: _ImportPruner.throughTrailingNewline(content, statement.end) });
+        continue;
+      }
+      for (const binding of unused) {
+        if (binding.kind !== "named") continue;
+        const range = _ImportPruner.specifierRemoval(content, binding.start, binding.end);
+        if (range) removals.push(range);
+      }
+    }
+    let result = content;
+    for (const range of removals.sort((a, b) => b.start - a.start)) {
+      result = result.slice(0, range.start) + result.slice(range.end);
+    }
+    return result;
+  }
+  /** End offset widened over a trailing newline so a removed statement leaves no blank line. */
+  static throughTrailingNewline(content, end) {
+    let cursor = end;
+    if (content[cursor] === "\r") cursor++;
+    if (content[cursor] === "\n") cursor++;
+    return cursor;
+  }
+  /** The range to delete for one named specifier, eating one adjacent comma. */
+  static specifierRemoval(content, start, end) {
+    let from = start;
+    const to = end;
+    let cursor = to;
+    while (cursor < content.length && (content[cursor] === " " || content[cursor] === "	")) cursor++;
+    if (content[cursor] === ",") {
+      cursor++;
+      while (cursor < content.length && (content[cursor] === " " || content[cursor] === "	")) cursor++;
+      return { start: from, end: cursor };
+    }
+    let back = from;
+    while (back > 0 && (content[back - 1] === " " || content[back - 1] === "	")) back--;
+    if (back > 0 && content[back - 1] === ",") {
+      back--;
+      while (back > 0 && (content[back - 1] === " " || content[back - 1] === "	")) back--;
+      return { start: back, end: to };
+    }
+    return null;
+  }
+};
+
+// src/intelligence/edit/edit-engine.ts
+function inside(root, candidate) {
+  const relative = path2.relative(root, candidate);
+  return relative === "" || !relative.startsWith(".." + path2.sep) && relative !== ".." && !path2.isAbsolute(relative);
+}
+function nearestExisting(candidate) {
+  let cursor = candidate;
+  while (!existsSync2(cursor)) {
+    const parent = path2.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return cursor;
+}
+function resolveSafeEditPath(projectPath, requested) {
+  const root = realpathSync(projectPath);
+  const raw = path2.isAbsolute(requested) ? requested : path2.resolve(root, requested);
+  const existing = nearestExisting(raw);
+  const realExisting = realpathSync(existing);
+  if (!inside(root, realExisting)) {
+    const viaSymlink = realExisting !== existing;
+    throw new Error(
+      `path escapes project root${viaSymlink ? " through symlink" : ""}: ${requested}${raw === existing ? "" : ` (via ${existing})`}`
+    );
+  }
+  if (raw !== existing) {
+    const tail = path2.relative(existing, raw);
+    const target = tail ? path2.join(realExisting, tail) : realExisting;
+    if (!inside(root, target)) throw new Error(`path escapes project root through symlink: ${requested}`);
+    assertWritableTarget(root, target, requested);
+    return target;
+  }
+  assertWritableTarget(root, realExisting, requested);
+  return realExisting;
+}
+var PROTECTED_SEGMENTS = /* @__PURE__ */ new Set([".git", ".hg", ".svn", "node_modules", ".bb-data"]);
+function assertWritableTarget(root, target, requested) {
+  const relative = path2.relative(root, target);
+  const protectedSegment = relative.split(path2.sep).find((segment) => PROTECTED_SEGMENTS.has(segment));
+  if (protectedSegment) {
+    throw new Error(
+      `refused: ${requested} is inside a protected path (${protectedSegment}/) \u2014 bb_edit does not write version-control, dependency, or tool-state directories; choose a source path instead`
+    );
+  }
+  let dataDir = null;
+  try {
+    dataDir = bbDataDir();
+  } catch {
+    dataDir = null;
+  }
+  if (dataDir && inside(dataDir, target)) {
+    throw new Error(
+      `refused: ${requested} is inside the index data directory (${dataDir}) \u2014 bb_edit never edits index state as source; choose a source path instead`
+    );
+  }
+}
+function replaceRange(text, start, end, replacement) {
+  if (start < 0 || end < start || end > text.length) throw new Error(`invalid edit bounds: ${start}-${end}`);
+  return text.slice(0, start) + replacement + text.slice(end);
+}
+function dominantNewline(text) {
+  let crlf = 0;
+  let lf = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] !== "\n") continue;
+    if (i > 0 && text[i - 1] === "\r") crlf++;
+    else lf++;
+  }
+  return crlf > lf ? "\r\n" : "\n";
+}
+function withNewline(text, nl) {
+  return nl === "\n" ? text : text.replace(/\r?\n/g, nl);
+}
+function hasLoneLf(text) {
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] !== "\n") continue;
+    if (i === 0 || text[i - 1] !== "\r") return true;
+  }
+  return false;
+}
+function snapshotOf(file) {
+  if (!existsSync2(file)) return { existed: false, bytes: null, mode: null, hash: null };
+  const bytes = readFileSync2(file);
+  let mode = null;
+  try {
+    mode = statSync(file).mode & 511;
+  } catch {
+    mode = null;
+  }
+  return { existed: true, bytes, mode, hash: createHash("sha256").update(bytes).digest("hex") };
+}
+function fileHash(file) {
+  try {
+    if (!existsSync2(file)) return null;
+    return createHash("sha256").update(readFileSync2(file)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+function preImageMismatches(projectPath, planned, current) {
+  const moved = [];
+  for (const path0 of Object.keys(planned)) {
+    const want = planned[path0];
+    const got = current.get(path0) ?? null;
+    if (want === got) continue;
+    const label = relativeTo(projectPath, path0);
+    moved.push(`${label} (planned ${want ? want.slice(0, 12) : "no file at that path"}, now ${got ? got.slice(0, 12) : "gone"})`);
+  }
+  return moved;
+}
+function writeBytesPreservingMode(file, bytes, mode) {
+  writeFileSync2(file, bytes);
+  if (mode !== null) {
+    try {
+      chmodSync(file, mode);
+    } catch {
+    }
+  }
+}
+var WRITE_GUARD = {
+  /** A replacement that removes fewer lines than this is never questioned. */
+  minRemovedLines: 5,
+  /** …and it must also leave no more than this share of the pre-image's lines. */
+  maxRemainingRatio: 0.5
+};
+function lineCount(text) {
+  if (text.length === 0) return 0;
+  const end = text.endsWith("\n") ? text.length - 1 : text.length;
+  return text.slice(0, end).split("\n").length;
+}
+function writeGuardMessage(relPath, target, overwrite) {
+  if (!target.existed) return null;
+  if (overwrite === false) {
+    return `write refused: ${relPath} already exists and overwrite is false (create-only) \u2014 pass overwrite: true to replace it, or use update/insert to change it in place.`;
+  }
+  if (overwrite === true) return null;
+  const beforeLines = lineCount(target.before);
+  const afterLines = lineCount(target.after);
+  const removed = beforeLines - afterLines;
+  if (removed < WRITE_GUARD.minRemovedLines) return null;
+  if (afterLines > beforeLines * WRITE_GUARD.maxRemainingRatio) return null;
+  const percent = Math.round(removed / beforeLines * 100);
+  return `write refused: it would replace ${relPath} (${beforeLines} lines) with ${afterLines} line(s), removing ${removed} lines (${percent}%) \u2014 a write that removes at least half of a file's lines (and at least ${WRITE_GUARD.minRemovedLines}) is treated as a probable mistake. Pass overwrite: true to replace it anyway, or use update/insert to change part of the file.`;
+}
+function findSymbolBody(parsed, start, end) {
+  const candidates = parsed.bodyRanges.filter((b) => b.startIndex >= start && b.endIndex <= end);
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => a.startIndex - b.startIndex || b.endIndex - a.endIndex);
+  return candidates[0];
+}
+function lineIndent(text, pos) {
+  let lineStart = pos;
+  while (lineStart > 0 && text[lineStart - 1] !== "\n") lineStart--;
+  return text.slice(lineStart, pos);
+}
+function indentLines(text, indent, includeFirst) {
+  return text.split("\n").map((line, i) => i === 0 && !includeFirst || line.length === 0 ? line : indent + line).join("\n");
+}
+function lineLeadingWhitespace(text, pos) {
+  let lineStart = pos;
+  while (lineStart > 0 && text[lineStart - 1] !== "\n") lineStart--;
+  let i = lineStart;
+  while (i < pos && (text[i] === " " || text[i] === "	")) i++;
+  return text.slice(lineStart, i);
+}
+function indentUnit(text) {
+  const lines = text.split("\n").slice(0, 200);
+  let min = "";
+  for (const line of lines) {
+    const m = /^[\t ]+/.exec(line);
+    if (!m) continue;
+    if (m[0].includes("	") && !m[0].includes(" ")) return "	";
+    if (min === "" || m[0].length < min.length) min = m[0];
+  }
+  if (min.length >= 4) return "    ";
+  return "  ";
+}
+function computeInnerIndent(text, body) {
+  const open = body.startIndex;
+  const end = body.endIndex;
+  let i = open + 1;
+  while (i < end && (text[i] === " " || text[i] === "	" || text[i] === "\r" || text[i] === "\n")) i++;
+  if (i >= end) return lineLeadingWhitespace(text, open) + indentUnit(text);
+  if (!text.slice(open, i).includes("\n")) return lineLeadingWhitespace(text, open) + indentUnit(text);
+  return lineLeadingWhitespace(text, i);
+}
+var FALSE_POSITIVE_BINDING_TYPES = /* @__PURE__ */ new Set([
+  "field_expression",
+  // Rust, C/C++, Scala, Zig — t.includes("field") matches
+  "field_access"
+  // Java — t.includes("field") matches
+]);
+function isBindingParentType(type) {
+  const t = type.toLowerCase();
+  if (FALSE_POSITIVE_BINDING_TYPES.has(t)) return false;
+  return t.includes("declarator") || // variable_declarator, function_declarator (C/C++)
+  t.includes("declaration") || // function/class/method/variable/field_declaration
+  t.includes("definition") || // function/class/method/field_definition
+  t.includes("parameter") || // formal/required/typed/default parameter
+  t.includes("field") || // field_declaration / field_definition / record_field
+  t.includes("property") || // property_signature / property_declaration
+  t.includes("signature") || // function_signature (Dart), method/property_signature (TS)
+  t === "method" || // Ruby def name
+  t === "class" || // Ruby class/module name (bare 'class' node)
+  t === "bind" || // Haskell top-level binding (function/pattern)
+  t.endsWith("_item") || // Rust function/struct/enum/trait/impl/mod/type/const/static_item
+  t.endsWith("specifier") || // C/C++ class/struct/union/enum_specifier
+  t.endsWith("_spec") || // Go type_spec / import_spec
+  t === "type_name" || // F# type name container
+  t === "assignment" || // Python `x = …`
+  t === "pair" || // JS/TS object key { target: … }
+  t.includes("import") || // import_specifier
+  t === "catch_clause" || // catch (target)
+  t.includes("for_in") || // for (target in …)
+  t.includes("for_of") || // for (target of …)
+  t.includes("shorthand");
+}
+var VALUE_SIDE_BINDING_PARENTS = /* @__PURE__ */ new Set([
+  "assignment",
+  "augmented_assignment",
+  "variable_declarator",
+  "pair",
+  "var_spec",
+  "init_declarator",
+  "field_declaration"
+]);
+function isReferenceSite(o, _relType) {
+  if (o.isMemberName) return false;
+  if (isBindingParentType(o.parentType)) {
+    if (VALUE_SIDE_BINDING_PARENTS.has(o.parentType) && (o.parentField === "value" || o.parentField === "right" || o.parentField === "initializer")) return true;
+    return false;
+  }
+  return true;
+}
+function findDeclarationName(occurrences, symbolName, start, end) {
+  let best;
+  for (const o of occurrences) {
+    if (o.text !== symbolName) continue;
+    if (o.startIndex < start || o.endIndex > end) continue;
+    if (!isBindingParentType(o.parentType)) continue;
+    if (!best || o.startIndex < best.startIndex) best = o;
+  }
+  return best ? best.startIndex : void 0;
+}
+async function staleDeclarationFile(projectId, match) {
+  const raw = await BrainDatabase.getRawInstance(projectId);
+  const freshness = checkSymbolFreshness(raw, match.id);
+  if (freshness?.status === "fresh") return null;
+  const row = raw.prepare("SELECT file_hash FROM brain_file WHERE path=? AND project_id=?").get(match.fileId, projectId);
+  if (!row?.file_hash || !fileUnchangedSince(match.fileId, row.file_hash)) return match.fileId;
+  return null;
+}
+function matchesOf(found) {
+  return (found?.matches ?? []).filter((m) => m.byteStart != null && m.byteEnd != null);
+}
+async function indexedFileCount(projectId) {
+  try {
+    const raw = await BrainDatabase.getRawInstance(projectId);
+    return Number(raw.prepare("SELECT COUNT(*) c FROM brain_file WHERE project_id=?").get(projectId).c ?? 0);
+  } catch {
+    return -1;
+  }
+}
+async function uniqueSymbol(projectId, name, filePath, lineStart, allowStaleIndex = false, projectPath, warnings) {
+  const found = await ASTEngine.findSymbol(projectId, name, filePath, lineStart);
+  let matches = matchesOf(found);
+  if (matches.length === 0) {
+    if (await indexedFileCount(projectId) === 0) {
+      const project = projectPath ? `"${projectPath}"` : "<project>";
+      throw new Error(
+        `symbol ${name} could not be resolved: this project has no index (0 files indexed), so the name cannot be found in it \u2014 index it first: bb index ${project}. bb_edit write mode does not need an index and works now; update, insert, delete and refactor resolve their target through the index.`
+      );
+    }
+    throw new Error(`symbol ${name} not found or has no byte bounds`);
+  }
+  if (matches.length > 1) throw new Error(`symbol ${name} is ambiguous; provide filePath and lineStart`);
+  let match = matches[0];
+  if (allowStaleIndex) return match;
+  const staleFile = await staleDeclarationFile(projectId, match);
+  if (!staleFile) return match;
+  if (!projectPath) throw new Error(`stale index bounds for ${name}; reindex before editing`);
+  try {
+    await reindexFilesParallel(projectId, realpathSync(projectPath), [{ path: staleFile, type: "modified" }]);
+  } catch (e) {
+    throw new Error(
+      `stale index bounds for ${name}: ${staleFile} changed after indexing and refreshing it failed (${e?.message ?? String(e)}); run bb_index for that file, then retry`
+    );
+  }
+  const reFound = await ASTEngine.findSymbol(projectId, name, filePath, lineStart);
+  matches = matchesOf(reFound);
+  if (matches.length === 0) throw new Error(`symbol ${name} not found after refreshing ${staleFile} \u2014 it was renamed or removed since it was indexed`);
+  if (matches.length > 1) throw new Error(`symbol ${name} is ambiguous; provide filePath and lineStart`);
+  match = matches[0];
+  if (await staleDeclarationFile(projectId, match)) {
+    throw new Error(`stale index bounds for ${name} persist after refreshing ${staleFile}; reindex before editing`);
+  }
+  warnings?.push(`refreshed stale index rows for ${path2.basename(match.fileId)} before editing (the file changed after it was indexed)`);
+  return match;
+}
+function basenameNoExt(fileId) {
+  return path2.basename(fileId, path2.extname(fileId));
+}
+var IMPORT_SPECIFIER_PARENTS = /* @__PURE__ */ new Set([
+  "import_specifier",
+  "import_clause",
+  "export_specifier",
+  "dotted_name",
+  "scoped_identifier"
+]);
+var MODULE_EXTENSIONS = Object.freeze(
+  Array.from(new Set(Object.keys(EXTENSION_LANGUAGE).filter((k) => k !== k.toUpperCase()).map((k) => `.${k}`)))
+);
+function resolveImportToFile(importerRelPath, spec, declRelPath) {
+  if (!spec) return false;
+  const importerDir = path2.posix.dirname(importerRelPath.replace(/\\/g, "/"));
+  let base;
+  if (spec.startsWith("./") || spec.startsWith("../") || spec === "." || spec === "..") {
+    base = path2.posix.normalize(path2.posix.join(importerDir, spec));
+  } else if (spec.startsWith("/")) {
+    base = path2.posix.normalize(spec.slice(1));
+  } else return false;
+  const declExt = path2.posix.extname(declRelPath);
+  const declStem = declRelPath.slice(0, declRelPath.length - declExt.length);
+  if (base === declRelPath || base === declStem) return true;
+  if (path2.posix.dirname(declStem) === base) {
+    const asIndex = path2.posix.basename(declStem);
+    if (asIndex === "index" || MODULE_EXTENSIONS.some((e) => asIndex === `index${e}`)) return true;
+  }
+  return false;
+}
+function projectRelativePath(raw, projectId, fileId, projectRoot) {
+  const row = raw.prepare("SELECT relative_path AS relPath FROM brain_file WHERE project_id = ? AND (id = ? OR path = ?)").get(projectId, fileId, fileId);
+  if (row?.relPath) return row.relPath.replace(/\\/g, "/");
+  if (projectRoot && path2.isAbsolute(fileId)) {
+    const rel = path2.relative(projectRoot, fileId);
+    if (rel && !rel.startsWith("..")) return rel.split(path2.sep).join("/");
+  }
+  return null;
+}
+function relativeTo(root, file) {
+  const rel = path2.relative(root, file);
+  return rel && !rel.startsWith("..") ? rel : path2.basename(file);
+}
+async function validateFile(filePath, content) {
+  const result = await ASTEngine.parseFile(filePath, content);
+  const errors = (result.errors ?? []).filter((error) => /syntax error/i.test(error.message ?? ""));
+  if (errors.length > 0) throw new Error(`validation failed for ${filePath}: ${errors[0].message}`);
+}
+var MEMBER_NAME_PARENT_TYPES = /* @__PURE__ */ new Set([
+  "pair",
+  "pair_pattern",
+  "method_definition",
+  "public_field_definition",
+  "property_signature"
+]);
+var PARAMETER_BINDING_PARENTS = /* @__PURE__ */ new Set([
+  "required_parameter",
+  "optional_parameter",
+  "formal_parameters",
+  "formal_parameter",
+  "spread_parameter",
+  "parameter",
+  "parameter_declaration",
+  "parameters",
+  "method_parameters",
+  "lambda_parameters",
+  "typed_parameter",
+  "default_parameter"
+]);
+function collectShadowScopes(parsed, symbolName, declStart) {
+  const out = [];
+  for (const o of parsed.occurrences) {
+    if (o.text !== symbolName) continue;
+    if (!isBindingParentType(o.parentType)) continue;
+    if (o.startIndex === declStart) continue;
+    if (PARAMETER_BINDING_PARENTS.has(o.parentType)) {
+      const following = parsed.bodyRanges.filter((b) => b.startIndex > o.endIndex).sort((a, b) => a.startIndex - b.startIndex)[0];
+      if (following) out.push({ start: following.startIndex, end: following.endIndex });
+      const container = parsed.declaredNames.filter((d) => d.declarationStart <= o.startIndex && o.endIndex <= d.declarationEnd).sort((a, b) => a.declarationEnd - a.declarationStart - (b.declarationEnd - b.declarationStart))[0];
+      if (container) out.push({ start: container.declarationStart, end: container.declarationEnd });
+      continue;
+    }
+    const body = parsed.bodyRanges.filter((b) => b.startIndex <= o.startIndex && o.endIndex <= b.endIndex).sort((a, b) => b.endIndex - b.startIndex - (a.endIndex - a.startIndex))[0];
+    if (!body) continue;
+    if (body.startIndex <= declStart && declStart <= body.endIndex) continue;
+    if (MEMBER_NAME_PARENT_TYPES.has(o.parentType) && !DECLARATION_WRAPPER_BODY_TYPES.has(body.nodeType)) continue;
+    out.push({ start: body.startIndex, end: body.endIndex });
+  }
+  return out;
+}
+var DECLARATION_WRAPPER_BODY_TYPES = /* @__PURE__ */ new Set([
+  "class_body",
+  "interface_body",
+  "enum_body",
+  "object_body",
+  "impl_body",
+  "trait_body",
+  "type_body",
+  "class_definition",
+  "declaration_list",
+  // C# class/interface/enum body
+  "field_declaration_list",
+  // Rust struct / Go struct body
+  "enum_variant_list"
+  // Rust enum body
+]);
+function insideStatementBody(parsed, declared) {
+  return parsed.bodyRanges.some(
+    (b) => !DECLARATION_WRAPPER_BODY_TYPES.has(b.nodeType) && b.startIndex <= declared.declarationStart && declared.declarationEnd <= b.endIndex
+  );
+}
+function declaresSymbolAtTopLevel(parsed, symbolName) {
+  return parsed.declaredNames.some((d) => d.text === symbolName && !insideStatementBody(parsed, d));
+}
+function legacySelfDeclarationPattern(symbolName) {
+  const escaped = symbolName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(
+    `(?:function|class|interface|type|enum|struct|impl|def|fn|func|method|const|let|var|val)\\s+${escaped}\\b|\\b(?:public|private|protected|internal|static|abstract|override|readonly|final|sealed|export|declare|async)\\s+(?:async\\s+)?${escaped}\\b`
+  );
+}
+var METHOD_FRAGMENT_WRAPPED = (content) => `class __bb_fragment__ {
+${content}
+}
+`;
+async function contentDeclaresSymbol(filePath, content, symbolName, symbolType) {
+  let parsed;
+  try {
+    parsed = await parseForSafety(filePath, content);
+  } catch {
+    return false;
+  }
+  if (declaresSymbolAtTopLevel(parsed, symbolName)) return true;
+  if (parsed.declaredNames.length === 0 && legacySelfDeclarationPattern(symbolName).test(content)) return true;
+  const grammarSawTheName = parsed.declaredNames.some((d) => d.text === symbolName);
+  if (!grammarSawTheName && (parsed.hasSyntaxError || /method|constructor/i.test(symbolType ?? ""))) {
+    try {
+      const wrapped = await parseForSafety(filePath, METHOD_FRAGMENT_WRAPPED(content));
+      if (wrapped.declaredNames.some(
+        (d) => d.text === symbolName && /function|method/i.test(d.declarationType) && !insideStatementBody(wrapped, d)
+      )) {
+        return true;
+      }
+    } catch {
+    }
+  }
+  return false;
+}
+function declarationRangeOf(parsed, symbolName, spanStart, spanEnd) {
+  const hits = parsed.declaredNames.filter(
+    (d) => d.text === symbolName && d.startIndex >= spanStart && d.endIndex <= spanEnd
+  );
+  if (hits.length === 0) return null;
+  const decl = hits.reduce((a, b) => b.declarationStart < a.declarationStart ? b : a);
+  const start = Math.min(spanStart, decl.declarationStart);
+  const end = Math.max(spanEnd, decl.declarationEnd);
+  if (start === spanStart && end === spanEnd) return null;
+  if (parsed.content.slice(start, spanStart).includes("\n") || parsed.content.slice(spanEnd, end).includes("\n")) return null;
+  return { start, end };
+}
+var BATCH_ENTRY_MODES = ["write", "update", "insert", "delete", "refactor"];
+var BATCH_WIDE_OPTIONS = ["dryRun", "format", "edits", "files"];
+var MAX_BATCH_EDITS = 200;
+function expandBatchRequest(request) {
+  const specs = request.edits;
+  if (!Array.isArray(specs) || specs.length === 0) {
+    throw new Error("batch requires a non-empty `edits` array \u2014 one entry per edit, each with its own mode (write|update|insert|delete|refactor)");
+  }
+  const files = request.files;
+  if (files !== void 0) {
+    if (!Array.isArray(files) || files.length === 0) {
+      throw new Error("batch: `files` must be a non-empty array of project-relative paths \u2014 omit it to let each entry name its own filePath");
+    }
+    const seen = /* @__PURE__ */ new Map();
+    for (const [i, file] of files.entries()) {
+      if (typeof file !== "string" || file.trim() === "") throw new Error(`batch: files[${i}] must be a non-empty project-relative path`);
+      const prior = seen.get(file);
+      if (prior !== void 0) {
+        throw new Error(`batch: files[${i}] repeats ${file} (already listed as files[${prior}]) \u2014 \`files\` fans every entry out over the list, and two entries on one file would be planned from the same pre-edit bytes`);
+      }
+      seen.set(file, i);
+    }
+  }
+  const batch = [];
+  for (const [i, raw] of specs.entries()) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new Error(`batch entry ${i} must be an object carrying its own mode (write|update|insert|delete|refactor)`);
+    }
+    const spec = raw;
+    if (String(spec.mode) === "batch") {
+      throw new Error(`batch entry ${i} must not itself be a batch \u2014 the entries are the five single-file modes: ${BATCH_ENTRY_MODES.join(" | ")}`);
+    }
+    if (!BATCH_ENTRY_MODES.includes(String(spec.mode))) {
+      throw new Error(`batch entry ${i} requires a mode of ${BATCH_ENTRY_MODES.join("|")} (got ${JSON.stringify(spec.mode ?? null)}) \u2014 an entry with no mode would otherwise pass every per-mode check silently`);
+    }
+    const mode = spec.mode;
+    const wide = BATCH_WIDE_OPTIONS.filter((option) => spec[option] !== void 0);
+    if (wide.length > 0) {
+      throw new Error(`batch entry ${i} must not set ${wide.join(", ")} \u2014 ${wide.length === 1 ? "that option belongs" : "those options belong"} to the batch as a whole, because a batch previews, formats and reindexes ONCE; set ${wide.join(", ")} on the batch request itself`);
+    }
+    if (files !== void 0) {
+      if (typeof spec.filePath === "string") {
+        throw new Error(`batch entry ${i} sets filePath (${spec.filePath}) and the batch sets \`files\` \u2014 \`files\` supplies the target of every entry, so an entry must not also name one`);
+      }
+      for (const file of files) batch.push({ entry: i, mode, request: { ...spec, filePath: file } });
+    } else {
+      batch.push({ entry: i, mode, request: { ...spec } });
+    }
+  }
+  if (batch.length > MAX_BATCH_EDITS) {
+    throw new Error(
+      `batch: ${batch.length} planned edits exceeds the limit of ${MAX_BATCH_EDITS} (${specs.length} entr${specs.length === 1 ? "y" : "ies"}${files ? ` \xD7 ${files.length} file(s)` : ""}) \u2014 split the batch, or lower the entry count and the fan-out list. The limit bounds one plan, one formatting pass, one validation pass and one reindex, which all hold every target at once.`
+    );
+  }
+  return batch;
+}
+function readPreImage(file, preImages, preImageBytes) {
+  if (!existsSync2(file)) {
+    preImages.set(file, null);
+    preImageBytes.set(file, null);
+    return { existed: false, text: "" };
+  }
+  const bytes = readFileSync2(file);
+  preImages.set(file, createHash("sha256").update(bytes).digest("hex"));
+  preImageBytes.set(file, bytes.length);
+  return { existed: true, text: bytes.toString("utf8") };
+}
+async function planEdit(projectPath, projectId, request) {
+  const preImages = /* @__PURE__ */ new Map();
+  const preImageBytes = /* @__PURE__ */ new Map();
+  const plan = await planEditInto(projectPath, projectId, request, preImages, preImageBytes);
+  return {
+    ...plan,
+    preImages: Object.fromEntries(preImages),
+    preImageBytes: Object.fromEntries(preImageBytes),
+    owners: Object.fromEntries(
+      plan.changes.map((change) => [change.path, { entry: 0, mode: request.mode }])
+    )
+  };
+}
+async function planBatch(projectPath, projectId, request) {
+  const entries = expandBatchRequest(request);
+  const preImages = /* @__PURE__ */ new Map();
+  const preImageBytes = /* @__PURE__ */ new Map();
+  const changes = [];
+  const warnings = [];
+  const owners = {};
+  const batchRows = /* @__PURE__ */ new Map();
+  let renamedFiles = 0;
+  let renamedSites = 0;
+  let sawSummary = false;
+  for (const { entry, mode, request: concrete } of entries) {
+    let planned;
+    try {
+      planned = await planEditInto(projectPath, projectId, concrete, preImages, preImageBytes);
+    } catch (e) {
+      const target = typeof concrete.filePath === "string" ? ` ${concrete.filePath}` : "";
+      throw new Error(`batch entry ${entry} (${mode}${target}): ${e?.message ?? String(e)}`);
+    }
+    for (const change of planned.changes) {
+      const prior = owners[change.path];
+      if (prior) {
+        throw new Error(
+          `bb_edit wrote nothing: batch entries ${prior.entry} and ${entry} both resolve to ${relativeTo(projectPath, change.path)} \u2014 each entry is planned from the file's pre-edit bytes, so applying both would discard one of them. Edit that file in one entry, or make a second bb_edit call after this one.`
+        );
+      }
+      owners[change.path] = { entry, mode };
+      changes.push(change);
+    }
+    for (const warning of planned.warnings) warnings.push(`batch entry ${entry}: ${warning}`);
+    if (planned.summary) {
+      sawSummary = true;
+      renamedFiles += planned.summary.renamedFiles;
+      renamedSites += planned.summary.renamedSites;
+    }
+    const row = batchRows.get(entry) ?? { entry, mode, files: [] };
+    row.files.push(...planned.changes.map((change) => relativeTo(projectPath, change.path)));
+    if (planned.importPruning) row.importPruning = planned.importPruning;
+    batchRows.set(entry, row);
+  }
+  return {
+    changes,
+    warnings,
+    summary: sawSummary ? { renamedFiles, renamedSites } : void 0,
+    preImages: Object.fromEntries(preImages),
+    preImageBytes: Object.fromEntries(preImageBytes),
+    owners,
+    batch: [...batchRows.values()]
+  };
+}
+async function planEditInto(projectPath, projectId, request, preImages, preImageBytes) {
+  const warnings = [];
+  if (request.mode === "write") {
+    if (!request.filePath) throw new Error("write requires filePath");
+    const target = resolveSafeEditPath(projectPath, request.filePath);
+    const pre = readPreImage(target, preImages, preImageBytes);
+    const after = String(request.content ?? request.newContent ?? "");
+    const refusal = writeGuardMessage(relativeTo(projectPath, target), { existed: pre.existed, before: pre.text, after }, request.overwrite);
+    if (refusal) throw new Error(refusal);
+    return { changes: [{ path: target, before: pre.text, after }], warnings };
+  }
+  const symbolName = request.mode === "insert" ? request.targetSymbolName : request.symbolName;
+  if (!symbolName) throw new Error(`${request.mode} requires ${request.mode === "insert" ? "targetSymbolName" : "symbolName"}`);
+  const match = await uniqueSymbol(projectId, symbolName, request.filePath, request.lineStart, request.allowStaleIndex === true, projectPath, warnings);
+  resolveSafeEditPath(projectPath, match.fileId);
+  const original = readPreImage(match.fileId, preImages, preImageBytes).text;
+  let originalParse;
+  const parsedOriginal = async () => {
+    if (originalParse === void 0) {
+      try {
+        originalParse = await parseForSafety(match.fileId, original);
+      } catch {
+        originalParse = null;
+      }
+    }
+    return originalParse;
+  };
+  const declaredRange = async () => {
+    const parsed = await parsedOriginal();
+    if (!parsed) return null;
+    return declarationRangeOf(parsed, symbolName, match.byteStart, match.byteEnd);
+  };
+  if (request.mode === "update") {
+    const newContent = String(request.newContent ?? request.content ?? "");
+    if (await contentDeclaresSymbol(match.fileId, newContent, symbolName, match.symbolType)) {
+      const range = await declaredRange() ?? { start: match.byteStart, end: match.byteEnd };
+      return { changes: [{ path: match.fileId, before: original, after: replaceRange(original, range.start, range.end, withNewline(newContent, dominantNewline(original))) }], warnings };
+    }
+    const parsed = await parsedOriginal();
+    if (!parsed) throw new Error(`update ${symbolName}: cannot parse ${path2.basename(match.fileId)} to locate a body block`);
+    const body = findSymbolBody(parsed, match.byteStart, match.byteEnd);
+    if (body && original[body.startIndex] === "{") {
+      const open = body.startIndex;
+      const close = body.endIndex - 1;
+      const inner = original.slice(open + 1, close);
+      const innerIndent = inner.includes("\n") ? computeInnerIndent(original, body) : lineLeadingWhitespace(original, open) + indentUnit(original);
+      const nl = dominantNewline(original);
+      const spliced = withNewline("\n" + indentLines(newContent, innerIndent, true) + "\n" + lineLeadingWhitespace(original, open), nl);
+      const after = replaceRange(original, open + 1, close, spliced);
+      return { changes: [{ path: match.fileId, before: original, after }], warnings };
+    }
+    throw new Error(`update ${symbolName}: newContent does not declare the symbol and no replaceable body block was found; pass the full declaration to replace it`);
+  }
+  if (request.mode === "insert") {
+    const position = request.position ?? "after";
+    const content = String(request.newContent ?? request.content ?? "");
+    let start = position === "before" ? match.byteStart : match.byteEnd;
+    let end = start;
+    let replacement = `
+${content}
+`;
+    if (position === "before" || position === "after") {
+      const anchor = await declaredRange() ?? { start: match.byteStart, end: match.byteEnd };
+      start = end = position === "before" ? anchor.start : anchor.end;
+    }
+    if (position === "inside-top" || position === "inside-bottom") {
+      const parsed = await parsedOriginal();
+      if (!parsed) throw new Error(`cannot insert inside ${symbolName}: ${path2.basename(match.fileId)} could not be parsed`);
+      const body = findSymbolBody(parsed, match.byteStart, match.byteEnd);
+      if (!body) throw new Error(`cannot insert inside ${symbolName}: no recognizable body block (unsupported language or syntax)`);
+      if (original[body.startIndex] === "{") {
+        const open = body.startIndex;
+        const close = body.endIndex - 1;
+        const inner = original.slice(open + 1, close);
+        const isMultiLine = inner.includes("\n");
+        const braceLineIndent = lineLeadingWhitespace(original, open);
+        const innerIndent = isMultiLine ? computeInnerIndent(original, body) : braceLineIndent + indentUnit(original);
+        if (isMultiLine) {
+          if (position === "inside-top") {
+            start = end = open + 1;
+            replacement = "\n" + indentLines(content, innerIndent, true);
+          } else {
+            start = end = close;
+            replacement = indentLines(content, innerIndent, true) + "\n";
+          }
+        } else if (inner.trim() === "") {
+          start = end = open + 1;
+          replacement = "\n" + indentLines(content, innerIndent, true) + "\n" + braceLineIndent;
+        } else {
+          const stmt = inner.trim();
+          const contentLines = indentLines(content, innerIndent, true);
+          start = open + 1;
+          end = close;
+          replacement = position === "inside-top" ? "\n" + contentLines + "\n" + innerIndent + stmt + "\n" + braceLineIndent : "\n" + innerIndent + stmt + "\n" + contentLines + "\n" + braceLineIndent;
+        }
+      } else {
+        const indent = lineIndent(original, body.startIndex);
+        if (!/^[\t ]*$/.test(indent)) {
+          throw new Error(`cannot insert inside ${symbolName}: body is not line-aligned (unsupported body form such as Elixir do/end)`);
+        }
+        if (position === "inside-top") {
+          start = end = body.startIndex;
+          replacement = indentLines(content, indent, false) + "\n" + indent;
+        } else {
+          start = end = body.endIndex;
+          replacement = "\n" + indentLines(content, indent, true);
+        }
+      }
+    }
+    const nl = dominantNewline(original);
+    const after = withNewline(replaceRange(original, start, end, replacement), nl);
+    return { changes: [{ path: match.fileId, before: original, after }], warnings };
+  }
+  if (request.mode === "delete") {
+    const raw2 = await BrainDatabase.getRawInstance(projectId);
+    const callers = raw2.prepare("SELECT COUNT(*) c FROM brain_relationship WHERE target_symbol_id=? AND relationship_type IN ('calls','instantiates','references','uses')").get(match.id)?.c ?? 0;
+    const removal = await declaredRange() ?? { start: match.byteStart, end: match.byteEnd };
+    const deleted = replaceRange(original, removal.start, removal.end, "");
+    const parsedAfter = await parseForSafety(match.fileId, deleted);
+    const leftovers = parsedAfter.occurrences.filter((o) => o.text === symbolName && isReferenceSite(o, "")).map((o) => `line ${o.startLine}: ${o.parentType || "reference"}`);
+    const declRelPath2 = projectRelativePath(raw2, projectId, match.fileId, projectPath);
+    const importerRows = declRelPath2 === null ? [] : raw2.prepare(
+      // The LIKE is a PREFILTER on the specifier's last segment, nothing more.
+      // It bounds the candidate set without deciding anything: the decision is
+      // made by resolveImportToFile below, which walks the real path.
+      "SELECT DISTINCT i.file_id AS fileId, f.path AS path, f.relative_path AS relPath, i.import_path AS spec FROM brain_import i JOIN brain_file f ON f.id = i.file_id WHERE i.project_id = ? AND i.is_external = 0 AND i.file_id <> ? AND i.import_path IS NOT NULL AND (i.import_path = ? OR i.import_path LIKE ? OR i.import_path LIKE ?)"
+    ).all(
+      projectId,
+      match.fileId,
+      basenameNoExt(match.fileId),
+      `%/${basenameNoExt(match.fileId)}`,
+      `./${basenameNoExt(match.fileId)}`
+    );
+    const parsedByFile = /* @__PURE__ */ new Map();
+    const importerLeftovers = [];
+    for (const importer of importerRows) {
+      if (!resolveImportToFile(importer.relPath, importer.spec, declRelPath2)) continue;
+      let parsed = parsedByFile.get(importer.fileId);
+      if (parsed === void 0) {
+        try {
+          parsed = await parseForSafety(importer.path, readFileSync2(importer.path, "utf8"));
+        } catch {
+          parsed = null;
+        }
+        parsedByFile.set(importer.fileId, parsed);
+      }
+      if (!parsed) continue;
+      for (const o of parsed.occurrences) {
+        if (o.text !== symbolName) continue;
+        if (!IMPORT_SPECIFIER_PARENTS.has(o.parentType)) continue;
+        importerLeftovers.push(`${relativeTo(projectPath, importer.path)}:${o.startLine} (${o.parentType})`);
+      }
+    }
+    const indexedCallers = callers > 0 ? `${callers} indexed caller(s)` : null;
+    const totalLeftovers = leftovers.length + importerLeftovers.length;
+    if ((callers > 0 || totalLeftovers > 0) && request.force !== true) {
+      const parts = [
+        indexedCallers,
+        // The phrase "surviving deletion" is kept because script/m13/verify-edit-unit
+        // asserts on it, and a gate that greps for it is checking that the
+        // refusal SAYS what survives — which is right. The WHERE is new
+        // information layered on top, not a replacement: the declaring file and
+        // the importing files are different risks and the message distinguishes
+        // them.
+        leftovers.length > 0 ? `${leftovers.length} live reference(s) surviving deletion in the declaring file (${leftovers.slice(0, 5).join(", ")}${leftovers.length > 5 ? ", \u2026" : ""})` : null,
+        importerLeftovers.length > 0 ? `${importerLeftovers.length} reference(s) surviving deletion in importing file(s) \u2014 ${[...new Set(importerLeftovers.map((l) => l.split(":")[0]))].slice(0, 4).join(", ")}` : null
+      ].filter(Boolean).join("; ");
+      throw new Error(`cannot delete ${symbolName}: ${parts}; pass force=true after reviewing impact`);
+    }
+    if (totalLeftovers > 0) {
+      const where = [...leftovers.map((l) => `${path2.basename(match.fileId)} ${l}`), ...importerLeftovers];
+      warnings.push(`delete ${symbolName} (forced): ${totalLeftovers} reference(s) remain \u2014 ${where.slice(0, 10).join("; ")}${where.length > 10 ? "; \u2026" : ""}`);
+    }
+    if (request.force === true && callers > 0) {
+      warnings.push(`delete ${symbolName} (forced): ${callers} indexed caller(s) were bypassed by force=true \u2014 the index still records them; review with bb_graph or bb_impact before relying on this deletion`);
+    }
+    const pruneReport = await ImportPruner.pruneWithReport(deleted, match.fileId);
+    const prunedContent = pruneReport.content ?? deleted;
+    if (pruneReport.removedBindings.length > 0) {
+      warnings.push(`delete ${symbolName}: removed ${pruneReport.removedBindings.length} import binding(s) the deletion made dead \u2014 ${pruneReport.removedBindings.join(", ")}`);
+    }
+    if (!pruneReport.attempted && pruneReport.reason) {
+      warnings.push(`delete ${symbolName}: import cleanup was not attempted \u2014 ${pruneReport.reason}`);
+    }
+    const importPruning = pruneReport.attempted ? { attempted: true, language: pruneReport.language, removedBindings: pruneReport.removedBindings } : { attempted: false, language: pruneReport.language, removedBindings: [], reason: pruneReport.reason };
+    return { changes: [{ path: match.fileId, before: original, after: prunedContent }], warnings, importPruning };
+  }
+  const newName = String(request.newName ?? "");
+  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(newName)) throw new Error("refactor requires a valid identifier newName");
+  if (newName === symbolName) {
+    throw new Error(`refactor ${symbolName} \u2192 ${newName}: the new name is the current name; a rename must change the identifier. No change was made.`);
+  }
+  const raw = await BrainDatabase.getRawInstance(projectId);
+  const callerRows = raw.prepare(
+    "SELECT DISTINCT f.id AS fileId, f.path AS path, s.byte_start AS byteStart, s.byte_end AS byteEnd, r.relationship_type AS relType FROM brain_relationship r LEFT JOIN brain_symbol s ON s.id = r.source_symbol_id LEFT JOIN brain_file f ON f.id = s.file_id WHERE r.target_symbol_id = ? AND r.relationship_type IN ('calls','instantiates','references','uses')"
+  ).all(match.id);
+  const locatableCallerRows = callerRows.filter((r) => r.path != null && r.byteStart != null);
+  const sourcelessCallerRows = callerRows.filter((r) => r.path == null);
+  const declRelPath = projectRelativePath(raw, projectId, match.fileId, projectPath);
+  const importers = /* @__PURE__ */ new Map();
+  if (declRelPath !== null) {
+    const stem = basenameNoExt(match.fileId);
+    const importerRows = raw.prepare(
+      "SELECT i.file_id AS fileId, f.path AS path, f.relative_path AS relPath, i.imported_name AS importedName,        i.imported_as AS importedAs, i.import_path AS spec, i.line_number AS lineNumber FROM brain_import i JOIN brain_file f ON f.id = i.file_id WHERE i.project_id = ? AND i.is_external = 0 AND i.file_id <> ? AND i.import_path IS NOT NULL AND i.imported_name = ? AND (i.import_path = ? OR i.import_path LIKE ? OR i.import_path LIKE ?)"
+    ).all(projectId, match.fileId, symbolName, stem, `%/${stem}`, `./${stem}`);
+    for (const row of importerRows) {
+      if (!resolveImportToFile(row.relPath, row.spec, declRelPath)) continue;
+      const entry = importers.get(row.path) ?? { fileId: row.fileId, bindings: [] };
+      entry.bindings.push({
+        line: row.lineNumber ?? null,
+        aliased: row.importedAs != null && row.importedAs !== "" && row.importedAs !== symbolName
+      });
+      importers.set(row.path, entry);
+    }
+  }
+  const callerFileIds = [.../* @__PURE__ */ new Set([
+    ...locatableCallerRows.map((r) => r.fileId).filter((id) => id != null),
+    ...[...importers.values()].map((i) => i.fileId)
+  ])].filter((id) => id !== match.fileId);
+  if (callerFileIds.length > 0) assertFreshFiles(raw, callerFileIds, `refactor ${symbolName}`);
+  const fileRanges = /* @__PURE__ */ new Map();
+  const declEntry = fileRanges.get(match.fileId) ?? { callers: [] };
+  declEntry.declaration = { start: match.byteStart, end: match.byteEnd };
+  fileRanges.set(match.fileId, declEntry);
+  for (const row of locatableCallerRows) {
+    if (row.path == null || row.byteStart == null) continue;
+    const entry = fileRanges.get(row.path) ?? { callers: [] };
+    entry.callers.push({ start: row.byteStart, end: row.byteEnd ?? Number.MAX_SAFE_INTEGER, relType: row.relType || "" });
+    fileRanges.set(row.path, entry);
+  }
+  for (const [importerPath, importer] of importers) {
+    const entry = fileRanges.get(importerPath) ?? { callers: [] };
+    entry.imports = [...entry.imports ?? [], ...importer.bindings];
+    fileRanges.set(importerPath, entry);
+  }
+  const unrenamed = [];
+  const changes = [];
+  let renamedFiles = 0;
+  let renamedSites = 0;
+  let declarationRenamed = false;
+  for (const [file, ranges] of fileRanges) {
+    resolveSafeEditPath(projectPath, file);
+    const before = readPreImage(file, preImages, preImageBytes).text;
+    const parsed = await parseForSafety(file, before);
+    const sites = /* @__PURE__ */ new Set();
+    const declStart = ranges.declaration ? findDeclarationName(parsed.occurrences, symbolName, ranges.declaration.start, ranges.declaration.end) : void 0;
+    if (declStart != null) {
+      sites.add(declStart);
+      declarationRenamed = true;
+    }
+    const importAnchor = parsed.occurrences.find(
+      (o) => o.text === symbolName && IMPORT_SPECIFIER_PARENTS.has(o.parentType)
+    )?.startIndex;
+    const shadowScopes = collectShadowScopes(parsed, symbolName, declStart ?? importAnchor ?? 0);
+    const shadowedSites = /* @__PURE__ */ new Set();
+    const isShadowed = (start, end) => shadowScopes.some((s) => start >= s.start && end <= s.end);
+    if (ranges.declaration && declStart != null) {
+      for (const o of parsed.occurrences) {
+        if (o.text !== symbolName) continue;
+        if (!isReferenceSite(o, "")) continue;
+        if (isShadowed(o.startIndex, o.endIndex)) {
+          shadowedSites.add(o.startIndex);
+          continue;
+        }
+        sites.add(o.startIndex);
+      }
+    }
+    for (const span of ranges.callers) {
+      const spanEnd = span.end === Number.MAX_SAFE_INTEGER ? before.length : span.end;
+      if (span.start < 0 || span.start >= before.length || spanEnd < span.start || spanEnd > before.length) {
+        throw new Error(`refactor ${symbolName}: caller span out of bounds in ${file} (start=${span.start}, end=${span.end}, length=${before.length}); reindex before editing`);
+      }
+      for (const o of parsed.occurrences) {
+        if (o.text !== symbolName) continue;
+        if (o.startIndex < span.start || o.endIndex > spanEnd) continue;
+        if (!isReferenceSite(o, span.relType)) continue;
+        if (isShadowed(o.startIndex, o.endIndex)) {
+          shadowedSites.add(o.startIndex);
+          continue;
+        }
+        sites.add(o.startIndex);
+      }
+    }
+    if (ranges.imports?.length) {
+      const specifiers = parsed.occurrences.filter((o) => o.text === symbolName && IMPORT_SPECIFIER_PARENTS.has(o.parentType));
+      for (const binding of ranges.imports) {
+        const onLine = binding.line == null ? [] : specifiers.filter((o) => o.startLine === binding.line);
+        const chosen = onLine.length > 0 ? onLine : specifiers;
+        for (const o of chosen) sites.add(o.startIndex);
+      }
+      if (ranges.imports.some((b) => !b.aliased)) {
+        for (const o of parsed.occurrences) {
+          if (o.text !== symbolName) continue;
+          if (!isReferenceSite(o, "")) continue;
+          if (isShadowed(o.startIndex, o.endIndex)) {
+            shadowedSites.add(o.startIndex);
+            continue;
+          }
+          sites.add(o.startIndex);
+        }
+      }
+    }
+    const fileHasEvidence = ranges.declaration != null || (ranges.imports?.length ?? 0) > 0;
+    if (fileHasEvidence) {
+      for (const o of parsed.occurrences) {
+        if (o.text !== symbolName) continue;
+        if (sites.has(o.startIndex) || shadowedSites.has(o.startIndex)) continue;
+        if (!IMPORT_SPECIFIER_PARENTS.has(o.parentType) && !isReferenceSite(o, "")) continue;
+        unrenamed.push(`${relativeTo(projectPath, file)}:${o.startLine} (${o.parentType || "reference"})`);
+      }
+    }
+    if (sites.size === 0) continue;
+    let after = before;
+    for (const offset of [...sites].sort((a, b) => b - a)) after = replaceRange(after, offset, offset + symbolName.length, newName);
+    changes.push({ path: file, before, after });
+    renamedFiles++;
+    renamedSites += sites.size;
+  }
+  if (unrenamed.length > 0) {
+    throw new Error(`refactor ${symbolName} \u2192 ${newName}: ${unrenamed.length} reference(s) this rename found but could not rewrite \u2014 ${unrenamed.slice(0, 6).join(", ")}${unrenamed.length > 6 ? ", \u2026" : ""}; reindex the project or rename them manually`);
+  }
+  if (renamedSites === 0) {
+    throw new Error(`refactor ${symbolName} \u2192 ${newName}: resolved 0 rename site(s) in 0 file(s) \u2014 the symbol was located but nothing could be renamed (this grammar may expose no identifier node for it, as a YAML key or a Makefile target does not). No change was made.`);
+  }
+  const collisions = [];
+  for (const change of changes) {
+    const parsedAfter = await parseForSafety(change.path, change.after);
+    const topLevel = parsedAfter.declaredNames.filter((d) => d.text === newName && !insideStatementBody(parsedAfter, d));
+    const expected = change.path === match.fileId && declarationRenamed ? 1 : 0;
+    for (const extra of topLevel.slice(expected)) {
+      const line = parsedAfter.content.slice(0, extra.startIndex).split("\n").length;
+      collisions.push(`${relativeTo(projectPath, change.path)}:${line} (${extra.declarationType})`);
+    }
+  }
+  if (collisions.length > 0) {
+    throw new Error(`refactor ${symbolName} \u2192 ${newName}: the new name is already declared \u2014 ${collisions.slice(0, 6).join(", ")}${collisions.length > 6 ? ", \u2026" : ""}; renaming onto an existing declaration would leave two declarations with one name. No change was made.`);
+  }
+  if (request.mode === "refactor") {
+    warnings.push(`refactor ${symbolName} \u2192 ${newName}: ${renamedSites} site(s) across ${renamedFiles} file(s)`);
+    if (sourcelessCallerRows.length > 0) {
+      warnings.push(`refactor ${symbolName}: ${sourcelessCallerRows.length} cross-file edge(s) to this symbol have no source symbol in the index; ${importers.size} importing file(s) were covered through brain_import, and a call site in a file that does not import the declaration module is not reachable by this rename`);
+    }
+  }
+  return { changes, warnings, summary: request.mode === "refactor" ? { renamedFiles, renamedSites } : void 0 };
+}
+function plannedEnvelope(projectPath, plan) {
+  return {
+    atomic: true,
+    entries: plan.changes.map((change) => {
+      const owner = plan.owners[change.path] ?? { entry: 0, mode: "write" };
+      return {
+        path: relativeTo(projectPath, change.path),
+        entry: owner.entry,
+        mode: owner.mode,
+        planned: true,
+        committed: false,
+        restored: false,
+        bytesBefore: plan.preImageBytes[change.path] ?? null,
+        bytesAfter: null
+      };
+    }),
+    committed: 0,
+    restored: 0,
+    failed: []
+  };
+}
+function closeEnvelope(envelope, changes) {
+  envelope.committed = envelope.entries.filter((entry) => entry.committed).length;
+  envelope.restored = envelope.entries.filter((entry) => entry.restored).length;
+  for (const [i, entry] of envelope.entries.entries()) {
+    try {
+      entry.bytesAfter = statSync(changes[i].path).size;
+    } catch {
+      entry.bytesAfter = null;
+    }
+  }
+  return envelope;
+}
+async function commitPlan(projectPath, projectId, request, plan) {
+  const { changes, warnings, summary, preImages, batch } = plan;
+  const snapshots = new Map(changes.map((change) => [change.path, snapshotOf(change.path)]));
+  if (snapshots.size !== changes.length) {
+    const seen = /* @__PURE__ */ new Set();
+    const dupes = changes.filter((change) => seen.has(change.path) ? true : (seen.add(change.path), false)).map((change) => relativeTo(projectPath, change.path));
+    throw new Error(`bb_edit wrote nothing: two planned changes target the same file (${[...new Set(dupes)].join(", ")}) \u2014 a plan defect, not a request defect: each change is resolved against the file's pre-edit bytes, so only one of them could ever be applied.`);
+  }
+  const envelope = plannedEnvelope(projectPath, plan);
+  const envelopeByAbs = new Map(changes.map((change, i) => [change.path, envelope.entries[i]]));
+  const moved = preImageMismatches(
+    projectPath,
+    preImages,
+    new Map([...snapshots].map(([path0, snapshot]) => [path0, snapshot.hash]))
+  );
+  if (moved.length > 0) {
+    throw new Error(
+      `bb_edit wrote nothing: ${moved.length} target file(s) changed on disk between planning and committing \u2014 ${moved.join(", ")}. The edit was planned from those bytes, so applying it now would overwrite content it never read; re-run the edit to re-plan against the current file.`
+    );
+  }
+  const committed = [];
+  const temps = [];
+  try {
+    for (const change of changes) {
+      mkdirSync(path2.dirname(change.path), { recursive: true });
+      const temporary = `${change.path}.bb-edit-${randomUUID()}`;
+      temps.push(temporary);
+      writeFileSync2(temporary, change.after, "utf8");
+      const originalMode = snapshots.get(change.path).mode;
+      renameSync(temporary, change.path);
+      committed.push(change.path);
+      envelopeByAbs.get(change.path).committed = true;
+      if (originalMode !== null) {
+        try {
+          chmodSync(change.path, originalMode);
+        } catch {
+        }
+      }
+    }
+    const formatting = request.format === false ? void 0 : await Promise.all(changes.map(async (change) => {
+      const outcome = await BrainSurgicalPatcher.tryAutoFormat(change.path);
+      return { path: relativeTo(projectPath, change.path), ...outcome };
+    }));
+    for (const entry of formatting ?? []) {
+      if (entry.ran && !entry.ok) warnings.push(`format: ${entry.path}: ${entry.reason ?? "formatter failed"}`);
+    }
+    if (formatting) {
+      const absoluteByRel = new Map(changes.map((change) => [relativeTo(projectPath, change.path), change.path]));
+      for (const entry of formatting) {
+        if (!entry.ran || !entry.ok) continue;
+        const absolute = absoluteByRel.get(entry.path);
+        const preImage = absolute ? snapshots.get(absolute)?.bytes : null;
+        if (!absolute || !preImage) continue;
+        if (dominantNewline(preImage.toString("utf8")) !== "\r\n") continue;
+        const current = readFileSync2(absolute, "utf8");
+        if (!hasLoneLf(current)) continue;
+        writeFileSync2(absolute, withNewline(current, "\r\n"), "utf8");
+        entry.lineEndingRestored = true;
+      }
+    }
+    for (const change of changes) await validateFile(change.path, readFileSync2(change.path, "utf8"));
+    const reindexResult = await reindexFilesParallel(projectId, realpathSync(projectPath), changes.map((change) => ({ path: change.path, type: snapshots.get(change.path).existed ? "modified" : "added" })));
+    const reindexErrors = reindexResult.errors ?? 0;
+    const reindexed = reindexErrors === 0;
+    if (reindexErrors > 0) {
+      const named = (reindexResult.errorDetail ?? []).slice(0, 5).map((d) => `${relativeTo(projectPath, d.file)} (${d.error})`);
+      warnings.push(`reindex: ${reindexErrors} file(s) failed to reindex \u2014 the edit stands but the index is NOT current for them${named.length > 0 ? `: ${named.join("; ")}` : ""}; run bb index --changed`);
+    }
+    return {
+      mode: request.mode,
+      dryRun: false,
+      changes: changes.map((change) => ({ ...change, after: readFileSync2(change.path, "utf8") })),
+      formatted: formatting !== void 0 && formatting.length > 0 && formatting.every((entry) => entry.ok),
+      ...formatting !== void 0 ? { formatting } : {},
+      validated: true,
+      reindexed,
+      // visible derived-data outcome — never a silent deferral.
+      derived: reindexResult.derived ?? { pass: "deferred", phases: [], repairedInEdges: 0, touchedSymbols: 0 },
+      warnings: warnings.length > 0 ? warnings : void 0,
+      summary,
+      ...batch ? { batch } : {},
+      ...plan.importPruning ? { importPruning: plan.importPruning } : {},
+      envelope: closeEnvelope(envelope, changes)
+    };
+  } catch (error) {
+    const rollbackFailures = [];
+    for (const file of committed) {
+      const snapshot = snapshots.get(file);
+      try {
+        if (snapshot.existed) writeBytesPreservingMode(file, snapshot.bytes, snapshot.mode);
+        else rmSync(file, { force: true });
+        envelopeByAbs.get(file).restored = true;
+      } catch (e) {
+        rollbackFailures.push(`${file}: ${e?.message ?? String(e)}`);
+        envelope.failed.push({ path: relativeTo(projectPath, file), reason: e?.message ?? String(e) });
+      }
+    }
+    for (const t of temps) {
+      try {
+        rmSync(t, { force: true });
+      } catch {
+      }
+    }
+    if (rollbackFailures.length > 0) {
+      ;
+      error.rollbackFailures = rollbackFailures;
+      error.message = `${error.message} \u2014 ROLLBACK INCOMPLETE, these files were NOT restored: ${rollbackFailures.join("; ")}`;
+    }
+    ;
+    error.envelope = closeEnvelope(envelope, changes);
+    throw error;
+  }
+}
+async function executeEdit(projectPath, projectId, request) {
+  let plan;
+  try {
+    plan = request.mode === "batch" ? await planBatch(projectPath, projectId, request) : await planEdit(projectPath, projectId, request);
+  } catch (error) {
+    if (error && typeof error === "object" && error.envelope === void 0) {
+      error.envelope = { atomic: true, entries: [], committed: 0, restored: 0, failed: [] };
+      error.refusedBeforeWriting = true;
+    }
+    throw error;
+  }
+  if (request.dryRun === true) {
+    const { changes, warnings, summary, batch } = plan;
+    return {
+      mode: request.mode,
+      dryRun: true,
+      changes,
+      formatted: false,
+      validated: false,
+      reindexed: false,
+      warnings: warnings.length > 0 ? warnings : void 0,
+      summary,
+      ...batch ? { batch } : {},
+      ...plan.importPruning ? { importPruning: plan.importPruning } : {},
+      envelope: plannedEnvelope(projectPath, plan)
+    };
+  }
+  return commitPlan(projectPath, projectId, request, plan);
+}
+
+export {
+  resolveSafeEditPath,
+  fileHash,
+  preImageMismatches,
+  WRITE_GUARD,
+  lineCount,
+  writeGuardMessage,
+  isBindingParentType,
+  isReferenceSite,
+  findDeclarationName,
+  BATCH_ENTRY_MODES,
+  BATCH_WIDE_OPTIONS,
+  MAX_BATCH_EDITS,
+  expandBatchRequest,
+  executeEdit
+};