@opum-ai/lore 0.1.0 → 0.2.0

package/src/core/reconcile.ts

@@ -1,236 +0,0 @@
-/**
- * reconcile.ts — roll a `Story`/`Spec`'s `tasks:`-linked Backlog statuses up into one derived
- * doc `status` (LORE-23, [ADR-0009] §3).
- *
- * A Story's `status` frontmatter is not authored once and left stale — it is **recomputed** from
- * the live statuses of the tasks it links, so a reader (or `lore check`'s drift gate) never sees a
- * doc claiming `done` while a linked task is still open. This module is the shared pure engine
- * behind that computation: the command layer (LORE-24+) resolves each linked task id to its raw
- * `status` string (the LORE-21 adapter's `viewTask`/`listTasks`) and reads the project's ordered
- * status flow from `backlog/config.yml` (`statuses:`), then calls {@link reconcileStatus}. `lore
- * sync` writes the result; `lore check` diffs it against the persisted `status` and never writes
- * (ADR-0007).
- *
- * Per-repo `[reconcile.overrides]` (`.lore/config.toml`, LORE-26) lets a project map a specific
- * Backlog status straight to a {@link ReconciledStatus}, bypassing `statusFlow` position entirely —
- * the escape hatch for a status an ordered flow cannot classify unambiguously (see
- * {@link reconcileStatus}'s `overrides` parameter).
- *
- * Per the core contract (lore-design §2.1) this module is pure: two string arrays (plus an optional
- * overrides map) in, a derived status (or `null`) or a typed {@link LoreError} out — no filesystem,
- * no spawn, no clock. Reading `backlog/config.yml` and resolving each task's live status are
- * command-layer concerns, kept out of this engine so it stays a single deterministic function over
- * already-resolved data.
- *
- * [ADR-0009]: ../../docs/adr/0009-story-task-coupling-reconciliation.md
- */
-
-import { LoreError } from "../errors";
-
-/** The three derived rollup values (ADR-0009 §3, backlog-cli-contract.md §3.2). */
-export type ReconciledStatus = "todo" | "in-progress" | "done";
-
-/** The closed set {@link ReconciledStatus} draws from, for validating a `[reconcile.overrides]` target. */
-const RECONCILED_STATUSES: readonly ReconciledStatus[] = ["todo", "in-progress", "done"];
-
-/** Where one task's status falls in the project's ordered {@link StatusFlow}. */
-type StatusPosition = "not-started" | "active" | "terminal";
-
-/**
- * Per-repo `[reconcile.overrides]` (`.lore/config.toml`, `config.ts`'s {@link ReconcileConfig.overrides}):
- * a raw Backlog status string → the {@link ReconciledStatus} it should contribute to the rollup,
- * **bypassing** {@link StatusFlow} position entirely for that status (ADR-0009 §3). `config.ts` parses
- * this as an unvalidated `Record<string, string>` — "reconcile.ts owns the rollup-status vocabulary and
- * its semantics" (config.ts) — so {@link reconcileStatus} is where an out-of-vocabulary target value is
- * caught.
- */
-export type StatusOverrides = Readonly<Record<string, string>>;
-
-/**
- * A project's status set, **ordered** exactly as configured (`backlog/config.yml` `statuses:` /
- * `backlog config get statuses`) — never the hardcoded `["To Do", "In Progress", "Done"]` default
- * (backlog-cli-contract.md §3.1). Index `0` is the not-started state; the last index is the
- * terminal ("done") state; everything between is an active/started state (`In Progress`,
- * `Review`, `Testing`, `Blocked`, …). Reading this from config is a command-layer concern — this
- * engine only consumes the resolved list. Must carry **at least two** entries: a single-entry flow
- * cannot distinguish "not started" from "terminal" ({@link reconcileStatus} rejects it).
- */
-export type StatusFlow = readonly string[];
-
-/**
- * Roll `taskStatuses` — the raw `status` string of every task a Story links via its `tasks:`
- * frontmatter — up into one {@link ReconciledStatus}, per `statusFlow`'s config-driven ordering
- * (ADR-0009 §3):
- *
- * - `taskStatuses` empty (no linked tasks) → `null`: a narrative-only doc's authored `status` is
- *   never overwritten (AC#2) — the caller leaves the doc's existing `status` untouched.
- * - every linked task's status is `statusFlow`'s **last** (terminal) entry → `"done"`.
- * - any linked task's status is **neither** first nor last (an active/started state) →
- *   `"in-progress"`.
- * - otherwise (tasks exist, none active, not all terminal) → `"todo"`.
- *
- * The three rules are applied by elimination, in that order, exactly as backlog-cli-contract.md
- * §3.2 states it. One corner case follows directly from the literal rule and is intentional, not
- * a bug: a Story linking only a `Done` task and a `To Do` task (no task in an explicit mid-flow
- * status) rolls up to `"todo"`, not `"in-progress"` — "in-progress" is defined purely by the
- * presence of an active-state task, not by partial completion among terminal/not-started tasks.
- *
- * @param taskStatuses the raw configured `status` string of every linked task (AC#1: any custom
- *   flow, not just the three defaults), in any order — order does not affect the rollup.
- * @param statusFlow the project's ordered status set, resolved from Backlog config.
- * @param overrides per-repo `[reconcile.overrides]` (default `{}`): a status matching a key here
- *   contributes its mapped {@link ReconciledStatus} directly, bypassing `statusFlow` position
- *   entirely — the escape hatch for a status a strict ordered flow cannot classify unambiguously
- *   (a bespoke `Cancelled`/`Won't Fix` state, or one a team added without reordering `statuses:`).
- *   Takes precedence over position even when the status is *also* present in `statusFlow`.
- * @returns the rolled-up status, or `null` when there are no linked tasks.
- * @throws LoreError `validation` when `statusFlow` has fewer than two entries, is empty, or
- *   carries a duplicate entry (an ambiguous flow lore cannot classify against — ADR-0009 "must
- *   report rather than guess"), when an override's target is not one of `todo`/`in-progress`/
- *   `done`, or when a task's status is not present in `statusFlow` **and** has no override (a
- *   config/task drift lore refuses to guess past).
- */
-export function reconcileStatus(
-  taskStatuses: readonly string[],
-  statusFlow: StatusFlow,
-  overrides: StatusOverrides = {},
-): ReconciledStatus | null {
-  if (taskStatuses.length === 0) {
-    return null;
-  }
-  validateStatusFlow(statusFlow);
-  const validatedOverrides = validateOverrides(overrides);
-  const positions = taskStatuses.map((status) => classify(status, statusFlow, validatedOverrides));
-  if (positions.every((position) => position === "terminal")) {
-    return "done";
-  }
-  if (positions.some((position) => position === "active")) {
-    return "in-progress";
-  }
-  return "todo";
-}
-
-/**
- * Validate `statusFlow`/`overrides` up front, without needing any task data — the fail-fast half of
- * {@link reconcileStatus} exposed on its own so a caller resolving many tasks per invocation (e.g.
- * `lore sync`, one Backlog subprocess round-trip per linked task) can catch a semantically-broken
- * config (a degenerate flow, an out-of-vocabulary override target) **before** spending any of that
- * work — `reconcileStatus` itself only reaches this validation once real task data is in hand,
- * which is too late for that fail-fast property alone. Re-validates the same inputs
- * `reconcileStatus` will validate again per call; see that function's own note on why the
- * redundancy is accepted rather than threading a pre-validated value through its signature.
- *
- * @throws LoreError `validation` — see {@link reconcileStatus}'s throws for the exact conditions.
- */
-export function validateReconcileInputs(statusFlow: StatusFlow, overrides: StatusOverrides = {}): void {
-  validateStatusFlow(statusFlow);
-  validateOverrides(overrides);
-}
-
-/**
- * Reject a `statusFlow` lore cannot classify against unambiguously: fewer than two entries (with
- * only one entry, index `0` is simultaneously the not-started **and** the terminal position — the
- * two roles {@link classify} treats as distinct would silently collapse to the same index) or
- * carrying a duplicate entry (an entry's position — and so its not-started/active/terminal
- * classification — would depend on which occurrence is meant).
- */
-function validateStatusFlow(statusFlow: StatusFlow): void {
-  if (statusFlow.length < 2) {
-    throw new LoreError(
-      "validation",
-      `cannot reconcile status: the project's configured status flow has ${statusFlow.length} ${statusFlow.length === 1 ? "entry" : "entries"} (need at least 2 to distinguish "not started" from "terminal")`,
-      'set `statuses:` in `backlog/config.yml` to an ordered list of at least two statuses (e.g. ["To Do", "In Progress", "Done"])',
-      { statusFlow },
-    );
-  }
-  const seen = new Set<string>();
-  for (const status of statusFlow) {
-    if (seen.has(status)) {
-      throw new LoreError(
-        "validation",
-        `cannot reconcile status: the project's configured status flow has a duplicate entry ${JSON.stringify(status)}`,
-        "each entry in `backlog/config.yml`'s `statuses:` must be unique so its position in the flow is unambiguous",
-        { statusFlow },
-      );
-    }
-    seen.add(status);
-  }
-}
-
-/**
- * Validate a `[reconcile.overrides]` map and return it keyed for safe, exhaustive lookup: a `Map`
- * (not the input `Record`) so a status string that happens to name an `Object.prototype` member
- * (`constructor`, `toString`, …) can never resolve to an inherited value instead of a real miss —
- * the same class of hazard `config.ts`'s `asStringMap` guards on the write side.
- *
- * @throws LoreError `validation` naming the offending status and target when a target is not one
- *   of {@link RECONCILED_STATUSES} — `config.ts` deliberately leaves this vocabulary check to
- *   reconcile.ts (its own header comment), so a bad `.lore/config.toml` value is caught here.
- */
-function validateOverrides(overrides: StatusOverrides): ReadonlyMap<string, ReconciledStatus> {
-  const validated = new Map<string, ReconciledStatus>();
-  for (const [status, target] of Object.entries(overrides)) {
-    if (!isReconciledStatus(target)) {
-      throw new LoreError(
-        "validation",
-        `cannot reconcile status: [reconcile.overrides] maps ${JSON.stringify(status)} to ${JSON.stringify(target)}, which is not a valid rollup status`,
-        `set [reconcile.overrides] "${status}" in .lore/config.toml to one of: ${RECONCILED_STATUSES.join(", ")}`,
-        { status, target, valid: RECONCILED_STATUSES },
-      );
-    }
-    validated.set(status, target);
-  }
-  return validated;
-}
-
-/** Narrow an override's raw string target to {@link ReconciledStatus}, for {@link validateOverrides}. */
-function isReconciledStatus(value: string): value is ReconciledStatus {
-  return (RECONCILED_STATUSES as readonly string[]).includes(value);
-}
-
-/**
- * Classify one task's raw `status` string, checking `overrides` before falling back to its index in
- * `statusFlow`: the first entry is not-started, the last is terminal, everything between is active.
- * Matching is exact-string (Backlog status labels are canonical configured strings, verbatim in the
- * `--json` payload — not user-typed free text lore case-folds elsewhere).
- *
- * @throws LoreError `validation` when `status` has no override and is absent from `statusFlow` entirely.
- */
-function classify(
-  status: string,
-  statusFlow: StatusFlow,
-  overrides: ReadonlyMap<string, ReconciledStatus>,
-): StatusPosition {
-  const override = overrides.get(status);
-  if (override !== undefined) {
-    return positionForOverride(override);
-  }
-  const index = statusFlow.indexOf(status);
-  if (index === -1) {
-    throw new LoreError(
-      "validation",
-      `cannot reconcile status: task status ${JSON.stringify(status)} is not in the project's configured status flow (${statusFlow.map((s) => JSON.stringify(s)).join(", ")}) and has no [reconcile.overrides] entry`,
-      "the task's status must match one of `backlog/config.yml`'s `statuses:` exactly, or add a `[reconcile.overrides]` entry for it in .lore/config.toml",
-      { status, statusFlow },
-    );
-  }
-  if (index === statusFlow.length - 1) {
-    return "terminal";
-  }
-  if (index === 0) {
-    return "not-started";
-  }
-  return "active";
-}
-
-/** Map an override's validated target directly to the {@link StatusPosition} the aggregation rule expects. */
-function positionForOverride(target: ReconciledStatus): StatusPosition {
-  switch (target) {
-    case "done":
-      return "terminal";
-    case "in-progress":
-      return "active";
-    case "todo":
-      return "not-started";
-  }
-}

