blume 1.5.3 → 1.6.1

package/src/deploy/function-bundle.ts

@@ -0,0 +1,251 @@
+import { existsSync, readFileSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { builtinModules } from "node:module";
+
+import { dirname, join, relative } from "pathe";
+import { z } from "zod";
+
+import { packageRoot } from "../core/package-root.ts";
+
+/**
+ * Post-build audit of a Vercel serverless function bundle.
+ *
+ * The Vercel adapter traces the server entry with `@vercel/nft` and copies
+ * every file it reaches into `.vercel/output/functions/_render.func`. A bare
+ * import the trace cannot resolve — a package that isn't reachable by walking
+ * `node_modules` up from the chunk that imports it — is dropped *silently*,
+ * and the deployed function dies on its first request with
+ * `ERR_MODULE_NOT_FOUND` (Vercel reports it as `FUNCTION_INVOCATION_FAILED`).
+ * Under an isolated linker (pnpm, Bun's `isolated` mode) that is exactly the
+ * shape of Blume's own runtime dependencies: the SSR build leaves them
+ * external, and they live under `blume`'s store directory, not the project
+ * root. Nothing before deploy surfaces it — the build is green, a warm-cache
+ * preview is green — so the bundle is re-checked here with Node's own
+ * resolution rule: a package is present when some `node_modules/<name>` on
+ * the walk from the importing chunk up to the function root exists.
+ */
+
+/** A bare package import the function bundle cannot satisfy. */
+export interface MissingPackage {
+  /** Function-relative paths of the chunks that import the package. */
+  importers: string[];
+  name: string;
+}
+
+/** One function directory's audit result. */
+export interface FunctionBundleAudit {
+  /** Absolute path of the `*.func` directory. */
+  dir: string;
+  missing: MissingPackage[];
+}
+
+const BUILTINS = new Set(builtinModules);
+
+/** Specifier prefixes that never name an installed package. */
+const NON_PACKAGE_PREFIXES = ["node:", "astro:", "virtual:", "data:", "\0"];
+
+/**
+ * The package a bare specifier resolves through (`@scope/name` or `name`), or
+ * null for relative/absolute paths, Node builtins, and virtual ids.
+ */
+export const packageName = (specifier: string): string | null => {
+  if (
+    specifier.startsWith(".") ||
+    specifier.startsWith("/") ||
+    NON_PACKAGE_PREFIXES.some((prefix) => specifier.startsWith(prefix)) ||
+    BUILTINS.has(specifier)
+  ) {
+    return null;
+  }
+  const segments = specifier.split("/");
+  if (specifier.startsWith("@")) {
+    return segments.length >= 2 ? `${segments[0]}/${segments[1]}` : null;
+  }
+  return segments[0] || null;
+};
+
+/**
+ * Static specifiers: a side-effect `import "x"` or an `import`/`export … from
+ * "x"` clause. Only `import` takes the bare-string form — `export "x"` is not
+ * syntax, so a runtime message quoting `export 'ALL'` must not match. The
+ * specifier quote must not be escaped either: a backslash-quoted `from \"zod\"`
+ * is a code sample serialized into a string (the MCP snapshot carries page
+ * Markdown), not module syntax.
+ */
+const STATIC_IMPORT =
+  /(?:^|[;\s}])(?:import\s*(?<!\\)["'](?<bare>[^"'\n]+)["']|(?:import|export)\s*[\w$*{},\s]*?\s*from\s*(?<!\\)["'](?<from>[^"'\n]+)["'])/gu;
+
+/** Dynamic `import("…")` specifiers, same escaped-quote rule. */
+const DYNAMIC_IMPORT =
+  /\bimport\(\s*(?<!\\)["'](?<dynamic>[^"'\n]+)["']\s*\)/gu;
+
+/** Every bare package name a module's source imports. */
+export const importedPackages = (source: string): string[] => {
+  const names = new Set<string>();
+  for (const pattern of [STATIC_IMPORT, DYNAMIC_IMPORT]) {
+    for (const match of source.matchAll(pattern)) {
+      const groups = match.groups ?? {};
+      const name = packageName(
+        groups.bare ?? groups.from ?? groups.dynamic ?? ""
+      );
+      if (name) {
+        names.add(name);
+      }
+    }
+  }
+  return [...names];
+};
+
+/** Whether `node_modules/<name>` exists on the walk from `from` up to `root`. */
+const resolvable = (name: string, from: string, root: string): boolean => {
+  let dir = from;
+  for (;;) {
+    if (existsSync(join(dir, "node_modules", name, "package.json"))) {
+      return true;
+    }
+    if (dir === root) {
+      return false;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return false;
+    }
+    dir = parent;
+  }
+};
+
+const MODULE_FILE = /\.(?:m?js|cjs)$/u;
+
+/** The one `.vc-config.json` field the audit reads; the rest passes through. */
+const vcConfigSchema = z.looseObject({ handler: z.string().optional() });
+
+/** Every JavaScript module under `dir`, skipping any `node_modules`. */
+const listModules = async (dir: string): Promise<string[]> => {
+  const files: string[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== "node_modules") {
+        // oxlint-disable-next-line no-await-in-loop -- sequential walk keeps ordering deterministic
+        files.push(...(await listModules(path)));
+      }
+    } else if (entry.isFile() && MODULE_FILE.test(entry.name)) {
+      files.push(path);
+    }
+  }
+  return files;
+};
+
+/**
+ * Audit one function directory: read its `.vc-config.json` handler, scan
+ * every module beside the handler (the adapter's `dist/server` tree) for bare
+ * imports, and report the packages no `node_modules` on the walk up to the
+ * function root provides. A function without a handler has nothing to check.
+ */
+export const auditFunctionBundle = async (
+  funcDir: string
+): Promise<MissingPackage[]> => {
+  const configPath = join(funcDir, ".vc-config.json");
+  if (!existsSync(configPath)) {
+    return [];
+  }
+  const config = vcConfigSchema.safeParse(
+    JSON.parse(await readFile(configPath, "utf-8"))
+  );
+  if (!config.success || !config.data.handler) {
+    return [];
+  }
+  const serverDir = dirname(join(funcDir, config.data.handler));
+  if (!existsSync(serverDir)) {
+    return [];
+  }
+  const missing = new Map<string, string[]>();
+  for (const file of await listModules(serverDir)) {
+    // oxlint-disable-next-line no-await-in-loop -- sequential read keeps the importer lists ordered
+    const source = await readFile(file, "utf-8");
+    for (const name of importedPackages(source)) {
+      if (resolvable(name, dirname(file), funcDir)) {
+        continue;
+      }
+      const importers = missing.get(name) ?? [];
+      importers.push(relative(funcDir, file));
+      missing.set(name, importers);
+    }
+  }
+  return [...missing]
+    .map(([name, importers]) => ({ importers, name }))
+    .toSorted((a, b) => a.name.localeCompare(b.name));
+};
+
+/**
+ * Audit every function in a Vercel Build Output tree (`.vercel/output`).
+ * Functions with nothing missing are omitted; an output tree without a
+ * `functions/` directory (a static build) yields nothing.
+ */
+export const auditVercelFunctions = async (
+  outputDir: string
+): Promise<FunctionBundleAudit[]> => {
+  const functionsDir = join(outputDir, "functions");
+  if (!existsSync(functionsDir)) {
+    return [];
+  }
+  const audits: FunctionBundleAudit[] = [];
+  const entries = await readdir(functionsDir, { withFileTypes: true });
+  for (const entry of entries.toSorted((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (!(entry.isDirectory() && entry.name.endsWith(".func"))) {
+      continue;
+    }
+    const dir = join(functionsDir, entry.name);
+    // oxlint-disable-next-line no-await-in-loop -- sequential audit keeps the report ordered
+    const missing = await auditFunctionBundle(dir);
+    if (missing.length > 0) {
+      audits.push({ dir, missing });
+    }
+  }
+  return audits;
+};
+
+/** Blume's own runtime dependency names, from its published `package.json`. */
+export const blumeDependencyNames = (): Set<string> => {
+  const manifest: { dependencies?: Record<string, string> } = JSON.parse(
+    readFileSync(join(packageRoot(), "package.json"), "utf-8")
+  );
+  return new Set(Object.keys(manifest.dependencies ?? {}));
+};
+
+/** What a build should do about an audit: nothing, warn, or fail. */
+export interface FunctionBundleVerdict {
+  /**
+   * A missing package is one of Blume's own dependencies — the runtime Blume
+   * generated imports it, so the function is certain to crash. Anything else
+   * (a project's own external import) is reported but left to the author.
+   */
+  fatal: boolean;
+  message: string;
+}
+
+/**
+ * Describe a function's missing packages and how to fix them. Vercel's trace
+ * only reaches packages resolvable from the project root, so the remedy is a
+ * root-level dependency entry for each — the same mirror rule Blume's native
+ * dependencies (`sharp`, `takumi-js`) already follow.
+ */
+export const functionBundleVerdict = (
+  audit: FunctionBundleAudit,
+  root: string,
+  ownDependencies: ReadonlySet<string>
+): FunctionBundleVerdict => {
+  const names = audit.missing.map((entry) => entry.name);
+  const lines = audit.missing.map(
+    (entry) => `  - ${entry.name} (imported by ${entry.importers.join(", ")})`
+  );
+  const fatal = names.some((name) => ownDependencies.has(name));
+  const message = [
+    `The Vercel function bundle at ${relative(root, audit.dir) || audit.dir} is missing packages its server code imports, so the deployed function would fail on every request with ERR_MODULE_NOT_FOUND:`,
+    ...lines,
+    "Vercel's dependency trace only includes packages resolvable from the project root; under an isolated linker (pnpm, Bun's isolated mode) Blume's own dependencies are not. Add them to the project's package.json so the trace can find them:",
+    `  npm install -D ${names.join(" ")}`,
+  ].join("\n");
+  return { fatal, message };
+};

package/src/deploy/vercel-negotiation.ts

@@ -9,6 +9,9 @@
  * into it so a content-page request that prefers `text/markdown` is rewritten
  * (not redirected) to the page's prerendered `.md` mirror — the deployed
  * counterpart of the dev-server rewrite in `astro/markdown-negotiation.ts`.
+ * The same routing config also answers a *missing* page: a request that
+ * prefers Markdown (or asks for a `.md` URL no page backs) gets the
+ * prerendered Markdown 404 body with the 404 status, instead of the HTML shell.
  */
 
 /**
@@ -49,6 +52,32 @@ const ACCEPT_MARKDOWN_CONDITION: VercelRoute["has"] = [
 
 const VARY_ACCEPT = { vary: "Accept" };
 
+/** Where the prerendered Markdown 404 (`pages/404.md.ts`) lands. */
+const NOT_FOUND_MARKDOWN_DEST = "/404.md";
+
+/** The adapter's own not-found fallback — the anchor the Markdown 404 precedes. */
+const NOT_FOUND_HTML_DEST = "/404.html";
+
+/**
+ * Miss-phase routes that answer a missing page with the Markdown 404 body: any
+ * path when the client prefers Markdown, and any `.md`/`.mdx` URL (a request
+ * for a raw-Markdown mirror that has no page wants Markdown back, not the HTML
+ * shell). Both keep the 404 status. Spliced immediately before the adapter's
+ * `/404.html` fallback, so they run after every server route (the MCP
+ * endpoint, server islands, images) has had its turn and never hijack a
+ * request one of those would have answered.
+ */
+const NOT_FOUND_MARKDOWN_ROUTES: readonly VercelRoute[] = [
+  {
+    dest: NOT_FOUND_MARKDOWN_DEST,
+    has: ACCEPT_MARKDOWN_CONDITION,
+    headers: VARY_ACCEPT,
+    src: "^/.*$",
+    status: 404,
+  },
+  { dest: NOT_FOUND_MARKDOWN_DEST, src: "^/.*\\.mdx?$", status: 404 },
+];
+
 /**
  * Vercel rejects route `src` patterns longer than 4096 characters, so route
  * alternations are split across as many route entries as needed. The budget
@@ -186,12 +215,14 @@ export const TRAILING_SLASH_REDIRECT: VercelRoute = {
  * user-authored route of that identical shape would be semantically equal to
  * the one re-added); the homepage `Link` route by its three-field
  * continue-with-link shape (the Build Output config is adapter-generated, so
- * no user-authored route competes in this file).
+ * no user-authored route competes in this file); the Markdown 404 routes by
+ * their `/404.md` destination.
  */
 const isNegotiationRoute = (route: VercelRoute): boolean =>
   route.has?.some(
     (condition) => condition.value === ACCEPT_MARKDOWN_HEADER_VALUE
   ) === true ||
+  (route.dest === NOT_FOUND_MARKDOWN_DEST && route.status === 404) ||
   (route.continue === true &&
     route.headers?.vary === "Accept" &&
     isString(route.src) &&
@@ -213,17 +244,21 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
  * platform's mechanism for extensionless static files (e.g. the Web Bot Auth
  * signature directory). The trailing-slash 308 redirect is always spliced in
  * alongside, so slashed duplicates of every page collapse onto the canonical
- * slashless URL. Returns the updated JSON text (tab-indented, like the
- * adapter's own output), or `null` when there is nowhere safe to splice: an
- * unparsable config, no `routes` array, or no `handle: "filesystem"` marker
- * to anchor the splice.
+ * slashless URL. With `notFoundMarkdown` (the build emitted `404.md`), the
+ * Markdown 404 routes go into the miss phase right before the adapter's
+ * `/404.html` fallback — and nowhere when that fallback is absent, since a
+ * `dest` with no file behind it would serve nothing. Returns the updated JSON
+ * text (tab-indented, like the adapter's own output), or `null` when there is
+ * nowhere safe to splice: an unparsable config, no `routes` array, or no
+ * `handle: "filesystem"` marker to anchor the splice.
  */
 export const injectNegotiationRoutes = (
   configText: string,
   routePaths: readonly string[],
   homeLinkHeader?: string | null,
   contentTypeOverrides?: Record<string, string>,
-  homeTokens?: number
+  homeTokens?: number,
+  notFoundMarkdown = false
 ): string | null => {
   const overrideEntries = Object.entries(contentTypeOverrides ?? {});
   let config: {
@@ -272,6 +307,14 @@ export const injectNegotiationRoutes = (
     ...rewriteRoutes,
     TRAILING_SLASH_REDIRECT
   );
+  if (notFoundMarkdown) {
+    const fallbackIndex = routes.findIndex(
+      (route) => route.status === 404 && route.dest === NOT_FOUND_HTML_DEST
+    );
+    if (fallbackIndex !== -1) {
+      routes.splice(fallbackIndex, 0, ...NOT_FOUND_MARKDOWN_ROUTES);
+    }
+  }
   config.routes = routes;
   return `${JSON.stringify(config, null, "\t")}\n`;
 };

package/src/eval/schema.ts

@@ -3,6 +3,8 @@ import { readFile } from "node:fs/promises";
 import { load } from "js-yaml";
 import { z } from "zod";
 
+import { YAML_SCHEMA } from "../core/yaml.ts";
+
 /** Question ids are kebab-case slugs so they read well in reports and CI logs. */
 const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/u;
 
@@ -90,7 +92,7 @@ export const loadEvalsFile = async (
 
   let parsed: unknown;
   try {
-    parsed = load(raw);
+    parsed = load(raw, { schema: YAML_SCHEMA });
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     throw new EvalsFileError(path, `Invalid YAML in ${path}: ${detail}`);

package/src/markdown/code-title.ts

@@ -9,6 +9,13 @@
  *   `data-line-numbers`; the theme renders a counter-driven line-number gutter.
  */
 
+import {
+  isLineRange,
+  metaTokens,
+  QUOTED_ATTR,
+  RESERVED_META_KEYWORDS,
+} from "./fence-meta.ts";
+
 /** The slice of Shiki's transformer `this` context Blume reads. */
 interface CodeMetaContext {
   options: { meta?: { __raw?: string } };
@@ -25,29 +32,25 @@ export interface CodeTitleTransformer {
   pre: (this: CodeMetaContext, node: PreNode) => void;
 }
 
-// The body excludes only the delimiting quote, so `title="foo's file.ts"`
-// (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;
 
+// Quoted attrs are blanked before keyword/bare-token scans so a quoted value
+// can't leak tokens (`title="enable lineNumbers later"`).
 const withoutQuotedAttrs = (raw: string): string =>
   raw.replace(QUOTED_ATTR, " ");
 
 // The first bare token is the title (```ts blume.config.ts): a non-empty token
 // that isn't a Shiki line range (`{1,3-5}`), a `key=value` attr, or a reserved
-// `lineNumbers`/`twoslash` keyword.
-const isTitleToken = (token: string): boolean => {
-  if (token.length === 0 || token.startsWith("{") || token.includes("=")) {
-    return false;
-  }
-  return token !== "lineNumbers" && token !== "twoslash";
-};
+// keyword.
+const isTitleToken = (token: string): boolean =>
+  token.length > 0 &&
+  !isLineRange(token) &&
+  !token.includes("=") &&
+  !RESERVED_META_KEYWORDS.has(token);
 
-const parseTitle = (raw: string | undefined): string | undefined => {
+/** The title a fence's meta string promotes to `data-title`, if any. */
+export const parseCodeTitle = (raw: string | undefined): string | undefined => {
   if (!raw) {
     return undefined;
   }
@@ -62,7 +65,10 @@ const parseTitle = (raw: string | undefined): string | undefined => {
   if (attrTitle) {
     return attrTitle;
   }
-  return withoutQuotedAttrs(raw).trim().split(/\s+/u).find(isTitleToken);
+  // The shared tokenizer keeps a quoted attr (rejected below by its `=`) and
+  // a spaced line range (`{1, 3-5}`) whole, so neither can shed a fragment
+  // that reads as a bare title.
+  return metaTokens(raw).find(isTitleToken);
 };
 
 const hasLineNumbers = (raw: string | undefined): boolean =>
@@ -73,7 +79,7 @@ export const codeTitleTransformer = (): CodeTitleTransformer => ({
   name: "blume:code-meta",
   pre(node) {
     const raw = this.options.meta?.__raw;
-    const title = parseTitle(raw);
+    const title = parseCodeTitle(raw);
     if (title) {
       node.properties.dataTitle = title;
     }

package/src/markdown/features.ts

@@ -0,0 +1,21 @@
+import type { Features } from "satteri";
+
+/**
+ * Sätteri's feature set for plain `.md` pages. Shared by the renderer and the
+ * search extractor so the index reads the same grammar the page renders.
+ */
+export const MARKDOWN_FEATURES = {
+  subscript: true,
+  superscript: true,
+} satisfies Features;
+
+/**
+ * The `.mdx` feature set: Markdown's plus `:::` directives (→ `<Callout>`) and
+ * block-only math — `singleDollarTextMath: false` keeps a bare `$` (currency,
+ * shell, code) as literal text and only parses `$$…$$`.
+ */
+export const MDX_FEATURES = {
+  ...MARKDOWN_FEATURES,
+  directive: true,
+  math: { singleDollarTextMath: false },
+} satisfies Features;

package/src/markdown/fence-meta.ts

@@ -0,0 +1,50 @@
+/**
+ * The shared fence-meta grammar: how the tokens after a code fence's language
+ * (```ts title="..." {1,3-5} lineNumbers) split, and which of them carry
+ * reserved meaning. Both the Shiki-side meta reader (`code-title.ts`) and the
+ * MDAST plugins that rewrite marked fences (`ts2js.ts`) consume this, so the
+ * two layers can't drift on token boundaries or keyword lists.
+ */
+
+/**
+ * Any quoted `key="..."` attr (spaces allowed inside the quotes). The body
+ * excludes only the delimiting quote, so `title="foo's file.ts"` (an
+ * apostrophe inside double quotes) still matches. The left boundary stops
+ * `subtitle="..."` (or any `*title=` attr) from reading as a title.
+ */
+export const QUOTED_ATTR = /[\w-]+=(?:"[^"]*"|'[^']*')/gu;
+
+/**
+ * A Shiki `{1,3-5}` line-range token, braces included. Shiki tolerates
+ * whitespace inside the braces (`{1, 3-5}`), so the range is one token even
+ * when it contains spaces — split on whitespace alone, `3-5}` would surface
+ * as a bare word and be promoted to the block title.
+ */
+const LINE_RANGE = /\{[^}]*\}/u;
+
+/**
+ * One fence-meta token: a quoted attribute, a line range, or a bare word, so
+ * a keyword inside a quoted value (`title="enable ts2js later"`) never reads
+ * as a bare token and a spaced line range never splits.
+ */
+const META_TOKEN = new RegExp(
+  `${QUOTED_ATTR.source}|${LINE_RANGE.source}|\\S+`,
+  "gu"
+);
+
+/** Split a raw fence meta string into its tokens. */
+export const metaTokens = (meta: string | null | undefined): string[] =>
+  meta?.match(META_TOKEN) ?? [];
+
+/**
+ * Bare keywords with reserved meaning after the language; never promoted to
+ * a block title.
+ */
+export const RESERVED_META_KEYWORDS: ReadonlySet<string> = new Set([
+  "lineNumbers",
+  "ts2js",
+  "twoslash",
+]);
+
+/** A Shiki `{1,3-5}` line-range token. */
+export const isLineRange = (token: string): boolean => token.startsWith("{");