blume 1.7.2 → 2.0.0

package/src/core/project-graph.ts

@@ -1,7 +1,8 @@
 import { isAbsolute, relative } from "pathe";
 
+import { CHANGELOG_INDEX_ROUTE, hasChangelogIndex } from "./changelog-index.ts";
 import { loadConfig } from "./config.ts";
-import { applyDeploymentEnv } from "./deployment-env.ts";
+import { customStaticRoutes, discoverPages } from "./custom-pages.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import { expandIncludes, hasIncludeStatements } from "./includes.ts";
@@ -36,12 +37,6 @@ export type BuildMode = "dev" | "build";
 export interface ConfigOverrides {
   /** Override `content.root` (`blume dev --content-dir`). */
   contentRoot?: string;
-  /** Override `deployment.adapter` (`blume build --adapter`). */
-  adapter?: ResolvedConfig["deployment"]["adapter"];
-  /** Override `deployment.base` (`blume build --base`). */
-  base?: string;
-  /** Override `deployment.output` (`blume build --output`). */
-  output?: ResolvedConfig["deployment"]["output"];
 }
 
 /**
@@ -61,18 +56,20 @@ const applyConfigOverrides = (
   if (!overrides) {
     return config;
   }
+  // `--content-dir` re-roots every filesystem source: with one (the
+  // zero-config case) it is exactly the old `content.root` override, and
+  // several must share a root anyway (see `resolveDocsCollection`).
+  const { contentRoot } = overrides;
+  const sources = contentRoot
+    ? config.content.sources.map((source) =>
+        source.kind === "filesystem"
+          ? { ...source, options: { ...source.options, root: contentRoot } }
+          : source
+      )
+    : config.content.sources;
   return {
     ...config,
-    content: {
-      ...config.content,
-      root: overrides.contentRoot ?? config.content.root,
-    },
-    deployment: {
-      ...config.deployment,
-      adapter: overrides.adapter ?? config.deployment.adapter,
-      base: overrides.base ?? config.deployment.base,
-      output: overrides.output ?? config.deployment.output,
-    },
+    content: { ...config.content, sources },
   };
 };
 
@@ -138,7 +135,7 @@ const entryIdDiagnostics = (
         message: `Content source "${page.source.name}" is rooted outside the docs collection base, so ${page.route} resolves entry id "${entryId}" but the collection would generate "${expected}" — the page would 404 at runtime.`,
         severity: "error",
         suggestion:
-          "Use a single filesystem source (the docs collection roots at it), or root every filesystem source at content.root and partition them with include globs — a root at a subdirectory of content.root still mismatches.",
+          "Use a single filesystem() source (the docs collection roots at it), or give every filesystem() source the same root and partition them with include globs — a root at a subdirectory of the first source's root still mismatches.",
       });
     }
   }
@@ -185,6 +182,7 @@ const normalizeLoadedEntries = (
         frontmatterExtend,
         i18n: config.i18n,
         source: {
+          monolingual: source.monolingual,
           name: source.name,
           prefix: source.prefix,
           staged: source.staged,
@@ -208,6 +206,15 @@ const normalizeLoadedEntries = (
  * Collects all diagnostics without throwing on content-level problems so
  * callers can decide how strict to be.
  */
