@xndrjs/i18n 0.8.1 → 0.8.2-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xndrjs/i18n",
-  "version": "0.8.1",
+  "version": "0.8.2-alpha.0",
   "description": "Compiler-first, type-safe ICU MessageFormat i18n with lazy delivery loading and external payload validation for content ingest.",
   "private": false,
   "license": "MIT",
@@ -11,9 +11,9 @@
   },
   "type": "module",
   "bin": {
-    "xndrjs-i18n-codegen": "./bin/codegen.mjs",
-    "xndrjs-i18n-setup": "./bin/setup.mjs",
-    "xndrjs-i18n-audit": "./bin/audit.mjs"
+    "xndrjs-i18n-codegen": "./dist/cli/codegen.js",
+    "xndrjs-i18n-setup": "./dist/cli/setup.js",
+    "xndrjs-i18n-audit": "./dist/cli/audit.js"
   },
   "types": "./dist/index.d.ts",
   "exports": {
@@ -34,9 +34,7 @@
     }
   },
   "files": [
-    "dist",
-    "bin",
-    "src"
+    "dist"
   ],
   "engines": {
     "node": ">=18"
@@ -47,7 +45,6 @@
     "yaml": "^2.8.1"
   },
   "peerDependencies": {
-    "tsx": ">=4",
     "zod": "^4.0.0"
   },
   "devDependencies": {
@@ -61,7 +58,7 @@
     "pack": "pnpm run build && mkdir -p artifacts && npm pack --pack-destination artifacts",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "test": "vitest run",
+    "test": "pnpm run build && vitest run",
     "typecheck": "tsc --noEmit"
   }
 }

package/bin/audit.mjs

@@ -1,14 +0,0 @@
-#!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-const script = join(dirname(fileURLToPath(import.meta.url)), "../src/audit/run-audit.ts");
-
-const result = spawnSync("tsx", [script, ...process.argv.slice(2)], {
-  stdio: "inherit",
-  cwd: process.cwd(),
-  env: process.env,
-});
-
-process.exit(result.status ?? 1);

package/bin/codegen.mjs

@@ -1,17 +0,0 @@
-#!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-const script = join(
-  dirname(fileURLToPath(import.meta.url)),
-  "../src/codegen/generate-i18n-types.ts"
-);
-
-const result = spawnSync("tsx", [script, ...process.argv.slice(2)], {
-  stdio: "inherit",
-  cwd: process.cwd(),
-  env: process.env,
-});
-
-process.exit(result.status ?? 1);

package/bin/setup.mjs

@@ -1,14 +0,0 @@
-#!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-const script = join(dirname(fileURLToPath(import.meta.url)), "../src/setup/setup-i18n.ts");
-
-const result = spawnSync("tsx", [script, ...process.argv.slice(2)], {
-  stdio: "inherit",
-  cwd: process.cwd(),
-  env: process.env,
-});
-
-process.exit(result.status ?? 1);

package/src/IcuTranslationProviderMulti.test.ts

