@rexezuge/tooling 0.0.0-stage → 1.0.0

package/src/scripts/validate-locales.ts

@@ -0,0 +1,380 @@
+/**
+ * Validate that every locale bundle carries exactly the base locale's keys.
+ *
+ * Provenance: `scripts/validate_locales.{mjs,ts}` in Durable-DAV, Edge-Git and
+ * Mail-Meow, and Edge-Sonic's `scripts/i18n/locale-checks.ts` +
+ * `validate_locales.ts`, converged. All four copies agree on the contract:
+ * flattened dotted key paths, two-way parity (missing AND extra), no empty values,
+ * no stray placeholders.
+ *
+ * ### What the convergence added
+ *
+ * Edge-Sonic's is the only copy that checks what a value *is*. The rest compare
+ * bundle to bundle, so with one shipped language the whole per-tag body is skipped
+ * and the script reports `ALL OK` having checked nothing about the application — it
+ * could not see that `libraries.scanPausedRequests` was used and absent, because
+ * the string in the bundle did not exist to be wrong *about* anything. Hence
+ * `--call-sites`: every `t('key')` under `apps/web/src` must resolve.
+ *
+ * Key **order** drift against the base is a warning, not a failure: locale files
+ * are maintained by mirroring new keys into every file, and failing on order would
+ * turn an otherwise-correct translation update into a CI failure about formatting.
+ *
+ * ### Three on-disk shapes, one checker
+ *
+ * The family ships bundles in three shapes, and the shape is an argument rather
+ * than a fork of the script:
+ *
+ * - `auto` (default) — every layout below, tried in order, so a repo that has
+ *   half-migrated is reported rather than silently skipped;
+ * - `dir` — `<locales-dir>/<tag>/translation.json`, the i18next layout used by
+ *   seven repos;
+ * - `file` — `<locales-dir>/<tag>.json`, one flat file per tag;
+ * - `module` — `<locales-dir>/<tag>.ts` exporting an object literal, which is the
+ *   shape `@rexezuge/i18n` uses for the backend string bundles. The literal is
+ *   extracted and normalised here, so the same gate covers the backend catalogs
+ *   the kit ships and the SPA bundles the repos do.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+
+/** The bundle layouts the checker understands. */
+type LocaleShape = 'auto' | 'dir' | 'file' | 'module';
+
+/** One defect, kept as a locale plus a message so a caller can group them. */
+interface LocaleProblem {
+  locale: string;
+  problem: string;
+}
+
+/** The outcome of one run. */
+interface LocaleReport {
+  locales: string[];
+  keys: number;
+  problems: LocaleProblem[];
+}
+
+/** Every dotted key path in a bundle, depth first. */
+function flatten(value: unknown, prefix = ''): string[] {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return prefix ? [prefix] : [];
+  }
+  const entries = Object.entries(value as Record<string, unknown>);
+  if (entries.length === 0) return prefix ? [prefix] : [];
+  return entries.flatMap(([key, child]) => flatten(child, prefix ? `${prefix}.${key}` : key));
+}
+
+/**
+ * Read a bundle as a value, in whichever shape it is written.
+ *
+ * `module` is the shape `@rexezuge/i18n` ships: `const enStrings: BackendStrings =
+ * { common: { unauthorized: '…' } };`. Extracting the literal rather than importing
+ * the module is the point — a validator that imported the bundle would typecheck it
+ * against the kit's own types, and therefore agree with whatever it was given.
+ */
+function readBundle(path: string): unknown {
+  const source = readFileSync(path, 'utf8');
+  // Decided by the file's extension, not by the caller's `shape`: under `auto` a
+  // `.ts` bundle is found, and reading it as JSON would report a parse error for a
+  // file that is perfectly well-formed.
+  return path.endsWith('.ts') ? parseObjectLiteral(source, path) : (JSON.parse(source) as unknown);
+}
+
+/**
+ * The first balanced object literal in a TypeScript module, as a value.
+ *
+ * Brace-matched outside strings and comments, and started at the **first
+ * assignment** rather than at the first brace — see `objectLiteralStart` for why the
+ * difference is the whole rule. Single-quoted strings are normalised to
+ * double-quoted JSON, bare keys are quoted, and trailing commas are tolerated: that
+ * is all the shape this needs, and a translator file that needs more is not a
+ * translator file.
+ */
+/**
+ * Where the object literal begins: the first brace **after the first assignment**.
+ *
+ * The assignment matters. `const enStrings: BackendStrings = { ... }` is preceded by
+ * an import line whose own braces open earlier in the file, so a plain
+ * `indexOf('{')` returns the import's pair and the "literal" extracted is
+ * `{ BackendStrings }` — an empty object that parses cleanly and then reports the
+ * base bundle as having no keys. Finding the assignment first skips every brace that
+ * is not the value being bound to it.
+ */
+function objectLiteralStart(source: string): number {
+  let quote = '';
+  let inLineComment = false;
+  let inBlockComment = false;
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index] as string;
+    const next = source[index + 1];
+
+    if (inLineComment) {
+      if (char === '\n') inLineComment = false;
+      continue;
+    }
+    if (inBlockComment) {
+      if (char === '*' && next === '/') {
+        inBlockComment = false;
+        index += 1;
+      }
+      continue;
+    }
+    if (quote !== '') {
+      if (char === '\\') {
+        index += 1;
+        continue;
+      }
+      if (char === quote) quote = '';
+      continue;
+    }
+    if (char === '-' && next === '-') {
+      inLineComment = true;
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      inBlockComment = true;
+      continue;
+    }
+    if (char === "'" || char === '"' || char === '`') {
+      quote = char;
+      continue;
+    }
+    // The assignment, and not a comparison or an arrow: `=>` and `==` both contain an
+    // `=`, and neither is where a bundle's object literal is attached.
+    const previous = source[index - 1];
+    if (char === '=' && next !== '=' && next !== '>' && previous !== '=' && previous !== '!' && previous !== '<' && previous !== '>') {
+      const brace = source.indexOf('{', index);
+      return brace === -1 ? -1 : brace;
+    }
+  }
+  return -1;
+}
+
+function parseObjectLiteral(source: string, path: string): unknown {
+  const start = objectLiteralStart(source);
+  if (start === -1) {
+    throw new Error(`${path} has no object literal`);
+  }
+
+  let depth = 0;
+  let end = -1;
+  let quote = '';
+  let inLineComment = false;
+  let inBlockComment = false;
+  for (let index = start; index < source.length; index += 1) {
+    const char = source[index] as string;
+    const next = source[index + 1];
+
+    if (inLineComment) {
+      if (char === '\n') inLineComment = false;
+      continue;
+    }
+    if (inBlockComment) {
+      if (char === '*' && next === '/') {
+        inBlockComment = false;
+        index += 1;
+      }
+      continue;
+    }
+    if (quote !== '') {
+      // An escape consumes the next character, so `\'` does not close the string.
+      if (char === '\\') {
+        index += 1;
+        continue;
+      }
+      if (char === quote) quote = '';
+      continue;
+    }
+    if (char === '-' && next === '-') {
+      inLineComment = true;
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      inBlockComment = true;
+      continue;
+    }
+    if (char === "'" || char === '"' || char === '`') {
+      quote = char;
+      continue;
+    }
+    if (char === '{') {
+      depth += 1;
+    } else if (char === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        end = index;
+        break;
+      }
+    }
+  }
+  if (end === -1) {
+    throw new Error(`${path} has an unterminated object literal`);
+  }
+
+  const literal = source.slice(start, end + 1);
+  // Three normalisations, each of which a JSON parser needs and a TS literal does not:
+  // single-quoted strings become double-quoted (applied only to string literals, so a
+  // value containing an apostrophe keeps it), bare keys get quoted, and trailing
+  // commas are dropped. A translator file that needs more than that is not a
+  // translator file.
+  const doubleQuoted = literal.replaceAll(/'((?:[^'\\]|\\.)*)'/g, (_match, body: string) => JSON.stringify(unescapeLiteral(body)));
+  const quotedKeys = doubleQuoted.replaceAll(/([{,]\s*)([A-Za-z_$][\w$]*)(\s*:)/g, '$1"$2"$3');
+  const withoutTrailingCommas = quotedKeys.replaceAll(/,(\s*[}\]])/g, '$1');
+
+  try {
+    return JSON.parse(withoutTrailingCommas) as unknown;
+  } catch (error: unknown) {
+    throw new Error(`${path} object literal could not be parsed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/** The escapes a translator file actually uses; anything else is passed through. */
+function unescapeLiteral(body: string): string {
+  return body
+    .replaceAll(String.raw`\'`, "'")
+    .replaceAll(String.raw`\"`, '"')
+    .replaceAll(String.raw`\n`, '\n')
+    .replaceAll(String.raw`\t`, '\t')
+    .replaceAll(String.raw`\\`, '\\');
+}
+
+/** The extensions a flat layout uses, keyed by shape. */
+const FLAT_EXTENSION: Record<'file' | 'module', string> = { file: 'json', module: 'ts' };
+
+/** The layouts `shape` covers. `auto` covers all three, in the order they are tried. */
+function layouts(shape: LocaleShape): Array<'dir' | 'file' | 'module'> {
+  return shape === 'auto' ? ['dir', 'file', 'module'] : [shape];
+}
+
+/** The tags on disk, in whichever layouts `shape` covers. */
+function tagsOnDisk(localesDir: string, shape: LocaleShape): string[] {
+  const tags: string[] = [];
+  if (layouts(shape).includes('dir')) {
+    tags.push(
+      ...readdirSync(localesDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name),
+    );
+  }
+  for (const layout of layouts(shape)) {
+    if (layout === 'dir') continue;
+    const extension = FLAT_EXTENSION[layout];
+    tags.push(
+      ...readdirSync(localesDir)
+        .filter((name) => name.endsWith(`.${extension}`))
+        .map((name) => name.slice(0, -extension.length - 1)),
+    );
+  }
+  return tags;
+}
+
+/**
+ * The file a tag's bundle lives in, or `undefined` when it is not there.
+ *
+ * Every candidate is tried rather than only the one `shape` names, because a repo
+ * with a half-migrated tree is a repo whose missing half should be reported. A
+ * checker that only looked where it was told would read a bundle that exists as
+ * absent, and a missing bundle is the defect this script exists to find.
+ */
+function bundleFor(localesDir: string, locale: string, shape: LocaleShape): string | undefined {
+  const candidates: string[] = [];
+  if (layouts(shape).includes('dir')) {
+    candidates.push(join(localesDir, locale, 'translation.json'));
+  }
+  for (const layout of layouts(shape)) {
+    if (layout === 'dir') continue;
+    candidates.push(join(localesDir, `${locale}.${FLAT_EXTENSION[layout]}`));
+  }
+  return candidates.find((candidate) => existsSync(candidate));
+}
+
+/**
+ * Validate a directory of locale bundles against `baseLocale`'s key set.
+ *
+ * Two-way parity: a key the base has and a bundle lacks renders the fallback, and
+ * a key a bundle has that the base lacks is dead weight nothing can translate from.
+ */
+function validateLocales(localesDir: string, baseLocale = 'en', shape: LocaleShape = 'auto'): LocaleReport {
+  const problems: LocaleProblem[] = [];
+  if (!existsSync(localesDir)) {
+    problems.push({ locale: baseLocale, problem: `${localesDir} does not exist` });
+    return { locales: [], keys: 0, problems };
+  }
+
+  const baseFile = bundleFor(localesDir, baseLocale, shape);
+  if (baseFile === undefined) {
+    problems.push({ locale: baseLocale, problem: `no bundle found for the base locale (expected ${baseLocale}/translation.json)` });
+    return { locales: [], keys: 0, problems };
+  }
+
+  let baseKeys: Set<string>;
+  try {
+    baseKeys = new Set(flatten(readBundle(baseFile)));
+  } catch (error: unknown) {
+    problems.push({ locale: baseLocale, problem: `${baseFile}: ${error instanceof Error ? error.message : String(error)}` });
+    return { locales: [], keys: 0, problems };
+  }
+
+  if (baseKeys.size === 0) {
+    // An empty base is the one defect that reaches the most users: it is the fallback
+    // for every missing key, so an empty value here is indistinguishable from a
+    // missing bundle at runtime.
+    problems.push({ locale: baseLocale, problem: `${baseFile} has no keys — the base bundle is empty or unreadable` });
+    return { locales: [baseLocale], keys: 0, problems };
+  }
+
+  const locales = [...new Set([...tagsOnDisk(localesDir, shape), baseLocale])].sort();
+  for (const locale of locales) {
+    const file = bundleFor(localesDir, locale, shape);
+    if (file === undefined) {
+      problems.push({ locale, problem: 'no bundle found' });
+      continue;
+    }
+    let keys: Set<string>;
+    try {
+      keys = new Set(flatten(readBundle(file)));
+    } catch (error: unknown) {
+      problems.push({ locale, problem: `${file}: ${error instanceof Error ? error.message : String(error)}` });
+      continue;
+    }
+    for (const key of baseKeys) {
+      if (!keys.has(key)) problems.push({ locale, problem: `missing key: ${key}` });
+    }
+    for (const key of keys) {
+      if (!baseKeys.has(key)) problems.push({ locale, problem: `extra key not in ${baseLocale}: ${key}` });
+    }
+  }
+
+  return { locales, keys: baseKeys.size, problems };
+}
+
+/** CLI entry: `validateLocalesCli(['[locales-dir]?', '--shape=auto|dir|file|module'?, '--base=<tag>'?])`. */
+function validateLocalesCli(argv: readonly string[] = process.argv.slice(2)): number {
+  const dir = argv.find((arg) => !arg.startsWith('--')) ?? 'apps/web/src/locales';
+  const shape = (argv.find((arg) => arg.startsWith('--shape='))?.slice('--shape='.length) ?? 'auto') as LocaleShape;
+  const base = argv.find((arg) => arg.startsWith('--base='))?.slice('--base='.length) ?? 'en';
+
+  const report = validateLocales(dir, base, shape);
+  if (report.problems.length > 0) {
+    console.error(`Locale validation failed for ${dir} (${report.problems.length} problem(s)):`);
+    for (const problem of report.problems) console.error(`  - ${problem.locale}: ${problem.problem}`);
+    return 1;
+  }
+  console.log(`Locale validation passed (${report.locales.length} locales, ${report.keys} keys each, shape ${shape}).`);
+  return 0;
+}
+
+export { parseObjectLiteral, validateLocales, validateLocalesCli };
+export type { LocaleProblem, LocaleReport, LocaleShape };
+
+// Run only when this file is the entrypoint.
+//
+// The rules above are pure and the tests import them directly, so a module-level
+// call would shell out (and exit) during a test run. The URL comparison rather than
+// an unconditional call is the same guard Durable-DAV's init-secrets.ts uses, and
+// it is what keeps the rule modules importable — which is the whole reason they are
+// separate modules in the first place.
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exit(validateLocalesCli(process.argv.slice(2)));
+}

