blume 0.6.7 → 0.8.0

package/src/core/sources/assets.ts

@@ -68,7 +68,12 @@ export const materializeAssets = async (
           throw new Error(`${res.status}`);
         }
         const bytes = new Uint8Array(await res.arrayBuffer());
-        const file = `${hashText(url)}${extFor(url)}`;
+        // Hash the query-less URL (as `extFor` does): CMS asset URLs are
+        // pre-signed, so the query changes on every fetch of the same image —
+        // hashing it would mint a new file each refresh and re-dirty the
+        // content digest. Two real assets sharing scheme+host+path and
+        // differing only in query are rare enough to accept colliding.
+        const file = `${hashText(url.split("?")[0] ?? url)}${extFor(url)}`;
         await mkdir(ctx.assetsDir, { recursive: true });
         await writeFile(join(ctx.assetsDir, file), bytes);
         rewrites.set(url, `${ctx.assetsBaseUrl}/${file}`);

package/src/core/sources/filesystem.ts

@@ -63,6 +63,10 @@ export const filesystemSource = (
         return {
           body: { format, text: parsed.content },
           data: parsed.data,
+          // The unstripped text: lets `normalizeEntry` offset link line numbers
+          // by the frontmatter block's height, so diagnostics point at the real
+          // file line (and spares a re-read on the frontmatter-error path).
+          raw: source,
           ref: relative(contentRoot, file),
           sourcePath: file,
         };

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

@@ -88,7 +88,8 @@ const releaseToEntry = (release: GithubRelease): SourceEntry => {
     type: "changelog",
   };
   const raw = matter.stringify(`${body}\n`, data);
-  const ref = `${slugifyTag(release.tag_name) || `release-${release.id}`}.md`;
+  const fallbackRef = `release-${release.id}`;
+  const ref = `${slugifyTag(release.tag_name) || fallbackRef}.md`;
   return {
     body: { format: "md", text: body },
     data,

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

@@ -37,49 +37,48 @@ const REGEX_SPECIAL = /[.*+?^${}()|[\]\\]/u;
 const escapeChar = (char: string): string =>
   REGEX_SPECIAL.test(char) ? `\\${char}` : char;
 
+/** Translate one glob token at `i` into RegExp source + the next index. */
+const globToken = (
+  pattern: string,
+  i: number
+): { source: string; next: number } => {
+  const char = pattern[i] ?? "";
+  if (char === "*") {
+    if (pattern[i + 1] === "*") {
+      // `**/` spans zero or more whole segments — `docs/**/guide.md` must
+      // match `docs/guide.md` and `docs/a/guide.md` but not `docs/subguide.md`.
+      if (pattern[i + 2] === "/") {
+        return { next: i + 3, source: "(?:.*/)?" };
+      }
+      return { next: i + 2, source: ".*" };
+    }
+    return { next: i + 1, source: "[^/]*" };
+  }
+  if (char === "?") {
+    return { next: i + 1, source: "[^/]" };
+  }
+  if (char === "{") {
+    const end = pattern.indexOf("}", i);
+    if (end !== -1) {
+      const options = pattern
+        .slice(i + 1, end)
+        .split(",")
+        .map((part) => [...part].map(escapeChar).join(""))
+        .join("|");
+      return { next: end + 1, source: `(?:${options})` };
+    }
+  }
+  return { next: i + 1, source: escapeChar(char) };
+};
+
 /** Compile a glob (`**`, `*`, `?`, `{a,b}`) into an anchored RegExp. */
 const globToRegExp = (pattern: string): RegExp => {
   let source = "";
   let i = 0;
   while (i < pattern.length) {
-    const char = pattern[i] ?? "";
-    if (char === "*") {
-      if (pattern[i + 1] === "*") {
-        i += 2;
-        // `**/` spans zero or more whole segments — `docs/**/guide.md` must
-        // match `docs/guide.md` and `docs/a/guide.md` but not `docs/subguide.md`.
-        if (pattern[i] === "/") {
-          i += 1;
-          source += "(?:.*/)?";
-        } else {
-          source += ".*";
-        }
-        continue;
-      }
-      source += "[^/]*";
-      i += 1;
-      continue;
-    }
-    if (char === "?") {
-      source += "[^/]";
-      i += 1;
-      continue;
-    }
-    if (char === "{") {
-      const end = pattern.indexOf("}", i);
-      if (end !== -1) {
-        const options = pattern
-          .slice(i + 1, end)
-          .split(",")
-          .map((part) => [...part].map(escapeChar).join(""))
-          .join("|");
-        source += `(?:${options})`;
-        i = end + 1;
-        continue;
-      }
-    }
-    source += escapeChar(char);
-    i += 1;
+    const token = globToken(pattern, i);
+    source += token.source;
+    i = token.next;
   }
   return new RegExp(`^${source}$`, "u");
 };
@@ -137,15 +136,22 @@ const enumerateGithub = async (
     truncated?: boolean;
   };
   const prefix = base ? `${base}/` : "";
-  const refs = (body.tree ?? [])
-    .filter((node) => node.type === "blob" && node.path.startsWith(prefix))
-    .map((node) => node.path.slice(prefix.length))
-    .filter((rel) => matchesInclude(rel, include))
-    .map((rel) => ({
-      editUrl: `https://github.com/${owner}/${repo}/edit/${ref}/${prefix}${rel}`,
-      fetchUrl: `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${prefix}${rel}`,
-      ref: rel,
-    }));
+  const refs = (body.tree ?? []).flatMap((node) => {
+    if (!(node.type === "blob" && node.path.startsWith(prefix))) {
+      return [];
+    }
+    const rel = node.path.slice(prefix.length);
+    if (!matchesInclude(rel, include)) {
+      return [];
+    }
+    return [
+      {
+        editUrl: `https://github.com/${owner}/${repo}/edit/${ref}/${prefix}${rel}`,
+        fetchUrl: `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${prefix}${rel}`,
+        ref: rel,
+      },
+    ];
+  });
   // GitHub caps the recursive tree response (~100k entries / 7MB) and flags it
   // with `truncated`; ignoring it would silently import only part of the repo.
   return { refs, truncated: body.truncated === true };
@@ -164,6 +170,21 @@ export const mdxRemoteSource = (
   const cache = snapshotCache(ctx.cacheDir);
   let snapshot = new Map<string, SourceEntry>();
 
+  // Validated up front in `load`, *before* the cached-fetch path: thrown from
+  // inside `loadWithCache`'s fetch callback, a misconfiguration would be masked
+  // as BLUME_SOURCE_FETCH_FAILED (no cache) or downgraded to a stale-cache
+  // BLUME_SOURCE_OFFLINE warning (cache present).
+  const assertConfigured = (): void => {
+    if (options.github || (options.files && options.url)) {
+      return;
+    }
+    throw new BlumeError({
+      code: "BLUME_SOURCE_MISCONFIGURED",
+      message: `Source "${options.name}" needs either { github } or { url, files }.`,
+      severity: "error",
+    });
+  };
+
   const enumerate = async (): Promise<{
     refs: RemoteRef[];
     truncated: boolean;
@@ -171,22 +192,13 @@ export const mdxRemoteSource = (
     if (options.github) {
       return await enumerateGithub(options.github, options.include, doFetch);
     }
-    if (options.files && options.url) {
-      const base = options.url.replace(/\/$/u, "");
-      const refs = options.files
-        .filter((ref) => matchesInclude(ref, options.include))
-        .map((ref) => ({
-          editUrl: `${base}/${ref}`,
-          fetchUrl: `${base}/${ref}`,
-          ref,
-        }));
-      return { refs, truncated: false };
-    }
-    throw new BlumeError({
-      code: "BLUME_SOURCE_MISCONFIGURED",
-      message: `Source "${options.name}" needs either { github } or { url, files }.`,
-      severity: "error",
-    });
+    const base = (options.url ?? "").replace(/\/$/u, "");
+    const refs = (options.files ?? []).flatMap((ref) =>
+      matchesInclude(ref, options.include)
+        ? [{ editUrl: `${base}/${ref}`, fetchUrl: `${base}/${ref}`, ref }]
+        : []
+    );
+    return { refs, truncated: false };
   };
 
   const fetchEntry = async (item: RemoteRef): Promise<SourceEntry> => {
@@ -212,6 +224,7 @@ export const mdxRemoteSource = (
   const load = async (
     refresh = ctx.refresh ?? true
   ): Promise<SourceLoadResult> => {
+    assertConfigured();
     const skipped: Diagnostic[] = [];
     const result = await loadWithCache(
       options.name,

package/src/core/sources/normalize.ts

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import GithubSlugger from "github-slugger";
 import { extname } from "pathe";
 
+import { withBasePath } from "../base-path.ts";
 import { diagnosticsFromZod } from "../diagnostics.ts";
 import { localePlacement, localizeRoute } from "../i18n.ts";
 import { pageMetaSchema } from "../schema.ts";
@@ -45,6 +46,29 @@ const titleCase = (value: string): string =>
     .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
     .join(" ");
 
+/** Fold one raw path part into the accumulating route segments/groups. */
+const addRouteSegment = (
+  part: string,
+  segments: string[],
+  groups: string[]
+): void => {
+  // A leading/trailing/double slash yields an empty part; keeping it would
+  // produce a malformed route (`//foo`, `/foo/`) that nothing can link to.
+  if (part === "") {
+    return;
+  }
+  const group = groupLabel(part);
+  if (group !== null) {
+    groups.push(group);
+    return;
+  }
+  const clean = stripNumericPrefix(part);
+  if (clean === "index") {
+    return;
+  }
+  segments.push(clean);
+};
+
 /** Convert a content-root-relative path into URL + nav metadata. */
 const mapRoute = (
   relativePath: string
@@ -59,61 +83,147 @@ const mapRoute = (
   const groups: string[] = [];
 
   for (const part of rawParts) {
-    // A leading/trailing/double slash yields an empty part; keeping it would
-    // produce a malformed route (`//foo`, `/foo/`) that nothing can link to.
-    if (part === "") {
-      continue;
-    }
-    const group = groupLabel(part);
-    if (group !== null) {
-      groups.push(group);
-      continue;
-    }
-    const clean = stripNumericPrefix(part);
-    if (clean === "index") {
-      continue;
-    }
-    segments.push(clean);
+    addRouteSegment(part, segments, groups);
   }
 
   const route = segments.length === 0 ? "/" : `/${segments.join("/")}`;
   return { groups, route, segments };
 };
 
-const CODE_FENCE = /^```/u;
+// CommonMark allows backtick *and* tilde fences. The scanners track which
+// delimiter opened the current fence (`null` when outside one) so a ``` line
+// inside a ~~~ block is content, not a toggle — see `nextFenceState`.
+const CODE_FENCE = /^(?<delimiter>```|~~~)/u;
+
+/** The fence delimiter opening the current code block, or null outside one. */
+type FenceState = "```" | "~~~" | null;
+
+/**
+ * Advance the fenced-code state for one line: an opening fence records its
+ * delimiter, only the matching delimiter closes it, and any other line leaves
+ * the state untouched.
+ */
+const nextFenceState = (line: string, fence: FenceState): FenceState => {
+  const delimiter = line.trimStart().match(CODE_FENCE)?.groups?.delimiter as
+    | Exclude<FenceState, null>
+    | undefined;
+  if (delimiter === undefined) {
+    return fence;
+  }
+  if (fence === null) {
+    return delimiter;
+  }
+  return fence === delimiter ? null : fence;
+};
 // A closing hash sequence must be preceded by whitespace (CommonMark), so a
-// heading like `## What is C#` keeps its trailing `#`.
-const ATX_HEADING = /^(?<hashes>#{1,6})\s+(?<text>.+?)(?:\s+#+)?\s*$/u;
+// heading like `## What is C#` keeps its trailing `#`. Up to 3 leading spaces
+// are allowed; 4+ is an indented code block.
+const ATX_HEADING = /^ {0,3}(?<hashes>#{1,6})\s+(?<text>.+?)(?:\s+#+)?\s*$/u;
+// A setext underline: a run of `=` (level 1) or `-` (level 2) alone on a line,
+// up to 3 leading spaces. It only forms a heading directly under paragraph
+// text — see `scanHeadingLine`.
+const SETEXT_UNDERLINE = /^ {0,3}(?<marker>=+|-+)\s*$/u;
+// Lines that end a paragraph without being one (CommonMark): blank lines are
+// checked separately; these cover list items, blockquotes, and thematic
+// breaks, so a `---` after any of them stays a thematic break, not an
+// underline promoting the list/quote text to a heading.
+const PARAGRAPH_INTERRUPT = /^ {0,3}(?:[-+*][ \t]|\d{1,9}[.)][ \t]|>)/u;
+const THEMATIC_BREAK =
+  /^ {0,3}(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})$/u;
+const FRONT_MATTER_CLOSE = /^(?:-{3}|\.{3})\s*$/u;
 
 /**
- * Extract ATX headings from a markdown body, skipping fenced code blocks. Each
- * heading's anchor slug comes from a per-document `github-slugger` — the exact
- * slugger the renderer uses (`markdown/heading-anchors`) — advanced over every
- * `#`–`######` in document order. Matching it (rather than a hand-rolled
- * slugify) keeps the manifest's anchor ids identical to the rendered ones, so
- * `blume validate` stops false-flagging links like `#the-read--write-fallback`
- * (a hand slugify collapses `--`; github-slugger keeps it) and resolves repeated
- * headings the same way (`setup`, `setup-1`).
+ * The body lines, minus a leading front matter block. Bodies from the
+ * normalize pipeline are already frontmatter-stripped, but `extractHeadings`
+ * also runs on raw documents — where a leading `---` block (closed by `---` or
+ * `...`) is front matter, not a thematic break whose closing `---` would
+ * underline the last metadata line into a phantom setext heading.
  */
+const linesWithoutFrontMatter = (body: string): string[] => {
+  const lines = body.split("\n");
+  if (!/^-{3}\s*$/u.test(lines[0] ?? "")) {
+    return lines;
+  }
+  const close = lines.findIndex(
+    (line, index) => index > 0 && FRONT_MATTER_CLOSE.test(line)
+  );
+  return close === -1 ? lines : lines.slice(close + 1);
+};
+
+/** Scanner state: the open fence plus the paragraph lines accumulated so far. */
+interface HeadingScanState {
+  fence: FenceState;
+  /** Consecutive paragraph lines — the candidate text for a setext underline. */
+  paragraph: string[];
+}
+
+/**
+ * Extract ATX and setext headings from a markdown body, skipping fenced code
+ * blocks, exactly as the renderer sees them: ATX headings may be indented up
+ * to 3 spaces, and a paragraph underlined with `=`/`-` is a level 1/2 setext
+ * heading. Each heading's anchor slug comes from a per-document
+ * `github-slugger` — the exact slugger the renderer uses
+ * (`markdown/heading-anchors`) — advanced over every heading in document
+ * order. Matching it (rather than a hand-rolled slugify) keeps the manifest's
+ * anchor ids identical to the rendered ones, so `blume validate` stops
+ * false-flagging links like `#the-read--write-fallback` (a hand slugify
+ * collapses `--`; github-slugger keeps it) and resolves repeated headings the
+ * same way (`setup`, `setup-1`).
+ */
+/** Scan one line for a heading, advancing the fence/paragraph state. */
+const scanHeadingLine = (
+  line: string,
+  state: HeadingScanState,
+  slugger: GithubSlugger,
+  headings: Heading[]
+): void => {
+  const next = nextFenceState(line, state.fence);
+  // Skip fence delimiter lines themselves and anything inside a fence. A fence
+  // also ends any open paragraph, so no underline can reach across it.
+  if (state.fence !== null || next !== null) {
+    state.fence = next;
+    state.paragraph = [];
+    return;
+  }
+  const atx = line.match(ATX_HEADING);
+  if (atx?.groups) {
+    const depth = atx.groups.hashes?.length ?? 1;
+    const text = (atx.groups.text ?? "").trim();
+    headings.push({ depth, slug: slugger.slug(text), text });
+    state.paragraph = [];
+    return;
+  }
+  const setext = line.match(SETEXT_UNDERLINE);
+  if (setext?.groups && state.paragraph.length > 0) {
+    // Setext wins over thematic break when it closes a paragraph (CommonMark);
+    // a multi-line paragraph renders as one heading, soft breaks as spaces.
+    const text = state.paragraph.join(" ").trim();
+    headings.push({
+      depth: setext.groups.marker?.startsWith("=") ? 1 : 2,
+      slug: slugger.slug(text),
+      text,
+    });
+    state.paragraph = [];
+    return;
+  }
+  if (
+    line.trim() === "" ||
+    THEMATIC_BREAK.test(line) ||
+    PARAGRAPH_INTERRUPT.test(line)
+  ) {
+    state.paragraph = [];
+    return;
+  }
+  state.paragraph.push(line.trim());
+};
+
 export const extractHeadings = (body: string): Heading[] => {
   const headings: Heading[] = [];
   const slugger = new GithubSlugger();
-  let inFence = false;
+  const state: HeadingScanState = { fence: null, paragraph: [] };
 
-  for (const line of body.split("\n")) {
-    if (CODE_FENCE.test(line.trimStart())) {
-      inFence = !inFence;
-      continue;
-    }
-    if (inFence) {
-      continue;
-    }
-    const match = line.match(ATX_HEADING);
-    if (match?.groups) {
-      const depth = match.groups.hashes?.length ?? 1;
-      const text = (match.groups.text ?? "").trim();
-      headings.push({ depth, slug: slugger.slug(text), text });
-    }
+  for (const line of linesWithoutFrontMatter(body)) {
+    scanHeadingLine(line, state, slugger, headings);
   }
 
   return headings;
@@ -125,42 +235,53 @@ const INLINE_CODE = /`[^`]*`/gu;
 /**
  * Extract link targets from a markdown body for later validation, recording the
  * 1-based line/column of each target. Skips fenced code blocks and inline code.
+ * `lineOffset` shifts every recorded line: the body is frontmatter-stripped, so
+ * diagnostics that point into the raw file must add the stripped block's height.
  */
-export const extractLinks = (body: string): PageLink[] => {
+/** Scan one line for link targets; returns the next fenced-block state. */
+const scanLinkLine = (
+  line: string,
+  lineNumber: number,
+  fence: FenceState,
+  links: PageLink[]
+): FenceState => {
+  const next = nextFenceState(line, fence);
+  // Skip fence delimiter lines themselves and anything inside a fence.
+  if (fence !== null || next !== null) {
+    return next;
+  }
+  // Blank out inline code spans (`[label](/x)` shown as syntax, not a link)
+  // with same-length padding so recorded columns stay accurate.
+  const masked = line.replaceAll(INLINE_CODE, (span) =>
+    " ".repeat(span.length)
+  );
+  for (const match of masked.matchAll(MD_LINK)) {
+    const target = match.groups?.target;
+    if (target === undefined || match.index === undefined) {
+      continue;
+    }
+    // Locate the target from the `](` boundary rather than searching for the
+    // target text from the match start — otherwise a label that contains the
+    // same text (e.g. `[/a/b](/a/b)`) reports the column inside the label. The
+    // label can't contain `]`, so `](` is unambiguous.
+    const targetOffset = match.index + match[0].indexOf("](") + "](".length;
+    links.push({
+      column: targetOffset + 1,
+      line: lineNumber,
+      target,
+    });
+  }
+  return next;
+};
+
+export const extractLinks = (body: string, lineOffset = 0): PageLink[] => {
   const links: PageLink[] = [];
-  let inFence = false;
-  let lineNumber = 0;
+  let fence: FenceState = null;
+  let lineNumber = lineOffset;
 
   for (const line of body.split("\n")) {
     lineNumber += 1;
-    if (CODE_FENCE.test(line.trimStart())) {
-      inFence = !inFence;
-      continue;
-    }
-    if (inFence) {
-      continue;
-    }
-    // Blank out inline code spans (`[label](/x)` shown as syntax, not a link)
-    // with same-length padding so recorded columns stay accurate.
-    const masked = line.replaceAll(INLINE_CODE, (span) =>
-      " ".repeat(span.length)
-    );
-    for (const match of masked.matchAll(MD_LINK)) {
-      const target = match.groups?.target;
-      if (target === undefined || match.index === undefined) {
-        continue;
-      }
-      // Locate the target from the `](` boundary rather than searching for the
-      // target text from the match start — otherwise a label that contains the
-      // same text (e.g. `[/a/b](/a/b)`) reports the column inside the label. The
-      // label can't contain `]`, so `](` is unambiguous.
-      const targetOffset = match.index + match[0].indexOf("](") + "](".length;
-      links.push({
-        column: targetOffset + 1,
-        line: lineNumber,
-        target,
-      });
-    }
+    fence = scanLinkLine(line, lineNumber, fence, links);
   }
 
   return links;
@@ -179,30 +300,45 @@ const JSX_OPEN = /<(?<tag>[A-Z][A-Za-z0-9]*)/gu;
  * strings so code samples and prose don't count. Powers the missing-component
  * diagnostic.
  */
+/** Scan one line for JSX component tags; returns the next fenced-block state. */
+const scanTagLine = (
+  line: string,
+  fence: FenceState,
+  tags: Set<string>
+): FenceState => {
+  const next = nextFenceState(line, fence);
+  // Skip fence delimiter lines themselves and anything inside a fence.
+  if (fence !== null || next !== null) {
+    return next;
+  }
+  const clean = line.replaceAll(INLINE_CODE, "").replaceAll(DOUBLE_QUOTED, "");
+  for (const match of clean.matchAll(JSX_OPEN)) {
+    const tag = match.groups?.tag;
+    if (tag) {
+      tags.add(tag);
+    }
+  }
+  return next;
+};
+
 export const extractComponentTags = (body: string): string[] => {
   const tags = new Set<string>();
-  let inFence = false;
+  let fence: FenceState = null;
   for (const line of body.split("\n")) {
-    if (CODE_FENCE.test(line.trimStart())) {
-      inFence = !inFence;
-      continue;
-    }
-    if (inFence) {
-      continue;
-    }
-    const clean = line
-      .replaceAll(INLINE_CODE, "")
-      .replaceAll(DOUBLE_QUOTED, "");
-    for (const match of clean.matchAll(JSX_OPEN)) {
-      const tag = match.groups?.tag;
-      if (tag) {
-        tags.add(tag);
-      }
-    }
+    fence = scanTagLine(line, fence, tags);
   }
   return [...tags];
 };
 
+/**
+ * Height of the frontmatter block stripped from `raw` to produce `body` (0
+ * when the raw text is unknown or nothing was stripped). Link positions are
+ * extracted from the stripped body, but diagnostics point into the raw
+ * document — recorded lines must shift by this offset to match it.
+ */
+const strippedLineOffset = (raw: string | undefined, body: string): number =>
+  raw ? Math.max(0, raw.split("\n").length - body.split("\n").length) : 0;
+
 const deriveTitle = (
   meta: PageMeta,
   headings: Heading[],
@@ -311,7 +447,10 @@ export const normalizeEntry = (
     headings,
     id: `${ctx.source.name}:${entry.ref}`,
     lastModified: meta.lastModified ?? entry.lastModified,
-    links: extractLinks(entry.body.text),
+    links: extractLinks(
+      entry.body.text,
+      strippedLineOffset(entry.raw, entry.body.text)
+    ),
     meta,
     navPath,
     segments,
@@ -323,10 +462,16 @@ export const normalizeEntry = (
 
   // One record per locale this entry maps to (one normally; every locale for a
   // shared `$` file). All share the same id, source ref, and translation key.
+  // `basePath` is applied outermost — after locale prefixing — so the route
+  // reads `{basePath}/{locale?}/{prefix?}/…`; `navPath` and `translationKey`
+  // stay base-less so the nav tree and translation matching are unaffected.
   const pages = locales.map((locale) => ({
     ...base,
     locale,
-    route: i18n ? localizeRoute(logicalRoute, locale, i18n) : logicalRoute,
+    route: withBasePath(
+      ctx.basePath ?? "",
+      i18n ? localizeRoute(logicalRoute, locale, i18n) : logicalRoute
+    ),
   }));
 
   return { diagnostics: [], pages };