@xndrjs/i18n 0.8.1 → 0.8.2-alpha.1

package/src/audit/audit-dictionaries.ts

@@ -1,178 +0,0 @@
-import path from "node:path";
-import type { DictionaryJson } from "../codegen/types.js";
-import { buildRequiredLocales, enrichLocaleFallback } from "../codegen/locale-policy.js";
-import { resolveLocaleTemplate } from "../resolve-locale.js";
-import { CodegenConfig } from "../codegen/codegen-config-schema.js";
-
-export type FailOnCriterion = "effective" | "direct" | "any";
-
-export interface I18nAuditReport {
-  requiredLocales: string[];
-  localeFallback?: Record<string, string | null>;
-  summary: Record<string, Record<string, { missingDirect: number; missingEffective: number }>>;
-  missingDirectByLocale: Record<string, Record<string, string[]>>;
-  missingEffectiveByLocale: Record<string, Record<string, string[]>>;
-}
-
-export interface AuditDictionariesOptions {
-  namespaces: Record<string, DictionaryJson>;
-  config: Pick<CodegenConfig, "localeFallback">;
-  treatEmptyAsMissing?: boolean;
-}
-
-function isDirectlyMissing(
-  localesByKey: Record<string, string>,
-  locale: string,
-  treatEmptyAsMissing: boolean
-): boolean {
-  const template = localesByKey[locale];
-  if (template === undefined) {
-    return true;
-  }
-  return treatEmptyAsMissing && template === "";
-}
-
-function isEffectivelyMissing(
-  localesByKey: Record<string, string>,
-  locale: string,
-  localeFallback: Record<string, string | null> | undefined,
-  treatEmptyAsMissing: boolean
-): boolean {
-  const resolved = resolveLocaleTemplate(localesByKey, locale, localeFallback);
-  if (resolved === undefined) {
-    return true;
-  }
-  return treatEmptyAsMissing && resolved.template === "";
-}
-
-function collectDictionaryLocales(namespaces: Record<string, DictionaryJson>): Set<string> {
-  const locales = new Set<string>();
-
-  for (const dictionary of Object.values(namespaces)) {
-    for (const localesByKey of Object.values(dictionary)) {
-      for (const locale of Object.keys(localesByKey)) {
-        locales.add(locale);
-      }
-    }
-  }
-
-  return locales;
-}
-
-/**
- * Audit pipeline: reports missing translations per namespace/locale (direct and
- * effective via fallback), using the same locale policy as codegen.
- */
-export function auditDictionaries(options: AuditDictionariesOptions): I18nAuditReport {
-  const { namespaces, config, treatEmptyAsMissing = true } = options;
-  const dictionaryLocales = collectDictionaryLocales(namespaces);
-  const requiredLocales = buildRequiredLocales(dictionaryLocales, config.localeFallback);
-  const localeFallbackForAudit = config.localeFallback
-    ? enrichLocaleFallback(dictionaryLocales, config.localeFallback)
-    : undefined;
-
-  const summary: I18nAuditReport["summary"] = {};
-  const missingDirectByLocale: I18nAuditReport["missingDirectByLocale"] = {};
-  const missingEffectiveByLocale: I18nAuditReport["missingEffectiveByLocale"] = {};
-
-  for (const [namespace, dictionary] of Object.entries(namespaces)) {
-    summary[namespace] = {};
-    missingDirectByLocale[namespace] = {};
-    missingEffectiveByLocale[namespace] = {};
-
-    for (const locale of requiredLocales) {
-      summary[namespace]![locale] = { missingDirect: 0, missingEffective: 0 };
-      missingDirectByLocale[namespace]![locale] = [];
-      missingEffectiveByLocale[namespace]![locale] = [];
-    }
-
-    for (const [key, localesByKey] of Object.entries(dictionary)) {
-      for (const locale of requiredLocales) {
-        if (isDirectlyMissing(localesByKey, locale, treatEmptyAsMissing)) {
-          summary[namespace]![locale]!.missingDirect += 1;
-          missingDirectByLocale[namespace]![locale]!.push(key);
-        }
-
-        if (
-          isEffectivelyMissing(localesByKey, locale, localeFallbackForAudit, treatEmptyAsMissing)
-        ) {
-          summary[namespace]![locale]!.missingEffective += 1;
-          missingEffectiveByLocale[namespace]![locale]!.push(key);
-        }
-      }
-    }
-
-    for (const locale of requiredLocales) {
-      missingDirectByLocale[namespace]![locale]!.sort();
-      missingEffectiveByLocale[namespace]![locale]!.sort();
-    }
-  }
-
-  return {
-    requiredLocales,
-    ...(localeFallbackForAudit !== undefined ? { localeFallback: localeFallbackForAudit } : {}),
-    summary,
-    missingDirectByLocale,
-    missingEffectiveByLocale,
-  };
-}
-
-export function reportHasGaps(report: I18nAuditReport, criterion: FailOnCriterion): boolean {
-  for (const namespace of Object.keys(report.missingDirectByLocale)) {
-    for (const locale of report.requiredLocales) {
-      const direct = report.missingDirectByLocale[namespace]?.[locale] ?? [];
-      const effective = report.missingEffectiveByLocale[namespace]?.[locale] ?? [];
-
-      if (criterion === "direct" && direct.length > 0) {
-        return true;
-      }
-      if (criterion === "effective" && effective.length > 0) {
-        return true;
-      }
-      if (criterion === "any" && (direct.length > 0 || effective.length > 0)) {
-        return true;
-      }
-    }
-  }
-
-  return false;
-}
-
-export interface RunAuditOptions {
-  projectRoot: string;
-  config: CodegenConfig;
-  treatEmptyAsMissing?: boolean;
-  failOn?: FailOnCriterion;
-}
-
-export interface RunAuditResult {
-  report: I18nAuditReport;
-  exitCode: 0 | 1;
-}
-
-export async function runAuditFromConfig(options: RunAuditOptions): Promise<RunAuditResult> {
-  const { resolveNamespaces } = await import("../codegen/config.js");
-  const { readDictionaryFile } = await import("../codegen/read-dictionary.js");
-
-  const config = options.config;
-  const entries = resolveNamespaces(config);
-  const namespaces: Record<string, DictionaryJson> = {};
-
-  for (const entry of entries) {
-    const absolutePath = path.resolve(options.projectRoot, entry.filePath);
-    namespaces[entry.namespace] = readDictionaryFile(absolutePath);
-  }
-
-  const report = auditDictionaries({
-    namespaces,
-    config,
-    ...(options.treatEmptyAsMissing !== undefined
-      ? { treatEmptyAsMissing: options.treatEmptyAsMissing }
-      : {}),
-  });
-
-  const exitCode =
-    options.failOn && reportHasGaps(report, options.failOn) ? (1 as const) : (0 as const);
-
-  return { report, exitCode };
-}

