blume 2.0.0 → 2.0.2

package/src/core/sources/contentful.ts

@@ -1,3 +1,4 @@
+import { BlumeError } from "../diagnostics.ts";
 import {
   assetFromEntry,
   contentfulRichTextToMarkdown,
@@ -111,19 +112,29 @@ export const contentfulSource = (
     );
   };
 
-  const fetchEntries = async (): Promise<SourceEntry[]> => {
-    const preview = ctx?.preview ?? false;
-    const deliveryToken = options.token ?? process.env.CONTENTFUL_ACCESS_TOKEN;
-    const previewToken =
-      options.previewToken ?? process.env.CONTENTFUL_PREVIEW_TOKEN;
-    // The Preview API rejects delivery tokens, so falling back to one would
-    // only trade a clear config error for a 401.
-    if (preview && !previewToken) {
-      throw new Error(
-        "Contentful --preview needs a Preview API token: set previewToken or CONTENTFUL_PREVIEW_TOKEN."
-      );
+  const preview = ctx?.preview ?? false;
+  const previewToken = (): string | undefined =>
+    options.previewToken ?? process.env.CONTENTFUL_PREVIEW_TOKEN;
+
+  // The Preview API rejects delivery tokens, so falling back to one would
+  // only trade a clear config error for a 401. Checked before the cache, so
+  // a warm snapshot can't stand in for the drafts `--preview` asked for.
+  const assertConfigured = (): void => {
+    if (preview && !previewToken()) {
+      throw new BlumeError({
+        code: "BLUME_SOURCE_MISCONFIGURED",
+        message: `Source "${options.name}": Contentful --preview needs a Preview API token.`,
+        severity: "error",
+        suggestion:
+          "Set previewToken on contentfulSource, or the CONTENTFUL_PREVIEW_TOKEN environment variable.",
+      });
     }
-    const token = preview ? previewToken : deliveryToken;
+  };
+
+  const fetchEntries = async (): Promise<SourceEntry[]> => {
+    const token = preview
+      ? previewToken()
+      : (options.token ?? process.env.CONTENTFUL_ACCESS_TOKEN);
     const client: RestClient = {
       fetchImpl: options.fetchImpl,
       headers: token ? { authorization: `Bearer ${token}` } : {},
@@ -163,10 +174,12 @@ export const contentfulSource = (
 
   return remoteSource(
     {
+      assertConfigured,
       fetchEntries,
       name: options.name,
       pollInterval: options.pollInterval,
       prefix: options.prefix,
+      withContext: (next) => contentfulSource(options, next),
     },
     ctx
   );

package/src/core/sources/filesystem.ts

@@ -83,7 +83,9 @@ export const filesystemSource = (
         file: contentRoot,
         message: `Content root not found: ${options.root}`,
         severity: "error",
-        suggestion: `Create a "${options.root}" folder with at least one .md or .mdx file, or set content.root in blume.config.ts.`,
+        // `content.root` is rejected beside `content.sources`, so the hint
+        // names both places a root is set.
+        suggestion: `Create a "${options.root}" folder with at least one .md or .mdx file, or point Blume at your docs folder: content.root in blume.config.ts, or the filesystem() source's root when you list content.sources.`,
       });
     }
   };
@@ -113,6 +115,8 @@ export const filesystemSource = (
 
   return {
     contentRoot,
+    exclude: options.exclude,
+    include: options.include,
     load,
     name: options.name,
     prefix: options.prefix,

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

@@ -1,4 +1,4 @@
-import type { Heading, Nodes } from "mdast";
+import type { Definition, Heading, Link, Nodes } from "mdast";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { gfmFromMarkdown } from "mdast-util-gfm";
 import { toString as mdastToString } from "mdast-util-to-string";
@@ -15,6 +15,7 @@ import {
   pollingWatch,
   snapshotCache,
 } from "./cache.ts";
+import { destination, escapeMarkdownText } from "./lower.ts";
 import type {
   ContentSource,
   SourceContext,
@@ -43,6 +44,11 @@ export interface GithubReleasesSourceOptions {
   prereleases?: boolean;
   /** Repository name. */
   repo: string;
+  /**
+   * The site's own URL (`deployment.site`). A link in the notes back to it
+   * becomes root-relative, the way a page links to another page.
+   */
+  site?: string;
 }
 
 /** The subset of the GitHub release payload the adapter reads. */
@@ -164,6 +170,92 @@ const liftHeadings = (body: string): string => {
   return lifted;
 };
 
+const WEB_PROTOCOL = /^https?:$/u;
+const TITLE_SPECIALS = /["\\]/gu;
+
+/** The origin of an http(s) site URL, or null when there is none. */
+const webOrigin = (site?: string): string | null => {
+  const parsed = site ? URL.parse(site) : null;
+  return parsed && WEB_PROTOCOL.test(parsed.protocol) ? parsed.origin : null;
+};
+
+/** A link title as Markdown carries it, or nothing when there is none. */
+const titleSuffix = (title?: string | null): string =>
+  title ? ` "${title.replaceAll(TITLE_SPECIALS, String.raw`\$&`)}"` : "";
+
+/**
+ * The Markdown a link or definition to one of the site's own pages becomes,
+ * pointing at `path` instead. An inline link keeps its label as written, and
+ * an autolink keeps showing the URL it was written as.
+ */
+const rewrittenLink = (
+  markdown: string,
+  node: Definition | Link,
+  path: string
+): string => {
+  const target = `${destination(path)}${titleSuffix(node.title)}`;
+  if (node.type === "definition") {
+    return `[${node.label ?? node.identifier}]: ${target}`;
+  }
+  const start = node.position?.start.offset ?? 0;
+  if (markdown[start] !== "[") {
+    return `[${escapeMarkdownText(mdastToString(node))}](${target})`;
+  }
+  const first = node.children.at(0)?.position?.start.offset ?? start + 1;
+  const last = node.children.at(-1)?.position?.end.offset ?? first;
+  return `[${markdown.slice(first, last)}](${target})`;
+};
+
+/**
+ * Point the notes' links to the site itself (`https://acme.dev/docs/x` when
+ * `deployment.site` is `https://acme.dev`) at the root-relative path, as a
+ * page on the site links to another: an absolute link hardcodes production,
+ * so it leaves a preview deploy and trips `blume audit`'s own-origin check.
+ */
+const relativizeOwnLinks = (markdown: string, site?: string): string => {
+  const origin = webOrigin(site);
+  if (!origin) {
+    return markdown;
+  }
+  const spans: { end: number; start: number; text: string }[] = [];
+  const visit = (node: Nodes): void => {
+    if (node.type === "link" || node.type === "definition") {
+      const parsed = URL.parse(node.url);
+      if (parsed?.origin === origin) {
+        spans.push({
+          // fromMarkdown stamps every node's position.
+          end: node.position?.end.offset ?? 0,
+          start: node.position?.start.offset ?? 0,
+          text: rewrittenLink(
+            markdown,
+            node,
+            `${parsed.pathname}${parsed.search}${parsed.hash}`
+          ),
+        });
+        return;
+      }
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        visit(child);
+      }
+    }
+  };
+  visit(
+    fromMarkdown(markdown, {
+      extensions: [gfm()],
+      mdastExtensions: [gfmFromMarkdown()],
+    })
+  );
+  let out = "";
+  let cursor = 0;
+  for (const span of spans) {
+    out += markdown.slice(cursor, span.start) + span.text;
+    cursor = span.end;
+  }
+  return out + markdown.slice(cursor);
+};
+
 /** Slugify a tag into a stable, URL-safe source ref (`v1.2.0` -> `v1-2-0`). */
 const slugifyTag = (tag: string): string =>
   tag.toLowerCase().replaceAll(NON_SLUG, "-").replaceAll(EDGE_DASHES, "");
@@ -197,16 +289,22 @@ interface ChangelogFrontmatter {
  * generated `/changelog` timeline and RSS feed, and a summary derived from the
  * notes becomes the release page's meta description.
  */
-const releaseToEntry = (release: GithubRelease): SourceEntry => {
+const releaseToEntry = (release: GithubRelease, site?: string): SourceEntry => {
   const version = release.tag_name.replace(LEADING_V, "");
   const title = release.name?.trim() || release.tag_name;
   const date = release.published_at ?? release.created_at;
   const category = release.prerelease ? "Prerelease" : "Release";
   // Release notes are the repository's content, not the site author's, so a
   // link whose destination isn't a web, mail, or relative address
-  // (`javascript:`, `data:`) keeps only its label (see `safe-links.ts`).
+  // (`javascript:`, `data:`) keeps only its label (see `safe-links.ts`), and
+  // a link back to the site becomes root-relative.
   const body = liftHeadings(
-    neutralizeUnsafeLinks((release.body ?? "").replaceAll("\r\n", "\n")).trim()
+    relativizeOwnLinks(
+      neutralizeUnsafeLinks(
+        (release.body ?? "").replaceAll("\r\n", "\n")
+      ).trim(),
+      site
+    )
   );
   // A summary in `seo.description` gives each release page a unique meta
   // description (instead of the site-wide fallback) without also rendering the
@@ -295,7 +393,9 @@ export const githubReleasesSource = (
         cache,
         async () => {
           const releases = await fetchReleases();
-          return releases.map(releaseToEntry);
+          return releases.map((release) =>
+            releaseToEntry(release, options.site)
+          );
         },
         refresh
       );
@@ -347,5 +447,6 @@ export const githubReleasesSource = (
           () => load()
         )
       : undefined,
+    withContext: (next) => githubReleasesSource(options, next),
   };
 };

package/src/core/sources/lexical.ts

@@ -11,6 +11,7 @@ import type { InlineMarks } from "./lower.ts";
 import {
   absoluteUrl,
   blockquote,
+  guardBlockStart,
   headingPrefix,
   image,
   indent,
@@ -105,6 +106,10 @@ const renderInlineNode = (
   }
 };
 
+/** A text block's inline children, joined and guarded as one block. */
+const blockText = (node: JsonObject, options: LexicalOptions): string =>
+  guardBlockStart(renderInlines(children(node), options));
+
 const renderUpload = (node: JsonObject, options: LexicalOptions): string => {
   const value = asObject(node.value);
   const url = value ? asString(value.url) : undefined;
@@ -140,7 +145,7 @@ const renderList = (node: JsonObject, options: LexicalOptions): string => {
     if (listType === "check") {
       check = item.checked === true ? "[x] " : "[ ] ";
     }
-    const line = `${check}${renderInlines(inline, options)}`;
+    const line = `${check}${guardBlockStart(renderInlines(inline, options))}`;
     items.push(listItem(lastMarker, sub ? `${line}\n${sub}` : line));
     index += 1;
   }
@@ -150,14 +155,14 @@ const renderList = (node: JsonObject, options: LexicalOptions): string => {
 const renderBlock = (node: JsonObject, options: LexicalOptions): string => {
   switch (typeOf(node)) {
     case "paragraph": {
-      return renderInlines(children(node), options);
+      return blockText(node, options);
     }
     case "heading": {
       const level = Number((asString(node.tag) ?? "h1").slice(1));
-      return `${headingPrefix(level)}${renderInlines(children(node), options)}`;
+      return `${headingPrefix(level)}${blockText(node, options)}`;
     }
     case "quote": {
-      return blockquote(renderInlines(children(node), options));
+      return blockquote(blockText(node, options));
     }
     case "list": {
       return renderList(node, options);

package/src/core/sources/lower.ts

@@ -22,29 +22,37 @@ const MARKDOWN_SPECIALS = /[\\`*_{}[\]~<]/gu;
 // it names rather than as written. A bare `&` is left alone.
 const CHARACTER_REFERENCE = /&(?=#?[a-z0-9]+;)/giu;
 
-// Block syntax is only syntax at the start of a line: `# `, `- `, `+ ` and
-// `1. `/`1) ` need the space (or line end) to become a heading or list item,
-// while `>` opens a quote on its own, and a line of only `=` or `-` turns the
-// line above it into a heading (or, alone, into a rule). A CMS paragraph that
-// begins with one of these — a soft break inside it counts as a line start
-// too — must stay prose.
+// Block syntax is only syntax at the start of a line: `# ` (through
+// `###### `), `- `, `+ ` and `1. `/`1) ` need the space (or line end) to
+// become a heading or list item, while `>` opens a quote on its own, and a
+// line of only `=` or `-` turns the line above it into a heading (or, alone,
+// into a rule). Indentation of up to three spaces still counts. A CMS
+// paragraph that begins with one of these — a soft break inside it counts as
+// a line start too — must stay prose.
 const BLOCK_START =
-  /^(?<marker>[#+-]|\d+[.)])(?=[ \t]|$)|^(?<quote>>)|^(?<rule>=+|-{2,})(?=[ \t]*$)/gmu;
+  /^(?<indent>[ \t]*)(?:(?<marker>#+|[+-]|\d+[.)])(?=[ \t]|$)|(?<quote>>)|(?<rule>=+|-{2,})(?=[ \t]*$))/gmu;
 
-// MDX reads a top-level paragraph that opens with `import ` or `export ` as an
-// ESM statement, and prose like "import the CSV first" then fails the whole
-// page. The keyword's first letter as a character reference renders the same
-// in `.md` and `.mdx`, and MDX no longer sees the keyword. Only a paragraph's
-// first line counts; a blank line inside a run starts a new paragraph.
-const ESM_START = /(?<=^|\n[ \t]*\n)(?<keyword>import|export)(?= )/gu;
+// MDX reads a top-level line that opens with `import` or `export` followed by
+// a space, a tab, `{`, or `*` as an ESM statement, and prose like "import the
+// CSV first" then fails the whole page. The keyword's first letter as a
+// character reference renders the same in `.md` and `.mdx`, and MDX no longer
+// sees the keyword. The keyword is escaped wherever a word ends on it, which
+// covers every character that opens a statement. Only a block's first line
+// counts; a blank line inside the text starts a new block.
+const ESM_START = /(?<=^|\n[ \t]*\n)(?<keyword>import|export)(?![\w$])/gu;
+
+// Whitespace opening a block: four columns of it (or a tab) make an indented
+// code block, and a paragraph drops it when it renders anyway.
+const BLOCK_INDENT = /(?<=^|\n[ \t]*\n)[ \t]+/gu;
 
 const escapeBlockStart = (text: string): string =>
-  text.replaceAll(BLOCK_START, (marker: string) => {
+  text.replaceAll(BLOCK_START, (match: string, indent: string) => {
     // A numbered marker escapes its punctuation (`1\.`), the rest themselves.
+    const marker = match.slice(indent.length);
     const index = marker.search(/[.)]/u);
     return index === -1
-      ? `\\${marker}`
-      : `${marker.slice(0, index)}\\${marker.slice(index)}`;
+      ? `${indent}\\${marker}`
+      : `${indent}${marker.slice(0, index)}\\${marker.slice(index)}`;
   });
 
 const escapeEsmStart = (text: string): string =>
@@ -92,6 +100,17 @@ export const codeSpan = (code: string): string => {
   return `${fence}${pad}${code}${pad}${fence}`;
 };
 
+/**
+ * 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.
+ */
+export const guardBlockStart = (text: string): string =>
+  escapeEsmStart(text.replaceAll(BLOCK_INDENT, ""));
+
 const EDGE_SPACE = /^(?<lead>\s*)(?<body>[\s\S]*?)(?<trail>\s*)$/u;
 
 /**
@@ -122,13 +141,30 @@ export const renderInline = (text: string, marks: InlineMarks): string => {
   return `${lead}${out}${trail}`;
 };
 
-// A destination with whitespace or parentheses ends early in `[label](…)`;
-// CommonMark's pointy-bracket form carries it intact.
-const UNSAFE_DESTINATION = /[\s()]/u;
+// 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.
+const UNSAFE_DESTINATION = /[\s()\u0000-\u001F\u007F]/u;
+
+// Markdown decodes a destination before the browser sees it: a backslash
+// escape or a character reference becomes its character, so
+// `java&#115;cript:` would reach the `href` as `javascript:` after the safety
+// check passed it. Escaping both — and `<`/`>`, which would close the
+// pointy form early and let the rest of the URL open a second link — keeps
+// the `href` exactly the URL the CMS holds.
+const DESTINATION_SPECIALS = /[\\<>]|&(?=#?[a-z0-9]+;)/giu;
+
+// A destination can't hold a line break, and the URL parser drops tabs and
+// line breaks anyway, so removing them leaves the same URL.
+const DESTINATION_IGNORED = /[\t\n\r]/gu;
 
-/** A link or image destination as Markdown can carry it verbatim. */
-export const destination = (url: string): string =>
-  UNSAFE_DESTINATION.test(url) ? `<${url}>` : url;
+/** A link or image destination as Markdown carries it verbatim. */
+export const destination = (url: string): string => {
+  const escaped = url
+    .replaceAll(DESTINATION_IGNORED, "")
+    .replaceAll(DESTINATION_SPECIALS, String.raw`\$&`);
+  return UNSAFE_DESTINATION.test(escaped) ? `<${escaped}>` : escaped;
+};
 
 /**
  * A Markdown link, or the label alone when the target is missing — or unsafe:
@@ -172,10 +208,20 @@ export const indent = (text: string, width: number): string => {
     .join("\n");
 };
 
-/** A fenced code block whose fence outruns any backtick run in the code. */
+// A fence's language is one word of its info string. A backtick in it keeps
+// the fence from opening at all, so the code renders as Markdown and HTML,
+// and whitespace would start the meta Blume reads code titles from; a
+// language that isn't a single such word is dropped.
+const FENCE_LANGUAGE = /^[^\s`]+$/u;
+
+/**
+ * A fenced code block whose fence outruns any backtick run in the code,
+ * labeled with its language when that is one word a fence can carry.
+ */
 export const codeFence = (code: string, language = ""): string => {
   const fence = "`".repeat(Math.max(3, longestBacktickRun(code) + 1));
-  return `${fence}${language}\n${code}\n${fence}`;
+  const label = FENCE_LANGUAGE.test(language) ? language : "";
+  return `${fence}${label}\n${code}\n${fence}`;
 };
 
 /** A Markdown image; the alt is escaped so a `]` in a caption can't close it. */
@@ -193,12 +239,19 @@ export const writesMdx = <Node>(
   serializers?: Record<string, (node: Node) => string>
 ): boolean => serializers !== undefined && Object.keys(serializers).length > 0;
 
+// A node's type is the CMS's data too: a `*/` (or `--`) in it would close the
+// comment early and let the rest run as MDX (or render as HTML). A space
+// between the two characters keeps it inside.
+const COMMENT_END = /\*\/|--/gu;
+
 /**
  * A comment marking a node the lowerer has no Markdown for — an MDX comment
  * when the output is MDX, which rejects `<!-- -->`.
  */
-export const unsupported = (what: string, mdx = false): string =>
-  mdx ? `{/* unsupported ${what} */}` : `<!-- unsupported ${what} -->`;
+export const unsupported = (what: string, mdx = false): string => {
+  const label = what.replaceAll(COMMENT_END, (end) => [...end].join(" "));
+  return mdx ? `{/* unsupported ${label} */}` : `<!-- unsupported ${label} -->`;
+};
 
 /** Blocks separated by blank lines; empty blocks are dropped. */
 export const joinBlocks = (blocks: string[]): string =>

package/src/core/sources/mdx-remote.ts

@@ -253,5 +253,6 @@ export const mdxRemoteSource = (
           () => load()
         )
       : undefined,
+    withContext: (next) => mdxRemoteSource(options, next),
   };
 };