prosebook 0.0.1 → 0.1.0

package/src/tools/migrate.ts

@@ -0,0 +1,138 @@
+/**
+ * `prosebook migrate`: a catalog and its translations rewritten from one syntax to the other. Each
+ * message is written in the target syntax, read back, and rendered both ways over sample values, so
+ * one that can't be written, or would come out different, is reported before anything changes.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { isMap, parseDocument, Scalar } from 'yaml';
+
+import { createHelpers, flatten } from '#src/runtime/helpers.ts';
+import type { CompiledMessages } from '#src/runtime/types.ts';
+
+import { loadCatalog } from './catalog.ts';
+import { compileLocale, localeExpression } from './compile.ts';
+import type { ResolvedConfig } from './config.ts';
+import { argsOf, tagsOf, type MessageFormatElement } from './icu.ts';
+import { readMessage, writeMessage, type MessageFormatVersion } from './syntax.ts';
+
+interface Located {
+  key: string;
+  locale: string;
+  /** The file, relative to the project root. */
+  file: string;
+}
+
+export interface MigratePlan {
+  to: MessageFormatVersion;
+  rewrites: (Located & { before: string; after: string })[];
+  /** Messages the target syntax can't say, and why. Nothing is written while there are any. */
+  blocked: (Located & { reason: string })[];
+  /** Messages that would render differently, with the first values that show it. */
+  changed: (Located & { values: string; before: string; after: string })[];
+}
+
+export function planMigrate(config: ResolvedConfig, to: MessageFormatVersion): MigratePlan {
+  const catalog = loadCatalog(config);
+  const plan: MigratePlan = { to, rewrites: [], blocked: [], changed: [] };
+  for (const m of catalog.messages) {
+    const versions = [
+      { locale: config.source, text: m.text, ast: m.ast, file: m.file },
+      ...[...m.translations].map(([locale, t]) => ({ locale, text: t.text, ast: t.ast, file: t.file })),
+    ];
+    for (const { locale, text, ast, file } of versions) {
+      const at = { key: m.key, locale, file };
+      let after: string;
+      let back: MessageFormatElement[];
+      try {
+        after = writeMessage(to, ast, locale);
+        back = readMessage(to, after, locale);
+      } catch (e) {
+        plan.blocked.push({ ...at, reason: (e as Error).message });
+        continue;
+      }
+      const difference = firstDifference(ast, back, locale);
+      if (difference !== undefined) plan.changed.push({ ...at, ...difference });
+      if (after !== text) plan.rewrites.push({ ...at, before: text, after });
+    }
+  }
+  return plan;
+}
+
+/** Writes the plan's rewrites into the YAML files, keeping their comments and layout. Returns the files written. */
+export function applyMigrate(config: ResolvedConfig, plan: MigratePlan): string[] {
+  if (plan.blocked.length > 0) throw new Error('prosebook: some messages have no equivalent in the target syntax; nothing was written');
+  const byFile = Map.groupBy(plan.rewrites, (r) => r.file);
+  for (const [file, rewrites] of byFile) {
+    const path = join(config.root, file);
+    // As YAML 1.1, so a new value that 1.1 would read differently, like `n`, is quoted.
+    const doc = parseDocument(readFileSync(path, 'utf8'), { version: '1.1' });
+    for (const r of rewrites) {
+      const value = doc.createNode(r.after);
+      if (r.after.includes('\n')) value.type = Scalar.BLOCK_LITERAL;
+      const entry = doc.get(r.key, true);
+      if (isMap(entry)) entry.set(config.source, value);
+      else doc.set(r.key, value);
+    }
+    writeFileSync(path, doc.toString({ lineWidth: 0 }));
+  }
+  return [...byFile.keys()];
+}
+
+const NUMBERS = [0, 1, 2, 3, 5, 11, 21, 101, 1.5, 1234.5];
+const DATE = new Date(Date.UTC(2026, 0, 5, 14, 30, 15));
+
+function samplesOf(type: string): unknown[] {
+  if (type === 'number') return NUMBERS;
+  if (type === 'Date | number') return [DATE];
+  const named = [...type.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => JSON.parse(`"${m[1]}"`) as string);
+  return named.length > 0 ? [...named, 'zzz'] : ['Ada'];
+}
+
+/** Every combination of sample values, or each argument varied alone where there are too many. */
+function* samples(a: MessageFormatElement[], b: MessageFormatElement[]): Generator<Record<string, unknown>> {
+  const types = new Map<string, Set<unknown>>();
+  for (const [name, type] of [...argsOf(a), ...argsOf(b)]) {
+    const set = types.get(name) ?? new Set();
+    for (const value of samplesOf(type)) set.add(value);
+    types.set(name, set);
+  }
+  const tags = Object.fromEntries(
+    [...new Set([...tagsOf(a), ...tagsOf(b)])].map((t) => [t, (c: unknown[]) => `<${t}>${c.join('')}</${t}>`]),
+  );
+  const names = [...types.keys()];
+  const lists = names.map((n) => [...types.get(n)!]);
+  if (lists.reduce((n, l) => n * l.length, 1) <= 1000) {
+    let combos: unknown[][] = [[]];
+    for (const list of lists) combos = combos.flatMap((c) => list.map((v) => [...c, v]));
+    for (const combo of combos) yield { ...tags, ...Object.fromEntries(names.map((n, i) => [n, combo[i]])) };
+    return;
+  }
+  const base = Object.fromEntries(names.map((n, i) => [n, lists[i]![0]]));
+  for (const [i, n] of names.entries()) for (const value of lists[i]!) yield { ...tags, ...base, [n]: value };
+}
+
+function renderer(ast: MessageFormatElement[], locale: string): (values: Record<string, unknown>) => string {
+  // oxlint-disable-next-line no-new-func, typescript/no-implied-eval -- evaluating our own compiled message, as the bundle would
+  const messages = new Function(`return ${localeExpression(compileLocale([['m', ast]]))};`)() as CompiledMessages;
+  const message = messages.m!;
+  const h = createHelpers(locale);
+  return (values) => (typeof message === 'string' ? message : flatten(message(values, h)).join(''));
+}
+
+function firstDifference(a: MessageFormatElement[], b: MessageFormatElement[], locale: string) {
+  const before = renderer(a, locale);
+  const after = renderer(b, locale);
+  for (const values of samples(a, b)) {
+    const x = before(values);
+    const y = after(values);
+    if (x !== y) {
+      const shown = Object.entries(values)
+        .filter(([, v]) => typeof v !== 'function')
+        .map(([k, v]) => `${k}: ${v instanceof Date ? v.toISOString() : JSON.stringify(v)}`);
+      return { values: `{ ${shown.join(', ')} }`, before: x, after: y };
+    }
+  }
+  return undefined;
+}

