blume 2.0.2 → 2.0.3

package/src/core/sources/contentful-rich-text.ts

@@ -9,7 +9,7 @@
  */
 import type { JsonObject } from "./json.ts";
 import { asString, getPath, objectsIn } from "./json.ts";
-import type { InlineMarks } from "./lower.ts";
+import type { InlineMarks, InlinePart } from "./lower.ts";
 import {
   absoluteUrl,
   blockquote,
@@ -17,10 +17,10 @@ import {
   headingPrefix,
   image,
   joinBlocks,
+  linkParts,
   listItem,
   markdownDocument,
   renderInline,
-  renderLink,
   unsupported,
   writesMdx,
 } from "./lower.ts";
@@ -139,45 +139,50 @@ const embeddedEntry = (
   );
 };
 
-const renderInlines = (
+const inlineParts = (
   nodes: JsonObject[],
   options: ContentfulRichTextOptions
-): string =>
-  nodes
-    // oxlint-disable-next-line no-use-before-define -- mutual recursion: a link's label is itself inline content
-    .map((node) => renderInlineNode(node, options))
-    .join("");
+): InlinePart[] =>
+  // oxlint-disable-next-line no-use-before-define -- mutual recursion: a link's label is itself inline content
+  nodes.flatMap((node) => inlineNodeParts(node, options));
 