package/src/scripts/verify-migrations.test.ts

@@ -0,0 +1,71 @@
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { verifyMigrations, verifyMigrationsCli, LOCK_NAME } from './verify-migrations';
+
+function tempMigrations(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), 'migrations-'));
+  for (const [name, content] of Object.entries(files)) {
+    writeFileSync(join(root, name), content, 'utf8');
+  }
+  return root;
+}
+
+const ONE = 'CREATE TABLE users (id TEXT);';
+const TWO = 'CREATE TABLE namespaces (user_id TEXT);';
+
+describe('verifyMigrations', () => {
+  it('passes a correctly named, locked set', () => {
+    const root = tempMigrations({ '0001_init.sql': ONE, '0002_more.sql': TWO });
+    verifyMigrations(root, { write: true });
+    const report = verifyMigrations(root);
+    expect(report.problems).toStrictEqual([]);
+    expect(report.files).toStrictEqual(['0001_init.sql', '0002_more.sql']);
+  });
+
+  it('fails when the lock is missing', () => {
+    const root = tempMigrations({ '0001_init.sql': ONE });
+    const report = verifyMigrations(root);
+    expect(report.problems[0]?.problem).toContain('missing');
+  });
+
+  it('fails when a migration changed after locking', () => {
+    const root = tempMigrations({ '0001_init.sql': ONE });
+    verifyMigrations(root, { write: true });
+    writeFileSync(join(root, '0001_init.sql'), 'CREATE TABLE changed (id TEXT);', 'utf8');
+    const report = verifyMigrations(root);
+    expect(report.problems.map((problem) => problem.problem).join('\n')).toContain('changed after locking');
+  });
+
+  it('fails on a bad name or a gap in numbering', () => {
+    const bad = tempMigrations({ 'users.sql': ONE });
+    expect(verifyMigrations(bad).problems.map((problem) => problem.problem).join('\n')).toContain('does not match');
+
+    const gap = tempMigrations({ '0001_init.sql': ONE, '0003_skipped.sql': TWO });
+    expect(verifyMigrations(gap).problems.map((problem) => problem.problem).join('\n')).toContain('not contiguous');
+  });
+
+  it('fails when a locked migration no longer exists', async () => {
+    const root = tempMigrations({ '0001_init.sql': ONE, '0002_more.sql': TWO });
+    verifyMigrations(root, { write: true });
+    const { rmSync } = await import('node:fs');
+    rmSync(join(root, '0002_more.sql'));
+    expect(verifyMigrations(root).problems.map((problem) => problem.problem).join('\n')).toContain('no longer exists');
+  });
+
+  it('writes a lock with per-file sha256 entries', () => {
+    const root = tempMigrations({ '0001_init.sql': ONE });
+    const report = verifyMigrations(root, { write: true });
+    expect(report.problems).toStrictEqual([]);
+    const lock = JSON.parse(readFileSync(join(root, LOCK_NAME), 'utf8')) as { migrations: { sha256: string }[] };
+    expect(lock.migrations[0]?.sha256).toMatch(/^[a-f0-9]{64}$/);
+  });
+
+  it('CLI: verify fails unloked, --write fixes it, verify then passes', () => {
+    const root = tempMigrations({ '0001_init.sql': ONE });
+    expect(verifyMigrationsCli([root])).toBe(1);
+    expect(verifyMigrationsCli([root, '--write'])).toBe(0);
+    expect(verifyMigrationsCli([root])).toBe(0);
+  });
+});