@@ -1,215 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-
-type TestSchema = {
-  default: {
-    login_button: { en: string; it: string };
-    welcome: { en: string };
-    dashboard_status: { en: string; it: string };
-    inbox_owner: { en: string; it: string };
-    ranking_position: { en: string; it: string };
-  };
-  billing: {
-    invoice_summary: { en: string; it: string };
-    account_balance: { en: string; it: string };
-    appointment_summary: { en: string; it: string };
-    empty_label: { en: string };
-  };
-};
-
-type TestParams = {
-  default: {
-    login_button: never;
-    welcome: { name: string };
-    dashboard_status: { msgCount: number; chatCount: number };
-    inbox_owner: { gender: string; name: string };
-    ranking_position: { position: number };
-  };
-  billing: {
-    invoice_summary: { count: number; name: string };
-    account_balance: { amount: number };
-    appointment_summary: { dueDate: Date | number; startTime: Date | number };
-    empty_label: never;
-  };
-};
-
-const dictionary: TestSchema = {
-  default: {
-    login_button: { en: "Login", it: "Accedi" },
-    welcome: { en: "Welcome {name}!" },
-    dashboard_status: {
-      en: "You have {msgCount, plural, one {1 message} other {{msgCount} messages}} in {chatCount, plural, one {one chat} other {{chatCount} chats}}",
-      it: "Hai {msgCount, plural, one {1 messaggio} other {{msgCount} messaggi}} in {chatCount, plural, one {una chat} other {{chatCount} chat}}",
-    },
-    inbox_owner: {
-      en: "{gender, select, female {{name} owns her inbox} male {{name} owns his inbox} other {{name} owns their inbox}}",
-      it: "{gender, select, female {{name} gestisce la sua casella} male {{name} gestisce la sua casella} other {{name} gestisce la propria casella}}",
-    },
-    ranking_position: {
-      en: "You finished {position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}",
-      it: "Hai concluso al {position, selectordinal, one {#°} other {#°}} posto",
-    },
-  },
-  billing: {
-    invoice_summary: {
-      en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
-      it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
-    },
-    account_balance: {
-      en: "Balance: {amount, number, ::currency/EUR}",
-      it: "Saldo: {amount, number, ::currency/EUR}",
-    },
-    appointment_summary: {
-      en: "Due {dueDate, date, short} at {startTime, time, short}",
-      it: "Scade il {dueDate, date, short} alle {startTime, time, short}",
-    },
-    empty_label: { en: "" },
-  },
-};
-
-describe("IcuTranslationProviderMulti", () => {
-  const engine = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
-
-  it("tracks namespaces via dictionary keys", () => {
-    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
-      default: dictionary.default,
-    });
-
-    expect("default" in partial.getAll()).toBe(true);
-    expect("billing" in partial.getAll()).toBe(false);
-  });
-
-  it("supports partial initialization", () => {
-    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
-      default: dictionary.default,
-    });
-
-    expect(partial.toScope({ namespaces: ["default"] }).t("default", "login_button", "en")).toBe(
-      "Login"
-    );
-  });
-
-  it("adds namespace to dictionary with applyLoadMergeNamespace", () => {
-    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
-      default: dictionary.default,
-    });
-    expect("billing" in partial.getAll()).toBe(false);
-
-    partial.applyLoadMergeNamespace("billing", dictionary.billing);
-    expect("billing" in partial.getAll()).toBe(true);
-  });
-
-  it("adds namespace to dictionary on first applyLoadMergeNamespace", () => {
-    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({});
-    expect("billing" in partial.getAll()).toBe(false);
-
-    partial.applyLoadMergeNamespace("billing", dictionary.billing);
-    expect("billing" in partial.getAll()).toBe(true);
-  });
-
-  it("accumulates a locale via applyLoadMergeNamespace when the namespace already exists", () => {
-    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>({
-      billing: {
-        invoice_summary: {
-          en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
-        },
-      },
-    });
-    const view = () => local.toScope({ namespaces: ["billing"] });
-
-    expect("billing" in local.getAll()).toBe(true);
-    expect(view().t("billing", "invoice_summary", "en", { count: 1, name: "Ada" })).toBe(
-      "You have 1 invoice for Ada"
-    );
-
-    local.applyLoadMergeNamespace("billing", {
-      invoice_summary: {
-        it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
-      },
-    });
-
-    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
-      "You have 2 invoices for Bob"
-    );
-    expect(view().t("billing", "invoice_summary", "it", { count: 2, name: "Bob" })).toBe(
-      "Hai 2 fatture per Bob"
-    );
-  });
-
-  it("merges locales per key with applyLoadMergeNamespace without dropping existing locales", () => {
-    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>({
-      billing: {
-        invoice_summary: {
-          en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
-        },
-      },
-    });
-    const view = () => local.toScope({ namespaces: ["billing"] });
-
-    local.applyLoadMergeNamespace("billing", {
-      invoice_summary: {
-        it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
-      },
-    });
-
-    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
-      "You have 2 invoices for Bob"
-    );
-    expect(view().t("billing", "invoice_summary", "it", { count: 2, name: "Bob" })).toBe(
-      "Hai 2 fatture per Bob"
-    );
-  });
-
-  it("merges namespaces with applyLoadMergeAll without dropping existing locales", () => {
-    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>({
-      billing: {
-        invoice_summary: {
-          en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
-        },
-      },
-    });
-    const view = () => local.toScope({ namespaces: ["default", "billing"] });
-
-    local.applyLoadMergeAll({
-      billing: {
-        invoice_summary: {
-          it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
-        },
-      },
-      default: dictionary.default,
-    });
-
-    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
-      "You have 2 invoices for Bob"
-    );
-    expect(view().t("billing", "invoice_summary", "it", { count: 2, name: "Bob" })).toBe(
-      "Hai 2 fatture per Bob"
-    );
-    expect(view().t("default", "login_button", "en")).toBe("Login");
-  });
-
-  it("returns the live dictionary from getAll (constructor clones the input)", () => {
-    expect(engine.getAll()).toEqual(dictionary);
-    expect(engine.getAll()).not.toBe(dictionary);
-    expect(engine.getAll()).toBe(engine.getAll());
-  });
-
-  it("invalidates compiled cache when applyLoadMergeNamespace overwrites a key", () => {
-    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
-    const view = () => local.toScope({ namespaces: ["billing"] });
-
-    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
-      "You have 2 invoices for Bob"
-    );
-
-    local.applyLoadMergeNamespace("billing", {
-      invoice_summary: {
-        en: "{count, plural, one {1 bill} other {{count} bills}} for {name}",
-      },
-    });
-
-    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
-      "2 bills for Bob"
-    );
-  });
-});

