blume 1.7.3 → 2.0.0

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);
+};