package/src/tools/presets.ts

@@ -0,0 +1,159 @@
+/**
+ * The defaults: four kinds of string, the surfaces they sit on, and the word lists of the strict lint preset.
+ *
+ * The kinds are the four any UI writing guide comes down to. A name identifies, an action says what
+ * pressing it does, a description adds what the name cannot carry, a state reports what is true.
+ * Each carries a budget and a grammar, which is what makes a mechanical check of the words possible.
+ */
+export type Severity = 'error' | 'warn' | 'off';
+
+export interface KindRule {
+  /** What the kind is for, shown when an editor completes it. */
+  doc: string;
+  /** The most words it may have. Articles, short prepositions and asides in parentheses are free. */
+  maxWords?: number;
+  /** The most sentences it may have, and per surface where that differs. */
+  maxSentences?: number;
+  maxSentencesOn?: Record<string, number>;
+  /** Whether it ends with a period: always, never, or only on the surfaces listed. */
+  period?: 'always' | 'never' | string[];
+  /** Capitalizes only its first word and proper nouns. */
+  sentenceCase?: boolean;
+  /** Carries no explanation after a dash or colon: `Quick capture`, not `Quick capture: choose an area`. */
+  bare?: boolean;
+}
+
+export const DEFAULT_KINDS: Record<string, KindRule> = {
+  name: {
+    doc: 'Identifies a thing so it can be found again. One to four words, a noun phrase, no period.',
+    maxWords: 4,
+    period: 'never',
+    sentenceCase: true,
+    bare: true,
+  },
+  action: {
+    doc: 'Says what pressing it does. One to three words, verb first, no period.',
+    maxWords: 3,
+    period: 'never',
+    sentenceCase: true,
+  },
+  description: {
+    doc: 'Adds only what the name cannot carry. One sentence, two at most, with a period.',
+    maxSentences: 2,
+    period: 'always',
+  },
+  state: {
+    doc: 'Reports what is true right now. One sentence, present tense; on an error or empty state, one more saying what to do.',
+    maxSentences: 1,
+    maxSentencesOn: { error: 2, empty: 2, hint: 2, status: 2 },
+    period: ['hint', 'status', 'error', 'empty', 'confirm'],
+  },
+};
+
+export const DEFAULT_SURFACES: Record<string, string> = {
+  action: 'The text of a button or a menu entry.',
+  aria: 'Reached only by a screen reader, so nothing on screen carries it.',
+  choice: 'One option among a set offered together.',
+  confirm: 'The question of a confirmation, or the verb that answers it.',
+  empty: 'Fills a list or a panel that has nothing in it.',
+  error: 'Says what failed.',
+  heading: 'Heads a section, group, dialog or list.',
+  hint: 'A subordinate line under the thing it qualifies.',
+  label: 'Names a control, a field, a section or a destination.',
+  placeholder: 'Sits inside an empty field, and goes when typing starts.',
+  status: 'Reports what is true right now, on a badge or beside a row.',
+  title: 'The title of a page, window or document.',
+  toast: 'A notification that comes and goes.',
+  tooltip: 'Appears on hover.',
+};
+
+/** The word lists of the strict preset: filler, marketing and reassurance, and American spelling. */
+export const STRICT_LISTS = {
+  banned: [
+    {
+      words: ['seamless', 'seamlessly', 'effortless', 'effortlessly', 'hassle-free', 'frictionless'],
+      why: 'promises a feeling rather than saying what happens',
+    },
+    {
+      words: ['leverage', 'leverages', 'leveraging', 'utilize', 'utilizes', 'utilizing', 'harness', 'take advantage of'],
+      why: 'is a long way to say use',
+    },
+    {
+      words: [
+        'delve',
+        'dive into',
+        'deep dive',
+        'embark',
+        'journey',
+        'tapestry',
+        'realm',
+        'landscape',
+        'testament',
+        'synergy',
+        'paradigm',
+        'holistic',
+      ],
+      why: 'is filler, not a thing on the screen',
+    },
+    {
+      words: [
+        'robust',
+        'powerful',
+        'cutting-edge',
+        'state-of-the-art',
+        'best-in-class',
+        'world-class',
+        'next-generation',
+        'revolutionary',
+        'game-changing',
+      ],
+      why: 'is marketing: say what it does',
+    },
+    {
+      words: ['streamline', 'streamlined', 'empower', 'unlock', 'unleash', 'elevate', 'supercharge', 'boost', 'enhance', 'enhanced'],
+      why: 'claims an improvement without naming it',
+    },
+    { words: ['meticulous', 'crucial', 'pivotal', 'vital', 'paramount'], why: 'tells the reader how to feel instead of what it is' },
+    {
+      words: ['comprehensive', 'myriad', 'plethora', 'a variety of', 'a wide range of'],
+      why: 'is padding: name the things, or say how many',
+    },
+    {
+      words: ['furthermore', 'moreover', 'additionally', 'in order to', 'please note', 'note that', 'keep in mind', 'rest assured'],
+      why: 'is a connective a short string has no room for',
+    },
+    { words: ['intuitive', 'sleek', 'stunning', 'beautiful', 'delightful', 'magical'], why: 'grades the product instead of describing it' },
+    { words: ['simply', 'just', 'easily', 'easy', 'quickly'], why: 'says it is easy, which helps nobody it is not easy for' },
+    { words: ['so you can', 'allows you to', 'lets you', 'enables you to', "don't worry"], why: 'justifies or reassures: state the fact' },
+    { words: ['please', 'oops', 'whoops', 'sorry'], why: 'pleads or apologizes: say what failed and what to do' },
+    { words: ['etc', 'and more', 'and so on'], why: 'trails off: name the things or stop' },
+  ],
+  spelling: {
+    colour: 'color',
+    colours: 'colors',
+    behaviour: 'behavior',
+    favourite: 'favorite',
+    cancelled: 'canceled',
+    cancelling: 'canceling',
+    labelled: 'labeled',
+    centre: 'center',
+    licence: 'license',
+    grey: 'gray',
+    organise: 'organize',
+    recognise: 'recognize',
+    customise: 'customize',
+    optimise: 'optimize',
+    minimise: 'minimize',
+    maximise: 'maximize',
+    synchronise: 'synchronize',
+    authorise: 'authorize',
+    initialise: 'initialize',
+    analyse: 'analyze',
+    catalogue: 'catalog',
+    dialogue: 'dialog',
+    artefact: 'artifact',
+    judgement: 'judgment',
+    whilst: 'while',
+    amongst: 'among',
+  } as Record<string, string>,
+};

