@xndrjs/i18n 0.7.0 → 0.8.0

package/src/codegen/regenerate-namespaces.ts

@@ -0,0 +1,180 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { CodegenConfig } from "./codegen-config-schema.js";
+import {
+  loadConfig,
+  resolveArtifactsPath,
+  resolveCodegenPaths,
+  resolveNamespaces,
+} from "./config.js";
+import { getDeliveryArtifactsIssues } from "./delivery-artifacts.js";
+import {
+  buildDictionarySpecFromAnalysis,
+  loadDictionarySpecFromSchemaFile,
+  namespaceContractsMatch,
+} from "./dictionary-spec-contract.js";
+import { analyzeDictionaries } from "./icu-analysis.js";
+import { collectRequestLocales, getCodegenLocaleFallbackIssues } from "./locale-fallback.js";
+import { reportCodegenIssues } from "./paths.js";
+import { prepareDictionaryEntries } from "./read-dictionary.js";
+import type { DictionaryJson } from "./types.js";
+
+export interface RegenerateNamespacesInput {
+  /** Namespaces whose delivery JSON should be refreshed from authoring sources. */
+  namespaces: readonly string[];
+  configPath?: string;
+  config?: CodegenConfig;
+  projectRoot?: string;
+  /** When false, skip console.log summaries (default true). */
+  log?: boolean;
+}
+
+export interface RegenerateNamespacesResult {
+  projectRoot: string;
+  compiledFiles: string[];
+  splitPathsByNamespace: Record<string, Record<string, string>>;
+}
+
+function resolveRegenerateInput(input: RegenerateNamespacesInput): {
+  projectRoot: string;
+  config: CodegenConfig;
+  namespaces: readonly string[];
+  log: boolean;
+} {
+  const log = input.log !== false;
+  const namespaces = input.namespaces;
+
+  if (input.config !== undefined) {
+    return {
+      projectRoot: path.resolve(input.projectRoot ?? process.cwd()),
+      config: input.config,
+      namespaces,
+      log,
+    };
+  }
+
+  const configPath = path.resolve(process.cwd(), input.configPath ?? "i18n/i18n.codegen.json");
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`[Codegen Error] Config file not found: ${configPath}`);
+  }
+  return {
+    projectRoot: path.dirname(configPath),
+    config: loadConfig(configPath),
+    namespaces,
+    log,
+  };
+}
+
+/**
+ * Content-only refresh: re-materialize delivery JSON for selected namespaces from
+ * current authoring files, without rewriting generated TypeScript.
+ *
+ * Must not change the ICU key/param contract established by a prior {@link runCodegen}.
+ * If authoring changed keys or ICU args, this throws — run {@link runCodegen} and ship a release.
+ *
+ * Authoring updates are out of scope for this library (CMS or editors write those files).
+ * End-to-end without app rebuild requires `loaderStrategy: "fetch"`.
+ */
+export function regenerateNamespaces(input: RegenerateNamespacesInput): RegenerateNamespacesResult {
+  const { projectRoot, config, namespaces, log } = resolveRegenerateInput(input);
+
+  if (namespaces.length === 0) {
+    throw new Error("[Codegen Error] regenerateNamespaces requires a non-empty namespaces list.");
+  }
+
+  const sourceEntries = resolveNamespaces(config);
+  const known = new Set(sourceEntries.map((entry) => entry.namespace));
+  const unknown = namespaces.filter((namespace) => !known.has(namespace));
+  if (unknown.length > 0) {
+    throw new Error(
+      `[Codegen Error] Unknown namespace(s) for regenerateNamespaces: ${unknown.join(", ")}.`
+    );
+  }
+
+  const requested = new Set(namespaces);
+  const selectedEntries = sourceEntries.filter((entry) => requested.has(entry.namespace));
+
+  const paths = resolveCodegenPaths(config);
+  const schemaPath = path.resolve(projectRoot, paths.dictionarySchemaOutput);
+  const established = loadDictionarySpecFromSchemaFile(schemaPath);
+
+  const artifactsPathRelative = resolveArtifactsPath(config);
+  const delivery = config.delivery ?? "split-by-locale";
+
+  // Analyze all namespaces so locale unions / deliveryArtifacts stay consistent with full codegen.
+  const analysisResult = analyzeDictionaries(projectRoot, sourceEntries);
+  if (!analysisResult.ok) {
+    throw new Error(
+      "[Codegen Error] Dictionary ICU analysis failed while regenerating namespaces."
+    );
+  }
+
+  const {
+    argsSpecByNamespace,
+    locales,
+    dictionariesByNamespace: sourceDictionaries,
+  } = analysisResult.analysis;
+
+  const current = buildDictionarySpecFromAnalysis(selectedEntries, argsSpecByNamespace);
+  if (!namespaceContractsMatch(namespaces, current, established)) {
+    throw new Error(
+      "[Codegen Error] Namespace ICU contract changed (keys or params). Contract change requires runCodegen."
+    );
+  }
+
+  if (config.localeFallback) {
+    const localeFallbackIssues = getCodegenLocaleFallbackIssues(config.localeFallback, locales);
+    if (localeFallbackIssues.length > 0) {
+      reportCodegenIssues(localeFallbackIssues);
+      throw new Error("[Codegen Error] Invalid localeFallback configuration.");
+    }
+  }
+
+  const requestLocales = collectRequestLocales(locales, config.localeFallback);
+  const requestLocalesList = [...requestLocales].sort();
+
+  if (delivery === "custom" && config.deliveryArtifacts) {
+    const deliveryArtifactsIssues = getDeliveryArtifactsIssues(
+      config.deliveryArtifacts,
+      requestLocales
+    );
+    if (deliveryArtifactsIssues.length > 0) {
+      reportCodegenIssues(deliveryArtifactsIssues);
+      throw new Error("[Codegen Error] Invalid deliveryArtifacts configuration.");
+    }
+  }
+
+  const dictionariesByNamespace: Record<string, DictionaryJson> = {};
+  for (const entry of selectedEntries) {
+    const dictionary = sourceDictionaries[entry.namespace];
+    if (!dictionary) {
+      throw new Error(
+        `[Codegen Error] Missing parsed dictionary for namespace "${entry.namespace}".`
+      );
+    }
+    dictionariesByNamespace[entry.namespace] = dictionary;
+  }
+
+  const { splitPathsByNamespace, compiledFiles } = prepareDictionaryEntries(
+    projectRoot,
+    selectedEntries,
+    artifactsPathRelative,
+    {
+      dictionariesByNamespace,
+      delivery,
+      localeFallback: config.localeFallback,
+      requestLocales: delivery === "split-by-locale" ? requestLocalesList : undefined,
+      deliveryArtifacts: delivery === "custom" ? config.deliveryArtifacts : undefined,
+    }
+  );
+
+  if (log) {
+    if (compiledFiles.length > 0) {
+      console.log(`✅ Regenerated delivery artifacts: ${compiledFiles.join(", ")}`);
+    } else {
+      console.log("✅ Regenerated delivery artifacts: unchanged");
+    }
+  }
+
+  return { projectRoot, compiledFiles, splitPathsByNamespace };
+}

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

