blume 2.0.1 → 2.0.3

package/src/core/sources/notion.ts

@@ -15,8 +15,15 @@ import {
   pollingWatch,
   snapshotCache,
 } from "./cache.ts";
-import { codeFence, image, renderInline, renderLink } from "./lower.ts";
-import { slugifyPath } from "./normalize.ts";
+import type { InlineRun } from "./lower.ts";
+import {
+  codeFence,
+  guardBlockStart,
+  image,
+  linkParts,
+  renderInline,
+} from "./lower.ts";
+import { slugify, slugifyPath } from "./normalize.ts";
 import type {
   ContentSource,
   SourceContext,
@@ -154,26 +161,43 @@ interface NotionFrontmatter {
   [key: string]: boolean | string | { order: number } | undefined;
 }
 
+/** Neighboring rich-text runs that link to one `href` (or none), and it. */
+interface LinkedRuns {
+  href?: string;
+  runs: InlineRun[];
+}
+
 /**
- * Rich text as Markdown for an MDX body. Each run goes through the shared
+ * Rich text as Markdown for an MDX body. The runs go through the shared
  * lowering, so a literal `{`, `<`, `*`, or `[` typed in Notion renders as
- * itself instead of opening a JSX expression, a tag, or emphasis, and a code
- * run keeps its text verbatim inside a long-enough code span.
+ * itself instead of opening a JSX expression, a tag, or emphasis, a code run
+ * keeps its text verbatim inside a long-enough code span, neighbors share
+ * their marks' delimiters, and neighbors that link to one `href` share one
+ * link.
  */
-const richToMarkdown = (rich: NotionRichText[] = []): string =>
-  rich
-    .map(({ annotations = {}, href, plain_text: text }) =>
-      renderLink(
-        renderInline(text, {
-          bold: annotations.bold,
-          code: annotations.code,
-          italic: annotations.italic,
-          strike: annotations.strikethrough,
-        }),
-        href ?? undefined
-      )
-    )
-    .join("");
+const richToMarkdown = (rich: NotionRichText[] = []): string => {
+  const linked: LinkedRuns[] = [];
+  for (const { annotations = {}, href, plain_text: text } of rich) {
+    const run: InlineRun = {
+      marks: {
+        bold: annotations.bold,
+        code: annotations.code,
+        italic: annotations.italic,
+        strike: annotations.strikethrough,
+      },
+      text,
+    };
+    const last = linked.at(-1);
+    if (last && last.href === (href ?? undefined)) {
+      last.runs.push(run);
+    } else {
+      linked.push({ href: href ?? undefined, runs: [run] });
+    }
+  }
+  return renderInline(
+    linked.flatMap(({ href, runs }) => linkParts(runs, href))
+  );
+};
 
 const isBlockPayload = (
   value: NotionBlockPayload | boolean | string | undefined
@@ -217,12 +241,12 @@ const withNotionRetry = async <T>(
     if (status !== RATE_LIMITED || attempt === MAX_RETRIES) {
       throw error;
     }
-    // SAFETY: same APIResponseError shape — `headers` maps lower-cased HTTP
-    // header names to their values; a missing header yields `NaN` and falls
-    // back to exponential backoff.
-    const retryAfter = Number(
-      (error as { headers?: Record<string, string> }).headers?.["retry-after"]
-    );
+    // SAFETY: same APIResponseError shape — `headers` is the failed
+    // response's fetch `Headers`, read with `get()`; a missing header (or
+    // headers without `get`) yields no positive wait and falls back to
+    // exponential backoff.
+    const { headers } = error as { headers?: Headers };
+    const retryAfter = Number(headers?.get?.("retry-after"));
     const wait =
       retryAfter > 0
         ? retryAfter * SECOND_MS
@@ -266,6 +290,12 @@ const richToPlain = (rich: NotionRichText[] = []): string =>
  */
 const jsxString = (value: string): string => `{${JSON.stringify(value)}}`;
 
+// `<Frame>` renders its caption as Markdown after escaping `<` and `>` itself
+// (so a caption can't inject HTML), which turns the lowering's own `\<` into
+// a visible `&lt;`. Its caption drops those backslashes and leaves the
+// escaping to Frame; every other escape still applies.
+const FRAME_ESCAPED = /\\(?=[<>])/gu;
+
 const YOUTUBE_HOST = /(?:^|\.)(?:youtube(?:-nocookie)?\.com|youtu\.be)$/u;
 
 // `parseYouTubeId` is host-agnostic on purpose (the component accepts bare
@@ -295,19 +325,23 @@ const renderVideo = (data: NotionBlockPayload): string => {
   const title = caption ? ` title=${jsxString(richToPlain(data.caption))}` : "";
   // Everything else (a Notion upload, or a direct link to a media file) is a
   // real video file: `materializeAssets` rewrites the `src`, which matters most
-  // for uploads, whose Notion URLs are signed and expire.
+  // for uploads, whose Notion URLs are signed and expire. It finds the file by
+  // that quoted `src`, where MDX decodes no backslash escapes — a JSON
+  // string's `\\` and `\"` would corrupt the URL or end the attribute — so the
+  // URL goes in as written, with a double quote as the `%22` it means anyway.
+  // The embed's `url` takes the expression form, like every string prop here.
   const media = isYouTubeUrl(url)
-    ? `<YouTube${title} url=${JSON.stringify(url)} />`
-    : `<video controls src=${JSON.stringify(url)} />`;
+    ? `<YouTube${title} url=${jsxString(url)} />`
+    : `<video controls src="${url.replaceAll('"', "%22")}" />`;
   return caption
-    ? `<Frame caption=${jsxString(caption)}>\n${media}\n</Frame>`
+    ? `<Frame caption=${jsxString(caption.replaceAll(FRAME_ESCAPED, ""))}>\n${media}\n</Frame>`
     : media;
 };
 
 /** Render a leaf (non-container) block to Markdown, or null for containers. */
 const renderLeaf = (block: NotionBlock): string | null => {
   const data = payloadOf(block) ?? {};
-  const text = richToMarkdown(blockField(block));
+  const text = guardBlockStart(richToMarkdown(blockField(block)));
   switch (block.type) {
     case "paragraph": {
       return text;
@@ -440,7 +474,10 @@ export const notionSource = (
     };
 
     if (block.type === "callout") {
-      const body = [richToMarkdown(blockField(block)), await children(block)]
+      const body = [
+        guardBlockStart(richToMarkdown(blockField(block))),
+        await children(block),
+      ]
         .filter(Boolean)
         .join("\n\n");
       return `<Callout>\n${body}\n</Callout>`;
@@ -562,9 +599,14 @@ export const notionSource = (
     const slugProp = richToPlain(
       page.properties[props.slug ?? "Slug"]?.rich_text
     );
-    // Path-aware: a `guides/setup` slug keeps its `/` (per-segment slugging)
-    // instead of mashing into `guidessetup`.
-    const slug = slugifyPath(slugProp || title) || page.id;
+    // A Slug property is path-aware: `guides/setup` keeps its `/` (per-segment
+    // slugging) instead of mashing into `guidessetup`. A title is one name, so
+    // its slashes become hyphens: "CI/CD Setup" routes to `ci-cd-setup`, not
+    // to `cd-setup` inside an invented `ci` group.
+    const slug =
+      (slugProp
+        ? slugifyPath(slugProp)
+        : slugify(title.replaceAll("/", "-"))) || page.id;
     return { data, slug };
   };
 
@@ -680,5 +722,6 @@ export const notionSource = (
           () => load()
         )
       : undefined,
+    withContext: (next) => notionSource(options, next),
   };
 };

package/src/core/sources/obsidian.ts

@@ -20,6 +20,8 @@ import {
   placeEntryRef,
   resolveEntryRoute,
   slugifyPath,
+  strippedLineOffset,
+  unloadablePathDiagnostic,
 } from "./normalize.ts";
 import type {
   ContentSource,
@@ -84,6 +86,8 @@ interface ParsedNote {
   /** The note body, frontmatter stripped and otherwise untouched. */
   content: string;
   data: SourceEntry["data"];
+  /** How many lines of the file the frontmatter block (if any) spans. */
+  frontmatterLines: number;
   placement: EntryPlacement;
   /** Vault-relative path, e.g. `guides/Getting Started.md`. */
   rel: string;
@@ -584,10 +588,11 @@ const transformBody = (
  * `[#custom-id]` pin and the `setup-1` a later collision gets are honored
  * rather than re-slugged. When no heading holds anything the rewrite changes,
  * the raw body's headings are the staged body's; otherwise the body is lowered
- * once more so the headings are scanned exactly as they ship. A link inside a
- * heading is rewritten here before the other notes' anchors are known, so its
- * own anchor is left off; that only moves the manifest id of a heading that
- * itself holds a heading link, which the docs already flag as unaddressable.
+ * once more so the headings are scanned exactly as they ship. A heading link
+ * inside a heading is rewritten here before every note's anchors are known,
+ * so its href may still lack the anchor it ships with. That moves no id: a
+ * heading is slugged by its rendered text, where the link is its label alone,
+ * so the heading stays as addressable as any other.
  */
 const fillAnchors = (pair: IndexedPair, index: LinkIndex): void => {
   const raw = extractHeadings(pair.note.content);
@@ -638,7 +643,7 @@ const buildLinkIndex = (
       { ref: note.rel, slug: entrySlugFor(note.placement.navPath) },
       ".md",
       isStringValue(note.data.slug) ? note.data.slug : undefined,
-      options
+      { ...options, orderingPrefixes: true }
     );
     const built: IndexedNote = {
       anchors: new Map(),
@@ -756,10 +761,17 @@ const noteToEntry = (
     )
   );
   const merged = title === undefined ? data : { ...data, title };
-  const text = transformBody(note.content.trim(), index, pair.self, unresolved);
+  const body = note.content.trim();
+  const text = transformBody(body, index, pair.self, unresolved);
   const raw = matter.stringify(`${text}\n`, merged);
+  // `raw` re-serializes the frontmatter without the dropped properties, so
+  // its height is not the file's: count the file's own frontmatter and the
+  // blank lines the trim dropped, so a link diagnostic names the line the
+  // author sees in the note.
+  const leading = note.content.slice(0, note.content.indexOf(body));
   return {
     body: { format: "md", text },
+    bodyLineOffset: note.frontmatterLines + leading.split("\n").length - 1,
     data: merged,
     hash: hashText(raw),
     raw,
@@ -782,11 +794,13 @@ const readNote = async (
 ): Promise<ParsedNote | null> => {
   const absPath = join(vaultDir, rel);
   try {
-    const { content, data } = matter(await readFile(absPath, "utf-8"));
+    const file = await readFile(absPath, "utf-8");
+    const { content, data } = matter(file);
     return {
       absPath,
       content,
       data,
+      frontmatterLines: strippedLineOffset(file, content),
       // Version outermost, then locale, the way `normalizeEntry` reads the
       // ref — the slug is built from what remains, so the pipeline's own
       // re-prefixing does not stack a second `fr/` or `v1.0/` onto the route.
@@ -946,7 +960,19 @@ export const obsidianSource = (
   const exclude = new Set([...BLUME_IGNORE_DIRS, ...(options.exclude ?? [])]);
 
   const load = async (): Promise<SourceLoadResult> => {
-    const files = await walkVault(vaultDir, vaultDir, exclude);
+    // A note is staged under its vault path, where Astro's content loader
+    // can't read a name holding `#` or `?`; such a note is reported and left
+    // out, and links to it degrade like links to any missing note.
+    const skipped: Diagnostic[] = [];
+    const files: string[] = [];
+    for (const rel of await walkVault(vaultDir, vaultDir, exclude)) {
+      const unloadable = unloadablePathDiagnostic(rel, join(vaultDir, rel));
+      if (unloadable) {
+        skipped.push(unloadable);
+      } else {
+        files.push(rel);
+      }
+    }
     const read = await Promise.all(
       files.map((rel) => readNote(vaultDir, rel, options))
     );
@@ -959,7 +985,10 @@ export const obsidianSource = (
       noteToEntry(pair, index, options, unresolved)
     );
     return {
-      diagnostics: unresolvedDiagnostics(options.name, unresolved),
+      diagnostics: [
+        ...skipped,
+        ...unresolvedDiagnostics(options.name, unresolved),
+      ],
       entries,
     };
   };
@@ -1030,6 +1059,8 @@ export const obsidianSource = (
     contentRoot: vaultDir,
     load,
     name: options.name,
+    // Notes are named like files: `01 Intro` sorts first and routes `/intro`.
+    orderedNames: true,
     prefix: options.prefix,
     read,
     staged: true,

package/src/core/sources/payload.ts

@@ -129,6 +129,7 @@ export const payloadSource = (
       name: options.name,
       pollInterval: options.pollInterval,
       prefix: options.prefix,
+      withContext: (next) => payloadSource(options, next),
     },
     ctx
   );

package/src/core/sources/portable-text.ts

@@ -4,7 +4,15 @@
  * user-supplied serializer or are skipped with a noted comment. Output is
  * Markdown text that flows through Blume's normal pipeline.
  */
-import { escapeMarkdownText, image, unsupported, writesMdx } from "./lower.ts";
+import type { InlineRun } from "./lower.ts";
+import {
+  guardBlockStart,
+  image,
+  linkParts,
+  renderInline,
+  unsupported,
+  writesMdx,
+} from "./lower.ts";
 
 /**
  * A field value on a Portable Text node: the arbitrary JSON the CMS query
@@ -66,64 +74,91 @@ const HEADING_STYLES = new Map([
   ["h6", "###### "],
 ]);
 
-/** Wrap a span's text in Markdown for its marks (decorators + link defs). */
-const renderSpan = (
-  span: PortableTextSpan,
-  defs: Map<string, PortableTextMarkDef>
-): string => {
-  // Code spans stay verbatim: their text is literal inside the backticks,
-  // and backslash escapes would render as backslashes.
-  const isCode = span.marks?.includes("code") ?? false;
-  let text = isCode ? (span.text ?? "") : escapeMarkdownText(span.text ?? "");
-  if (!span.marks || span.marks.length === 0) {
-    return text;
-  }
-  // Decorators wrap inline; a link def wraps last so its label keeps emphasis.
-  let link: PortableTextMarkDef | undefined;
-  for (const mark of span.marks) {
-    switch (mark) {
-      case "strong": {
-        text = `**${text}**`;
-        break;
-      }
-      case "em": {
-        text = `*${text}*`;
-        break;
-      }
-      case "code": {
-        text = `\`${text}\``;
-        break;
-      }
-      case "strike-through": {
-        text = `~~${text}~~`;
-        break;
-      }
-      default: {
-        const def = defs.get(mark);
-        if (def?._type === "link") {
-          link = def;
-        }
-      }
-    }
-  }
-  return link?.href ? `[${text}](${link.href})` : text;
+/** A span's text and the marks Markdown has syntax for. */
+const spanRun = (span: PortableTextSpan): InlineRun => {
+  const marks = span.marks ?? [];
+  return {
+    marks: {
+      bold: marks.includes("strong"),
+      code: marks.includes("code"),
+      italic: marks.includes("em"),
+      strike: marks.includes("strike-through"),
+    },
+    text: span.text ?? "",
+  };
 };
 
-/** Render the inline children of a block to a single Markdown string. */
+/** Neighboring spans under one link def (or none), and that def. */
+interface LinkedSpans {
+  link?: PortableTextMarkDef;
+  runs: InlineRun[];
+}
+
+/**
+ * Render the inline children of a block to a single Markdown string, through
+ * the shared lowering every CMS uses: prose is escaped, a code span outruns
+ * the backticks inside it, edge whitespace stays outside emphasis, neighbors
+ * share their marks' delimiters, and neighbors under one link def share one
+ * link — wrapped last (so its label keeps emphasis), and only when its
+ * destination is safe to click.
+ */
 const renderChildren = (block: PortableTextBlock): string => {
   const defs = new Map(
     (block.markDefs ?? []).map((def) => [def._key, def] as const)
   );
-  return (block.children ?? []).map((span) => renderSpan(span, defs)).join("");
+  const linked: LinkedSpans[] = [];
+  for (const span of block.children ?? []) {
+    const link = (span.marks ?? [])
+      .map((mark) => defs.get(mark))
+      .findLast((def) => def?._type === "link");
+    const last = linked.at(-1);
+    if (last && last.link === link) {
+      last.runs.push(spanRun(span));
+    } else {
+      linked.push({ link, runs: [spanRun(span)] });
+    }
+  }
+  return guardBlockStart(
+    renderInline(
+      linked.flatMap(({ link, runs }) => linkParts(runs, link?.href))
+    )
+  );
 };
 
 /** Whether an image block's `alt` field is usable alt text (CMS JSON may hold anything). */
 const isAltText = (value: PortableTextValue): value is string =>
   typeof value === "string";
 
+/** The marker a list block opens with. */
+const listMarker = (block: PortableTextBlock): string =>
+  block.listItem === "number" ? "1." : "-";
+
+/**
+ * How far each block is indented. Portable Text lists are flat blocks with a
+ * `level`, while Markdown nests an item by indenting it to its parent item's
+ * content column: two past a `-` item's indent, three past a `1.` item's. The
+ * column comes from the item actually above, so a skipped level nests under
+ * the deepest open item instead of indenting into a code block.
+ */
+const listIndents = (blocks: PortableTextBlock[]): number[] => {
+  const columns: number[] = [];
+  return blocks.map((block) => {
+    if (!block.listItem) {
+      columns.length = 0;
+      return 0;
+    }
+    const depth = Math.min(Math.max(0, (block.level ?? 1) - 1), columns.length);
+    const indent = columns[depth - 1] ?? 0;
+    columns.length = depth;
+    columns.push(indent + listMarker(block).length + 1);
+    return indent;
+  });
+};
+
 const renderBlock = (
   block: PortableTextBlock,
-  options: PortableTextOptions
+  options: PortableTextOptions,
+  indent: number
 ): string => {
   const custom = options.serializers?.[block._type];
   if (custom) {
@@ -143,9 +178,7 @@ const renderBlock = (
 
   const inline = renderChildren(block);
   if (block.listItem) {
-    const indent = "  ".repeat(Math.max(0, (block.level ?? 1) - 1));
-    const marker = block.listItem === "number" ? "1." : "-";
-    return `${indent}${marker} ${inline}`;
+    return `${" ".repeat(indent)}${listMarker(block)} ${inline}`;
   }
   if (block.style === "blockquote") {
     return `> ${inline}`;
@@ -158,7 +191,10 @@ export const portableTextToMarkdown = (
   blocks: PortableTextBlock[],
   options: PortableTextOptions = {}
 ): string => {
-  const lines = blocks.map((block) => renderBlock(block, options));
+  const indents = listIndents(blocks);
+  const lines = blocks.map((block, i) =>
+    renderBlock(block, options, indents[i] ?? 0)
+  );
   // List items are single-newline separated; everything else gets a blank line.
   const out: string[] = [];
   for (let i = 0; i < lines.length; i += 1) {

package/src/core/sources/remote.ts

@@ -1,6 +1,7 @@
 import { join } from "pathe";
 
 import matter from "../frontmatter.ts";
+import { neutralizeUnsafeLinks } from "../safe-links.ts";
 import {
   hashText,
   loadWithCache,
@@ -19,12 +20,21 @@ import type {
 
 /** What every REST-backed CMS source needs to be a staged, cached source. */
 export interface RemoteSourceOptions {
+  /**
+   * Throw a `BlumeError` when the source cannot load as configured. Runs
+   * before the cache is consulted: thrown from `fetchEntries` instead, a
+   * misconfiguration would be served over by a stale snapshot with only an
+   * offline warning.
+   */
+  assertConfigured?: () => void;
   /** Pull every entry from the API; called on refresh and on each poll. */
   fetchEntries: () => Promise<SourceEntry[]>;
   name: string;
   /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
   pollInterval?: number;
   prefix?: string;
+  /** The adapter rebuilt on another context (`ContentSource.withContext`). */
+  withContext?: (ctx: SourceContext) => ContentSource;
 }
 
 /**
@@ -45,6 +55,7 @@ export const remoteSource = (
   const load = async (
     refresh = ctx?.refresh ?? true
   ): Promise<SourceLoadResult> => {
+    options.assertConfigured?.();
     const result = await loadWithCache(
       options.name,
       cache,
@@ -77,6 +88,7 @@ export const remoteSource = (
           () => load()
         )
       : undefined,
+    withContext: options.withContext,
   };
 };
 
@@ -182,7 +194,8 @@ export interface RemoteFieldMap {
  * when the slug field is missing or slugifies to nothing (pure punctuation),
  * so distinct documents never collapse onto one `untitled.md`; a slashed
  * slug keeps its segments. A string body is Markdown and passes through as
- * `.md`; any other shape goes to the CMS's lowerer, and is written as `.mdx`
+ * `.md`, its unsafe links reduced to their labels; any other shape goes to
+ * the CMS's lowerer, and is written as `.mdx`
  * when `lowersToMdx` (the source has serializers, see `writesMdx`).
  */
 export const documentEntry = (
@@ -211,7 +224,10 @@ export const documentEntry = (
   let markdown = "";
   let format: "md" | "mdx" = "md";
   if (isStringValue(body)) {
-    markdown = `${body.trimEnd()}\n`;
+    // The CMS's Markdown is its editors', not the site author's: a link whose
+    // destination isn't a web, mail, or relative address (`javascript:`)
+    // keeps only its label, as release notes do (see `safe-links.ts`).
+    markdown = neutralizeUnsafeLinks(`${body.trimEnd()}\n`);
   } else if (body !== undefined) {
     markdown = lower(body);
     format = lowersToMdx ? "mdx" : "md";