package/src/tools/pseudo.ts

@@ -0,0 +1,40 @@
+/**
+ * Pseudo-localization: the source with every letter accented, vowels doubled for the length a
+ * translation usually adds, and brackets around the whole. A screen in the pseudo-locale shows at a
+ * glance which text is hardcoded (it is plain), which is clipped (a bracket is missing), and which
+ * splices fragments together (brackets inside brackets).
+ */
+import { TYPE, type MessageFormatElement } from './icu.ts';
+
+const PLAIN = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const ACCENTED = Array.from('áƀçðéƒĝĥíĵķļɱñóþǫŕšţúṽŵẋýžÁƁÇÐÉƑĜĤÍĴĶĻṀÑÓÞǪŔŠŢÚṼŴẊÝŽ');
+
+export function pseudoText(text: string): string {
+  return text.replace(/[A-Za-z]/g, (c) => {
+    const accented = ACCENTED[PLAIN.indexOf(c)]!;
+    return /[aeiou]/i.test(c) ? accented.repeat(2) : accented;
+  });
+}
+
+function transform(elements: MessageFormatElement[]): MessageFormatElement[] {
+  return elements.map((el) => {
+    if (el.type === TYPE.literal) return { ...el, value: pseudoText(el.value) };
+    if (el.type === TYPE.tag) return { ...el, children: transform(el.children) };
+    if (el.type === TYPE.select || el.type === TYPE.plural) {
+      const options = Object.fromEntries(Object.entries(el.options).map(([arm, o]) => [arm, { ...o, value: transform(o.value) }]));
+      return { ...el, options };
+    }
+    return el;
+  });
+}
+
+export function pseudoAst(ast: MessageFormatElement[]): MessageFormatElement[] {
+  const out: MessageFormatElement[] = [];
+  // Adjacent literals are joined, so a message with no placeholders still compiles to a plain string.
+  for (const el of [{ type: TYPE.literal, value: '⟦' }, ...transform(ast), { type: TYPE.literal, value: '⟧' }] as MessageFormatElement[]) {
+    const last = out.at(-1);
+    if (el.type === TYPE.literal && last?.type === TYPE.literal) out[out.length - 1] = { ...last, value: last.value + el.value };
+    else out.push(el);
+  }
+  return out;
+}

