blume 2.0.1 → 2.0.3

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

@@ -9,17 +9,18 @@
  */
 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,
+  guardBlockStart,
   headingPrefix,
   image,
   joinBlocks,
+  linkParts,
   listItem,
   markdownDocument,
   renderInline,
-  renderLink,
   unsupported,
   writesMdx,
 } from "./lower.ts";
@@ -138,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,
@@ -197,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`\|`);
@@ -234,11 +242,11 @@ const renderBlock = (
   const type = asString(node.nodeType) ?? "";
   const heading = HEADING.exec(type)?.groups?.level;
   if (heading) {
-    return `${headingPrefix(Number(heading))}${renderInlines(children(node), options)}`;
+    return `${headingPrefix(Number(heading))}${blockText(node, options)}`;
   }
   switch (type) {
     case "paragraph": {
-      return renderInlines(children(node), options);
+      return blockText(node, options);
     }
     case "blockquote": {
       return blockquote(

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

@@ -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 => {
@@ -83,7 +101,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 +133,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,8 @@ import {
   pollingWatch,
   snapshotCache,
 } from "./cache.ts";
+import { destination, escapeMarkdownText } from "./lower.ts";
+import { REMOTE_TIMEOUT_MS } from "./remote.ts";
 import type {
   ContentSource,
   SourceContext,
@@ -43,6 +45,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 +171,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 +290,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
@@ -260,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[]> => {
@@ -295,7 +412,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 +466,6 @@ export const githubReleasesSource = (
           () => load()
         )
       : undefined,
+    withContext: (next) => githubReleasesSource(options, next),
   };
 };

package/src/core/sources/lexical.ts

@@ -7,17 +7,18 @@
  */
 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,
+  guardBlockStart,
   headingPrefix,
   image,
   indent,
+  linkParts,
   listItem,
   markdownDocument,
   renderInline,
-  renderLink,
   unsupported,
   writesMdx,
 } from "./lower.ts";
@@ -66,45 +67,54 @@ 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 =>
+  inlineText(children(node), options);
+
 const renderUpload = (node: JsonObject, options: LexicalOptions): string => {
   const value = asObject(node.value);
   const url = value ? asString(value.url) : undefined;
@@ -140,7 +150,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}${inlineText(inline, options)}`;
     items.push(listItem(lastMarker, sub ? `${line}\n${sub}` : line));
     index += 1;
   }
@@ -150,14 +160,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);