blume 1.5.2 → 1.6.0

package/src/core/sources/normalize.ts

@@ -5,9 +5,15 @@ import { extname } from "pathe";
 
 import { withBasePath } from "../base-path.ts";
 import { diagnosticsFromIssues, diagnosticsFromZod } from "../diagnostics.ts";
+import { occupySlug, parseHeadingMarkers } from "../heading-markers.ts";
 import { localePlacement, localizeRoute } from "../i18n.ts";
 import { pageMetaSchema } from "../schema.ts";
-import type { FrontmatterExtend, PageMeta } from "../schema.ts";
+import type {
+  FrontmatterExtend,
+  PageMeta,
+  ResolvedI18nConfig,
+} from "../schema.ts";
+import { trimChar } from "../trim.ts";
 import type { Diagnostic, Heading, PageLink, PageRecord } from "../types.ts";
 import { detectVersionRef, versionizeRoute } from "../versions.ts";
 import type { NormalizeContext, SourceEntry } from "./types.ts";
@@ -110,7 +116,11 @@ interface MappedRoute {
   route: string;
 }
 
-/** Convert a content-root-relative path into URL + nav metadata. */
+/**
+ * Convert a content-root-relative path into URL + nav metadata. Not exported:
+ * a source that needs to predict a route goes through
+ * {@link resolveEntryRoute}, so there is exactly one derivation.
+ */
 const mapRoute = (relativePath: string): MappedRoute => {
   const withoutExt = relativePath.slice(
     0,
@@ -129,41 +139,42 @@ const mapRoute = (relativePath: string): MappedRoute => {
   return { groups, route, segments };
 };
 
-// CommonMark allows backtick *and* tilde fences. The scanners track which
-// delimiter opened the current fence (`null` when outside one) so a ``` line
-// inside a ~~~ block is content, not a toggle — see `nextFenceState`.
-const CODE_FENCE = /^(?<delimiter>```|~~~)/u;
+// CommonMark allows backtick *and* tilde fences, three or more characters
+// long. The scanners track which delimiter opened the current fence and how
+// long its run was (`null` when outside one), so a ``` line inside a ~~~
+// block — or inside a ````-delimited block (the wrapper `codeBlockLines`
+// emits around code that contains its own ``` fence) — is content, not a
+// toggle. See `nextFenceState`.
+const CODE_FENCE = /^(?<run>`{3,}|~{3,})/u;
 
-/** The fence delimiter opening the current code block, or null outside one. */
-export type FenceState = "```" | "~~~" | null;
+/** The open fence's delimiter char and run length, or null outside one. */
+export type FenceState = { delimiter: "`" | "~"; length: number } | null;
 
 /**
  * Advance the fenced-code state for one line: an opening fence records its
- * delimiter, only the matching delimiter closes it, and any other line leaves
- * the state untouched.
+ * delimiter and run length, only a run of the same character at least as long
+ * closes it (CommonMark), and any other line leaves the state untouched.
  */
 export const nextFenceState = (line: string, fence: FenceState): FenceState => {
   const trimmed = line.trimStart();
-  const delimiter = trimmed.match(CODE_FENCE)?.groups?.delimiter;
-  // The `delimiter` group matches exactly ``` or ~~~; comparing against both
-  // narrows it without a cast.
-  if (delimiter !== "```" && delimiter !== "~~~") {
+  const run = trimmed.match(CODE_FENCE)?.groups?.run;
+  if (run === undefined) {
     return fence;
   }
+  const delimiter = run.startsWith("`") ? ("`" as const) : ("~" as const);
   if (fence === null) {
     // A backtick fence's info string cannot itself contain a backtick
     // (CommonMark) — a line-leading ```inline``` span is a paragraph, and
     // opening a phantom fence on it would swallow every heading and link
     // after it. Tilde fences carry no such rule.
-    if (delimiter === "```") {
-      const run = trimmed.match(/^`+/u)?.[0].length ?? 0;
-      if (trimmed.slice(run).includes("`")) {
-        return fence;
-      }
+    if (delimiter === "`" && trimmed.slice(run.length).includes("`")) {
+      return fence;
     }
-    return delimiter;
+    return { delimiter, length: run.length };
   }
-  return fence === delimiter ? null : fence;
+  return fence.delimiter === delimiter && run.length >= fence.length
+    ? null
+    : fence;
 };
 // A closing hash sequence must be preceded by whitespace (CommonMark), so a
 // heading like `## What is C#` keeps its trailing `#`. Up to 3 leading spaces
@@ -198,35 +209,81 @@ const PROMPT_OPEN = /^<Prompt(?![\w-])/u;
 const PROMPT_CLOSE = /<\/Prompt>/u;
 
 /**
- * The body lines, minus a leading front matter block. Bodies from the
- * normalize pipeline are already frontmatter-stripped, but `extractHeadings`
- * also runs on raw documents — where a leading `---` block (closed by `---` or
- * `...`) is front matter, not a thematic break whose closing `---` would
- * underline the last metadata line into a phantom setext heading.
+ * The body lines, minus a leading front matter block, plus the height of the
+ * block that was dropped (`offset`) so line numbers can be reported against
+ * the whole body. Bodies from the normalize pipeline are already
+ * frontmatter-stripped, but `scanBody` also runs on raw documents — where a
+ * leading `---` block (closed by `---` or `...`) is front matter, not a
+ * thematic break whose closing `---` would underline the last metadata line
+ * into a phantom setext heading.
  */
-const linesWithoutFrontMatter = (body: string): string[] => {
+const linesWithoutFrontMatter = (body: string) => {
   const lines = body.split("\n");
   if (!/^-{3}\s*$/u.test(lines[0] ?? "")) {
-    return lines;
+    return { lines, offset: 0 };
   }
   // A blank line directly after the dashes means the body *opens* with a
   // thematic break, not front matter — YAML metadata starts on the very next
   // line. Treating it as an unclosed block ate everything up to the next
   // `---`/`...` line of an already-stripped body.
   if ((lines[1] ?? "").trim() === "") {
-    return lines;
+    return { lines, offset: 0 };
   }
   const close = lines.findIndex(
     (line, index) => index > 0 && FRONT_MATTER_CLOSE.test(line)
   );
-  return close === -1 ? lines : lines.slice(close + 1);
+  return close === -1
+    ? { lines, offset: 0 }
+    : { lines: lines.slice(close + 1), offset: close + 1 };
 };
 
+// A trailing `{#id}` heading marker written without a backslash escape. Both
+// pipelines resolve escapes before parsing markers (see `ESCAPED_PUNCTUATION`),
+// so `\{#id\}` is the same marker — and the only spelling that survives the
+// MDX parser, where a bare `{…}` is a JSX expression and `#id` is not a valid
+// one (`Could not parse expression with acorn`). Further bracket markers may
+// follow the brace (`{#id} [toc]`), nothing else.
+const BARE_CURLY_MARKER =
+  /(?<!\\)\{#(?<id>[^\s}]+)\}(?:\s*\[(?:#[^\s\]]+|!?toc)\])*\s*$/u;
+
+// A raw HTML element carrying an `id` — `<a id="…">`, `<section id='…'>`,
+// the unquoted `<a id=plain>`, or the JSX spelling `<div id={"…"}>` — whose
+// element is a fragment-link target outside headings. Lowercase tags only: a
+// capitalized `<YouTube id="…">` is a component prop, not a DOM id (the
+// `JSX_OPEN` split below). `[^<>]` bounds the attribute run, so a wrapped tag
+// (`<div\n  id="x"\n>`) still matches while a long tag-free line can't
+// backtrack quadratically, and the run never reaches into a neighboring tag.
+const HTML_ID =
+  /<[a-z][a-z0-9-]*(?:\s[^<>]*?)?\sid=(?:(?<quote>["'])(?<quoted>[^"'<>]+)\k<quote>|\{(?<jsxQuote>["'])(?<jsx>[^"'<>]+)\k<jsxQuote>\}|(?<bare>[^\s"'=<>`{}]+))/gu;
+// Commented-out markup renders nothing; matched across lines once the
+// scannable lines are joined back together. Shared with the search
+// extractor so both agree on what a comment is.
+export const HTML_COMMENT = /<!--[\s\S]*?-->/gu;
+export const INLINE_CODE = /`[^`]*`/gu;
+
+/** A heading whose trailing `{#id}` marker is unescaped — see `BARE_CURLY_MARKER`. */
+export interface CurlyMarker {
+  id: string;
+  /** 1-based line of the heading (a setext heading's first text line) in the body. */
+  line: number;
+}
+
 /** Scanner state: the open fence plus the paragraph lines accumulated so far. */
 interface HeadingScanState {
+  /**
+   * Lines eligible to hold an HTML `id` — outside fences and `<Prompt>`
+   * regions, inline code masked — collected for one `HTML_ID` pass at the
+   * end so a tag wrapped over several lines still matches.
+   */
+  anchorLines: string[];
+  curlyMarkers: CurlyMarker[];
   fence: FenceState;
+  /** 1-based body line of the line being scanned. */
+  line: number;
   /** Consecutive paragraph lines — the candidate text for a setext underline. */
   paragraph: string[];
+  /** Body line of the first line in `paragraph`. */
+  paragraphStart: number;
   /** Nesting depth inside `<Prompt>...</Prompt>` — 0 when outside one. */
   promptDepth: number;
   /** True inside a multi-line `<Prompt` opening tag, awaiting its `>`. */
@@ -275,12 +332,155 @@ const finishPromptTag = (
  * collapses `--`; github-slugger keeps it) and resolves repeated headings the
  * same way (`setup`, `setup-1`).
  */
+// CommonMark's escapable ASCII punctuation. The renderer only ever sees
+// heading text *after* the Markdown parser has resolved backslash escapes, so
+// `\[toc]` reaches the hast as plain `[toc]` and the marker still applies;
+// resolving escapes here keeps the two pipelines identical (there is no
+// inline way to write a literal trailing marker — use inline code instead).
+const ESCAPED_PUNCTUATION = /\\(?<char>[!-/:-@[-`{-~])/gu;
+
+// The start of a link-reference definition, as the renderer accepts it:
+// `[label]:` after up to 3 leading spaces, optionally inside block-quote or
+// list-item containers (`> [label]: /url`, `- [label]: /url`) — a definition
+// nested in either still defines the label document-wide. `rest` is whatever
+// follows the colon on the same line.
+//
+// Every container iteration begins with its marker and ends with the
+// whitespace that follows it, so a whitespace run belongs to exactly one
+// iteration. Letting an iteration start with optional whitespace as well
+// gave each run two homes and backtracked exponentially on `>\t>\t>…` and
+// `*\t\t*\t\t*…` lines (CodeQL js/redos).
+const REF_DEFINITION =
+  /^(?: {0,3}|[ \t]*(?:(?:>|(?:[-*+]|\d{1,9}[.)])[ \t])[ \t]*)+)\[(?<label>[^\]]+)\]:[ \t]*(?<rest>.*)$/u;
+
+/**
+ * The normalized labels of every link-reference definition in the body
+ * (outside fenced code). A trailing heading bracket whose label is defined is
+ * a CommonMark shortcut link, not a marker — the renderer leaves it in the
+ * heading as an `<a>`, so the marker parse must skip it too. Labels match
+ * case-insensitively with collapsed internal whitespace (CommonMark).
+ *
+ * Only a *valid* definition defines a label: the label must contain a
+ * non-whitespace character, and a destination must follow — on the same line
+ * or, as CommonMark allows, alone on the next. A bare `[toc]:` with nothing
+ * after it is paragraph text, and the renderer still treats the heading's
+ * `[toc]` as literal — which Blume reads as a marker — so it must not be
+ * recorded here.
+ */
+const refDefinitionLabels = (lines: readonly string[]): Set<string> => {
+  const labels = new Set<string>();
+  let fence: FenceState = null;
+  for (const [index, line] of lines.entries()) {
+    const next = nextFenceState(line, fence);
+    if (fence !== null || next !== null) {
+      fence = next;
+      continue;
+    }
+    const groups = line.match(REF_DEFINITION)?.groups;
+    if (groups?.label === undefined || groups.label.trim() === "") {
+      continue;
+    }
+    const destination = groups.rest ?? "";
+    if (destination === "" && (lines[index + 1] ?? "").trim() === "") {
+      continue;
+    }
+    labels.add(groups.label.trim().replaceAll(/\s+/gu, " ").toLowerCase());
+  }
+  return labels;
+};
+
+/**
+ * A heading record from raw heading text: escapes resolved and trailing
+ * markers stripped, exactly as the renderer sees them. A `[#custom-id]` pin
+ * becomes the slug verbatim and — matching the renderer — occupies its id in
+ * the slugger, so a later heading whose auto-slug collides disambiguates
+ * (`setup` → `setup-1`). `[!toc]`/`[toc]` headings stay in the record: their
+ * ids exist in the rendered page, so links to them are valid anchors
+ * regardless of TOC visibility. A heading that is nothing but markers keeps
+ * them as literal text, mirroring the renderer.
+ */
+const toHeading = (
+  depth: number,
+  raw: string,
+  slugger: GithubSlugger,
+  isRefDefined: (label: string) => boolean
+): Heading => {
+  const unescaped = raw.replaceAll(ESCAPED_PUNCTUATION, "$<char>");
+  const markers = parseHeadingMarkers(unescaped, isRefDefined);
+  const text = markers.text.trim();
+  if (text === "" && (markers.id !== undefined || markers.toc !== undefined)) {
+    return { depth, slug: slugger.slug(unescaped), text: unescaped };
+  }
+  if (markers.id !== undefined) {
+    occupySlug(slugger, markers.id);
+    return { depth, slug: markers.id, text };
+  }
+  return { depth, slug: slugger.slug(text), text };
+};
+
+/** Record a heading's unescaped trailing `{#id}` so `.mdx` pages can be warned. */
+const noteCurlyMarker = (
+  text: string,
+  line: number,
+  state: HeadingScanState
+): void => {
+  const id = text.match(BARE_CURLY_MARKER)?.groups?.id;
+  if (id !== undefined) {
+    state.curlyMarkers.push({ id, line });
+  }
+};
+
+/** Scan a line outside fences and prompts: an anchor host, a heading, or prose. */
+const scanContentLine = (
+  line: string,
+  state: HeadingScanState,
+  slugger: GithubSlugger,
+  headings: Heading[],
+  isRefDefined: (label: string) => boolean
+): void => {
+  // Inline code is masked so a documented `<a id="…">` isn't an anchor.
+  state.anchorLines.push(line.replaceAll(INLINE_CODE, ""));
+  const atx = line.match(ATX_HEADING);
+  if (atx?.groups) {
+    const depth = atx.groups.hashes?.length ?? 1;
+    const text = (atx.groups.text ?? "").trim();
+    headings.push(toHeading(depth, text, slugger, isRefDefined));
+    noteCurlyMarker(text, state.line, state);
+    state.paragraph = [];
+    return;
+  }
+  const setext = line.match(SETEXT_UNDERLINE);
+  if (setext?.groups && state.paragraph.length > 0) {
+    // Setext wins over thematic break when it closes a paragraph (CommonMark);
+    // a multi-line paragraph renders as one heading, soft breaks as spaces.
+    const depth = setext.groups.marker?.startsWith("=") ? 1 : 2;
+    const text = state.paragraph.join(" ").trim();
+    headings.push(toHeading(depth, text, slugger, isRefDefined));
+    noteCurlyMarker(text, state.paragraphStart, state);
+    state.paragraph = [];
+    return;
+  }
+  if (
+    line.trim() === "" ||
+    THEMATIC_BREAK.test(line) ||
+    PARAGRAPH_INTERRUPT.test(line)
+  ) {
+    state.paragraph = [];
+    return;
+  }
+  if (state.paragraph.length === 0) {
+    state.paragraphStart = state.line;
+  }
+  state.paragraph.push(line.trim());
+};
+
 /** Scan one line for a heading, advancing the fence/paragraph state. */
 const scanHeadingLine = (
   line: string,
   state: HeadingScanState,
   slugger: GithubSlugger,
-  headings: Heading[]
+  headings: Heading[],
+  isRefDefined: (label: string) => boolean
 ): void => {
   const next = nextFenceState(line, state.fence);
   // Skip fence delimiter lines themselves and anything inside a fence. A fence
@@ -312,55 +512,68 @@ const scanHeadingLine = (
     state.paragraph = [];
     return;
   }
-  const atx = line.match(ATX_HEADING);
-  if (atx?.groups) {
-    const depth = atx.groups.hashes?.length ?? 1;
-    const text = (atx.groups.text ?? "").trim();
-    headings.push({ depth, slug: slugger.slug(text), text });
-    state.paragraph = [];
-    return;
-  }
-  const setext = line.match(SETEXT_UNDERLINE);
-  if (setext?.groups && state.paragraph.length > 0) {
-    // Setext wins over thematic break when it closes a paragraph (CommonMark);
-    // a multi-line paragraph renders as one heading, soft breaks as spaces.
-    const text = state.paragraph.join(" ").trim();
-    headings.push({
-      depth: setext.groups.marker?.startsWith("=") ? 1 : 2,
-      slug: slugger.slug(text),
-      text,
-    });
-    state.paragraph = [];
-    return;
-  }
-  if (
-    line.trim() === "" ||
-    THEMATIC_BREAK.test(line) ||
-    PARAGRAPH_INTERRUPT.test(line)
-  ) {
-    state.paragraph = [];
-    return;
-  }
-  state.paragraph.push(line.trim());
+  scanContentLine(line, state, slugger, headings, isRefDefined);
 };
 
-export const extractHeadings = (body: string): Heading[] => {
+/** Everything one walk over a body yields for the anchor index. */
+export interface BodyScan {
+  /**
+   * Raw HTML element ids (`<a id="…">`) outside headings, fences, inline
+   * code, comments, and `<Prompt>` regions — fragment-link targets that
+   * `blume validate` accepts alongside heading slugs. Deduplicated, in
+   * document order.
+   */
+  anchors: string[];
+  /** Headings whose trailing `{#id}` marker is unescaped, for `.mdx` pages. */
+  curlyMarkers: CurlyMarker[];
+  headings: Heading[];
+}
+
+/**
+ * Scan a body for its headings, explicit HTML anchors, and unescaped `{#id}`
+ * markers in one fence-aware walk (the same walk `extractHeadings` exposes for
+ * headings alone).
+ */
+export const scanBody = (body: string): BodyScan => {
   const headings: Heading[] = [];
   const slugger = new GithubSlugger();
   const state: HeadingScanState = {
+    anchorLines: [],
+    curlyMarkers: [],
     fence: null,
+    line: 0,
     paragraph: [],
+    paragraphStart: 0,
     promptDepth: 0,
     promptTag: false,
   };
 
-  for (const line of linesWithoutFrontMatter(body)) {
-    scanHeadingLine(line, state, slugger, headings);
+  const { lines, offset } = linesWithoutFrontMatter(body);
+  const definedLabels = refDefinitionLabels(lines);
+  const isRefDefined = (label: string): boolean =>
+    definedLabels.has(label.toLowerCase());
+  for (const [index, line] of lines.entries()) {
+    state.line = index + offset + 1;
+    scanHeadingLine(line, state, slugger, headings, isRefDefined);
   }
 
-  return headings;
+  const anchors = new Set<string>();
+  // Replaced with a space rather than removed: dropping a comment outright
+  // can splice its neighbors into a new `<!--` (`<!-<!-- x -->->`), and a
+  // space keeps a tag from fusing with an `id=` that only a comment separated.
+  const markup = state.anchorLines.join("\n").replaceAll(HTML_COMMENT, " ");
+  for (const match of markup.matchAll(HTML_ID)) {
+    const id = match.groups?.quoted ?? match.groups?.jsx ?? match.groups?.bare;
+    if (id !== undefined) {
+      anchors.add(id);
+    }
+  }
+  return { anchors: [...anchors], curlyMarkers: state.curlyMarkers, headings };
 };
 
+export const extractHeadings = (body: string): Heading[] =>
+  scanBody(body).headings;
+
 // The label admits one level of nested brackets so an image-wrapped link
 // (`[![alt](/img.png)](/target)`) matches as the *outer* link — with a flat
 // `[^\]]*` label the match stopped at the image's `]` and the outer target was
@@ -372,7 +585,6 @@ const MD_LINK =
 // link of its own before labels admitted nesting, and still should be.
 export const MD_IMAGE =
   /!\[[^\]]*\]\((?<target>(?:[^()\s]|\([^()\s]*\))+)(?<title>\s+"[^"]*")?\)/gu;
-export const INLINE_CODE = /`[^`]*`/gu;
 
 /** Column (0-based, within `matched`) where a link/image match's target starts. */
 export const targetOffsetIn = (
@@ -510,9 +722,90 @@ export const extractComponentTags = (body: string): string[] => {
  * extracted from the stripped body, but diagnostics point into the raw
  * document — recorded lines must shift by this offset to match it.
  */
-const strippedLineOffset = (raw: string | undefined, body: string): number =>
+export const strippedLineOffset = (
+  raw: string | undefined,
+  body: string
+): number =>
   raw ? Math.max(0, raw.split("\n").length - body.split("\n").length) : 0;
 
+/**
+ * Map links extracted from include-expanded text back to the file and raw
+ * line each expanded line came from, so a broken link inside a partial is
+ * reported against the partial. Links whose origin is the page's own source
+ * carry no `file` override (origins already hold raw-file lines).
+ */
+const remapExpandedLinks = (
+  links: PageLink[],
+  origins: { file: string; line: number }[],
+  sourcePath: string | undefined
+): PageLink[] =>
+  links.map((link) => {
+    const origin = origins[link.line - 1];
+    if (!origin) {
+      return link;
+    }
+    const remapped: PageLink = { ...link, line: origin.line };
+    if (origin.file !== sourcePath) {
+      remapped.file = origin.file;
+    }
+    return remapped;
+  });
+
+/** The entry's transitively included files, when the scan expanded any. */
+const entryIncludes = (entry: SourceEntry): string[] | undefined =>
+  entry.expanded && entry.expanded.includes.length > 0
+    ? entry.expanded.includes
+    : undefined;
+
+/**
+ * Extract an entry's links for validation. When the scan expanded includes,
+ * extraction runs over the expanded text (origins already hold raw-file
+ * lines); otherwise over the stripped body, shifted by the stripped front
+ * matter block's height.
+ */
+const entryLinks = (entry: SourceEntry): PageLink[] =>
+  entry.expanded
+    ? remapExpandedLinks(
+        extractLinks(entry.expanded.text),
+        entry.expanded.origins,
+        entry.sourcePath
+      )
+    : extractLinks(
+        entry.body.text,
+        strippedLineOffset(entry.raw, entry.body.text)
+      );
+
+/**
+ * Diagnostics for `{#id}` heading markers in an `.mdx` page. The MDX parser
+ * reads a bare `{…}` as a JSX expression, so the page fails to compile —
+ * reported here, at the marker's source line, instead of as a raw acorn error
+ * at render time. An included `.md` partial is spliced into the including
+ * page and parsed in *its* format (see `markdown/include.ts`), so a partial's
+ * markers count too and are reported against the partial via the expansion's
+ * origins. `.md` pages render the marker as text and get no diagnostic.
+ */
+const curlyMarkerDiagnostics = (
+  entry: SourceEntry,
+  markers: CurlyMarker[],
+  sourceName: string
+): Diagnostic[] =>
+  markers.map(({ id, line }) => {
+    const origin = entry.expanded?.origins[line - 1];
+    const page = entry.sourcePath ?? `${sourceName}:${entry.ref}`;
+    const inPartial = origin !== undefined && origin.file !== entry.sourcePath;
+    return {
+      code: "BLUME_MDX_CURLY_ANCHOR",
+      file: origin?.file ?? page,
+      line:
+        origin?.line ?? line + strippedLineOffset(entry.raw, entry.body.text),
+      message: inPartial
+        ? `\`{#${id}}\` is a JSX expression once this partial is included in ${page} (.mdx), so that page fails to compile.`
+        : `\`{#${id}}\` is a JSX expression in .mdx, so this page fails to compile.`,
+      severity: "error",
+      suggestion: `Write \`[#${id}]\` or escape it as \`\\{#${id}\\}\` — both pin the same anchor in .md and .mdx.`,
+    };
+  });
+
 const deriveTitle = (
   meta: PageMeta,
   headings: Heading[],
@@ -530,18 +823,126 @@ const deriveTitle = (
 };
 
 /** Strip habitual leading/trailing slashes (`/getting-started`, `guides/`). */
-const trimSlashes = (value: string): string =>
-  value.replaceAll(/^\/+|\/+$/gu, "");
+const trimSlashes = (value: string): string => trimChar(value, "/");
 
 /** Whether a raw frontmatter value is a string (e.g. the `type` override). */
-const isStringValue = (value: SourceEntry["data"][string]): value is string =>
-  typeof value === "string";
+export const isStringValue = (
+  value: SourceEntry["data"][string]
+): value is string => typeof value === "string";
 
+/** Mount a source-relative path under the source's route prefix. */
 const withPrefix = (prefix: string | undefined, path: string): string => {
   const clean = prefix ? trimSlashes(prefix) : "";
   return clean ? `${clean}/${path}` : path;
 };
 
+/** What a route resolution needs from the owning source and the config. */
+export type RouteContext = Pick<NormalizeContext, "i18n" | "versions"> & {
+  /** The source's route prefix (`NormalizeContext["source"]["prefix"]`). */
+  prefix?: string;
+};
+
+/** Where an entry's ref places it once its directories are read off. */
+export interface EntryPlacement {
+  /**
+   * The locale codes the entry publishes in: `[""]` without i18n, one code for
+   * a placed file, every configured code for a shared `$` file.
+   */
+  locales: string[];
+  /** The ref with its version and locale directories stripped, prefix-less. */
+  navPath: string;
+  /** The version snapshot the entry belongs to (`""` for current). */
+  version: string;
+}
+
+/**
+ * Read the version and locale directories off an entry's ref. The version is
+ * detected first: a snapshot directory is outermost on disk
+ * (`v1.0/fr/page.mdx`), so the locale parser must see a version-stripped ref.
+ * The current version is `""` and lives at the root. Locale placement comes
+ * from the ref (a leading dir, or a filename suffix under the `dot` parser),
+ * never the slug — the slug is the logical, locale-agnostic path within a
+ * locale. A shared `$` file maps to every locale; a source without i18n
+ * placement maps to one.
+ */
+export const placeEntryRef = (
+  ref: string,
+  ext: string,
+  ctx: Pick<RouteContext, "i18n" | "versions">
+): EntryPlacement => {
+  const { version, rest } = ctx.versions
+    ? detectVersionRef(ref, ctx.versions)
+    : { rest: ref, version: "" };
+  const { navPath, locales } = ctx.i18n
+    ? localePlacement(rest, ext, ctx.i18n)
+    : { locales: [""], navPath: rest };
+  return { locales, navPath, version };
+};
+
+/** Everything `normalizeEntry` derives from an entry's ref and slug. */
+export interface EntryRoute extends Pick<
+  EntryPlacement,
+  "locales" | "version"
+> {
+  groups: string[];
+  /**
+   * The version-prefixed, locale-agnostic route — the translation key. Pass it
+   * through {@link localizedRoute} for the route one locale publishes at.
+   */
+  logicalRoute: string;
+  /** The prefixed, locale- and version-stripped nav path. */
+  navPath: string;
+  segments: string[];
+  /** The version-agnostic mapped route. */
+  versionKey: string;
+}
+
+/**
+ * The canonical route resolution, shared by {@link normalizeEntry} and any
+ * source that must predict the route an entry will publish at — the Obsidian
+ * source turns `[[Note]]` into a real href, and a second derivation of a route
+ * is a second answer.
+ *
+ * A frontmatter `slug` wins, then the adapter-supplied `entry.slug` (the typed
+ * SPI's "logical route input; defaults to ref if omitted"), then the ref. The
+ * extension is re-appended so `mapRoute`'s extname strip can't eat a dotted
+ * slug segment (`v1.2`). A slug that trims to nothing falls back. The version
+ * prefixes the mapped route *after* `mapRoute` runs: the mapped route is the
+ * version-agnostic key, the config id is prepended verbatim (never
+ * numeric-prefix-stripped), a frontmatter `slug` gets versionized so snapshots
+ * can't collide with the live page, and `translationKey` becomes
+ * version-specific for free. `basePath` is not applied here — it is outermost,
+ * after locale prefixing — so the result reads `{locale?}/{prefix?}/…`.
+ */
+export const resolveEntryRoute = (
+  entry: Pick<SourceEntry, "ref" | "slug">,
+  ext: string,
+  frontmatterSlug: string | undefined,
+  ctx: RouteContext
+): EntryRoute => {
+  const { locales, navPath, version } = placeEntryRef(entry.ref, ext, ctx);
+  const slugInput = frontmatterSlug ?? entry.slug;
+  const slug = slugInput ? trimSlashes(slugInput) : "";
+  const routeInput = withPrefix(ctx.prefix, slug ? `${slug}${ext}` : navPath);
+  const { segments, groups, route: versionKey } = mapRoute(routeInput);
+  return {
+    groups,
+    locales,
+    logicalRoute: versionizeRoute(versionKey, version),
+    navPath: withPrefix(ctx.prefix, navPath),
+    segments,
+    version,
+    versionKey,
+  };
+};
+
+/** The route a logical route publishes at in one locale, base path excluded. */
+export const localizedRoute = (
+  logicalRoute: string,
+  locale: string,
+  i18n: ResolvedI18nConfig | undefined
+): string => (i18n ? localizeRoute(logicalRoute, locale, i18n) : logicalRoute);
+
 /** A custom-key validation failure, lowered to a joinable diagnostic path. */
 interface CustomKeyIssue {
   message: string;
@@ -717,50 +1118,32 @@ export const normalizeEntry = (
     meta.seo.noindex = true;
   }
 
-  // The version is detected first: a snapshot directory is outermost on disk
-  // (`v1.0/fr/page.mdx`), so the locale parser and route mapping must see a
-  // version-stripped ref. The current version is `""` and lives at the root.
-  const { versions } = ctx;
-  const { version, rest: versionlessRef } = versions
-    ? detectVersionRef(entry.ref, versions)
-    : { rest: entry.ref, version: "" };
-
-  // Locale and the locale-stripped nav path come from the entry's ref (a leading
-  // dir, or a filename suffix under the `dot` parser), not the slug — the slug is
-  // the logical, locale-agnostic path within a locale. A shared `$` file maps to
-  // every locale. Remote/CMS sources without i18n placement map to one locale.
-  const { i18n } = ctx;
-  const { navPath: rawNavPath, locales } = i18n
-    ? localePlacement(versionlessRef, ext, i18n)
-    : { locales: [""], navPath: versionlessRef };
-
-  const navPath = withPrefix(ctx.source.prefix, rawNavPath);
-  // Frontmatter `slug` wins, then the adapter-supplied `entry.slug` (the typed
-  // SPI's "logical route input; defaults to ref if omitted"), then the ref.
-  // The extension is re-appended so mapRoute's extname strip can't eat a
-  // dotted slug segment (`v1.2`). A slug that trims to nothing falls back.
-  const slugInput = meta.slug ?? entry.slug;
-  const slug = slugInput ? trimSlashes(slugInput) : "";
-  const routeInput = withPrefix(
-    ctx.source.prefix,
-    slug ? `${slug}${ext}` : rawNavPath
-  );
-
-  // The version prefixes the mapped route *after* `mapRoute` runs: the mapped
-  // route is the version-agnostic key, the config id is prepended verbatim
-  // (never numeric-prefix-stripped), a frontmatter `slug` gets versionized so
-  // snapshots can't collide with the live page, and `translationKey` becomes
-  // version-specific for free.
-  const { segments, groups, route: versionKey } = mapRoute(routeInput);
-  const logicalRoute = versionizeRoute(versionKey, version);
-  const headings = extractHeadings(entry.body.text);
+  const {
+    groups,
+    locales,
+    logicalRoute,
+    navPath,
+    segments,
+    version,
+    versionKey,
+  } = resolveEntryRoute(entry, ext, meta.slug, {
+    i18n: ctx.i18n,
+    prefix: ctx.source.prefix,
+    versions: ctx.versions,
+  });
+  // Extraction runs on the include-expanded body when the scan expanded one,
+  // so a partial's headings anchor-index and TOC under every including page
+  // and its components register for the runtime import map.
+  const bodyText = entry.expanded?.text ?? entry.body.text;
+  const { anchors, curlyMarkers, headings } = scanBody(bodyText);
   const { staged } = ctx.source;
 
   const base = {
+    anchors,
     body: staged ? { format, text: entry.raw ?? entry.body.text } : undefined,
     collection: staged ? "staged" : undefined,
     componentsUsed:
-      format === "mdx" ? extractComponentTags(entry.body.text) : undefined,
+      format === "mdx" ? extractComponentTags(bodyText) : undefined,
     contentType: meta.type ?? ctx.defaultType,
     custom: parsed.custom,
     description: meta.description,
@@ -770,11 +1153,9 @@ export const normalizeEntry = (
     groups,
     headings,
     id: `${ctx.source.name}:${entry.ref}`,
+    includes: entryIncludes(entry),
     lastModified: meta.lastModified ?? entry.lastModified,
-    links: extractLinks(
-      entry.body.text,
-      strippedLineOffset(entry.raw, entry.body.text)
-    ),
+    links: entryLinks(entry),
     meta,
     navPath,
     segments,
@@ -796,9 +1177,15 @@ export const normalizeEntry = (
     locale,
     route: withBasePath(
       ctx.basePath ?? "",
-      i18n ? localizeRoute(logicalRoute, locale, i18n) : logicalRoute
+      localizedRoute(logicalRoute, locale, ctx.i18n)
     ),
   }));
 
-  return { diagnostics: [], pages };
+  return {
+    diagnostics:
+      format === "mdx"
+        ? curlyMarkerDiagnostics(entry, curlyMarkers, ctx.source.name)
+        : [],
+    pages,
+  };
 };