@burdenoff/fe-libs 2026.1021.8 → 2026.1021.9

package/scripts/i18n/cli.ts

@@ -0,0 +1,281 @@
+#!/usr/bin/env bun
+/**
+ * burdenoff-i18n — the fleet's shared i18n bundle gates.
+ *
+ * App shells each carried ~20 i18n scripts; the product-agnostic ones are
+ * here, configured by an `i18n.config.json` at the shell root. What stays in a
+ * shell is what reads that shell's own translation sources (the extractor and
+ * bundle builder), exposed to these commands through a small adapter module.
+ *
+ * Usage (from a shell root, after `bun install`):
+ *   burdenoff-i18n <command> [--config=i18n.config.json] [options]
+ * or
+ *   bun run node_modules/@burdenoff/fe-libs/scripts/i18n/cli.ts <command> …
+ *
+ * Commands:
+ *   verify-shipped [--bundle=<src>] [--warn]
+ *       Every key the installed, compiled packages request is in the bundle
+ *       (default <src>: built), or held back on purpose by the builder.
+ *   digest [<src>] [--order=utf8|utf16]
+ *       Print key/row counts and set digests (default <src>: built) as JSON.
+ *   diff <base> <proposed> [--allow-updates] [--allow-deletions] [--json=PATH] [--limit=N]
+ *       The additive-seed contract: fail if seeding <proposed> over <base>
+ *       would change or delete a served row.
+ *   served-tree [<src>] [--baseline=<src>] [--reads-leaf-slot=true|false] [--limit=N]
+ *       Model global-i18n-svc's nested export per locale and fail when a key
+ *       would not be served as the bundle says (with --baseline: when a key
+ *       resolved today would be hidden or shadowed).
+ *
+ * <src> is `built` (the adapter's buildBundle(), else bundleFile), `served`
+ * (servedUrl), a file path, or an https:// URL.
+ *
+ * Exit codes: 0 pass · 1 the check found a problem · 2 the check could not run.
+ */
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { BundleError } from './bundle';
+import {
+  CommandError,
+  runDiff,
+  runDigest,
+  runServedTree,
+  runVerifyShipped,
+  type CommandContext,
+} from './commands';
+import { DEFAULT_CONFIG_FILE, I18nConfigError, resolveI18nConfig } from './config';
+import type { DigestOrder, ResolvedI18nToolsConfig } from './types';
+
+export const COMMANDS = ['verify-shipped', 'digest', 'diff', 'served-tree'] as const;
+export type CommandName = (typeof COMMANDS)[number];
+
+export interface ParsedCli {
+  command: CommandName;
+  configPath: string;
+  /** Whether --config was passed: then a missing file is an error. */
+  configExplicit: boolean;
+  positionals: string[];
+  warn: boolean;
+  bundle?: string;
+  order?: DigestOrder;
+  allowUpdates: boolean;
+  allowDeletions: boolean;
+  jsonPath?: string;
+  limit?: number;
+  baseline?: string;
+  readsLeafSlot?: boolean;
+}
+
+export class UsageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+const isCommand = (value: string | undefined): value is CommandName =>
+  value !== undefined && (COMMANDS as readonly string[]).includes(value);
+
+const ARITY: Readonly<Record<CommandName, { min: number; max: number }>> = {
+  'verify-shipped': { min: 0, max: 0 },
+  digest: { min: 0, max: 1 },
+  diff: { min: 2, max: 2 },
+  'served-tree': { min: 0, max: 1 },
+};
+
+/** Parse argv (without the runtime and script) into a validated invocation. */
+export function parseCli(argv: readonly string[]): ParsedCli {
+  const [command, ...rest] = argv;
+  if (!isCommand(command)) {
+    throw new UsageError(
+      `${command === undefined ? 'missing command' : `unknown command "${command}"`}; ` +
+        `expected one of: ${COMMANDS.join(', ')}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: [...rest],
+      allowPositionals: true,
+      strict: true,
+      options: {
+        config: { type: 'string' },
+        warn: { type: 'boolean', default: false },
+        bundle: { type: 'string' },
+        order: { type: 'string' },
+        'allow-updates': { type: 'boolean', default: false },
+        'allow-deletions': { type: 'boolean', default: false },
+        json: { type: 'string' },
+        limit: { type: 'string' },
+        baseline: { type: 'string' },
+        'reads-leaf-slot': { type: 'string' },
+      },
+    });
+  } catch (error) {
+    throw new UsageError((error as Error).message);
+  }
+  const { values, positionals } = parsed;
+  const arity = ARITY[command];
+  if (positionals.length < arity.min || positionals.length > arity.max) {
+    throw new UsageError(
+      `${command} takes ${arity.min === arity.max ? arity.min : `${arity.min}-${arity.max}`} ` +
+        `positional argument(s), got ${positionals.length}`
+    );
+  }
+
+  let order: DigestOrder | undefined;
+  if (values.order !== undefined) {
+    if (values.order !== 'utf8' && values.order !== 'utf16') {
+      throw new UsageError('--order must be utf8 or utf16');
+    }
+    order = values.order;
+  }
+  let limit: number | undefined;
+  if (values.limit !== undefined) {
+    limit = Number(values.limit);
+    if (!Number.isInteger(limit) || limit < 0)
+      throw new UsageError('--limit must be a whole number');
+  }
+  let readsLeafSlot: boolean | undefined;
+  const slot = values['reads-leaf-slot'];
+  if (slot !== undefined) {
+    if (slot !== 'true' && slot !== 'false') {
+      throw new UsageError('--reads-leaf-slot must be true or false');
+    }
+    readsLeafSlot = slot === 'true';
+  }
+
+  return {
+    command,
+    configPath: values.config ?? DEFAULT_CONFIG_FILE,
+    configExplicit: values.config !== undefined,
+    positionals,
+    warn: values.warn ?? false,
+    ...(values.bundle !== undefined ? { bundle: values.bundle } : {}),
+    ...(order !== undefined ? { order } : {}),
+    allowUpdates: values['allow-updates'] ?? false,
+    allowDeletions: values['allow-deletions'] ?? false,
+    ...(values.json !== undefined ? { jsonPath: values.json } : {}),
+    ...(limit !== undefined ? { limit } : {}),
+    ...(values.baseline !== undefined ? { baseline: values.baseline } : {}),
+    ...(readsLeafSlot !== undefined ? { readsLeafSlot } : {}),
+  };
+}
+
+/** Read the config when present; a missing default config is allowed for path-only commands. */
+export function readConfig(cli: ParsedCli, cwd: string): ResolvedI18nToolsConfig | undefined {
+  const path = resolve(cwd, cli.configPath);
+  if (!existsSync(path)) {
+    if (cli.configExplicit || cli.command === 'verify-shipped') {
+      throw new I18nConfigError([
+        `config not found: ${path} (see @burdenoff/fe-libs/scripts/i18n/README.md)`,
+      ]);
+    }
+    return undefined;
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+  } catch (error) {
+    throw new I18nConfigError([`${path} is not valid JSON: ${(error as Error).message}`]);
+  }
+  return resolveI18nConfig(raw, dirname(path));
+}
+
+/** Run one invocation; returns the exit code. */
+export async function runCli(
+  argv: readonly string[],
+  ctx: Omit<CommandContext, 'config'> = {}
+): Promise<number> {
+  const log = ctx.log ?? ((line: string) => console.error(line));
+  const cwd = ctx.cwd ?? process.cwd();
+  try {
+    const cli = parseCli(argv);
+    const config = readConfig(cli, cwd);
+    const context: CommandContext = { ...ctx, cwd, log, ...(config ? { config } : {}) };
+    switch (cli.command) {
+      case 'verify-shipped':
+        return await runVerifyShipped(
+          { warn: cli.warn, ...(cli.bundle !== undefined ? { bundle: cli.bundle } : {}) },
+          context
+        );
+      case 'digest':
+        return await runDigest(
+          { source: cli.positionals[0] ?? 'built', ...(cli.order ? { order: cli.order } : {}) },
+          context
+        );
+      case 'diff': {
+        const [base, proposed] = cli.positionals as [string, string];
+        return await runDiff(
+          {
+            base,
+            proposed,
+            allowUpdates: cli.allowUpdates,
+            allowDeletions: cli.allowDeletions,
+            ...(cli.limit !== undefined ? { limit: cli.limit } : {}),
+            ...(cli.jsonPath !== undefined
+              ? {
+                  onDiff: (diff) => {
+                    const out = resolve(cwd, cli.jsonPath as string);
+                    mkdirSync(dirname(out), { recursive: true });
+                    writeFileSync(out, `${JSON.stringify(diff, null, 2)}\n`, 'utf8');
+                    log(`[burdenoff-i18n] diff written to ${out}`);
+                  },
+                }
+              : {}),
+          },
+          context
+        );
+      }
+      case 'served-tree':
+        return await runServedTree(
+          {
+            proposed: cli.positionals[0] ?? 'built',
+            ...(cli.baseline !== undefined ? { baseline: cli.baseline } : {}),
+            ...(cli.readsLeafSlot !== undefined ? { readsLeafSlot: cli.readsLeafSlot } : {}),
+            ...(cli.limit !== undefined ? { limit: cli.limit } : {}),
+          },
+          context
+        );
+    }
+  } catch (error) {
+    if (
+      error instanceof UsageError ||
+      error instanceof I18nConfigError ||
+      error instanceof BundleError ||
+      error instanceof CommandError
+    ) {
+      log(`[burdenoff-i18n] ${error.message}`);
+      return 2;
+    }
+    log(`[burdenoff-i18n] unexpected failure: ${(error as Error).stack ?? String(error)}`);
+    return 2;
+  }
+}
+
+/**
+ * Whether this file is the process entry point. A package `bin` runs through a
+ * symlink in node_modules/.bin, so both sides are compared after realpath.
+ */
+export function isEntryPoint(argv1: string | undefined, moduleUrl: string): boolean {
+  if (argv1 === undefined) return false;
+  try {
+    return realpathSync(resolve(argv1)) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+const invokedDirectly = isEntryPoint(process.argv[1], import.meta.url);
+
+if (invokedDirectly) {
+  runCli(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (error: unknown) => {
+      console.error(`[burdenoff-i18n] unexpected failure: ${String(error)}`);
+      process.exit(2);
+    }
+  );
+}

package/scripts/i18n/commands.ts

@@ -0,0 +1,370 @@
+/**
+ * The `burdenoff-i18n` subcommands, as functions that return an exit code.
+ *
+ * Exit codes (every command):
+ *   0  the check passed / the report was produced
+ *   1  the check found a problem (missing keys, a non-additive seed, a lost key)
+ *   2  the check could not run (bad config, unreadable bundle, nothing to check)
+ *
+ * A check that could not look at anything is exit 2, never a pass.
+ */
+
+import { join, resolve } from 'node:path';
+import {
+  bundleLocales,
+  diffBundles,
+  digestBundle,
+  loadBundleSource,
+  localeRows,
+  type LoadOptions,
+} from './bundle';
+import { loadAdapter } from './config';
+import { compareServed, resolvableKeys } from './servedTree';
+import { missingFromBundle, shippedKeys } from './shipped';
+import type {
+  BundleDiff,
+  DigestOrder,
+  I18nAdapter,
+  I18nBundle,
+  ResolvedI18nToolsConfig,
+  RowChange,
+  ShippedKey,
+} from './types';
+
+export type Log = (line: string) => void;
+
+export interface CommandContext {
+  config?: ResolvedI18nToolsConfig;
+  /** Injected adapter (tests); otherwise loaded from `config.adapter`. */
+  adapter?: I18nAdapter;
+  load?: LoadOptions;
+  log?: Log;
+  cwd?: string;
+}
+
+export class CommandError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CommandError';
+  }
+}
+
+const defaultLog: Log = (line) => console.error(line);
+
+async function adapterOf(ctx: CommandContext): Promise<I18nAdapter | undefined> {
+  if (ctx.adapter) return ctx.adapter;
+  if (ctx.config?.adapter) {
+    ctx.adapter = await loadAdapter(ctx.config.adapter);
+    return ctx.adapter;
+  }
+  return undefined;
+}
+
+export interface ResolvedSource {
+  label: string;
+  bundle: I18nBundle;
+  heldBack: Map<string, string>;
+}
+
+function toHeldBackMap(
+  value: ReadonlyMap<string, string> | Readonly<Record<string, string>> | undefined
+): Map<string, string> {
+  if (value === undefined) return new Map();
+  if (value instanceof Map) return new Map(value);
+  return new Map(Object.entries(value as Readonly<Record<string, string>>));
+}
+
+/**
+ * Resolve a bundle source spec:
+ *   - `served` -> the config's `servedUrl`;
+ *   - `built`  -> the adapter's `buildBundle()`, else the config's `bundleFile`;
+ *   - anything else -> a file path (relative to cwd) or an https:// URL.
+ */
+export async function resolveSource(spec: string, ctx: CommandContext): Promise<ResolvedSource> {
+  const { config } = ctx;
+  if (spec === 'served') {
+    if (!config?.servedUrl)
+      throw new CommandError('"served" needs "servedUrl" in i18n.config.json');
+    return {
+      label: config.servedUrl,
+      bundle: await loadBundleSource(config.servedUrl, ctx.load),
+      heldBack: new Map(),
+    };
+  }
+  if (spec === 'built') {
+    const adapter = await adapterOf(ctx);
+    if (adapter?.buildBundle) {
+      const built = await adapter.buildBundle();
+      return {
+        label: 'built bundle',
+        bundle: built.bundle,
+        heldBack: toHeldBackMap(built.heldBack),
+      };
+    }
+    if (config?.bundleFile) {
+      return {
+        label: config.bundleFile,
+        bundle: await loadBundleSource(config.bundleFile, ctx.load),
+        heldBack: new Map(),
+      };
+    }
+    throw new CommandError(
+      '"built" needs an adapter with buildBundle() or "bundleFile" in i18n.config.json'
+    );
+  }
+  const path = /^[a-z]+:\/\//i.test(spec) ? spec : resolve(ctx.cwd ?? process.cwd(), spec);
+  return { label: spec, bundle: await loadBundleSource(path, ctx.load), heldBack: new Map() };
+}
+
+// ─── verify-shipped ────────────────────────────────────────────────────────
+
+export interface VerifyShippedOptions {
+  warn?: boolean;
+  /** Bundle to check against; default `built`. */
+  bundle?: string;
+  /** Directory of the installed scope; default `<configDir>/node_modules/<scope>`. */
+  scopeDir?: string;
+}
+
+/**
+ * Every key the installed, compiled packages request must be in the bundle,
+ * or held back on purpose by the shell's builder.
+ */
+export async function runVerifyShipped(
+  options: VerifyShippedOptions,
+  ctx: CommandContext
+): Promise<number> {
+  const log = ctx.log ?? defaultLog;
+  const config = ctx.config;
+  if (!config) throw new CommandError('verify-shipped needs an i18n.config.json');
+  const failCode = options.warn ? 0 : 1;
+  const scopeDir = options.scopeDir ?? join(config.configDir, 'node_modules', config.shipped.scope);
+
+  const shipped = shippedKeys(scopeDir, config.shipped.packages);
+  if (shipped.size === 0) {
+    log(
+      `❌ No compiled ${config.shipped.scope}/{${config.shipped.packages.join(',')}} ` +
+        `packages found under ${scopeDir} — run \`bun install\` first.`
+    );
+    return 2;
+  }
+
+  const adapter = await adapterOf(ctx);
+  if (adapter?.requestedKeys) {
+    const extra = await adapter.requestedKeys();
+    for (const [key, value] of Object.entries(extra)) {
+      if (!shipped.has(key)) shipped.set(key, value);
+    }
+  }
+
+  const source = await resolveSource(options.bundle ?? 'built', ctx);
+  const absent = missingFromBundle(
+    shipped,
+    source.bundle.keys.map((k) => k.key)
+  );
+  const held = absent.filter(([key]) => source.heldBack.has(key));
+  const missing = absent.filter(([key]) => !source.heldBack.has(key));
+
+  log(
+    `\n[${config.product}] Shipped packages request ${shipped.size} i18n keys; ${source.label} ` +
+      `defines ${shipped.size - absent.length}, and holds back ${held.length} on purpose.`
+  );
+  if (held.length > 0) {
+    const byReason = new Map<string, number>();
+    for (const [key] of held) {
+      const reason = source.heldBack.get(key) ?? 'held back';
+      byReason.set(reason, (byReason.get(reason) ?? 0) + 1);
+    }
+    log('\nHeld back (not seeded; users read the call site fallback):');
+    for (const [reason, n] of [...byReason].sort((a, b) => b[1] - a[1])) {
+      log(`   ${String(n).padStart(5)}  ${reason}`);
+    }
+  }
+  if (missing.length === 0) {
+    log('✅ Every key the shipped code asks for is in the bundle, or held back on purpose.\n');
+    return 0;
+  }
+
+  const byPkg = new Map<string, number>();
+  for (const [, v] of missing) byPkg.set(v.pkg, (byPkg.get(v.pkg) ?? 0) + 1);
+  log(`\n❌ ${missing.length} key(s) requested by shipped code are MISSING:\n`);
+  for (const [pkg, n] of [...byPkg.entries()].sort((a, b) => b[1] - a[1])) {
+    log(`   ${pkg.padEnd(32)} ${n}`);
+  }
+  log('');
+  for (const [key, v] of missing.slice(0, 25)) {
+    log(`   ${key}\n      (${v.pkg}) "${v.fallback.slice(0, 60)}"`);
+  }
+  if (missing.length > 25) log(`   … and ${missing.length - 25} more`);
+  log(
+    '\nEvery locale reads the call site English for these. Re-run the shell extractor, ' +
+      'or list pinned-only / dynamic keys in its dynamic-keys file.\n'
+  );
+  return failCode;
+}
+
+// ─── digest ────────────────────────────────────────────────────────────────
+
+export interface DigestOptions {
+  source: string;
+  order?: DigestOrder;
+  /** Print to this sink instead of stdout (tests). */
+  out?: Log;
+}
+
+/** Print a bundle's counts and set digests as JSON. */
+export async function runDigest(options: DigestOptions, ctx: CommandContext): Promise<number> {
+  const source = await resolveSource(options.source, ctx);
+  const order = options.order ?? ctx.config?.digestOrder ?? 'utf8';
+  const out = options.out ?? ((line: string) => console.log(line));
+  out(JSON.stringify({ source: source.label, ...digestBundle(source.bundle, order) }, null, 2));
+  return 0;
+}
+
+// ─── diff ──────────────────────────────────────────────────────────────────
+
+export interface DiffOptions {
+  base: string;
+  proposed: string;
+  allowUpdates?: boolean;
+  allowDeletions?: boolean;
+  /** Rows of each kind to print. */
+  limit?: number;
+  /** Receives the full diff (the CLI writes it to --json). */
+  onDiff?: (diff: BundleDiff) => void;
+}
+
+function printRows(log: Log, title: string, rows: readonly RowChange[], limit: number): void {
+  if (rows.length === 0) return;
+  log(`\n${title} (${rows.length}):`);
+  for (const row of rows.slice(0, limit)) {
+    const before = row.before === null ? '∅' : JSON.stringify(row.before.slice(0, 60));
+    const after = row.after === null ? '∅' : JSON.stringify(row.after.slice(0, 60));
+    log(`   ${row.key} [${row.locale}]  ${before} → ${after}`);
+  }
+  if (rows.length > limit) log(`   … and ${rows.length - limit} more`);
+}
+
+/**
+ * The additive-seed contract: seeding `proposed` over `base` may insert rows,
+ * but changes or removes none unless explicitly allowed.
+ */
+export async function runDiff(options: DiffOptions, ctx: CommandContext): Promise<number> {
+  const log = ctx.log ?? defaultLog;
+  const base = await resolveSource(options.base, ctx);
+  const proposed = await resolveSource(options.proposed, ctx);
+  const diff = diffBundles(base.bundle, proposed.bundle);
+  options.onDiff?.(diff);
+  const limit = options.limit ?? 25;
+
+  log(
+    `\n${base.label} (${diff.base.keys} keys, ${diff.base.rows} rows) → ` +
+      `${proposed.label} (${diff.proposed.keys} keys, ${diff.proposed.rows} rows)`
+  );
+  log(
+    `   inserts ${diff.inserts.length}, updates ${diff.updates.length}, deletions ${diff.deletions.length}; ` +
+      `new keys ${diff.newKeys.length}, removed keys ${diff.removedKeys.length}`
+  );
+  const byLocale = Object.entries(diff.insertsByLocale)
+    .map(([l, n]) => `${l}=${n}`)
+    .join(' ');
+  if (byLocale) log(`   inserts by locale: ${byLocale}`);
+  printRows(log, 'Updates', diff.updates, limit);
+  printRows(log, 'Deletions', diff.deletions, limit);
+
+  const blocking: string[] = [];
+  if (diff.updates.length > 0 && !options.allowUpdates) {
+    blocking.push(`${diff.updates.length} served value(s) would change`);
+  }
+  if (diff.deletions.length > 0 && !options.allowDeletions) {
+    blocking.push(`${diff.deletions.length} served row(s) would be deleted`);
+  }
+  if (blocking.length > 0) {
+    log(
+      `\n❌ Not additive: ${blocking.join('; ')}. Pass --allow-updates / --allow-deletions only ` +
+        'for a reviewed, intended change.\n'
+    );
+    return 1;
+  }
+  log('\n✅ Additive: nothing served is changed or deleted.\n');
+  return 0;
+}
+
+// ─── served-tree ───────────────────────────────────────────────────────────
+
+export interface ServedTreeOptions {
+  proposed: string;
+  /** Compare with this bundle (normally `served`); without it, report every unresolvable key. */
+  baseline?: string;
+  readsLeafSlot?: boolean;
+  limit?: number;
+}
+
+/**
+ * Model the nested export per locale. With a baseline, fail when a key the
+ * runtime resolves today would stop resolving or resolve to another value
+ * than the proposed bundle's own; without one, fail on any bundle value the
+ * runtime cannot read back.
+ */
+export async function runServedTree(
+  options: ServedTreeOptions,
+  ctx: CommandContext
+): Promise<number> {
+  const log = ctx.log ?? defaultLog;
+  const readsLeafSlot = options.readsLeafSlot ?? ctx.config?.readsLeafSlot ?? true;
+  const limit = options.limit ?? 25;
+  const proposed = await resolveSource(options.proposed, ctx);
+  const baseline = options.baseline ? await resolveSource(options.baseline, ctx) : undefined;
+
+  const locales = bundleLocales(proposed.bundle);
+  if (locales.length === 0) {
+    log(`❌ ${proposed.label} carries no rows.`);
+    return 2;
+  }
+
+  let problems = 0;
+  for (const locale of locales) {
+    const rows = localeRows(proposed.bundle, locale);
+    const after = resolvableKeys(rows, readsLeafSlot);
+    if (baseline) {
+      const before = resolvableKeys(localeRows(baseline.bundle, locale), readsLeafSlot);
+      const cmp = compareServed(before, after);
+      // A changed value is fine when it IS the proposed value for that key
+      // (an intended update, which `diff` gates); it is a problem when the
+      // nested export serves something else at that key.
+      // A key the proposed bundle no longer carries at all is a deletion,
+      // which `diff` reports and gates; here only nesting effects count.
+      const proposedValue = new Map(rows);
+      const lost = cmp.lost.filter((key) => proposedValue.has(key));
+      const shadowed = cmp.changed.filter((key) => after.get(key) !== proposedValue.get(key));
+      const bad = [...lost, ...shadowed];
+      log(
+        `[${locale}] resolves ${cmp.before} → ${cmp.after} (+${cmp.gained}); ` +
+          `hidden ${lost.length}, shadowed ${shadowed.length}`
+      );
+      for (const key of bad.slice(0, limit)) log(`   ${key}`);
+      if (bad.length > limit) log(`   … and ${bad.length - limit} more`);
+      problems += bad.length;
+    } else {
+      const unreadable = rows
+        .filter(([key, value]) => after.get(key) !== value)
+        .map(([key]) => key);
+      log(`[${locale}] ${rows.length} rows; ${unreadable.length} not read back as themselves`);
+      for (const key of unreadable.slice(0, limit)) log(`   ${key}`);
+      if (unreadable.length > limit) log(`   … and ${unreadable.length - limit} more`);
+      problems += unreadable.length;
+    }
+  }
+
+  if (problems > 0) {
+    log(
+      `\n❌ ${problems} key/locale pair(s) would not be served as the bundle says ` +
+        `(readsLeafSlot=${readsLeafSlot}).\n`
+    );
+    return 1;
+  }
+  log(`\n✅ Every key resolves as the bundle says (readsLeafSlot=${readsLeafSlot}).\n`);
+  return 0;
+}
+
+export type { ShippedKey };