package/src/audit/run-audit.test.ts

@@ -1,169 +0,0 @@
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname } from "node:path";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { parseAuditArgs, runAuditCli } from "./run-audit.js";
-
-const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
-const auditBin = join(packageRoot, "bin/audit.mjs");
-
-describe("parseAuditArgs", () => {
-  it("defaults to report-only mode without --fail-on", () => {
-    expect(parseAuditArgs([])).toEqual({
-      configPath: join(process.cwd(), "i18n/i18n.codegen.json"),
-      outPath: undefined,
-      failOn: undefined,
-      treatEmptyAsMissing: true,
-    });
-  });
-
-  it("parses fail-on and allow-empty", () => {
-    const parsed = parseAuditArgs([
-      "--config",
-      "cfg.json",
-      "--fail-on",
-      "effective",
-      "--allow-empty",
-    ]);
-    expect(parsed.failOn).toBe("effective");
-    expect(parsed.treatEmptyAsMissing).toBe(false);
-    expect(parsed.configPath).toBe(join(process.cwd(), "cfg.json"));
-  });
-});
-
-describe("runAuditCli", () => {
-  let tempDir = "";
-
-  afterEach(() => {
-    if (tempDir) {
-      rmSync(tempDir, { recursive: true, force: true });
-      tempDir = "";
-    }
-  });
-
-  function writeFixture(dictionary: Record<string, Record<string, string>>) {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-audit-"));
-    mkdirSync(join(tempDir, "i18n/translations"), { recursive: true });
-    writeFileSync(join(tempDir, "i18n/translations/default.json"), JSON.stringify(dictionary));
-    writeFileSync(
-      join(tempDir, "i18n/i18n.codegen.json"),
-      JSON.stringify({
-        projectName: "App",
-        namespaces: {
-          default: "translations/default.json",
-        },
-        codegenPath: "generated",
-        localeFallback: {
-          en: null,
-          it: "en",
-        },
-      })
-    );
-  }
-
-  it("exits 0 without --fail-on even when effective gaps exist", async () => {
-    writeFixture({
-      welcome: { en: "Welcome" },
-    });
-
-    const previousCwd = process.cwd();
-    process.chdir(tempDir);
-    try {
-      const exitCode = await runAuditCli(["--config", "i18n/i18n.codegen.json"]);
-      expect(exitCode).toBe(0);
-    } finally {
-      process.chdir(previousCwd);
-    }
-  });
-
-  it("exits 1 with --fail-on effective when effective gaps exist", async () => {
-    writeFixture({
-      login_button: { it: "Accedi" },
-    });
-
-    const previousCwd = process.cwd();
-    process.chdir(tempDir);
-    try {
-      const exitCode = await runAuditCli([
-        "--config",
-        "i18n/i18n.codegen.json",
-        "--fail-on",
-        "effective",
-      ]);
-      expect(exitCode).toBe(1);
-    } finally {
-      process.chdir(previousCwd);
-    }
-  });
-
-  it("writes JSON report to --out", async () => {
-    writeFixture({
-      login_button: { en: "Login", it: "Accedi" },
-    });
-
-    const outPath = join(tempDir, "audit.json");
-    const previousCwd = process.cwd();
-    process.chdir(tempDir);
-    try {
-      const exitCode = await runAuditCli(["--config", "i18n/i18n.codegen.json", "--out", outPath]);
-      expect(exitCode).toBe(0);
-      const report = JSON.parse(readFileSync(outPath, "utf8"));
-      expect(report.requiredLocales).toEqual(["en", "it"]);
-      expect(report.missingEffectiveByLocale.default.en).toEqual([]);
-    } finally {
-      process.chdir(previousCwd);
-    }
-  });
-
-  it("exits 2 with an error message when the config is invalid", async () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-audit-"));
-    mkdirSync(join(tempDir, "i18n"), { recursive: true });
-    writeFileSync(
-      join(tempDir, "i18n/i18n.codegen.json"),
-      JSON.stringify({ namespaces: { default: "translations/default.json" } })
-    );
-
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => void 0);
-    const previousCwd = process.cwd();
-    process.chdir(tempDir);
-    try {
-      const exitCode = await runAuditCli(["--config", "i18n/i18n.codegen.json"]);
-      expect(exitCode).toBe(2);
-      expect(String(errorSpy.mock.calls[0]?.[0])).toContain("Invalid i18n.codegen.json");
-    } finally {
-      process.chdir(previousCwd);
-      errorSpy.mockRestore();
-    }
-  });
-
-  it("exits 2 with an error message when --fail-on has an invalid value", async () => {
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => void 0);
-    try {
-      const exitCode = await runAuditCli(["--fail-on", "bogus"]);
-      expect(exitCode).toBe(2);
-      expect(String(errorSpy.mock.calls[0]?.[0])).toContain(
-        "[Audit Error] --fail-on must be one of: effective, direct, any"
-      );
-    } finally {
-      errorSpy.mockRestore();
-    }
-  });
-
-  it("runs through the bin wrapper", () => {
-    writeFixture({
-      login_button: { en: "Login" },
-    });
-
-    const result = spawnSync("node", [auditBin, "--config", "i18n/i18n.codegen.json"], {
-      cwd: tempDir,
-      encoding: "utf8",
-    });
-
-    expect(result.status).toBe(0);
-    const report = JSON.parse(result.stdout);
-    expect(report.requiredLocales).toEqual(["en", "it"]);
-  });
-});