package/src/core/replace.ts

@@ -1,419 +0,0 @@
-/**
- * replace.ts — the **pure** engine behind `lore replace`'s find-and-replace, with one
- * inviolable rule: a lore-**managed region is never touched** (cli-surface §replace, AC#1).
- *
- * `lore replace` is a refactoring convenience — literal or regex find/replace across one doc
- * or the whole bundle. The danger it must design around is that a doc is not all author prose:
- * parts of it are **machine-owned**, regenerated wholesale by `lore sync` from an external
- * source of truth. A blind text replace that edited inside such a region would either be
- * silently reverted on the next `sync` (at best) or corrupt the region's structure so that
- * regeneration's drift gate trips (at worst). So a match that overlaps a managed region is left
- * untouched and uncounted; only author-owned bytes are rewritten ({@link applyReplacement}).
- *
- * ### One pass over the whole document
- *
- * The matcher runs over the **entire** document and each match is kept or skipped by whether its
- * byte span overlaps a managed region. Running over the whole text (rather than over each
- * author-owned gap in isolation) is what makes regex anchors and zero-width assertions bind to the
- * real document — `^`/`$`/`\b`/lookaround see the true start/end and neighbors, not a gap boundary
- * next to a managed block. `$1`/`$&`/`` $` ``/`$'`/`$<name>` substitutions are expanded explicitly
- * ({@link expandTemplate}, byte-for-byte with `String.prototype.replace`) so the single pass keeps
- * full regex-replacement semantics; in literal mode the replacement is inserted verbatim ($ is not
- * special).
- *
- * ### What counts as a managed region
- *
- * The bundle has two kinds of in-file managed region, both registered in
- * {@link MANAGED_REGION_LOCATORS}: the `<!-- lore:index:begin -->` … `<!-- lore:index:end -->`
- * listing block that {@link generateIndexes} owns in every `index.md` (lore-design §6.2), and the
- * `<!-- lore:tasks:begin -->` … `<!-- lore:tasks:end -->` task table that `managed-block.ts` owns in
- * a `Story`/`Spec` doc (LORE-22). {@link managedRanges} locates each registered region with **that
- * region's own owner's** location logic — so `replace` protects exactly the span `lore sync` would
- * regenerate, and a refactor can never land in bytes `sync` later reverts. Each locator is a fail-loud
- * `validation` error on a malformed layout (a duplicated marker pair, or an unmatched/crossed begin)
- * rather than a guessed span (LORE-86) — `replace` never has to guess which bytes were meant to stay
- * protected either. A future managed-block kind is likewise a one-entry addition to the registry. The
- * fully machine-generated `log.md` has no in-file markers; it is excluded by the command layer's
- * discovery, not here (this engine sees only the bytes it is handed).
- *
- * Two different location strategies, deliberately not unified into one: `lore:index`'s
- * {@link locateManagedBlock} is a literal `indexOf` scan — safe there only because that marker text
- * never occurs outside a real index block in practice. `lore:tasks:begin`/`:end`, however, are
- * routinely *cited* in this project's own prose and fenced code examples documenting the format, so a
- * literal scan misfires on those (a false "duplicated"/"unmatched" error, or worse, silently
- * protecting prose that merely mentions the syntax); {@link locateTaskBlock} instead reuses
- * `managed-block.ts`'s structural, mdast-based marker location (the same one `lore sync`/`lore check`
- * already trust), where a sentinel inside a code fence or blockquote is never mistaken for a real
- * marker (LORE-73).
- *
- * Per the core contract (lore-design §2.1) everything here is pure: text in, `{ text, count }` out,
- * or a {@link LoreError} out — `usage` for an unusable pattern (empty, invalid regex, or one that
- * can match the empty string), or `validation` when a managed region's markers are malformed
- * (LORE-86, propagated from whichever locator owns that region) — no filesystem, no printing, no
- * flags, no `process.exit`. The command layer ({@link commands/replace}) discovers and reads the
- * files, compiles the pattern **once**, and applies it per file; a `validation` error aborts before
- * any file is written (`commands/replace.ts` only writes after every target has been read and
- * rewritten).
- */
-
-import { LoreError } from "../errors";
-import { INDEX_BLOCK_BEGIN, INDEX_BLOCK_END, locateManagedBlock } from "./indexes";
-import { locateTaskBlock, TASK_BLOCK_BEGIN, TASK_BLOCK_END } from "./managed-block";
-
-/**
- * A half-open `[start, end)` byte range within a file's text. Used for the spans
- * {@link managedRanges} protects from replacement.
- */
-export interface TextRange {
-  /** Inclusive start offset. */
-  readonly start: number;
-  /** Exclusive end offset. */
-  readonly end: number;
-}
-
-/** The result of applying a {@link Replacer} to one file. */
-export interface ReplaceResult {
-  /** The rewritten text (identical to the input when `count` is 0). */
-  readonly text: string;
-  /** How many matches were replaced — counted **only outside** managed regions. */
-  readonly count: number;
-}
-
-/** Options for {@link compileReplacer}/{@link replaceInText}. */
-export interface ReplaceOptions {
-  /** Treat `find` as a JavaScript regular expression (with `$1`/`$&` substitution in `replace`). */
-  readonly regex?: boolean;
-}
-
-/**
- * A compiled find-and-replace, ready to apply to any number of files. `compile once, apply per file`
- * is what lets the command validate the pattern a **single** time up front (so a bad pattern fails
- * even when discovery finds zero files) instead of only when the per-file loop happens to run.
- */
-export type Replacer = (text: string) => ReplaceResult;
-
-/**
- * One entry in {@link MANAGED_REGION_LOCATORS}: the location function for one managed-region kind,
- * paired with `duplicateProbe` — a synthetic, individually-well-formed *duplicated* instance of that
- * region (its marker pair written out twice) used only by the LORE-194 regression test
- * (`replace.test.ts`) to pin the throw-on-duplicate contract documented below. Requiring a probe on
- * every entry is what makes a new registration prove the contract rather than merely promise it.
- */
-interface ManagedRegionLocator {
-  readonly locate: (text: string) => TextRange | null;
-  readonly duplicateProbe: string;
-}
-
-/**
- * The location functions that find each kind of lore-managed region, one per marker pair. The single
- * registry every managed-region consumer skips, so a new managed block is protected by adding one
- * entry rather than threading a new special case through `replace`. Each locator is owned by (and
- * imported from) the module that owns that region's markers ({@link indexes}, {@link managed-block}),
- * so `replace` always agrees with `lore sync`/`lore check` on a region's exact extent — including
- * which location *strategy* (literal scan vs. structural) is safe for that marker pair.
- *
- * **Contract (LORE-194): every locator MUST throw a {@link LoreError} — never return the first
- * span — when its marker occurs more than once, even when each occurrence is individually a
- * well-formed block.** {@link assertNoInjectedMarker}'s LORE-162 guarantee (a `` $` ``/`$'` expansion
- * that copies an existing marker into the rewritten result is rejected, not silently written) depends
- * entirely on this: it re-runs {@link managedRanges} — i.e. every locator here — over the *rewritten*
- * text and trusts that a newly-duplicated marker surfaces as a thrown error. A locator that instead
- * returned the first span on duplication would make that re-validation pass silently, reopening
- * LORE-162 for that marker kind with no existing test failing. {@link locateManagedBlock} and
- * {@link locateTaskBlock} both satisfy this today; a new entry must too, proven by its
- * `duplicateProbe` (see `locatorThrowsOnDuplicate` and the registry-iterating test in
- * `replace.test.ts`) rather than left as an incidental property nothing checks.
- */
-export const MANAGED_REGION_LOCATORS: ReadonlyArray<ManagedRegionLocator> = [
-  {
-    locate: (text) => locateManagedBlock(text, INDEX_BLOCK_BEGIN, INDEX_BLOCK_END),
-    duplicateProbe: `${INDEX_BLOCK_BEGIN}\na\n${INDEX_BLOCK_END}\n${INDEX_BLOCK_BEGIN}\nb\n${INDEX_BLOCK_END}`,
-  },
-  {
-    locate: (text) => locateTaskBlock(text),
-    duplicateProbe: `${TASK_BLOCK_BEGIN}\na\n${TASK_BLOCK_END}\n${TASK_BLOCK_BEGIN}\nb\n${TASK_BLOCK_END}`,
-  },
-];
-
-/**
- * Whether `locate` obeys the throw-on-duplicate contract documented on {@link MANAGED_REGION_LOCATORS}
- * for its own `duplicateProbe`: throwing a {@link LoreError} (not returning a span, and not returning
- * `null`) when the probe's marker occurs twice. Exported only for the LORE-194 regression test in
- * `replace.test.ts` — both to pin the two current registry entries and to prove the check itself flags
- * a first-span-on-duplicate violation, via a synthetic locator that deliberately breaks the contract.
- */
-export function locatorThrowsOnDuplicate(locate: (text: string) => TextRange | null, duplicateProbe: string): boolean {
-  try {
-    locate(duplicateProbe);
-  } catch (cause) {
-    return cause instanceof LoreError;
-  }
-  return false; // returned a span (or null) instead of throwing — contract violated
-}
-
-/** A representative probe carrying word boundaries, line ends, digits, and punctuation, for the zero-width guard. */
-const ZERO_WIDTH_PROBE = "a b1\n.x-_/2";
-
-/**
- * Every lore-managed region in `text`, as merged, ascending `[start, end)` ranges. Each registered
- * locator finds its own region kind ({@link MANAGED_REGION_LOCATORS}) so `replace` and `lore
- * sync`/`check` agree byte-for-byte on a region's extent. Ranges from different marker kinds are
- * merged so any overlap/touch collapses, leaving a clean ordered partition for
- * {@link applyReplacement}.
- *
- * @throws LoreError `validation` when a registered region's markers are malformed (duplicated,
- *   unmatched, or crossed) — propagated from whichever locator owns that region, rather than
- *   guessing which bytes to protect (LORE-86).
- */
-export function managedRanges(text: string): TextRange[] {
-  const ranges: TextRange[] = [];
-  for (const { locate } of MANAGED_REGION_LOCATORS) {
-    const bounds = locate(text);
-    if (bounds !== null) {
-      ranges.push(bounds);
-    }
-  }
-  return mergeRanges(ranges);
-}
-
-/**
- * Compile a find/replace into a reusable {@link Replacer}, validating the pattern up front: an empty
- * `find`, an invalid regex, or a pattern that can match the **empty string** (`x*`, `a?`, `.*`,
- * `\b`, `^`, `(?:)`) is a `usage` {@link LoreError} — a zero-width global match would otherwise
- * "replace" between every character and mass-corrupt a file. Literal mode matches `find` as plain
- * text and inserts `replace` verbatim ($ is not special); regex mode honors `$1`/`$&`/`` $` ``/`$'`/
- * `$<name>` substitutions.
- */
-export function compileReplacer(find: string, replace: string, options: ReplaceOptions = {}): Replacer {
-  if (find === "") {
-    throw new LoreError("usage", "the find pattern is empty", "pass a non-empty string (or regex) to search for");
-  }
-  const matcher = options.regex ? compileRegex(find) : new RegExp(escapeRegExp(find), "g");
-  assertNonEmptyMatching(matcher);
-  const expand: (match: RegExpMatchArray, source: string) => string = options.regex
-    ? (match, source) => expandTemplate(replace, match, source)
-    : () => replace;
-  return (text: string): ReplaceResult => applyReplacement(text, matcher, expand);
-}
-
-/**
- * Find-and-replace within `text` (a single-shot {@link compileReplacer} + apply), returning the
- * rewritten text and the count of matches replaced **outside** managed regions (AC#1). Equivalent to
- * `String.prototype.replace` over the whole document, except matches overlapping a managed region are
- * left untouched and uncounted.
- */
-export function replaceInText(
-  text: string,
-  find: string,
-  replace: string,
-  options: ReplaceOptions = {},
-): ReplaceResult {
-  return compileReplacer(find, replace, options)(text);
-}
-
-/**
- * Apply a compiled `matcher` to the whole `text`, splicing in `expand(match)` for each match whose
- * byte span does **not** overlap a managed region and leaving every other byte verbatim. Because the
- * matcher runs over the full document, anchors/assertions bind to the real document; because skipped
- * matches simply fall inside the verbatim slices, managed regions pass through untouched.
- *
- * `overlapsManaged` only screens the ORIGINAL matched span, before `expand` runs — in regex mode the
- * `` $` ``/`$'` template tokens ({@link expandTemplate}) copy the document's own prefix/suffix
- * verbatim, so a match sitting entirely outside a managed region can still expand into a splice that
- * carries an existing managed-block marker into its result. That would leave two copies of the marker
- * in the rewritten document with no owner able to agree on the region's extent (LORE-86's invariant,
- * broken from the other direction). So once the full `result` is assembled, it is re-validated with
- * {@link managedRanges} — the same locators every managed region already trusts — before being
- * returned (LORE-162); a violation there is surfaced as a `usage` error (this replacement's pattern is
- * unusable against this document) rather than the `validation` error `managedRanges` would normally
- * throw for a document that was ALREADY malformed on disk.
- */
-function applyReplacement(
-  text: string,
-  matcher: RegExp,
-  expand: (match: RegExpMatchArray, source: string) => string,
-): ReplaceResult {
-  const ranges = managedRanges(text);
-  const overlapsManaged = (start: number, length: number): boolean =>
-    ranges.some((r) => start < r.end && start + length > r.start);
-
-  let result = "";
-  let last = 0;
-  let count = 0;
-  for (const match of text.matchAll(matcher)) {
-    const start = match.index ?? 0;
-    const matched = match[0];
-    if (matched.length === 0) {
-      // A zero-width pattern that slipped past the compile-time probe (rare): refuse rather than
-      // loop forever or splice between characters. Validation up front makes this practically dead.
-      throw zeroWidthError();
-    }
-    if (overlapsManaged(start, matched.length)) {
-      continue; // a match inside (or crossing into) a managed region — leave it, don't count it
-    }
-    result += text.slice(last, start) + expand(match, text);
-    last = start + matched.length;
-    count++;
-  }
-  result += text.slice(last);
-  if (count === 0) {
-    return { text, count };
-  }
-  assertNoInjectedMarker(result);
-  return { text: result, count };
-}
-
-/**
- * Re-validate a rewritten document against {@link managedRanges} — the same structural/literal
- * locators {@link MANAGED_REGION_LOCATORS} registers everywhere else — to catch a `` $` ``/`$'`
- * expansion that spliced a managed-block marker into the result, duplicating (or otherwise
- * malforming) it (LORE-162). `text` was already validated once, before the replacement loop ran, so
- * any failure here was newly introduced by splicing `expand`'s output in, never a pre-existing
- * condition of the input document — re-thrown as a `usage` error (this replacement is what's
- * unusable) instead of `managedRanges`' own `validation` error (which reads as "the input document is
- * malformed").
- */
-function assertNoInjectedMarker(result: string): void {
-  try {
-    managedRanges(result);
-  } catch (cause) {
-    if (cause instanceof LoreError) {
-      throw new LoreError(
-        "usage",
-        `this replacement would leave a lore-managed block marker duplicated or malformed in the result: ${cause.message}`,
-        "rewrite the pattern/replacement so it cannot copy a managed-block marker into the output (e.g. keep $` /$' from spanning a managed region), or narrow --in to skip the affected file",
-      );
-    }
-    throw cause;
-  }
-}
-
-/** Compile a user regex as global, mapping a syntax error to a `usage` {@link LoreError} (exit 2). */
-function compileRegex(pattern: string): RegExp {
-  try {
-    return new RegExp(pattern, "g");
-  } catch (cause) {
-    throw new LoreError(
-      "usage",
-      `invalid regex "${pattern}": ${cause instanceof Error ? cause.message : String(cause)}`,
-      "fix the regular expression, or drop --regex to match it as a literal string",
-    );
-  }
-}
-
-/**
- * Reject a pattern that can match the empty string, before it is ever applied. A global zero-width
- * match would make `replace` insert the replacement between every character (mass corruption), which
- * the empty-`find` guard exists to prevent but a regex like `x*`/`\b` slips past. Detected by probing
- * the matcher against the empty string and a representative {@link ZERO_WIDTH_PROBE} (word
- * boundaries, a line end, digits, punctuation); a zero-length match in either is fatal. `matchAll`
- * clones the regex, so probing does not disturb the matcher's later use.
- */
-function assertNonEmptyMatching(matcher: RegExp): void {
-  for (const probe of ["", ZERO_WIDTH_PROBE]) {
-    for (const match of probe.matchAll(matcher)) {
-      if (match[0].length === 0) {
-        throw zeroWidthError();
-      }
-    }
-  }
-}
-
-/** The `usage` {@link LoreError} for a pattern that can match the empty string. */
-function zeroWidthError(): LoreError {
-  return new LoreError(
-    "usage",
-    "the pattern can match an empty string, which would replace between every character",
-    "refine the pattern so every match has length (e.g. require at least one character)",
-  );
-}
-
-/**
- * Expand a regex replacement `template` against one `match` mostly as `String.prototype.replace`
- * does: `$$`→`$`, `$&`→the match, `` $` ``→the prefix, `$'`→the suffix, `$<name>`→a named group, and
- * `$n`/`$nn`→a numbered group (greedy two digits when that group exists, else one digit plus the
- * literal digit; an out-of-range number is left literal). This is what lets the single whole-document
- * pass keep native substitution semantics while still skipping managed regions.
- *
- * One deliberate divergence: `$<name>` for a name the regex never declares is left as the literal
- * token `$<name>`, whether the regex has no named groups at all (this matches native behavior) or has
- * *other* named groups but not this one (native silently substitutes `""` there; this engine does not,
- * because an unresolvable token silently deleting document text is worse than leaving it visibly
- * unresolved — LORE-163).
- */
-function expandTemplate(template: string, match: RegExpMatchArray, source: string): string {
-  const groups = match.length - 1;
-  const index = match.index ?? 0;
-  return template.replace(/\$(\$|&|`|'|<[^>]*>|\d\d?)/g, (whole, selector: string): string => {
-    if (selector === "$") {
-      return "$";
-    }
-    if (selector === "&") {
-      return match[0];
-    }
-    if (selector === "`") {
-      return source.slice(0, index);
-    }
-    if (selector === "'") {
-      return source.slice(index + match[0].length);
-    }
-    if (selector.startsWith("<")) {
-      const name = selector.slice(1, -1);
-      // Only substitute when this regex actually declares a named group of this name — whether it
-      // participated in the match or not. `match.groups` carries a key for every named group the
-      // *pattern* declares (undefined when that particular group didn't participate), so `in` tells
-      // "declared" apart from "declared but empty". An undeclared name (no named groups at all, or
-      // named groups that don't include this one) leaves the token as literal text, matching what
-      // `String.prototype.replace` does when the regex has zero named groups — and, by design, also
-      // when it has some but not this one, so an unresolvable `$<name>` is never silently deleted.
-      if (match.groups !== undefined && name in match.groups) {
-        return match.groups[name] ?? "";
-      }
-      return whole;
-    }
-    // Numeric: greedily prefer the two-digit group, then fall back to one digit + the literal digit.
-    const n = Number.parseInt(selector, 10);
-    if (n >= 1 && n <= groups) {
-      return match[n] ?? "";
-    }
-    if (selector.length === 2) {
-      const first = Number.parseInt(selector[0] as string, 10);
-      if (first >= 1 && first <= groups) {
-        return `${match[first] ?? ""}${selector[1]}`;
-      }
-    }
-    return whole; // an out-of-range group number is left literal, as String.replace does
-  });
-}
-
-/** Escape a literal string for use as a `RegExp` source (every regex metacharacter neutralized). */
-function escapeRegExp(literal: string): string {
-  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/**
- * Merge overlapping/touching ranges into a sorted, non-overlapping list (ascending by start).
- * Exported because it is the general invariant {@link managedRanges} relies on now that the marker
- * registry holds more than one kind: two different managed blocks (e.g. a `lore:tasks` block
- * adjacent to an `index` block) can produce ranges that touch or nest, and a clean partition for
- * {@link applyReplacement} needs them collapsed. A nested range (fully inside another) is absorbed; a
- * touching one (`start === prev.end`) is joined so no zero-width author gap is left between them.
- */
-export function mergeRanges(ranges: TextRange[]): TextRange[] {
-  if (ranges.length <= 1) {
-    return ranges;
-  }
-  const sorted = [...ranges].sort((a, b) => a.start - b.start);
-  const merged: TextRange[] = [];
-  for (const range of sorted) {
-    const last = merged[merged.length - 1];
-    if (last !== undefined && range.start <= last.end) {
-      if (range.end > last.end) {
-        merged[merged.length - 1] = { start: last.start, end: range.end };
-      }
-    } else {
-      merged.push(range);
-    }
-  }
-  return merged;
-}