prosebook 0.0.1 → 0.2.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 } }),
+    },
+  };
+}