@oxy.so/doctor 1.4.0 → 1.6.0

package/README.md

@@ -47,6 +47,56 @@ Require normal tests and typecheck before merging; never use `latest` ranges or
 mutate dependencies during application startup or CI. Renovate proposes
 changes; Doctor detects drift and duplicate installations.
 
+## Translation keys
+
+Every translation catalog follows one key convention (oxy
+`docs/adr/0055-translation-keys.md`): nested objects of identifier segments
+(`compose.toolbar.addImage`), the first segment a namespace, never the English
+text and never a flat dotted string, and English as the source.
+
+```bash
+bunx oxy-doctor-i18n --ci            # every locales/ directory with an en catalog
+bunx oxy-doctor-i18n --root=packages/frontend --json
+```
+
+It finds `locales/<lang>.json` (single file) and `locales/<lang>/<namespace>.json`
+(per namespace) catalogs. **Errors** (`--ci` exits 1): a key segment that is
+text (`text-key`), a dotted key stored flat (`flat-key`), a top-level string in
+a single-file catalog (`top-level-string`), a leaf that is neither a string
+nor a list of strings (`non-string`), a translation key the source lacks
+(`stray-key`), a string where the source has a namespace or the reverse
+(`shape-mismatch`). **Warnings**: a missing translation (`missing-translation`,
+rendered in English) and a placeholder set that differs from the source
+(`placeholder-mismatch`).
+
+## Expo Android device-session autolinking
+
+After a complete frozen install, run the separate check against the Expo app
+root (the current directory by default):
+
+```bash
+oxy-doctor-expo-android --project-root=packages/frontend \
+  --require-source=SharedDeviceSessionPublish.kt \
+  --require-source=SharedDeviceSessionSweep.kt \
+  --require-source=OxyDeviceSessionStore.kt
+```
+
+The command invokes the app's installed `expo-modules-autolinking` resolver and
+requires exactly one Oxy Services entry matching the version resolved by Node
+from the app root, and one device-session module from that package's Android
+directory. It requires
+`OxyDeviceSessionModule.kt` and any repeated `--require-source` filenames.
+Choose additional sources according to the Services version and guarantees the
+app expects; older releases need not contain newer files. Missing or ambiguous
+results and resolver failures exit nonzero. This does not change the existing
+Doctor or emulator preflight commands.
+
+The check verifies discovery and source presence in the installed dependency
+graph, not source contents, Android compilation, native binary distribution,
+or device runtime behavior. It cannot exclude additional installed copies or
+prove which copy Metro resolves from nested importers. Run it in a complete
+install; a partial install cannot establish that the full app graph is correct.
+
 ## Android emulator preflight
 
 `oxy-emulator-preflight --serial emulator-5554` checks that the explicitly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/doctor",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Read-only health checks for Oxy ecosystem repositories",
   "repository": {
     "type": "git",
@@ -10,10 +10,13 @@
   "type": "module",
   "bin": {
     "oxy-doctor": "./src/cli.mjs",
+    "oxy-doctor-expo-android": "./src/expo-android.mjs",
+    "oxy-doctor-i18n": "./src/i18n-cli.mjs",
     "oxy-emulator-preflight": "./src/emulator-preflight.mjs"
   },
   "exports": {
-    ".": "./src/checks.mjs"
+    ".": "./src/checks.mjs",
+    "./i18n": "./src/i18n.mjs"
   },
   "files": [
     "src",

package/src/expo-android.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+
+const usage = 'oxy-doctor-expo-android [--project-root=PATH] [--require-source=NAME.kt ...]';
+const args = process.argv.slice(2);
+if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
+  console.log(
+    `${usage}\n\nCheck Expo Android autolinking for the installed Oxy device-session module.`,
+  );
+  process.exit(0);
+}
+try {
+  let root;
+  const requiredSources = new Set(['OxyDeviceSessionModule.kt']);
+  for (const arg of args) {
+    if (arg.startsWith('--project-root=') && root === undefined) {
+      root = arg.slice('--project-root='.length);
+      if (!root) throw new Error('project root must not be empty');
+    } else if (arg.startsWith('--require-source=')) {
+      const source = arg.slice('--require-source='.length);
+      if (!/^[A-Za-z][A-Za-z0-9_]*\.kt$/.test(source)) {
+        throw new Error('required source must be a Kotlin filename');
+      }
+      requiredSources.add(source);
+    } else {
+      throw new Error(`invalid argument: ${arg}`);
+    }
+  }
+  const projectRoot = resolve(root ?? process.cwd());
+  const projectRequire = createRequire(join(projectRoot, 'package.json'));
+  const manifestPath = projectRequire.resolve('@oxy.so/services/package.json');
+  const services = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  if (
+    services.name !== '@oxy.so/services' ||
+    typeof services.version !== 'string' ||
+    !services.version
+  ) {
+    throw new Error('installed Oxy Services manifest is invalid');
+  }
+  const autolinking = projectRequire.resolve('expo-modules-autolinking/package.json');
+  const cli = join(dirname(autolinking), 'bin/expo-modules-autolinking.js');
+  let output;
+  try {
+    output = execFileSync(
+      process.execPath,
+      [cli, 'resolve', '--platform', 'android', '--project-root', projectRoot, '--json'],
+      {
+        encoding: 'utf8',
+        env: { ...process.env, NO_COLOR: '1' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    );
+  } catch {
+    throw new Error('Expo Android autolinking failed');
+  }
+  let result;
+  try {
+    result = JSON.parse(output);
+  } catch {
+    throw new Error('invalid Expo autolinking result');
+  }
+  if (!Array.isArray(result?.modules)) throw new Error('invalid Expo autolinking result');
+  const matches = result.modules.filter((entry) => entry?.packageName === '@oxy.so/services');
+  if (matches.length !== 1 || matches[0].packageVersion !== services.version) {
+    throw new Error('Android autolinking must select one Oxy Services entry matching the app root');
+  }
+  if (!Array.isArray(matches[0].projects)) throw new Error('invalid Oxy Services project list');
+  const projects = matches[0].projects.filter(
+    (project) =>
+      Array.isArray(project?.modules) &&
+      project.modules.some(
+        (module) => module?.classifier === 'so.oxy.devicesession.OxyDeviceSessionModule',
+      ),
+  );
+  if (
+    projects.length !== 1 ||
+    projects[0].modules.filter(
+      (module) => module?.classifier === 'so.oxy.devicesession.OxyDeviceSessionModule',
+    ).length !== 1
+  )
+    throw new Error('Android autolinking must include exactly one OxyDeviceSessionModule');
+  const nativeDir = join(dirname(manifestPath), 'android');
+  if (realpathSync(projects[0].sourceDir) !== realpathSync(nativeDir)) {
+    throw new Error('OxyDeviceSessionModule must come from the installed Oxy Services package');
+  }
+  for (const source of requiredSources) {
+    if (!existsSync(join(nativeDir, 'src/main/java/so/oxy/devicesession', source))) {
+      throw new Error(`installed Oxy Services is missing Android source ${source}`);
+    }
+  }
+  console.log(
+    `Android autolinking includes OxyDeviceSessionModule from Oxy Services ${services.version}.`,
+  );
+} catch (error) {
+  console.error(
+    `Oxy Android check failed: ${error instanceof Error ? error.message : String(error)}`,
+  );
+  process.exitCode = 1;
+}

package/src/i18n-cli.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { DEFAULT_SOURCE_LOCALE, inspectTranslations } from './i18n.mjs';
+
+const usage = 'oxy-doctor-i18n [--root=PATH] [--source=LOCALE] [--ci] [--json]';
+const SHOWN_PER_RULE = 10;
+
+/** `Map.groupBy`, which Node 20 (the engines floor) lacks. */
+function groupBy(items, keyOf) {
+  const groups = new Map();
+  for (const item of items) {
+    const key = keyOf(item);
+    groups.set(key, [...(groups.get(key) ?? []), item]);
+  }
+  return groups;
+}
+
+let root = process.cwd();
+let source = DEFAULT_SOURCE_LOCALE;
+let ci = false;
+let json = false;
+for (const arg of process.argv.slice(2)) {
+  if (arg === '--help' || arg === '-h') {
+    console.log(
+      `${usage}\n\nCheck every translation catalog (locales/<lang>.json or locales/<lang>/*.json)\nagainst the Oxy key convention. --ci exits 1 on errors; warnings never fail.`,
+    );
+    process.exit(0);
+  } else if (arg.startsWith('--root=')) root = arg.slice('--root='.length);
+  else if (arg.startsWith('--source=')) source = arg.slice('--source='.length);
+  else if (arg === '--ci') ci = true;
+  else if (arg === '--json') json = true;
+  else {
+    console.error(`invalid argument: ${arg}\n${usage}`);
+    process.exit(2);
+  }
+}
+
+let catalogs;
+try {
+  catalogs = await inspectTranslations(resolve(root), source);
+} catch (error) {
+  console.error(`oxy-doctor-i18n: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(2);
+}
+
+const errorCount = catalogs.reduce((sum, catalog) => sum + catalog.errors.length, 0);
+if (json) {
+  console.log(JSON.stringify({ catalogs, errorCount }, null, 2));
+} else if (catalogs.length === 0) {
+  console.log(`No translation catalogs with a ${source} source found.`);
+} else {
+  for (const catalog of catalogs) {
+    console.log(
+      `${catalog.directory} (${catalog.layout}, ${catalog.locales.length} locales): ${catalog.errors.length} errors, ${catalog.warnings.length} warnings`,
+    );
+    const byRule = groupBy(catalog.errors, (issue) => issue.rule);
+    for (const [rule, issues] of byRule) {
+      console.log(`  error ${rule} (${issues.length})`);
+      for (const issue of issues.slice(0, SHOWN_PER_RULE)) {
+        console.log(`    ${issue.locale}: ${JSON.stringify(issue.key)} — ${issue.message}`);
+      }
+      if (issues.length > SHOWN_PER_RULE) {
+        console.log(`    … ${issues.length - SHOWN_PER_RULE} more`);
+      }
+    }
+    const warnings = groupBy(catalog.warnings, (issue) => issue.rule);
+    for (const [rule, issues] of warnings) {
+      const perLocale = groupBy(issues, (issue) => issue.locale);
+      console.log(
+        `  warning ${rule}: ${[...perLocale].map(([locale, list]) => `${locale} ${list.length}`).join(', ')}`,
+      );
+    }
+  }
+}
+process.exit(ci && errorCount > 0 ? 1 : 0);

package/src/i18n.mjs

@@ -0,0 +1,262 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { basename, join, relative } from 'node:path';
+
+/**
+ * Translation catalogs across the Oxy ecosystem follow ONE key convention
+ * (oxy `docs/adr/0055-translation-keys.md`):
+ *
+ *  - A key is a PATH of short identifier segments (`compose.toolbar.addImage`),
+ *    stored as NESTED JSON objects, never as a flat dotted string and never as
+ *    the English sentence itself.
+ *  - In a single-file catalog (`locales/en.json`) every top-level entry is a
+ *    namespace object; a per-namespace catalog (`locales/en/compose.json`) is
+ *    that namespace's file.
+ *  - A translation holds only keys the source locale has, with the same shape.
+ *
+ * Missing translations are warnings: i18next renders the source text, and a
+ * translation pass is ordinary product work, not a broken build.
+ */
+
+export const DEFAULT_SOURCE_LOCALE = 'en';
+
+/** One key segment: an identifier, or a data value such as `picked_up` or `us-east-1`. */
+const KEY_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const LOCALE_NAME = /^[a-z]{2,3}(?:[-_][A-Za-z0-9]{2,8})*$/;
+const PLACEHOLDER = /\{\{\s*([^}\s,]+)[^}]*\}\}/g;
+
+/** Never walked, with every dot-directory (`.git`, `.worktrees`, `.claude`, …). */
+const IGNORED_DIRECTORIES = new Set(['build', 'coverage', 'dist', 'node_modules']);
+
+/**
+ * Every `locales` directory under `root` that holds a catalog for
+ * `sourceLocale`: either `locales/<source>.json` (single file) or
+ * `locales/<source>/*.json` (one file per namespace).
+ */
+export async function findCatalogDirectories(root, sourceLocale = DEFAULT_SOURCE_LOCALE) {
+  const found = [];
+  async function walk(directory) {
+    const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+    if (basename(directory) === 'locales') {
+      const hasSource = entries.some(
+        (entry) =>
+          (entry.isFile() && entry.name === `${sourceLocale}.json`) ||
+          (entry.isDirectory() && entry.name === sourceLocale),
+      );
+      if (hasSource) {
+        found.push(directory);
+        return;
+      }
+    }
+    for (const entry of entries) {
+      if (
+        entry.isDirectory() &&
+        !entry.name.startsWith('.') &&
+        !IGNORED_DIRECTORIES.has(entry.name)
+      ) {
+        await walk(join(directory, entry.name));
+      }
+    }
+  }
+  await walk(root);
+  return found.sort();
+}
+
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * Load a catalog directory as `{ layout, locales: Map<locale, tree> }`, where a
+ * per-namespace catalog's tree is `{ <namespace>: <file contents> }` so both
+ * layouts are checked as one nested tree.
+ */
+export async function loadCatalogs(directory, sourceLocale = DEFAULT_SOURCE_LOCALE) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const perNamespace = entries.some((entry) => entry.isDirectory() && entry.name === sourceLocale);
+  const locales = new Map();
+  for (const entry of entries) {
+    if (perNamespace && entry.isDirectory() && LOCALE_NAME.test(entry.name)) {
+      const tree = {};
+      const files = await readdir(join(directory, entry.name), { withFileTypes: true });
+      for (const file of files) {
+        if (file.isFile() && file.name.endsWith('.json')) {
+          tree[file.name.slice(0, -'.json'.length)] = await readJson(
+            join(directory, entry.name, file.name),
+          );
+        }
+      }
+      locales.set(entry.name, tree);
+    } else if (!perNamespace && entry.isFile() && entry.name.endsWith('.json')) {
+      const locale = entry.name.slice(0, -'.json'.length);
+      if (LOCALE_NAME.test(locale)) {
+        locales.set(locale, await readJson(join(directory, entry.name)));
+      }
+    }
+  }
+  return { layout: perNamespace ? 'per-namespace' : 'single-file', locales };
+}
+
+const isTree = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** A string, or a list of strings (read with i18next's `returnObjects`). */
+const isLeaf = (value) =>
+  typeof value === 'string' ||
+  (Array.isArray(value) && value.every((item) => typeof item === 'string'));
+
+const PLURAL_FORM = /_(?:zero|one|two|few|many|other)$/;
+const PLURAL_CATEGORIES = ['zero', 'one', 'two', 'few', 'many', 'other'];
+
+/** Whether `node` holds another plural form of the same base as `segment`. */
+function hasPluralSibling(node, segment) {
+  if (!PLURAL_FORM.test(segment)) return false;
+  const base = segment.replace(PLURAL_FORM, '');
+  return PLURAL_CATEGORIES.some((category) => `${base}_${category}` in node);
+}
+
+const SINGULAR_PLURAL = /_(?:zero|one|two)$/;
+
+/**
+ * The placeholders a string interpolates. A singular plural form may spell its
+ * number out ("un elemento"), so `count` is not required there.
+ */
+function placeholders(text, key) {
+  const names = [...text.matchAll(PLACEHOLDER)].map((match) => match[1]);
+  return [...new Set(SINGULAR_PLURAL.test(key) ? names.filter((name) => name !== 'count') : names)]
+    .sort()
+    .join(',');
+}
+
+/**
+ * Check one loaded catalog directory. Returns `{ errors, warnings }`, each a
+ * list of `{ rule, locale, key, message }`.
+ */
+export function checkCatalogs({ locales }, sourceLocale = DEFAULT_SOURCE_LOCALE) {
+  const errors = [];
+  const warnings = [];
+  const source = locales.get(sourceLocale);
+  if (!isTree(source)) {
+    errors.push({
+      rule: 'missing-source',
+      locale: sourceLocale,
+      key: '',
+      message: `no ${sourceLocale} catalog`,
+    });
+    return { errors, warnings };
+  }
+
+  // Key shape, on every locale: a translation can introduce a bad key too.
+  for (const [locale, tree] of locales) {
+    for (const [key, value] of Object.entries(isTree(tree) ? tree : {})) {
+      if (!isTree(value) && !key.includes('.')) {
+        errors.push({
+          rule: 'top-level-string',
+          locale,
+          key,
+          message: 'a top-level entry must be a namespace object',
+        });
+      }
+    }
+    (function walk(node, path) {
+      for (const [segment, value] of Object.entries(node)) {
+        const key = path ? `${path}.${segment}` : segment;
+        if (segment.includes('.')) {
+          errors.push({
+            rule: 'flat-key',
+            locale,
+            key,
+            message: 'a dotted key must be nested objects, not one flat string',
+          });
+        } else if (!KEY_SEGMENT.test(segment)) {
+          errors.push({
+            rule: 'text-key',
+            locale,
+            key,
+            message: 'a key segment is an identifier, never the text itself',
+          });
+        }
+        if (isTree(value)) walk(value, key);
+        else if (!isLeaf(value)) {
+          errors.push({
+            rule: 'non-string',
+            locale,
+            key,
+            message: 'a leaf must be a string or a list of strings',
+          });
+        }
+      }
+    })(isTree(tree) ? tree : {}, '');
+  }
+
+  // Translations against the source.
+  for (const [locale, tree] of locales) {
+    if (locale === sourceLocale) continue;
+    (function compare(sourceNode, node, path) {
+      for (const [segment, value] of Object.entries(node)) {
+        const key = path ? `${path}.${segment}` : segment;
+        if (!(segment in sourceNode)) {
+          // Another CLDR plural form of a source key: `_few` / `_many` exist in
+          // languages English has no form for.
+          if (hasPluralSibling(sourceNode, segment)) continue;
+          errors.push({
+            rule: 'stray-key',
+            locale,
+            key,
+            message: `not in ${sourceLocale}; delete it or add it to ${sourceLocale}`,
+          });
+        } else if (isTree(value) !== isTree(sourceNode[segment])) {
+          errors.push({
+            rule: 'shape-mismatch',
+            locale,
+            key,
+            message: `a ${isTree(value) ? 'namespace' : 'string'} here, the other in ${sourceLocale}`,
+          });
+        } else if (isTree(value)) {
+          compare(sourceNode[segment], value, key);
+        } else if (typeof value === 'string' && typeof sourceNode[segment] === 'string') {
+          const expected = placeholders(sourceNode[segment], key);
+          if (placeholders(value, key) !== expected) {
+            warnings.push({
+              rule: 'placeholder-mismatch',
+              locale,
+              key,
+              message: `placeholders differ from ${sourceLocale} ({{${expected}}})`,
+            });
+          }
+        }
+      }
+      for (const segment of Object.keys(sourceNode)) {
+        // A language without this plural category (`_one` in Japanese) is not missing it.
+        if (!(segment in node) && !hasPluralSibling(node, segment)) {
+          const key = path ? `${path}.${segment}` : segment;
+          warnings.push({
+            rule: 'missing-translation',
+            locale,
+            key,
+            message: `renders the ${sourceLocale} text`,
+          });
+        }
+      }
+    })(source, isTree(tree) ? tree : {}, '');
+  }
+
+  return { errors, warnings };
+}
+
+/** Find and check every catalog under `root`. */
+export async function inspectTranslations(root, sourceLocale = DEFAULT_SOURCE_LOCALE) {
+  const catalogs = [];
+  for (const directory of await findCatalogDirectories(root, sourceLocale)) {
+    const loaded = await loadCatalogs(directory, sourceLocale);
+    catalogs.push({
+      directory: relative(root, directory) || '.',
+      layout: loaded.layout,
+      locales: [...loaded.locales.keys()].sort(),
+      ...checkCatalogs(loaded, sourceLocale),
+    });
+  }
+  return catalogs;
+}