prosebook 0.2.0 → 0.4.0

package/src/tools/native/android.ts

@@ -0,0 +1,201 @@
+/**
+ * The catalog as Android string resources: `values/<name>.xml` for the source and
+ * `values-<qualifier>/<name>.xml` for every other locale, each holding what that locale shows, every
+ * fallback resolved. An app with the Kotlin target still needs these: its manifest, shortcuts and
+ * other XML resources name strings as `@string/…`, which only a resource answers.
+ *
+ * Android fills values in with `String.format` and picks a plural's arm itself, from its own CLDR
+ * rules, so this takes a narrower subset than the other targets, written straight from the ICU tree:
+ * text, plain `{name}` placeholders, and one cardinal plural, with the text around it in each arm.
+ */
+import { join } from 'node:path';
+
+import type { Catalog, Message, Problem } from '#src/tools/catalog.ts';
+import type { Entry } from '#src/tools/compile.ts';
+import type { NativeTarget } from '#src/tools/config.ts';
+import { selectionOf, TYPE, type MessageFormatElement } from '#src/tools/icu.ts';
+import { checkNames, leading, snake } from './emit.ts';
+import { fileOf, foundIn, LEAVE_OUT, wordsFor } from './model.ts';
+import { formatString, noteOf, type Printf } from './printf.ts';
+
+const KEYWORDS = new Set(
+  'abstract assert boolean break byte case catch char class const continue default do double else enum extends false final finally float for goto if implements import instanceof int interface long native new null package private protected public return short static strictfp super switch synchronized this throw throws transient true try void volatile while'.split(
+    ' ',
+  ),
+);
+
+/**
+ * A locale as Android's resource qualifier: `de`, `pt-rBR`, and BCP 47's own form, `b+sr+Latn`,
+ * past what the old form holds (a script, a numeric region, a variant).
+ */
+export function qualifierOf(locale: string): string {
+  const [language = '', ...rest] = locale.split(/[-_]/);
+  const subtags = [
+    language.toLowerCase(),
+    ...rest.map((s) =>
+      s.length === 4 && /^[a-z]+$/i.test(s)
+        ? s.charAt(0).toUpperCase() + s.slice(1).toLowerCase()
+        : s.length === 2
+          ? s.toUpperCase()
+          : s.toLowerCase(),
+    ),
+  ];
+  const old = /^[a-z]{2,3}$/.test(subtags[0]!) && (rest.length === 0 || (rest.length === 1 && /^[A-Z]{2}$/.test(subtags[1]!)));
+  if (!old) return `b+${subtags.join('+')}`;
+  return rest.length === 0 ? subtags[0]! : `${subtags[0]}-r${subtags[1]}`;
+}
+
+/** Whitespace as aapt2 reads it: collapsed to one space, and trimmed at the ends, outside double quotes. */
+const LOOSE = /^[ \t\n\v\f\r]|[ \t\n\v\f\r]$|[ \t\n\v\f\r]{2}/;
+
+/**
+ * Text as a resource holds it: XML's escapes, then Android's (`\`, `'`, `"`, a newline or a tab).
+ * In a string that is formatted, `%` is doubled, so `String.format` writes one.
+ */
+function escape(text: string, formatted: boolean): string {
+  const out = text
+    .replaceAll('\\', '\\\\')
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll("'", "\\'")
+    .replaceAll('"', '\\"')
+    .replaceAll('\n', '\\n')
+    .replaceAll('\t', '\\t');
+  return formatted ? out.replaceAll('%', '%%') : out;
+}
+
+/**
+ * A whole value: a leading `@` or `?` escaped, since either would make it a reference, and the value
+ * quoted where its spaces would otherwise be collapsed or trimmed.
+ */
+function value(written: string): string {
+  const out = /^[@?]/.test(written) ? `\\${written}` : written;
+  return LOOSE.test(out) ? `"${out}"` : out;
+}
+
+const PRINTF: Printf = {
+  platform: 'Android',
+  formatter: 'String.format',
+  holder: 'Android resources',
+  string: 's',
+  escape,
+  plural: (name) =>
+    `{${name}} is a second plural in the message, and Android's <plurals> picks on one count: split it into a key per count, ${LEAVE_OUT}`,
+};
+
+/**
+ * A message as `<string>`, or `<plurals>` when it holds a plural. Android's picks between whole
+ * messages, so the text around the plural goes into each arm: the pseudo-locale's brackets, or a
+ * sentence the plural ends.
+ */
+function resource(name: string, ast: MessageFormatElement[], args: string[]): string {
+  const at = ast.findIndex((el) => el.type === TYPE.plural);
+  const plural = ast[at];
+  if (plural?.type !== TYPE.plural) {
+    const written = formatString(ast, args, PRINTF);
+    // Unformatted, `%` is written as it is, which aapt2 refuses where it reads as two placeholders.
+    const raw = args.length === 0 && written.includes('%') ? ' formatted="false"' : '';
+    return `    <string name="${name}"${raw}>${value(written)}</string>`;
+  }
+  const [before, after] = [ast.slice(0, at), ast.slice(at + 1)];
+  const named = `{${plural.value}}`;
+  if (plural.pluralType === 'ordinal') {
+    throw new Error(
+      `${named} is an ordinal, and Android's <plurals> are cardinal only: write a key per case and pick one in code, ${LEAVE_OUT}`,
+    );
+  }
+  if (plural.offset !== 0) {
+    throw new Error(
+      `${named} has an offset, which Android's <plurals> don't: count without it, and say the rest in each arm, ${LEAVE_OUT}`,
+    );
+  }
+  const selection = selectionOf(plural);
+  if (selection !== undefined && (selection.fn.name !== 'integer' || Object.keys(selection.fn.options).length > 0)) {
+    throw new Error(
+      `${named} selects with :${selection.fn.name} and its options, and Android selects on the count as an integer: select with a bare :number or :integer, ${LEAVE_OUT}`,
+    );
+  }
+  const exact = Object.keys(plural.options).filter((k) => k.startsWith('='));
+  if (exact.length > 0) {
+    throw new Error(
+      `${named} has the arm ${exact.join(', ')}, and Android's <plurals> have none for one number (its zero is a category, which most languages never pick): say it in a category's arm, or write a key for it and pick that in code, ${LEAVE_OUT}`,
+    );
+  }
+  const items = Object.entries(plural.options).map(
+    ([category, option]) =>
+      `        <item quantity="${category}">${value(formatString([...before, ...option.value, ...after], args, PRINTF, plural.value))}</item>`,
+  );
+  return `    <plurals name="${name}">\n${items.join('\n')}\n    </plurals>`;
+}
+
+/** The context and what each argument holds, as the comment above an entry. */
+function comment(m: Message): string {
+  const said = noteOf(m);
+  // `--` ends a comment early, so XML refuses it inside one.
+  return said === '' ? '' : `    <!-- ${said.replace(/-{2,}/g, '-')} -->\n`;
+}
+
+/** The files `target` writes, by path, or a problem for every message it can't hold. */
+export function androidResources(
+  target: NativeTarget & { name: string },
+  catalog: Catalog,
+  locales: string[],
+  entries: Map<string, Entry[]>,
+  banner: string,
+): { files: Map<string, string>; problems: Problem[] } {
+  const source = locales[0]!;
+  const asts = new Map([...entries].map(([locale, list]) => [locale, new Map(list)]));
+  const taken = catalog.messages.flatMap((m) => {
+    const words = wordsFor(target, m.key);
+    return words === undefined ? [] : [{ m, name: leading(snake(words)) }];
+  });
+  checkNames(
+    'android',
+    taken.map(({ m, name }) => [m.key, name]),
+    [],
+  );
+  const problems = taken
+    .filter((t) => KEYWORDS.has(t.name))
+    .map(({ m, name }): Problem => ({
+      severity: 'error',
+      file: m.file,
+      key: m.key,
+      message: `android: ${m.key} is named ${name}, which Java keeps for itself: rename it`,
+    }));
+
+  const bodies = new Map<string, string[]>(locales.map((l) => [l, []]));
+  const failed = new Set<string>();
+  for (const { m, name } of taken) {
+    const args = [...m.args.keys()];
+    const written = new Map<string, string>();
+    for (const locale of locales) {
+      const found = foundIn(m.key, locale, locales, asts);
+      if (failed.has(m.key)) break;
+      if (found === undefined) continue;
+      let entry = written.get(found);
+      if (entry === undefined) {
+        try {
+          entry = `${comment(m)}${resource(name, asts.get(found)!.get(m.key)!, args)}`;
+        } catch (e) {
+          failed.add(m.key);
+          problems.push({ severity: 'error', file: fileOf(m, found, source), key: m.key, message: `android: ${(e as Error).message}` });
+          continue;
+        }
+        written.set(found, entry);
+      }
+      bodies.get(locale)!.push(entry);
+    }
+  }
+
+  const head = `<!-- ${banner.replace(/^\/\/ /, '')} -->`;
+  const files = new Map(
+    locales.map((locale) => {
+      const folder = locale === source ? 'values' : `values-${qualifierOf(locale)}`;
+      const body = bodies.get(locale)!.join('\n');
+      const xml = `<?xml version="1.0" encoding="utf-8"?>\n${head}\n<resources>\n${body}${body === '' ? '' : '\n'}</resources>\n`;
+      return [join(target.out, folder, `${target.name}.xml`), xml];
+    }),
+  );
+  return { files, problems };
+}