package/src/audit/run-audit.ts

@@ -1,94 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import type { CodegenConfig } from "../codegen/codegen-config-schema.js";
-import { loadConfig } from "../codegen/config.js";
-import { type FailOnCriterion, runAuditFromConfig } from "./audit-dictionaries.js";
-
-const FAIL_ON_VALUES = new Set<FailOnCriterion>(["effective", "direct", "any"]);
-
-export interface AuditCliOptions {
-  configPath: string;
-  outPath?: string;
-  failOn?: FailOnCriterion;
-  treatEmptyAsMissing: boolean;
-}
-
-export function parseAuditArgs(argv: string[]): AuditCliOptions {
-  const configArgIndex = argv.indexOf("--config");
-  const outArgIndex = argv.indexOf("--out");
-  const failOnArgIndex = argv.indexOf("--fail-on");
-
-  const configPath = path.resolve(
-    process.cwd(),
-    configArgIndex >= 0 ? argv[configArgIndex + 1]! : "i18n/i18n.codegen.json"
-  );
-
-  const outPath =
-    outArgIndex >= 0 ? path.resolve(process.cwd(), argv[outArgIndex + 1]!) : undefined;
-
-  let failOn: FailOnCriterion | undefined;
-  if (failOnArgIndex >= 0) {
-    const value = argv[failOnArgIndex + 1];
-    if (!value || !FAIL_ON_VALUES.has(value as FailOnCriterion)) {
-      throw new Error(`[Audit Error] --fail-on must be one of: effective, direct, any`);
-    }
-    failOn = value as FailOnCriterion;
-  }
-
-  const treatEmptyAsMissing = !argv.includes("--allow-empty");
-
-  return {
-    configPath,
-    treatEmptyAsMissing,
-    ...(outPath !== undefined ? { outPath } : {}),
-    ...(failOn !== undefined ? { failOn } : {}),
-  };
-}
-
-export async function runAuditCli(argv = process.argv.slice(2)): Promise<number> {
-  let options: AuditCliOptions;
-  let config: CodegenConfig;
-
-  try {
-    options = parseAuditArgs(argv);
-
-    if (!fs.existsSync(options.configPath)) {
-      console.error(`[Audit Error] Config file not found: ${options.configPath}`);
-      return 2;
-    }
-
-    config = loadConfig(options.configPath);
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    return 2;
-  }
-
-  const projectRoot = path.dirname(options.configPath);
-
-  const { report, exitCode } = await runAuditFromConfig({
-    projectRoot,
-    config,
-    treatEmptyAsMissing: options.treatEmptyAsMissing,
-    ...(options.failOn !== undefined ? { failOn: options.failOn } : {}),
-  });
-
-  const json = `${JSON.stringify(report, null, 2)}\n`;
-
-  if (options.outPath) {
-    fs.mkdirSync(path.dirname(options.outPath), { recursive: true });
-    fs.writeFileSync(options.outPath, json);
-  } else {
-    process.stdout.write(json);
-  }
-
-  return exitCode;
-}
-
-async function main(): Promise<void> {
-  const exitCode = await runAuditCli();
-  process.exit(exitCode);
-}
-
-if (process.argv[1]?.endsWith("run-audit.ts")) {
-  void main();
-}

