blume 1.6.4 → 1.6.6

package/src/core/api-name.ts

@@ -0,0 +1,18 @@
+/**
+ * Whether a name already reads as an API's name: it contains `API` or `APIs`
+ * as a whole word, anywhere. Word-bounded on both sides, so "OpenAPI" and
+ * "AsyncAPI" are product names rather than API names and still take the
+ * suffix; unanchored at the end, so "Petstore API v2" is left alone too.
+ */
+const NAMES_AN_API = /\bAPIs?\b/iu;
+
+/**
+ * `name` as the phrase "the ___" in generated prose — the spec title or
+ * reference label, followed by ` API` unless it already says so. Keeps
+ * "Petstore" reading as "Petstore API" without turning "Petstore API" into
+ * "Petstore API API".
+ */
+export const apiNamePhrase = (name: string): string => {
+  const trimmed = name.trim();
+  return NAMES_AN_API.test(trimmed) ? trimmed : `${trimmed} API`;
+};

package/src/core/code-fences.ts

@@ -0,0 +1,48 @@
+/**
+ * Fenced-code state for line scanners. Kept free of imports so request-time
+ * code (the Ask AI grounding excerpts) can share it with the build-time source
+ * scanners without pulling the filesystem and schema modules along.
+ *
+ * CommonMark allows backtick *and* tilde fences, three or more characters
+ * long. The scanners track which delimiter opened the current fence and how
+ * long its run was (`null` when outside one), so a ``` line inside a ~~~
+ * block — or inside a ````-delimited block (the wrapper `codeBlockLines`
+ * emits around code that contains its own ``` fence) — is content, not a
+ * toggle.
+ */
+const CODE_FENCE = /^(?<run>`{3,}|~{3,})/u;
+
+/** The open fence's delimiter char and run length, or null outside one. */
+export type FenceState = { delimiter: "`" | "~"; length: number } | null;
+
+/**
+ * Advance the fenced-code state for one line: an opening fence records its
+ * delimiter and run length, only a bare run of the same character at least as
+ * long closes it (CommonMark), and any other line leaves the state untouched.
+ */
+export const nextFenceState = (line: string, fence: FenceState): FenceState => {
+  const trimmed = line.trimStart();
+  const run = trimmed.match(CODE_FENCE)?.groups?.run;
+  if (run === undefined) {
+    return fence;
+  }
+  const rest = trimmed.slice(run.length);
+  const delimiter = run.startsWith("`") ? ("`" as const) : ("~" as const);
+  if (fence === null) {
+    // A backtick fence's info string cannot itself contain a backtick
+    // (CommonMark) — a line-leading ```inline``` span is a paragraph, and
+    // opening a phantom fence on it would swallow every heading and link
+    // after it. Tilde fences carry no such rule.
+    if (delimiter === "`" && rest.includes("`")) {
+      return fence;
+    }
+    return { delimiter, length: run.length };
+  }
+  // A closing fence may be followed only by whitespace: a same-length
+  // ```js line inside an open ``` block is content, not a closer.
+  return fence.delimiter === delimiter &&
+    run.length >= fence.length &&
+    rest.trim() === ""
+    ? null
+    : fence;
+};

package/src/core/config-input.ts

@@ -895,6 +895,16 @@ export interface AnalyticsScript {
 
 /** Analytics providers. Configure one, several, or none. */
 export interface AnalyticsConfig {
+  /**
+   * Cloudflare Web Analytics, for a site Cloudflare doesn't proxy (manual
+   * setup). Not needed on a proxied zone with automatic RUM enabled — that
+   * injects the beacon at the edge, and configuring it here too would count
+   * every pageview twice.
+   */
+  cloudflare?: {
+    /** Site token from the Web Analytics JS snippet (`data-cf-beacon`). */
+    token: string;
+  };
   /** PostHog product analytics. */
   posthog?: {
     /** API host (for self-hosted / EU). Defaults to PostHog cloud. */

package/src/core/content-assets.ts

@@ -11,14 +11,10 @@ import {
 } from "pathe";
 
 import { normalizeBasePath } from "./base-path.ts";
+import { nextFenceState } from "./code-fences.ts";
+import type { FenceState } from "./code-fences.ts";
 import { hashText } from "./sources/cache.ts";
-import type { FenceState } from "./sources/normalize.ts";
-import {
-  INLINE_CODE,
-  MD_IMAGE,
-  nextFenceState,
-  targetOffsetIn,
-} from "./sources/normalize.ts";
+import { INLINE_CODE, MD_IMAGE, targetOffsetIn } from "./sources/normalize.ts";
 import { readExpandedEntryText } from "./sources/read.ts";
 import type { ContentSource } from "./sources/types.ts";
 import type { PageRecord } from "./types.ts";

package/src/core/includes.ts

@@ -2,14 +2,10 @@ import { readFile } from "node:fs/promises";
 
 import { dirname, extname, join, relative, resolve } from "pathe";
 
+import { nextFenceState } from "./code-fences.ts";
+import type { FenceState } from "./code-fences.ts";
 import matter from "./frontmatter.ts";
-import type { FenceState } from "./sources/normalize.ts";
-import {
-  INLINE_CODE,
-  MD_IMAGE,
-  nextFenceState,
-  targetOffsetIn,
-} from "./sources/normalize.ts";
+import { INLINE_CODE, MD_IMAGE, targetOffsetIn } from "./sources/normalize.ts";
 import type { Diagnostic } from "./types.ts";
 
 /**

package/src/core/package-root.ts

@@ -28,7 +28,7 @@ let cached: string | undefined;
  * Anchoring here — rather than at a fixed offset from `import.meta` — keeps the
  * package's own `src/`, assets, and `node_modules` locatable whether the code
  * runs from source under Bun (`src/...`) or from the published, bundled CLI
- * (`dist/cli/index.js`). The two layouts sit at different depths, so a relative
+ * (`dist/cli/*.js`). The two layouts sit at different depths, so a relative
  * `../..` resolves to different places; locating `package.json` does not.
  */
 export const packageRoot = (): string => {

package/src/core/schema.ts

@@ -176,6 +176,25 @@ export const pageMetaSchema = pageMetaBaseSchema;
 export type PageMeta = z.infer<typeof pageMetaBaseSchema>;
 export type PageMetaInput = z.input<typeof pageMetaBaseSchema>;
 
+/** The fully-defaulted front matter of a page that declares nothing. */
+const EMPTY_PAGE_META: PageMeta = pageMetaBaseSchema.parse({});
+
+/**
+ * The page schema as the generated content collections declare it, so
+ * `entry.data` is typed and normalized (dates as ISO strings, X handles with
+ * their `@`) the same way the scan's `PageMeta` is. Two deliberate loosenings
+ * over {@link pageMetaSchema}: custom keys (`frontmatter.extend`, per-type
+ * maps) pass through instead of failing the strict parse, and a page the
+ * strict parse rejects resolves to the empty defaults instead of throwing.
+ * The scan has already dropped such a page with a `BLUME_FRONTMATTER_INVALID`
+ * diagnostic — Blume continues without it unless `--strict` — so the
+ * collection must not turn that dropped page into a failed content sync.
+ */
+export const pageCollectionSchema = pageMetaBaseSchema
+  .loose()
+  // oxlint-disable-next-line promise/prefer-await-to-then -- zod's catch, not a promise
+  .catch(() => EMPTY_PAGE_META);
+
 /** Built-in page frontmatter keys; custom keys must never redeclare one. */
 const BUILT_IN_PAGE_META_KEYS = new Set<string>(
   pageMetaBaseSchema.keyof().options
@@ -1220,6 +1239,14 @@ const analyticsScriptSchema = z
   });
 
 const analyticsConfigSchema = z.strictObject({
+  // Cloudflare Web Analytics in manual (JS snippet) mode; the token comes from
+  // the site's snippet in the dashboard. A zone Cloudflare proxies with
+  // automatic RUM injection on needs no config at all.
+  cloudflare: z
+    .strictObject({
+      token: z.string().min(1),
+    })
+    .optional(),
   posthog: z
     .strictObject({
       host: z.string().optional(),

package/src/core/sources/normalize.ts

@@ -4,6 +4,8 @@ import GithubSlugger from "github-slugger";
 import { extname } from "pathe";
 
 import { withBasePath } from "../base-path.ts";
+import { nextFenceState } from "../code-fences.ts";
+import type { FenceState } from "../code-fences.ts";
 import { diagnosticsFromIssues, diagnosticsFromZod } from "../diagnostics.ts";
 import { occupySlug, parseHeadingMarkers } from "../heading-markers.ts";
 import { localePlacement, localizeRoute } from "../i18n.ts";
@@ -139,43 +141,6 @@ const mapRoute = (relativePath: string): MappedRoute => {
   return { groups, route, segments };
 };
 
-// CommonMark allows backtick *and* tilde fences, three or more characters
-// long. The scanners track which delimiter opened the current fence and how
-// long its run was (`null` when outside one), so a ``` line inside a ~~~
-// block — or inside a ````-delimited block (the wrapper `codeBlockLines`
-// emits around code that contains its own ``` fence) — is content, not a
-// toggle. See `nextFenceState`.
-const CODE_FENCE = /^(?<run>`{3,}|~{3,})/u;
-
-/** The open fence's delimiter char and run length, or null outside one. */
-export type FenceState = { delimiter: "`" | "~"; length: number } | null;
-
-/**
- * Advance the fenced-code state for one line: an opening fence records its
- * delimiter and run length, only a run of the same character at least as long
- * closes it (CommonMark), and any other line leaves the state untouched.
- */
-export const nextFenceState = (line: string, fence: FenceState): FenceState => {
-  const trimmed = line.trimStart();
-  const run = trimmed.match(CODE_FENCE)?.groups?.run;
-  if (run === undefined) {
-    return fence;
-  }
-  const delimiter = run.startsWith("`") ? ("`" as const) : ("~" as const);
-  if (fence === null) {
-    // A backtick fence's info string cannot itself contain a backtick
-    // (CommonMark) — a line-leading ```inline``` span is a paragraph, and
-    // opening a phantom fence on it would swallow every heading and link
-    // after it. Tilde fences carry no such rule.
-    if (delimiter === "`" && trimmed.slice(run.length).includes("`")) {
-      return fence;
-    }
-    return { delimiter, length: run.length };
-  }
-  return fence.delimiter === delimiter && run.length >= fence.length
-    ? null
-    : fence;
-};
 // A closing hash sequence must be preceded by whitespace (CommonMark), so a
 // heading like `## What is C#` keeps its trailing `#`. Up to 3 leading spaces
 // are allowed; 4+ is an indented code block.

package/src/core/sources/obsidian.ts

@@ -4,18 +4,19 @@ import { readdir, readFile, stat } from "node:fs/promises";
 
 import { basename, isAbsolute, join, relative, resolve } from "pathe";
 
+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 type { ResolvedI18nConfig, ResolvedVersionsConfig } from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 import { hashText } from "./cache.ts";
-import type { EntryPlacement, FenceState } from "./normalize.ts";
+import type { EntryPlacement } from "./normalize.ts";
 import {
   extractHeadings,
   isStringValue,
   localizedRoute,
-  nextFenceState,
   placeEntryRef,
   resolveEntryRoute,
   slugifyPath,

package/src/core/svg-dimensions.ts

@@ -0,0 +1,97 @@
+/**
+ * Pixel dimensions declared by an SVG document's root element.
+ *
+ * Blume needs an SVG's size in two places — the header logo's reserved
+ * `<img>` box and the OG card's brand mark — and both read it through this
+ * one parser so the header and the card can't disagree about one logo. It
+ * inspects the root `<svg …>` tag only: explicit `width`/`height` win, a
+ * `viewBox` fills in whatever is missing (scaled to a lone explicit length
+ * when there is one), and lengths carry CSS units at 96dpi. Percentages have
+ * no pixel meaning and are ignored, so a percent-sized SVG measures by its
+ * viewBox alone.
+ */
+export interface SvgDimensions {
+  height: number;
+  width: number;
+}
+
+/** The root tag, tolerating `>` inside a quoted attribute value. */
+const ROOT = /<svg\s(?:[^>"']|"[^"]*"|'[^']*')*>/u;
+const WIDTH = /\swidth=(?<quote>['"])(?<value>[^%]+?)\k<quote>/u;
+const HEIGHT = /\sheight=(?<quote>['"])(?<value>[^%]+?)\k<quote>/u;
+const VIEWBOX = /\sviewBox=(?<quote>['"])(?<value>.+?)\k<quote>/iu;
+
+/** Pixels per CSS unit at 96dpi; an omitted unit means pixels. */
+const INCH_CM = 2.54;
+const UNITS = new Map([
+  ["cm", 96 / INCH_CM],
+  ["em", 16],
+  ["ex", 8],
+  ["in", 96],
+  ["m", (96 / INCH_CM) * 100],
+  ["mm", 96 / INCH_CM / 10],
+  ["pc", (96 / 72) * 12],
+  ["pt", 96 / 72],
+  ["px", 1],
+]);
+const LENGTH =
+  /^(?<number>[0-9.]+(?:e\d+)?)(?<unit>in|cm|em|ex|m|mm|pc|pt|px)?$/u;
+
+/** A CSS length as whole pixels, or undefined when it isn't one. */
+const parseLength = (value: string | undefined): number | undefined => {
+  const groups = value === undefined ? undefined : LENGTH.exec(value)?.groups;
+  if (!groups) {
+    return;
+  }
+  const pixels = Math.round(
+    Number(groups.number) * (UNITS.get(groups.unit ?? "px") ?? 1)
+  );
+  return pixels > 0 ? pixels : undefined;
+};
+
+/** An attribute's raw value on the root tag, or undefined when absent. */
+const attribute = (root: string, pattern: RegExp): string | undefined =>
+  pattern.exec(root)?.groups?.value;
+
+/** The viewBox's own width and height (its third and fourth numbers). */
+const viewBoxSize = (root: string): SvgDimensions | null => {
+  const raw = attribute(root, VIEWBOX);
+  if (raw === undefined) {
+    return null;
+  }
+  const bounds = raw.split(" ");
+  const width = parseLength(bounds[2]);
+  const height = parseLength(bounds[3]);
+  return width && height ? { height, width } : null;
+};
+
+/**
+ * The SVG's pixel size, or null when the root carries no usable size: no
+ * root tag, neither explicit dimensions nor a viewBox, a viewBox that isn't
+ * space-separated, or a zero or unparsable length.
+ */
+export const svgDimensions = (svg: string): SvgDimensions | null => {
+  const root = ROOT.exec(svg)?.[0];
+  if (root === undefined) {
+    return null;
+  }
+  const width = parseLength(attribute(root, WIDTH));
+  const height = parseLength(attribute(root, HEIGHT));
+  if (width && height) {
+    return { height, width };
+  }
+  const box = viewBoxSize(root);
+  if (!box) {
+    return null;
+  }
+  const ratio = box.width / box.height;
+  if (width) {
+    const scaled = Math.floor(width / ratio);
+    return scaled > 0 ? { height: scaled, width } : null;
+  }
+  if (height) {
+    const scaled = Math.floor(height * ratio);
+    return scaled > 0 ? { height, width: scaled } : null;
+  }
+  return box;
+};

package/src/core/version-cut.ts

@@ -4,13 +4,13 @@ import { cp, readdir, readFile, rm } from "node:fs/promises";
 import { join, relative } from "pathe";
 
 import { stripBasePath } from "./base-path.ts";
+import { nextFenceState } from "./code-fences.ts";
+import type { FenceState } from "./code-fences.ts";
 import { writeTextAtomic } from "./fs-atomic.ts";
 import { localizeRoute } from "./i18n.ts";
 import type { BlumeProject } from "./project-graph.ts";
 import { isWithin, scanProject } from "./project-graph.ts";
 import { VERSION_ID } from "./schema.ts";
-import { nextFenceState } from "./sources/normalize.ts";
-import type { FenceState } from "./sources/normalize.ts";
 import { VERSION_LIKE, versionizeRoute } from "./versions.ts";
 
 /** What `cutVersion` did, for the CLI to report. */