package/src/tools/sarif.ts

@@ -0,0 +1,80 @@
+/**
+ * Findings as SARIF 2.1.0, the static-analysis format code scanning reads (GitHub's among them), so
+ * `lint`, `scan`, `status` and `check` can annotate a pull request on the line the string is written.
+ *
+ * Paths are relative to the project root under `%SRCROOT%`, which the log maps to the root itself:
+ * a project that isn't at the top of its repository still resolves to the right files.
+ */
+import { pathToFileURL } from 'node:url';
+
+export interface SarifResult {
+  /** A rule the report describes, or one of a lint plugin's. */
+  rule: string;
+  level: 'error' | 'warning';
+  message: string;
+  /** Relative to the project root, with forward slashes; none for a problem that isn't in a file. */
+  file?: string;
+  /** From 1; none for the file as a whole. */
+  line?: number;
+  column?: number;
+}
+
+export interface SarifTool {
+  name: string;
+  version: string;
+  informationUri: string;
+}
+
+/** Collects what a command found, then writes it as one SARIF run. */
+export class SarifReport {
+  readonly results: SarifResult[] = [];
+  private readonly rules = new Map<string, string | undefined>();
+
+  /** Describes a rule in one sentence; the first description given for an id stands. */
+  rule(id: string, description?: string): void {
+    if (this.rules.get(id) === undefined) this.rules.set(id, description);
+  }
+
+  add(result: SarifResult): void {
+    if (!this.rules.has(result.rule)) this.rules.set(result.rule, undefined);
+    this.results.push(result);
+  }
+
+  toJSON(root: string, tool: SarifTool): object {
+    const ids = [...this.rules.keys()];
+    return {
+      $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+      version: '2.1.0',
+      runs: [
+        {
+          tool: {
+            driver: {
+              ...tool,
+              rules: ids.map((id) => {
+                const description = this.rules.get(id);
+                return description === undefined ? { id } : { id, shortDescription: { text: description } };
+              }),
+            },
+          },
+          originalUriBaseIds: { '%SRCROOT%': { uri: pathToFileURL(root).href.replace(/\/?$/, '/') } },
+          results: this.results.map((r) => ({
+            ruleId: r.rule,
+            ruleIndex: ids.indexOf(r.rule),
+            level: r.level,
+            message: { text: r.message },
+            locations: r.file === undefined ? [] : [location(r.file, r.line, r.column)],
+          })),
+        },
+      ],
+    };
+  }
+}
+
+function location(file: string, line: number | undefined, column: number | undefined): object {
+  return {
+    physicalLocation: {
+      artifactLocation: { uri: encodeURI(file), uriBaseId: '%SRCROOT%' },
+      ...(line === undefined ? {} : { region: { startLine: line, startColumn: column ?? 1 } }),
+    },
+  };
+}