package/src/builder-load-registry.test.ts

@@ -1,44 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { BuilderLoadRegistry } from "./builder-load-registry.js";
-
-describe("BuilderLoadRegistry", () => {
-  it("tracks pending, loaded, and error states", () => {
-    const registry = new BuilderLoadRegistry();
-    const failure = new Error("boom");
-
-    registry.markPending("billing", "it");
-    expect(registry.getLoadState()).toEqual({
-      resources: [{ namespace: "billing", partition: "it", status: "pending" }],
-    });
-
-    registry.markLoaded("billing", "it");
-    expect(registry.has("billing", "it")).toBe(true);
-    expect(registry.getLoadState()).toEqual({
-      resources: [{ namespace: "billing", partition: "it", status: "loaded" }],
-    });
-    expect(registry.entries()).toEqual([["billing", "it"]]);
-
-    registry.markError("default", "en", failure);
-    expect(registry.getLoadState()).toEqual({
-      resources: [
-        { namespace: "billing", partition: "it", status: "loaded" },
-        { namespace: "default", partition: "en", status: "error", error: failure },
-      ],
-    });
-  });
-
-  it("seeds hydrated resources as loaded", () => {
-    const registry = new BuilderLoadRegistry();
-    registry.seed([
-      ["default", "it"],
-      ["billing", "it"],
-    ]);
-
-    expect(registry.getLoadState()).toEqual({
-      resources: [
-        { namespace: "billing", partition: "it", status: "loaded" },
-        { namespace: "default", partition: "it", status: "loaded" },
-      ],
-    });
-  });
-});

