@burdenoff/fe-libs 2026.1021.8 → 2026.1021.9

package/scripts/i18n/config.ts

@@ -0,0 +1,178 @@
+/**
+ * `i18n.config.json` parsing, and loading a shell's adapter module.
+ *
+ * A config that does not validate is a hard error (exit 2): a gate that
+ * silently degrades to "checked nothing" is the failure this toolkit removes.
+ */
+
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type {
+  AdapterBuild,
+  DigestOrder,
+  I18nAdapter,
+  ResolvedI18nToolsConfig,
+  ShippedKey,
+} from './types';
+
+export const DEFAULT_CONFIG_FILE = 'i18n.config.json';
+export const DEFAULT_SCOPE = '@burdenoff';
+export const DEFAULT_PACKAGES = ['microfe-*'];
+
+export class I18nConfigError extends Error {
+  readonly issues: string[];
+
+  constructor(issues: string[]) {
+    super(`Invalid i18n config:\n  - ${issues.join('\n  - ')}`);
+    this.name = 'I18nConfigError';
+    this.issues = issues;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+const KNOWN_KEYS = new Set([
+  '$schema',
+  '$comment',
+  'product',
+  'servedUrl',
+  'bundleFile',
+  'adapter',
+  'shipped',
+  'readsLeafSlot',
+  'digestOrder',
+]);
+
+function optionalString(
+  raw: Record<string, unknown>,
+  key: string,
+  issues: string[]
+): string | undefined {
+  const value = raw[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || value.trim() === '') {
+    issues.push(`"${key}" must be a non-empty string`);
+    return undefined;
+  }
+  return value;
+}
+
+/** Validate a parsed config and apply defaults; relative paths resolve against `configDir`. */
+export function resolveI18nConfig(raw: unknown, configDir: string): ResolvedI18nToolsConfig {
+  const issues: string[] = [];
+  if (!isRecord(raw)) throw new I18nConfigError(['config must be a JSON object']);
+
+  for (const key of Object.keys(raw)) {
+    if (!KNOWN_KEYS.has(key)) issues.push(`unknown key "${key}"`);
+  }
+
+  const product = optionalString(raw, 'product', issues);
+  if (product === undefined && !issues.some((i) => i.startsWith('"product"'))) {
+    issues.push('"product" is required');
+  }
+
+  const servedUrl = optionalString(raw, 'servedUrl', issues);
+  if (servedUrl !== undefined && !servedUrl.startsWith('https://')) {
+    issues.push('"servedUrl" must be an https:// URL');
+  }
+  const bundleFile = optionalString(raw, 'bundleFile', issues);
+  const adapter = optionalString(raw, 'adapter', issues);
+
+  let scope = DEFAULT_SCOPE;
+  let packages = DEFAULT_PACKAGES;
+  if (raw.shipped !== undefined) {
+    if (!isRecord(raw.shipped)) issues.push('"shipped" must be an object');
+    else {
+      const s = raw.shipped;
+      for (const key of Object.keys(s)) {
+        if (key !== 'scope' && key !== 'packages') issues.push(`unknown key "shipped.${key}"`);
+      }
+      if (s.scope !== undefined) {
+        if (typeof s.scope !== 'string' || !/^@[a-z0-9][a-z0-9._-]*$/.test(s.scope)) {
+          issues.push('"shipped.scope" must be an npm scope such as "@burdenoff"');
+        } else scope = s.scope;
+      }
+      if (s.packages !== undefined) {
+        if (
+          !Array.isArray(s.packages) ||
+          s.packages.length === 0 ||
+          !s.packages.every((p: unknown) => typeof p === 'string' && p !== '' && p !== '*')
+        ) {
+          issues.push(
+            '"shipped.packages" must be a non-empty array of package names (a trailing * is a prefix; a bare * is refused)'
+          );
+        } else {
+          // Narrowed by the `every` string check just above.
+          packages = s.packages as string[];
+        }
+      }
+    }
+  }
+
+  let readsLeafSlot = true;
+  if (raw.readsLeafSlot !== undefined) {
+    if (typeof raw.readsLeafSlot !== 'boolean') issues.push('"readsLeafSlot" must be a boolean');
+    else readsLeafSlot = raw.readsLeafSlot;
+  }
+
+  let digestOrder: DigestOrder = 'utf8';
+  if (raw.digestOrder !== undefined) {
+    if (raw.digestOrder !== 'utf8' && raw.digestOrder !== 'utf16') {
+      issues.push('"digestOrder" must be "utf8" or "utf16"');
+    } else digestOrder = raw.digestOrder;
+  }
+
+  if (issues.length > 0) throw new I18nConfigError(issues);
+
+  const abs = (path: string | undefined): string | undefined =>
+    path === undefined ? undefined : isAbsolute(path) ? path : resolve(configDir, path);
+
+  return {
+    // `issues` is empty, so the required "product" check above has passed.
+    product: product as string,
+    configDir,
+    ...(servedUrl !== undefined ? { servedUrl } : {}),
+    ...(bundleFile !== undefined ? { bundleFile: abs(bundleFile) } : {}),
+    ...(adapter !== undefined ? { adapter: abs(adapter) } : {}),
+    shipped: { scope, packages },
+    readsLeafSlot,
+    digestOrder,
+  };
+}
+
+/** Narrow an imported module to the adapter surface, refusing members of the wrong type. */
+export function toAdapter(mod: unknown, label: string): I18nAdapter {
+  if (!isRecord(mod)) throw new I18nConfigError([`${label} did not load as a module`]);
+  const source = isRecord(mod.default) ? mod.default : mod;
+  const issues: string[] = [];
+  const adapter: I18nAdapter = {};
+  const build = source.buildBundle;
+  if (build !== undefined) {
+    if (typeof build !== 'function') issues.push(`${label}: buildBundle must be a function`);
+    else adapter.buildBundle = build as () => Promise<AdapterBuild> | AdapterBuild;
+  }
+  const requested = source.requestedKeys;
+  if (requested !== undefined) {
+    if (typeof requested !== 'function') issues.push(`${label}: requestedKeys must be a function`);
+    else {
+      adapter.requestedKeys = requested as () =>
+        | Promise<Readonly<Record<string, ShippedKey>>>
+        | Readonly<Record<string, ShippedKey>>;
+    }
+  }
+  if (adapter.buildBundle === undefined && adapter.requestedKeys === undefined) {
+    issues.push(`${label}: exports neither buildBundle nor requestedKeys`);
+  }
+  if (issues.length > 0) throw new I18nConfigError(issues);
+  return adapter;
+}
+
+/** Import the configured adapter module (TypeScript is fine under Bun). */
+export async function loadAdapter(path: string): Promise<I18nAdapter> {
+  if (!existsSync(path)) throw new I18nConfigError([`adapter not found: ${path}`]);
+  const mod: unknown = await import(pathToFileURL(path).href);
+  return toAdapter(mod, path);
+}

package/scripts/i18n/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Programmatic entry point for the fleet i18n toolkit, for shell scripts and
+ * tests that import the shared pieces rather than shelling out to the CLI:
+ *
+ *   import { digestBundle, resolvableKeys } from '@burdenoff/fe-libs/scripts/i18n';
+ */
+
+export {
+  BundleError,
+  MAX_BUNDLE_BYTES,
+  bundleLocales,
+  bundleRows,
+  diffBundles,
+  digestBundle,
+  loadBundleSource,
+  localeRows,
+  parseBundle,
+  rowLine,
+  setDigest,
+  utf16Order,
+  utf8Order,
+} from './bundle';
+export {
+  DEFAULT_CONFIG_FILE,
+  DEFAULT_PACKAGES,
+  DEFAULT_SCOPE,
+  I18nConfigError,
+  loadAdapter,
+  resolveI18nConfig,
+  toAdapter,
+} from './config';
+export {
+  CommandError,
+  resolveSource,
+  runDiff,
+  runDigest,
+  runServedTree,
+  runVerifyShipped,
+} from './commands';
+export {
+  LEAF_SLOT,
+  LEAF_SLOT_FE_LIBS,
+  UNSAFE_SEGMENTS,
+  assertExportableKey,
+  buildNestedDictionary,
+  compareServed,
+  flattenServed,
+  hidingPrefix,
+  keyPath,
+  nestingPrefixes,
+  resolvableKeys,
+  resolveInApp,
+} from './servedTree';
+export type { NestedDoc, ServedComparison } from './servedTree';
+export {
+  CALL_PAIR,
+  collectShippedKeys,
+  matchingPackages,
+  missingFromBundle,
+  packageMatches,
+  shippedKeys,
+} from './shipped';
+export type * from './types';

package/scripts/i18n/servedTree.ts

@@ -0,0 +1,270 @@
+/**
+ * What an app shell is actually SERVED: the nested dictionary global-i18n-svc's
+ * `exportTranslations(format: JSON)` builds from a product's rows, and what
+ * fe-libs' runtime can resolve from it.
+ *
+ * VibeControls (`scripts/i18n-nested-export.ts`) and FluidGrids
+ * (`scripts/i18n-served-tree.ts`) each carried their own port of the same
+ * service algorithm. This is the one shared port, so a change to the service
+ * is modelled once.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE MODEL (global-i18n-svc src/modules/i18n/nested-keys.ts, 2026.920.1)
+ *
+ * A nested document holds a string OR an object at each path, so a key that is
+ * also a prefix of other keys (`channel.status` and `channel.status.active`)
+ * cannot keep its value at its own path:
+ *
+ *   - the SUBTREE keeps the path, whatever order the rows come back in
+ *     (2026.919.1, BOFF-7458);
+ *   - the displaced LEAF is served from its branch's `_` member (2026.920.1,
+ *     BOFF-7459): `channel.status._ = "Status"`. A key stored literally as
+ *     `<path>._` already fills that slot and keeps it.
+ *
+ * fe-libs' `resolveTranslationValue` walks `key.split('.')` and returns the
+ * string it lands on; from fe-libs 2026.919.1 it falls back to a branch's `_`
+ * string (`readsLeafSlot`). A shell that wants the conservative pre-slot model
+ * passes `readsLeafSlot: false` explicitly.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+/** A nested export document: every leaf is a served value. */
+export type NestedDoc = { [segment: string]: string | NestedDoc };
+
+/** Segments the export refuses: a key containing one is skipped. */
+export const UNSAFE_SEGMENTS: ReadonlySet<string> = new Set([
+  '__proto__',
+  'prototype',
+  'constructor',
+]);
+
+/** The member a branch serves its own displaced leaf from. */
+export const LEAF_SLOT = '_';
+
+/** The first fe-libs release whose runtime reads `LEAF_SLOT` (fe-libs#239). */
+export const LEAF_SLOT_FE_LIBS = '2026.919.1';
+
+function isBranch(value: unknown): value is NestedDoc {
+  return typeof value === 'object' && value !== null;
+}
+
+function ownValue(node: NestedDoc, segment: string): string | NestedDoc | undefined {
+  return Object.hasOwn(node, segment) ? node[segment] : undefined;
+}
+
+/**
+ * The path the export stores a key at, or `null` when it stores it nowhere:
+ * an empty segment is skipped (`a..b` is stored at `a.b`), an unsafe segment
+ * skips the key, and an empty LAST segment (`a.b.`) skips the key whole.
+ */
+export function keyPath(key: string): string[] | null {
+  const segments = key.split('.');
+  if (!segments[segments.length - 1]) return null;
+  if (segments.some((segment) => UNSAFE_SEGMENTS.has(segment))) return null;
+  return segments.filter((segment) => segment !== '');
+}
+
+/**
+ * Throw for a key the export cannot serve as itself: one with an empty
+ * segment (served under another path or not at all) or an unsafe segment
+ * (not served). Builders call this before emitting a key.
+ */
+export function assertExportableKey(key: string): void {
+  const parts = key.split('.');
+  if (parts.some((part) => part === '')) {
+    throw new Error(
+      `key ${JSON.stringify(key)} has an empty segment; the nested export would serve it under another path`
+    );
+  }
+  const unsafe = parts.find((part) => UNSAFE_SEGMENTS.has(part));
+  if (unsafe !== undefined) {
+    throw new Error(
+      `key ${JSON.stringify(key)} has a ${unsafe} segment, which the nested export skips`
+    );
+  }
+}
+
+function branchAt(root: NestedDoc, path: readonly string[]): NestedDoc | undefined {
+  let current: string | NestedDoc | undefined = root;
+  for (const segment of path) {
+    if (!isBranch(current)) return undefined;
+    current = ownValue(current, segment);
+  }
+  return isBranch(current) ? current : undefined;
+}
+
+/**
+ * The document global-i18n-svc builds from one locale's rows (its
+ * `buildNestedDictionary`). Pass 1 is the shape: the subtree wins over a
+ * colliding leaf in either row order, recording each displaced leaf. Pass 2
+ * writes each displaced leaf into its branch's `_` slot unless a literal
+ * `<path>._` key already owns it. The result depends only on the SET of rows,
+ * except where two rows name one path (a repeated key, or `a.b` and `a..b`),
+ * where the last read wins exactly as in the service.
+ */
+export function buildNestedDictionary(rows: Iterable<readonly [string, string]>): NestedDoc {
+  const root: NestedDoc = {};
+  const displaced = new Map<string, { path: string[]; value: string }>();
+
+  for (const [key, value] of rows) {
+    const path = keyPath(key);
+    if (!path) continue;
+    const last = path.at(-1);
+    if (last === undefined) continue;
+
+    let cursor: NestedDoc = root;
+    for (const [depth, segment] of path.slice(0, -1).entries()) {
+      const existing = ownValue(cursor, segment);
+      if (isBranch(existing)) {
+        cursor = existing;
+        continue;
+      }
+      if (typeof existing === 'string') {
+        const leafPath = path.slice(0, depth + 1);
+        displaced.set(leafPath.join('.'), { path: leafPath, value: existing });
+      }
+      const branch: NestedDoc = {};
+      cursor[segment] = branch;
+      cursor = branch;
+    }
+
+    if (isBranch(ownValue(cursor, last))) {
+      displaced.set(path.join('.'), { path, value });
+      continue;
+    }
+    cursor[last] = value;
+  }
+
+  for (const { path, value } of displaced.values()) {
+    const branch = branchAt(root, path);
+    if (branch && !Object.hasOwn(branch, LEAF_SLOT)) branch[LEAF_SLOT] = value;
+  }
+
+  return root;
+}
+
+/** Every string path of a nested document, `_` members included. */
+export function flattenServed(doc: NestedDoc): Map<string, string> {
+  const out = new Map<string, string>();
+  const walk = (node: NestedDoc, prefix: string): void => {
+    for (const [segment, value] of Object.entries(node)) {
+      const path = prefix ? `${prefix}.${segment}` : segment;
+      if (typeof value === 'string') out.set(path, value);
+      else walk(value, path);
+    }
+  };
+  walk(doc, '');
+  return out;
+}
+
+/**
+ * What fe-libs resolves for `key` in `doc`: walk the RAW segments (so `a..b`
+ * resolves nothing even though the export stores it at `a.b`) and take the
+ * string landed on; with `readsLeafSlot`, a branch falls back to its `_`
+ * string.
+ */
+export function resolveInApp(
+  doc: NestedDoc,
+  key: string,
+  readsLeafSlot = true
+): string | undefined {
+  let current: string | NestedDoc | undefined = doc;
+  for (const segment of key.split('.')) {
+    if (!isBranch(current)) return undefined;
+    current = ownValue(current, segment);
+  }
+  if (typeof current === 'string') return current;
+  if (!readsLeafSlot || !isBranch(current)) return undefined;
+  const leaf = ownValue(current, LEAF_SLOT);
+  return typeof leaf === 'string' ? leaf : undefined;
+}
+
+/**
+ * key -> value for every row key the runtime can resolve from the document
+ * those rows produce. A row is counted under the path it is stored at, which is
+ * the key a call site looks up; the synthetic `_` a displaced leaf occupies
+ * belongs to no row and is not counted.
+ */
+export function resolvableKeys(
+  rows: Iterable<readonly [string, string]>,
+  readsLeafSlot = true
+): Map<string, string> {
+  const materialised = [...rows];
+  const doc = buildNestedDictionary(materialised);
+  const out = new Map<string, string>();
+  for (const [key] of materialised) {
+    const lookup = keyPath(key)?.join('.');
+    if (lookup === undefined) continue;
+    const value = resolveInApp(doc, lookup, readsLeafSlot);
+    if (value !== undefined) out.set(lookup, value);
+  }
+  return out;
+}
+
+/**
+ * The paths a value for `key` turns into branches: every non-empty segment but
+ * the last (`a.b.c` walks `a` and `a.b`). A key with an unsafe segment walks
+ * nothing, because the export skips it.
+ */
+export function nestingPrefixes(key: string): string[] {
+  const all = key.split('.');
+  if (all.some((part) => UNSAFE_SEGMENTS.has(part))) return [];
+  const parents = all.slice(0, -1).filter(Boolean);
+  return parents.map((_, n) => parents.slice(0, n + 1).join('.'));
+}
+
+/**
+ * The key resolved today that a NEW value for `key` would stop serving (or
+ * serve differently), or undefined when the value is safe to add.
+ *
+ * Without the slot, every resolved prefix the new key walks through is lost.
+ * With it, a displaced prefix P still resolves from `P._`, unless the new key
+ * runs through that very slot (`P._` takes it, `P._.x` makes it a branch).
+ */
+export function hidingPrefix(
+  key: string,
+  resolved: ReadonlySet<string> | ReadonlyMap<string, string>,
+  readsLeafSlot = true
+): string | undefined {
+  const prefixes = nestingPrefixes(key);
+  const parts = key.split('.').filter(Boolean);
+  return prefixes.find(
+    (prefix, i) => resolved.has(prefix) && (!readsLeafSlot || parts[i + 1] === LEAF_SLOT)
+  );
+}
+
+/** What one locale resolves before vs after a change. */
+export interface ServedComparison {
+  before: number;
+  after: number;
+  /** Keys resolved before and not after, sorted. */
+  lost: string[];
+  /** Keys resolved both times whose value changed, sorted. */
+  changed: string[];
+  /** Keys resolved after and not before. */
+  gained: number;
+}
+
+/** Compare two `resolvableKeys` results: every key resolved before must still be. */
+export function compareServed(
+  before: ReadonlyMap<string, string>,
+  after: ReadonlyMap<string, string>
+): ServedComparison {
+  const lost: string[] = [];
+  const changed: string[] = [];
+  for (const [key, value] of before) {
+    const next = after.get(key);
+    if (next === undefined) lost.push(key);
+    else if (next !== value) changed.push(key);
+  }
+  let gained = 0;
+  for (const key of after.keys()) if (!before.has(key)) gained++;
+  const byCodePoint = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+  return {
+    before: before.size,
+    after: after.size,
+    lost: lost.sort(byCodePoint),
+    changed: changed.sort(byCodePoint),
+    gained,
+  };
+}

package/scripts/i18n/shipped.ts

@@ -0,0 +1,99 @@
+/**
+ * The i18n keys the code that ACTUALLY SHIPS asks for.
+ *
+ * A shell's extractor reads microfrontend sources at origin/main, but the app
+ * ships the PINNED published packages, and the two can disagree. If main has
+ * renamed a key the pinned build still calls, the bundle omits it and users
+ * read English. Compiled bundles keep the call shape — `tr(key, fallback)`
+ * survives minification as `x("auth.login.welcomeBack", "Welcome back")` — so
+ * matching the (key, fallback) PAIR in `dist` recovers what the pinned code
+ * requests. Matching lone dotted strings would sweep up analytics event names,
+ * route ids and config paths; requiring an adjacent prose fallback keeps those
+ * out.
+ *
+ * Lifted from vibecontrols-app and fluidgrids-app `scripts/verify-shipped-i18n.ts`
+ * (BOFF-7300); the package filter is configuration instead of a constant.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ShippedKey } from './types';
+
+/**
+ * `<fn>("some.dotted.key", "Some English fallback")`: both literals, adjacent,
+ * as the first two arguments. The key shape is the extractors' (any depth).
+ */
+export const CALL_PAIR =
+  /\w+\(\s*"([a-z][a-zA-Z0-9]*(?:\.[A-Za-z0-9_-]+)+)"\s*,\s*"([^"\\]{2,300})"\s*[),]/g;
+
+/** Add every key -> first (package, fallback) pair found in one compiled source. */
+export function collectShippedKeys(
+  pkg: string,
+  source: string,
+  into: Map<string, ShippedKey> = new Map()
+): Map<string, ShippedKey> {
+  for (const match of source.matchAll(CALL_PAIR)) {
+    const key = match[1];
+    const fallback = match[2];
+    if (key === undefined || fallback === undefined) continue;
+    // A real UI fallback reads like prose; identifiers and numbers do not.
+    if (!/[a-zA-Z]/.test(fallback)) continue;
+    if (!into.has(key)) into.set(key, { pkg, fallback });
+  }
+  return into;
+}
+
+/** Whether `name` (unscoped) matches one of `patterns`; a trailing `*` is a prefix match. */
+export function packageMatches(name: string, patterns: readonly string[]): boolean {
+  return patterns.some((pattern) =>
+    pattern.endsWith('*') ? name.startsWith(pattern.slice(0, -1)) : name === pattern
+  );
+}
+
+function walkJs(dir: string): string[] {
+  const out: string[] = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir).sort()) {
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) {
+      if (entry !== 'node_modules') out.push(...walkJs(path));
+    } else if (entry.endsWith('.js') || entry.endsWith('.mjs')) out.push(path);
+  }
+  return out;
+}
+
+/** The packages under `scopeDir` that match `patterns`, sorted. */
+export function matchingPackages(scopeDir: string, patterns: readonly string[]): string[] {
+  if (!existsSync(scopeDir)) return [];
+  return readdirSync(scopeDir)
+    .filter((name) => packageMatches(name, patterns))
+    .sort();
+}
+
+/**
+ * Every key the installed, compiled packages request. Scans each matching
+ * package's `dist`; the first package (alphabetically) to request a key names it.
+ */
+export function shippedKeys(
+  scopeDir: string,
+  patterns: readonly string[]
+): Map<string, ShippedKey> {
+  const found = new Map<string, ShippedKey>();
+  for (const pkg of matchingPackages(scopeDir, patterns)) {
+    for (const file of walkJs(join(scopeDir, pkg, 'dist'))) {
+      collectShippedKeys(pkg, readFileSync(file, 'utf8'), found);
+    }
+  }
+  return found;
+}
+
+/** Shipped keys the bundle does not define, sorted by key. */
+export function missingFromBundle(
+  shipped: ReadonlyMap<string, ShippedKey>,
+  bundleKeys: Iterable<string>
+): Array<[string, ShippedKey]> {
+  const have = new Set(bundleKeys);
+  return [...shipped.entries()]
+    .filter(([key]) => !have.has(key))
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}