+/** Narrows the logo config's image shorthand from its object form. */
+const isLogoShorthand = (
+  logo: NonNullable<ResolvedConfig["logo"]>
+): logo is string => typeof logo === "string";
+
+/** The configured brand link: `logo.href`, else the site root. */
+const logoHref = (logo: ResolvedConfig["logo"]): string =>
+  logo === undefined || isLogoShorthand(logo) ? "/" : (logo.href ?? "/");
+
 export const scanProject = async (
   root: string,
   options: {
@@ -226,13 +233,7 @@ export const scanProject = async (
   const configResult = await loadConfig(root, {
     devServerUrl: options.devServerUrl,
   });
-  // Re-run platform detection after CLI overrides: `loadConfig` already ran it,
-  // but adapter inference keys off `deployment.output`, which `--output server`
-  // only sets here. Idempotent for already-resolved fields — `deployment.site`
-  // keeps loadConfig's explicit > platform env > devServerUrl precedence.
-  const config = applyDeploymentEnv(
-    applyConfigOverrides(configResult.config, options.overrides)
-  );
+  const config = applyConfigOverrides(configResult.config, options.overrides);
   const context = resolveProjectContext(root, config, {
     runtimeDir: options.runtimeDir,
   });
@@ -373,8 +374,20 @@ export const scanProject = async (
     );
   }
 
+  // Custom `.astro` pages and the generated changelog index aren't content
+  // pages, so name them for navigation: a `/changelog` tab should open the
+  // timeline, not the newest entry, and a tab or brand link to a custom page
+  // must stay on its route in every locale.
+  const customPages = context.pagesRoot
+    ? await discoverPages(context.pagesRoot)
+    : [];
   const graph = buildContentGraph(pages, {
     basePath: config.basePath,
+    brandHref: logoHref(config.logo),
+    extraRoutes: new Set([
+      ...customStaticRoutes(customPages),
+      ...(hasChangelogIndex(pages, config) ? [CHANGELOG_INDEX_ROUTE] : []),
+    ]),
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,
@@ -397,7 +410,10 @@ export const scanProject = async (
       ...contentDiagnostics,
       ...includeDiagnostics,
       ...folderMeta.diagnostics,
-      ...entryIdDiagnostics(pages, resolveDocsCollection(config, context).base),
+      ...entryIdDiagnostics(
+        pages,
+        resolveDocsCollection(config, context.root).base
+      ),
       ...graph.diagnostics,
       ...i18nWarnings,
       ...versionWarnings,

package/src/core/project.ts

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { isAbsolute, join, resolve } from "pathe";
 
 import type { ResolvedConfig } from "./schema.ts";
+import { resolveDocsCollection } from "./sources/collection.ts";
 import type { ProjectContext } from "./types.ts";
 
 const CONFIG_FILENAMES = [
@@ -28,6 +29,10 @@ const firstExisting = (root: string, names: string[]): string | null => {
 export const findConfigFile = (root: string): string | null =>
   firstExisting(root, CONFIG_FILENAMES);
 
+/** Locate the project's `components.ts`/`.tsx` override file, if any. */
+export const findComponentsFile = (root: string): string | null =>
+  firstExisting(root, COMPONENTS_FILENAMES);
+
 /**
  * Resolve the generated runtime directory for a project. Defaults to
  * `<root>/.blume`; an override (e.g. `.blume-verify` for an isolated build that
@@ -51,9 +56,9 @@ export const resolveProjectContext = (
   options?: { runtimeDir?: string }
 ): ProjectContext => {
   const absoluteRoot = resolve(root);
-  const contentRoot = isAbsolute(config.content.root)
-    ? config.content.root
-    : join(absoluteRoot, config.content.root);
+  // The content root is where the `docs` collection roots: the first
+  // filesystem source (the implicit one, for a zero-config project).
+  const contentRoot = resolveDocsCollection(config, absoluteRoot).base;
 
   const pagesPath = join(absoluteRoot, config.content.pages);
   const pagesRoot = existsSync(pagesPath) ? pagesPath : null;
@@ -66,7 +71,7 @@ export const resolveProjectContext = (
     : join(absoluteRoot, "dist");
 
   return {
-    componentsFile: firstExisting(absoluteRoot, COMPONENTS_FILENAMES),
+    componentsFile: findComponentsFile(absoluteRoot),
     configFile: findConfigFile(absoluteRoot),
     contentRoot,
     distDir,

package/src/core/request-body.ts

@@ -0,0 +1,61 @@
+/**
+ * Read a request body under a size cap, for the unauthenticated endpoints a
+ * server build exposes (the Ask AI route, the API playground proxy). A
+ * self-hosted Node server buffers whatever a client sends, so an endpoint that
+ * starts with `request.json()` or `arrayBuffer()` lets one oversized POST
+ * allocate hundreds of megabytes before any validation runs. A declared
+ * `content-length` over the cap is refused without reading the body; a body
+ * sent without one (chunked) is read until it passes the cap, then cancelled.
+ *
+ * Resolves to the bytes, or `undefined` when the body is over the cap — the
+ * caller answers that with a `413`.
+ */
+export const readCappedBody = async (
+  request: Request,
+  maxBytes: number
+): Promise<Uint8Array<ArrayBuffer> | undefined> => {
+  const declared = request.headers.get("content-length");
+  if (declared !== null && Number(declared) > maxBytes) {
+    return undefined;
+  }
+  if (!request.body) {
+    return new Uint8Array(0);
+  }
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  let over = false;
+  while (!over) {
+    // oxlint-disable-next-line no-await-in-loop -- a stream yields its chunks one read at a time, in order
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    size += value.byteLength;
+    over = size > maxBytes;
+    chunks.push(value);
+  }
+  if (over) {
+    await reader.cancel();
+    return undefined;
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+};
+
+/**
+ * The body as UTF-8 text under the same cap as {@link readCappedBody}, or
+ * `undefined` when it's over the cap.
+ */
+export const readCappedText = async (
+  request: Request,
+  maxBytes: number
+): Promise<string | undefined> => {
+  const bytes = await readCappedBody(request, maxBytes);
+  return bytes === undefined ? undefined : new TextDecoder().decode(bytes);
+};

package/src/core/safe-href.ts

@@ -0,0 +1,28 @@
+/**
+ * Link destinations in content Blume imports from someone else — an API spec's
+ * descriptions, a repository's release notes, CMS rich text — that are safe to
+ * render as a clickable link. Author-written pages are trusted and never pass
+ * through here; imported content can carry a `javascript:` (or `data:`,
+ * `vbscript:`) link that would run as the docs site when a reader clicks it.
+ * A destination with no scheme (a relative path, a fragment) stays a link, as
+ * does one whose scheme is on this list.
+ */
+const SAFE_SCHEMES = new Set(["http", "https", "mailto", "tel"]);
+
+const SCHEME = /^(?<scheme>[a-z][\d+.a-z-]*):/iu;
+
+// The URL parser removes ASCII tabs and newlines anywhere, and strips leading
+// C0 controls and spaces, before it reads a scheme — so `java\tscript:` is a
+// `javascript:` URL to a browser, and the check must see it the same way.
+const URL_IGNORED = /[\t\n\r]/gu;
+
+/** Whether a link destination from imported content is safe to keep. */
+export const isSafeHref = (href: string): boolean => {
+  const cleaned = href.replaceAll(URL_IGNORED, "");
+  let start = 0;
+  while (start < cleaned.length && (cleaned.codePointAt(start) ?? 0) <= 0x20) {
+    start += 1;
+  }
+  const scheme = SCHEME.exec(cleaned.slice(start))?.groups?.scheme;
+  return scheme === undefined || SAFE_SCHEMES.has(scheme.toLowerCase());
+};

package/src/core/safe-links.ts

@@ -0,0 +1,68 @@
+import type { Nodes, Root } from "mdast";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { toString } from "mdast-util-to-string";
+
+import { isSafeHref } from "./safe-href.ts";
+import { escapeMarkdownText } from "./sources/lower.ts";
+
+/** A link (or link definition) whose destination isn't safe. */
+export interface UnsafeLinkSpan {
+  /** End offset in the source, exclusive. */
+  end: number;
+  /** Start offset in the source. */
+  start: number;
+  /**
+   * What replaces it: the link's label, escaped so it can't form a link
+   * again; empty for a definition.
+   */
+  text: string;
+}
+
+/**
+ * The unsafe links in a parsed Markdown tree, in source order: inline and
+ * reference links (autolinks included) and link definitions whose parsed
+ * destination fails {@link isSafeHref}. The parsed `url` is what a browser
+ * would get, character references and all, so `javascript:` is caught.
+ */
+export const unsafeLinkSpans = (tree: Root): UnsafeLinkSpan[] => {
+  const spans: UnsafeLinkSpan[] = [];
+  const visit = (node: Nodes): void => {
+    if (
+      (node.type === "link" || node.type === "definition") &&
+      !isSafeHref(node.url)
+    ) {
+      // fromMarkdown stamps every node's position.
+      const start = node.position?.start.offset ?? 0;
+      const end = node.position?.end.offset ?? 0;
+      spans.push({
+        end,
+        start,
+        text: node.type === "link" ? escapeMarkdownText(toString(node)) : "",
+      });
+      return;
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        visit(child);
+      }
+    }
+  };
+  visit(tree);
+  return spans;
+};
+
+/**
+ * Markdown with every unsafe link reduced to its label text and every unsafe
+ * link definition removed. Everything else — safe links, raw HTML, code —
+ * passes through as written.
+ */
+export const neutralizeUnsafeLinks = (markdown: string): string => {
+  const spans = unsafeLinkSpans(fromMarkdown(markdown));
+  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);
+};