blume 1.0.4 → 1.1.0

package/src/components/openapi/security.ts

@@ -0,0 +1,201 @@
+/**
+ * Security (authorization) resolution for the OpenAPI components. An operation
+ * enforces its own `security` when declared — an empty array explicitly makes
+ * it public — and inherits the document's root `security` otherwise. Within the
+ * resolved list, each requirement object is one way to authorize (OR between
+ * entries), and every scheme named inside a single requirement is needed
+ * together (AND). Pure and dependency-free like `helpers.ts`, so it runs in the
+ * browser build with no server-only imports.
+ */
+
+/** A permissive view of an OpenAPI security scheme — only the fields we render. */
+export interface SecuritySchemeLike {
+  type?: string;
+  description?: string;
+  /** `apiKey`: the parameter name the key is sent as. */
+  name?: string;
+  /** `apiKey`: where the key goes — `header`, `query`, or `cookie`. */
+  in?: string;
+  /** `http`: the HTTP auth scheme, e.g. `bearer` or `basic`. */
+  scheme?: string;
+  /** `http` bearer: a hint at the token format, e.g. `JWT`. */
+  bearerFormat?: string;
+  [key: string]: unknown;
+}
+
+/** One security requirement: scheme name -> required scopes (empty outside OAuth). */
+export type SecurityRequirementLike = Record<string, string[]>;
+
+/** A scheme resolved out of `components.securitySchemes`, with its scopes. */
+export interface ResolvedScheme {
+  /** The scheme's component name, e.g. `bearerAuth`. */
+  key: string;
+  /** The scheme object; undefined when the requirement names an unknown one. */
+  scheme?: SecuritySchemeLike;
+  scopes: string[];
+}
+
+/** The security state one operation renders. */
+export interface OperationSecurity {
+  /** Ways to authorize (OR); every scheme within one entry is required (AND). */
+  alternatives: ResolvedScheme[][];
+  /** True when an empty requirement also allows unauthenticated calls. */
+  optional: boolean;
+}
+
+/**
+ * The requirement list an operation actually enforces: its own `security` when
+ * declared — the OpenAPI override rule, where `[]` removes the default and
+ * makes the operation public — else the document's root `security`.
+ */
+export const effectiveSecurity = (
+  operation?: SecurityRequirementLike[],
+  document?: SecurityRequirementLike[]
+): SecurityRequirementLike[] => operation ?? document ?? [];
+
+/**
+ * Resolve requirement names against `components.securitySchemes`. A name with
+ * no matching component is kept (with `scheme` undefined) so an inconsistent
+ * spec still renders the requirement instead of silently dropping it. An empty
+ * requirement object — the spec idiom for "auth optional" — contributes no
+ * alternative and flips `optional` instead.
+ */
+export const resolveSecurity = (
+  requirements: SecurityRequirementLike[],
+  schemes: Record<string, SecuritySchemeLike> | undefined
+): OperationSecurity => {
+  const alternatives: ResolvedScheme[][] = [];
+  let optional = false;
+  for (const requirement of requirements) {
+    const entries = Object.entries(requirement ?? {});
+    if (entries.length === 0) {
+      optional = true;
+      continue;
+    }
+    alternatives.push(
+      entries.map(([key, scopes]) => ({
+        key,
+        scheme: schemes?.[key],
+        scopes: Array.isArray(scopes)
+          ? scopes.filter((scope): scope is string => typeof scope === "string")
+          : [],
+      }))
+    );
+  }
+  return { alternatives, optional };
+};
+
+const capitalize = (text: string): string =>
+  text.charAt(0).toUpperCase() + text.slice(1);
+
+/** A short human label for a scheme row, e.g. `Bearer token` or `API key`. */
+export const schemeLabel = (resolved: ResolvedScheme): string => {
+  const { scheme } = resolved;
+  switch (scheme?.type) {
+    case "http": {
+      const kind = (scheme.scheme ?? "").toLowerCase();
+      if (kind === "bearer") {
+        return scheme.bearerFormat
+          ? `Bearer token (${scheme.bearerFormat})`
+          : "Bearer token";
+      }
+      if (kind === "basic") {
+        return "Basic auth";
+      }
+      return kind ? `HTTP ${kind}` : "HTTP auth";
+    }
+    case "apiKey": {
+      return "API key";
+    }
+    case "oauth2": {
+      return "OAuth2 access token";
+    }
+    case "openIdConnect": {
+      return "OpenID Connect token";
+    }
+    case "mutualTLS": {
+      return "Mutual TLS";
+    }
+    default: {
+      // Unknown scheme ref: the component name is the best label available.
+      return resolved.key;
+    }
+  }
+};
+
+/**
+ * Where the credential travels: the header/query/cookie parameter it occupies.
+ * Undefined for schemes with no request parameter (mutual TLS) and for unknown
+ * refs, where guessing a location would be misleading.
+ */
+export const schemeCarrier = (
+  resolved: ResolvedScheme
+): { name: string; in: string } | undefined => {
+  const { scheme } = resolved;
+  switch (scheme?.type) {
+    case "http":
+    case "oauth2":
+    case "openIdConnect": {
+      return { in: "header", name: "Authorization" };
+    }
+    case "apiKey": {
+      return { in: scheme.in ?? "header", name: scheme.name ?? resolved.key };
+    }
+    default: {
+      return undefined;
+    }
+  }
+};
+
+/** Placeholder credentials the request samples send. */
+export interface SampleAuth {
+  headers: Record<string, string>;
+  query: Record<string, string>;
+}
+
+/**
+ * Placeholder credentials for an operation's request samples, from its first
+ * alternative (the spec's preferred way to authorize). Schemes that don't
+ * travel in the request (mutual TLS) and unknown refs contribute nothing.
+ */
+export const sampleAuth = (security: OperationSecurity): SampleAuth => {
+  const headers: Record<string, string> = {};
+  const query: Record<string, string> = {};
+  const cookies: string[] = [];
+  for (const resolved of security.alternatives[0] ?? []) {
+    const { scheme } = resolved;
+    switch (scheme?.type) {
+      case "http": {
+        const kind = (scheme.scheme ?? "bearer").toLowerCase();
+        headers.Authorization =
+          kind === "bearer"
+            ? "Bearer YOUR_TOKEN"
+            : `${capitalize(kind)} YOUR_CREDENTIALS`;
+        break;
+      }
+      case "oauth2":
+      case "openIdConnect": {
+        headers.Authorization = "Bearer YOUR_ACCESS_TOKEN";
+        break;
+      }
+      case "apiKey": {
+        const name = scheme.name ?? resolved.key;
+        if (scheme.in === "query") {
+          query[name] = "YOUR_API_KEY";
+        } else if (scheme.in === "cookie") {
+          cookies.push(`${name}=YOUR_API_KEY`);
+        } else {
+          headers[name] = "YOUR_API_KEY";
+        }
+        break;
+      }
+      default: {
+        break;
+      }
+    }
+  }
+  if (cookies.length > 0) {
+    headers.Cookie = cookies.join("; ");
+  }
+  return { headers, query };
+};