@@ -0,0 +1,230 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { regenerateNamespaces } from "./regenerate-namespaces.js";
+import { runCodegen } from "./run-codegen.js";
+
+function setupProject() {
+  const projectRoot = mkdtempSync(join(tmpdir(), "xndrjs-i18n-a5-"));
+  mkdirSync(join(projectRoot, "translations"), { recursive: true });
+  mkdirSync(join(projectRoot, "generated"), { recursive: true });
+
+  writeFileSync(
+    join(projectRoot, "translations/default.json"),
+    JSON.stringify(
+      {
+        welcome: { en: "Hello {name}!", it: "Ciao {name}!" },
+        login: { en: "Login", it: "Accedi" },
+      },
+      null,
+      2
+    )
+  );
+
+  writeFileSync(
+    join(projectRoot, "translations/billing.json"),
+    JSON.stringify(
+      {
+        invoice_summary: {
+          en: "You have {count} invoices",
+          it: "Hai {count} fatture",
+        },
+      },
+      null,
+      2
+    )
+  );
+
+  writeFileSync(
+    join(projectRoot, "i18n.codegen.json"),
+    JSON.stringify(
+      {
+        projectName: "App",
+        namespaces: {
+          default: "translations/default.json",
+          billing: "translations/billing.json",
+        },
+        codegenPath: "generated",
+        delivery: "split-by-locale",
+        artifactsPath: "generated",
+      },
+      null,
+      2
+    )
+  );
+
+  return projectRoot;
+}
+
+describe("runCodegen + regenerateNamespaces", () => {
+  let projectRoot: string;
+
+  afterEach(() => {
+    if (projectRoot) {
+      rmSync(projectRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("runCodegen emits types, loaders, and delivery JSON", () => {
+    projectRoot = setupProject();
+    const result = runCodegen({
+      configPath: join(projectRoot, "i18n.codegen.json"),
+      log: false,
+    });
+
+    expect(result.generatedFiles).toEqual(
+      expect.arrayContaining([
+        "generated/i18n-types.generated.ts",
+        "generated/instance.generated.ts",
+        "generated/namespace-loaders.generated.ts",
+        "generated/dictionary-schema.generated.ts",
+      ])
+    );
+    expect(
+      readFileSync(join(projectRoot, "generated/translations/default.en.json"), "utf8")
+    ).toContain("Hello {name}!");
+    expect(
+      readFileSync(join(projectRoot, "generated/namespace-loaders.generated.ts"), "utf8")
+    ).toContain("import('./translations/default.en.json')");
+  });
+
+  it("runCodegen emits fetch loaders when configured", () => {
+    projectRoot = setupProject();
+    writeFileSync(
+      join(projectRoot, "i18n.codegen.json"),
+      JSON.stringify(
+        {
+          projectName: "App",
+          namespaces: {
+            default: "translations/default.json",
+            billing: "translations/billing.json",
+          },
+          codegenPath: "generated",
+          delivery: "split-by-locale",
+          artifactsPath: "generated",
+          loaderStrategy: "fetch",
+        },
+        null,
+        2
+      )
+    );
+
+    runCodegen({ configPath: join(projectRoot, "i18n.codegen.json"), log: false });
+    const loaders = readFileSync(
+      join(projectRoot, "generated/namespace-loaders.generated.ts"),
+      "utf8"
+    );
+    expect(loaders).toContain('fetchImpl({ locale, namespace: "default" })');
+    expect(loaders).toContain("createNamespaceLoaders");
+  });
+
+  it("regenerateNamespaces refreshes selected delivery JSON without rewriting types", () => {
+    projectRoot = setupProject();
+    runCodegen({ configPath: join(projectRoot, "i18n.codegen.json"), log: false });
+
+    const typesBefore = readFileSync(
+      join(projectRoot, "generated/i18n-types.generated.ts"),
+      "utf8"
+    );
+    const instanceBefore = readFileSync(
+      join(projectRoot, "generated/instance.generated.ts"),
+      "utf8"
+    );
+    const billingBefore = readFileSync(
+      join(projectRoot, "generated/translations/billing.en.json"),
+      "utf8"
+    );
+
+    writeFileSync(
+      join(projectRoot, "translations/default.json"),
+      JSON.stringify(
+        {
+          welcome: { en: "Hi {name}!", it: "Ciao {name}!" },
+          login: { en: "Login", it: "Accedi" },
+        },
+        null,
+        2
+      )
+    );
+
+    regenerateNamespaces({
+      configPath: join(projectRoot, "i18n.codegen.json"),
+      namespaces: ["default"],
+      log: false,
+    });
+
+    const en = JSON.parse(
+      readFileSync(join(projectRoot, "generated/translations/default.en.json"), "utf8")
+    );
+    expect(en.welcome.en).toBe("Hi {name}!");
+    expect(en.login.en).toBe("Login");
+    expect(readFileSync(join(projectRoot, "generated/translations/billing.en.json"), "utf8")).toBe(
+      billingBefore
+    );
+    expect(readFileSync(join(projectRoot, "generated/i18n-types.generated.ts"), "utf8")).toBe(
+      typesBefore
+    );
+    expect(readFileSync(join(projectRoot, "generated/instance.generated.ts"), "utf8")).toBe(
+      instanceBefore
+    );
+  });
+
+  it("regenerateNamespaces rejects authoring that changes ICU args", () => {
+    projectRoot = setupProject();
+    runCodegen({ configPath: join(projectRoot, "i18n.codegen.json"), log: false });
+
+    writeFileSync(
+      join(projectRoot, "translations/default.json"),
+      JSON.stringify(
+        {
+          welcome: { en: "Hello {name} {extra}!", it: "Ciao {name} {extra}!" },
+          login: { en: "Login", it: "Accedi" },
+        },
+        null,
+        2
+      )
+    );
+
+    expect(() =>
+      regenerateNamespaces({
+        configPath: join(projectRoot, "i18n.codegen.json"),
+        namespaces: ["default"],
+        log: false,
+      })
+    ).toThrow(/Contract change requires runCodegen/);
+  });
+
+  it("regenerateNamespaces rejects empty or unknown namespaces", () => {
+    projectRoot = setupProject();
+    runCodegen({ configPath: join(projectRoot, "i18n.codegen.json"), log: false });
+
+    expect(() =>
+      regenerateNamespaces({
+        configPath: join(projectRoot, "i18n.codegen.json"),
+        namespaces: [],
+        log: false,
+      })
+    ).toThrow(/non-empty namespaces/);
+
+    expect(() =>
+      regenerateNamespaces({
+        configPath: join(projectRoot, "i18n.codegen.json"),
+        namespaces: ["missing"],
+        log: false,
+      })
+    ).toThrow(/Unknown namespace/);
+  });
+
+  it("regenerateNamespaces requires a prior runCodegen schema", () => {
+    projectRoot = setupProject();
+
+    expect(() =>
+      regenerateNamespaces({
+        configPath: join(projectRoot, "i18n.codegen.json"),
+        namespaces: ["default"],
+        log: false,
+      })
+    ).toThrow(/Run runCodegen first/);
+  });
+});

package/src/codegen/run-codegen.ts

@@ -0,0 +1,252 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  loadConfig,
+  resolveArtifactsPath,
+  resolveCodegenPaths,
+  resolveNamespaces,
+} from "./config.js";
+import type { CodegenConfig } from "./codegen-config-schema.js";
+import {
+  formatDictionarySchemaFile,
+  formatDictionarySpecBlock,
+} from "./emit/dictionary-schema-file.js";
+import { formatInstanceFile } from "./emit/instance-file.js";
+import { formatNamespaceLoadersFile } from "./emit/namespace-loaders-file.js";
+import { formatTypesFile } from "./emit/types-file.js";
+import { analyzeDictionaries } from "./icu-analysis.js";
+import { getDeliveryArtifactsIssues } from "./delivery-artifacts.js";
+import { collectRequestLocales, getCodegenLocaleFallbackIssues } from "./locale-fallback.js";
+import { enrichLocaleFallback } from "./locale-policy.js";
+import { DEFAULT_IMPORT_EXTENSION, reportCodegenIssues, toModuleBasename } from "./paths.js";
+import { prepareDictionaryEntries } from "./read-dictionary.js";
+import { writeFileIfChanged } from "./write-file-if-changed.js";
+
+export type RunCodegenInput =
+  | string
+  | {
+      configPath?: string;
+      config?: CodegenConfig;
+      projectRoot?: string;
+      /** When false, skip console.log summaries (default true). */
+      log?: boolean;
+    };
+
+export interface RunCodegenResult {
+  projectRoot: string;
+  generatedFiles: string[];
+  compiledFiles: string[];
+}
+
+function resolveRunCodegenInput(input?: RunCodegenInput): {
+  projectRoot: string;
+  config: CodegenConfig;
+  log: boolean;
+} {
+  if (typeof input === "string" || input === undefined) {
+    const configPath = path.resolve(
+      process.cwd(),
+      typeof input === "string" ? input : "i18n/i18n.codegen.json"
+    );
+    if (!fs.existsSync(configPath)) {
+      throw new Error(`[Codegen Error] Config file not found: ${configPath}`);
+    }
+    return {
+      projectRoot: path.dirname(configPath),
+      config: loadConfig(configPath),
+      log: true,
+    };
+  }
+
+  const log = input.log !== false;
+
+  if (input.config !== undefined) {
+    const projectRoot = path.resolve(input.projectRoot ?? process.cwd());
+    return { projectRoot, config: input.config, log };
+  }
+
+  const configPath = path.resolve(process.cwd(), input.configPath ?? "i18n/i18n.codegen.json");
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`[Codegen Error] Config file not found: ${configPath}`);
+  }
+  return {
+    projectRoot: path.dirname(configPath),
+    config: loadConfig(configPath),
+    log,
+  };
+}
+
+/**
+ * Full codegen pipeline: types + instance + loaders + delivery JSON (+ schema).
+ * Run at build time or when the *contract* changes (keys, params, namespaces, locales).
+ * Content-only refreshes (same ICU contract) should use {@link regenerateNamespaces} instead.
+ */
+export function runCodegen(input?: RunCodegenInput): RunCodegenResult {
+  const { projectRoot, config, log } = resolveRunCodegenInput(input);
+  const sourceEntries = resolveNamespaces(config);
+  const artifactsPathRelative = resolveArtifactsPath(config);
+  const delivery = config.delivery ?? "split-by-locale";
+  const loaderStrategy = config.loaderStrategy ?? "import";
+
+  const analysisResult = analyzeDictionaries(projectRoot, sourceEntries);
+  if (!analysisResult.ok) {
+    throw new Error("[Codegen Error] Dictionary ICU analysis failed. See messages above.");
+  }
+
+  const { paramsByNamespace, argsSpecByNamespace, locales, dictionariesByNamespace } =
+    analysisResult.analysis;
+
+  if (config.localeFallback) {
+    const localeFallbackIssues = getCodegenLocaleFallbackIssues(config.localeFallback, locales);
+    if (localeFallbackIssues.length > 0) {
+      reportCodegenIssues(localeFallbackIssues);
+      throw new Error("[Codegen Error] Invalid localeFallback configuration.");
+    }
+  }
+
+  const paths = resolveCodegenPaths(config);
+  const {
+    paramsTypeName,
+    schemaTypeName,
+    localeTypeName,
+    localeFallbackConstName,
+    factoryName,
+    deliveryAreaTypeName: resolvedDeliveryAreaTypeName,
+  } = paths;
+  const localeFallbackTypeName = `${localeTypeName}Fallback`;
+  const importExtension = DEFAULT_IMPORT_EXTENSION;
+
+  const requestLocales = collectRequestLocales(locales, config.localeFallback);
+  const requestLocalesList = [...requestLocales].sort();
+
+  if (delivery === "custom" && config.deliveryArtifacts) {
+    const deliveryArtifactsIssues = getDeliveryArtifactsIssues(
+      config.deliveryArtifacts,
+      requestLocales
+    );
+    if (deliveryArtifactsIssues.length > 0) {
+      reportCodegenIssues(deliveryArtifactsIssues);
+      throw new Error("[Codegen Error] Invalid deliveryArtifacts configuration.");
+    }
+  }
+
+  const {
+    resolvedEntries: entries,
+    splitPathsByNamespace,
+    compiledFiles,
+  } = prepareDictionaryEntries(projectRoot, sourceEntries, artifactsPathRelative, {
+    dictionariesByNamespace,
+    delivery,
+    localeFallback: config.localeFallback,
+    requestLocales: delivery === "split-by-locale" ? requestLocalesList : undefined,
+    deliveryArtifacts: delivery === "custom" ? config.deliveryArtifacts : undefined,
+  });
+
+  const typesOutputPath = path.resolve(projectRoot, paths.typesOutput);
+  const instanceOutputPath = path.resolve(projectRoot, paths.instanceOutput);
+  const namespaceLoadersOutputPath = path.resolve(projectRoot, paths.namespaceLoadersOutput);
+  const dictionarySchemaOutputPath = path.resolve(projectRoot, paths.dictionarySchemaOutput);
+  const typesModule = toModuleBasename(typesOutputPath);
+
+  const deliveryAreaNames =
+    delivery === "custom" && config.deliveryArtifacts
+      ? Object.keys(config.deliveryArtifacts).sort()
+      : undefined;
+  const deliveryAreaTypeName = delivery === "custom" ? resolvedDeliveryAreaTypeName : undefined;
+
+  const localeFallbackForEmit = config.localeFallback
+    ? enrichLocaleFallback(locales, config.localeFallback)
+    : undefined;
+
+  const typesContent = formatTypesFile({
+    entries,
+    projectRoot,
+    typesOutputPath,
+    paramsTypeName,
+    schemaTypeName,
+    localeTypeName,
+    localeFallbackConstName,
+    localeFallbackTypeName,
+    localeFallback: localeFallbackForEmit,
+    paramsByNamespace,
+    requestLocales: requestLocalesList,
+    ...(deliveryAreaTypeName && deliveryAreaNames
+      ? {
+          deliveryAreaTypeName,
+          deliveryAreaNames,
+          ...(delivery === "custom" && config.deliveryArtifacts
+            ? { deliveryArtifacts: config.deliveryArtifacts }
+            : {}),
+        }
+      : {}),
+    lazyEntries: entries,
+  });
+
+  const instanceContent = formatInstanceFile({
+    typesOutputPath,
+    namespaceLoadersOutputPath,
+    paramsTypeName,
+    schemaTypeName,
+    localeTypeName,
+    localeFallbackConstName,
+    factoryName,
+    hasLocaleFallback: Boolean(config.localeFallback),
+    hasLocaleType: requestLocalesList.length > 0,
+    importExtension,
+    delivery,
+    loaderStrategy,
+    ...(delivery === "custom" ? { localeDeliveryAreaConstName: "LOCALE_DELIVERY_AREA" } : {}),
+  });
+
+  writeFileIfChanged(typesOutputPath, typesContent);
+
+  const generatedFiles = [
+    path.relative(projectRoot, typesOutputPath),
+    path.relative(projectRoot, instanceOutputPath),
+  ];
+
+  writeFileIfChanged(instanceOutputPath, instanceContent);
+
+  const dictionarySpecBlock = formatDictionarySpecBlock(entries, argsSpecByNamespace);
+  const dictionarySchemaContent = formatDictionarySchemaFile(
+    schemaTypeName,
+    typesModule,
+    dictionarySpecBlock,
+    importExtension
+  );
+  writeFileIfChanged(dictionarySchemaOutputPath, dictionarySchemaContent);
+  generatedFiles.push(path.relative(projectRoot, dictionarySchemaOutputPath));
+
+  const lazyEntriesWithPaths = entries.map((entry) => ({
+    ...entry,
+    absolutePath: path.resolve(projectRoot, entry.filePath),
+  }));
+  const namespaceLoadersContent = formatNamespaceLoadersFile({
+    loadersOutputPath: namespaceLoadersOutputPath,
+    lazyEntries: lazyEntriesWithPaths,
+    schemaTypeName,
+    localeTypeName,
+    typesModule,
+    importExtension,
+    projectRoot,
+    delivery,
+    splitPathsByNamespace,
+    loaderStrategy,
+    ...(delivery === "split-by-locale" ? { requestLocales: requestLocalesList } : {}),
+    ...(delivery === "custom" && deliveryAreaTypeName && deliveryAreaNames
+      ? { deliveryAreaTypeName, deliveryAreaNames }
+      : {}),
+  });
+
+  writeFileIfChanged(namespaceLoadersOutputPath, namespaceLoadersContent);
+  generatedFiles.push(path.relative(projectRoot, namespaceLoadersOutputPath));
+
+  if (log) {
+    console.log(`✅ Generated: ${generatedFiles.join(", ")}`);
+    if (compiledFiles.length > 0) {
+      console.log(`✅ Compiled: ${compiledFiles.join(", ")}`);
+    }
+  }
+
+  return { projectRoot, generatedFiles, compiledFiles };
+}

package/src/codegen/types.ts

@@ -8,9 +8,3 @@ export interface NamespaceEntry {
 }
 
 export type DictionaryJson = Record<string, Record<string, string>>;
-
-export interface LoadOnInitResolution {
-  loadOnInitSet: Set<string>;
-  lazyEntries: NamespaceEntry[];
-  hasLazy: boolean;
-}