@opum-ai/lore 0.1.0

package/src/core/rewrite.ts

@@ -0,0 +1,940 @@
+/**
+ * rewrite.ts — the **pure** graph-aware inbound-rewrite engine behind `lore rename` (and,
+ * next, `lore supersede`): when a concept's id/path changes, repoint **every** reference to
+ * it — body cross-links and `specs`/`supersedes`/`superseded_by` frontmatter refs — to the new
+ * location, without touching one byte of authored prose (cli-surface §rename, LORE-35 AC#1–3).
+ *
+ * ### Why a surgical string splice, not parse→stringify
+ *
+ * lore deliberately ships **no markdown serializer** (deps are only `mdast-util-from-markdown`
+ * for parsing, plus js-yaml/zod for frontmatter — ADR-0001 packaging constraint).
+ * Re-emitting a body through a stringifier would reflow prose — reindenting lists, normalizing
+ * emphasis, rewrapping — which ADR-0008 §7 forbids and AC#3 pins against. So a link's
+ * destination is rewritten by **splicing the new bytes over the old destination's byte range**,
+ * located structurally inside the parsed link node; every other byte of the body is copied
+ * verbatim.
+ *
+ * Locating that range cannot use a text search for the destination, because a parsed
+ * `node.url` is **not** byte-equal to the source it came from: `mdast-util-from-markdown`
+ * strips an angle-bracket `<…>` wrapper, decodes backslash escapes (`a\(b\).md` → `a(b).md`),
+ * and drops an optional `"title"` — while *keeping* percent-encoding. An `indexOf(node.url)`
+ * would miss (or, worse, mis-hit) the destination. Instead {@link destRangeForLink} /
+ * {@link destRangeForDefinition} walk the source from the link node's known start offset to find
+ * the exact `[start, end)` of the destination token as authored (see each for the grammar).
+ *
+ * ### What gets rewritten
+ *
+ * The affected files are computed from the graph, not a directory scan: the moved concept itself
+ * (when `move`), plus every concept that is the `from` of an edge whose `to` is the renamed
+ * concept (any {@link EdgeKind}). For each affected concept:
+ *
+ * - **Inbound files** (point *at* the renamed concept): each body link or used reference
+ *   definition that resolves to `fromId` is repointed to the new path via {@link normalizeLink}
+ *   (preserving any `#fragment`/`?query`); each `specs`/`supersedes`/`superseded_by` ref that
+ *   resolves to `fromId` is rewritten to the bare-id `toId` (the canonical frontmatter ref form).
+ * - **The moved file** (only when `move`): *all* of its outbound internal links are recomputed
+ *   against its new directory — they move with the file — so a sibling link becomes a `../`
+ *   link (or vice versa) and a self-link retargets to the new name. This is pure path
+ *   arithmetic, so it corrects even links that dangle (resolve to no concept).
+ *
+ * Resolution mirrors the bundle graph's own rules byte-for-byte ({@link bundle}'s
+ * `internalTarget` + {@link resolvePath} for a body link, `resolveRef` for frontmatter), so this
+ * engine rewrites exactly the edges the graph counts — case-sensitively, and including
+ * `resolvePath`'s `/`-absolute special case (a leading `/` resolves against the bundle root,
+ * stripped, instead of joining onto the referring file's directory — the same rule `check.ts`'s
+ * link gate applies, LORE-180).
+ *
+ * The rewritten bytes are produced by {@link serializeConcept} (frontmatter in canonical,
+ * byte-stable form; body verbatim with the splices applied), so an already-canonical concept's
+ * frontmatter round-trips unchanged and only its changed destinations/refs differ.
+ *
+ * ### Boundaries (deliberate, documented)
+ *
+ * - Only **concept** files are rewritten — a graph edge always originates at a concept. A link
+ *   to the renamed concept from a *non-concept* markdown file (a frontmatter-free `index.md`
+ *   listing's authored prose, a README) is not a graph edge and is left for `lore check` to
+ *   surface; the machine-owned `index.md` listing blocks are regenerated by the command layer
+ *   via {@link generateIndexes}, not here.
+ * - The moved file's own outbound references are recomputed for its new location — body links by
+ *   path arithmetic, and resolving frontmatter refs canonicalized to their bare (location-
+ *   independent) id. A frontmatter ref that *dangles* (resolves to no concept) is left as-is, the
+ *   same broken signal `lore check` already reports.
+ *
+ * ### Text/target mismatch reporting (LORE-262)
+ *
+ * An inbound link is always retargeted exactly as described above — the engine never *skips* a
+ * retarget, because for `lore rename` the old file is deleted, and a skipped link would become a
+ * genuinely dangling one (worse than a stale-reading text). But a link whose *visible display
+ * text* still names the OLD id (e.g. a supersession doc's own `[ADR-0005](…)` citation, now
+ * pointing at ADR-0006) is easy to leave silently misleading, so every such retarget is *also*
+ * surfaced as a {@link LinkTextMismatch} in {@link RewritePlan.textMismatches} — advisory data
+ * only, the same shape as everything else this module returns (pure, no I/O). The command layer
+ * renders each one as a stderr warning via {@link renderLinkTextMismatchWarning}. Scoped to
+ * **inbound** files only (not the moved file's own self-link retarget in `move` mode) — see
+ * {@link computeBodyEdits}'s doc comment for why.
+ *
+ * Per the core contract (lore-design §2.1) everything here is pure: a {@link BundleGraph} in, a
+ * {@link RewritePlan} out, or a `not_found`/`conflict` {@link LoreError}. No filesystem, no
+ * printing, no flags, no `process.exit` — the command layer reads the bundle, writes the plan's
+ * bytes, and performs the move/delete.
+ */
+
+import { posix, win32 } from "node:path";
+import type { Nodes } from "mdast";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { LoreError } from "../errors";
+import {
+  type BundleGraph,
+  conceptNotInBundle,
+  internalTarget,
+  nodeText,
+  REF_FIELDS,
+  resolvePath,
+  resolveRef,
+  walkMdast,
+} from "./bundle";
+import { type Concept, idFromPath, serializeConcept } from "./concept";
+import { normalizeLink } from "./links";
+import { compareCodeUnits } from "./order";
+import type { Profile } from "./profile";
+import { DOCS_DIR } from "./scaffold";
+
+/** A half-open `[start, end)` byte range within a body, locating a link destination to splice. */
+interface ByteRange {
+  readonly start: number;
+  readonly end: number;
+}
+
+/** One file the plan writes: its bundle-relative path and the new bytes (full file contents). */
+export interface RewriteWrite {
+  /** Bundle-relative path of the file to write (the moved file carries its **new** path). */
+  readonly path: string;
+  /** The complete new file contents. */
+  readonly bytes: string;
+}
+
+/**
+ * One retargeted **inbound** body link whose visible display text still names the OLD id — a
+ * text/target mismatch a naive retarget would otherwise leave silently in place (LORE-262). The
+ * link's destination is always still repointed to `to` (skipping it would leave a genuinely
+ * *dangling* link once `lore rename` deletes the old file — worse than a stale-reading text), so
+ * this is advisory data only: the caller (`commands/supersede.ts`/`commands/rename.ts`) surfaces
+ * it as a stderr warning via {@link renderLinkTextMismatchWarning} so the author can review the
+ * prose, not something the engine acts on itself.
+ */
+export interface LinkTextMismatch {
+  /** Bundle-relative path of the concept file containing the mismatched link. */
+  readonly path: string;
+  /** The link's visible display text, verbatim as authored (e.g. `"ADR-0005"`). */
+  readonly text: string;
+  /** The old id the text names (bare id, no `.md`). */
+  readonly from: string;
+  /** The new id the link's destination now points to (bare id, no `.md`). */
+  readonly to: string;
+}
+
+/**
+ * The stderr warning line for one {@link LinkTextMismatch} (LORE-262). Exported so
+ * `commands/supersede.ts` and `commands/rename.ts` — the two callers that can produce one — render
+ * byte-identical wording through a single shared function, rather than two independently-drifting
+ * copies (mirrors `state.ts`'s `renderBacklogCommitLine`, reused the same way by `rename.ts`).
+ */
+export function renderLinkTextMismatchWarning(m: LinkTextMismatch): string {
+  return `link text "${m.text}" in ${DOCS_DIR}/${m.path} still names "${m.from}", but its link now points to "${m.to}" — review the prose`;
+}
+
+/**
+ * The result of {@link rewriteInbound}: the optional file move and every file whose bytes change.
+ * `rename` is non-null only in `move` mode — it tells the command which file to write at the new
+ * path and delete at the old; the moved file's new bytes are in `writes` under its new path.
+ * `writes` is in ascending-path order for a stable, reviewable plan.
+ */
+export interface RewritePlan {
+  /** The file relocation (`move` mode only): write `to`, delete `from`. `null` in place-only mode. */
+  readonly rename: { readonly from: string; readonly to: string } | null;
+  /** Each changed file's new bytes, ascending by path. */
+  readonly writes: readonly RewriteWrite[];
+  /**
+   * Every retargeted inbound link whose text names the old id, ascending by path (each file's own
+   * entries keep document order — LORE-262). Empty when no such link was found — the overwhelmingly
+   * common case, so an ordinary rewrite carries no advisory data at all.
+   */
+  readonly textMismatches: readonly LinkTextMismatch[];
+}
+
+/** Options for {@link rewriteInbound}. */
+export interface RewriteInboundOptions {
+  /**
+   * Whether the renamed concept **relocates** (`lore rename`): its file moves `fromId`→`toId`,
+   * its own outbound links are recomputed, and `toId` must not already exist. When `false`
+   * (`lore supersede`'s `--rewrite-links`), nothing moves — only inbound references are
+   * repointed — and `toId` is expected to already exist (the command validates that).
+   */
+  readonly move?: boolean;
+  /**
+   * Whether to repoint `specs`/`supersedes`/`superseded_by` **frontmatter** refs as well as body
+   * links. Defaults to `true` (`lore rename`: the old path vanishes, so every ref to it — structured
+   * or prose — must move or dangle). `lore supersede` passes `false`: it **preserves** the old file,
+   * so a third party's `supersedes`/`superseded_by`/`specs` ref to it is still a valid historical
+   * record, not a dead pointer — repointing it would fabricate a relationship that never happened.
+   * Only body cross-links (the navigational "go read this" edges) are redirected to the successor.
+   */
+  readonly rewriteFrontmatterRefs?: boolean;
+  /**
+   * Concept ids the caller will rewrite itself and the engine must therefore leave untouched (never
+   * parsed, serialized, or emitted in the plan). `lore supersede` excludes the two **principals**
+   * (it wires their frontmatter directly — repointing the successor's own link to its predecessor,
+   * or the preserved old doc's self-link, would be wrong) and the machine-owned `index.md`/`log.md`
+   * hubs (regenerated by `lore sync`, never hand-rewritten). Empty by default (`lore rename` rewrites
+   * everything its graph reaches). If this set contains `fromId` itself in `move` mode, the returned
+   * plan's `rename` is `null` too (LORE-164) — the caller owns that file entirely, including whether
+   * it moves, so the engine cannot claim a move it never wrote the destination bytes for.
+   */
+  readonly exclude?: ReadonlySet<string>;
+  /**
+   * The active profile, forwarded to every {@link serializeConcept} call this engine makes so a
+   * rewritten concept's re-emitted frontmatter validates against the SAME profile the caller's own
+   * `loadBundle` used to read the bundle in the first place — never silently falling back to the
+   * built-in default when the caller has a project-specific `.lore/profile.toml` (LORE-88). Also the
+   * profile a caller should re-parse these bytes with afterward (e.g. `rename.ts`'s
+   * `buildPostRenameGraph`), so a concept is never written under one profile and re-read under
+   * another. Defaults to {@link serializeConcept}'s own default (the built-in profile), so a caller
+   * that does not opt in is unaffected (LORE-88 AC#5).
+   */
+  readonly profile?: Profile;
+}
+
+/** The shared empty exclude set, so the common (no-exclude) path allocates nothing. */
+const NO_EXCLUDE: ReadonlySet<string> = new Set();
+
+/**
+ * Compute the {@link RewritePlan} to repoint every reference to `fromId` onto `toId`.
+ *
+ * In `move` mode (`lore rename`) the concept relocates: `fromId` must exist, `toId` must not,
+ * inbound references are repointed, and the moved file's own outbound links are recomputed for
+ * its new directory. Without `move` (`lore supersede`) the concept stays put and only inbound
+ * references are repointed.
+ *
+ * @throws LoreError `not_found` when `fromId` names no concept; `conflict` (move mode) when
+ *   `toId` already names a concept.
+ */
+export function rewriteInbound(
+  graph: BundleGraph,
+  fromId: string,
+  toId: string,
+  options: RewriteInboundOptions = {},
+): RewritePlan {
+  const move = options.move ?? false;
+  const rewriteRefs = options.rewriteFrontmatterRefs ?? true;
+  const exclude = options.exclude ?? NO_EXCLUDE;
+  const profile = options.profile;
+  assertConfinedToBundle(fromId, "fromId");
+  assertConfinedToBundle(toId, "toId");
+  const from = idFromPath(fromId);
+  const to = idFromPath(toId);
+
+  const fromConcept = graph.concepts.get(from);
+  if (fromConcept === undefined) {
+    throw conceptNotInBundle(from);
+  }
+  if (move && graph.concepts.has(to)) {
+    throw new LoreError(
+      "conflict",
+      `cannot rename to "${to}": a concept already exists there`,
+      "choose an id/path that is not already taken, or supersede instead of rename",
+      { id: to },
+    );
+  }
+
+  const fromPath = fromConcept.path;
+  const toPath = `${to}.md`;
+
+  // Affected files: the moved concept (always, in move mode) plus every concept with an edge
+  // pointing at it. A Set folds a file that both moves and self-references into one rewrite.
+  const affected = new Set<string>();
+  if (move) {
+    affected.add(from);
+  }
+  for (const edge of graph.edges) {
+    if (edge.to === from) {
+      affected.add(edge.from);
+    }
+  }
+
+  const writes: RewriteWrite[] = [];
+  const textMismatches: LinkTextMismatch[] = [];
+  for (const id of affected) {
+    if (exclude.has(id)) {
+      continue; // the caller rewrites this file itself — never parse, serialize, or plan it here
+    }
+    const concept = graph.concepts.get(id);
+    if (concept === undefined) {
+      continue; // an edge's `from` is always a real concept; this is unreachable belt-and-braces
+    }
+    const isMoved = move && id === from;
+    const rewritten = rewriteConcept(concept, graph, { from, to, fromPath, toPath, isMoved, rewriteRefs }, profile);
+    if (rewritten.bytes === null && !isMoved) {
+      continue; // nothing changed in this file and it does not move — leave it untouched
+    }
+    const bytes = rewritten.bytes ?? serializeConcept(concept, { profile });
+    writes.push({ path: isMoved ? toPath : concept.path, bytes });
+    textMismatches.push(...rewritten.textMismatches);
+  }
+
+  writes.sort((a, b) => compareCodeUnits(a.path, b.path));
+  // Stable sort: each file's own mismatches keep the document order they were collected in.
+  textMismatches.sort((a, b) => compareCodeUnits(a.path, b.path));
+  // `rename` must only claim the move when the source's own rewrite actually ran: if `exclude`
+  // contains `from`, the loop above `continue`d past it before ever pushing its destination write
+  // (the exclude contract — never parsed, serialized, or planned here), so a `rename` announcing the
+  // move would leave `writes` with no entry at `toPath` for a caller to act on (LORE-164).
+  const rename = move && !exclude.has(from) ? { from: fromPath, to: toPath } : null;
+  return { rename, writes, textMismatches };
+}
+
+/**
+ * Reject a `fromId`/`toId` that would resolve outside the `docs/` bundle root — closes the
+ * traversal gap for every {@link rewriteInbound} caller (`lore rename`, `lore supersede`) at the
+ * one shared layer both funnel through (LORE-80). Checked on the RAW caller-supplied value,
+ * before {@link idFromPath} ever runs.
+ *
+ * An absolute path is checked against BOTH `posix.isAbsolute` and `win32.isAbsolute` — this ships
+ * as a compiled binary for both platforms from the same source, so a Windows drive-letter id
+ * (inert POSIX-side, genuinely absolute on a win32 run) must be rejected regardless of which
+ * platform is running (the LORE-69 cross-platform-normalize convention).
+ *
+ * A relative escape is caught by {@link escapesRoot}, which walks segments split on EITHER `/` or
+ * `\` — not just `posix.normalize`'s own forward-slash-only splitting. `idFromPath`'s
+ * `posix.normalize` treats a backslash as an ordinary filename character, not a separator, so a
+ * relative traversal spelled `..\pwned` survives it completely unchanged and would trip neither
+ * `posix.isAbsolute` (it isn't) nor `win32.isAbsolute` (it's relative, not absolute — that check
+ * only matches a drive-letter/UNC/leading-separator *absolute* form). Yet the command layer's
+ * eventual write (`commands/rename.ts`, via the platform-native `path.join`) treats `\` as a
+ * separator on an actual Windows run, so `..\pwned` is exactly as real an escape there as
+ * `../pwned` is everywhere else — this check must catch it on every platform it runs on, not only
+ * the one it happens to be compiled for.
+ */
+function assertConfinedToBundle(id: string, label: "fromId" | "toId"): void {
+  if (posix.isAbsolute(id) || win32.isAbsolute(id) || escapesRoot(id) || isDriveRelative(id) || resolvesToRoot(id)) {
+    throw new LoreError(
+      "validation",
+      `${label} "${id}" resolves outside the docs/ bundle root`,
+      "pass an id that stays inside the docs/ bundle",
+      { id },
+    );
+  }
+}
+
+/**
+ * Whether `id` is a Windows drive-relative reference — a drive letter and colon with **no**
+ * following separator (e.g. `"C:foo"`, real Windows syntax meaning "relative to that drive's
+ * current directory"). Distinct from an absolute `"C:\\foo"`/`"C:/foo"` form, which
+ * `win32.isAbsolute` already rejects: `win32.isAbsolute("C:foo")` is `false` (Node correctly
+ * implements this Windows quirk), and `posix.isAbsolute("C:foo")` is also `false`, so nothing
+ * else {@link assertConfinedToBundle} already checks catches this shape (LORE-95). Exported so
+ * `commands/rename.ts`'s own argument-parsing-layer guard can reuse this exact check, mirroring
+ * how {@link escapesRoot} itself is already shared rather than re-derived per call site.
+ */
+export function isDriveRelative(id: string): boolean {
+  return /^[A-Za-z]:(?![\\/])/.test(id);
+}
+
+/**
+ * Whether `id` normalizes to the bundle root itself — an empty string, `"."`, or a self-cancelling
+ * relative path like `"sub/.."` whose segments net out to zero remaining depth. {@link escapesRoot}
+ * alone doesn't catch this: none of these ever climb *above* where they started (the property
+ * `escapesRoot` checks) — they simply cancel out to nothing. Left uncaught, `idFromPath`'s
+ * `posix.normalize` folds any of these to `"."`, and a caller building `` `${to}.md` `` from that
+ * gets the literal string `"..md"` — a hidden dotfile silently created at the bundle root instead
+ * of a rejection (LORE-95). Shares `escapesRoot`'s own segment-walk convention (split on either
+ * `/` or `\`) for the identical cross-platform reason documented there; a segment that merely
+ * *starts with* `".."` (e.g. `"..foo"`) is a real, non-cancelling segment and does not count
+ * towards depth going down, matching `escapesRoot`'s own exact-match care. Exported for reuse by
+ * `commands/rename.ts`'s own argument-parsing-layer guard, mirroring how `escapesRoot` itself is
+ * already shared.
+ */
+export function resolvesToRoot(id: string): boolean {
+  let depth = 0;
+  for (const segment of id.split(/[\\/]+/)) {
+    if (segment === "" || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      // A genuine climb-above-start is escapesRoot's own concern, already checked separately;
+      // clamping at 0 here keeps this function correct standalone regardless of call order.
+      depth = Math.max(0, depth - 1);
+    } else {
+      depth++;
+    }
+  }
+  return depth === 0;
+}
+
+/**
+ * Whether walking `id`'s segments — split on a run of either `/` or `\`, since either can act as
+ * a separator depending on which platform's binary eventually resolves it (see
+ * {@link assertConfinedToBundle}) — climbs above the directory `id` starts in. A literal `..`
+ * segment always means "parent directory": no real filesystem, on either platform, permits a
+ * file or directory literally named `..`, so this can never misfire on a genuine bundle id — nor
+ * reject a real segment that merely *starts* with `..` (e.g. `..foo/bar`), since that segment
+ * does not equal `..` exactly (mirrors `new.ts`'s `resolveOutPath`'s own documented care).
+ *
+ * Exported so a command layer can reuse this exact, already-review-tested traversal check for its
+ * own defense-in-depth confinement guard (e.g. `commands/rename.ts`'s `newId`, LORE-79) instead of
+ * re-deriving the same security-sensitive segment walk a second time.
+ */
+export function escapesRoot(id: string): boolean {
+  let depth = 0;
+  for (const segment of id.split(/[\\/]+/)) {
+    if (segment === "" || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      if (depth === 0) {
+        return true;
+      }
+      depth--;
+    } else {
+      depth++;
+    }
+  }
+  return false;
+}
+
+/** The resolved coordinates one concept's rewrite needs (`from`/`to` are normalized ids). */
+interface RewriteContext {
+  readonly from: string;
+  readonly to: string;
+  readonly fromPath: string;
+  readonly toPath: string;
+  /** Whether this concept is the relocating one (recompute all its outbound links). */
+  readonly isMoved: boolean;
+  /** Whether to repoint `specs`/`supersedes`/`superseded_by` frontmatter refs (false for `lore supersede`). */
+  readonly rewriteRefs: boolean;
+}
+
+/** {@link rewriteConcept}'s result: the new bytes (`null` when nothing changed) plus any {@link LinkTextMismatch}es found. */
+interface ConceptRewrite {
+  readonly bytes: string | null;
+  readonly textMismatches: readonly LinkTextMismatch[];
+}
+
+/**
+ * Rewrite one affected concept, returning its new serialized bytes (`null` when nothing in it
+ * changed — no body destination and no frontmatter ref needed rewriting) plus every
+ * {@link LinkTextMismatch} its body edits surfaced. The moved file always yields bytes from its
+ * caller even on a `null` here, because it still relocates.
+ */
+function rewriteConcept(
+  concept: Concept,
+  graph: BundleGraph,
+  ctx: RewriteContext,
+  profile: Profile | undefined,
+): ConceptRewrite {
+  const dir = posix.dirname(concept.path);
+  const { edits, textMismatches } = computeBodyEdits(concept.body, concept.path, ctx, graph.concepts);
+  const newBody = applyBodyEdits(concept.body, edits);
+
+  // `lore supersede` (rewriteRefs=false) preserves the old file, so a third party's frontmatter ref
+  // to it stays a valid historical record — only body links are redirected to the successor.
+  const newFrontmatter = ctx.rewriteRefs ? remapFrontmatterRefs(concept.frontmatter, dir, graph, ctx) : null;
+  const frontmatterChanged = newFrontmatter !== null;
+
+  if (newBody === concept.body && !frontmatterChanged) {
+    return { bytes: null, textMismatches: [] };
+  }
+  const next: Concept = {
+    ...concept,
+    frontmatter: frontmatterChanged ? newFrontmatter : concept.frontmatter,
+    body: newBody,
+  };
+  return { bytes: serializeConcept(next, { profile }), textMismatches };
+}
+
+// ── Body link rewriting ──────────────────────────────────────────────────────────
+
+/** A planned destination splice: the source byte range to replace and its replacement text. */
+interface BodyEdit extends ByteRange {
+  readonly dest: string;
+}
+
+/** {@link computeBodyEdits}'s result: the destination splices plus any {@link LinkTextMismatch}es they surfaced. */
+interface BodyEditsResult {
+  readonly edits: BodyEdit[];
+  readonly textMismatches: LinkTextMismatch[];
+}
+
+/**
+ * Compute every destination splice for one concept body. The body is parsed once; each inline
+ * link and each *used* reference definition (a definition an actual `linkReference` points at,
+ * mirroring how the bundle graph counts edges — an orphan definition is not an edge) is a
+ * candidate. For the moved file, every internal link is recomputed against the new directory; for
+ * an inbound file, only links that resolve to `fromId` are repointed. An edit is emitted only when
+ * the new destination differs from the authored bytes, so a canonical link the move leaves in
+ * place produces no churn.
+ *
+ * For an **inbound** file (`!ctx.isMoved`) — the code path both `lore supersede --rewrite-links`
+ * and `lore rename` funnel every *other* affected concept through — each emitted edit is also
+ * checked against {@link textNamesOldId}: if the link's visible display text still names the OLD
+ * id, a {@link LinkTextMismatch} is recorded alongside it. The destination is retargeted exactly
+ * as before either way (LORE-262 AC#2: no regression) — this only adds advisory data the caller
+ * surfaces, never changes what gets rewritten. The moved file's own outbound links are exempt: a
+ * self-link's destination follows the file to its new location by construction, and most of the
+ * candidates recomputed there aren't edges to `fromId` at all (see {@link newDestPathFor}), so
+ * "does this text name the old id" isn't a meaningful question to ask there.
+ */
+function computeBodyEdits(
+  body: string,
+  conceptPath: string,
+  ctx: RewriteContext,
+  byId: ReadonlyMap<string, Concept>,
+): BodyEditsResult {
+  const tree = fromMarkdown(body);
+  const links: Nodes[] = [];
+  const usedIdentifiers = new Set<string>();
+  const firstDefinition = new Map<string, Nodes>();
+  const allDefinitions: Nodes[] = [];
+  // The visible text of a reference-style link lives on its `linkReference` node, not on the
+  // `definition` it resolves to — collected here, first occurrence wins, while the tree is walked
+  // anyway for `usedIdentifiers` (LORE-262: needed only to check a definition-candidate's text
+  // below, but cheap to always collect).
+  const linkRefText = new Map<string, string>();
+  walkMdast(tree, (node) => {
+    if (node.type === "link") {
+      links.push(node);
+    } else if (node.type === "linkReference") {
+      usedIdentifiers.add(node.identifier);
+      if (!linkRefText.has(node.identifier)) {
+        linkRefText.set(node.identifier, nodeText(node));
+      }
+    } else if (node.type === "definition") {
+      allDefinitions.push(node);
+      if (!firstDefinition.has(node.identifier)) {
+        firstDefinition.set(node.identifier, node); // first definition wins, as CommonMark resolves
+      }
+    }
+  });
+
+  // Candidate destinations in document order: inline links, then reference definitions. For the
+  // moved file *every* definition is recomputed (it moves with the file, even an orphan/unused one
+  // that renders as nothing); for an inbound file only the **used** definitions are edges, so an
+  // orphan definition is left alone — mirroring how the bundle graph counts edges.
+  const candidates: Array<{ node: Nodes; isDefinition: boolean }> = links.map((node) => ({
+    node,
+    isDefinition: false,
+  }));
+  if (ctx.isMoved) {
+    for (const def of allDefinitions) {
+      candidates.push({ node: def, isDefinition: true });
+    }
+  } else {
+    for (const identifier of usedIdentifiers) {
+      const def = firstDefinition.get(identifier);
+      if (def !== undefined) {
+        candidates.push({ node: def, isDefinition: true });
+      }
+    }
+  }
+
+  // Only an inbound file's retargets are checked for a stale text citation (see the doc comment
+  // above) — computed once, not per-candidate.
+  const oldIdCandidates = ctx.isMoved ? null : oldIdNameCandidates(ctx.from);
+
+  const edits: BodyEdit[] = [];
+  const textMismatches: LinkTextMismatch[] = [];
+  for (const { node, isDefinition } of candidates) {
+    const newPath = newDestPathFor((node as { url: string }).url, conceptPath, ctx, byId);
+    if (newPath === null) {
+      continue; // external/non-.md, or (inbound) not a link to the renamed concept
+    }
+    const range = isDefinition ? destRangeForDefinition(body, node) : destRangeForLink(body, node);
+    if (range === null) {
+      continue; // defensive: a well-formed link/definition always locates, but never corrupt on a miss
+    }
+    // Append the destination's #fragment/?query taken from the **source** bytes (not the decoded
+    // node.url), so an authored fragment — even one carrying escapes — is preserved byte-for-byte
+    // (AC#3); only the path portion is replaced with the canonical form.
+    const src = body.slice(range.start, range.end);
+    const newDest = newPath + sourceSuffix(src);
+    if (src === newDest) {
+      continue; // already the canonical bytes — no edit (the move left this link in place)
+    }
+    edits.push({ start: range.start, end: range.end, dest: newDest });
+
+    if (oldIdCandidates !== null) {
+      // Reference-style: the visible text is the linkReference's, looked up by identifier — a
+      // definition candidate here always has one (only *used* definitions are candidates when
+      // `!ctx.isMoved`), so this lookup cannot miss. Inline: the text lives on the link node itself.
+      const text = isDefinition ? (linkRefText.get((node as { identifier: string }).identifier) ?? "") : nodeText(node);
+      if (textNamesOldId(text, oldIdCandidates)) {
+        textMismatches.push({ path: conceptPath, text, from: ctx.from, to: ctx.to });
+      }
+    }
+  }
+  return { edits, textMismatches };
+}
+
+/**
+ * Candidate substrings a link's visible text might contain to be "naming" `fromId` (LORE-262): the
+ * bare id itself, its basename, and — for an `NNNN-slug` id (lore's ADR/RFC-style numbering
+ * convention, e.g. `adr/0005-cli-contract`) — the bare digits and `<dirname>-<digits>` (so a prose
+ * citation like `"ADR-0005"` is caught even though the id's own basename is `0005-cli-contract`,
+ * not `adr-0005`). This is a deliberately pragmatic heuristic, not a full NLP match: it cannot
+ * catch every phrasing (a citation with no digits at all, an id with no numeric prefix referenced
+ * only by an unrelated-looking title) — see {@link textNamesOldId} for how each candidate is
+ * matched against the text.
+ */
+function oldIdNameCandidates(fromId: string): string[] {
+  const candidates = new Set<string>([fromId]);
+  const base = posix.basename(fromId);
+  candidates.add(base);
+  const numeric = base.match(/^(\d+)-/);
+  if (numeric?.[1] !== undefined) {
+    const digits = numeric[1];
+    candidates.add(digits);
+    const dir = posix.basename(posix.dirname(fromId));
+    if (dir !== "" && dir !== ".") {
+      candidates.add(`${dir}-${digits}`);
+    }
+  }
+  // A short candidate (e.g. a one/two-character id or digit run) is dropped: matching it against
+  // arbitrary prose would produce far more noise than signal.
+  return [...candidates].filter((c) => c.length >= 3);
+}
+
+/**
+ * Whether `text` names one of `candidates` — a case-insensitive check, applied as a plain
+ * substring for a candidate containing `/` (a full bundle id, which essentially never collides
+ * with unrelated prose) and as a **word-boundary** regex match otherwise (a bare id/digits/slug
+ * candidate, which — unlike a full id — could otherwise false-positive inside a longer unrelated
+ * word or number).
+ */
+function textNamesOldId(text: string, candidates: readonly string[]): boolean {
+  const lower = text.toLowerCase();
+  for (const candidate of candidates) {
+    if (candidate.includes("/")) {
+      if (lower.includes(candidate.toLowerCase())) {
+        return true;
+      }
+      continue;
+    }
+    if (new RegExp(`\\b${escapeRegExp(candidate)}\\b`, "i").test(text)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Escape every regex metacharacter in `s`, so a candidate built from arbitrary id text is safe to interpolate into a `RegExp`. */
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * The canonical **path** (no `#fragment`/`?query`) one link should point at after the rename, or
+ * `null` when the link is not a target: external, non-`.md`, or — for an inbound file — not a link
+ * to the renamed concept. Classification and id derivation reuse the bundle graph's own
+ * {@link internalTarget}/{@link resolvePath} — including `resolvePath`'s `/`-absolute special
+ * case (leading `/` strips and resolves against the bundle root, rather than joining onto `dir`
+ * like a relative segment) — so this rewrites exactly the edges the graph counts, and a `/`-absolute
+ * link is never mis-classified against a same-string decoy that merely happens to sit at the
+ * dir-joined path (LORE-180).
+ */
+function newDestPathFor(
+  url: string,
+  conceptPath: string,
+  ctx: RewriteContext,
+  byId: ReadonlyMap<string, Concept>,
+): string | null {
+  const decoded = internalTarget(url);
+  if (decoded === null) {
+    return null; // external, anchor-only, or non-.md — not an internal concept link
+  }
+  const dir = posix.dirname(conceptPath);
+  const targetId = resolvePath(decoded, dir, byId);
+
+  // normalizeLink's precondition is the repo-relative coordinate space (both operands rooted at
+  // the repo, `docs/…`), not the bundle-relative one `conceptPath`/`ctx.to` use as graph ids. The
+  // two coincide for a link that stays inside the bundle (a constant `docs/` prefix cancels out of
+  // a relative-path computation), which is why this only ever surfaced for a link that escapes the
+  // bundle root — e.g. a Story's managed task block linking `backlog/tasks/…` (LORE-68): resolving
+  // `decoded`/`ctx.toPath` in bundle-relative space silently drops the `docs/` hop, truncating the
+  // rewritten link by one `../` segment.
+  const repoDir = `${DOCS_DIR}/${dir}`;
+  const repoToPath = `${DOCS_DIR}/${ctx.toPath}`;
+
+  if (ctx.isMoved) {
+    // The file moves: recompute the link against its new directory. A self-link follows the file
+    // to its new path; any other target keeps its location (pure path arithmetic, so a dangling
+    // link is corrected too) — joined with the same leading-`/`-aware rule as `targetId` above, so
+    // a `/`-absolute sibling link isn't mis-resolved into the file's old directory (LORE-180: plain
+    // `posix.join(repoDir, decoded)` does NOT treat an absolute second segment specially — it just
+    // concatenates — so this must special-case it explicitly rather than lean on `posix.join`).
+    const targetPath =
+      targetId === ctx.from
+        ? repoToPath
+        : posix.normalize(decoded.startsWith("/") ? `${DOCS_DIR}/${decoded.slice(1)}` : posix.join(repoDir, decoded));
+    // A link authored with more `../` segments than the file's depth resolves ABOVE the repo
+    // root: `targetPath` (already normalized, repo-relative) equals `..` or starts with `../`.
+    // normalizeLink roots both operands at a fixed virtual `/` (links.ts) and would silently
+    // clamp that surplus `..`, quietly retargeting an already-non-portable link rather than
+    // preserving it. Bail out with no edit instead, so the original authored bytes survive the
+    // move verbatim (the `decoded.startsWith("/")` sub-branch above always yields a `docs/…`
+    // path and can never trigger this).
+    if (targetPath === ".." || targetPath.startsWith("../")) {
+      return null;
+    }
+    return normalizeLink(repoToPath, targetPath);
+  }
+  if (targetId !== ctx.from) {
+    return null; // an inbound file only repoints links to the renamed concept
+  }
+  // An inbound link is recomputed from *this* file's location to the moved concept's new path.
+  return normalizeLink(`${DOCS_DIR}/${conceptPath}`, repoToPath);
+}
+
+/**
+ * The `#fragment`/`?query` suffix of a source destination token, preserved verbatim: the
+ * angle-bracket `<…>` wrapper (which the canonical form drops) is stripped, then everything from
+ * the first `#`/`?` onward is returned — the authored bytes, never the decoded `node.url`.
+ */
+function sourceSuffix(src: string): string {
+  const inner = src.startsWith("<") && src.endsWith(">") ? src.slice(1, -1) : src;
+  const hash = inner.indexOf("#");
+  const question = inner.indexOf("?");
+  // The first of the two delimiters that is present (a `?` living inside a `#fragment` is not a query).
+  const cut = hash < 0 ? question : question < 0 ? hash : Math.min(hash, question);
+  return cut < 0 ? "" : inner.slice(cut);
+}
+
+/** Apply destination splices right-to-left (descending start) so earlier edits don't shift later offsets. */
+function applyBodyEdits(body: string, edits: BodyEdit[]): string {
+  if (edits.length === 0) {
+    return body;
+  }
+  const ordered = [...edits].sort((a, b) => b.start - a.start);
+  let result = body;
+  for (const edit of ordered) {
+    result = result.slice(0, edit.start) + edit.dest + result.slice(edit.end);
+  }
+  return result;
+}
+
+// ── Destination range location (structural, not a text search) ─────────────────────
+
+/**
+ * The `[start, end)` byte range of an **inline** link's destination token (`[label](DEST)` or
+ * `[label](<DEST>)`, with an optional `"title"` after `DEST`), located structurally from the
+ * link node's offsets — because `node.url` is not byte-equal to the source (see the module
+ * header). Returns the full token including a `<…>` wrapper (so it is replaced by the canonical,
+ * wrapper-free form) and any `#fragment`/`?query`, but excludes a following `"title"`. `null` if
+ * the structure cannot be located (never expected for a parsed link).
+ */
+function destRangeForLink(body: string, node: Nodes): ByteRange | null {
+  const span = positionOf(node);
+  if (span === null) {
+    return null;
+  }
+  // End of the label content: the last child's end offset, or just past `[` for an empty label.
+  const contentEnd = maxChildEnd(node) ?? span.start + 1;
+  const rb = body.indexOf("]", contentEnd); // the label's closing `]`
+  if (rb === -1 || body[rb + 1] !== "(") {
+    return null;
+  }
+  return scanDestination(body, rb + 2, span.end, true);
+}
+
+/**
+ * The `[start, end)` byte range of a **reference definition**'s destination (`[label]: DEST
+ * "title"`), located structurally from the node's offsets. Unlike an inline link, the raw form
+ * has no enclosing `()`, so the destination ends at whitespace (a following title) or the node's
+ * end — not at a closing paren. `null` if the structure cannot be located.
+ *
+ * Unlike {@link destRangeForLink}, a `definition` node carries no parsed `children` to derive the
+ * label's end from structurally (mdast gives only its decoded `identifier`/`label` strings, whose
+ * lengths are not byte-equal to the raw source once escapes are involved — the same reason
+ * `node.url` can't drive a text search, see the module header) — so the closing `]` is located by
+ * an escape-aware raw scan ({@link findLabelClose}) instead of a plain `indexOf`, which would
+ * match an escaped `\]` *inside* the label rather than the real closing bracket (LORE-87).
+ */
+function destRangeForDefinition(body: string, node: Nodes): ByteRange | null {
+  const span = positionOf(node);
+  if (span === null) {
+    return null;
+  }
+  const rb = findLabelClose(body, span.start + 1, span.end); // the label's closing `]`
+  if (rb === -1) {
+    return null;
+  }
+  const colon = body.indexOf(":", rb);
+  if (colon === -1) {
+    return null;
+  }
+  return scanDestination(body, colon + 1, span.end, false);
+}
+
+/**
+ * The index of a reference definition's label-closing `]`, scanned from just after the opening
+ * `[` (`from`) and honoring `\` escapes — the same escape convention {@link scanDestination}
+ * applies to a destination, so `\]` inside the label is skipped rather than mistaken for the real
+ * closing bracket (LORE-87). `-1` if none is found before `end`.
+ */
+function findLabelClose(body: string, from: number, end: number): number {
+  let j = from;
+  while (j < end) {
+    if (body[j] === "\\") {
+      j += 2;
+      continue;
+    }
+    if (body[j] === "]") {
+      return j;
+    }
+    j++;
+  }
+  return -1;
+}
+
+/**
+ * Scan a link destination starting at `from` (just after `(` for an inline link, or after `:`
+ * for a definition), bounded by `end` (the node's end offset). Leading whitespace is skipped;
+ * then either an angle-bracket `<…>` form (scanned to its closing `>`, honoring `\` escapes) or
+ * a raw form (honoring `\` escapes and — for an inline link — balanced `()`, stopping at
+ * unescaped whitespace before a title, or at the inline link's closing `)`). `inline` selects
+ * whether an unescaped depth-0 `)` ends the destination.
+ */
+function scanDestination(body: string, from: number, end: number, inline: boolean): ByteRange | null {
+  let i = from;
+  while (i < end && isWhitespace(body[i])) {
+    i++;
+  }
+  if (i >= end) {
+    return null;
+  }
+  const start = i;
+  if (body[i] === "<") {
+    let j = i + 1;
+    while (j < end && body[j] !== ">") {
+      j += body[j] === "\\" ? 2 : 1;
+    }
+    return { start, end: Math.min(j + 1, end) }; // include the closing `>`
+  }
+  let depth = 0;
+  let j = i;
+  while (j < end) {
+    const c = body[j];
+    if (c === "\\") {
+      j += 2;
+      continue;
+    }
+    if (isWhitespace(c)) {
+      break; // a title (or nothing) follows
+    }
+    if (c === "(") {
+      depth++;
+    } else if (c === ")") {
+      if (inline && depth === 0) {
+        break; // the inline link's closing `)`
+      }
+      if (depth > 0) {
+        depth--;
+      }
+    }
+    j++;
+  }
+  return { start, end: Math.min(j, end) };
+}
+
+/** Whether `c` is ASCII whitespace that bounds a link destination (space, tab, newline, CR, FF). */
+function isWhitespace(c: string | undefined): boolean {
+  return c === " " || c === "\t" || c === "\n" || c === "\r" || c === "\f";
+}
+
+/** The max end offset among a node's direct children, or `null` when it has none (an empty label). */
+function maxChildEnd(node: Nodes): number | null {
+  if (!("children" in node) || node.children.length === 0) {
+    return null;
+  }
+  let max = 0;
+  let seen = false;
+  for (const child of node.children) {
+    const span = positionOf(child);
+    if (span !== null) {
+      max = Math.max(max, span.end);
+      seen = true;
+    }
+  }
+  return seen ? max : null;
+}
+
+/** A node's `[start, end)` source offsets, or `null` when position info is absent (defensive). */
+function positionOf(node: Nodes): ByteRange | null {
+  const position = node.position;
+  if (position?.start.offset === undefined || position.end.offset === undefined) {
+    return null;
+  }
+  return { start: position.start.offset, end: position.end.offset };
+}
+
+// ── Frontmatter ref rewriting ──────────────────────────────────────────────────────
+
+/**
+ * Return a new frontmatter object with the `specs`/`supersedes`/`superseded_by` refs rewritten, or
+ * `null` when none changed. A field may be a single ref or a list — both shapes are preserved, and
+ * a non-matching item (including a non-string producer value) is copied verbatim. The original
+ * object is never mutated (the graph snapshot stays intact). The ref fields iterated are the
+ * graph's own {@link REF_FIELDS}, so a future ref kind cannot be added as an edge without also
+ * being rewritten here.
+ */
+function remapFrontmatterRefs(
+  frontmatter: Record<string, unknown>,
+  dir: string,
+  graph: BundleGraph,
+  ctx: RewriteContext,
+): Record<string, unknown> | null {
+  let changed = false;
+  const next: Record<string, unknown> = { ...frontmatter };
+  for (const field of REF_FIELDS) {
+    const value = frontmatter[field];
+    if (value === undefined) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const mapped = value.map((item) => remapRefItem(item, dir, graph, ctx));
+      if (mapped.some((item, i) => item !== value[i])) {
+        next[field] = mapped;
+        changed = true;
+      }
+    } else {
+      const mapped = remapRefItem(value, dir, graph, ctx);
+      if (mapped !== value) {
+        next[field] = mapped;
+        changed = true;
+      }
+    }
+  }
+  return changed ? next : null;
+}
+
+/**
+ * Rewrite one frontmatter ref item, reusing the bundle graph's own {@link resolveRef} (which trims
+ * and classifies exactly as the edge collector does, so this repoints exactly the refs the graph
+ * counts). A non-string or a dangling ref is returned unchanged. For an **inbound** file only a ref
+ * that resolves to the renamed concept is rewritten (to the bare-id `to`). For the **moved** file
+ * every resolving ref is canonicalized to its bare id — which both repoints a self-ref to `to` and
+ * corrects a relative-path ref to *another* concept that the move would otherwise leave pointing at
+ * the wrong location (the body-link recompute does the analogous fix); an already-bare-id ref maps
+ * to itself, so it is left byte-identical.
+ */
+function remapRefItem(item: unknown, dir: string, graph: BundleGraph, ctx: RewriteContext): unknown {
+  if (typeof item !== "string") {
+    return item;
+  }
+  const resolved = resolveRef(item, dir, graph.concepts);
+  if (resolved === null) {
+    return item; // external or dangling — not a concept ref to repoint
+  }
+  if (!ctx.isMoved) {
+    return resolved === ctx.from ? ctx.to : item;
+  }
+  return resolved === ctx.from ? ctx.to : resolved; // moved file: canonicalize to bare id
+}