blume 1.3.1 → 1.4.1

package/src/eval/report.ts

@@ -1,23 +1,14 @@
 import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 
+import { colors } from "consola/utils";
+import type { ColorFunction } from "consola/utils";
 import { join, relative } from "pathe";
 
 import { AGENTS } from "../audit/agent.ts";
 import { countBySeverity } from "../core/diagnostics.ts";
 import type { EvalResult, QuestionResult, QuestionStatus } from "./run.ts";
 
-const ESC = String.fromCodePoint(27);
-const COLORS = {
-  bold: `${ESC}[1m`,
-  cyan: `${ESC}[36m`,
-  dim: `${ESC}[2m`,
-  green: `${ESC}[32m`,
-  red: `${ESC}[31m`,
-  reset: `${ESC}[0m`,
-  yellow: `${ESC}[33m`,
-};
-
 const GLYPH: Record<QuestionStatus, string> = {
   error: "!",
   fail: "✖",
@@ -25,11 +16,11 @@ const GLYPH: Record<QuestionStatus, string> = {
   skip: "⊘",
 };
 
-const STATUS_COLOR: Record<QuestionStatus, string> = {
-  error: COLORS.yellow,
-  fail: COLORS.red,
-  pass: COLORS.green,
-  skip: COLORS.dim,
+const STATUS_COLOR: Record<QuestionStatus, ColorFunction> = {
+  error: colors.yellow,
+  fail: colors.red,
+  pass: colors.green,
+  skip: colors.dim,
 };
 
 /** Longest id gets the room; everything shorter aligns to it. */
@@ -52,17 +43,18 @@ const duration = (ms: number): string => {
 /** One question's progress/report line: glyph, id, status, score, time, cost. */
 export const questionLine = (result: QuestionResult): string => {
   const color = STATUS_COLOR[result.status];
-  const glyph = `${color}${GLYPH[result.status]}${COLORS.reset}`;
+  const glyph = color(GLYPH[result.status]);
   const id = result.id.padEnd(ID_PAD);
   if (result.status === "skip") {
-    return `  ${glyph} ${id} ${COLORS.dim}skipped${COLORS.reset}`;
+    return `  ${glyph} ${id} ${colors.dim("skipped")}`;
   }
   const score = result.score === undefined ? "" : result.score.toFixed(2);
+  const cost = money(result.costUsd);
   const cells = [
-    `${color}${result.status}${COLORS.reset}`,
+    color(result.status),
     score,
-    `${COLORS.dim}${seconds(result.durationMs)}${COLORS.reset}`,
-    `${COLORS.dim}${money(result.costUsd)}${COLORS.reset}`,
+    colors.dim(seconds(result.durationMs)),
+    cost === "" ? "" : colors.dim(cost),
   ]
     .filter((cell) => cell !== "")
     .join("  ");
@@ -77,17 +69,17 @@ export const questionDetails = (
   const lines: string[] = [];
   if (result.status === "fail") {
     for (const fact of result.missing) {
-      lines.push(`      ${COLORS.dim}missing: ${fact}${COLORS.reset}`);
+      lines.push(`      ${colors.dim(`missing: ${fact}`)}`);
     }
   }
   if (result.status === "error" && result.detail) {
-    lines.push(`      ${COLORS.dim}${result.detail}${COLORS.reset}`);
+    lines.push(`      ${colors.dim(result.detail)}`);
   }
   if (verbose && result.answer && result.status !== "pass") {
     lines.push(
       ...result.answer
         .split("\n")
-        .map((line) => `      ${COLORS.dim}> ${line}${COLORS.reset}`)
+        .map((line) => `      ${colors.dim(`> ${line}`)}`)
     );
   }
   return lines;
@@ -109,11 +101,11 @@ export const summaryLine = (result: EvalResult): string => {
 
 /** The header line the command prints before the first question runs. */
 export const headerLine = (total: number, agent: EvalResult["agent"]): string =>
-  `${COLORS.bold}blume eval${COLORS.reset}  ${total} question(s) · ${AGENTS[agent].name}`;
+  `${colors.bold("blume eval")}  ${total} question(s) · ${AGENTS[agent].name}`;
 
 /** The dim announce line while a question's agents run. */
 export const startLine = (id: string, index: number, total: number): string =>
-  `  ${COLORS.dim}▸ ${id} (${index + 1}/${total})${COLORS.reset}`;
+  `  ${colors.dim(`▸ ${id} (${index + 1}/${total})`)}`;
 
 /** `fix:` pointers for failed questions, naming the file that resolves each. */
 export const fixLines = (result: EvalResult, root: string): string[] =>
@@ -123,7 +115,7 @@ export const fixLines = (result: EvalResult, root: string): string[] =>
       const site = finding.file
         ? `${relative(root, finding.file)}${finding.line ? `:${finding.line}` : ""}`
         : "";
-      return `  ${COLORS.cyan}fix:${COLORS.reset} ${site} ${COLORS.dim}${finding.message}${COLORS.reset}`;
+      return `  ${colors.cyan("fix:")} ${site} ${colors.dim(finding.message)}`;
     });
 
 /** Dim warnings for route hints that no longer match a page. */
@@ -134,7 +126,7 @@ export const warningLines = (result: EvalResult, root: string): string[] =>
       const site = finding.file
         ? ` ${relative(root, finding.file)}${finding.line ? `:${finding.line}` : ""}`
         : "";
-      return `  ${COLORS.yellow}⚠${COLORS.reset}${site} ${COLORS.dim}${finding.message}${COLORS.reset}`;
+      return `  ${colors.yellow("⚠")}${site} ${colors.dim(finding.message)}`;
     });
 
 /** The human report, written to stderr by the command. */

package/src/markdown/directives.ts

@@ -1,3 +1,5 @@
+import { toString as mdastToString } from "mdast-util-to-string";
+
 import { jsxAttribute, jsxFlowElement } from "./mdast.ts";
 import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
 
@@ -35,23 +37,6 @@ export const calloutTypeFor = (name: string): string | null => {
   return ALIASES[lower] ?? null;
 };
 
-interface TextNode extends MdastNode {
-  value?: string;
-}
-
-/**
- * Concatenate the plain text of a node, recursing through phrasing children so
- * formatted labels keep every word — `:::note[Read **this**]` yields
- * `Read this`, not `Read ` (the bolded run dropped).
- */
-const textOf = (node: MdastNode): string => {
-  const { children } = node as { children?: MdastNode[] };
-  if (children && children.length > 0) {
-    return children.map(textOf).join("");
-  }
-  return (node as TextNode).value ?? "";
-};
-
 /**
  * Satteri MDAST plugin mapping container directives (`:::note`, `:::warning`,
  * `:::tip`, …) onto Blume's `<Callout>` component. The title comes from a
@@ -77,7 +62,10 @@ export const directiveToCalloutPlugin = () => ({
     if (labelIndex !== -1) {
       const [label] = children.splice(labelIndex, 1);
       if (label) {
-        title ??= textOf(label) || undefined;
+        // Flatten the label's phrasing children so `:::note[Read **this**]`
+        // yields `Read this`; image alt is excluded (an image is not label
+        // text), matching the historical child-values-only behavior.
+        title ??= mdastToString(label, { includeImageAlt: false }) || undefined;
       }
     }
 

package/src/markdown/index.ts

@@ -6,6 +6,7 @@ import {
   transformerNotationHighlight,
   transformerNotationWordHighlight,
 } from "@shikijs/transformers";
+import { escape as escapeHtml } from "html-escaper";
 import { codeToHtml } from "shiki";
 
 import { baseLinksPlugin } from "./base-links.ts";
@@ -107,12 +108,6 @@ export const blumeShikiTransformers = (
   return transformers;
 };
 
-const escapeHtml = (value: string): string =>
-  value
-    .replaceAll("&", "&")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;");
-
 /**
  * Tag the highlighted `<pre>` with `astro-code` (plus any extra classes) so the
  * theme's code-block styles apply — `codeToHtml`'s bare output is `pre.shiki`,

package/src/markdown/package-commands.ts

@@ -79,10 +79,6 @@ const normalizeFlags = (args: string[]): string[] =>
  */
 const parseIntent = (input: string): Intent => {
   const tokens = input.trim().split(WHITESPACE).filter(Boolean);
-  if (tokens.length === 0) {
-    return { args: [], operation: "install" };
-  }
-
   const [first, ...rest] = tokens;
   if (first === undefined) {
     return { args: [], operation: "install" };

package/src/openapi/parse.ts

@@ -150,16 +150,18 @@ const fetchSpecText = async (spec: string): Promise<string> => {
     if ("text" in last) {
       return last.text;
     }
-    if (!last.retryable || attempt === MAX_ATTEMPTS - 1) {
-      throw last.error;
+    if (!last.retryable) {
+      break;
+    }
+    if (attempt < MAX_ATTEMPTS - 1) {
+      // oxlint-disable-next-line no-await-in-loop -- back off before retrying
+      await sleep(
+        Math.min(
+          last.retryAfter ?? BASE_BACKOFF_MS * 2 ** attempt,
+          MAX_RETRY_WAIT_MS
+        )
+      );
     }
-    // oxlint-disable-next-line no-await-in-loop -- back off before retrying
-    await sleep(
-      Math.min(
-        last.retryAfter ?? BASE_BACKOFF_MS * 2 ** attempt,
-        MAX_RETRY_WAIT_MS
-      )
-    );
   }
   throw last.error;
 };

package/src/search/documents.ts

@@ -5,6 +5,7 @@ import { contentIndexable } from "../core/manifest.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { NavNode } from "../core/types.ts";
+import { pageFacets } from "./facets.ts";
 
 /** A document indexed by the client-side search providers (Orama, FlexSearch). */
 export interface SearchDocument {
@@ -18,8 +19,15 @@ export interface SearchDocument {
   section: string;
   /** Locale code, so the dialog can filter results to the active language. */
   locale: string;
+  /** Resolved page `type` (`doc`, `blog`, a custom `rfc`…), for type filters. */
+  contentType: string;
   /** Frontmatter `search.tags`, surfaced for hosted-provider faceting. */
   tags?: string[];
+  /**
+   * Declared facet values (`content.types.<type>.facets`), key → value.
+   * Filterable through the MCP tools' `filters` input.
+   */
+  facets?: Record<string, string>;
 }
 
 /**
@@ -193,10 +201,13 @@ export const buildSearchDocuments = async (
         options?.content === "markdown" ? visible.trim() : toPlainText(visible);
       const tags = page?.meta?.search?.tags;
       const crumb = crumbs.get(route.path);
+      const facets = page ? pageFacets(page, project.config) : undefined;
       return {
         breadcrumb: crumb?.breadcrumb ?? [],
         content: body,
+        contentType: route.contentType,
         description: page?.description ?? "",
+        ...(facets ? { facets } : {}),
         locale: route.locale,
         route: route.path,
         section: crumb?.section || "Docs",

package/src/search/facets.ts

@@ -0,0 +1,33 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { PageRecord } from "../core/types.ts";
+
+/**
+ * Resolve a page's facet values: the subset of its validated custom
+ * frontmatter named by its content type's `facets` declaration. Strings facet
+ * as-is; numbers and booleans are stringified so an enum-like `priority: 1`
+ * or `enforced: true` still filters; any other shape (objects, arrays,
+ * transformed dates) is not a facet value and is skipped. Returns `undefined`
+ * when nothing facets, so the field stays absent from serialized documents
+ * rather than shipping as `{}` on every page.
+ */
+export const pageFacets = (
+  page: Pick<PageRecord, "contentType" | "custom">,
+  config: ResolvedConfig
+): Record<string, string> | undefined => {
+  const declared = config.content.types[page.contentType]?.facets;
+  if (!declared || declared.length === 0 || !page.custom) {
+    return;
+  }
+  const facets: Record<string, string> = {};
+  for (const key of declared) {
+    const value = page.custom[key];
+    if (
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      facets[key] = String(value);
+    }
+  }
+  return Object.keys(facets).length > 0 ? facets : undefined;
+};

package/src/search/orama-index.ts

@@ -13,6 +13,10 @@ export interface OramaDoc {
   title: string;
   /** Locale code; indexed as an enum so queries can filter to one language. */
   locale?: string;
+  /** Resolved page `type`; indexed as an enum so queries can filter by type. */
+  contentType?: string;
+  /** Declared facet values (`content.types.<type>.facets`), key → value. */
+  facets?: Record<string, string>;
   /** Carried through for the search dialog's breadcrumb + filter pills. Stored
    * but not indexed, so they ride along on the returned document untouched. */
   breadcrumb?: string[];
@@ -21,13 +25,22 @@ export interface OramaDoc {
 
 const SCHEMA = {
   content: "string",
+  // Enums (not full-text "string") so `where` does an exact-match filter.
+  contentType: "enum",
   description: "string",
-  // Enum (not full-text "string") so `where` does an exact-match filter.
+  // Facets, flattened to `key:value` terms — enum[] so one static schema
+  // serves every project's facet keys, with `containsAll` matching a filter
+  // set. Derived from `facets` at insert time.
+  facetTerms: "enum[]",
   locale: "enum",
   route: "string",
   title: "string",
 } as const;
 
+/** Flatten a facet map to the `key:value` terms the `facetTerms` enum holds. */
+const toFacetTerms = (facets: Record<string, string>): string[] =>
+  Object.entries(facets).map(([key, value]) => `${key}:${value}`);
+
 /** Title and description outrank body text, matching the search dialog. */
 const BOOST = { description: 2, title: 3 };
 
@@ -169,17 +182,36 @@ export const buildOramaIndex = async (
     schema: SCHEMA,
     ...(tokenizer ? { components: { tokenizer } } : {}),
   });
-  await insertMultiple(db, documents);
+  await insertMultiple(
+    db,
+    documents.map((doc) =>
+      doc.facets ? { ...doc, facetTerms: toFacetTerms(doc.facets) } : doc
+    )
+  );
   return db;
 };
 
 /** Orama keeps only documents matching every token at a threshold of 0. */
 const ALL_TOKENS = 0;
 
+/** Optional exact-match filters applied to a query via Orama's `where`. */
+export interface OramaQueryFilters {
+  /** Keep only documents whose `contentType` is in this list. */
+  contentTypes?: string[];
+  /**
+   * Keep only documents matching every facet, key → required value. Facet
+   * keys and values come from the `facets` field on the indexed documents.
+   */
+  facets?: Record<string, string>;
+  /** Keep only documents in this locale. */
+  locale?: string;
+}
+
 /**
  * Query the index, returning the matching documents (highest-ranked first).
- * When `locale` is given, results are filtered to that language via an exact
- * `where` match on the `locale` enum.
+ * `filters` narrows results by exact `where` matches on the enum fields:
+ * `locale` to one language, `contentTypes` to a set of page types, `facets`
+ * to documents carrying every requested `key:value` term.
  *
  * On a bigrammed index the strict pass runs first: a term is only meant to
  * match where its bigrams sit together, and scoring them independently lets a
@@ -191,14 +223,24 @@ export const queryOramaIndex = async (
   db: AnyOrama,
   term: string,
   limit: number,
-  locale?: string
+  filters?: OramaQueryFilters
 ): Promise<OramaDoc[]> => {
+  const facetTerms = filters?.facets ? toFacetTerms(filters.facets) : [];
+  const where = {
+    ...(filters?.locale ? { locale: { eq: filters.locale } } : {}),
+    ...(filters?.contentTypes && filters.contentTypes.length > 0
+      ? { contentType: { in: filters.contentTypes } }
+      : {}),
+    ...(facetTerms.length > 0
+      ? { facetTerms: { containsAll: facetTerms } }
+      : {}),
+  };
   const params = {
     boost: BOOST,
     limit,
     properties: ["title", "description", "content"],
     term,
-    ...(locale ? { where: { locale: { eq: locale } } } : {}),
+    ...(Object.keys(where).length > 0 ? { where } : {}),
   };
   const bigrammed = BIGRAM_LANGUAGES.has(db.tokenizer?.language ?? "");
   const strict = bigrammed

package/src/search/popular-icon.ts

@@ -0,0 +1,33 @@
+import { escape } from "html-escaper";
+
+import { prefixBase } from "../components/islands/base-path.ts";
+import { isImageIcon, isInlineSvg } from "../theme/icon-kind.ts";
+import { resolveIcon } from "../theme/icons.ts";
+
+/**
+ * Resolve a `search.popular` icon to markup for the Cmd+K island. Accepts the
+ * same *inputs* as nav `<Icon>` (built-in name, image path/URL, inline SVG);
+ * resolved on the server so the island never loads the icon set.
+ */
+export const resolvePopularIconMarkup = (
+  icon?: string,
+  /** `deployment.base` / `import.meta.env.BASE_URL` for root-relative image paths. */
+  base = "/"
+): string | undefined => {
+  if (!icon) {
+    return undefined;
+  }
+  if (isInlineSvg(icon)) {
+    // Author SVG carries no guaranteed width/height (a viewBox-only <svg>
+    // defaults to 300x150), so size it the same way Icon.astro's wrapper does.
+    return `<span aria-hidden="true" style="display:inline-flex;width:16px;height:16px">${icon.trim()}</span>`;
+  }
+  if (isImageIcon(icon)) {
+    const src = escape(prefixBase(base, icon.trim()));
+    return `<img src="${src}" width="16" height="16" alt="" aria-hidden="true" class="size-4" />`;
+  }
+  const resolved = resolveIcon(icon);
+  return resolved
+    ? `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="${resolved.viewBox}" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${resolved.body}</svg>`
+    : undefined;
+};

package/src/theme/icon-kind.ts

@@ -0,0 +1,20 @@
+/**
+ * Classify author-supplied icon strings — built-in Lucide names vs image
+ * paths/URLs vs inline SVG. Shared by nav diagnostics, `<Icon>`, and the
+ * Cmd+K popular-icon resolver so the three shapes stay in sync.
+ */
+
+const IMAGE_ICON =
+  /^(?:https?:\/\/|data:image\/|\/|\.{1,2}\/)|\.(?:avif|gif|jpe?g|png|svg|webp)$/iu;
+
+const INLINE_SVG = /^\s*<svg[\s\S]*<\/svg>\s*$/u;
+
+/** Image path, remote URL, or data URI — not a Lucide name or inline SVG. */
+export const isImageIcon = (value: string): boolean => IMAGE_ICON.test(value);
+
+/** Full `<svg>…</svg>` markup (whitespace-tolerant). */
+export const isInlineSvg = (value: string): boolean => INLINE_SVG.test(value);
+
+/** Image or inline SVG — anything that is not a built-in icon name. */
+export const isAssetIcon = (value: string): boolean =>
+  isInlineSvg(value) || isImageIcon(value);

package/src/translate/agents.ts

@@ -0,0 +1,51 @@
+import type { AgentKind } from "../audit/agent.ts";
+import { DISALLOWED_TOOLS } from "../eval/agents.ts";
+
+/**
+ * argv builders for the translator role. The subprocess machinery
+ * (`runAgentHeadless`, `readAgentOutput`, the `HeadlessRunner` test seam) is
+ * shared with `blume eval` — only the argument surface differs: a translator
+ * is a pure text→text call with no MCP servers and no tools at all, so the
+ * agent can neither read the repo nor write files (Blume owns every write).
+ */
+
+/**
+ * Wall-clock ceiling per file. Generous by design: translating a large page
+ * means regenerating the whole file token by token, and a 20KB+ reference
+ * page comfortably exceeds the eval reader's 3-minute precedent. The ceiling
+ * exists to catch hung agents, not to police slow-but-progressing ones.
+ */
+export const DEFAULT_TRANSLATE_TIMEOUT_MS = 600_000;
+
+const claudeArgs = (): string[] => [
+  "-p",
+  "--output-format",
+  "json",
+  "--strict-mcp-config",
+  "--disallowedTools",
+  DISALLOWED_TOOLS.join(","),
+  "--max-turns",
+  "1",
+];
+
+const codexArgs = (lastMessagePath: string): string[] => [
+  "exec",
+  "--skip-git-repo-check",
+  "--ignore-user-config",
+  "--ephemeral",
+  "--sandbox",
+  "read-only",
+  "--output-last-message",
+  lastMessagePath,
+  "-",
+];
+
+/**
+ * Build the argv for one headless translation call. `lastMessagePath` is where
+ * codex writes its final message (its stdout interleaves progress); claude
+ * ignores it and answers as JSON on stdout.
+ */
+export const translateAgentArgs = (
+  kind: AgentKind,
+  lastMessagePath: string
+): string[] => (kind === "claude" ? claudeArgs() : codexArgs(lastMessagePath));

package/src/translate/ledger.ts

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+import { join } from "pathe";
+import { z } from "zod";
+
+import { writeTextAtomic } from "../core/fs-atomic.ts";
+
+/**
+ * The committed translation ledger: which source files have been translated
+ * into which locales, and at what source content. Named "ledger" to avoid
+ * colliding with the route manifest (`core/manifest.ts`). It lives at the
+ * project root — never inside `.blume/` (init gitignores that dir wholesale,
+ * and the whole point is that the ledger is committed alongside the docs).
+ */
+export const LEDGER_FILE = "blume.translations.json";
+
+/**
+ * `files` maps a POSIX root-relative source path to, per locale, the hash of
+ * the raw source text at the moment that locale's translation was written.
+ */
+export interface TranslationLedger {
+  version: 1;
+  files: Record<string, Record<string, string>>;
+}
+
+const ledgerSchema = z.object({
+  files: z.record(z.string(), z.record(z.string(), z.string())),
+  version: z.literal(1),
+});
+
+export const emptyLedger = (): TranslationLedger => ({
+  files: {},
+  version: 1,
+});
+
+/**
+ * Hash the raw source text (frontmatter included), so any edit invalidates
+ * every locale's stamp. sha256-16 like the audit snapshot's content hash —
+ * never `hashText` (djb2), which is an ephemeral-cache-only hash.
+ */
+export const hashSource = (text: string): string =>
+  createHash("sha256").update(text).digest("hex").slice(0, 16);
+
+/**
+ * Read the ledger at `root`, tolerantly: a missing file, unparseable JSON, or
+ * an unknown shape/version all resolve to an empty ledger rather than an error
+ * (same posture as the dev lock's `parseLock`) — the worst outcome of a
+ * corrupt ledger is retranslating files that were already up to date.
+ */
+export const readLedger = async (root: string): Promise<TranslationLedger> => {
+  let raw: string;
+  try {
+    raw = await readFile(join(root, LEDGER_FILE), "utf-8");
+  } catch {
+    return emptyLedger();
+  }
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return emptyLedger();
+  }
+  const parsed = ledgerSchema.safeParse(data);
+  return parsed.success ? parsed.data : emptyLedger();
+};
+
+/** Deterministic serialization: keys sorted at both levels, 2-space indent. */
+export const serializeLedger = (ledger: TranslationLedger): string => {
+  const files: Record<string, Record<string, string>> = {};
+  for (const source of Object.keys(ledger.files).toSorted()) {
+    const locales = ledger.files[source] ?? {};
+    files[source] = Object.fromEntries(
+      Object.keys(locales)
+        .toSorted()
+        .map((locale) => [locale, locales[locale] ?? ""])
+    );
+  }
+  return `${JSON.stringify({ files, version: ledger.version }, null, 2)}\n`;
+};
+
+/**
+ * Write the ledger at `root`, returning whether anything changed on disk. A
+ * byte-identical ledger is left untouched (no mtime churn, no git noise);
+ * a changed one lands via temp-file-plus-rename so a concurrent reader never
+ * observes a half-written file.
+ */
+export const writeLedger = async (
+  root: string,
+  ledger: TranslationLedger
+): Promise<boolean> => {
+  const path = join(root, LEDGER_FILE);
+  const content = serializeLedger(ledger);
+  let existing: string | null = null;
+  try {
+    existing = await readFile(path, "utf-8");
+  } catch {
+    existing = null;
+  }
+  if (existing === content) {
+    return false;
+  }
+  await writeTextAtomic(path, content);
+  return true;
+};
+
+/** Record that `sourceRel` is translated into `locale` at source hash `hash`. */
+export const stampLedger = (
+  ledger: TranslationLedger,
+  sourceRel: string,
+  locale: string,
+  hash: string
+): void => {
+  const locales = ledger.files[sourceRel] ?? {};
+  locales[locale] = hash;
+  ledger.files[sourceRel] = locales;
+};
+
+/**
+ * Drop entries for sources that no longer exist and locales that are no longer
+ * configured, so deleted pages and removed locales don't linger in the ledger
+ * forever. Returns a new ledger.
+ */
+export const pruneLedger = (
+  ledger: TranslationLedger,
+  knownSources: ReadonlySet<string>,
+  knownLocales: ReadonlySet<string>
+): TranslationLedger => {
+  const files: Record<string, Record<string, string>> = {};
+  for (const [source, locales] of Object.entries(ledger.files)) {
+    if (!knownSources.has(source)) {
+      continue;
+    }
+    const kept = Object.fromEntries(
+      Object.entries(locales).filter(([locale]) => knownLocales.has(locale))
+    );
+    if (Object.keys(kept).length > 0) {
+      files[source] = kept;
+    }
+  }
+  return { files, version: ledger.version };
+};