-const renderInlineNode = (
+const inlineNodeParts = (
   node: JsonObject,
   options: ContentfulRichTextOptions
-): string => {
+): InlinePart[] => {
   switch (asString(node.nodeType)) {
     case "text": {
-      return renderInline(asString(node.value) ?? "", marksOf(node));
+      return [{ marks: marksOf(node), text: asString(node.value) ?? "" }];
     }
     case "hyperlink": {
-      return renderLink(
-        renderInlines(children(node), options),
+      return linkParts(
+        inlineParts(children(node), options),
         asString(getPath(node, "data.uri"))
       );
     }
     case "asset-hyperlink": {
-      return renderLink(
-        renderInlines(children(node), options),
+      return linkParts(
+        inlineParts(children(node), options),
         linkedAsset(node, options)?.url
       );
     }
     case "embedded-entry-inline": {
-      return embeddedEntry(node, options);
+      return [{ markdown: embeddedEntry(node, options) }];
     }
     default: {
       // entry-hyperlink (no route to point at) and anything unknown: the label.
-      return renderInlines(children(node), options);
+      return inlineParts(children(node), options);
     }
   }
 };
 
+/** A block's inline children as Markdown, guarded as one block. */
+const blockText = (
+  node: JsonObject,
+  options: ContentfulRichTextOptions
+): string =>
+  guardBlockStart(renderInline(inlineParts(children(node), options)));
+
 const renderList = (
   items: JsonObject[],
   marker: (index: number) => string,
@@ -198,12 +203,14 @@ const renderList = (
     )
     .join("\n");
 
+// Each of a cell's paragraphs is a block as much as a page's is, so it goes
+// through the same guard: two struck runs in one still meet as `~~~~`.
 const cellText = (
   cell: JsonObject,
   options: ContentfulRichTextOptions
 ): string =>
   children(cell)
-    .map((paragraph) => renderInlines(children(paragraph), options))
+    .map((paragraph) => blockText(paragraph, options))
     .join(" ")
     .replaceAll(CELL_BREAK, " ")
     .replaceAll(CELL_PIPE, String.raw`\|`);
@@ -235,11 +242,11 @@ const renderBlock = (
   const type = asString(node.nodeType) ?? "";
   const heading = HEADING.exec(type)?.groups?.level;
   if (heading) {
-    return `${headingPrefix(Number(heading))}${guardBlockStart(renderInlines(children(node), options))}`;
+    return `${headingPrefix(Number(heading))}${blockText(node, options)}`;
   }
   switch (type) {
     case "paragraph": {
-      return guardBlockStart(renderInlines(children(node), options));
+      return blockText(node, options);
     }
     case "blockquote": {
       return blockquote(

package/src/core/sources/filesystem.ts

@@ -6,6 +6,8 @@ import { glob } from "tinyglobby";
 
 import { BlumeError } from "../diagnostics.ts";
 import matter from "../frontmatter.ts";
+import type { Diagnostic } from "../types.ts";
+import { unloadablePathDiagnostic } from "./normalize.ts";
 import type { ContentSource, SourceEntry, SourceLoadResult } from "./types.ts";
 import {
   baselineScanIgnore,
@@ -54,8 +56,24 @@ export const filesystemSource = (
     });
     files.sort();
 
+    // A file Astro's content loader can't read would publish a route that
+    // only ever renders "Page not found"; it is reported and left out.
+    const diagnostics: Diagnostic[] = [];
+    const loadable: string[] = [];
+    for (const file of files) {
+      const unloadable = unloadablePathDiagnostic(
+        relative(contentRoot, file),
+        file
+      );
+      if (unloadable) {
+        diagnostics.push(unloadable);
+      } else {
+        loadable.push(file);
+      }
+    }
+
     const entries = await Promise.all(
-      files.map(async (file): Promise<SourceEntry> => {
+      loadable.map(async (file): Promise<SourceEntry> => {
         const source = await readFile(file, "utf-8");
         const ext = extname(file).toLowerCase();
         const format = ext === ".mdx" ? "mdx" : "md";
@@ -73,7 +91,7 @@ export const filesystemSource = (
       })
     );
 
-    return { diagnostics: [], entries };
+    return { diagnostics, entries };
   };
 
   const validate = (): void => {

package/src/core/sources/github-releases.ts

@@ -16,6 +16,7 @@ import {
   snapshotCache,
 } from "./cache.ts";
 import { destination, escapeMarkdownText } from "./lower.ts";
+import { REMOTE_TIMEOUT_MS } from "./remote.ts";
 import type {
   ContentSource,
   SourceContext,
@@ -358,15 +359,33 @@ export const githubReleasesSource = (
     (options.drafts || !release.draft) &&
     (options.prereleases || !release.prerelease);
 
+  // Each page gets {@link REMOTE_TIMEOUT_MS}, body included: an API that
+  // accepts the connection and never answers would otherwise hold the scan,
+  // and so the build or every dev rescan, indefinitely. The timeout's error
+  // names the URL and the limit, so the empty-changelog warning says what
+  // stalled instead of only that an operation was aborted.
   const fetchPage = async (page: number): Promise<GithubRelease[]> => {
     const url = `${base}/repos/${options.owner}/${options.repo}/releases?per_page=${PER_PAGE}&page=${page}`;
-    const res = await doFetch(url, { headers: githubHeaders() });
-    if (!res.ok) {
-      throw new Error(`${url} -> ${res.status}`);
+    try {
+      const res = await doFetch(url, {
+        headers: githubHeaders(),
+        signal: AbortSignal.timeout(REMOTE_TIMEOUT_MS),
+      });
+      if (!res.ok) {
+        throw new Error(`${url} -> ${res.status}`);
+      }
+      // SAFETY: GitHub's releases endpoint returns a JSON array of release
+      // objects; `GithubRelease` models only the fields the adapter reads.
+      return (await res.json()) as GithubRelease[];
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "TimeoutError") {
+        throw new Error(
+          `${url} did not respond within ${REMOTE_TIMEOUT_MS / 1000}s`,
+          { cause: error }
+        );
+      }
+      throw error;
     }
-    // SAFETY: GitHub's releases endpoint returns a JSON array of release
-    // objects; `GithubRelease` models only the fields the adapter reads.
-    return (await res.json()) as GithubRelease[];
   };
 
   const fetchReleases = async (): Promise<GithubRelease[]> => {

package/src/core/sources/lexical.ts

@@ -7,7 +7,7 @@
  */
 import type { JsonObject } from "./json.ts";
 import { asNumber, asObject, asString, getPath, objectsIn } from "./json.ts";
-import type { InlineMarks } from "./lower.ts";
+import type { InlineMarks, InlinePart } from "./lower.ts";
 import {
   absoluteUrl,
   blockquote,
@@ -15,10 +15,10 @@ import {
   headingPrefix,
   image,
   indent,
+  linkParts,
   listItem,
   markdownDocument,
   renderInline,
-  renderLink,
   unsupported,
   writesMdx,
 } from "./lower.ts";
@@ -67,48 +67,53 @@ const customBlock = (node: JsonObject, options: LexicalOptions): string => {
   );
 };
 
-const renderInlines = (nodes: JsonObject[], options: LexicalOptions): string =>
-  nodes
-    // oxlint-disable-next-line no-use-before-define -- mutual recursion: a link's label is itself inline content
-    .map((node) => renderInlineNode(node, options))
-    .join("");
+const inlineParts = (
+  nodes: JsonObject[],
+  options: LexicalOptions
+): InlinePart[] =>
+  // oxlint-disable-next-line no-use-before-define -- mutual recursion: a link's label is itself inline content
+  nodes.flatMap((node) => inlineNodeParts(node, options));
 
-const renderInlineNode = (
+const inlineNodeParts = (
   node: JsonObject,
   options: LexicalOptions
-): string => {
+): InlinePart[] => {
   switch (typeOf(node)) {
     case "text": {
-      return renderInline(asString(node.text) ?? "", marksOf(node));
+      return [{ marks: marksOf(node), text: asString(node.text) ?? "" }];
     }
     case "linebreak": {
-      return "\n";
+      return [{ markdown: "\n" }];
     }
     case "tab": {
-      return "\t";
+      return [{ markdown: "\t" }];
     }
     case "link":
     case "autolink": {
       // `fields.url` on Payload 3; `url` on older Lexical payloads. An
       // internal link (`linkType: "internal"`) carries a document, not a
       // URL, so its label stays.
-      return renderLink(
-        renderInlines(children(node), options),
+      return linkParts(
+        inlineParts(children(node), options),
         asString(getPath(node, "fields.url")) ?? asString(node.url)
       );
     }
     case "inlineBlock": {
-      return customBlock(node, options);
+      return [{ markdown: customBlock(node, options) }];
     }
     default: {
-      return renderInlines(children(node), options);
+      return inlineParts(children(node), options);
     }
   }
 };
 
+/** Inline nodes as Markdown, guarded as one block. */
+const inlineText = (nodes: JsonObject[], options: LexicalOptions): string =>
+  guardBlockStart(renderInline(inlineParts(nodes, options)));
+
 /** A text block's inline children, joined and guarded as one block. */
 const blockText = (node: JsonObject, options: LexicalOptions): string =>
-  guardBlockStart(renderInlines(children(node), options));
+  inlineText(children(node), options);
 
 const renderUpload = (node: JsonObject, options: LexicalOptions): string => {
   const value = asObject(node.value);
@@ -145,7 +150,7 @@ const renderList = (node: JsonObject, options: LexicalOptions): string => {
     if (listType === "check") {
       check = item.checked === true ? "[x] " : "[ ] ";
     }
-    const line = `${check}${guardBlockStart(renderInlines(inline, options))}`;
+    const line = `${check}${inlineText(inline, options)}`;
     items.push(listItem(lastMarker, sub ? `${line}\n${sub}` : line));
     index += 1;
   }

package/src/core/sources/lower.ts

@@ -9,13 +9,29 @@ import { isSafeHref } from "../safe-href.ts";
 
 // Markdown/raw-HTML structure characters. Rich-text leaves are *plain text* —
 // formatting arrives as marks, never as syntax in the text — so a literal
-// `*`, `_`, `[`, backtick, `~`, or `<` typed in the CMS must render as
-// itself. Unescaped, it opened emphasis or a code span mid-paragraph, and `<`
-// let CMS prose inject raw HTML into the rendered page. `{` and `}` open an
-// expression once an entry is written as MDX (see {@link writesMdx}). CommonMark
+// `*`, `_`, `[`, backtick, `~`, `^`, or `<` typed in the CMS must render as
+// itself. Unescaped, it opened emphasis, a code span, or a superscript
+// (`2^10 and 2^20`) mid-paragraph, and `<` let CMS prose inject raw HTML into
+// the rendered page. `{` and `}` open an expression once an entry is written
+// as MDX (see {@link writesMdx}), and `$$` opens math there. CommonMark
 // backslash-escapes every ASCII punctuation character, so `\*` is always the
 // literal asterisk, in `.md` and `.mdx` alike.
-const MARKDOWN_SPECIALS = /[\\`*_{}[\]~<]/gu;
+const MARKDOWN_SPECIALS = /[\\`*_{}[\]~<$^]/gu;
+
+// MDX reads a colon ahead of a letter or digit as a text directive (`10:30`,
+// `og:image`, `pets:read`), so that colon is escaped too. One inside a bare
+// URL (`http://localhost:3000`) stays as written: an escape there would end
+// the autolink early.
+const DIRECTIVE_COLON = /(?<!(?:[a-z][\w+.-]*:\/\/|www\.)\S*):(?=[a-z\d])/giu;
+
+// GFM autolinks a bare `http://`, `https://`, or `www.` URL in prose, taking
+// its characters verbatim up to the next space or `<`: an escape inside one
+// reaches the href as a backslash (`a\_b`), so prose leaves a bare URL's
+// characters as written. That includes a trailing `*`, `_`, or `~`, which
+// GFM leaves out of the link: escaped, its backslash would still land inside.
+// A link label is the exception — GFM links nothing inside one, so there
+// every special is escaped (see `linkParts`).
+const BARE_URL = /\b(?:https?:\/\/|www\.)[\w-][^\s<]*/giu;
 
 // An entity or numeric character reference (`&copy;`, `&#38;`) is decoded
 // even in plain text, so one typed in the CMS would render as the character
@@ -61,15 +77,37 @@ const escapeEsmStart = (text: string): string =>
     (keyword: string) => `&#${keyword.codePointAt(0)};${keyword.slice(1)}`
   );
 
-export const escapeMarkdownText = (text: string): string =>
+const escapeSpecials = (text: string): string =>
+  text.replaceAll(MARKDOWN_SPECIALS, String.raw`\$&`);
+
+/** The escapes that apply everywhere, once the specials are escaped. */
+const escapeRest = (text: string): string =>
   escapeEsmStart(
     escapeBlockStart(
       text
-        .replaceAll(MARKDOWN_SPECIALS, String.raw`\$&`)
+        .replaceAll(DIRECTIVE_COLON, String.raw`\:`)
         .replaceAll(CHARACTER_REFERENCE, String.raw`\&`)
     )
   );
 
+/**
+ * CMS text as Markdown that renders as written, wherever it lands — a link
+ * label included, where GFM autolinks nothing, so every special is escaped.
+ */
+export const escapeMarkdownText = (text: string): string =>
+  escapeRest(escapeSpecials(text));
+
+/** CMS prose as {@link escapeMarkdownText}, except inside a bare URL. */
+const escapeProse = (text: string): string => {
+  let out = "";
+  let last = 0;
+  for (const match of text.matchAll(BARE_URL)) {
+    out += escapeSpecials(text.slice(last, match.index)) + match[0];
+    last = match.index + match[0].length;
+  }
+  return escapeRest(out + escapeSpecials(text.slice(last)));
+};
+
 /** The marks a lowerer can put on an inline run. */
 export interface InlineMarks {
   bold?: boolean;
@@ -78,6 +116,20 @@ export interface InlineMarks {
   strike?: boolean;
 }
 
+/** A run of CMS text and the marks on it. */
+export interface InlineRun {
+  marks: InlineMarks;
+  text: string;
+}
+
+/** Inline Markdown a lowerer rendered itself: a link, an embed, a break. */
+export interface InlineMarkdown {
+  markdown: string;
+}
+
+/** One piece of a block's inline content, in order. */
+export type InlinePart = InlineMarkdown | InlineRun;
+
 const BACKTICK_RUN = /`+/gu;
 
 /** The longest run of backticks in `text`, 0 when there is none. */
@@ -100,47 +152,153 @@ export const codeSpan = (code: string): string => {
   return `${fence}${pad}${code}${pad}${fence}`;
 };
 
+// Two struck runs side by side meet as `~~~~`: a closer and an opener that
+// GFM reads as one four-tilde run, so both print as literal tildes. A literal
+// `~` is escaped outside a bare URL, so an unescaped `~~~~` outside a code
+// span, a link destination, or a bare URL is exactly that seam, and dropping
+// it merges the runs into one strikethrough. The other alternatives only step
+// over escapes, code spans, destinations, and bare URLs so the seam is never
+// matched inside them.
+const SEAM_STEPS =
+  /\\[\s\S]|(?<ticks>`+)[\s\S]*?(?<!`)\k<ticks>(?!`)|\]\((?:<(?:\\.|[^\\<>\n])*>|(?:\\.|[^\\\s)])+)\)/u;
+const STRIKE_SEAM = new RegExp(
+  `${SEAM_STEPS.source}|${BARE_URL.source}|~~~~`,
+  "giu"
+);
+
+// A heading that ends in a space and a run of `#` reads that run as the
+// optional closing sequence and drops it (`## Issue #` renders "Issue").
+const CLOSING_HASHES = /(?<=[ \t])#+(?=[ \t]*$)/u;
+
 /**
  * A block's inline text, guarded where only the whole block can tell. Runs
  * are escaped one at a time, but "import" ending one run and a space or code
  * span opening the next form an MDX `import` statement only once they are
- * joined, and whitespace the first runs put in front of a block turns it into
- * an indented code block. Apply it to the joined text of a paragraph,
- * heading, quote, or list item — never to code.
+ * joined, whitespace the first runs put in front of a block turns it into
+ * an indented code block, two struck runs fuse into literal tildes, and a
+ * trailing ` #` is a heading's closing sequence. Apply it to the joined text
+ * of a paragraph, heading, quote, or list item — never to code.
  */
 export const guardBlockStart = (text: string): string =>
-  escapeEsmStart(text.replaceAll(BLOCK_INDENT, ""));
+  escapeEsmStart(
+    text
+      .replaceAll(BLOCK_INDENT, "")
+      .replaceAll(STRIKE_SEAM, (match: string) =>
+        match === "~~~~" ? "" : match
+      )
+      .replace(CLOSING_HASHES, String.raw`\$&`)
+  );
 
 const EDGE_SPACE = /^(?<lead>\s*)(?<body>[\s\S]*?)(?<trail>\s*)$/u;
 
 /**
- * Wrap a text run in the Markdown for its marks. Code stays verbatim inside
- * the backticks (an escape would render as a backslash); everything else is
- * escaped first. Whitespace at either edge moves outside the delimiters,
- * since `** bold **` is not strong emphasis but `**bold**` is — editors
- * routinely bold a word together with the space after it.
+ * `text` with `render` applied between its edge whitespace, or as it is when
+ * it is only whitespace.
  */
-export const renderInline = (text: string, marks: InlineMarks): string => {
+const betweenEdges = (
+  text: string,
+  render: (body: string) => string
+): string => {
   const match = EDGE_SPACE.exec(text);
-  const lead = match?.groups?.lead ?? "";
   const body = match?.groups?.body ?? "";
-  const trail = match?.groups?.trail ?? "";
   if (body === "") {
     return text;
   }
-  let out = marks.code ? codeSpan(body) : escapeMarkdownText(body);
-  if (marks.bold) {
-    out = `**${out}**`;
-  }
-  if (marks.italic) {
-    out = `*${out}*`;
+  return `${match?.groups?.lead ?? ""}${render(body)}${match?.groups?.trail ?? ""}`;
+};
+
+const MARK_NAMES = ["bold", "code", "italic", "strike"] as const;
+
+const sameMarks = (
+  a: InlineMarks,
+  b: InlineMarks,
+  names: readonly (keyof InlineMarks)[] = MARK_NAMES
+): boolean => names.every((mark) => Boolean(a[mark]) === Boolean(b[mark]));
+
+/** A stretch of neighboring runs that share marks, and those marks. */
+interface RunGroup {
+  marks: InlineMarks;
+  runs: InlineRun[];
+}
+
+/** Runs split into stretches of neighbors that share the `names` marks. */
+const groupRuns = (
+  runs: InlineRun[],
+  names: readonly (keyof InlineMarks)[] = MARK_NAMES
+): RunGroup[] => {
+  const groups: RunGroup[] = [];
+  for (const run of runs) {
+    const group = groups.at(-1);
+    if (group && sameMarks(group.marks, run.marks, names)) {
+      group.runs.push(run);
+    } else {
+      groups.push({ marks: run.marks, runs: [run] });
+    }
   }
-  if (marks.strike) {
-    out = `~~${out}~~`;
+  return groups;
+};
+
+/**
+ * Consecutive text runs as Markdown. Neighbors with the same bold, italic,
+ * and strikethrough share one set of delimiters — rendered one run at a
+ * time, two bold runs met as `****` and two italic ones as `**`, which print
+ * as literal asterisks. Code stays verbatim inside the backticks (an escape
+ * would render as a backslash), and neighboring code joins into one span;
+ * everything else is escaped. Whitespace at either edge moves outside the
+ * delimiters, since `** bold **` is not strong emphasis but `**bold**` is —
+ * editors routinely bold a word together with the space after it.
+ */
+const renderRuns = (
+  runs: InlineRun[],
+  escape: (text: string) => string
+): string =>
+  groupRuns(runs, ["bold", "italic", "strike"])
+    .map(({ marks, runs: shared }) => {
+      const inner = groupRuns(shared)
+        .map((same) =>
+          betweenEdges(same.runs.map((run) => run.text).join(""), (body) =>
+            same.marks.code ? codeSpan(body) : escape(body)
+          )
+        )
+        .join("");
+      return betweenEdges(inner, (body) => {
+        let out = body;
+        if (marks.bold) {
+          out = `**${out}**`;
+        }
+        if (marks.italic) {
+          out = `*${out}*`;
+        }
+        if (marks.strike) {
+          out = `~~${out}~~`;
+        }
+        return out;
+      });
+    })
+    .join("");
+
+/** Inline parts as Markdown, each stretch of runs through {@link renderRuns}. */
+const renderParts = (
+  parts: InlinePart[],
+  escape: (text: string) => string
+): string => {
+  let out = "";
+  let runs: InlineRun[] = [];
+  for (const part of parts) {
+    if ("markdown" in part) {
+      out += renderRuns(runs, escape) + part.markdown;
+      runs = [];
+    } else {
+      runs.push(part);
+    }
   }
-  return `${lead}${out}${trail}`;
+  return out + renderRuns(runs, escape);
 };
 
+/** A block's inline content as Markdown. */
+export const renderInline = (parts: InlinePart[]): string =>
+  renderParts(parts, escapeProse);
+
 // A destination with whitespace, a control character, or parentheses ends
 // early in `[label](…)`; CommonMark's pointy-bracket form carries it intact.
 // oxlint-disable-next-line no-control-regex -- control characters are exactly what the bare form refuses.
@@ -167,13 +325,22 @@ export const destination = (url: string): string => {
 };
 
 /**
- * A Markdown link, or the label alone when the target is missing — or unsafe:
- * CMS content is the editor's, not the site author's, so a destination that
- * isn't a web, mail, or relative address (`javascript:`, `data:`) never
- * becomes a clickable link on the docs site (see `safe-links.ts`).
+ * A Markdown link over inline parts, or the parts alone when the target is
+ * missing — or unsafe: CMS content is the editor's, not the site author's, so
+ * a destination that isn't a web, mail, or relative address (`javascript:`,
+ * `data:`) never becomes a clickable link on the docs site (see
+ * `safe-links.ts`). The parts stay parts then, so their runs merge with their
+ * neighbors'. A label escapes a bare URL too: GFM autolinks nothing inside a
+ * link, so its specials would read as syntax.
  */
-export const renderLink = (label: string, href?: string): string =>
-  href && isSafeHref(href) ? `[${label}](${destination(href)})` : label;
+export const linkParts = (parts: InlinePart[], href?: string): InlinePart[] =>
+  href && isSafeHref(href)
+    ? [
+        {
+          markdown: `[${renderParts(parts, escapeMarkdownText)}](${destination(href)})`,
+        },
+      ]
+    : parts;
 
 /** The ATX prefix for a heading level, clamped to Markdown's six. */
 export const headingPrefix = (level: number): string =>