blume 2.1.3 → 2.2.0

package/src/markdown/content-assets.ts

@@ -0,0 +1,210 @@
+import { fileURLToPath } from "node:url";
+
+import { dirname, join, normalize } from "pathe";
+
+import { RUNTIME_MODULE_FILES } from "../astro/runtime-modules.ts";
+import { contentAssetUrl } from "../core/content-assets.ts";
+import {
+  resolveRelativeFile,
+  resolveRelativeImage,
+} from "../core/relative-files.ts";
+import {
+  isLinkElementUrl,
+  rewriteElementUrls,
+} from "../core/sources/normalize.ts";
+import type { MdastNode, MdastValue } from "./mdast.ts";
+import { snapshotReader } from "./route-snapshot.ts";
+
+/** An MDX JSX attribute, as the plugin reads it. */
+interface JsxAttribute {
+  [key: string]: MdastValue;
+  name?: string;
+  type?: string;
+  value?: MdastValue;
+}
+
+/** An MDX JSX element (`<Card img="./cover.png" />`), as the plugin reads it. */
+interface JsxNode extends MdastNode {
+  attributes?: JsxAttribute[];
+  children?: MdastValue[];
+  name?: string | null;
+}
+
+/** A link or a reference definition (`[spec]: ./spec.pdf`). */
+interface UrlNode extends MdastNode {
+  url?: string | null;
+}
+
+/** Raw HTML in a `.md` page. */
+interface HtmlNode extends MdastNode {
+  value: string;
+}
+
+/** The visitor-context slice this plugin uses (see `mdast.ts` for the model). */
+interface ContentAssetsContext {
+  fileURL: URL | undefined;
+  replaceNode: (node: MdastNode, replacement: MdastNode) => void;
+  setProperty: (node: MdastNode, key: "url" | "value", value: string) => void;
+}
+
+export interface ContentAssetsPluginOptions {
+  /**
+   * The `blume:data` snapshot file an ejected app aliases. The served
+   * content-assets map is written beside it, and read from there when no CLI
+   * publishes it.
+   */
+  dataFile?: string;
+  /** Astro's `deployment.base` subdirectory (`""` or `/seg`). */
+  deployBase?: string;
+}
+
+/** A plain string attribute value; an expression value isn't a path. */
+const isStringValue = (value: MdastValue): value is string =>
+  typeof value === "string";
+
+/** The directory of the page being compiled, when the compiler names it. */
+const pageDir = (ctx: ContentAssetsContext): string | undefined =>
+  ctx.fileURL ? dirname(normalize(fileURLToPath(ctx.fileURL))) : undefined;
+
+/**
+ * Satteri MDAST plugin that points a page's references to files beside it at
+ * their served copies (`/blume-assets/content/…`), the way a colocated
+ * `![](./cover.png)` is published: a `<Card img="./cover.png">`, a link or a
+ * reference definition naming a file (`[spec](./spec.pdf)`), and an
+ * element's `src` or `href` (`<img src="./diagram.png">`, `<a href>`, a
+ * component's `href`) in `.mdx`, or in a `.md` page's raw HTML. Left as
+ * written, each ships as a relative URL the browser resolves against the
+ * page's URL, where nothing is served. A card's image is resolved from
+ * beside the page as an embed is (`resolveRelativeImage`), and any other
+ * file as `resolveRelativeFile` finds one; an included partial's were
+ * already rebased onto the page by the include expander. A reference is
+ * rewritten only when the content-assets endpoint serves its file: the map
+ * `collectContentAssets` builds over the same references. Anything else is
+ * left as written, and `blume validate` reports it.
+ */
+export const contentAssetsPlugin = (
+  options: ContentAssetsPluginOptions = {}
+) => {
+  const assetsFile = options.dataFile
+    ? join(
+        dirname(options.dataFile),
+        RUNTIME_MODULE_FILES.get("blume:content-assets") ?? ""
+      )
+    : undefined;
+  const readAssets = snapshotReader("blume:content-assets", assetsFile);
+
+  // The map is published as `param → absolute path`; parsed once per
+  // published text and inverted, so each reference looks its file up directly.
+  let cached: { params: Map<string, string>; text: string } | undefined;
+  const servedParams = (): Map<string, string> | undefined => {
+    const text = readAssets();
+    if (text === undefined) {
+      return undefined;
+    }
+    if (cached?.text !== text) {
+      const files: Record<string, string> = JSON.parse(text);
+      cached = {
+        params: new Map(
+          Object.entries(files).map(([param, path]) => [normalize(path), param])
+        ),
+        text,
+      };
+    }
+    return cached.params;
+  };
+
+  /** The served URL of `file`, or undefined when the endpoint doesn't serve it. */
+  const servedUrl = (file: string | null, suffix = ""): string | undefined => {
+    const param = file === null ? undefined : servedParams()?.get(file);
+    return param === undefined
+      ? undefined
+      : `${contentAssetUrl(param, options.deployBase)}${suffix}`;
+  };
+
+  /** The served URL of a file a link or an element URL names beside the page. */
+  const fileUrl = (dir: string, target: string): string | undefined => {
+    const file = resolveRelativeFile(dir, target);
+    return file ? servedUrl(file.path, file.suffix) : undefined;
+  };
+
+  const rewriteUrl = (node: UrlNode, ctx: ContentAssetsContext): void => {
+    const dir = pageDir(ctx);
+    const next =
+      dir && isStringValue(node.url) ? fileUrl(dir, node.url) : undefined;
+    if (next !== undefined) {
+      ctx.setProperty(node, "url", next);
+    }
+  };
+
+  const rewriteHtml = (node: HtmlNode, ctx: ContentAssetsContext): void => {
+    const dir = pageDir(ctx);
+    if (dir === undefined) {
+      return;
+    }
+    const next = rewriteElementUrls(node.value, (url) =>
+      isLinkElementUrl(url) ? (fileUrl(dir, url.value) ?? null) : null
+    );
+    if (next !== node.value) {
+      ctx.setProperty(node, "value", next);
+    }
+  };
+
+  /** The served URL an element's attribute is rewritten to, if any. */
+  const attributeUrl = (
+    dir: string,
+    tag: string,
+    attribute: JsxAttribute
+  ): string | undefined => {
+    const { name, value } = attribute;
+    if (
+      attribute.type !== "mdxJsxAttribute" ||
+      name === undefined ||
+      !isStringValue(value)
+    ) {
+      return undefined;
+    }
+    if (tag === "Card" && name === "img") {
+      return servedUrl(resolveRelativeImage(dir, value));
+    }
+    return isLinkElementUrl({ attribute: name, tag, value })
+      ? fileUrl(dir, value)
+      : undefined;
+  };
+
+  const rewriteElement = (node: JsxNode, ctx: ContentAssetsContext): void => {
+    const dir = pageDir(ctx);
+    const { name } = node;
+    if (!(dir && name)) {
+      return;
+    }
+    const attributes = node.attributes ?? [];
+    let changed = false;
+    const next = attributes.map((attribute) => {
+      const url = attributeUrl(dir, name, attribute);
+      if (url === undefined) {
+        return attribute;
+      }
+      changed = true;
+      return { name: attribute.name, type: attribute.type, value: url };
+    });
+    if (changed) {
+      // Sätteri can't set a JSX element's attributes in place, so the element
+      // is swapped for a copy; its children carry over and are still visited.
+      ctx.replaceNode(node, {
+        attributes: next,
+        children: node.children ?? [],
+        name,
+        type: node.type,
+      });
+    }
+  };
+
+  return {
+    definition: rewriteUrl,
+    html: rewriteHtml,
+    link: rewriteUrl,
+    mdxJsxFlowElement: rewriteElement,
+    mdxJsxTextElement: rewriteElement,
+    name: "blume-content-assets",
+  };
+};

