blume 0.6.1 → 0.6.2

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

@@ -145,7 +145,9 @@ export const githubReleasesSource = (
     return collected.slice(0, max);
   };
 
-  const load = async (): Promise<SourceLoadResult> => {
+  const load = async (
+    refresh = ctx.refresh ?? true
+  ): Promise<SourceLoadResult> => {
     try {
       const result = await loadWithCache(
         options.name,
@@ -154,7 +156,7 @@ export const githubReleasesSource = (
           const releases = await fetchReleases();
           return releases.map(releaseToEntry);
         },
-        ctx.refresh ?? true
+        refresh
       );
       snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
       return result;
@@ -194,7 +196,11 @@ export const githubReleasesSource = (
     read,
     staged: true,
     watch: options.pollInterval
-      ? pollingWatch(load, options.pollInterval)
+      ? pollingWatch(
+          () => load(true),
+          options.pollInterval,
+          () => load()
+        )
       : undefined,
   };
 };

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

@@ -45,10 +45,14 @@ const globToRegExp = (pattern: string): RegExp => {
     const char = pattern[i] ?? "";
     if (char === "*") {
       if (pattern[i + 1] === "*") {
-        source += ".*";
         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;
       }
@@ -205,7 +209,9 @@ export const mdxRemoteSource = (
     };
   };
 
-  const load = async (): Promise<SourceLoadResult> => {
+  const load = async (
+    refresh = ctx.refresh ?? true
+  ): Promise<SourceLoadResult> => {
     const skipped: Diagnostic[] = [];
     const result = await loadWithCache(
       options.name,
@@ -245,7 +251,7 @@ export const mdxRemoteSource = (
         }
         return entries;
       },
-      ctx.refresh ?? true
+      refresh
     );
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
     return {
@@ -271,7 +277,11 @@ export const mdxRemoteSource = (
     read,
     staged: true,
     watch: options.pollInterval
-      ? pollingWatch(load, options.pollInterval)
+      ? pollingWatch(
+          () => load(true),
+          options.pollInterval,
+          () => load()
+        )
       : undefined,
   };
 };

package/src/core/sources/normalize.ts

@@ -81,7 +81,9 @@ const mapRoute = (
 };
 
 const CODE_FENCE = /^```/u;
-const ATX_HEADING = /^(?<hashes>#{1,6})\s+(?<text>.+?)\s*#*$/u;
+// 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;
 
 /**
  * Extract ATX headings from a markdown body, skipping fenced code blocks. Each
@@ -260,6 +262,16 @@ export const normalizeEntry = (
 
   const meta = result.data;
 
+  // Top-level `hidden`/`noindex` are accepted as shorthands for their nested
+  // equivalents — the schema declares them, so silently ignoring them would
+  // strand authors with no diagnostic.
+  if (meta.hidden) {
+    meta.sidebar.hidden = true;
+  }
+  if (meta.noindex) {
+    meta.seo.noindex = true;
+  }
+
   // Locale and the locale-stripped nav path come from the entry's ref (a leading
   // dir, or a filename suffix under the `dot` parser), not the slug — the slug is
   // the logical, locale-agnostic path within a locale. A shared `$` file maps to

package/src/core/sources/notion.ts

@@ -335,10 +335,40 @@ export const notionSource = (
     blocks: NotionBlock[]
   ): Promise<string> => {
     const parts = await Promise.all(
-      blocks.map(
-        (block) =>
-          renderLeaf(block) ?? renderContainer(client, block, renderBlocks)
-      )
+      blocks.map(async (block) => {
+        const leaf = renderLeaf(block);
+        if (leaf === null) {
+          return renderContainer(client, block, renderBlocks);
+        }
+        // Leaf blocks can still carry children (nested list items, indented
+        // paragraphs); dropping them would silently lose content.
+        if (!block.has_children) {
+          return leaf;
+        }
+        const nested = await renderBlocks(
+          client,
+          await childrenOf(client, block.id)
+        );
+        if (!nested) {
+          return leaf;
+        }
+        if (isListItem(block)) {
+          // Indent past the list marker so the children belong to the item
+          // (`1. ` needs three columns, `- `/`- [x] ` two).
+          const indent = " ".repeat(
+            block.type === "numbered_list_item" ? 3 : 2
+          );
+          const indented = nested
+            .split("\n")
+            .map((line) => (line ? `${indent}${line}` : line))
+            .join("\n");
+          return `${leaf}\n${indented}`;
+        }
+        // Other leaves (paragraph, quote) keep their children as following
+        // sibling blocks — the indentation semantics are lost but the content
+        // survives.
+        return `${leaf}\n\n${nested}`;
+      })
     );
     // Join with a blank line, except between consecutive list items, which stay
     // tight so they render as a single list rather than separate loose ones.
@@ -430,7 +460,9 @@ export const notionSource = (
     };
   };
 
-  const load = async (): Promise<SourceLoadResult> => {
+  const load = async (
+    refresh = ctx?.refresh ?? true
+  ): Promise<SourceLoadResult> => {
     const assetDiagnostics: Diagnostic[] = [];
     const result = await loadWithCache(
       options.name,
@@ -453,7 +485,7 @@ export const notionSource = (
         }
         return built.map((item) => item.entry);
       },
-      ctx?.refresh ?? true
+      refresh
     );
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
     return {
@@ -478,7 +510,11 @@ export const notionSource = (
     read,
     staged: true,
     watch: options.pollInterval
-      ? pollingWatch(load, options.pollInterval)
+      ? pollingWatch(
+          () => load(true),
+          options.pollInterval,
+          () => load()
+        )
       : undefined,
   };
 };

package/src/core/sources/resolve.ts

@@ -1,4 +1,4 @@
-import { join } from "pathe";
+import { isAbsolute, join, resolve } from "pathe";
 
 import { blumeReferences } from "../../openapi/references.ts";
 import { openApiSource } from "../../openapi/source.ts";
@@ -125,6 +125,49 @@ const buildSource = (
   );
 };
 
+/** Resolve a source `root` against the project root (absolute passes through). */
+const resolveRoot = (projectRoot: string, root: string): string =>
+  isAbsolute(root) ? root : join(resolve(projectRoot), root);
+
+/**
+ * The generated `docs` glob collection: its base directory and the include /
+ * exclude globs applied under it. Astro's glob loader ids each entry by its path
+ * relative to `base`, and a filesystem source ids each entry relative to its own
+ * root — so the two only agree when the collection is rooted at that source. A
+ * project with exactly one filesystem source therefore roots the collection at
+ * *that* source (honoring a non-default `root`), rather than the global
+ * `content.root`. With no sources (the implicit source) or several, the base
+ * stays `content.root`; a second filesystem source rooted elsewhere can't share
+ * one base and is caught by the entry-id guard in `scanProject`.
+ */
+export interface DocsCollection {
+  base: string;
+  include: string[];
+  exclude: string[];
+}
+
+export const resolveDocsCollection = (
+  config: ResolvedConfig,
+  context: ProjectContext
+): DocsCollection => {
+  const filesystem = (config.content.sources ?? []).filter(
+    (def) => def.type === "filesystem"
+  );
+  const only = filesystem.length === 1 ? filesystem[0] : undefined;
+  if (only) {
+    return {
+      base: resolveRoot(context.root, only.root),
+      exclude: only.exclude,
+      include: only.include,
+    };
+  }
+  return {
+    base: context.contentRoot,
+    exclude: config.content.exclude,
+    include: config.content.include,
+  };
+};
+
 /** The base name to allocate for a source config (before deduplication). */
 const baseName = (def: ContentSourceConfig): string => {
   if (def.type === "custom") {

package/src/core/sources/sanity.ts

@@ -183,7 +183,9 @@ export const sanitySource = (
     };
   };
 
-  const load = async (): Promise<SourceLoadResult> => {
+  const load = async (
+    refresh = ctx?.refresh ?? true
+  ): Promise<SourceLoadResult> => {
     const result = await loadWithCache(
       options.name,
       cache,
@@ -194,7 +196,7 @@ export const sanitySource = (
         );
         return docs.map(toEntry);
       },
-      ctx?.refresh ?? true
+      refresh
     );
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
     return result;
@@ -216,7 +218,11 @@ export const sanitySource = (
     read,
     staged: true,
     watch: options.pollInterval
-      ? pollingWatch(load, options.pollInterval)
+      ? pollingWatch(
+          () => load(true),
+          options.pollInterval,
+          () => load()
+        )
       : undefined,
   };
 };

package/src/core/sources/types.ts

@@ -84,6 +84,12 @@ export interface ContentSource {
   readonly staged: boolean;
   /** Optional route prefix; the source's routes namespace under `/<prefix>/`. */
   readonly prefix?: string;
+  /**
+   * Resolved on-disk root, set by filesystem-backed sources only. Drives
+   * folder-meta discovery (scan under this root) and the docs-collection base;
+   * omitted by remote/CMS/staged sources that have no local tree.
+   */
+  readonly contentRoot?: string;
   /** Pull every entry. Called once per scan. */
   load: () => Promise<SourceLoadResult>;
   /** Validate the source is usable; throws a BlumeError when not. */

package/src/deploy/rss.ts

@@ -68,7 +68,9 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
       .map((page) => ({
         date: pageDate(page),
         description: page.description,
-        link: `${base}${page.route}`,
+        // Encode like the sitemap does: a route with spaces or non-ASCII
+        // must still yield a valid <link>/<guid> URL after XML decoding.
+        link: encodeURI(`${base}${page.route}`),
         title: page.title,
       }))
       .toSorted((a, b) => (b.date?.getTime() ?? 0) - (a.date?.getTime() ?? 0))

package/src/markdown/code-title.ts

@@ -26,9 +26,16 @@ export interface CodeTitleTransformer {
 }
 
 // The body excludes only the delimiting quote, so `title="foo's file.ts"`
-// (an apostrophe inside double quotes) still matches.
-const TITLE_ATTR = /title=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/u;
+// (an apostrophe inside double quotes) still matches. The left boundary stops
+// `subtitle="..."` (or any `*title=` attr) from reading as a title.
+const TITLE_ATTR = /(?:^|\s)title=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/u;
 const LINE_NUMBERS = /(?:^|\s)lineNumbers(?=\s|$)/u;
+// Any quoted `key="..."` attr — blanked before keyword/bare-token scans so a
+// quoted value can't leak tokens (`title="enable lineNumbers later"`).
+const QUOTED_ATTR = /[\w-]+=(?:"[^"]*"|'[^']*')/gu;
+
+const withoutQuotedAttrs = (raw: string): string =>
+  raw.replace(QUOTED_ATTR, " ");
 
 const parseTitle = (raw: string | undefined): string | undefined => {
   if (!raw) {
@@ -42,7 +49,7 @@ const parseTitle = (raw: string | undefined): string | undefined => {
   // The first bare token is the title (```ts blume.config.ts), skipping Shiki
   // line ranges (`{1,3-5}`), `key=value` attrs, and the reserved `lineNumbers`
   // and `twoslash` keywords.
-  return raw
+  return withoutQuotedAttrs(raw)
     .trim()
     .split(/\s+/u)
     .find(
@@ -56,7 +63,7 @@ const parseTitle = (raw: string | undefined): string | undefined => {
 };
 
 const hasLineNumbers = (raw: string | undefined): boolean =>
-  Boolean(raw && LINE_NUMBERS.test(raw));
+  Boolean(raw && LINE_NUMBERS.test(withoutQuotedAttrs(raw)));
 
 /** Build the transformer. Runs after Shiki's built-in `data-language` hook. */
 export const codeTitleTransformer = (): CodeTitleTransformer => ({

package/src/markdown/package-commands.ts

@@ -98,6 +98,19 @@ const parseIntent = (input: string): Intent => {
   if (!verb) {
     return { args: [], operation: "install" };
   }
+  // Yarn Classic spells global installs `yarn global <add|remove> …`; map it
+  // onto the flag-style intent so every manager renders its own global form
+  // instead of falling into the run-as-script branch.
+  if (first === "yarn" && verb === "global") {
+    const [globalVerb, ...globalArgs] = verbArgs;
+    const globalOp = globalVerb ? normalizeVerb(globalVerb) : null;
+    if (globalOp === "add" || globalOp === "remove") {
+      return {
+        args: [...normalizeFlags(globalArgs), "-g"],
+        operation: globalOp,
+      };
+    }
+  }
   const operation = normalizeVerb(verb);
   if (operation === null) {
     // Unknown subcommand (e.g. `npm test`); run it as a script.

package/src/og/card.ts

@@ -145,7 +145,9 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
   const accent = resolveAccent(options.accent ?? "blue");
   const brand = options.brand?.trim();
   const logo = options.logo?.trim();
-  const initial = brand ? brand.charAt(0).toUpperCase() : "";
+  // Slice by code point, not code unit — `charAt(0)` would split a leading
+  // surrogate pair (an emoji brand initial) into a lone half that renders blank.
+  const initial = brand ? ([...brand][0]?.toUpperCase() ?? "") : "";
   const description = options.description?.trim();
   const repo = options.repo?.trim();
   const site = options.site?.trim();

package/src/openapi/model.ts

@@ -144,7 +144,8 @@ export const extractOperations = (
         method,
         operationId: operation.operationId,
         path,
-        route: `${baseRoute}/${tagSlug}/${key}`,
+        // A root-mounted reference (`route: "/"`) must not emit `//tag/key`.
+        route: `${baseRoute === "/" ? "" : baseRoute}/${tagSlug}/${key}`,
         summary: operation.summary ?? "",
         tag,
         tagSlug,

package/src/openapi/parse.ts

@@ -26,6 +26,9 @@ const URL_SPEC = /^https?:\/\//u;
 const FETCH_TIMEOUT_MS = 15_000;
 const MAX_ATTEMPTS = 3;
 const BASE_BACKOFF_MS = 500;
+// Honor Retry-After only up to a sane ceiling: a server answering with
+// `Retry-After: 3600` must not stall a build for an hour per attempt.
+const MAX_RETRY_WAIT_MS = 10_000;
 const SECOND_MS = 1000;
 // Worth another try: request timeout, too-early, rate-limited, and the 5xx range.
 const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
@@ -138,7 +141,12 @@ const fetchSpecText = async (spec: string): Promise<string> => {
       throw last.error;
     }
     // oxlint-disable-next-line no-await-in-loop -- back off before retrying
-    await sleep(last.retryAfter ?? BASE_BACKOFF_MS * 2 ** attempt);
+    await sleep(
+      Math.min(
+        last.retryAfter ?? BASE_BACKOFF_MS * 2 ** attempt,
+        MAX_RETRY_WAIT_MS
+      )
+    );
   }
   throw last.error;
 };

package/src/openapi/references.ts

@@ -145,6 +145,7 @@ export const referenceTabs = (config: ResolvedConfig): NavTab[] =>
 /** Blume-rendered OpenAPI references, deduped by route (first wins). */
 export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
   const seen = new Set<string>();
+  const usedSlugs = new Set<string>();
   const result: ReferenceSource[] = [];
   for (const ref of resolveReferences(config)) {
     if (ref.kind !== "openapi" || ref.renderer !== "blume") {
@@ -154,7 +155,16 @@ export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
       continue;
     }
     seen.add(ref.route);
-    result.push(ref);
+    // Distinct routes can slugify identically (`/api/v1` and `/api-v1` both
+    // yield `api-v1`). The slug keys the `blume:openapi` data module, so a
+    // collision would let one spec silently overwrite the other while the
+    // loser's pages still point at the shared key — disambiguate.
+    let { slug } = ref;
+    for (let n = 2; usedSlugs.has(slug); n += 1) {
+      slug = `${ref.slug}-${n}`;
+    }
+    usedSlugs.add(slug);
+    result.push(slug === ref.slug ? ref : { ...ref, slug });
   }
   return result;
 };

package/src/openapi/render-mdx.ts

@@ -25,7 +25,13 @@ const ENTITIES: Record<string, string> = {
 // SDK…" is common spec prose). Entity-escape the keyword's first letter so the
 // construct can't match; it still renders as the literal word.
 const MDX_ESM_KEYWORD = /^(?<keyword>import|export)\b/gmu;
-const mdxSafe = (text: string): string =>
+// Backtick code — inline spans and fences alike — is already literal in MDX,
+// and entities are NOT decoded inside it, so escaping there would render the
+// entity text verbatim (`/pets/&#123;petId&#125;`). Matching any balanced
+// backtick run covers `code`, ``code``, and ```fences``` in one shot.
+const BACKTICK_CODE = /(?<bt>`+)[\s\S]*?\k<bt>/gu;
+
+const escapeProse = (text: string): string =>
   text
     .replace(MDX_UNSAFE, (char) => ENTITIES[char] ?? char)
     .replace(
@@ -33,6 +39,19 @@ const mdxSafe = (text: string): string =>
       (keyword) => `&#${keyword.codePointAt(0)};${keyword.slice(1)}`
     );
 
+/** Escape MDX-special syntax in prose while leaving backtick code verbatim. */
+const mdxSafe = (text: string): string => {
+  let out = "";
+  let cursor = 0;
+  for (const match of text.matchAll(BACKTICK_CODE)) {
+    const start = match.index ?? 0;
+    out += escapeProse(text.slice(cursor, start));
+    out += match[0];
+    cursor = start + match[0].length;
+  }
+  return out + escapeProse(text.slice(cursor));
+};
+
 /** Frontmatter + body for one operation or overview page. */
 export interface RenderedPage {
   data: Record<string, unknown>;
@@ -80,8 +99,16 @@ export const overviewMdx = (spec: ApiSpecData): RenderedPage => {
   // markdown pipeline gives them ids, permalink anchors, and table-of-contents
   // entries; only the operation-link list defers to a component.
   const operations = Object.values(spec.operations);
-  const sections = [...spec.tags];
-  const known = new Set(spec.tags.map((tag) => tag.slug));
+  // Dedupe by slug: two declared tags that slugify identically (`Store` and
+  // `store`) must render one section, not the same operation list twice.
+  const sections: typeof spec.tags = [];
+  const known = new Set<string>();
+  for (const tag of spec.tags) {
+    if (!known.has(tag.slug)) {
+      known.add(tag.slug);
+      sections.push(tag);
+    }
+  }
   for (const operation of operations) {
     if (!known.has(operation.tagSlug)) {
       known.add(operation.tagSlug);

package/src/openapi/source.ts

@@ -59,8 +59,10 @@ const specEntries = (
   );
   // Overview last so an operation sets the section's routePath before the index
   // page is inserted (the group's routePath is derived from its first child).
+  // A root-mounted reference refs `index.mdx`, not `/index.mdx`.
+  const base = routeToRef(spec.route);
   entries.push(
-    toEntry(overviewMdx(spec), `${routeToRef(spec.route)}/index.mdx`)
+    toEntry(overviewMdx(spec), base ? `${base}/index.mdx` : "index.mdx")
   );
   return entries;
 };

package/src/search/documents.ts

@@ -39,7 +39,10 @@ export interface SearchRecord {
 
 const CODE_FENCE = /```[\s\S]*?```/gu;
 const INLINE_CODE = /`(?<code>[^`]+)`/gu;
-const HTML_OR_JSX = /<[^>]+>/gu;
+// Tag-shaped only: a name (or closing slash/fragment) right after `<`, and no
+// newline inside. A bare `<` in prose ("costs < 5 credits") must not swallow
+// everything up to some later `>` — potentially whole paragraphs.
+const HTML_OR_JSX = /<\/?[a-zA-Z][^\n<>]*>|<\/?>/gu;
 const IMAGE = /!\[[^\]]*\]\([^)]*\)/gu;
 const LINK = /\[(?<text>[^\]]*)\]\([^)]*\)/gu;
 const HEADING_MARK = /^#{1,6}\s+/gmu;

package/src/theme/entry.ts

@@ -435,6 +435,9 @@ blume-diff {
   font-size: 0.8125rem;
 }
 
+/* GFM renders cells as <td><code> directly, which the descendant form alone
+   never matches (a cell is not its own descendant). */
+.prose :where(td, th) > code,
 .prose :where(td, th) :not(pre) > code {
   white-space: nowrap;
 }

package/src/theme/icons.ts

@@ -79,14 +79,10 @@ export const resolveIcon = (name: string): ResolvedIcon | null => {
   return fromSet(DEFAULT_SET, normalized);
 };
 
-/** Whether a name resolves to a known Lucide icon. */
-export const hasIcon = (name: string): boolean => {
-  if (resolveIcon(name)) {
-    return true;
-  }
-  const normalized = normalize(name);
-  const bare = normalized.includes(":")
-    ? normalized.slice(normalized.indexOf(":") + 1)
-    : normalized;
-  return Object.values(SETS).some((set) => getIconData(set, bare) !== null);
-};
+/**
+ * Whether a name resolves to a renderable icon. Exactly mirrors
+ * {@link resolveIcon}: a laxer check (e.g. matching the bare name under an
+ * unknown prefix) would let callers suppress their fallback and diagnostics
+ * for a name `<Icon>` then renders as nothing.
+ */
+export const hasIcon = (name: string): boolean => resolveIcon(name) !== null;