prosebook 0.0.1 → 0.2.0

package/src/tools/config.ts

@@ -0,0 +1,211 @@
+/**
+ * `prosebook/config`: where the catalog lives, what an entry may say about itself, and how strictly
+ * its words are checked. Written as `prosebook.config.ts` (or `.js`, `.mjs`, `.json`) at the project root.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { compileRule, CORE_RULES, type CheckRule, type CoreRule, type Plugin } from './lint.ts';
+import { DEFAULT_KINDS, DEFAULT_SURFACES, STRICT_LISTS, type KindRule, type Severity } from './presets.ts';
+
+export type { KindRule, Severity };
+export {
+  definePlugin,
+  HOLE,
+  phrase,
+  sentences,
+  words,
+  type CapitalizationRule,
+  type CheckRule,
+  type ConditionalRule,
+  type ExistenceRule,
+  type OccurrenceRule,
+  type Plugin,
+  type Readings,
+  type Report,
+  type Rule,
+  type RuleContext,
+  type SubstitutionRule,
+} from './lint.ts';
+
+export interface WordLists {
+  /** Words a string never uses, in groups that say why. */
+  banned?: { words: string[]; why: string }[];
+  /** A spelling, and the one the product uses instead. */
+  spelling?: Record<string, string>;
+  /** A near-synonym, and the one word the product uses for that concept. */
+  concepts?: Record<string, string>;
+  /** Words that keep their capital inside a sentence-case string: product names, platforms. */
+  properNouns?: string[];
+  /** What a path through menus or settings is written with, spaced: `›` by default, as in Settings › General. */
+  pathSeparator?: string;
+}
+
+type RuleSeverities = Partial<Record<CoreRule, Severity>> & Record<string, Severity>;
+
+export interface LintConfig extends WordLists {
+  /** `recommended` (the default) checks shape; `strict` adds the word lists and rules of a house style guide. */
+  extends?: 'recommended' | 'strict' | 'none';
+  /** Rules of your own, as `<plugin>/<rule>`. Each takes the severity it gives itself under `extends`. */
+  plugins?: Plugin[];
+  rules?: RuleSeverities;
+  /** Severities for one area's entries (a key's first segment) over `rules`: `{ native: { 'sentence-case': 'off' } }`. */
+  areas?: Record<string, RuleSeverities>;
+}
+
+export interface ProsebookConfig {
+  /** The source-language catalog: one `<area>.yaml` per area. */
+  catalog?: string;
+  /** Translations: `<locale>/<area>.yaml` or `<locale>.yaml`, holding `key: message`. */
+  locales?: string;
+  /** Where the generated modules go. */
+  out?: string;
+  /** Records which source text each translation was made from, so a changed source marks it stale. */
+  lock?: string;
+  /** The locale the catalog is written in. Its code is also the field holding the message. */
+  source?: string;
+  /**
+   * The syntax messages are written in: ICU MessageFormat (1) or Unicode MessageFormat 2. Source and
+   * translations alike; `prosebook migrate` rewrites a catalog from one to the other.
+   */
+  messageFormat?: 1 | 2;
+  /** Locales that ship in the main bundle beside the source, rather than loading when first used. */
+  bundled?: string[];
+  /** A pseudo-locale generated from the source (accented and lengthened) to find layout bugs and hardcoded text. */
+  pseudo?: string | false;
+  /** What a translation whose source changed since does: still show (`use`) or show the source (`fallback`). */
+  stale?: 'use' | 'fallback';
+  /** Generated modules as TypeScript or as JavaScript with a `.d.ts` beside the index. */
+  language?: 'ts' | 'js';
+  /** The extension generated imports name: `.js` suits most TypeScript setups, `.ts` suits Node's type stripping. */
+  importExtension?: '.js' | '.ts' | '';
+  /** The fields every entry must have. A shorthand `key: message` entry satisfies none of them. */
+  require?: ('context' | 'kind' | 'surface')[];
+  /** The kinds of string an entry may say it is, with the shape each one is held to. */
+  kinds?: Record<string, KindRule>;
+  /** Where a string may sit, with what each surface means. */
+  surfaces?: Record<string, string>;
+  lint?: LintConfig;
+  /** Where `prosebook scan` looks for hardcoded text and catalog keys. */
+  scan?: {
+    dirs?: string[];
+    extensions?: string[];
+    /** JSX attributes whose literal value a person reads. */
+    attributes?: string[];
+  };
+}
+
+export interface ResolvedConfig {
+  root: string;
+  catalog: string;
+  locales: string;
+  out: string;
+  lock: string;
+  source: string;
+  messageFormat: 1 | 2;
+  bundled: string[];
+  pseudo: string | false;
+  stale: 'use' | 'fallback';
+  language: 'ts' | 'js';
+  importExtension: '.js' | '.ts' | '';
+  require: ('context' | 'kind' | 'surface')[];
+  kinds: Record<string, KindRule>;
+  surfaces: Record<string, string>;
+  lint: {
+    rules: Record<string, { rule: CheckRule; severity: Severity }>;
+    areas: Record<string, Record<string, Severity>>;
+  } & Required<WordLists>;
+  scan: { dirs: string[]; extensions: string[]; attributes: string[] };
+}
+
+/** Typed config, for `prosebook.config.ts`. */
+export function defineConfig(config: ProsebookConfig): ProsebookConfig {
+  return config;
+}
+
+export const CONFIG_FILES = [
+  'prosebook.config.ts',
+  'prosebook.config.mts',
+  'prosebook.config.js',
+  'prosebook.config.mjs',
+  'prosebook.config.json',
+];
+
+/** Finds and reads the config at `root`, or the defaults when there is none. */
+export async function loadConfig(root: string, inline?: ProsebookConfig): Promise<ResolvedConfig> {
+  if (inline) return resolveConfig(root, inline);
+  for (const name of CONFIG_FILES) {
+    const path = join(root, name);
+    if (!existsSync(path)) continue;
+    if (name.endsWith('.json')) return resolveConfig(root, JSON.parse(readFileSync(path, 'utf8')) as ProsebookConfig);
+    const mod = (await import(pathToFileURL(path).href)) as { default?: ProsebookConfig };
+    return resolveConfig(root, mod.default ?? {});
+  }
+  return resolveConfig(root, {});
+}
+
+export function resolveConfig(root: string, config: ProsebookConfig): ResolvedConfig {
+  const at = (path: string) => (isAbsolute(path) ? path : resolve(root, path));
+  const lint = config.lint ?? {};
+  const base = lint.extends ?? 'recommended';
+  const strict = base === 'strict';
+  const rules = lintRules(lint);
+  for (const [area, severities] of Object.entries(lint.areas ?? {})) {
+    for (const name of Object.keys(severities))
+      if (!(name in rules)) throw new Error(`lint.areas.${area}.${name} is not a rule: name one of ${Object.keys(rules).join(', ')}`);
+  }
+  return {
+    root,
+    catalog: at(config.catalog ?? 'copy/catalog'),
+    locales: at(config.locales ?? 'copy/locales'),
+    out: at(config.out ?? 'src/copy'),
+    lock: at(config.lock ?? 'copy/lock.json'),
+    source: config.source ?? 'en',
+    messageFormat: config.messageFormat ?? 1,
+    bundled: config.bundled ?? [],
+    pseudo: config.pseudo ?? false,
+    stale: config.stale ?? 'use',
+    language: config.language ?? 'ts',
+    importExtension: config.importExtension ?? '.js',
+    require: config.require ?? ['context'],
+    kinds: config.kinds ?? DEFAULT_KINDS,
+    surfaces: config.surfaces ?? DEFAULT_SURFACES,
+    lint: {
+      rules,
+      areas: lint.areas ?? {},
+      banned: [...(strict ? STRICT_LISTS.banned : []), ...(lint.banned ?? [])],
+      spelling: { ...(strict ? STRICT_LISTS.spelling : {}), ...lint.spelling },
+      concepts: { ...lint.concepts },
+      properNouns: lint.properNouns ?? [],
+      pathSeparator: lint.pathSeparator ?? '›',
+    },
+    scan: {
+      dirs: (config.scan?.dirs ?? ['src']).map(at),
+      extensions: config.scan?.extensions ?? ['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs'],
+      attributes: config.scan?.attributes ?? ['alt', 'title', 'placeholder', 'label', 'aria-label', 'aria-description', 'aria-placeholder'],
+    },
+  };
+}
+
+function lintRules(lint: LintConfig): ResolvedConfig['lint']['rules'] {
+  const base = lint.extends ?? 'recommended';
+  const all: [string, CheckRule][] = Object.entries(CORE_RULES);
+  const seen = new Set<string>();
+  for (const plugin of lint.plugins ?? []) {
+    if (!/^[a-z][a-z0-9-]*$/i.test(plugin.name))
+      throw new Error(`lint.plugins: "${plugin.name}" is not a plugin name: use letters, digits and dashes`);
+    if (seen.has(plugin.name)) throw new Error(`lint.plugins: "${plugin.name}" is added twice: remove one`);
+    seen.add(plugin.name);
+    for (const [name, rule] of Object.entries(plugin.rules)) {
+      const full = `${plugin.name}/${name}`;
+      all.push([full, compileRule(full, rule)]);
+    }
+  }
+  const preset = (rule: CheckRule): Severity =>
+    base === 'none' ? 'off' : base === 'strict' ? (rule.strict ?? 'error') : (rule.recommended ?? 'off');
+  const rules = Object.fromEntries(all.map(([name, rule]) => [name, { rule, severity: lint.rules?.[name] ?? preset(rule) }]));
+  for (const name of Object.keys(lint.rules ?? {}))
+    if (!(name in rules)) throw new Error(`lint.rules.${name} is not a rule: name one of ${Object.keys(rules).join(', ')}`);
+  return rules;
+}