package/src/tools/native/apple.ts

@@ -0,0 +1,139 @@
+/**
+ * The catalog as Apple `.strings` tables: `<locale>.lproj/<name>.strings` per locale, each holding
+ * what that locale shows, every fallback resolved. Plain `.strings` and not a String Catalog, which
+ * only Xcode compiles: an app bundled by other tools copies these into its `Resources` as they are.
+ *
+ * The Swift target covers what code shows; these are for what the system reads from a bundle. With
+ * `plist`, the table is `InfoPlist`: the permission prompts and names in that Info.plist, an entry
+ * per key it has, which its own text must match in the source locale.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import type { Catalog, Message, Problem } from '#src/tools/catalog.ts';
+import type { Entry } from '#src/tools/compile.ts';
+import type { NativeTarget } from '#src/tools/config.ts';
+import { staticLiteral } from '#src/tools/icu.ts';
+import { checkNames } from './emit.ts';
+import { fileOf, foundIn, LEAVE_OUT, restOf, wordsFor } from './model.ts';
+import { formatString, noteOf, type Printf } from './printf.ts';
+
+/** Text inside a `.strings` file's quotes; `%` doubled where the string has arguments. */
+function escape(text: string, formatted: boolean): string {
+  const out = text.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n').replaceAll('\r', '\\r').replaceAll('\t', '\\t');
+  return formatted ? out.replaceAll('%', '%%') : out;
+}
+
+const PRINTF: Printf = {
+  platform: 'Apple',
+  formatter: 'String(format:)',
+  holder: '.strings files',
+  string: '@',
+  escape,
+  plural: (name) =>
+    `{${name}} is a plural, which a .strings file can't hold (it takes a .stringsdict, which this target doesn't write): show it from the Swift target, ${LEAVE_OUT}`,
+};
+
+const ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+
+/** An XML plist's string values by key, read as its text is: every `<key>` followed by a `<string>`. */
+function plistStrings(xml: string): Map<string, string> {
+  const strings = new Map<string, string>();
+  for (const [, key, value] of xml.matchAll(/<key>([^<]*)<\/key>\s*(?:<string>([^<]*)<\/string>|<string\/>)/g)) {
+    strings.set(
+      key!,
+      (value ?? '').replace(/&(amp|lt|gt|quot|apos|#x?[0-9a-f]+);/gi, (_, e: string) =>
+        e.startsWith('#')
+          ? String.fromCodePoint(Number.parseInt(e.slice(/x/i.test(e[1]!) ? 2 : 1), /x/i.test(e[1]!) ? 16 : 10))
+          : ENTITIES[e.toLowerCase()]!,
+      ),
+    );
+  }
+  return strings;
+}
+
+/** The files `target` writes, by path, or a problem for every message it can't hold. */
+export function appleStrings(
+  target: NativeTarget & { name: string },
+  root: string,
+  catalog: Catalog,
+  locales: string[],
+  entries: Map<string, Entry[]>,
+  banner: string,
+): { files: Map<string, string>; problems: Problem[] } {
+  const source = locales[0]!;
+  const asts = new Map([...entries].map(([locale, list]) => [locale, new Map(list)]));
+  const problems: Problem[] = [];
+  const error = (m: Message, message: string, file = m.file) =>
+    problems.push({ severity: 'error', file, key: m.key, message: `apple: ${message}` });
+
+  const plist = target.plist;
+  const shown = plist === undefined ? '' : relative(root, plist).replaceAll('\\', '/');
+  if (plist !== undefined && !existsSync(plist)) throw new Error(`apple: ${shown} is missing: name the Info.plist the table translates`);
+  const strings = plist === undefined ? undefined : plistStrings(readFileSync(plist, 'utf8'));
+  const byLower = new Map([...(strings?.keys() ?? [])].map((k) => [k.toLowerCase(), k]));
+
+  // Under `plist`, a key's words spell the plist key, which catalog keys can't hold as written.
+  const taken = catalog.messages.flatMap((m) => {
+    const rest = restOf(target, m.key);
+    if (rest === undefined) return [];
+    if (strings === undefined) return [{ m, name: rest }];
+    const name = byLower.get(wordsFor(target, m.key)!.join('').toLowerCase());
+    if (name === undefined) {
+      error(
+        m,
+        `${m.key} names no string in ${shown}: spell one of its keys, as ns-camera-usage-description is NSCameraUsageDescription, or add it there`,
+      );
+      return [];
+    }
+    return [{ m, name }];
+  });
+  checkNames(
+    'apple',
+    taken.map(({ m, name }) => [m.key, name]),
+    [],
+  );
+
+  for (const { m, name } of taken) {
+    if (strings === undefined) continue;
+    if (m.args.size > 0) {
+      error(m, `${name} is shown as it is written, with nothing filled in: say it without {${[...m.args.keys()].join('}, {')}}`);
+      continue;
+    }
+    // The plist's own text shows where no .lproj matches, so it can't be left to say something else.
+    const text = staticLiteral(asts.get(source)?.get(m.key) ?? []);
+    if (text !== undefined && text !== strings.get(name))
+      error(m, `${shown} says ${JSON.stringify(strings.get(name))} for ${name}: make it ${JSON.stringify(text)}, as the catalog says`);
+  }
+
+  const lines = new Map<string, string[]>(locales.map((l) => [l, []]));
+  const failed = new Set(problems.map((p) => p.key));
+  for (const { m, name } of taken) {
+    if (failed.has(m.key)) continue;
+    const args = [...m.args.keys()];
+    const note = noteOf(m);
+    const head = note === '' ? '' : `/* ${note.replaceAll('*/', '* /')} */\n`;
+    const written = new Map<string, string>();
+    for (const locale of locales) {
+      const found = foundIn(m.key, locale, locales, asts);
+      if (found === undefined) continue;
+      let entry = written.get(found);
+      if (entry === undefined) {
+        try {
+          entry = `${head}"${escape(name, false)}" = "${formatString(asts.get(found)!.get(m.key)!, args, PRINTF)}";\n`;
+        } catch (e) {
+          error(m, (e as Error).message, fileOf(m, found, source));
+          break;
+        }
+        written.set(found, entry);
+      }
+      lines.get(locale)!.push(entry);
+    }
+  }
+
+  const top = `/* ${banner.replace(/^\/\/ /, '')} */\n`;
+  const files = new Map(
+    locales.map((locale) => [join(target.out, `${locale}.lproj`, `${target.name}.strings`), [top, ...lines.get(locale)!].join('\n')]),
+  );
+  return { files, problems };
+}

package/src/tools/native/emit.ts

@@ -0,0 +1,87 @@
+/**
+ * What every native writer shares: words to identifiers, numbers and strings to literals, and the
+ * names a file can't give two things.
+ */
+import type { Condition, Operand } from './plurals.ts';
+
+/** Words from an identifier written any way: `userName`, `user-name` and `user_name` are user, name. */
+export function wordsOf(name: string): string[] {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((w) => w.toLowerCase());
+}
+
+const capital = (w: string) => w.charAt(0).toUpperCase() + w.slice(1);
+
+export const snake = (words: string[]) => words.join('_');
+export const pascal = (words: string[]) => words.map(capital).join('');
+export const camel = (words: string[]) => words.map((w, i) => (i === 0 ? w : capital(w))).join('');
+export const upper = (words: string[]) => words.join('_').toUpperCase();
+
+/** An identifier can't start with a digit, so `404.title` is `_404Title`. */
+export function leading(name: string): string {
+  return /^[0-9]/.test(name) ? `_${name}` : name;
+}
+
+/** A double literal every target reads as one: `0.0`, `1.5`, `1e21`. */
+export function float(value: number): string {
+  const s = String(value).replace('e+', 'e');
+  return /[.e]/.test(s) ? s : `${s}.0`;
+}
+
+/** Characters that print nothing, or look like a space, written as escapes so the code shows them. */
+const INVISIBLE = /[\u{a0}\u{61c}\u{180e}\u{2000}-\u{200f}\u{2028}-\u{202f}\u{205f}-\u{206f}\u{feff}]/gu;
+
+/** Text for a doc comment, with what prints nothing written as `\u{…}`: Rust refuses direction marks there. */
+export function docText(line: string): string {
+  return line.replace(INVISIBLE, (c) => `\\u{${c.charCodeAt(0).toString(16)}}`);
+}
+
+/** A string literal: JSON's escapes, `\u{…}` where the target writes them so (Rust, Swift), and `$` escaped in Kotlin. */
+export function stringLiteral(value: string, language: 'rust' | 'swift' | 'kotlin'): string {
+  const json = JSON.stringify(value).replace(INVISIBLE, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+  if (language === 'kotlin') return json.replaceAll('$', '\\$');
+  return json.replace(/\\u([0-9a-f]{4})/g, (_, hex: string) => `\\u{${hex.replace(/^0+/, '')}}`);
+}
+
+/**
+ * A plural condition as an expression over operands `o`: `field(op)` reads one, `mod` takes a
+ * remainder, `within` tests a range as CLDR does (integers only). `&&`, `||` and `!` are every
+ * target's.
+ */
+export function conditionCode(
+  condition: Condition,
+  code: {
+    field: (op: Operand) => string;
+    mod: (value: string, by: string) => string;
+    within: (value: string, from: string, to: string) => string;
+  },
+): string {
+  const ors = condition.map((and) =>
+    and
+      .map((r) => {
+        const value = r.mod === undefined ? code.field(r.operand) : code.mod(code.field(r.operand), float(r.mod));
+        if (r.ranges.length === 1 && r.ranges[0]![0] === r.ranges[0]![1])
+          return `${value} ${r.negated ? '!=' : '=='} ${float(r.ranges[0]![0])}`;
+        const any = r.ranges
+          .map(([from, to]) => (from === to ? `${value} == ${float(from)}` : code.within(value, float(from), float(to))))
+          .join(' || ');
+        return r.negated ? `!(${any})` : r.ranges.length > 1 ? `(${any})` : any;
+      })
+      .join(' && '),
+  );
+  return ors.length > 1 ? ors.map((o) => (o.includes(' && ') ? `(${o})` : o)).join(' || ') : ors[0]!;
+}
+
+/** Fails with the keys whose names meet, or meet a name the file already has. */
+export function checkNames(language: string, named: [key: string, name: string][], taken: string[]): void {
+  const seen = new Map<string, string>(taken.map((t) => [t, 'a name the file already has']));
+  for (const [key, name] of named) {
+    const other = seen.get(name);
+    if (other !== undefined)
+      throw new Error(`${language}: ${key} is named ${name}, as ${other} is: rename one, or change the target's keys`);
+    seen.set(name, key);
+  }
+}

package/src/tools/native/index.ts

@@ -0,0 +1,48 @@
+/**
+ * The native files `generate` writes beside the TypeScript, one per target in the config's `native`
+ * (Android's and Apple's string resources, a file per locale). A message a target can't render
+ * fails the build with the reason, as a translation that drifted does.
+ */
+import { CatalogError, type Catalog, type Problem } from '#src/tools/catalog.ts';
+import type { Entry } from '#src/tools/compile.ts';
+import type { ResolvedConfig } from '#src/tools/config.ts';
+import { androidResources } from './android.ts';
+import { appleStrings } from './apple.ts';
+import { kotlinFile } from './kotlin.ts';
+import { nativeModel } from './model.ts';
+import { rustModule } from './rust.ts';
+import { swiftFile } from './swift.ts';
+
+const WRITERS = { rust: rustModule, swift: swiftFile, kotlin: kotlinFile };
+
+export function nativeFiles(
+  config: ResolvedConfig,
+  catalog: Catalog,
+  locales: string[],
+  entries: Map<string, Entry[]>,
+  banner: string,
+): Map<string, string> {
+  const files = new Map<string, string>();
+  const problems: Problem[] = [];
+  for (const target of config.native) {
+    try {
+      if (target.language === 'android' || target.language === 'apple') {
+        const { files: written, problems: found } =
+          target.language === 'android'
+            ? androidResources(target, catalog, locales, entries, banner)
+            : appleStrings(target, config.root, catalog, locales, entries, banner);
+        problems.push(...found);
+        for (const [path, content] of written) files.set(path, content);
+        continue;
+      }
+      const { model, problems: found } = nativeModel(target, catalog, locales, entries);
+      problems.push(...found);
+      if (found.length > 0) continue;
+      files.set(target.out, WRITERS[target.language](model, target, banner));
+    } catch (e) {
+      problems.push({ severity: 'error', message: (e as Error).message });
+    }
+  }
+  if (problems.length > 0) throw new CatalogError(problems);
+  return files;
+}