package/src/builder-load-registry.ts

@@ -1,78 +0,0 @@
-import type { I18nLoadState, I18nResourceLoadRecord } from "./load-state.js";
-
-/** Stable key for a lazy-loaded builder resource (namespace + locale or delivery area). */
-export function formatBuilderResourceKey(namespace: string, partition: string): string {
-  return `${namespace}\0${partition}`;
-}
-
-/** Serialized builder resource: namespace + partition (locale / delivery area). */
-export type BuilderResourceEntry = readonly [namespace: string, partition: string];
-
-/**
- * Dedup cache for lazy-loaded builder resources (`namespace` × partition).
- * Tracks pending / loaded / error for {@link I18nLoadState}.
- */
-export class BuilderLoadRegistry {
-  private readonly states = new Map<string, I18nResourceLoadRecord>();
-
-  has(namespace: string, partition: string): boolean {
-    return this.states.get(formatBuilderResourceKey(namespace, partition))?.status === "loaded";
-  }
-
-  markPending(namespace: string, partition: string): void {
-    this.setState(namespace, partition, { status: "pending" });
-  }
-
-  mark(namespace: string, partition: string): void {
-    this.markLoaded(namespace, partition);
-  }
-
-  markLoaded(namespace: string, partition: string): void {
-    this.setState(namespace, partition, { status: "loaded" });
-  }
-
-  markError(namespace: string, partition: string, error: unknown): void {
-    this.setState(namespace, partition, { status: "error", error });
-  }
-
-  /** Snapshot of loaded resources as `[namespace, partition]` tuples. */
-  entries(): BuilderResourceEntry[] {
-    const out: BuilderResourceEntry[] = [];
-    for (const record of this.states.values()) {
-      if (record.status === "loaded") {
-        out.push([record.namespace, record.partition]);
-      }
-    }
-    return out;
-  }
-
-  seed(resources: readonly BuilderResourceEntry[]): void {
-    for (const [namespace, partition] of resources) {
-      this.markLoaded(namespace, partition);
-    }
-  }
-
-  getLoadState(): I18nLoadState {
-    const resources = [...this.states.values()].sort((a, b) => {
-      const byNamespace = a.namespace.localeCompare(b.namespace);
-      return byNamespace !== 0 ? byNamespace : a.partition.localeCompare(b.partition);
-    });
-    return { resources };
-  }
-
-  private setState(
-    namespace: string,
-    partition: string,
-    patch: Pick<I18nResourceLoadRecord, "status"> & Partial<Pick<I18nResourceLoadRecord, "error">>
-  ): void {
-    const record: I18nResourceLoadRecord = {
-      namespace,
-      partition,
-      status: patch.status,
-    };
-    if (patch.error !== undefined) {
-      record.error = patch.error;
-    }
-    this.states.set(formatBuilderResourceKey(namespace, partition), record);
-  }
-}

package/src/builder-loaders.ts

@@ -1,15 +0,0 @@
-/** Split-by-locale or custom-area loader — partition key is locale or area name. */
-export type PartitionedLoader<T> = (
-  partition: string,
-  context: { locale: string }
-) => Promise<T> | T;
-
-export type NamespaceLoader<T> = PartitionedLoader<T>;
-
-export async function invokeNamespaceLoader<T>(
-  loader: NamespaceLoader<T>,
-  partition: string,
-  context: { locale: string }
-): Promise<T> {
-  return await loader(partition, context);
-}