package/src/tools/diff.ts

@@ -0,0 +1,84 @@
+/**
+ * A word diff, for showing a translator what changed in the source since they translated it. Words,
+ * runs of whitespace and single punctuation marks are the units, so an ICU brace or a period changes
+ * on its own rather than taking its word with it.
+ */
+
+export interface DiffPart {
+  op: 'same' | 'add' | 'del';
+  text: string;
+}
+
+const TOKEN = /\s+|[\p{L}\p{N}_'’]+|[^\s\p{L}\p{N}_]/gu;
+
+/** Past this many cells the table costs more than the diff is worth: show the whole change instead. */
+const MAX_CELLS = 250_000;
+
+export function wordDiff(before: string, after: string): DiffPart[] {
+  const a = before.match(TOKEN) ?? [];
+  const b = after.match(TOKEN) ?? [];
+  if (a.length * b.length > MAX_CELLS) {
+    const whole: DiffPart[] = [
+      { op: 'del', text: before },
+      { op: 'add', text: after },
+    ];
+    return merge(whole);
+  }
+  // The longest common subsequence, by suffix, so the walk below reads front to back.
+  const lcs: number[][] = Array.from({ length: a.length + 1 }, () => Array.from({ length: b.length + 1 }, () => 0));
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--)
+      lcs[i]![j] = a[i] === b[j] ? lcs[i + 1]![j + 1]! + 1 : Math.max(lcs[i + 1]![j]!, lcs[i]![j + 1]!);
+  }
+
+  const parts: DiffPart[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      parts.push({ op: 'same', text: a[i]! });
+      i++;
+      j++;
+    } else if (lcs[i + 1]![j]! >= lcs[i]![j + 1]!) {
+      parts.push({ op: 'del', text: a[i++]! });
+    } else {
+      parts.push({ op: 'add', text: b[j++]! });
+    }
+  }
+  while (i < a.length) parts.push({ op: 'del', text: a[i++]! });
+  while (j < b.length) parts.push({ op: 'add', text: b[j++]! });
+  return merge(parts);
+}
+
+/**
+ * Adjacent parts of one kind joined, and a space shared by two changes folded into them, so a
+ * replaced phrase reads `[-old words-]{+new words+}` rather than alternating word by word.
+ */
+function merge(parts: DiffPart[]): DiffPart[] {
+  const out: DiffPart[] = [];
+  for (let k = 0; k < parts.length; k++) {
+    const part = parts[k]!;
+    const prev = out.at(-1);
+    const next = parts[k + 1];
+    if (part.op === 'same' && /^\s+$/.test(part.text) && prev && prev.op !== 'same' && next && next.op !== 'same') {
+      // Whitespace between two changes belongs to both.
+      out.push({ op: 'del', text: part.text }, { op: 'add', text: part.text });
+      continue;
+    }
+    out.push({ ...part });
+  }
+  const joined: DiffPart[] = [];
+  for (const part of out.filter((p) => p.text !== '')) {
+    // Gather each stretch of changes as all its deletions, then all its additions.
+    const last = joined.at(-1);
+    if (last && last.op === part.op) last.text += part.text;
+    else if (part.op === 'del' && last?.op === 'add' && joined.at(-2)?.op === 'del') joined.at(-2)!.text += part.text;
+    else joined.push({ ...part });
+  }
+  return joined;
+}
+
+/** The diff as one line: `Save [-the-]{+a+} draft`, the notation of `git diff --word-diff`. */
+export function formatDiff(parts: DiffPart[]): string {
+  return parts.map((p) => (p.op === 'same' ? p.text : p.op === 'del' ? `[-${p.text}-]` : `{+${p.text}+}`)).join('');
+}

