blume 2.1.3 → 2.2.0

package/src/core/sources/notion.ts

@@ -3,7 +3,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 import pLimit from "p-limit";
 import { join } from "pathe";
 
-import { parseYouTubeId } from "../../components/content/youtube.ts";
+import { youtubeEmbedSrc } from "../../components/content/youtube.ts";
 import { BlumeError } from "../diagnostics.ts";
 import matter from "../frontmatter.ts";
 import { nodeRequire } from "../node-require.ts";
@@ -316,12 +316,13 @@ const FRAME_ESCAPED = /\\(?=[<>])/gu;
 
 const YOUTUBE_HOST = /(?:^|\.)(?:youtube(?:-nocookie)?\.com|youtu\.be)$/u;
 
-// `parseYouTubeId` is host-agnostic on purpose (the component accepts bare
+// `youtubeEmbedSrc` is host-agnostic on purpose (the component accepts bare
 // ids), so gate on the hostname first: `https://cdn.example.com/live/promo.mp4`
-// matches its `/live/<11 chars>` shape but is a media file, not an embed.
+// matches its `/live/<11 chars>` shape but is a media file, not an embed. A
+// playlist URL embeds too.
 const isYouTubeUrl = (url: string): boolean => {
   const host = URL.parse(url)?.hostname ?? "";
-  return YOUTUBE_HOST.test(host) && parseYouTubeId(url) !== null;
+  return YOUTUBE_HOST.test(host) && youtubeEmbedSrc(url) !== null;
 };
 
 /**

package/src/core/sources/obsidian.ts

@@ -9,7 +9,7 @@ import { nextFenceState } from "../code-fences.ts";
 import type { FenceState } from "../code-fences.ts";
 import { BlumeError } from "../diagnostics.ts";
 import matter from "../frontmatter.ts";
-import { pageMetaSchema } from "../schema.ts";
+import { BUILT_IN_PAGE_META_KEYS } from "../schema.ts";
 import type { ResolvedI18nConfig, ResolvedVersionsConfig } from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 import { hashText } from "./cache.ts";
@@ -139,9 +139,6 @@ const OBSIDIAN_NATIVE_KEYS = new Set([
   "tags",
 ]);
 
-/** Every key Blume's page meta schema accepts. */
-const PAGE_META_KEYS = new Set<string>(pageMetaSchema.keyof().options);
-
 /**
  * A note's route input: its locale- and version-stripped path, slugged. Vault
  * filenames are prose (`Getting Started.md`) and the route mapper does not
@@ -759,7 +756,7 @@ const noteToEntry = (
     Object.entries(note.data).filter(
       ([key]) =>
         !OBSIDIAN_NATIVE_KEYS.has(key) &&
-        (PAGE_META_KEYS.has(key) || keep.has(key))
+        (BUILT_IN_PAGE_META_KEYS.has(key) || keep.has(key))
     )
   );
   const merged = title === undefined ? data : { ...data, title };

package/src/core/sources/types.ts

@@ -67,6 +67,16 @@ export interface SourceEntry {
   };
 }
 
+/**
+ * A redirect a source asks for: from a route one of its pages used to have
+ * to the route it has now, both locale-stripped and without `basePath`, as
+ * the page routes its entries map to.
+ */
+export interface SourceRedirect {
+  from: string;
+  to: string;
+}
+
 /** The result of a single `ContentSource.load()` call. */
 export interface SourceLoadResult {
   entries: SourceEntry[];
@@ -80,6 +90,13 @@ export interface SourceLoadResult {
    * beneath user-authored meta files, which always win.
    */
   folderMeta?: Record<string, FolderMeta>;
+  /**
+   * Redirects from routes the source's pages moved off: the OpenAPI source
+   * keeps the URLs earlier releases gave operation pages working. Added to
+   * the config's `redirects` after them, skipping any whose `from` a page or
+   * a configured redirect already owns.
+   */
+  redirects?: SourceRedirect[];
 }
 
 /**

package/src/core/static-files.ts

@@ -0,0 +1,40 @@
+import { statSync } from "node:fs";
+
+import { join } from "pathe";
+
+/**
+ * Whether a root-relative path names a file the site serves outside its pages,
+ * as a static host answers it: a file in `public/`, a `public/` folder's
+ * `index.html` (`/demo` and `/demo/` for `public/demo/index.html`), or one of
+ * the files Blume generates (`generated`, base-less paths like `/llms.txt`;
+ * see `deploy/generated-files.ts`). `publicDir` is `null` when the project has
+ * no `public/` folder, which ships no files then. Paths come decoded, without
+ * `deployment.base`, which a host mounts `public/` under.
+ */
+export const staticFileResolver = (
+  publicDir: string | null,
+  generated: Iterable<string> = []
+): ((path: string) => boolean) => {
+  const files = new Set(generated);
+  return (path) => {
+    const folder = path.endsWith("/");
+    const trimmed = folder ? path.slice(0, -1) : path;
+    if (files.has(trimmed)) {
+      return true;
+    }
+    if (publicDir === null) {
+      return false;
+    }
+    const target = join(publicDir, trimmed);
+    const stat = statSync(target, { throwIfNoEntry: false });
+    if (stat?.isDirectory()) {
+      return (
+        statSync(join(target, "index.html"), {
+          throwIfNoEntry: false,
+        })?.isFile() === true
+      );
+    }
+    // A host answers `/spec.pdf/` with a 404: only a folder takes the slash.
+    return !folder && stat?.isFile() === true;
+  };
+};

package/src/core/static-host.ts

@@ -0,0 +1,125 @@
+/**
+ * What a static host does with the URLs `blume dev` and `blume preview`
+ * would otherwise answer on their own terms. Astro's `trailingSlash: "never"`
+ * has both 404 a slashed URL (`/guide/`), which every host answers: Vercel
+ * redirects it to `/guide`, and the others serve `guide/index.html`. And a
+ * folder of HTML shipped in `public/` (`public/demo/index.html`) is served at
+ * `/demo/`, `/demo` redirecting there, so the relative links inside it
+ * resolve against the folder; the dev server 404s both spellings, and Vite's
+ * preview serves only the slashless one.
+ */
+
+import { statSync } from "node:fs";
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+
+import { join, resolve } from "pathe";
+
+import { stripBasePath } from "./base-path.ts";
+import { trimEnd } from "./trim.ts";
+
+/** How to answer a request ahead of the server's own handlers. */
+export type HostAnswer =
+  | { kind: "redirect"; location: string; status: number }
+  | { kind: "rewrite"; url: string };
+
+/**
+ * The paths Astro keeps out of its trailing-slash handling (`/_astro/`,
+ * `/@vite/`, `/.well-known/`, `//`), and the root.
+ */
+const UNHANDLED_PATH = /^\/(?:[_@./]|$)/u;
+
+/** A request URL's path and its query string, `?` included. */
+const splitUrl = (url: string): { pathname: string; search: string } => {
+  const queryAt = url.search(/[?#]/u);
+  return queryAt === -1
+    ? { pathname: url, search: "" }
+    : { pathname: url.slice(0, queryAt), search: url.slice(queryAt) };
+};
+
+/**
+ * Whether `public/<path>/index.html` exists: a folder of HTML the site ships
+ * as is. `path` is the decoded request path with `deployment.base` stripped.
+ */
+export const publicFolder = (publicDir: string) => {
+  const root = resolve(publicDir);
+  return (path: string): boolean => {
+    const index = join(root, path, "index.html");
+    if (!index.startsWith(`${root}/`)) {
+      return false;
+    }
+    try {
+      return statSync(index).isFile();
+    } catch {
+      return false;
+    }
+  };
+};
+
+/**
+ * How a static host answers a URL's trailing slash, or null to leave the
+ * request alone. A slashed URL redirects to its slashless page, its query
+ * kept, unless it names a public folder, which serves its `index.html`; a
+ * slashless public folder redirects to its slashed URL. `base` is the
+ * normalized `deployment.base`, which the URL carries and `public/` doesn't.
+ * The redirect is a `301`, a `308` for a method a `301` would turn into a
+ * `GET`, as Astro answers on a server-rendered route.
+ */
+export const trailingSlashAnswer = (
+  request: Pick<IncomingMessage, "method" | "url">,
+  base: string,
+  isPublicFolder: (path: string) => boolean
+): HostAnswer | null => {
+  const { pathname, search } = splitUrl(request.url ?? "/");
+  if (UNHANDLED_PATH.test(pathname)) {
+    return null;
+  }
+  let path: string;
+  try {
+    path = decodeURIComponent(stripBasePath(base, pathname));
+  } catch {
+    return null;
+  }
+  const status =
+    request.method === "GET" || request.method === "HEAD" ? 301 : 308;
+  if (!pathname.endsWith("/")) {
+    return isPublicFolder(path)
+      ? { kind: "redirect", location: `${pathname}/${search}`, status }
+      : null;
+  }
+  const slashless = trimEnd(pathname, "/");
+  return isPublicFolder(trimEnd(path, "/"))
+    ? { kind: "rewrite", url: `${slashless}/index.html${search}` }
+    : { kind: "redirect", location: `${slashless}${search}`, status };
+};
+
+/**
+ * Answer every request on `server` with `answer` first: a redirect is sent
+ * then and there, and a rewrite changes the URL the server's own handlers
+ * (Vite's middleware) then see. They're the request listeners the server
+ * already has, so this goes ahead of every middleware, Astro's included.
+ */
+export const answerRequestsFirst = (
+  server: Server,
+  answer: (request: IncomingMessage) => HostAnswer | null,
+  headers: Record<string, string> = {}
+): void => {
+  const handlers = server.listeners("request");
+  server.removeAllListeners("request");
+  server.on("request", (request: IncomingMessage, response: ServerResponse) => {
+    const answered = answer(request);
+    if (answered?.kind === "redirect") {
+      response.writeHead(answered.status, {
+        ...headers,
+        Location: answered.location,
+      });
+      response.end();
+      return;
+    }
+    if (answered) {
+      request.url = answered.url;
+    }
+    for (const handler of handlers) {
+      handler.call(server, request, response);
+    }
+  });
+};

package/src/core/svg-images.ts

@@ -0,0 +1,98 @@
+import { readFile } from "node:fs/promises";
+
+import { imageMetadata } from "astro/assets/utils";
+import { dirname, extname } from "pathe";
+
+import { contentAssetParam, contentAssetUrl } from "./content-assets.ts";
+import { resolveRelativeImage } from "./relative-files.ts";
+import type { Diagnostic, PageRecord } from "./types.ts";
+
+/**
+ * Colocated SVGs Astro's image pipeline can't measure. Astro reads an image's
+ * size before it optimizes it, and for an SVG it looks for the `<svg>` tag in
+ * the file's first 1,000 bytes only, then needs a width and height or a
+ * viewBox on that tag. A draw.io export carries its whole diagram in a
+ * `content` attribute on the tag, which pushes the tag's end past that
+ * window, so one diagram fails the build (`NoImageMetadata`). Blume serves
+ * such an SVG as it is instead, from the endpoint that already serves content
+ * images to agents (`/blume-assets/content/…`), and warns about it
+ * (`BLUME_SVG_UNOPTIMIZED`). A browser draws an SVG at any size, so the
+ * only loss is the intrinsic `width`/`height` the optimized `<img>` carries.
+ */
+
+/** Whether the file at `path` is an SVG Astro can't read the size of. */
+export const isUnmeasurableSvg = async (path: string): Promise<boolean> => {
+  if (extname(path).toLowerCase() !== ".svg") {
+    return false;
+  }
+  let data: Buffer;
+  try {
+    data = await readFile(path);
+  } catch {
+    return false;
+  }
+  try {
+    await imageMetadata(data, path);
+    return false;
+  } catch {
+    return true;
+  }
+};
+
+/**
+ * The URL an unmeasurable SVG is served at, unbased (the base links plugin
+ * mounts `deployment.base`), or null when `target` isn't a colocated image
+ * Astro can measure no size for.
+ */
+export const unmeasurableSvgUrl = async (
+  sourceDir: string,
+  target: string,
+  projectRoot: string
+): Promise<string | null> => {
+  const abs = resolveRelativeImage(sourceDir, target);
+  if (!(abs && (await isUnmeasurableSvg(abs)))) {
+    return null;
+  }
+  return contentAssetUrl(contentAssetParam(projectRoot, abs));
+};
+
+/**
+ * A warning for each image embed of a colocated SVG Astro can't measure, at
+ * the line that embeds it (in a partial, when an `<include>` brought it in).
+ */
+export const unmeasurableSvgDiagnostics = async (
+  pages: readonly PageRecord[]
+): Promise<Diagnostic[]> => {
+  const seen = new Set<string>();
+  const embeds = pages.flatMap((page) => {
+    const { sourcePath } = page;
+    if (!sourcePath) {
+      return [];
+    }
+    return page.links.flatMap((link) => {
+      const file = link.file ?? sourcePath;
+      const key = `${file}:${link.line}:${link.column}`;
+      if (!link.image || seen.has(key)) {
+        return [];
+      }
+      seen.add(key);
+      const abs = resolveRelativeImage(dirname(sourcePath), link.target);
+      return abs ? [{ abs, file, link }] : [];
+    });
+  });
+  const found = await Promise.all(
+    embeds.map(async (embed) =>
+      (await isUnmeasurableSvg(embed.abs)) ? [embed] : []
+    )
+  );
+  return found.flat().map(({ file, link }) => ({
+    code: "BLUME_SVG_UNOPTIMIZED",
+    column: link.column,
+    file,
+    line: link.line,
+    message: `\`${link.target}\` is served as it is, not optimized: Astro can't read its size, which takes the whole \`<svg>\` tag within the file's first 1,000 bytes, with a width and height or a viewBox.`,
+    severity: "warning",
+    suggestion:
+      "The image still shows. To have it optimized, put the `<svg>` tag's width and height (or viewBox) near the start of the file. In a draw.io export, the `content` attribute pushes them out: export without a copy of the diagram, or remove that attribute.",
+  }));
+};