apply-edit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Ryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# apply-edit
+
+Apply the `oldString` → `newString` edits that language models produce, without guessing.
+
+Coding agents ask a model for the exact text to replace. Models drift: wrong indentation, tabs for spaces, a trailing space, CRLF versus LF, typographic quotes, literal `\n` sequences. Exact matching then fails, and fuzzy matching quietly edits the wrong place. This package sits between the two: it tolerates the drift that can be resolved unambiguously, refuses everything else with a precise report, and never widens or relocates an edit.
+
+Zero runtime dependencies. Strings in, strings out; no filesystem access. ESM, CommonJS and TypeScript declarations. Node 22+ and browsers.
+
+```sh
+npm install apply-edit
+```
+
+```js
+import {applyEdit} from 'apply-edit';
+
+const file = 'def example():\n    try:\n        result = process_data()\n        return result\n';
+const result = applyEdit(file, {
+  oldString: 'result = process_data()\nreturn result',      // the model dropped the indentation
+  newString: 'result = process_data()\nvalidate(result)\nreturn result',
+});
+
+result.ok;         // true
+result.strategy;   // 'indent-shift'  (not 'exact': tell the model, log it, or require exact in strict mode)
+result.reindented; // true            (newString was shifted to the file's indentation)
+result.matches;    // [{start: 27, end: 75, startLine: 3, endLine: 4}]
+result.text;       // the file with the block replaced at the right depth
+```
+
+When the edit cannot be applied safely, the result says why in terms the model can act on:
+
+```js
+applyEdit('foo\nbar\nfoo\n', {oldString: 'foo', newString: 'qux'});
+// {ok: false, code: 'ambiguous', candidates: [{startLine: 1, endLine: 1}, {startLine: 3, endLine: 3}], ...}
+
+applyEdit(file, {oldString: 'result = compute()\nreturn result', newString: '...'});
+// {ok: false, code: 'not-found', closest: {startLine: 3, endLine: 4, similarity: 0.83, preview: '3|         result = process_data()\n4|         return result', differences: [...]}, ...}
+```
+
+## What it does
+
+`applyEdit(text, edit, options?)` tries these strategies strictly in order and stops at the first that finds any candidate:
+
+| strategy | tolerates | scope |
+|---|---|---|
+| `exact` | nothing | substrings anywhere |
+| `trailing-whitespace` | trailing spaces and tabs per line | whole lines |
+| `indent-shift` | one constant indentation offset across the block, relative structure kept | whole lines |
+| `line-trimmed` | different indentation per line, tabs versus spaces | whole lines |
+| `whitespace-collapsed` | runs of internal whitespace | whole lines |
+| `unicode-normalized` | typographic quotes and dashes, non-breaking spaces, NFC | whole lines |
+| `escape-tolerant` / `unescaped:<strategy>` | literal `\n`, `\t`, `\"` sequences that stand for the real characters | as above |
+
+The rules that make it safe to use in a loop:
+
+- A strategy with more than one candidate refuses with `ambiguous` and the candidate lines. The search never falls through to a looser strategy. Pass `replaceAll`, `occurrence` (1-based, negative from the end) or a `line` hint to select deliberately.
+- Non-exact strategies match whole lines only, so a short fragment cannot fuzzily rewrite a larger region.
+- There is no similarity threshold. Near misses are reported in `closest` (line-numbered preview and first differences), never applied.
+- When a non-exact strategy located the block, `newString` is re-indented line by line to the matched region, including tab/space conversion. `reindented` says whether that happened.
+- The text's byte order mark and dominant line-ending style are preserved; `oldString` and `newString` may use either style. Mixed-EOL input produces a warning.
+- Every success reports `strategy`, `matches` (offsets and lines in the original text) and `warnings`, so a non-exact match can be surfaced to the model or rejected by strict callers.
+
+`applyEdits(text, edits)` resolves every edit against the original text, refuses overlapping edits, and applies all of them or none. `findEdit(text, oldString)` locates without changing anything.
+
+## API
+
+### `applyEdit(text, edit, options?)`
+
+`edit`: `{oldString, newString, replaceAll?, occurrence?, line?}`.
+
+`options`: `{tolerance?: 'exact' | 'whitespace' | 'unicode', unescape?: boolean, diagnostics?: boolean}`. `tolerance` caps the loosest strategy (`'unicode'` is the default and includes everything above). `unescape: false` disables the escape-sequence strategies. `diagnostics: false` skips the closest-region search on `not-found`.
+
+Returns `{ok: true, text, strategy, replaced, matches, reindented, warnings, lineEnding, bom}` or `{ok: false, code, message, ...}` with `code` one of `empty-old`, `no-change`, `not-found` (with `closest` when a plausible region exists), `ambiguous` (with `candidates` and `strategy`), `occurrence-out-of-range`. Invalid argument types throw `TypeError`; `occurrence: 0` throws `RangeError`.
+
+### `applyEdits(text, edits, options?)`
+
+Returns `{ok: true, text, applied, lineEnding, bom}` or the first failure with its `index`. Overlapping edits fail with `code: 'overlap'`.
+
+### `findEdit(text, oldString, options?)`
+
+Returns `{ok: true, strategy, matches, lineEnding, bom}` or a failure.
+
+## Limits
+
+- Escaped-sequence recovery is heuristic when the code itself contains literal backslash sequences; ambiguous inputs are refused rather than guessed.
+- Re-indentation maps replacement lines to matched lines by trimmed content and follows the previous anchor for new lines. Blocks that mix tabs and spaces within one line may keep the model's indentation; `reindented` and the diff tell you.
+- Matching is line-oriented above the exact tier. Reordered or paraphrased lines are misses, reported through `closest`.
+- This library does not read or write files, lock, or check that a file changed since it was read. Keep those in the tool.
+- Unified diffs, SEARCH/REPLACE block parsing and model-assisted correction are out of scope.
+
+## Why not the usual fallback ladder
+
+On a seeded corpus of 1,942 constructed edits over 12 real source files (drifted indentation, tabs, trailing whitespace, CRLF, typographic punctuation, escaped newlines, plus decoys, duplicates, stale blocks and non-contiguous input), this implementation applied 1,286 edits with the expected output and made 0 wrong-location or false applications. A transcription of a widely copied nine-replacer fallback ladder applied 116 edits wrongly (mostly stale blocks silently overwritten) and produced 302 outputs with the model's wrong indentation inserted verbatim; the closest published library made 144 to 333 wrong applications depending on its fuzz setting. Method and numbers are in [docs/comparison.md](docs/comparison.md). The corpus is synthetic and seeded, built from real files; it is not a sample of model output.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,481 @@
+'use strict';
+const BOM = '\uFEFF';
+const PUNCTUATION = new Map([
+  ['\u2010', '-'], ['\u2011', '-'], ['\u2012', '-'], ['\u2013', '-'], ['\u2014', '-'], ['\u2015', '-'], ['\u2212', '-'],
+  ['\u2018', "'"], ['\u2019', "'"], ['\u201A', "'"], ['\u201B', "'"],
+  ['\u201C', '"'], ['\u201D', '"'], ['\u201E', '"'], ['\u201F', '"'],
+  ['\u00A0', ' '], ['\u2002', ' '], ['\u2003', ' '], ['\u2004', ' '], ['\u2005', ' '], ['\u2006', ' '], ['\u2007', ' '],
+  ['\u2008', ' '], ['\u2009', ' '], ['\u200A', ' '], ['\u202F', ' '], ['\u205F', ' '], ['\u3000', ' '],
+]);
+const PUNCTUATION_PATTERN = /[\u2010-\u2015\u2212\u2018-\u201F\u00A0\u2002-\u200A\u202F\u205F\u3000]/g;
+const ESCAPE_PATTERN = /\\(n|t|r|"|'|`|\\)/g;
+const ESCAPES = {n: '\n', t: '\t', r: '\r', '"': '"', "'": "'", '`': '`', '\\': '\\'};
+const ESCAPE_ALTERNATIVES = {
+  '\\n': '(?:\\n[ \\t]*|\\\\n)', '\\t': '(?:\\t|\\\\t)', '\\r': '(?:\\r|\\\\r)',
+  '\\"': '(?:"|\\\\")', "\\'": "(?:'|\\\\')", '\\`': '(?:`|\\\\`)', '\\\\': '(?:\\\\|\\\\\\\\)',
+};
+const TOLERANCE_TIERS = {exact: 0, whitespace: 4, unicode: 5};
+
+const stripTrailing = line => line.replace(/[ \t\f\v]+$/, '');
+const trimLine = line => line.trim();
+const collapseWhitespace = line => line.replace(/\s+/g, ' ').trim();
+const normalizeUnicode = line => collapseWhitespace(line.normalize('NFC').replace(PUNCTUATION_PATTERN, c => PUNCTUATION.get(c) ?? c));
+const indentOf = line => /^[ \t]*/.exec(line)[0];
+const isBlank = line => line.trim() === '';
+const escapeRegExp = s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const TIERS = [
+  {name: 'exact'},
+  {name: 'trailing-whitespace', key: 'trailing', normalize: stripTrailing},
+  {name: 'indent-shift', key: 'indent-shift'},
+  {name: 'line-trimmed', key: 'trimmed', normalize: trimLine},
+  {name: 'whitespace-collapsed', key: 'collapsed', normalize: collapseWhitespace},
+  {name: 'unicode-normalized', key: 'unicode', normalize: normalizeUnicode},
+];
+
+function splitBom(text) {
+  return text.startsWith(BOM) ? {bom: BOM, body: text.slice(1)} : {bom: '', body: text};
+}
+
+// Normalizes CRLF and lone CR to LF while recording where each normalized index came from.
+function normalizeLineEndings(body) {
+  if (!body.includes('\r')) return {normalized: body, toRaw: null, crlf: 0, lf: countChar(body, '\n'), cr: 0};
+  let normalized = '';
+  let crlf = 0;
+  let lf = 0;
+  let cr = 0;
+  const toRaw = [];
+  let segmentStart = 0;
+  for (let i = 0; i < body.length; i++) {
+    if (body[i] !== '\r') {
+      if (body[i] === '\n') lf++;
+      continue;
+    }
+    const segment = body.slice(segmentStart, i);
+    for (let j = 0; j < segment.length; j++) toRaw.push(segmentStart + j);
+    normalized += segment + '\n';
+    toRaw.push(i);
+    if (body[i + 1] === '\n') {
+      crlf++;
+      i++;
+    } else {
+      cr++;
+    }
+    segmentStart = i + 1;
+  }
+  const tail = body.slice(segmentStart);
+  for (let j = 0; j < tail.length; j++) toRaw.push(segmentStart + j);
+  normalized += tail;
+  toRaw.push(body.length);
+  return {normalized, toRaw, crlf, lf, cr};
+}
+
+function countChar(text, char) {
+  let count = 0;
+  for (let i = text.indexOf(char); i !== -1; i = text.indexOf(char, i + 1)) count++;
+  return count;
+}
+
+// Line table built on first use; exact matches never need it.
+function createLineTable(normalized) {
+  let built = null;
+  const build = () => {
+    if (built) return built;
+    const lines = normalized.split('\n');
+    const starts = new Array(lines.length);
+    let offset = 0;
+    for (let i = 0; i < lines.length; i++) {
+      starts[i] = offset;
+      offset += lines[i].length + 1;
+    }
+    built = {lines, starts, cache: new Map()};
+    return built;
+  };
+  return {
+    get lines() { return build().lines; },
+    get starts() { return build().starts; },
+    normalized(key, fn) {
+      const table = build();
+      if (!table.cache.has(key)) table.cache.set(key, table.lines.map(fn));
+      return table.cache.get(key);
+    },
+  };
+}
+
+function exactSpans(text, needle) {
+  const spans = [];
+  for (let index = text.indexOf(needle); index !== -1; index = text.indexOf(needle, index + needle.length)) {
+    spans.push({start: index, end: index + needle.length});
+  }
+  return spans;
+}
+
+function addLineNumbers(normalized, spans) {
+  let line = 0;
+  let position = 0;
+  for (const span of spans) {
+    for (let i = normalized.indexOf('\n', position); i !== -1 && i < span.start; i = normalized.indexOf('\n', i + 1)) line++;
+    position = span.start;
+    span.startLine = line;
+    let endLine = line;
+    for (let i = normalized.indexOf('\n', span.start); i !== -1 && i < span.end - 1; i = normalized.indexOf('\n', i + 1)) endLine++;
+    span.endLine = endLine;
+  }
+  return spans;
+}
+
+function windowSpan(table, normalized, start, count, trailingNewline) {
+  const {lines, starts} = table;
+  const last = start + count - 1;
+  let end = starts[last] + lines[last].length;
+  if (trailingNewline && end < normalized.length && normalized[end] === '\n') end++;
+  return {start: starts[start], end, startLine: start, endLine: last};
+}
+
+// Whole-line window matching with a per-line normalizer.
+function lineSpans(table, normalized, oldLines, trailingNewline, key, normalize) {
+  const count = oldLines.length;
+  const lines = table.lines;
+  const spans = [];
+  if (count === 0 || count > lines.length) return spans;
+  const wanted = oldLines.map(normalize);
+  if (!wanted.some(Boolean)) return spans;
+  const source = table.normalized(key, normalize);
+  for (let i = 0; i + count <= lines.length; i++) {
+    if (source[i] !== wanted[0]) continue;
+    let matched = true;
+    for (let j = 1; j < count; j++) {
+      if (source[i + j] !== wanted[j]) { matched = false; break; }
+    }
+    if (matched) spans.push(windowSpan(table, normalized, i, count, trailingNewline));
+  }
+  return spans;
+}
+
+// Lines match after trimming and every non-blank line shares one indentation delta, so relative structure is preserved.
+function indentShiftSpans(table, normalized, oldLines, trailingNewline) {
+  const count = oldLines.length;
+  const lines = table.lines;
+  const spans = [];
+  if (count === 0 || count > lines.length) return spans;
+  const wantedText = oldLines.map(trimLine);
+  const wantedIndent = oldLines.map(indentOf);
+  const firstContent = wantedText.findIndex(Boolean);
+  if (firstContent === -1) return spans;
+  const text = table.normalized('trimmed', trimLine);
+  const indents = table.normalized('indent', indentOf);
+  for (let i = 0; i + count <= lines.length; i++) {
+    if (text[i + firstContent] !== wantedText[firstContent]) continue;
+    let matched = true;
+    let sign = null;
+    let delta = '';
+    for (let j = 0; j < count; j++) {
+      if (text[i + j] !== wantedText[j]) { matched = false; break; }
+      if (!wantedText[j]) continue;
+      const actual = indents[i + j];
+      const expected = wantedIndent[j];
+      if (sign === null) {
+        if (actual.startsWith(expected)) { sign = '+'; delta = actual.slice(expected.length); }
+        else if (expected.startsWith(actual)) { sign = '-'; delta = expected.slice(actual.length); }
+        else { matched = false; break; }
+      } else if (sign === '+' ? actual !== delta + expected : expected !== delta + actual) {
+        matched = false;
+        break;
+      }
+    }
+    if (matched) spans.push(windowSpan(table, normalized, i, count, trailingNewline));
+  }
+  return spans;
+}
+
+// A literal escape sequence in the search text may stand for the real character or for the same literal in the file.
+function escapeTolerantSpans(normalized, oldString) {
+  const parts = oldString.split(/(\\[ntr"'`\\])/);
+  if (parts.length < 3) return [];
+  const source = parts.map((part, i) => (i % 2 ? ESCAPE_ALTERNATIVES[part] : escapeRegExp(part))).join('');
+  const pattern = new RegExp(source, 'g');
+  const spans = [];
+  for (let match = pattern.exec(normalized); match; match = pattern.exec(normalized)) {
+    if (match[0].length === 0) { pattern.lastIndex++; continue; }
+    spans.push({start: match.index, end: match.index + match[0].length});
+  }
+  return spans;
+}
+
+function locate(normalized, table, oldString, options) {
+  const maxTier = TOLERANCE_TIERS[options.tolerance ?? 'unicode'];
+  if (maxTier === undefined) throw new TypeError(`Unknown tolerance: ${options.tolerance}`);
+  const attempts = [{prefix: '', text: oldString}];
+  const escaped = options.unescape !== false && ESCAPE_PATTERN.test(oldString);
+  ESCAPE_PATTERN.lastIndex = 0;
+  if (escaped) attempts.push({prefix: 'unescaped:', text: oldString.replace(ESCAPE_PATTERN, (m, c) => ESCAPES[c])});
+  for (const attempt of attempts) {
+    if (attempt.prefix) {
+      const spans = escapeTolerantSpans(normalized, oldString);
+      if (spans.length) return {strategy: 'escape-tolerant', spans: addLineNumbers(normalized, spans), oldLines: null};
+    }
+    const trailingNewline = attempt.text.endsWith('\n');
+    const oldLines = (trailingNewline ? attempt.text.slice(0, -1) : attempt.text).split('\n');
+    const whitespaceOnly = attempt.text.trim() === '';
+    for (let t = 0; t <= maxTier; t++) {
+      const tier = TIERS[t];
+      let spans;
+      if (tier.name === 'exact') spans = addLineNumbers(normalized, exactSpans(normalized, attempt.text));
+      else if (whitespaceOnly) break;
+      else if (tier.name === 'indent-shift') spans = indentShiftSpans(table, normalized, oldLines, trailingNewline);
+      else spans = lineSpans(table, normalized, oldLines, trailingNewline, tier.key, tier.normalize);
+      if (spans.length) return {strategy: attempt.prefix + tier.name, spans, oldLines: tier.name === 'exact' ? null : oldLines};
+    }
+  }
+  return null;
+}
+
+function bigrams(text) {
+  const map = new Map();
+  for (let i = 0; i + 1 < text.length; i++) {
+    const key = text.slice(i, i + 2);
+    map.set(key, (map.get(key) ?? 0) + 1);
+  }
+  return map;
+}
+
+function dice(a, b) {
+  if (a.length < 2 || b.length < 2) return a === b ? 1 : 0;
+  const left = bigrams(a);
+  const right = bigrams(b);
+  let shared = 0;
+  for (const [key, count] of left) shared += Math.min(count, right.get(key) ?? 0);
+  return (2 * shared) / (a.length - 1 + b.length - 1);
+}
+
+// Best window of the same height: most equal trimmed lines first, bigram similarity as the tie-breaker.
+function nearestRegion(table, oldLines, limit) {
+  const lines = table.lines;
+  const count = oldLines.length;
+  if (count === 0 || lines.length === 0 || count > lines.length) return null;
+  const trimmed = table.normalized('trimmed', trimLine);
+  const wanted = oldLines.map(trimLine);
+  const content = wanted.map(Boolean);
+  const scanned = Math.min(lines.length, limit);
+  const scored = [];
+  for (let i = 0; i + count <= scanned; i++) {
+    let equal = 0;
+    for (let j = 0; j < count; j++) if (content[j] && trimmed[i + j] === wanted[j]) equal++;
+    if (equal > 0) scored.push([equal, i]);
+  }
+  let candidates;
+  if (scored.length) {
+    scored.sort((a, b) => b[0] - a[0]);
+    candidates = scored.slice(0, 25).map(entry => entry[1]);
+  } else if (count <= 3) {
+    candidates = Array.from({length: Math.max(0, Math.min(scanned, 20000) - count + 1)}, (_, i) => i);
+  } else {
+    return null;
+  }
+  const target = wanted.join('\n');
+  let best = null;
+  for (const i of candidates) {
+    const similarity = dice(trimmed.slice(i, i + count).join('\n'), target);
+    if (!best || similarity > best.similarity) best = {startLine: i, endLine: i + count - 1, similarity};
+  }
+  if (!best || best.similarity < 0.3) return null;
+  const differences = [];
+  for (let j = 0; j < count && differences.length < 5; j++) {
+    const actual = lines[best.startLine + j];
+    if (actual !== oldLines[j]) differences.push({line: best.startLine + j + 1, expected: oldLines[j], actual});
+  }
+  return {
+    startLine: best.startLine + 1,
+    endLine: best.endLine + 1,
+    similarity: Math.round(best.similarity * 1000) / 1000,
+    preview: lines.slice(best.startLine, best.endLine + 1).map((line, j) => `${best.startLine + j + 1}| ${line}`).join('\n'),
+    differences,
+  };
+}
+
+function indentUnit(lines) {
+  let tabs = 0;
+  let spaces = 0;
+  let step = 0;
+  for (const line of lines) {
+    const indent = indentOf(line);
+    if (indent.startsWith('\t')) tabs++;
+    else if (indent.length) { spaces++; if (!step || indent.length < step) step = indent.length; }
+  }
+  return tabs > spaces ? {unit: '\t', width: 1} : {unit: ' ', width: step || 2};
+}
+
+function convertIndent(indent, from, to) {
+  if (!indent) return '';
+  const units = from.unit === '\t'
+    ? countChar(indent, '\t') + Math.floor(countChar(indent, ' ') / from.width)
+    : Math.round(indent.replace(/\t/g, ' '.repeat(from.width)).length / from.width);
+  return to.unit.repeat(Math.max(0, units * to.width));
+}
+
+// Maps every replacement line to the matched file line with the same trimmed content; new lines follow their anchor.
+function reindent(replacement, oldLines, matchedLines, fileLines) {
+  const from = indentUnit(oldLines);
+  const to = indentUnit(fileLines);
+  const sameUnit = from.unit === to.unit;
+  let cursor = 0;
+  let anchor = 0;
+  let adjusted = false;
+  const lines = replacement.split('\n').map(line => {
+    if (isBlank(line)) return line;
+    const text = line.trim();
+    for (let j = cursor; j < oldLines.length; j++) {
+      if (oldLines[j].trim() !== text) continue;
+      cursor = j + 1;
+      anchor = j;
+      const indent = indentOf(matchedLines[j]);
+      if (indent !== indentOf(line)) adjusted = true;
+      return indent + text;
+    }
+    const oldAnchor = indentOf(oldLines[anchor] ?? '');
+    const fileAnchor = indentOf(matchedLines[anchor] ?? '');
+    const indent = indentOf(line);
+    let next;
+    if (indent.startsWith(oldAnchor)) {
+      const extra = indent.slice(oldAnchor.length);
+      next = fileAnchor + (sameUnit ? extra : convertIndent(extra, from, to));
+    } else if (oldAnchor.startsWith(indent)) {
+      const missing = oldAnchor.slice(indent.length);
+      const drop = sameUnit ? missing.length : convertIndent(missing, from, to).length;
+      next = fileAnchor.slice(0, Math.max(0, fileAnchor.length - drop));
+    } else {
+      next = sameUnit ? indent : convertIndent(indent, from, to);
+    }
+    if (next !== indent) adjusted = true;
+    return next + text;
+  });
+  return {text: lines.join('\n'), adjusted};
+}
+
+function candidateList(spans) {
+  return spans.map(span => ({startLine: span.startLine + 1, endLine: span.endLine + 1}));
+}
+
+function failure(code, message, extra) {
+  return {ok: false, code, message, ...extra};
+}
+
+function prepare(text) {
+  if (typeof text !== 'string') throw new TypeError('text must be a string');
+  const {bom, body} = splitBom(text);
+  const {normalized, toRaw, crlf, lf, cr} = normalizeLineEndings(body);
+  const lineEnding = crlf >= lf && crlf >= cr && crlf > 0 ? 'crlf' : cr > lf && cr > crlf ? 'cr' : 'lf';
+  const mixed = [crlf, lf, cr].filter(Boolean).length > 1;
+  return {text, bom, body, normalized, toRaw, lineEnding, eol: lineEnding === 'crlf' ? '\r\n' : lineEnding === 'cr' ? '\r' : '\n', mixed, table: createLineTable(normalized)};
+}
+
+function resolve(doc, edit, options) {
+  const {oldString, newString, replaceAll = false, occurrence, line} = edit;
+  if (typeof oldString !== 'string' || typeof newString !== 'string') throw new TypeError('oldString and newString must be strings');
+  const meta = {lineEnding: doc.lineEnding, bom: doc.bom !== ''};
+  if (oldString === '') return failure('empty-old', 'oldString must not be empty.', meta);
+  if (oldString === newString) return failure('no-change', 'oldString and newString are identical.', meta);
+  const normalizedOld = oldString.replace(/\r\n?/g, '\n');
+  const found = locate(doc.normalized, doc.table, normalizedOld, options);
+  if (!found) {
+    const closest = options.diagnostics === false ? null : nearestRegion(doc.table, normalizedOld.replace(/\n$/, '').split('\n'), 200000);
+    const hint = closest ? ` The closest region starts at line ${closest.startLine} (similarity ${closest.similarity}); re-read it and copy the exact text.` : '';
+    return failure('not-found', `oldString was not found in the text.${hint}`, {...meta, closest: closest ?? undefined});
+  }
+  let spans = found.spans;
+  const warnings = [];
+  if (spans.length > 1 && !replaceAll) {
+    if (occurrence !== undefined) {
+      if (!Number.isInteger(occurrence) || occurrence === 0) throw new RangeError('occurrence must be a non-zero integer');
+      const index = occurrence > 0 ? occurrence - 1 : spans.length + occurrence;
+      if (index < 0 || index >= spans.length) return failure('occurrence-out-of-range', `occurrence ${occurrence} is out of range: oldString matches ${spans.length} locations (strategy ${found.strategy}).`, {...meta, strategy: found.strategy, candidates: candidateList(spans)});
+      spans = [spans[index]];
+    } else if (line !== undefined) {
+      const distances = spans.map(span => Math.abs(span.startLine + 1 - line));
+      const nearest = Math.min(...distances);
+      const near = spans.filter((span, i) => distances[i] === nearest);
+      if (near.length !== 1 || nearest > 3) return failure('ambiguous', `oldString matches ${spans.length} locations (strategy ${found.strategy}) and the line hint ${line} does not select exactly one. Add surrounding context, pass occurrence, or set replaceAll.`, {...meta, strategy: found.strategy, candidates: candidateList(spans)});
+      spans = near;
+    } else {
+      return failure('ambiguous', `oldString matches ${spans.length} locations (strategy ${found.strategy}). Add surrounding context, pass occurrence, or set replaceAll.`, {...meta, strategy: found.strategy, candidates: candidateList(spans)});
+    }
+  } else if (spans.length === 1 && line !== undefined && Math.abs(spans[0].startLine + 1 - line) > 5) {
+    warnings.push(`The match starts at line ${spans[0].startLine + 1}, not near the line hint ${line}.`);
+  }
+  if (doc.mixed) warnings.push('The text mixes line-ending styles; replacements use the dominant style.');
+  const replacement = newString.replace(/\r\n?/g, '\n');
+  const raw = index => doc.bom.length + (doc.toRaw ? doc.toRaw[index] : index);
+  let reindented = false;
+  const pieces = spans.map(span => {
+    let text = replacement;
+    if (found.oldLines) {
+      const matchedLines = doc.table.lines.slice(span.startLine, span.endLine + 1);
+      const result = reindent(replacement, found.oldLines, matchedLines, doc.table.lines);
+      text = result.text;
+      reindented = reindented || result.adjusted;
+    }
+    if (doc.eol !== '\n') text = text.replace(/\n/g, doc.eol);
+    return {start: raw(span.start), end: raw(span.end), startLine: span.startLine + 1, endLine: span.endLine + 1, replacement: text};
+  });
+  return {ok: true, strategy: found.strategy, pieces, reindented, warnings, ...meta};
+}
+
+function splice(text, pieces) {
+  let output = '';
+  let previous = 0;
+  for (const piece of pieces) {
+    output += text.slice(previous, piece.start) + piece.replacement;
+    previous = piece.end;
+  }
+  return output + text.slice(previous);
+}
+
+function publicMatches(pieces) {
+  return pieces.map(({start, end, startLine, endLine}) => ({start, end, startLine, endLine}));
+}
+
+function findEdit(text, oldString, options = {}) {
+  const doc = prepare(text);
+  const result = resolve(doc, {oldString, newString: oldString + '\u0000', replaceAll: true}, options);
+  if (!result.ok) return result;
+  return {ok: true, strategy: result.strategy, matches: publicMatches(result.pieces), lineEnding: result.lineEnding, bom: result.bom};
+}
+
+function applyEdit(text, edit, options = {}) {
+  const doc = prepare(text);
+  const result = resolve(doc, edit, options);
+  if (!result.ok) return result;
+  return {
+    ok: true,
+    text: splice(text, result.pieces),
+    strategy: result.strategy,
+    replaced: result.pieces.length,
+    matches: publicMatches(result.pieces),
+    reindented: result.reindented,
+    warnings: result.warnings,
+    lineEnding: result.lineEnding,
+    bom: result.bom,
+  };
+}
+
+function applyEdits(text, edits, options = {}) {
+  if (!Array.isArray(edits) || edits.length === 0) throw new TypeError('edits must be a non-empty array');
+  const doc = prepare(text);
+  const applied = [];
+  const pieces = [];
+  for (const [index, edit] of edits.entries()) {
+    const result = resolve(doc, edit, options);
+    if (!result.ok) return {...result, index};
+    applied.push({index, strategy: result.strategy, matches: publicMatches(result.pieces), reindented: result.reindented, warnings: result.warnings});
+    for (const piece of result.pieces) pieces.push({...piece, index});
+  }
+  pieces.sort((a, b) => a.start - b.start || a.index - b.index);
+  for (let i = 1; i < pieces.length; i++) {
+    if (pieces[i].start < pieces[i - 1].end || (pieces[i].start === pieces[i - 1].start && pieces[i - 1].end === pieces[i - 1].start && pieces[i].end === pieces[i].start)) {
+      return failure('overlap', `Edits ${pieces[i - 1].index} and ${pieces[i].index} overlap (lines ${pieces[i - 1].startLine}-${pieces[i - 1].endLine} and ${pieces[i].startLine}-${pieces[i].endLine}).`, {index: pieces[i].index, lineEnding: doc.lineEnding, bom: doc.bom !== ''});
+    }
+  }
+  return {ok: true, text: splice(text, pieces), applied, lineEnding: doc.lineEnding, bom: doc.bom !== ''};
+}
+
+module.exports = {findEdit, applyEdit, applyEdits};