package/src/IcuTranslationProviderMulti.ts

@@ -1,188 +0,0 @@
-import { BuilderLoadRegistry, type BuilderResourceEntry } from "./builder-load-registry.js";
-import type { I18nEngineMulti } from "./engine.js";
-import type { I18nSerializedState } from "./serialized-state.js";
-import { resolveAndFormat } from "./format-core.js";
-import { mergeNamespaceLocalesCore } from "./project-locales.js";
-import { validateLocaleFallback } from "./resolve-locale.js";
-import type {
-  IcuTranslationProviderOptions,
-  LocaleFallbackMap,
-  LocaleOfMulti,
-  MultiCompiledCache,
-  MultiDictionary,
-  OnMissingTranslation,
-  PartialKeyDictionary,
-  PartialMultiDictionary,
-} from "./types.js";
-import { I18nScopeMultiForLocaleImpl, I18nScopeMultiImpl } from "./scope-multi.js";
-import type { I18nScopeMulti, I18nScopeMultiForLocale } from "./scope-multi.js";
-import type { MultiParams, ParamsForNamespaces, SchemaForNamespaces } from "./scope-types.js";
-
-export class IcuTranslationProviderMulti<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string = LocaleOfMulti<Schema>,
-  Fallback extends LocaleFallbackMap | undefined = undefined,
-> implements I18nEngineMulti<Schema, Params, RequestLocales> {
-  readonly __i18nEngineMode = "multi" as const;
-
-  /** Loaded namespaces only — cold start is `{}`; never claim full Schema until loaded. */
-  private dictionary: PartialMultiDictionary<Schema, RequestLocales>;
-  private compiledCache: MultiCompiledCache = {};
-  private readonly builderLoadRegistry = new BuilderLoadRegistry();
-  private readonly localeFallback?: Fallback;
-  private readonly onMissing: OnMissingTranslation;
-
-  constructor(
-    dictionary: PartialMultiDictionary<Schema, RequestLocales> = {},
-    options?: IcuTranslationProviderOptions<Fallback>
-  ) {
-    this.dictionary = structuredClone(dictionary);
-    if (options?.localeFallback) {
-      validateLocaleFallback(options.localeFallback);
-      this.localeFallback = options.localeFallback;
-    }
-    this.onMissing = options?.onMissing ?? "throw";
-  }
-
-  getWithLocale(
-    namespace: string,
-    key: string,
-    locale: string,
-    params?: Record<string, unknown>
-  ): string {
-    const localeByKey = (
-      this.dictionary[namespace as keyof Schema] as
-        | Record<string, Record<string, string>>
-        | undefined
-    )?.[key];
-
-    return resolveAndFormat({
-      localeByKey,
-      locale,
-      params,
-      getCache: (resolvedLocale) => {
-        if (!this.compiledCache[resolvedLocale]) {
-          this.compiledCache[resolvedLocale] = {};
-        }
-        if (!this.compiledCache[resolvedLocale]![namespace]) {
-          this.compiledCache[resolvedLocale]![namespace] = {};
-        }
-        return this.compiledCache[resolvedLocale]![namespace]!;
-      },
-      context: {
-        namespace,
-        key,
-        locale,
-        localeFallback: this.localeFallback,
-        onMissing: this.onMissing,
-      },
-    });
-  }
-
-  toScope<
-    NsList extends readonly (keyof Schema & string)[],
-    Locale extends RequestLocales,
-  >(options: {
-    namespaces: NsList;
-    locale: Locale;
-  }): I18nScopeMultiForLocale<
-    SchemaForNamespaces<Schema, NsList>,
-    ParamsForNamespaces<Schema, Params, NsList>,
-    RequestLocales,
-    Locale
-  >;
-  toScope<NsList extends readonly (keyof Schema & string)[]>(options: {
-    namespaces: NsList;
-  }): I18nScopeMulti<
-    SchemaForNamespaces<Schema, NsList>,
-    ParamsForNamespaces<Schema, Params, NsList>,
-    RequestLocales
-  >;
-  toScope<
-    NsList extends readonly (keyof Schema & string)[],
-    Locale extends RequestLocales,
-  >(options: { namespaces: NsList; locale?: Locale }) {
-    if (options.locale !== undefined) {
-      return new I18nScopeMultiForLocaleImpl(this, options.locale) as I18nScopeMultiForLocale<
-        SchemaForNamespaces<Schema, NsList>,
-        ParamsForNamespaces<Schema, Params, NsList>,
-        RequestLocales,
-        Locale
-      >;
-    }
-    return new I18nScopeMultiImpl(this) as I18nScopeMulti<
-      SchemaForNamespaces<Schema, NsList>,
-      ParamsForNamespaces<Schema, Params, NsList>,
-      RequestLocales
-    >;
-  }
-
-  /** Live dictionary reference (loaded namespaces only). Do not mutate. */
-  getAll(): PartialMultiDictionary<Schema, RequestLocales> {
-    return this.dictionary;
-  }
-
-  hasBuilderResourceLoaded(namespace: string, partition: string): boolean {
-    return this.builderLoadRegistry.has(namespace, partition);
-  }
-
-  markBuilderResourcePending(namespace: string, partition: string): void {
-    this.builderLoadRegistry.markPending(namespace, partition);
-  }
-
-  markBuilderResourceLoaded(namespace: string, partition: string): void {
-    this.builderLoadRegistry.mark(namespace, partition);
-  }
-
-  markBuilderResourceError(namespace: string, partition: string, error: unknown): void {
-    this.builderLoadRegistry.markError(namespace, partition, error);
-  }
-
-  getBuilderLoadState() {
-    return this.builderLoadRegistry.getLoadState();
-  }
-
-  seedBuilderResources(resources: readonly BuilderResourceEntry[]): void {
-    this.builderLoadRegistry.seed(resources);
-  }
-
-  serialize(): I18nSerializedState<PartialMultiDictionary<Schema, RequestLocales>> {
-    return {
-      dictionary: this.dictionary,
-      resources: this.builderLoadRegistry.entries(),
-    };
-  }
-
-  applyLoadMergeNamespace<NS extends keyof Schema>(
-    namespace: NS,
-    values: PartialKeyDictionary<Schema[NS], RequestLocales>
-  ): void {
-    const existing = (this.dictionary[namespace] ?? {}) as Schema[NS];
-    const merged = mergeNamespaceLocalesCore(existing, values);
-
-    this.dictionary = {
-      ...this.dictionary,
-      [namespace]: merged,
-    };
-
-    for (const [key, incomingLocales] of Object.entries(values)) {
-      if (incomingLocales === undefined || typeof incomingLocales !== "object") {
-        continue;
-      }
-
-      for (const locale of Object.keys(incomingLocales)) {
-        delete this.compiledCache[locale]?.[namespace as string]?.[key];
-      }
-    }
-  }
-
-  applyLoadMergeAll(values: PartialMultiDictionary<Schema, RequestLocales>): void {
-    for (const namespace of Object.keys(values) as (keyof Schema & string)[]) {
-      const incoming = values[namespace];
-      if (incoming !== undefined) {
-        this.applyLoadMergeNamespace(namespace, incoming);
-      }
-    }
-  }
-}

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