package/src/builder-types.test.ts

@@ -1,57 +0,0 @@
-import { describe, expectTypeOf, it } from "vitest";
-import { createI18nHandle } from "./builder.js";
-import type { I18nHandle } from "./i18n-handle.js";
-import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-import type { LocalesForDeliveryArea, LocalesForDeliveryAreaOrAll } from "./builder-types.js";
-import type { PartialMultiDictionary } from "./types.js";
-
-type TypestateSchema = {
-  billing: { invoice_summary: { en: string; it: string } };
-};
-
-type TypestateParams = {
-  billing: { invoice_summary: { count: number } };
-};
-
-describe("builder-types", () => {
-  type ProjectLocale = "en" | "en-US" | "it" | "fr";
-  type DeliveryArea = "eu" | "amer";
-  type Artifacts = {
-    eu: readonly ["en", "it", "fr"];
-    amer: readonly ["en-US"];
-  };
-
-  it("LocalesForDeliveryArea indexes artifact locales", () => {
-    expectTypeOf<LocalesForDeliveryArea<Artifacts, "eu">>().toEqualTypeOf<"en" | "it" | "fr">();
-    expectTypeOf<LocalesForDeliveryArea<Artifacts, "amer">>().toEqualTypeOf<"en-US">();
-  });
-
-  it("LocalesForDeliveryAreaOrAll narrows only when a delivery map is configured", () => {
-    expectTypeOf<
-      LocalesForDeliveryAreaOrAll<ProjectLocale, DeliveryArea, Artifacts, "eu">
-    >().toEqualTypeOf<"en" | "it" | "fr">();
-    expectTypeOf<
-      LocalesForDeliveryAreaOrAll<ProjectLocale, never, Record<string, never>, "eu">
-    >().toEqualTypeOf<ProjectLocale>();
-  });
-});
-
-describe("I18nHandle typestate", () => {
-  it("exposes load / peek / serialize / getLoadState", () => {
-    const engine = new IcuTranslationProviderMulti<TypestateSchema, TypestateParams>({});
-    const handle = createI18nHandle(engine);
-    expectTypeOf(handle).toMatchTypeOf<I18nHandle<TypestateSchema, TypestateParams>>();
-    expectTypeOf(handle.serialize).returns.toEqualTypeOf<{
-      dictionary: PartialMultiDictionary<TypestateSchema>;
-      resources: readonly (readonly [string, string])[];
-    }>();
-    expectTypeOf(handle.getLoadState).returns.toEqualTypeOf<{
-      resources: readonly {
-        namespace: string;
-        partition: string;
-        status: "pending" | "loaded" | "error";
-        error?: unknown;
-      }[];
-    }>();
-  });
-});

package/src/builder-types.ts

@@ -1,24 +0,0 @@
-/** Locales served by a delivery area, from a codegen `DELIVERY_ARTIFACTS`-shaped map. */
-export type LocalesForDeliveryArea<
-  Artifacts extends Record<string, readonly string[]>,
-  Area extends keyof Artifacts & string,
-> = Artifacts[Area][number];
-
-/** Map from delivery area to locale lists; empty when custom delivery is not configured. */
-export type DeliveryArtifactsMap<RequestLocales extends string, DeliveryArea extends string> = [
-  DeliveryArea,
-] extends [never]
-  ? Record<string, never>
-  : Record<DeliveryArea, readonly RequestLocales[]>;
-
-/** When a delivery-area map is configured, resolve partition locales; otherwise keep the full pool. */
-export type LocalesForDeliveryAreaOrAll<
-  RequestLocales extends string,
-  DeliveryArea extends string,
-  DeliveryArtifacts extends DeliveryArtifactsMap<RequestLocales, DeliveryArea>,
-  Area extends string,
-> = [DeliveryArea] extends [never]
-  ? RequestLocales
-  : Area extends DeliveryArea
-    ? DeliveryArtifacts[Area][number]
-    : never;