package/src/tools/scan.ts

@@ -0,0 +1,173 @@
+/**
+ * What the code says: text a person reads that is still written in a component, and which catalog
+ * keys the code names.
+ *
+ * Key references are found by reading string literals, not by tracing calls, so a key kept in an
+ * array or a map still counts, and `nav.${id}` or `'nav.' + id` keeps every key under `nav.`. That
+ * errs towards keeping a key, which is the safe direction both for `unused` and for pruning a bundle.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+
+import { parseSync } from 'oxc-parser';
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'out', 'coverage', '.git']);
+
+export function sourceFiles(dirs: string[], extensions: string[], skip: string[] = []): string[] {
+  const files: string[] = [];
+  const visit = (dir: string) => {
+    let names: string[];
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const path = join(dir, name);
+      if (skip.some((s) => path === s || path.startsWith(`${s}/`) || path.startsWith(`${s}\\`))) continue;
+      if (statSync(path).isDirectory()) {
+        if (!SKIP_DIRS.has(name) && !name.startsWith('.')) visit(path);
+      } else if (extensions.includes(extname(name)) && !name.endsWith('.d.ts')) {
+        files.push(path);
+      }
+    }
+  };
+  for (const dir of dirs) visit(dir);
+  return files.sort();
+}
+
+export interface KeyRefs {
+  exact: Set<string>;
+  /** `nav.` from `nav.${id}` or `'nav.' + id`: every key under it may be read. */
+  prefixes: Set<string>;
+}
+
+const LITERAL_KEY = /(['"`])([a-z0-9][\w-]*(?:\.[\w-]+)+)\1/g;
+const KEY_PREFIX = /(['"`])([a-z0-9][\w-]*(?:\.[\w-]+)*\.)(?:\1|\$\{)/g;
+
+export function keyRefs(code: string, into: KeyRefs = { exact: new Set(), prefixes: new Set() }): KeyRefs {
+  for (const m of code.matchAll(LITERAL_KEY)) into.exact.add(m[2]!);
+  for (const m of code.matchAll(KEY_PREFIX)) into.prefixes.add(m[2]!);
+  return into;
+}
+
+export function isReferenced(key: string, refs: KeyRefs): boolean {
+  if (refs.exact.has(key)) return true;
+  for (const prefix of refs.prefixes) if (key.startsWith(prefix)) return true;
+  return false;
+}
+
+export interface Hardcoded {
+  file: string;
+  line: number;
+  column: number;
+  text: string;
+  /** Where it sits: `text`, or the attribute it is the value of. */
+  where: string;
+}
+
+type Node = { type: string; start: number; end: number; [field: string]: unknown };
+
+/**
+ * Text that reads as code rather than prose: one token holding a path, a call, an identifier with an
+ * underscore or a dotted name, as in `form.json()` or `src/index.ts`. Trailing punctuation doesn't
+ * count, so `Done.` is still prose.
+ */
+export function looksLikeCode(text: string): boolean {
+  const token = text.trim().replace(/[.!?:,…]+$/, '');
+  return token !== '' && !/\s/.test(token) && /[/()_=<>{}[\].]|::/.test(token);
+}
+
+const NON_PROSE_ELEMENTS = new Set(['code', 'pre', 'kbd', 'samp', 'script', 'style', 'svg', 'path']);
+const LETTER = /\p{L}/u;
+
+/** Literal text in JSX that a person reads, where it should be a catalog entry. */
+export function hardcodedText(file: string, code: string, attributes: string[]): Hardcoded[] {
+  const { program } = parseSync(file, code);
+  const found: Hardcoded[] = [];
+  const lines = code.split('\n');
+  const lineStarts: number[] = [];
+  let offset = 0;
+  for (const line of lines) {
+    lineStarts.push(offset);
+    offset += line.length + 1;
+  }
+  const position = (at: number) => {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (lineStarts[mid]! <= at) lo = mid;
+      else hi = mid - 1;
+    }
+    return { line: lo + 1, column: at - lineStarts[lo]! + 1 };
+  };
+  const ignored = (line: number) =>
+    (lines[line - 1] ?? '').includes('prosebook-ignore') || (lines[line - 2] ?? '').includes('prosebook-ignore');
+  const report = (node: Node, text: string, where: string) => {
+    const trimmed = text.replace(/\s+/g, ' ').trim();
+    if (!LETTER.test(trimmed) || looksLikeCode(trimmed)) return;
+    const at = position(node.start + Math.max(0, code.slice(node.start, node.end).search(/\S/)));
+    if (ignored(at.line)) return;
+    found.push({ file, ...at, text: trimmed, where });
+  };
+
+  const visit = (node: Node, inProse: boolean) => {
+    let prose = inProse;
+    if (node.type === 'JSXElement') {
+      const opening = node.openingElement as Node & { name: Node & { name?: string } };
+      if (opening.name.type === 'JSXIdentifier' && NON_PROSE_ELEMENTS.has(opening.name.name ?? '')) prose = false;
+    }
+    if (node.type === 'JSXText' && prose) report(node, node.value as string, 'text');
+    if (node.type === 'JSXExpressionContainer' && prose) {
+      const expr = node.expression as Node;
+      if (expr.type === 'Literal' && typeof expr.value === 'string') report(expr, expr.value, 'text');
+      if (expr.type === 'TemplateLiteral' && (expr.expressions as Node[]).length === 0)
+        report(expr, String((expr.quasis as { value: { cooked: string } }[])[0]?.value.cooked), 'text');
+    }
+    if (node.type === 'JSXAttribute') {
+      const name = node.name as Node & { name?: string };
+      const value = node.value as Node | null;
+      const attr = name.type === 'JSXIdentifier' ? (name.name ?? '') : '';
+      if (attributes.includes(attr) && value !== null) {
+        if (value.type === 'Literal' && typeof value.value === 'string') report(value, value.value, attr);
+        if (value.type === 'JSXExpressionContainer') {
+          const expr = value.expression as Node;
+          if (expr.type === 'Literal' && typeof expr.value === 'string') report(expr, expr.value, attr);
+        }
+      }
+      return;
+    }
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) {
+        for (const child of value) if (isNode(child)) visit(child, prose);
+      } else if (isNode(value)) {
+        visit(value, prose);
+      }
+    }
+  };
+  visit(program as unknown as Node, true);
+  return found;
+}
+
+function isNode(value: unknown): value is Node {
+  return typeof value === 'object' && value !== null && typeof (value as Node).type === 'string';
+}
+
+export interface ScanResult {
+  hardcoded: Hardcoded[];
+  refs: KeyRefs;
+  files: number;
+}
+
+export function scan(dirs: string[], extensions: string[], attributes: string[], root: string, skip: string[] = []): ScanResult {
+  const refs: KeyRefs = { exact: new Set(), prefixes: new Set() };
+  const hardcoded: Hardcoded[] = [];
+  const files = sourceFiles(dirs, extensions, skip);
+  for (const path of files) {
+    const code = readFileSync(path, 'utf8');
+    keyRefs(code, refs);
+    if (/\.[jt]sx$/.test(path)) hardcoded.push(...hardcodedText(relative(root, path).replaceAll('\\', '/'), code, attributes));
+  }
+  return { hardcoded, refs, files: files.length };
+}

package/src/tools/syntax.ts

@@ -0,0 +1,24 @@
+/**
+ * The two syntaxes a catalog can be written in, behind one pair of calls: read a message into the
+ * element tree, and write a tree back out. Everything past reading works on the tree alone.
+ */
+import { parseMessage, type MessageFormatElement } from './icu.ts';
+import { toMf1 } from './mf1.ts';
+import { parseMf2, toMf2 } from './mf2.ts';
+
+export type MessageFormatVersion = 1 | 2;
+
+export const SYNTAX_NAME: Record<MessageFormatVersion, string> = { 1: 'ICU MessageFormat', 2: 'MessageFormat 2' };
+
+/**
+ * A message as the element tree. MF2 is read per locale: which variants a value can reach depends
+ * on the locale's plural rules (see `matchTree` in mf2.ts).
+ */
+export function readMessage(version: MessageFormatVersion, text: string, locale: string): MessageFormatElement[] {
+  return version === 2 ? parseMf2(text, locale) : parseMessage(text);
+}
+
+/** A tree as text in the given syntax. Throws, saying what the syntax can't express, where it can't. */
+export function writeMessage(version: MessageFormatVersion, ast: MessageFormatElement[], locale: string): string {
+  return version === 2 ? toMf2(ast, locale) : toMf1(ast);
+}