package/src/components/openapi/snippets.ts

@@ -1,5 +1,6 @@
 import { exampleValue, toJson } from "./helpers.ts";
 import type { SchemaLike } from "./helpers.ts";
+import type { SampleAuth } from "./security.ts";
 
 /**
  * Request example + code-sample generation for an operation. Kept separate from
@@ -43,16 +44,22 @@ const jsonContentType = (
   return entries.find(([type]) => type.includes("json")) ?? entries[0];
 };
 
-/** The `?a=1&b=2` query string from an operation's required query params. */
+/**
+ * The `?a=1&b=2` query string from an operation's required query params, plus
+ * any extra entries (a query-borne API key from the security requirements).
+ */
 const queryString = (
   params: ParamLike[],
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  extra: Record<string, string>
 ): string => {
   const query: string[] = [];
+  const seen = new Set<string>();
   for (const param of params) {
     if (!(param.in === "query" && param.required && param.name)) {
       continue;
     }
+    seen.add(param.name);
     const value = param.example ?? exampleValue(param.schema, schemas);
     query.push(
       `${encodeURIComponent(param.name)}=${encodeURIComponent(
@@ -60,16 +67,46 @@ const queryString = (
       )}`
     );
   }
+  for (const [name, value] of Object.entries(extra)) {
+    // A spec may declare the credential as an explicit query parameter too;
+    // its (better) example wins over the auth placeholder, as in headers.
+    if (seen.has(name)) {
+      continue;
+    }
+    query.push(`${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
+  }
   return query.length > 0 ? `?${query.join("&")}` : "";
 };
 
+/**
+ * The sample's headers: auth placeholders first, so a spec that also declares
+ * the credential as an explicit header parameter overrides them with its own
+ * (better) example.
+ */
+const headerValues = (
+  params: ParamLike[],
+  schemas: Record<string, SchemaLike>,
+  auth: SampleAuth | undefined
+): Record<string, string> => {
+  const headers: Record<string, string> = { ...auth?.headers };
+  for (const param of params) {
+    if (param.in === "header" && param.required && param.name) {
+      headers[param.name] = String(
+        param.example ?? exampleValue(param.schema, schemas) ?? ""
+      );
+    }
+  }
+  return headers;
+};
+
 /** Assemble a representative request from an operation and the spec servers. */
 export const buildRequestSample = (
   operation: OperationLike,
   method: string,
   path: string,
   servers: { url?: string }[],
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  auth?: SampleAuth
 ): RequestSample => {
   const base = (servers[0]?.url ?? "").replace(TRAILING_SLASH, "");
   const params = operation.parameters ?? [];
@@ -85,16 +122,8 @@ export const buildRequestSample = (
     }
   }
 
-  const search = queryString(params, schemas);
-
-  const headers: Record<string, string> = {};
-  for (const param of params) {
-    if (param.in === "header" && param.required && param.name) {
-      headers[param.name] = String(
-        param.example ?? exampleValue(param.schema, schemas) ?? ""
-      );
-    }
-  }
+  const search = queryString(params, schemas, auth?.query ?? {});
+  const headers = headerValues(params, schemas, auth);
 
   const media = jsonContentType(operation.requestBody?.content);
   let body: string | undefined;

package/src/core/config-input.ts

@@ -10,6 +10,7 @@ import type {
   SidebarItemConfig,
 } from "./schema.ts";
 import type { ContentSource } from "./sources/types.ts";
+import type { StandardSchema } from "./standard-schema.ts";
 
 /**
  * The public, hand-documented authoring type for `blume.config.ts`.
@@ -452,6 +453,16 @@ export interface MixedbreadSearch {
   storeId: string;
 }
 
+/** A curated link for the search dialog empty state. */
+export interface SearchPopularLink {
+  /** Internal route or external URL. */
+  href: string;
+  /** Built-in icon name shown beside the label; defaults to the file glyph. */
+  icon?: string;
+  /** Link label shown in the dialog. */
+  label: string;
+}
+
 /**
  * Search backend. The default `orama` builds a local index at build time (and
  * runs in dev); hosted providers need their credential block below. `none`
@@ -469,6 +480,11 @@ export interface SearchConfig {
   mixedbread?: MixedbreadSearch;
   /** Orama Cloud credentials (required when `provider` is `orama-cloud`). */
   oramaCloud?: OramaCloudSearch;
+  /**
+   * Curated links for the Cmd+K empty state. When omitted or empty, the first
+   * sidebar pages are shown instead.
+   */
+  popular?: SearchPopularLink[];
   /** Which backend powers search. Defaults to `orama`. */
   provider?: SearchProvider;
   /** Typesense credentials (required when `provider` is `typesense`). */
@@ -711,7 +727,7 @@ export interface RssConfig {
   types?: string[];
 }
 
-/** Colors used by generated Open Graph cards. Values must be hex colors. */
+/** Colors used by generated Open Graph cards. Any CSS color — hex, `oklch(…)`, `rgb(…)`, named. */
 export interface OgPaletteConfig {
   /** Fallback mark color. Defaults to the light theme accent. */
   accent?: string;
@@ -733,6 +749,21 @@ export interface OgConfig {
    * value always wins.
    */
   enabled?: boolean;
+  /**
+   * Google Font families for the generated card, extending Takumi's Latin-only
+   * default so non-Latin titles (CJK, and so on) render instead of tofu.
+   * Fetched from Google Fonts at build. A bare string loads the family's
+   * default weights; the object form pins weights (`700`, `[400, 700]`, or a
+   * `"100..900"` variable range) and styles.
+   */
+  fonts?: (
+    | string
+    | {
+        name: string;
+        style?: "normal" | "italic" | ("normal" | "italic")[];
+        weight?: number | number[] | string;
+      }
+  )[];
   /** Local SVG used in the generated card instead of the site logo. */
   logo?: string;
   /** Optional generated-card colors. */
@@ -918,6 +949,38 @@ export type ExportConfig =
       pdf?: boolean;
     };
 
+/**
+ * Opt-in custom frontmatter keys. Page frontmatter is strictly validated —
+ * an unknown key fails the build so typos are caught — and `extend` carves
+ * out project-specific keys from that rule, each validated by a schema you
+ * supply.
+ */
+export interface FrontmatterConfig {
+  /**
+   * Extra frontmatter keys pages may carry, mapped to their validation
+   * schemas — any library implementing Standard Schema works (Zod — the
+   * version your project installs, 3.24+ or 4 — Valibot, ArkType):
+   *
+   * ```ts
+   * import { z } from "zod";
+   *
+   * frontmatter: {
+   *   extend: {
+   *     owner: z.string(),
+   *     reviewedAt: z.coerce.date().optional(),
+   *   },
+   * },
+   * ```
+   *
+   * Every declared key is validated on every page — absent ones included —
+   * so a required schema enforces the key site-wide; mark it `.optional()`
+   * to validate only when present. Validated values are preserved on each
+   * page record's `custom` field. Built-in frontmatter fields cannot be
+   * redeclared.
+   */
+  extend?: Record<string, StandardSchema>;
+}
+
 /**
  * "Last updated" timestamps. `false` (default) disables them; `true` derives
  * each date from git history; the object form selects the source. A page's
@@ -991,6 +1054,8 @@ export interface BlumeConfig {
   export?: ExportConfig;
   /** Show the per-page "Was this helpful?" widget. Defaults to `true`. */
   feedback?: boolean;
+  /** Opt-in custom frontmatter keys, validated by schemas you supply. */
+  frontmatter?: FrontmatterConfig;
   /** Source repository (Edit-this-page links and the header repo link). */
   github?: GithubConfig;
   /** Internationalization (opt-in multi-locale). */

package/src/core/data.ts

@@ -1,3 +1,4 @@
+import type { OgFont } from "../og/card.ts";
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
 import type { Navigation, RouteAlternate } from "./types.ts";
@@ -115,12 +116,19 @@ export interface BlumeDataConfig {
   /** Open Graph image generation. */
   og: {
     enabled: boolean;
+    /** Extra Google Font family specs for the card renderer, fetched at build. */
+    fonts?: OgFont[];
     logo?: string;
     palette?: ResolvedConfig["seo"]["og"]["palette"];
   };
   /** Repository URL for header/edit links, or `null`. */
   repoUrl: string | null;
-  search: { enabled: boolean; provider: SearchProvider };
+  search: {
+    enabled: boolean;
+    /** Resolved empty-state links; empty when unset (Search falls back to sidebar). */
+    popular: { icon?: string; label: string; route: string }[];
+    provider: SearchProvider;
+  };
   /** Deployment site URL, or `null` when none is configured/detected. */
   site: string | null;
   structuredData: boolean;

package/src/core/deployment-env.ts

@@ -44,6 +44,15 @@ const PLATFORMS: Platform[] = [
   },
 ];
 
+/**
+ * Adapters whose `deployment.site` arrives from platform env vars at deploy
+ * time. Consumers (e.g. the audit) use this to tell "site is missing" apart
+ * from "site is missing *here*, but the platform will set it".
+ */
+export const SITE_INFERRING_ADAPTERS: ReadonlySet<string> = new Set(
+  PLATFORMS.map((platform) => platform.adapter)
+);
+
 /**
  * Fill in `deployment.adapter` and `deployment.site` from platform env vars
  * (Vercel, Netlify, Cloudflare Pages) when the user hasn't set them. Explicit

package/src/core/diagnostics.ts

@@ -126,17 +126,43 @@ const locatePath = (
   return { column: found - lastNewline, line: before.split("\n").length };
 };
 
-/** Convert a ZodError into Blume diagnostics, anchored to a file. */
-export const diagnosticsFromZod = (
-  error: ZodError,
+/** The YAML front matter block of a `.md`/`.mdx` source, if it has one. */
+const FRONTMATTER = /^---\r?\n(?<body>[\s\S]*?)\r?\n---/u;
+
+/**
+ * Locate a front matter key in a content file, e.g. `["seo", "description"]` in
+ * `docs/api.mdx`. Scoped to the front matter block so a `title:` written in the
+ * page body can't be mistaken for the front matter key of the same name; returns
+ * undefined when the file has no front matter or the key isn't set (a missing
+ * key has no line to point at — callers anchor to the file instead).
+ */
+export const locateFrontmatterKey = (
+  source: string,
+  path: readonly (string | number)[]
+): { column: number; line: number } | undefined => {
+  const block = FRONTMATTER.exec(source);
+  if (!block) {
+    return;
+  }
+  // `locatePath` reports lines 1-based within the text it was given, and the
+  // front matter body starts one line below the opening `---`.
+  const position = locatePath(block.groups?.body ?? "", path);
+  return position && { column: position.column, line: position.line + 1 };
+};
+
+/**
+ * Convert generic validation issues (message + path, the shape shared by Zod
+ * and Standard Schema issues) into Blume diagnostics, anchored to a file.
+ */
+export const diagnosticsFromIssues = (
+  issues: readonly {
+    message: string;
+    path: readonly (string | number)[];
+  }[],
   options: { code: string; file?: string; source?: string }
 ): Diagnostic[] =>
-  error.issues.map((issue) => {
+  issues.map((issue) => {
     const schemaPath = issue.path.join(".");
-    const received =
-      "received" in issue
-        ? ` (received: ${JSON.stringify(issue.received)})`
-        : "";
     const position = options.source
       ? locatePath(options.source, issue.path)
       : undefined;
@@ -145,14 +171,28 @@ export const diagnosticsFromZod = (
       column: position?.column,
       file: options.file,
       line: position?.line,
-      message: schemaPath
-        ? `${schemaPath}: ${issue.message}${received}`
-        : `${issue.message}${received}`,
+      message: schemaPath ? `${schemaPath}: ${issue.message}` : issue.message,
       schemaPath: schemaPath || undefined,
       severity: "error",
     } satisfies Diagnostic;
   });
 
+/** Convert a ZodError into Blume diagnostics, anchored to a file. */
+export const diagnosticsFromZod = (
+  error: ZodError,
+  options: { code: string; file?: string; source?: string }
+): Diagnostic[] =>
+  diagnosticsFromIssues(
+    error.issues.map((issue) => ({
+      message:
+        "received" in issue
+          ? `${issue.message} (received: ${JSON.stringify(issue.received)})`
+          : issue.message,
+      path: issue.path,
+    })),
+    options
+  );
+
 const ESC = String.fromCodePoint(27);
 const COLORS = {
   blue: `${ESC}[34m`,
@@ -184,13 +224,20 @@ export const formatDiagnostic = (
     `${color}${COLORS.bold}${diagnostic.code}${COLORS.reset} ${diagnostic.message}`,
   ];
 
+  // An audit finding is about a built URL, and names the source file that fixes
+  // it as a second line ("at /docs/api" / "in docs/api.mdx:3:2"). Everything
+  // else is about a file alone, and keeps the original single `at file` line.
+  if (diagnostic.url) {
+    lines.push(`  ${COLORS.dim}at ${diagnostic.url}${COLORS.reset}`);
+  }
   if (diagnostic.file) {
     const location = root ? relative(root, diagnostic.file) : diagnostic.file;
     const column =
       diagnostic.column === undefined ? "" : `:${diagnostic.column}`;
     const position =
       diagnostic.line === undefined ? "" : `:${diagnostic.line}${column}`;
-    lines.push(`  ${COLORS.dim}at ${location}${position}${COLORS.reset}`);
+    const label = diagnostic.url ? "in" : "at";
+    lines.push(`  ${COLORS.dim}${label} ${location}${position}${COLORS.reset}`);
   }
 
   if (diagnostic.suggestion) {

package/src/core/links.ts

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { basename, join } from "pathe";
 
 import { stripBasePath, withBasePath } from "./base-path.ts";
+import { gradeExternal, probeAll } from "./probe.ts";
 import type {
   ContentGraph,
   Diagnostic,
@@ -25,13 +26,6 @@ const decodePercent = (value: string): string => {
 const DOC_EXT = /\.(?:md|mdx)$/iu;
 const FILE_EXT = /\.[a-z0-9]+$/iu;
 
-const EXTERNAL_CONCURRENCY = 8;
-const EXTERNAL_TIMEOUT_MS = 10_000;
-const STATUS_NOT_FOUND = 404;
-const STATUS_GONE = 410;
-const STATUS_METHOD_NOT_ALLOWED = 405;
-const STATUS_NOT_IMPLEMENTED = 501;
-
 /** Source position shared by every diagnostic raised for a link. */
 interface LinkSite {
   column: number;
@@ -214,94 +208,11 @@ const checkPathLink = (
   };
 };
 
-/** Probe a URL with the given method, normalizing failures to a result. */
-const request = async (
-  url: string,
-  method: "GET" | "HEAD"
-): Promise<{
-  ok: boolean;
-  status?: number;
-  timedOut?: boolean;
-  error?: string;
-}> => {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), EXTERNAL_TIMEOUT_MS);
-  try {
-    const response = await fetch(url, {
-      method,
-      redirect: "follow",
-      signal: controller.signal,
-    });
-    return { ok: response.ok, status: response.status };
-  } catch (error) {
-    if (error instanceof Error && error.name === "AbortError") {
-      return { ok: false, timedOut: true };
-    }
-    return {
-      error: error instanceof Error ? error.message : String(error),
-      ok: false,
-    };
-  } finally {
-    clearTimeout(timer);
-  }
-};
-
-/** Probe a single URL: HEAD first, falling back to GET when needed. */
-const probe = async (
-  url: string
-): Promise<Awaited<ReturnType<typeof request>>> => {
-  const head = await request(url, "HEAD");
-  const unreachable = !head.ok && head.status === undefined && !head.timedOut;
-  const retry =
-    head.status === STATUS_METHOD_NOT_ALLOWED ||
-    head.status === STATUS_NOT_IMPLEMENTED ||
-    unreachable;
-  return retry ? await request(url, "GET") : head;
-};
-
-/** Grade a probe result into a diagnostic severity + detail, or null if OK. */
-const gradeExternal = (
-  result: Awaited<ReturnType<typeof request>>
-): { severity: Diagnostic["severity"]; detail: string } | null => {
-  if (result.ok) {
-    return null;
-  }
-  if (result.timedOut) {
-    return { detail: "request timed out", severity: "warning" };
-  }
-  if (result.status === undefined) {
-    return { detail: result.error ?? "unreachable", severity: "error" };
-  }
-  if (result.status === STATUS_NOT_FOUND || result.status === STATUS_GONE) {
-    return { detail: `HTTP ${result.status}`, severity: "error" };
-  }
-  return { detail: `HTTP ${result.status}`, severity: "warning" };
-};
-
 /** Probe queued external links with bounded concurrency. */
 const checkExternalLinks = async (
   refs: ExternalRef[]
 ): Promise<Diagnostic[]> => {
-  const unique = [...new Set(refs.map((ref) => ref.url))];
-  const results = new Map<string, Awaited<ReturnType<typeof probe>>>();
-
-  let cursor = 0;
-  const worker = async (): Promise<void> => {
-    while (cursor < unique.length) {
-      const url = unique[cursor];
-      cursor += 1;
-      if (url !== undefined) {
-        // oxlint-disable-next-line no-await-in-loop -- bounded-concurrency pool
-        results.set(url, await probe(url));
-      }
-    }
-  };
-  await Promise.all(
-    Array.from(
-      { length: Math.min(EXTERNAL_CONCURRENCY, unique.length) },
-      worker
-    )
-  );
+  const results = await probeAll(refs.map((ref) => ref.url));
 
   const diagnostics: Diagnostic[] = [];
   for (const ref of refs) {