blume 2.1.3 → 2.2.0

package/src/core/directive-diagnostics.ts

@@ -1,43 +1,191 @@
-import type { Nodes } from "mdast";
-import { mdxToMdast } from "satteri";
+import type { Nodes, Paragraph } from "mdast";
+import { markdownToMdast, mdxToMdast } from "satteri";
 
 import {
   CALLOUT_ALIASES,
   CALLOUT_TYPES,
   calloutTypeFor,
 } from "../markdown/directives.ts";
-import { MDX_BODY_FEATURES } from "../markdown/features.ts";
+import {
+  MARKDOWN_BODY_FEATURES,
+  MDX_BODY_FEATURES,
+} from "../markdown/features.ts";
 import { strippedLineOffset } from "./sources/normalize.ts";
 import type { SourceEntry } from "./sources/types.ts";
 import type { Diagnostic } from "./types.ts";
 
+type ContainerDirective = Extract<Nodes, { type: "containerDirective" }>;
+
 // A line that may open a container directive: a colon fence and a name, after
-// any quote or list indentation. A page is parsed only when one of these
-// names something other than a callout, so pages without one cost a scan.
+// any quote or list indentation.
 const CONTAINER_OPENING = /^[\t >]*:{3,}(?<name>[a-z][\w-]*)/gimu;
 
+// A colon fence followed by text that opens no directive: text after a space
+// (`::: card`), or a character no name starts with (`:::{.x}`). Such a line
+// either closes a container and loses its text, or is a spaced opener.
+const FENCE_WITH_TEXT = /^[\t >]*:{3,}(?:[\t ]+\S|[^\s:a-z])/imu;
+
+// A container's closing line: the colon fence and whatever follows it.
+const CLOSING_LINE =
+  /^[\t >]*(?<written>(?<fence>:{3,})[\t ]*(?<text>.*?))\s*$/u;
+
+// A container opener with text after its name, and after any `[label]` or
+// `{attributes}`: `:::tip Some title`. Sätteri drops that text.
+const OPENING_TEXT =
+  /^[\t >]*(?<written>(?<fence>:{3,})(?<name>[a-z][\w-]*)(?<label>\[[^\]\n]*\])?(?<attributes>\{[^}\n]*\})?[\t ]+(?<text>\S.*?))\s*$/iu;
+const OPENING_TEXT_LINE =
+  /^[\t >]*:{3,}[a-z][\w-]*(?:\[[^\]\n]*\])?(?:\{[^}\n]*\})?[\t ]+\S/imu;
+
+// A markdown-it style opener, `::: tip Title`, which is no directive at all.
+const SPACED_OPENING =
+  /^[\t >]*(?<written>(?<fence>:{3,})[\t ]+(?<name>[a-z][\w-]*)(?<title>.*?))\s*$/iu;
+
+// A container opener's colon fence and name, after any quote or list
+// indentation, as one line of a `.md` paragraph holds it.
+const MD_OPENING = /^[\t >]*(?<written>:{3,}(?<name>[a-z][\w-]*))/iu;
+const MD_OPENING_LINE = /^[\t >]*:{3,}[a-z]/imu;
+
 const codeList = (names: Iterable<string>): string =>
   [...names].map((name) => `\`${name}\``).join(", ");
 
 const CALLOUT_NAMES = `${codeList(CALLOUT_TYPES)} (or the aliases ${codeList(Object.keys(CALLOUT_ALIASES))})`;
 
