prosebook 0.0.1 → 0.1.0

package/src/runtime/types.ts

@@ -0,0 +1,106 @@
+/**
+ * The shapes the generated catalog and the runtime agree on.
+ *
+ * A catalog is compiled at build time: every ICU message becomes either a string (no placeholders)
+ * or a small function over its arguments and a set of locale-bound helpers. The runtime never parses
+ * ICU, so it carries no parser, needs no `eval`, and a message costs a property read or one call.
+ */
+
+/** What the generator knows about one message: the arguments it takes and the tags it wraps text in. */
+export interface MessageShape {
+  args: object;
+  tags: string;
+}
+
+/** Every key of a catalog, mapped to its shape. The generated `Messages` interface is one of these. */
+export type MessageShapes = { [key: string]: MessageShape };
+
+/**
+ * Augmented by the generated module, so hooks and components that are not handed a catalog
+ * (`useCopy()`, `<Text>`) still know its keys:
+ *
+ * ```ts
+ * declare module 'prosebook' {
+ *   interface Register { messages: Messages; locale: Locale }
+ * }
+ * ```
+ *
+ * Add `tags: 'b' | 'link'` to say which tags the provider renders by default, so a call site
+ * needs to supply only the others.
+ */
+// oxlint-disable-next-line typescript/no-empty-interface -- filled in by declaration merging
+export interface Register {}
+
+export type RegisteredMessages = Register extends { messages: infer M extends MessageShapes } ? M : MessageShapes;
+export type RegisteredLocale = Register extends { locale: infer L extends string } ? L : string;
+/** Tags the provider renders unless a call site says otherwise. */
+export type DefaultTags = Register extends { tags: infer T extends string } ? T : never;
+
+/**
+ * The helpers a compiled message calls, bound to the locale its words are in. Names are one letter
+ * because they appear once per placeholder in every generated module.
+ */
+export interface Helpers {
+  readonly locale: string;
+  /** `{x, number, …}` and the `#` of a plural. */
+  n(value: number, options?: Intl.NumberFormatOptions): string;
+  /** `{x, date, …}` and `{x, time, …}`. */
+  d(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+  /** `{x, plural, …}` and `{x, selectordinal, …}`: picks an arm and renders it. */
+  p(value: number, offset: number, ordinal: boolean, arms: Arms): unknown;
+  /** `{x, select, …}`. */
+  s(value: unknown, arms: Arms): unknown;
+  /** `<tag>…</tag>`: the tag's function from the values, or the bare children when there is none. */
+  t(values: Values, tag: string, children: unknown): unknown;
+}
+
+export type Arms = { [arm: string]: () => unknown };
+// `any`, not `unknown`: call sites are checked against the generated `Messages`, so a compiled
+// message can hand its arguments to the helpers without a cast per placeholder.
+// oxlint-disable-next-line typescript/no-explicit-any
+export type Values = { readonly [name: string]: any };
+
+/**
+ * Told of every message read: its key, the text it came to and the locale it was found in, which is
+ * the fallback's when the current locale lacks it. The Vite plugin's dev inspector sets one on
+ * `globalThis` to map text on screen back to keys; nothing sets it in a build.
+ */
+export type ReadHook = (key: string, text: string, locale: string) => void;
+
+/** Hands a copy a locale's messages, regenerated after a catalog edit, in place of the ones it loaded. */
+export type HotHook = (locale: string, messages: CompiledMessages) => void;
+
+/**
+ * What the Vite plugin sets on `globalThis` in dev. `__PROSEBOOK_HOT__` is there before the app runs,
+ * so each copy adds itself, and the generated modules call every copy when they are updated.
+ */
+export type DevHooks = { __PROSEBOOK_READ__?: ReadHook; __PROSEBOOK_HOT__?: Set<HotHook> };
+
+/** One compiled message. */
+export type Compiled = string | ((values: Values, h: Helpers) => unknown);
+
+/** One locale's compiled messages: what a generated `<locale>.ts` module exports by default. */
+export type CompiledMessages = { readonly [key: string]: Compiled };
+
+/** What a tag's function receives: the pieces it wraps, adjacent text already joined. */
+export type Chunks<N> = (string | N)[];
+export type TagFn<N> = (chunks: Chunks<N>) => N;
+/** A tag renderer for any kind of node, as configured once on a `Copy`. */
+export type AnyTagFn = (chunks: never) => unknown;
+
+type NoArgs<T> = {} extends T ? true : false;
+
+/** The arguments of a plain read: optional when the message takes none. */
+export type ArgsParam<S extends MessageShape> = NoArgs<S['args']> extends true ? [args?: S['args']] : [args: S['args']];
+
+type TagValues<S extends MessageShape, N> = { [T in Exclude<S['tags'], DefaultTags>]: TagFn<N> } & {
+  [T in Extract<S['tags'], DefaultTags>]?: TagFn<N>;
+};
+
+/** A rich read takes the message's arguments and a function per tag it wraps, beside the defaults. */
+export type RichValues<S extends MessageShape, N> = S['args'] & TagValues<S, N>;
+export type RichParam<S extends MessageShape, N> =
+  NoArgs<RichValues<S, N>> extends true ? [values?: RichValues<S, N>] : [values: RichValues<S, N>];
+
+/** The keys whose message wraps part of itself in a tag. */
+export type RichKey<M extends MessageShapes> = { [K in keyof M]: [M[K]['tags']] extends [never] ? never : K }[keyof M] & string;

package/src/tools/catalog.ts

@@ -0,0 +1,449 @@
+/**
+ * Reads the catalog and its translations into one checked model.
+ *
+ * Every message is parsed as ICU here rather than at runtime, which is what lets the generator hand
+ * TypeScript exact argument types, compile messages to plain functions, and fail the build where a
+ * translation's placeholders drifted from the source instead of dropping a value off the screen.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+import { isMap, isScalar, LineCounter, parseDocument, parse as parseYaml, Scalar } from 'yaml';
+
+import type { ResolvedConfig } from './config.ts';
+import { argsOf, formatProblems, formatsOf, staticLiteral, tagsOf, type MessageFormatElement } from './icu.ts';
+import { readMessage } from './syntax.ts';
+
+export interface Translation {
+  text: string;
+  ast: MessageFormatElement[];
+  file: string;
+}
+
+export interface Message {
+  key: string;
+  /** The first segment of the key, which names its file. */
+  area: string;
+  file: string;
+  kind?: string;
+  surface?: string;
+  /** One sentence telling a translator where the string appears. */
+  context?: string;
+  /** What each placeholder holds, keyed by argument name. */
+  argDocs: Map<string, string>;
+  /** Completes something beside it rather than standing as a sentence, so sentence rules do not apply. */
+  fragment: boolean;
+  /** Lint rules the entry is exempt from, each with the reason. */
+  allow: Map<string, string>;
+  /** A change someone asked for, left for whoever edits the entry next, and deleted once it is made. */
+  comment?: string;
+  /** Asked to go: the entry, its translations and the code that reads it. */
+  remove: boolean;
+  /** The source message, in ICU MessageFormat. */
+  text: string;
+  ast: MessageFormatElement[];
+  /** Argument name to TypeScript type. */
+  args: Map<string, string>;
+  /** How each formatted argument is styled, for the doc comment at the call site. */
+  argFormats: Map<string, string>;
+  tags: string[];
+  /** Translations by locale. */
+  translations: Map<string, Translation>;
+}
+
+export interface Problem {
+  severity: 'error' | 'warn';
+  /** Relative to the project root; none for a problem that isn't in a file. */
+  file?: string;
+  /** The entry it is about, in `file`; none for the file as a whole. */
+  key?: string;
+  message: string;
+}
+
+/** `file key`, as the CLI names where a problem is. */
+export function whereOf(problem: Problem): string {
+  return [problem.file, problem.key].filter((s) => s !== undefined).join(' ');
+}
+
+export interface Catalog {
+  messages: Message[];
+  /** The translated locales found under `locales`, without the source. */
+  locales: string[];
+  problems: Problem[];
+}
+
+export class CatalogError extends Error {
+  readonly problems: Problem[];
+
+  constructor(problems: Problem[]) {
+    super(`the catalog has ${problems.length} problem(s):\n  ${problems.map((p) => `${whereOf(p)}: ${p.message}`).join('\n  ')}`);
+    this.problems = problems;
+  }
+}
+
+/**
+ * A key is dotted lowercase, two segments at least, and its first segment names the file it lives
+ * in. Keys are read at every call site, so they say what the string is for: `cart.checkout.title`.
+ */
+export const KEY_PATTERN = /^[a-z0-9]+(?:[-_][a-z0-9]+)*(?:\.[a-z0-9]+(?:[-_][a-z0-9]+)*)+$/;
+
+const FIELDS = new Set(['kind', 'surface', 'context', 'args', 'fragment', 'allow', 'comment', 'remove']);
+
+/**
+ * Loads and checks the catalog. Throws a `CatalogError` when anything is an error; warnings ride along.
+ * `unsaved` holds file contents by absolute path to read in place of what is on disk, so an edit can be
+ * checked before it is written; a translation file in it that isn't on disk yet is read too.
+ */
+export function loadCatalog(config: ResolvedConfig, unsaved?: ReadonlyMap<string, string>): Catalog {
+  const read = (path: string) => unsaved?.get(resolve(path)) ?? readFileSync(path, 'utf8');
+  const problems: Problem[] = [];
+  const error = (message: string, file?: string, key?: string) => problems.push({ severity: 'error', file, key, message });
+  const byKey = new Map<string, Message>();
+  const rel = (path: string) => relative(config.root, path).replaceAll('\\', '/');
+
+  if (!existsSync(config.catalog)) {
+    error('no catalog folder here: run `prosebook init`, or set `catalog` in the config', rel(config.catalog));
+    throw new CatalogError(problems);
+  }
+
+  for (const file of yamlFiles(config.catalog)) {
+    const area = file.slice(0, -'.yaml'.length);
+    const path = join(config.catalog, file);
+    const at = rel(path);
+    for (const [key, value] of Object.entries(readEntries(read(path), (m) => error(m, at)))) {
+      if (!KEY_PATTERN.test(key)) {
+        error('a key is dotted lowercase with two segments at least: `area.thing`', at, key);
+        continue;
+      }
+      if (key.slice(0, key.indexOf('.')) !== area) {
+        error(`a key in ${file} starts with "${area}."`, at, key);
+        continue;
+      }
+      if (byKey.has(key)) {
+        error('duplicate key', at, key);
+        continue;
+      }
+      const message = readEntry(key, area, at, value, config, (m) => error(m, at, key));
+      if (!message) continue;
+      byKey.set(key, message);
+      // Asked of whoever edits next, often an agent, which finds them among the warnings of every run.
+      const warn = (m: string) => problems.push({ severity: 'warn', file: at, key, message: m });
+      if (message.remove) warn('marked for removal: delete the entry, its translations and the code that reads it');
+      if (message.comment !== undefined) warn(`a comment to act on, then delete: ${message.comment}`);
+    }
+  }
+
+  const created = [...(unsaved?.keys() ?? [])].filter((path) => !existsSync(path));
+  const locales = readLocales(config, byKey, problems, rel, read, created);
+  if (problems.some((p) => p.severity === 'error')) throw new CatalogError(problems);
+  return { messages: [...byKey.values()].sort((a, b) => (a.key < b.key ? -1 : 1)), locales, problems };
+}
+
+function readEntry(
+  key: string,
+  area: string,
+  file: string,
+  value: unknown,
+  config: ResolvedConfig,
+  error: (message: string) => void,
+): Message | undefined {
+  // `key: message` is the shorthand for an entry with nothing to say about itself.
+  const entry = (typeof value === 'string' ? { [config.source]: value } : value) as Record<string, unknown> | null;
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+    error(`an entry is a message, or a mapping holding \`${config.source}\` and what the string is`);
+    return undefined;
+  }
+  let ok = true;
+  const fail = (message: string) => {
+    error(message);
+    ok = false;
+  };
+  for (const field of Object.keys(entry))
+    if (!FIELDS.has(field) && field !== config.source) fail(`"${field}" is not a field: ${[...FIELDS, config.source].join(', ')}`);
+
+  const text = entry[config.source];
+  if (typeof text !== 'string' || text === '') {
+    fail(`${config.source} is the message, and it is missing`);
+    return undefined;
+  }
+  for (const field of config.require) if (entry[field] === undefined) fail(`${field} is required (\`require\` in the config)`);
+
+  const kind = optionalString(entry, 'kind', fail);
+  if (kind !== undefined && !(kind in config.kinds)) fail(`kind is one of ${Object.keys(config.kinds).join(', ')}`);
+  const surface = optionalString(entry, 'surface', fail);
+  if (surface !== undefined && !(surface in config.surfaces)) fail(`surface is one of ${Object.keys(config.surfaces).join(', ')}`);
+  const context = optionalString(entry, 'context', fail);
+  if (entry.fragment !== undefined && typeof entry.fragment !== 'boolean') fail('fragment is true or false');
+  const comment = optionalString(entry, 'comment', fail);
+  if (entry.remove !== undefined && typeof entry.remove !== 'boolean') fail('remove is true or false');
+
+  let ast: MessageFormatElement[];
+  try {
+    ast = readMessage(config.messageFormat, text, config.source);
+  } catch (e) {
+    fail(syntaxError(config, text, e));
+    return undefined;
+  }
+  for (const problem of formatProblems(ast)) fail(problem);
+  const args = argsOf(ast, (name) => fail(`"${name}" is used as two different types`));
+  const argDocs = stringMap(entry, 'args', fail);
+  // An undocumented placeholder is fine unless context is required; a doc for an argument that no
+  // longer exists is always stale.
+  if (config.require.includes('context'))
+    for (const name of args.keys()) if (!argDocs.has(name)) fail(`args.${name} is missing: say what the placeholder holds`);
+
+  for (const name of argDocs.keys()) if (!args.has(name)) fail(`args.${name} is not an argument of this message`);
+
+  if (!ok) return undefined;
+  return {
+    key,
+    area,
+    file,
+    kind,
+    surface,
+    context,
+    argDocs,
+    fragment: entry.fragment === true,
+    allow: stringMap(entry, 'allow', fail),
+    comment,
+    remove: entry.remove === true,
+    text,
+    ast,
+    args,
+    argFormats: formatsOf(ast),
+    tags: tagsOf(ast),
+    translations: new Map(),
+  };
+}
+
+function readLocales(
+  config: ResolvedConfig,
+  byKey: Map<string, Message>,
+  problems: Problem[],
+  rel: (p: string) => string,
+  read: (path: string) => string,
+  created: string[],
+): string[] {
+  if (!existsSync(config.locales)) return [];
+  const files = new Map<string, string[]>();
+  for (const name of readdirSync(config.locales).sort()) {
+    const path = join(config.locales, name);
+    const isDir = statSync(path).isDirectory();
+    if (!isDir && !name.endsWith('.yaml')) continue;
+    const locale = isDir ? name : name.slice(0, -'.yaml'.length);
+    const found = isDir ? yamlFiles(path).map((f) => join(path, f)) : [path];
+    files.set(locale, [...(files.get(locale) ?? []), ...found]);
+  }
+  // A translation file an edit would create, read as if it were there already.
+  for (const path of created) {
+    const inside = relative(config.locales, path).replaceAll('\\', '/');
+    if (inside.startsWith('..') || !inside.endsWith('.yaml')) continue;
+    const [first = '', second] = inside.split('/');
+    const locale = second === undefined ? first.slice(0, -'.yaml'.length) : first;
+    files.set(locale, [...(files.get(locale) ?? []), path]);
+  }
+  files.delete(config.source);
+
+  for (const [locale, paths] of files) {
+    for (const path of paths) {
+      const file = rel(path);
+      const error = (message: string, key?: string) => problems.push({ severity: 'error', file, key, message });
+      for (const [key, value] of Object.entries(readEntries(read(path), error))) {
+        const message = byKey.get(key);
+        if (message === undefined) {
+          problems.push({ severity: 'warn', file, key, message: 'no such key in the catalog, so this translation is unused' });
+          continue;
+        }
+        if (typeof value !== 'string' || value === '') {
+          error('a translation is the message, as a string', key);
+          continue;
+        }
+        let ast: MessageFormatElement[];
+        try {
+          ast = readMessage(config.messageFormat, value, locale);
+        } catch (e) {
+          error(syntaxError(config, value, e), key);
+          continue;
+        }
+        const drift = driftFrom(message, ast);
+        if (drift !== undefined) {
+          error(drift, key);
+          continue;
+        }
+        for (const problem of formatProblems(ast)) error(problem, key);
+        message.translations.set(locale, { text: value, ast, file });
+      }
+    }
+  }
+  return [...files.keys()];
+}
+
+/** How a translation's placeholders or tags differ from the source, or nothing. */
+function driftFrom(message: Message, ast: MessageFormatElement[]): string | undefined {
+  const args = argsOf(ast);
+  const missing = [...message.args.keys()].filter((a) => !args.has(a));
+  const extra = [...args.keys()].filter((a) => !message.args.has(a));
+  const retyped = [...args]
+    .filter(([a, type]) => message.args.has(a) && message.args.get(a) !== type && !type.includes('string &'))
+    .map(([a]) => a);
+  const tags = tagsOf(ast);
+  const parts = [
+    missing.length > 0 ? `missing {${missing.join('}, {')}}` : '',
+    extra.length > 0 ? `unknown {${extra.join('}, {')}}` : '',
+    retyped.length > 0 ? `{${retyped.join('}, {')}} used as another type` : '',
+    tags.join() === message.tags.join()
+      ? ''
+      : `tags are <${tags.join('>, <') || 'none'}>, the source has <${message.tags.join('>, <') || 'none'}>`,
+  ].filter(Boolean);
+  return parts.length > 0 ? `differs from the source: ${parts.join('; ')}` : undefined;
+}
+
+function syntaxError(config: ResolvedConfig, text: string, e: unknown): string {
+  // MF2's reader words its own problems; see mf2.ts.
+  if (config.messageFormat === 2) return (e as Error).message;
+  return icuError(text, e);
+}
+
+function icuError(text: string, e: unknown): string {
+  const hyphenated = /select\s*,/.test(text) ? /[,{]\s*([a-z0-9]+(?:-[a-z0-9]+)+)\s*\{/.exec(text) : null;
+  if (hyphenated) return `names a select arm "${hyphenated[1]}": an arm's name takes no hyphen, so write it with an underscore`;
+  const reason = (e as Error).message;
+  if (/TAG/.test(reason)) return `is not valid ICU (${reason}): a literal < is written '<'`;
+  return `is not valid ICU MessageFormat: ${reason}`;
+}
+
+function yamlFiles(dir: string): string[] {
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.yaml'))
+    .sort();
+}
+
+/**
+ * The file's entries. YAML 1.1 and 1.2 disagree about bare scalars: 1.1 reads `n`, `on` and `yes` as
+ * booleans and `12:30` as a number. Translation tools are often 1.1, so a file that reads differently
+ * under each fails here, naming the value to quote, rather than corrupting quietly in the next tool.
+ */
+function readEntries(text: string, error: (message: string) => void): Record<string, unknown> {
+  let raw: unknown;
+  try {
+    raw = parseYaml(text);
+  } catch (e) {
+    error(`is not valid YAML: ${(e as Error).message}`);
+    return {};
+  }
+  if (raw === null || raw === undefined) return {};
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    error('a catalog file is a mapping of key to entry');
+    return {};
+  }
+  try {
+    const found = divergence(raw, parseYaml(text, { version: '1.1' }), '');
+    if (found !== undefined) error(found);
+  } catch (e) {
+    error(`does not parse as YAML 1.1, which another tool may well be: ${(e as Error).message}`);
+  }
+  return raw as Record<string, unknown>;
+}
+
+function divergence(a: unknown, b: unknown, path: string): string | undefined {
+  if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
+    if (Object.is(a, b)) return undefined;
+    return `${path} reads as ${JSON.stringify(a)} under YAML 1.2 and ${JSON.stringify(b)} under YAML 1.1: quote it`;
+  }
+  const left = a as Record<string, unknown>;
+  const right = b as Record<string, unknown>;
+  for (const key of new Set([...Object.keys(left), ...Object.keys(right)])) {
+    const here = path === '' ? key : `${path}.${key}`;
+    if (key in left !== key in right) return `${here} is a key under YAML ${key in left ? '1.2' : '1.1'} only: quote it`;
+    const found = divergence(left[key], right[key], here);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+function optionalString(entry: Record<string, unknown>, field: string, fail: (m: string) => void): string | undefined {
+  const value = entry[field];
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || value.trim() === '') {
+    fail(`${field} is a non-empty string`);
+    return undefined;
+  }
+  return value.trim();
+}
+
+function stringMap(entry: Record<string, unknown>, field: string, fail: (m: string) => void): Map<string, string> {
+  const out = new Map<string, string>();
+  const value = entry[field];
+  if (value === undefined) return out;
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    fail(`${field} is a mapping of name to sentence`);
+    return out;
+  }
+  for (const [name, said] of Object.entries(value)) {
+    if (typeof said !== 'string' || said.trim() === '') fail(`${field}.${name} is a sentence`);
+    else out.set(name, said.trim());
+  }
+  return out;
+}
+
+export interface EntryLocation {
+  /** Absolute. */
+  file: string;
+  /** From 1. */
+  line: number;
+  /** From 1. */
+  column: number;
+}
+
+/**
+ * Where a message's entry is written: its translation in `locale` when there is one, else the catalog.
+ * Read from the file as it is now, so an entry moved since the catalog was loaded is still found.
+ */
+export function entryLocation(config: ResolvedConfig, message: Message, locale?: string): EntryLocation {
+  const file = (locale === undefined ? undefined : message.translations.get(locale)?.file) ?? message.file;
+  return { file: join(config.root, file), ...entryLocator(config.root)(file, message.key) };
+}
+
+/**
+ * Finds a key's line and column in a catalog or translation file, given relative to `root`. Each file
+ * is read once, so a report that places many entries parses each file once. A key it can't find, or no
+ * key, is the top of the file.
+ *
+ * Given an `offset` into the message (under `field`, in an entry that is a mapping), it is that
+ * character, when the value is written in the file as it reads up to there: plain, or quoted on one
+ * line with nothing escaped before it. Otherwise it is the key.
+ */
+export function entryLocator(root: string): (file: string, key?: string, offset?: number, field?: string) => Omit<EntryLocation, 'file'> {
+  const read = new Map<string, { doc: ReturnType<typeof parseDocument>; lines: LineCounter; source: string }>();
+  return (file, key, offset, field) => {
+    let parsed = read.get(file);
+    if (parsed === undefined) {
+      const path = join(root, file);
+      const lines = new LineCounter();
+      const source = existsSync(path) ? readFileSync(path, 'utf8') : '';
+      parsed = { doc: parseDocument(source, { lineCounter: lines }), lines, source };
+      read.set(file, parsed);
+    }
+    const { doc, lines, source } = parsed;
+    const pair =
+      key !== undefined && isMap(doc.contents) ? doc.contents.items.find((p) => isScalar(p.key) && p.key.value === key) : undefined;
+    const value = isMap(pair?.value) && field !== undefined ? pair.value.get(field, true) : pair?.value;
+    if (offset !== undefined && isScalar(value) && typeof value.value === 'string' && value.range) {
+      const quoted = value.type === Scalar.QUOTE_DOUBLE || value.type === Scalar.QUOTE_SINGLE;
+      const content = value.range[0] + (quoted ? 1 : 0);
+      if (source.slice(content, content + offset) === value.value.slice(0, offset)) {
+        const { line, col } = lines.linePos(content + offset);
+        return { line, column: col };
+      }
+    }
+    const start = isScalar(pair?.key) ? pair.key.range?.[0] : undefined;
+    if (start === undefined) return { line: 1, column: 1 };
+    const { line, col } = lines.linePos(start);
+    return { line, column: col };
+  };
+}
+
+/** The source message as a reader sees it with no placeholders filled: for docs and reports. */
+export function previewOf(message: Message): string {
+  return staticLiteral(message.ast) ?? message.text;
+}