@@ -1,134 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { auditDictionaries, reportHasGaps } from "./audit-dictionaries.js";
-
-describe("auditDictionaries", () => {
-  it("reports missingDirect for fallback-only locales while missingEffective stays empty when en covers", () => {
-    const report = auditDictionaries({
-      namespaces: {
-        default: {
-          login_button: { en: "Login", it: "Accedi" },
-        },
-      },
-      config: {
-        localeFallback: {
-          en: null,
-          "de-DE": "en",
-          "de-CH": "de-DE",
-          it: "en",
-        },
-      },
-    });
-
-    expect(report.requiredLocales).toEqual(["de-CH", "de-DE", "en", "it"]);
-    expect(report.missingDirectByLocale.default?.["de-CH"]).toEqual(["login_button"]);
-    expect(report.missingEffectiveByLocale.default?.["de-CH"]).toEqual([]);
-    expect(report.missingDirectByLocale.default?.en).toEqual([]);
-  });
-
-  it("treats empty strings as missing by default", () => {
-    const report = auditDictionaries({
-      namespaces: {
-        default: {
-          empty_label: { en: "" },
-        },
-      },
-      config: {},
-    });
-
-    expect(report.missingDirectByLocale.default?.en).toEqual(["empty_label"]);
-    expect(report.missingEffectiveByLocale.default?.en).toEqual(["empty_label"]);
-  });
-
-  it("allows empty strings when treatEmptyAsMissing is false", () => {
-    const report = auditDictionaries({
-      namespaces: {
-        default: {
-          empty_label: { en: "" },
-        },
-      },
-      config: {},
-      treatEmptyAsMissing: false,
-    });
-
-    expect(report.missingDirectByLocale.default?.en).toEqual([]);
-    expect(report.missingEffectiveByLocale.default?.en).toEqual([]);
-  });
-
-  it("uses enriched locale fallback for effective gaps", () => {
-    const report = auditDictionaries({
-      namespaces: {
-        default: {
-          welcome: { en: "Welcome {name}!" },
-        },
-      },
-      config: {
-        localeFallback: {
-          en: null,
-          it: "en",
-        },
-      },
-    });
-
-    expect(report.localeFallback).toEqual({
-      en: null,
-      it: "en",
-    });
-    expect(report.missingEffectiveByLocale.default?.it).toEqual([]);
-  });
-
-  it("matches direct and effective when localeFallback is absent", () => {
-    const report = auditDictionaries({
-      namespaces: {
-        default: {
-          login_button: { en: "Login" },
-        },
-      },
-      config: {},
-    });
-
-    expect(report.localeFallback).toBeUndefined();
-    expect(report.requiredLocales).toEqual(["en"]);
-    expect(report.missingDirectByLocale.default?.en).toEqual([]);
-    expect(report.missingEffectiveByLocale.default?.en).toEqual([]);
-  });
-
-  it("reports effective gaps when fallback chain cannot resolve", () => {
-    const report = auditDictionaries({
-      namespaces: {
-        default: {
-          login_button: { it: "Accedi" },
-        },
-      },
-      config: {
-        localeFallback: {
-          en: null,
-          it: "en",
-        },
-      },
-    });
-
-    expect(report.missingEffectiveByLocale.default?.en).toEqual(["login_button"]);
-  });
-});
-
-describe("reportHasGaps", () => {
-  const report = auditDictionaries({
-    namespaces: {
-      default: {
-        login_button: { en: "Login", it: "Accedi" },
-      },
-    },
-    config: {
-      localeFallback: {
-        en: null,
-        "de-CH": "en",
-      },
-    },
-  });
-
-  it("detects direct gaps", () => {
-    expect(reportHasGaps(report, "direct")).toBe(true);
-    expect(reportHasGaps(report, "effective")).toBe(false);
-    expect(reportHasGaps(report, "any")).toBe(true);
-  });
-});