-/** A container directive that isn't a callout, and its line in `text`. */
-interface UnknownContainer {
+/** A directive problem at a line of the parsed text, before it's placed in a file. */
+interface Finding {
+  code: string;
   line: number;
-  name: string;
+  message: string;
+  suggestion: string;
 }
 
+const unknownContainer = (node: ContainerDirective): Finding[] =>
+  calloutTypeFor(node.name) === null
+    ? [
+        {
+          code: "BLUME_UNKNOWN_DIRECTIVE",
+          line: node.position?.start.line ?? 1,
+          message: `\`:::${node.name}\` isn't a callout type, so the page shows its \`:::\` lines as written around its content.`,
+          suggestion: `Use a callout type — ${CALLOUT_NAMES} — or remove the \`:::\` lines to keep the content as plain prose.`,
+        },
+      ]
+    : [];
+
+/**
+ * Text after the colons of a container's closing fence. Sätteri closes a
+ * container on any line that starts with at least its fence's colons and
+ * drops the rest of that line (micromark's directive grammar, which
+ * `remark-directive` uses, keeps such a line as content), so a `::: card`
+ * inside a `:::warning` ends the callout early and `card` never reaches the
+ * page. A container left unclosed ends with its content rather than on a
+ * fence line of its own.
+ */
+const closingText = (
+  node: ContainerDirective,
+  lines: readonly string[]
+): Finding[] => {
+  const start = node.position?.start.line ?? 1;
+  const end = node.position?.end.line ?? start;
+  const content = node.children.at(-1)?.position?.end.line ?? start;
+  const groups =
+    end > content ? CLOSING_LINE.exec(lines[end - 1] ?? "")?.groups : undefined;
+  if (!(groups?.text && groups.fence && groups.written)) {
+    return [];
+  }
+  const longer = ":".repeat(groups.fence.length + 1);
+  return [
+    {
+      code: "BLUME_DIRECTIVE_CLOSING_TEXT",
+      line: end,
+      message: `\`${groups.written}\` closes the \`:::${node.name}\` container above it, so \`${groups.text}\` never reaches the page.`,
+      suggestion: `Give the container a longer fence than this line's — \`${longer}${node.name}\`, closed by \`${longer}\` — to keep the line inside it as text, or remove \`${groups.text}\` from the line.`,
+    },
+  ];
+};
+
+/**
+ * Text after a callout opener's name (`:::tip Some title`). Sätteri ends the
+ * name at the space and drops the rest of the line, so the callout renders
+ * untitled and the text never shows. Docusaurus and the markdown-it
+ * containers VitePress uses read that text as the title, which is where the
+ * spelling comes from. Only callouts count: any other container renders its
+ * opening line as written (see `markdown/directives.ts`), text and all.
+ */
+const openingText = (
+  node: ContainerDirective,
+  lines: readonly string[]
+): Finding[] => {
+  const line = node.position?.start.line ?? 1;
+  const groups = OPENING_TEXT.exec(lines[line - 1] ?? "")?.groups;
+  if (
+    !(groups?.fence && groups.name && groups.text && groups.written) ||
+    calloutTypeFor(node.name) === null
+  ) {
+    return [];
+  }
+  const opener = `${groups.fence}${groups.name}`;
+  return [
+    {
+      code: "BLUME_DIRECTIVE_OPENING_TEXT",
+      line,
+      message: `\`${groups.written}\` opens a \`${groups.name}\` callout, but the text after its name, \`${groups.text}\`, never reaches the page.`,
+      suggestion:
+        groups.label || groups.attributes
+          ? `Move \`${groups.text}\` into the callout's title, or onto the next line as its text.`
+          : `Put the title in brackets: \`${opener}[${groups.text}]\`.`,
+    },
+  ];
+};
+
+/**
+ * Callout openers written with a space after the colons (`::: tip`, the
+ * markdown-it spelling VitePress, VuePress, and Docusaurus v2 use). That is
+ * never a directive, so the line and its whole block render as plain text.
+ * Only paragraph lines count, so an example in a code block stays quiet.
+ */
+const spacedOpenings = (
+  node: Paragraph,
+  lines: readonly string[]
+): Finding[] => {
+  const start = node.position?.start.line ?? 1;
+  const end = node.position?.end.line ?? start;
+  return lines.slice(start - 1, end).flatMap((text, index) => {
+    const groups = SPACED_OPENING.exec(text)?.groups;
+    if (
+      !(groups?.fence && groups.name && groups.written) ||
+      calloutTypeFor(groups.name) === null
+    ) {
+      return [];
+    }
+    const opener = `${groups.fence}${groups.name}`;
+    const title = groups.title?.trim();
+    return [
+      {
+        code: "BLUME_DIRECTIVE_SPACED_NAME",
+        line: start + index,
+        message: `\`${groups.written}\` has a space between its colons and its name, so it isn't a callout and the page shows it as text.`,
+        suggestion: title
+          ? `Remove the space and put the title in brackets: \`${opener}[${title}]\`.`
+          : `Remove the space: \`${opener}\`.`,
+      },
+    ];
+  });
+};
+
 /**
- * Every container directive in an `.mdx` body whose name isn't a callout, in
- * source order. The body is parsed as the renderer reads it, so a fence in a
- * code block or a `::: name` that isn't a directive at all never counts. A
- * body MDX can't parse fails to render anyway, with its own error.
+ * The directive problems in an `.mdx` body, in source order. The body is
+ * parsed as the renderer reads it, so a fence in a code block never counts. A
+ * page is parsed only when a line looks like one of these problems, so pages
+ * without one cost a scan. A body MDX can't parse fails to render anyway, with
+ * its own error.
  */
-const unknownContainers = (text: string): UnknownContainer[] => {
-  const named = [...text.matchAll(CONTAINER_OPENING)].some(
-    (match) => calloutTypeFor(match.groups?.name ?? "") === null
-  );
-  if (!named) {
+const directiveFindings = (text: string): Finding[] => {
+  const suspect =
+    FENCE_WITH_TEXT.test(text) ||
+    OPENING_TEXT_LINE.test(text) ||
+    [...text.matchAll(CONTAINER_OPENING)].some(
+      (match) => calloutTypeFor(match.groups?.name ?? "") === null
+    );
+  if (!suspect) {
     return [];
   }
   let tree: Nodes;
@@ -46,13 +194,17 @@ const unknownContainers = (text: string): UnknownContainer[] => {
   } catch {
     return [];
   }
-  const found: UnknownContainer[] = [];
+  const lines = text.split("\n");
+  const found: Finding[] = [];
   const walk = (node: Nodes): void => {
-    if (
-      node.type === "containerDirective" &&
-      calloutTypeFor(node.name) === null
-    ) {
-      found.push({ line: node.position?.start.line ?? 1, name: node.name });
+    if (node.type === "containerDirective") {
+      found.push(
+        ...unknownContainer(node),
+        ...openingText(node, lines),
+        ...closingText(node, lines)
+      );
+    } else if (node.type === "paragraph") {
+      found.push(...spacedOpenings(node, lines));
     }
     if ("children" in node) {
       for (const child of node.children) {
@@ -61,39 +213,105 @@ const unknownContainers = (text: string): UnknownContainer[] => {
     }
   };
   walk(tree);
+  return found.toSorted((a, b) => a.line - b.line);
+};
+
+/**
+ * Container directive openers on the lines of an `.md` paragraph (`:::note`).
+ * A `.md` page renders no directives, so the opener, its content, and its
+ * closing `:::` show as text. A directive in a code block is no paragraph.
+ */
+const mdOpenings = (node: Paragraph, lines: readonly string[]): Finding[] => {
+  const start = node.position?.start.line ?? 1;
+  const end = node.position?.end.line ?? start;
+  return lines.slice(start - 1, end).flatMap((text, index) => {
+    const groups = MD_OPENING.exec(text)?.groups;
+    if (!(groups?.name && groups.written)) {
+      return [];
+    }
+    const callout = calloutTypeFor(groups.name);
+    return [
+      {
+        code: "BLUME_MD_DIRECTIVE",
+        line: start + index,
+        message: `\`${groups.written}\` opens a directive, which Blume renders only in .mdx, so this .md page shows it and its closing \`:::\` as text.`,
+        suggestion: callout
+          ? `Rename the page to .mdx to render it as a \`${callout}\` callout.`
+          : `Rename the page to .mdx and use a callout type — ${CALLOUT_NAMES} — or remove the \`:::\` lines to keep the content as plain prose.`,
+      },
+    ];
+  });
+};
+
+/**
+ * The directives in an `.md` body, in source order, read the way the
+ * renderer reads the page: as paragraphs, since `.md` has no directives. A
+ * page is parsed only when a line looks like an opener.
+ */
+const mdDirectiveFindings = (text: string): Finding[] => {
+  if (!MD_OPENING_LINE.test(text)) {
+    return [];
+  }
+  const tree: Nodes = markdownToMdast(text, {
+    features: MARKDOWN_BODY_FEATURES,
+  });
+  const lines = text.split("\n");
+  const found: Finding[] = [];
+  const walk = (node: Nodes): void => {
+    if (node.type === "paragraph") {
+      found.push(...mdOpenings(node, lines));
+    } else if ("children" in node) {
+      for (const child of node.children) {
+        walk(child);
+      }
+    }
+  };
+  walk(tree);
   return found;
 };
 
 /**
- * Warn about each `:::name` container in an `.mdx` entry that isn't a callout.
- * The page keeps its content — the body renders between the literal `:::`
- * lines (see `markdown/directives.ts`) — but a typo like `:::warnig`, or a
- * `:::details` carried over from another docs tool, should read as the
- * mistake it is rather than as a finished page. Lines point into the file
- * the author wrote, a partial's own file for a container an `<include>`
- * brought in.
+ * Warn about the `:::` directives in an entry that don't render as their
+ * author meant. In `.mdx`:
+ *
+ * - `BLUME_UNKNOWN_DIRECTIVE`: a `:::name` container that isn't a callout.
+ *   The page keeps its content — the body renders between the literal `:::`
+ *   lines (see `markdown/directives.ts`) — but a typo like `:::warnig`, or a
+ *   `:::details` carried over from another docs tool, should read as the
+ *   mistake it is rather than as a finished page.
+ * - `BLUME_DIRECTIVE_OPENING_TEXT`: a callout opener with text after its
+ *   name, which the page drops (`:::tip Some title`).
+ * - `BLUME_DIRECTIVE_CLOSING_TEXT`: a closing fence with text after it, which
+ *   the page drops (`::: card` inside a `:::warning`).
+ * - `BLUME_DIRECTIVE_SPACED_NAME`: a spaced callout opener (`::: tip`), which
+ *   the page shows as text.
+ *
+ * In `.md`, which renders no directives:
+ *
+ * - `BLUME_MD_DIRECTIVE`: a `:::name` opener, which the page shows as text.
+ *
+ * Lines point into the file the author wrote, a partial's own file for a
+ * directive an `<include>` brought in.
  */
-export const unknownDirectiveDiagnostics = (
+export const directiveDiagnostics = (
   entry: SourceEntry,
   sourceName: string
 ): Diagnostic[] => {
-  if (entry.body.format !== "mdx") {
-    return [];
-  }
   const page = entry.sourcePath ?? `${sourceName}:${entry.ref}`;
   const offset =
     entry.bodyLineOffset ?? strippedLineOffset(entry.raw, entry.body.text);
-  return unknownContainers(entry.expanded?.text ?? entry.body.text).map(
-    ({ line, name }) => {
-      const origin = entry.expanded?.origins[line - 1];
-      return {
-        code: "BLUME_UNKNOWN_DIRECTIVE",
-        file: origin?.file ?? page,
-        line: origin?.line ?? line + offset,
-        message: `\`:::${name}\` isn't a callout type, so the page shows its \`:::\` lines as written around its content.`,
-        severity: "warning",
-        suggestion: `Use a callout type — ${CALLOUT_NAMES} — or remove the \`:::\` lines to keep the content as plain prose.`,
-      };
-    }
-  );
+  const text = entry.expanded?.text ?? entry.body.text;
+  const findings =
+    entry.body.format === "mdx"
+      ? directiveFindings(text)
+      : mdDirectiveFindings(text);
+  return findings.map(({ line, ...finding }) => {
+    const origin = entry.expanded?.origins[line - 1];
+    return {
+      ...finding,
+      file: origin?.file ?? page,
+      line: origin?.line ?? line + offset,
+      severity: "warning",
+    };
+  });
 };

package/src/core/former-routes.ts

@@ -0,0 +1,46 @@
+import { normalizePath, stripBasePath, withBasePath } from "./base-path.ts";
+import type { ResolvedConfig } from "./schema.ts";
+import type { PageRecord } from "./types.ts";
+
+type Redirect = ResolvedConfig["redirects"][number];
+
+/**
+ * Redirects from the routes an earlier Blume published pages at
+ * (`PageRecord.formerRoute`) to where they publish now, so a date-named
+ * page's old URL keeps working. None is added where the old URL is still
+ * served (another page, or a custom page, lives there now), where an authored
+ * redirect already starts, or where two pages once resolved to it: that was a
+ * duplicate route, which failed the build, so the URL never served either.
+ * Both ends are written base-less, like authored redirects.
+ */
+export const formerRouteRedirects = (
+  pages: readonly PageRecord[],
+  served: ReadonlySet<string>,
+  config: Pick<ResolvedConfig, "basePath" | "redirects">
+): Redirect[] => {
+  const targets = new Map<string, string | undefined>();
+  for (const page of pages) {
+    if (page.formerRoute !== undefined) {
+      targets.set(
+        page.formerRoute,
+        targets.has(page.formerRoute) ? undefined : page.route
+      );
+    }
+  }
+  const authored = new Set(
+    config.redirects.map((redirect) =>
+      normalizePath(withBasePath(config.basePath, redirect.from))
+    )
+  );
+  return [...targets].flatMap(([from, to]) =>
+    to === undefined || served.has(from) || authored.has(from)
+      ? []
+      : [
+          {
+            from: stripBasePath(config.basePath, from),
+            status: 301,
+            to: stripBasePath(config.basePath, to),
+          } satisfies Redirect,
+        ]
+  );
+};

package/src/core/git-ignored.ts

@@ -0,0 +1,53 @@
+import { execFileSync } from "node:child_process";
+
+import { isAbsolute, relative } from "pathe";
+
+import { gitEnv, gitRepositoryRoot, realPath } from "./last-modified.ts";
+
+/**
+ * The paths among `paths` that git ignores: a `.gitignore` rule matches them
+ * and the index doesn't track them, so they never reach the repository.
+ * Generated pages are the usual case, like a TypeDoc build written into a
+ * gitignored folder under the content root. One `git check-ignore` reads
+ * every path. Empty when git is unavailable or `root` isn't in a repository.
+ */
+export const gitIgnoredPaths = (root: string, paths: string[]): Set<string> => {
+  const gitRoot = paths.length > 0 ? gitRepositoryRoot(root) : null;
+  if (gitRoot === null) {
+    return new Set();
+  }
+  // Git names paths by their real location (see `realPath`), and a path
+  // outside the repository would fail the whole call, so only the paths
+  // inside it are asked about, by their repository-relative spelling.
+  const top = realPath(gitRoot);
+  const byRepoPath = new Map<string, string>();
+  for (const path of paths) {
+    const rel = relative(top, realPath(path));
+    if (!(rel.startsWith("..") || isAbsolute(rel))) {
+      byRepoPath.set(rel, path);
+    }
+  }
+  try {
+    const output = execFileSync(
+      // oxlint-disable-next-line sonarjs/no-os-command-from-path -- git is a required dev-tool dependency resolved from PATH
+      "git",
+      ["-C", top, "check-ignore", "-z", "--stdin"],
+      {
+        encoding: "utf-8",
+        env: gitEnv(),
+        input: [...byRepoPath.keys()].map((rel) => `${rel}\0`).join(""),
+        maxBuffer: 256 * 1024 * 1024,
+        stdio: ["pipe", "pipe", "ignore"],
+      }
+    );
+    return new Set(
+      output.split("\0").flatMap((rel) => {
+        const path = byRepoPath.get(rel);
+        return path === undefined ? [] : [path];
+      })
+    );
+  } catch {
+    // `check-ignore` exits 1 when no path is ignored.
+    return new Set();
+  }
+};

package/src/core/github.ts

@@ -1,10 +1,11 @@
 /**
  * Repository URL derivation for `config.github`.
  *
- * Every repo-derived link — the header mark, per-page edit links, the agent
- * manifest's `repository` — is built from `host`, which defaults to github.com
- * but accepts a GitHub Enterprise origin so self-hosted and data-resident
- * installations get working links instead of ones pointing at the public site.
+ * Every repo-derived link — the footer's repository link, per-page edit links,
+ * the agent manifest's `repository` — is built from `host`, which defaults to
+ * github.com but accepts a GitHub Enterprise origin so self-hosted and
+ * data-resident installations get working links instead of ones pointing at the
+ * public site.
  *
  * The REST base is derived from the host unless `api` is set explicitly, since
  * the two Enterprise flavors expose it differently: Enterprise Cloud with data

package/src/core/heading-markers.ts

@@ -13,9 +13,12 @@
  * Both heading pipelines share this parser — the render-time hast plugin
  * (`markdown/heading-anchors.ts`) and the scan-time source scanner
  * (`core/sources/normalize.ts`) — so the rendered `id`, the TOC entry, and the
- * anchor index `blume validate` checks against always agree.
+ * anchor index `blume validate` checks against always agree. Both also escape
+ * a pinned id's punctuation before they parse (`core/pinned-ids.ts`), so
+ * smart punctuation never rewrites the id an author pinned.
  */
 
+import { slug } from "github-slugger";
 import type GithubSlugger from "github-slugger";
 
 /**
@@ -25,6 +28,154 @@ import type GithubSlugger from "github-slugger";
  */
 export const TOC_HIDDEN_KEY = "__blumeTocHidden";
 
+/**
+ * Frontmatter key carrying TOC text out of a render, keyed by slug, for the
+ * headings whose TOC entry must read differently from the heading's text
+ * content: a heading holding a `<Badge>` lists without the badge's text. The
+ * page template reads it back the way it reads {@link TOC_HIDDEN_KEY}.
+ */
+export const TOC_TEXT_KEY = "__blumeTocText";
+
+const TRAILING_DASHES = /-+$/u;
+
+/**
+ * A heading's auto-generated anchor id, registered with the document slugger.
+ * The text is trimmed first: a heading that opens or ends with something that
+ * has no text (an inline component, an image, raw HTML) would otherwise slug
+ * that edge whitespace into a leading or trailing dash. A slug can still end
+ * in dashes when the slugger drops a symbol after a space (`Features ✨`);
+ * those go too, so no id ends in a dash.
+ */
+export const headingSlug = (slugger: GithubSlugger, text: string): string => {
+  const trimmed = text.trim();
+  const base = slug(trimmed);
+  // A slug is stable under re-slugging, so the stripped one registers as is.
+  return slugger.slug(
+    base.endsWith("-") ? base.replace(TRAILING_DASHES, "") : trimmed
+  );
+};
+
+/**
+ * A heading's text with its badges taken out. `pieces` is the heading's text
+ * in order, with `null` where a badge stood; a badge between two words
+ * leaves one space, not the two around it (`Install <Badge>beta</Badge> now`
+ * reads `Install now`).
+ */
+export const joinHeadingText = (pieces: readonly (string | null)[]): string => {
+  let text = "";
+  let gap = false;
+  for (const piece of pieces) {
+    if (piece === null) {
+      gap = true;
+      continue;
+    }
+    text += gap && /\s$/u.test(text) ? piece.replace(/^[\t ]+/u, "") : piece;
+    gap = false;
+  }
+  return text;
+};
+
+/** One raw HTML tag, as an inline `.md` (or scanned) heading holds it. */
+interface RawTag {
+  /** The attribute source after the name, a self-closing `/` included. */
+  attributes: string;
+  closing: boolean;
+  name: string;
+}
+
+const RAW_TAG =
+  /^<(?<closing>\/)?(?<name>[A-Za-z][\w.-]*)(?<attributes>[^>]*)>$/u;
+
+/** A raw inline HTML node's tag, or null when it holds something else. */
+const rawTag = (value: string): RawTag | null => {
+  const groups = RAW_TAG.exec(value.trim())?.groups;
+  return groups?.name === undefined
+    ? null
+    : {
+        attributes: groups.attributes ?? "",
+        closing: groups.closing !== undefined,
+        name: groups.name,
+      };
+};
+
+const isSelfClosing = (tag: RawTag): boolean =>
+  tag.attributes.trimEnd().endsWith("/");
+
+/**
+ * How a raw HTML node in a heading reads for its anchor: a `<Badge>` tag that
+ * opens or closes a run of badge text (a self-closing one is a badge with no
+ * text), the opening tag of an `<a>` (`target` its `id`, else its `name`),
+ * the `</a>` that closes one, or none of these.
+ */
+export type RawHeadingTag =
+  | { kind: "anchor-close" }
+  | { kind: "anchor-open"; selfClosing: boolean; target?: string }
+  | { kind: "badge"; selfClosing: boolean; closing: boolean }
+  | { kind: "other" };
+
+const ANCHOR_TARGET =
+  /(?:^|\s)(?<key>id|name)\s*=\s*(?:"(?<double>[^"]*)"|'(?<single>[^']*)'|(?<bare>[^\s"'=<>`/]+))/giu;
+
+/** An anchor's own fragment target: its `id`, else its `name`. */
+const anchorTarget = (attributes: string): string | undefined => {
+  const values = new Map<string, string>();
+  for (const match of attributes.matchAll(ANCHOR_TARGET)) {
+    const groups = match.groups ?? {};
+    const value = groups.double ?? groups.single ?? groups.bare;
+    const key = groups.key?.toLowerCase();
+    if (key && value && !values.has(key)) {
+      values.set(key, value);
+    }
+  }
+  return values.get("id") ?? values.get("name");
+};
+
+/** Classify a raw HTML node in a heading — see {@link RawHeadingTag}. */
+export const rawHeadingTag = (value: string): RawHeadingTag => {
+  const tag = rawTag(value);
+  if (tag?.name === "Badge") {
+    return {
+      closing: tag.closing,
+      kind: "badge",
+      selfClosing: isSelfClosing(tag),
+    };
+  }
+  if (tag?.name.toLowerCase() !== "a") {
+    return { kind: "other" };
+  }
+  return tag.closing
+    ? { kind: "anchor-close" }
+    : {
+        kind: "anchor-open",
+        selfClosing: isSelfClosing(tag),
+        target: anchorTarget(tag.attributes),
+      };
+};
+
+/**
+ * A JSX attribute: a name with a string value or an `{expression}` one, or a
+ * `{...spread}` (no name).
+ */
+export interface JsxAttribute {
+  name?: string;
+  type: string;
+  value?: string | { type: string; value?: string } | null;
+}
+
+const isStringValue = (value: JsxAttribute["value"]): value is string =>
+  typeof value === "string";
+
+/** A JSX `<a>`'s own fragment target: its string `id`, else its `name`. */
+export const jsxAnchorTarget = (
+  attributes: readonly JsxAttribute[]
+): string | undefined => {
+  const value = (key: string): string | undefined => {
+    const found = attributes.find((attribute) => attribute.name === key)?.value;
+    return isStringValue(found) && found !== "" ? found : undefined;
+  };
+  return value("id") ?? value("name");
+};
+
 /**
  * Register a pinned `[#id]` with the document slugger, the way
  * `GithubSlugger#slug` registers the slugs it returns — so a later heading
@@ -42,7 +193,10 @@ const MARKER =
   /\s*(?:\{#(?<curlyId>[^\s}]+)\}|\[(?:#(?<id>[^\s\]]+)|(?<hide>!)?toc)\])\s*$/u;
 
 export interface HeadingMarkers {
-  /** Author-pinned anchor id from `[#id]` or `{#id}`, used verbatim (never re-slugged). */
+  /**
+   * Author-pinned anchor id from `[#id]` or `{#id}`, used verbatim (never
+   * re-slugged, and never smart-punctuated: see `core/pinned-ids.ts`).
+   */
   id?: string;
   /** The heading text with every trailing marker stripped. */
   text: string;