package/src/markdown/directives.ts

@@ -56,6 +56,72 @@ export const calloutTypeFor = (name: string): string | null => {
   return CALLOUT_ALIASES[lower] ?? null;
 };
 
+// The characters that start inline Markdown in plain text, escaped so the
+// text reads back as written.
+const MARKDOWN_SPECIAL = /[\\`*_~[\]<]/gu;
+
+const escapeMarkdown = (text: string): string =>
+  text.replaceAll(MARKDOWN_SPECIAL, String.raw`\$&`);
+
+const BACKTICK_RUN = /`+/gu;
+
+/** A code span holding `code` verbatim. */
+const codeSpan = (code: string): string => {
+  const runs = [...code.matchAll(BACKTICK_RUN)].map(([run]) => run.length);
+  const fence = "`".repeat(Math.max(0, ...runs) + 1);
+  // A backtick at either end would join the fence, and CommonMark strips one
+  // space from each end of a span that has both: a space pads either case.
+  const pad =
+    code.startsWith("`") ||
+    code.endsWith("`") ||
+    (code.startsWith(" ") && code.endsWith(" ") && code.trim() !== "")
+      ? " "
+      : "";
+  return `${fence}${pad}${code}${pad}${fence}`;
+};
+
+// What can't sit inside a `<…>` link destination.
+const DESTINATION_UNSAFE = /[<>\n]/gu;
+
+/**
+ * A node's phrasing children (a directive label's, a paragraph's) written
+ * back as inline Markdown, for a component prop that renders it — a callout
+ * title. Text, emphasis, strong, strikethrough, code, and links keep their
+ * formatting; anything else reads as its text (an image as nothing, raw HTML
+ * as its literal source), the way a flattened title always did.
+ */
+export const phrasingMarkdown = (parent: MdastNode): string =>
+  // SAFETY: a phrasing parent's `children` is a node list.
+  ((parent.children ?? []) as MdastNode[])
+    .map((node) => {
+      switch (node.type) {
+        case "strong": {
+          return `**${phrasingMarkdown(node)}**`;
+        }
+        case "emphasis": {
+          return `*${phrasingMarkdown(node)}*`;
+        }
+        case "delete": {
+          return `~~${phrasingMarkdown(node)}~~`;
+        }
+        case "inlineCode": {
+          return codeSpan(mdastToString(node));
+        }
+        case "link": {
+          const url = String(node.url ?? "").replaceAll(
+            DESTINATION_UNSAFE,
+            encodeURIComponent
+          );
+          return `[${phrasingMarkdown(node)}](<${url}>)`;
+        }
+        default: {
+          break;
+        }
+      }
+      return escapeMarkdown(mdastToString(node, { includeImageAlt: false }));
+    })
+    .join("");
+
 /** The markers that open a text (`:name`) and a leaf (`::name`) directive. */
 const LITERAL_MARKERS = new Map([
   ["leafDirective", "::"],
@@ -194,12 +260,10 @@ const renderContainer = (
     ];
   }
 
-  // Flatten the label's phrasing children so `:::note[Read **this**]` yields
-  // `Read this`; image alt is excluded (an image is not label text), matching
-  // the historical child-values-only behavior.
+  // The label's phrasing as Markdown, which `<Callout>` renders in its title:
+  // `:::note[Read **this**]` keeps its bold.
   const title =
-    node.attributes?.title ??
-    (label ? mdastToString(label, { includeImageAlt: false }) : undefined);
+    node.attributes?.title ?? (label ? phrasingMarkdown(label) : undefined);
   const attributes = [jsxAttribute("type", type)];
   if (title) {
     attributes.push(jsxAttribute("title", title));

package/src/markdown/fence-language.ts

@@ -0,0 +1,106 @@
+/**
+ * A code fence's language, read the way authors coming from other docs tools
+ * write it. Shiki matches language ids exactly, so two common spellings used
+ * to fall back to plain text with only a console line:
+ *
+ * - a capitalized id (```` ```JSON ````, ```` ```Dockerfile ````): Shiki's ids
+ *   and aliases are all lowercase, so the id is lowercased when that names a
+ *   language and the spelling as written doesn't.
+ * - a line range glued to the id (```` ```js{2} ````, the VitePress and
+ *   VuePress form): the range moves into the fence meta, ahead of any meta
+ *   already there, where the line-highlight transformer reads it.
+ * - a line range glued to a bracketed title (```` ```ts [file.ts]{2} ````,
+ *   the Docus form): a space splits it off, so the title is the bracketed
+ *   word alone and the range stays a range.
+ *
+ * Every other fence keeps its language and meta exactly as written.
+ */
+
+import { bundledLanguages } from "shiki/langs";
+
+import type { MdastNode } from "./mdast.ts";
+
+/** The ids Shiki renders without a grammar: plain text and ANSI output. */
+const PLAIN_LANGUAGES: ReadonlySet<string> = new Set([
+  "ansi",
+  "plain",
+  "plaintext",
+  "text",
+  "txt",
+]);
+
+/** Whether Shiki highlights `lang` as written: a bundled id, alias, or plain. */
+export const isKnownLanguage = (lang: string): boolean =>
+  PLAIN_LANGUAGES.has(lang) || Object.hasOwn(bundledLanguages, lang);
+
+/** A language id with a line range glued on: `js{2}`, `ts{1,3-5}`. */
+const GLUED_RANGE = /^(?<lang>[^{]+)(?<range>\{[^}]*\})$/u;
+
+/** A bracketed title with a line range glued on: `[file.ts]{2}`. */
+const GLUED_TITLE_RANGE =
+  /(?<=^|\s)(?<title>\[[^\]]*\])(?<range>\{[^}]*\})(?=\s|$)/u;
+
+/** A fence's language and meta, after {@link normalizeFence}. */
+export interface Fence {
+  lang: string;
+  meta: string | null;
+}
+
+/**
+ * The language and meta a fence means, or null when it means what it says.
+ * A range glued to the language moves into the meta and one glued to a
+ * bracketed title splits off it, then a capitalized language that only names
+ * a known language in lowercase is lowercased.
+ */
+export const normalizeFence = (
+  lang: string | null | undefined,
+  meta: string | null | undefined
+): Fence | null => {
+  if (!lang) {
+    return null;
+  }
+  const glued = GLUED_RANGE.exec(lang)?.groups;
+  const id = glued?.lang ?? lang;
+  const fenceMeta =
+    (glued?.range
+      ? [glued.range, meta].filter(Boolean).join(" ")
+      : meta
+    )?.replace(GLUED_TITLE_RANGE, "$<title> $<range>") ?? null;
+  const lower = id.toLowerCase();
+  const language = !isKnownLanguage(id) && isKnownLanguage(lower) ? lower : id;
+  return language === lang && fenceMeta === (meta ?? null)
+    ? null
+    : { lang: language, meta: fenceMeta };
+};
+
+/** The code node slice the plugin reads. */
+interface CodeNode extends MdastNode {
+  lang?: string | null;
+  meta?: string | null;
+}
+
+/** The visitor context slice the plugin writes through. */
+interface FenceContext {
+  setProperty: (
+    node: CodeNode,
+    key: "lang" | "meta",
+    value: string | null
+  ) => void;
+}
+
+/**
+ * Satteri MDAST plugin applying {@link normalizeFence} to every fence. It runs
+ * before the plugins that read a fence's language (`package-install`, `ts2js`,
+ * mermaid) and before Shiki, so all of them see the normalized fence.
+ */
+export const fenceLanguagePlugin = () => ({
+  code(node: CodeNode, ctx: FenceContext) {
+    const fence = normalizeFence(node.lang, node.meta);
+    if (!fence) {
+      return;
+    }
+    ctx.setProperty(node, "lang", fence.lang);
+    ctx.setProperty(node, "meta", fence.meta);
+  },
+  name: "blume-fence-language",
+});

package/src/markdown/fence-meta.ts

@@ -48,5 +48,47 @@ export const RESERVED_META_KEYWORDS: ReadonlySet<string> = new Set([
   "wrap",
 ]);
 
+/**
+ * Bare keywords other docs tools read after the language, which Blume
+ * doesn't: Mintlify's `lines` and Docusaurus' `showLineNumbers` (line
+ * numbers) and Fern's `wordWrap` on any fence, and rustdoc's and mdBook's test
+ * and playground attributes on a Rust one. They do nothing here, so they're
+ * never promoted to a block title, and `blume check` warns about each
+ * (`BLUME_CODE_FENCE_OPTION`).
+ */
+const FOREIGN_META_KEYWORDS: ReadonlySet<string> = new Set([
+  "lines",
+  "wordWrap",
+]);
+
+// Docusaurus' line-numbers keyword, with an optional start line
+// (`showLineNumbers{3}`).
+const SHOW_LINE_NUMBERS = /^showLineNumbers(?:\{\d*\})?$/u;
+
+export const RUST_META_KEYWORDS: ReadonlySet<string> = new Set([
+  "compile_fail",
+  "edition2015",
+  "edition2018",
+  "edition2021",
+  "edition2024",
+  "editable",
+  "ignore",
+  "no_run",
+  "noplayground",
+  "should_panic",
+]);
+
+/** The fence languages rustdoc's and mdBook's keywords apply to. */
+export const RUST_LANGUAGES: ReadonlySet<string> = new Set(["rs", "rust"]);
+
+/** Whether `token` is another tool's keyword in a fence of language `lang`. */
+export const isForeignKeyword = (
+  token: string,
+  lang: string | null | undefined
+): boolean =>
+  FOREIGN_META_KEYWORDS.has(token) ||
+  SHOW_LINE_NUMBERS.test(token) ||
+  (RUST_LANGUAGES.has(lang ?? "") && RUST_META_KEYWORDS.has(token));
+
 /** A Shiki `{1,3-5}` line-range token. */
 export const isLineRange = (token: string): boolean => token.startsWith("{");

package/src/markdown/github-alerts.ts

@@ -0,0 +1,172 @@
+import { phrasingMarkdown } from "./directives.ts";
+import { jsxAttribute, jsxFlowElement } from "./mdast.ts";
+import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
+
+/**
+ * The callout each GitHub alert renders as. `IMPORTANT` has no callout of its
+ * own and reads as a note (`:::important` does too), and `CAUTION` — GitHub's
+ * red "risks or negative outcomes" alert — as danger.
+ */
+export const ALERT_CALLOUTS: ReadonlyMap<string, string> = new Map([
+  ["caution", "danger"],
+  ["important", "note"],
+  ["note", "note"],
+  ["tip", "tip"],
+  ["warning", "warning"],
+]);
+
+// `[!NOTE]` opening a quote's first line, any case, as GitHub reads it.
+const ALERT_MARKER = /^\[!(?<kind>[a-z]+)\]/iu;
+
+/** An alert marker as written (`[!NOTE]`) and the callout it renders as. */
+export interface AlertMarker {
+  callout: string;
+  marker: string;
+}
+
+/** The alert marker a quote's first text opens with, if any. */
+export const alertMarkerOf = (text: string): AlertMarker | undefined => {
+  const match = ALERT_MARKER.exec(text);
+  const callout = ALERT_CALLOUTS.get(match?.groups?.kind?.toLowerCase() ?? "");
+  return match && callout ? { callout, marker: match[0] } : undefined;
+};
+
+/** The visitor-context slice the alert visitor uses. */
+interface AlertVisitorContext extends MdastVisitorContext {
+  parent?: (node: MdastNode) => MdastNode | undefined;
+  source?: string;
+}
+
+/** The node's children. */
+const childrenOf = (node: MdastNode | undefined): MdastNode[] =>
+  // SAFETY: a parent's `children` is always a node list; leaves carry none.
+  (node?.children ?? []) as MdastNode[];
+
+/** A text node's value, or undefined for any other node. */
+const textOf = (node: MdastNode | undefined): string | undefined =>
+  node?.type === "text" ? String(node.value) : undefined;
+
+/** A text node's start offset into the page, when the parse recorded one. */
+const startOffset = (node: MdastNode): number | undefined => {
+  // SAFETY: Satteri positions carry numeric offsets.
+  const position = node.position as { start?: { offset?: number } } | undefined;
+  return position?.start?.offset;
+};
+
+/** The alert a blockquote opens with: its callout type and first paragraph. */
+interface Alert {
+  paragraph: MdastNode;
+  type: string;
+}
+
+/**
+ * The alert a blockquote is, or undefined. Its first paragraph must open with
+ * the marker as written: an escaped `\[!NOTE]` (text once parsed) starts with
+ * a backslash in the page.
+ */
+const alertOf = (node: MdastNode, source: string): Alert | undefined => {
+  const [paragraph] = childrenOf(node);
+  const first = childrenOf(paragraph).at(0);
+  const text = textOf(first);
+  if (paragraph?.type !== "paragraph" || first === undefined || !text) {
+    return undefined;
+  }
+  const marker = alertMarkerOf(text);
+  const offset = startOffset(first);
+  if (
+    marker === undefined ||
+    (offset !== undefined && source[offset] === "\\")
+  ) {
+    return undefined;
+  }
+  return { paragraph, type: marker.callout };
+};
+
+/** A paragraph's phrasing split at its first line break. */
+interface Lines {
+  first: MdastNode[];
+  rest: MdastNode[];
+}
+
+/** Split phrasing at its first line break: a newline in text, or a hard break. */
+const splitFirstLine = (nodes: readonly MdastNode[]): Lines => {
+  for (const [index, node] of nodes.entries()) {
+    const after = nodes.slice(index + 1);
+    if (node.type === "break") {
+      return { first: nodes.slice(0, index), rest: after };
+    }
+    const newline = textOf(node)?.indexOf("\n") ?? -1;
+    if (newline !== -1) {
+      const value = String(node.value);
+      const head = value.slice(0, newline);
+      const tail = value.slice(newline + 1);
+      return {
+        first: [...nodes.slice(0, index), { type: "text", value: head }],
+        rest: tail === "" ? after : [{ type: "text", value: tail }, ...after],
+      };
+    }
+  }
+  return { first: [...nodes], rest: [] };
+};
+
+/**
+ * A GitHub alert as a `<Callout>`: the marker comes off the first line, text
+ * after it on that line becomes the title (VitePress and Obsidian write
+ * `> [!WARNING] Heads up`), and the rest of the quote is the body.
+ */
+const alertCallout = ({ paragraph, type }: Alert, quote: MdastNode) => {
+  const [first, ...phrasing] = childrenOf(paragraph);
+  const opening = String(first?.value).replace(ALERT_MARKER, "");
+  const lines = splitFirstLine([{ type: "text", value: opening }, ...phrasing]);
+  const title = phrasingMarkdown({ children: lines.first, type: "paragraph" });
+  const attributes = [jsxAttribute("type", type)];
+  if (title.trim() !== "") {
+    attributes.push(jsxAttribute("title", title.trim()));
+  }
+  const body = lines.rest.length
+    ? [{ children: lines.rest, type: "paragraph" }]
+    : [];
+  return jsxFlowElement("Callout", attributes, [
+    ...body,
+    ...childrenOf(quote).slice(1),
+  ]);
+};
+
+/** Whether `node` sits inside a quote that is itself an alert. */
+const insideAlert = (node: MdastNode, ctx: AlertVisitorContext): boolean => {
+  for (
+    let parent = ctx.parent?.(node);
+    parent !== undefined;
+    parent = ctx.parent?.(parent)
+  ) {
+    if (
+      parent.type === "blockquote" &&
+      alertOf(parent, ctx.source ?? "") !== undefined
+    ) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/**
+ * Satteri MDAST plugin for GitHub alerts in `.mdx`: a quote whose first line
+ * is `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, or `[!CAUTION]`
+ * renders as the matching `<Callout>` (see {@link ALERT_CALLOUTS}), as on
+ * GitHub. An alert quoted inside another stays a quote, as GitHub leaves it.
+ * `.md` pages render no components, so their alerts stay quotes, which
+ * `blume check` warns about (`core/alert-diagnostics.ts`).
+ */
+export const githubAlertsPlugin = () => ({
+  blockquote(node: MdastNode, ctx: AlertVisitorContext) {
+    const alert = alertOf(node, ctx.source ?? "");
+    if (alert === undefined || insideAlert(node, ctx)) {
+      return;
+    }
+    ctx.replaceNode(node, alertCallout(alert, node));
+  },
+  name: "blume-github-alerts",
+  // Positions are opt-in since satteri 0.10; they tell an escaped marker
+  // from a written one.
+  options: { position: true },
+});