package/src/tools/compile.ts

@@ -0,0 +1,110 @@
+/**
+ * Compiles ICU ASTs to JavaScript.
+ *
+ * A message with no placeholders becomes its string. Any other becomes `(a, h) => …`, where `a` holds
+ * the arguments and `h` the locale's helpers (see `runtime/helpers.ts`): a plural is a call picking an
+ * arm, a number is a call to a cached `Intl.NumberFormat`. Formatting options are resolved here and
+ * hoisted to module constants, so a skeleton costs nothing at runtime and its formatter is built once.
+ */
+import { isDateElement, isNumberElement, isTimeElement } from '@formatjs/icu-messageformat-parser';
+
+import { dateOptions, numberOptions, staticLiteral, TYPE, type MessageFormatElement } from './icu.ts';
+
+export type Entry = readonly [key: string, ast: MessageFormatElement[]];
+
+/** Module-level constants for formatting options, one per distinct object. */
+class Hoisted {
+  private readonly byJson = new Map<string, string>();
+
+  /** `, oN` naming the hoisted options, or nothing when there are none. */
+  arg(options: object | undefined): string {
+    // `{}` (a bare `:number`) formats as no options do, so it needs no constant.
+    if (options === undefined || Object.keys(options).length === 0) return '';
+    const json = JSON.stringify(options);
+    let name = this.byJson.get(json);
+    if (name === undefined) this.byJson.set(json, (name = `o${this.byJson.size}`));
+    return `, ${name}`;
+  }
+
+  declarations(): string[] {
+    return [...this.byJson].map(([json, name]) => `const ${name} = ${json};`);
+  }
+}
+
+function access(name: string): string {
+  return /^[A-Za-z_$][\w$]*$/.test(name) ? `a.${name}` : `a[${JSON.stringify(name)}]`;
+}
+
+function nodes(elements: MessageFormatElement[], hoisted: Hoisted, pound: string | null): string {
+  if (elements.length === 0) return '""';
+  const parts = elements.map((el) => node(el, hoisted, pound));
+  return parts.length === 1 ? parts[0]! : `[${parts.join(', ')}]`;
+}
+
+function arms(options: Record<string, { value: MessageFormatElement[] }>, hoisted: Hoisted, pound: string | null): string {
+  const body = Object.entries(options).map(([arm, option]) => `${JSON.stringify(arm)}: () => ${nodes(option.value, hoisted, pound)}`);
+  return `{ ${body.join(', ')} }`;
+}
+
+function node(el: MessageFormatElement, hoisted: Hoisted, pound: string | null): string {
+  if (isNumberElement(el)) return `h.n(${access(el.value)}${hoisted.arg(numberOptions(el))})`;
+  if (isDateElement(el) || isTimeElement(el)) return `h.d(${access(el.value)}${hoisted.arg(dateOptions(el))})`;
+  switch (el.type) {
+    case TYPE.literal:
+      return JSON.stringify(el.value);
+    case TYPE.argument:
+      return access(el.value);
+    case TYPE.pound:
+      return pound ?? '"#"';
+    case TYPE.select:
+      return `h.s(${access(el.value)}, ${arms(el.options, hoisted, pound)})`;
+    case TYPE.plural: {
+      // `#` is the plural's own value less its offset, formatted as a number.
+      const value = access(el.value);
+      const hash = `h.n(${value}${el.offset !== 0 ? ` - ${el.offset}` : ''})`;
+      return `h.p(${value}, ${el.offset}, ${el.pluralType === 'ordinal'}, ${arms(el.options, hoisted, hash)})`;
+    }
+    case TYPE.tag:
+      return `h.t(a, ${JSON.stringify(el.value)}, ${nodes(el.children, hoisted, pound)})`;
+    default:
+      throw new Error(`prosebook: no compiler for ICU element type ${(el as MessageFormatElement).type}`);
+  }
+}
+
+function message(ast: MessageFormatElement[], hoisted: Hoisted): string {
+  const literal = staticLiteral(ast);
+  return literal === undefined ? `(a, h) => ${nodes(ast, hoisted, null)}` : JSON.stringify(literal);
+}
+
+export interface CompiledLocale {
+  /** `const oN = {…};` lines the messages refer to. */
+  declarations: string[];
+  /** `"key": message,` lines. */
+  rows: string[];
+}
+
+/** One locale's messages as code, keeping only `keep` when given. */
+export function compileLocale(entries: Iterable<Entry>, keep?: (key: string) => boolean): CompiledLocale {
+  const hoisted = new Hoisted();
+  const rows: string[] = [];
+  for (const [key, ast] of entries) {
+    if (keep && !keep(key)) continue;
+    rows.push(`  ${JSON.stringify(key)}: ${message(ast, hoisted)},`);
+  }
+  return { declarations: hoisted.declarations(), rows };
+}
+
+/** The locale as an ES module whose default export is its messages. */
+export function localeModule(compiled: CompiledLocale, banner: string, ts: boolean): string {
+  const head = ts ? `${banner}\nimport type { CompiledMessages } from 'prosebook';\n` : `${banner}\n`;
+  // `as const` keeps `style: "currency"` a literal, which is what `Intl`'s option types ask for.
+  const declarations = ts ? compiled.declarations.map((d) => d.replace(/;$/, ' as const;')) : compiled.declarations;
+  const consts = declarations.length > 0 ? `\n${declarations.join('\n')}\n` : '';
+  const close = ts ? '} satisfies CompiledMessages;' : '};';
+  return `${head}${consts}\nexport default {\n${compiled.rows.join('\n')}\n${close}\n`;
+}
+
+/** The locale as one expression, for a bundler to inline in place of the module. */
+export function localeExpression(compiled: CompiledLocale): string {
+  return `(() => {\n${compiled.declarations.join('\n')}\nreturn {\n${compiled.rows.join('\n')}\n};\n})()`;
+}