package/src/tools/entry.ts

@@ -0,0 +1,325 @@
+/**
+ * One entry as the dev inspector's dialog edits it, in every locale: as fields, or as the YAML written
+ * in its files.
+ *
+ * An edit is checked as the whole catalog, with the edited files read from memory, before anything is
+ * written: a save that would break the build comes back as problems instead, and the dev server never
+ * sees it. Fields are written into the parsed document, so comments, order and quoting elsewhere in the
+ * file stay as they were; YAML replaces the entry's text as typed. A translation left empty is no
+ * translation: one that was there is removed, and the locale falls back.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+import { isMap, isScalar, parseDocument, Scalar, type Document, type YAMLMap } from 'yaml';
+
+import { CatalogError, loadCatalog, type Catalog, type Message, type Problem } from './catalog.ts';
+import type { ResolvedConfig } from './config.ts';
+import { applyEdits, lint, type Edit, type Finding } from './lint.ts';
+
+export interface EntryFields {
+  /** The source message. */
+  message: string;
+  /** By locale. Empty or missing is no translation, so the locale falls back. */
+  translations: Record<string, string>;
+  context: string;
+  kind: string;
+  surface: string;
+  fragment: boolean;
+  /** What each placeholder holds, by name. */
+  args: Record<string, string>;
+  /** A change asked of whoever edits next; empty is none. */
+  comment: string;
+  /** Asks for the entry to go, with the code that reads it. */
+  remove: boolean;
+}
+
+export interface EntryYaml {
+  /** The entry in the catalog, from its key to the end of its value. */
+  catalog: string;
+  /** By locale, the entry in that locale's file. Empty is no translation. */
+  translations?: Record<string, string>;
+}
+
+export interface EntryView {
+  key: string;
+  /** The source locale. */
+  source: string;
+  /** Every translated locale, the source aside. */
+  locales: string[];
+  /** Relative to the project root. A locale without the entry names the file it would go in. */
+  files: { catalog: string; translations: Record<string, string> };
+  /** With every locale in `translations`, empty where it has none. */
+  fields: EntryFields;
+  yaml: Required<EntryYaml>;
+  /** The source message's placeholders. */
+  argNames: string[];
+  kinds: string[];
+  surfaces: string[];
+  /** What lint says of the entry as it stands, in every locale. */
+  findings: EntryFinding[];
+}
+
+export interface EntryFinding extends Finding {
+  /** The locale's text with this finding fixed, so the page can make the fix without lint's code. */
+  fixed?: string;
+}
+
+export type EntryEdit = { fields: EntryFields } | { yaml: EntryYaml };
+
+/** The entry for `key`, with its translation in every locale. */
+export function readEntry(config: ResolvedConfig, key: string): EntryView {
+  return viewOf(config, loadCatalog(config), key, new Map());
+}
+
+/**
+ * Applies an edit and checks the catalog with it. With `write`, a clean edit is written; without, it
+ * only comes back as the view, which is how the dialog turns fields into YAML and back.
+ */
+export function editEntry(config: ResolvedConfig, key: string, edit: EntryEdit, write: boolean): { view?: EntryView; problems: Problem[] } {
+  const current = viewOf(config, loadCatalog(config), key, new Map());
+  const unsaved = new Map<string, string>();
+  const text = (file: string) => contentOf(config, file, unsaved);
+  const put = (file: string, content: string) => unsaved.set(resolve(config.root, file), content);
+  // Locales the edit gives a translation, which the checked catalog must then have.
+  const translated: string[] = [];
+
+  if ('yaml' in edit) {
+    put(current.files.catalog, withSnippet(text(current.files.catalog), key, edit.yaml.catalog));
+    for (const locale of current.locales) {
+      const yaml = edit.yaml.translations?.[locale]?.trim() ?? current.yaml.translations[locale]!;
+      if (yaml !== '') translated.push(locale);
+      if (yaml === current.yaml.translations[locale]) continue;
+      put(current.files.translations[locale]!, withSnippet(text(current.files.translations[locale]!), key, yaml));
+    }
+  } else {
+    put(current.files.catalog, withFields(text(current.files.catalog), key, edit.fields, config.source));
+    for (const locale of current.locales) {
+      const next = edit.fields.translations[locale] ?? '';
+      if (next.trim() !== '') translated.push(locale);
+      if (next === current.fields.translations[locale]) continue;
+      put(current.files.translations[locale]!, withTranslation(text(current.files.translations[locale]!), key, next));
+    }
+  }
+
+  let catalog: Catalog;
+  try {
+    catalog = loadCatalog(config, unsaved);
+  } catch (e) {
+    if (!(e instanceof CatalogError)) throw e;
+    return { problems: e.problems.filter((p) => p.severity === 'error') };
+  }
+  const message = catalog.messages.find((m) => m.key === key);
+  const renamed = [
+    ...(message === undefined ? [current.files.catalog] : []),
+    ...translated.filter((l) => message?.translations.has(l) !== true).map((l) => current.files.translations[l]!),
+  ];
+  if (renamed.length > 0) {
+    const problem = `the entry is still ${key}: rename a key in the code and the catalog together`;
+    return { problems: renamed.map((file) => ({ severity: 'error', file, key, message: problem })) };
+  }
+
+  if (write) {
+    for (const [path, content] of unsaved) {
+      if (existsSync(path) && readFileSync(path, 'utf8') === content) continue;
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, content);
+    }
+  }
+  return { view: viewOf(config, catalog, key, unsaved), problems: [] };
+}
+
+/**
+ * Makes the edits that lint's findings carry, each message in its own file, and writes them only if
+ * the catalog they make loads clean: the problems come back instead, and nothing is written.
+ */
+export function applyFixes(config: ResolvedConfig, catalog: Catalog, findings: Finding[]): { fixed: number; problems: Problem[] } {
+  const unsaved = new Map<string, string>();
+  const entries = new Map<string, { file: string; key: string; locale: string; edits: Edit[]; count: number }>();
+  for (const f of findings) {
+    if (f.fix === undefined) continue;
+    const id = `${f.locale}\u0000${f.key}`;
+    const entry = entries.get(id) ?? { file: f.file, key: f.key, locale: f.locale, edits: [], count: 0 };
+    entry.edits.push(...f.fix);
+    entry.count += 1;
+    entries.set(id, entry);
+  }
+  let fixed = 0;
+  for (const { file, key, locale, edits, count } of entries.values()) {
+    const message = catalog.messages.find((m) => m.key === key);
+    const written = locale === config.source ? message?.text : message?.translations.get(locale)?.text;
+    if (written === undefined) continue;
+    const next = applyEdits(written, edits);
+    if (next === written) continue;
+    const content = contentOf(config, file, unsaved);
+    unsaved.set(
+      resolve(config.root, file),
+      locale === config.source ? withMessage(content, key, next, config.source) : withTranslation(content, key, next),
+    );
+    fixed += count;
+  }
+  try {
+    loadCatalog(config, unsaved);
+  } catch (e) {
+    if (!(e instanceof CatalogError)) throw e;
+    return { fixed: 0, problems: e.problems.filter((p) => p.severity === 'error') };
+  }
+  for (const [path, content] of unsaved) writeFileSync(path, content);
+  return { fixed, problems: [] };
+}
+
+/** A file as the edit has it, as it is on disk, or empty when it is still to be made. */
+function contentOf(config: ResolvedConfig, file: string, unsaved: Map<string, string>): string {
+  const path = resolve(config.root, file);
+  return unsaved.get(path) ?? (existsSync(path) ? readFileSync(path, 'utf8') : '');
+}
+
+/** The file a translation goes in: beside the locale's others, in its folder or its one file. */
+function translationFile(config: ResolvedConfig, message: Message, locale: string): string {
+  const existing = message.translations.get(locale)?.file;
+  if (existing !== undefined) return existing;
+  const folder = join(config.locales, locale);
+  const path = existsSync(folder) && statSync(folder).isDirectory() ? join(folder, `${message.area}.yaml`) : `${folder}.yaml`;
+  return relative(config.root, path).replaceAll('\\', '/');
+}
+
+function viewOf(config: ResolvedConfig, catalog: Catalog, key: string, unsaved: Map<string, string>): EntryView {
+  const message = catalog.messages.find((m) => m.key === key);
+  if (message === undefined) throw new Error(`no entry for "${key}" in the catalog: has it been renamed since the page loaded?`);
+  const files = Object.fromEntries(catalog.locales.map((l) => [l, translationFile(config, message, l)]));
+  return {
+    key,
+    source: config.source,
+    locales: catalog.locales,
+    files: { catalog: message.file, translations: files },
+    fields: {
+      message: message.text,
+      translations: Object.fromEntries(catalog.locales.map((l) => [l, message.translations.get(l)?.text ?? ''])),
+      context: message.context ?? '',
+      kind: message.kind ?? '',
+      surface: message.surface ?? '',
+      fragment: message.fragment,
+      args: Object.fromEntries(message.argDocs),
+      comment: message.comment ?? '',
+      remove: message.remove,
+    },
+    yaml: {
+      catalog: snippetOf(contentOf(config, message.file, unsaved), key)?.text ?? '',
+      translations: Object.fromEntries(catalog.locales.map((l) => [l, snippetOf(contentOf(config, files[l]!, unsaved), key)?.text ?? ''])),
+    },
+    argNames: [...message.args.keys()],
+    kinds: Object.keys(config.kinds),
+    surfaces: Object.keys(config.surfaces),
+    findings: lint([message], config).map((f) => {
+      const written = f.locale === config.source ? message.text : message.translations.get(f.locale)?.text;
+      return f.fix === undefined || written === undefined ? f : { ...f, fixed: applyEdits(written, f.fix) };
+    }),
+  };
+}
+
+/** Where an entry is written: from the start of its key's line to the end of its value. */
+function snippetOf(file: string, key: string): { start: number; end: number; text: string } | undefined {
+  const doc = parseDocument(file);
+  if (!isMap(doc.contents)) return undefined;
+  const pair = doc.contents.items.find((p) => isScalar(p.key) && p.key.value === key);
+  const keyStart = isScalar(pair?.key) ? pair.key.range?.[0] : undefined;
+  const valueEnd = (pair?.value as { range?: [number, number, number] } | null | undefined)?.range?.[1];
+  if (keyStart === undefined || valueEnd === undefined) return undefined;
+  const start = file.lastIndexOf('\n', keyStart - 1) + 1;
+  // The last value in a file runs to its final newline; the snippet stops at the text.
+  const end = start + file.slice(start, valueEnd).trimEnd().length;
+  return { start, end, text: file.slice(start, end) };
+}
+
+/** The file with the entry's text replaced, removed when `yaml` is empty, or added at the end. */
+function withSnippet(file: string, key: string, yaml: string): string {
+  const text = yaml.replace(/\n+$/, '');
+  const at = snippetOf(file, key);
+  if (at !== undefined) {
+    if (text.trim() === '') return file.slice(0, at.start) + file.slice(at.end).replace(/^\n/, '');
+    return file.slice(0, at.start) + text + file.slice(at.end);
+  }
+  if (text.trim() === '') return file;
+  return file.trim() === '' ? `${text}\n` : `${file.replace(/\n*$/, '\n')}${text}\n`;
+}
+
+// As YAML 1.1, so a new value that 1.1 would read differently, like `n`, is quoted (as in migrate.ts).
+// An empty file starts as a plain mapping: under 1.1 a key set on nothing makes an `!!omap`.
+function parse(file: string): Document {
+  const doc: Document = parseDocument(file, { version: '1.1' });
+  if (doc.contents === null) doc.contents = doc.createNode({});
+  return doc;
+}
+// New values quoted the way catalogs are; values already there keep how they were quoted.
+const print = (doc: Document) => doc.toString({ lineWidth: 0, singleQuote: true });
+
+/** A value written where one was, keeping how it was quoted; text over several lines as a block. */
+function setValue(doc: Document, map: YAMLMap, name: string, value: unknown): void {
+  const node = map.get(name, true);
+  if (isScalar(node) && typeof value === 'string') {
+    node.value = value;
+    if (value.includes('\n')) node.type = Scalar.BLOCK_LITERAL;
+    return;
+  }
+  map.set(name, doc.createNode(value));
+}
+
+function withFields(file: string, key: string, fields: EntryFields, source: string): string {
+  const doc = parse(file);
+  let entry = doc.get(key, true);
+  // `key: message` gains a mapping once it has anything to say about itself.
+  if (!isMap(entry)) {
+    entry = doc.createNode({ [source]: fields.message });
+    doc.set(key, entry);
+  }
+  const map = entry as YAMLMap;
+  const args = Object.fromEntries(Object.entries(fields.args).filter(([, v]) => v.trim() !== ''));
+  const wanted: [string, unknown][] = [
+    ['kind', fields.kind.trim() || undefined],
+    ['surface', fields.surface.trim() || undefined],
+    ['context', fields.context.trim() || undefined],
+    ['args', Object.keys(args).length > 0 ? args : undefined],
+    ['fragment', fields.fragment || undefined],
+    ['comment', fields.comment.trim() || undefined],
+    ['remove', fields.remove || undefined],
+  ];
+  for (const [name, value] of wanted) {
+    if (value === undefined) {
+      map.delete(name);
+      continue;
+    }
+    if (map.has(name)) {
+      setValue(doc, map, name, value);
+      continue;
+    }
+    // A field the entry didn't have goes before the message, where the others are.
+    const at = map.items.findIndex((p) => isScalar(p.key) && p.key.value === source);
+    map.items.splice(at === -1 ? map.items.length : at, 0, doc.createPair(name, value));
+  }
+  setValue(doc, map, source, fields.message);
+  return print(doc);
+}
+
+/** The source message replaced, and nothing else: a `key: message` entry stays one. */
+function withMessage(file: string, key: string, message: string, source: string): string {
+  const doc = parse(file);
+  const entry = doc.get(key, true);
+  if (!isMap(entry)) return withTranslation(file, key, message);
+  setValue(doc, entry, source, message);
+  return print(doc);
+}
+
+function withTranslation(file: string, key: string, translation: string): string {
+  const doc = parse(file);
+  const node = doc.get(key, true);
+  if (translation.trim() === '') {
+    doc.delete(key);
+  } else if (isScalar(node)) {
+    node.value = translation;
+    if (translation.includes('\n')) node.type = Scalar.BLOCK_LITERAL;
+  } else {
+    doc.set(key, translation);
+  }
+  // A file left with nothing in it reads as no translations, not as `{}`.
+  return isMap(doc.contents) && doc.contents.items.length === 0 ? '' : print(doc);
+}