@xndrjs/i18n 0.8.0 → 0.8.2-alpha.0

package/src/codegen/read-dictionary.ts

@@ -1,260 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import { IDENTIFIER_NAME_PATTERN, IDENTIFIER_NAME_REQUIREMENT } from "./constants.js";
-import type { DeliveryMode } from "./codegen-config-schema.js";
-import type { DeliveryArtifactsMap } from "./delivery-artifacts.js";
-import {
-  projectNamespaceForDeliveryAreaCore,
-  projectNamespaceLocalesCore,
-} from "../project-locales.js";
-import type { LocaleFallbackMap } from "../types.js";
-import type { DictionaryJson, NamespaceEntry } from "./types.js";
-import { writeFileIfChanged } from "./write-file-if-changed.js";
-
-/**
- * Dictionary I/O for codegen and audit: read/validate source files (`readDictionaryFile`)
- * and write compiled or split JSON artifacts (`prepareDictionaryEntries`).
- */
-export const SUPPORTED_DICTIONARY_EXTENSIONS = [".json", ".yaml", ".yml"] as const;
-export type DictionaryFormat = "json" | "yaml";
-
-export function getDictionaryFormat(filePath: string): DictionaryFormat | null {
-  const extension = path.extname(filePath).toLowerCase();
-  if (extension === ".json") {
-    return "json";
-  }
-  if (extension === ".yaml" || extension === ".yml") {
-    return "yaml";
-  }
-  return null;
-}
-
-export function resolveCompiledJsonPath(sourcePath: string, generatedDirRelative: string): string {
-  const baseName = `${path.basename(sourcePath, path.extname(sourcePath))}.json`;
-  return path.join(generatedDirRelative, "translations", baseName).replace(/\\/g, "/");
-}
-
-export function resolveSplitJsonPath(
-  sourcePath: string,
-  locale: string,
-  generatedDirRelative: string
-): string {
-  const baseName = path.basename(sourcePath, path.extname(sourcePath));
-  return path
-    .join(generatedDirRelative, "translations", `${baseName}.${locale}.json`)
-    .replace(/\\/g, "/");
-}
-
-export function resolveAreaJsonPath(
-  sourcePath: string,
-  area: string,
-  generatedDirRelative: string
-): string {
-  const baseName = path.basename(sourcePath, path.extname(sourcePath));
-  return path
-    .join(generatedDirRelative, "translations", `${baseName}.${area}.json`)
-    .replace(/\\/g, "/");
-}
-
-/** Projects a canonical dictionary into per-locale slices for split-by-locale delivery. */
-export function splitDictionaryByLocale(
-  dictionary: DictionaryJson,
-  locales: readonly string[],
-  localeFallback?: LocaleFallbackMap
-): Record<string, DictionaryJson> {
-  const byLocale: Record<string, DictionaryJson> = {};
-
-  for (const locale of locales) {
-    byLocale[locale] = projectNamespaceLocalesCore(dictionary, [locale], localeFallback);
-  }
-
-  return byLocale;
-}
-
-/** Projects a canonical dictionary into per-area slices for custom delivery. */
-export function splitDictionaryByDeliveryArea(
-  dictionary: DictionaryJson,
-  deliveryArtifacts: DeliveryArtifactsMap,
-  localeFallback?: LocaleFallbackMap
-): Record<string, DictionaryJson> {
-  const byArea: Record<string, DictionaryJson> = {};
-
-  for (const [area, areaLocales] of Object.entries(deliveryArtifacts)) {
-    byArea[area] = projectNamespaceForDeliveryAreaCore(dictionary, areaLocales, localeFallback);
-  }
-
-  return byArea;
-}
-
-function assertDictionaryShape(value: unknown, context: string): asserts value is DictionaryJson {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`[Codegen Error] ${context} must be a plain object.`);
-  }
-
-  for (const [key, localesByKey] of Object.entries(value)) {
-    if (!IDENTIFIER_NAME_PATTERN.test(key)) {
-      throw new Error(
-        `[Codegen Error] ${context}: invalid key "${key}" (${IDENTIFIER_NAME_REQUIREMENT}).`
-      );
-    }
-
-    if (localesByKey === null || typeof localesByKey !== "object" || Array.isArray(localesByKey)) {
-      throw new Error(`[Codegen Error] ${context}: key "${key}" must map locales to strings.`);
-    }
-
-    for (const [locale, template] of Object.entries(localesByKey)) {
-      if (typeof template !== "string") {
-        throw new Error(
-          `[Codegen Error] ${context}: key "${key}", locale "${locale}" must be a string.`
-        );
-      }
-    }
-  }
-}
-
-/** Reads and shape-validates a dictionary file from disk (JSON or YAML). */
-export function readDictionaryFile(absolutePath: string): DictionaryJson {
-  const format = getDictionaryFormat(absolutePath);
-  if (!format) {
-    throw new Error(
-      `[Codegen Error] Unsupported dictionary format "${path.extname(absolutePath)}" for ${absolutePath}. Use .json, .yaml, or .yml.`
-    );
-  }
-
-  const source = fs.readFileSync(absolutePath, "utf8");
-  let parsed: unknown;
-
-  try {
-    parsed = format === "json" ? JSON.parse(source) : parseYaml(source);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`[Codegen Error] Failed to parse dictionary ${absolutePath}: ${message}`);
-  }
-
-  assertDictionaryShape(parsed, `Dictionary file ${absolutePath}`);
-  return parsed;
-}
-
-function writeCompiledJson(absoluteJsonPath: string, dictionary: DictionaryJson): boolean {
-  return writeFileIfChanged(absoluteJsonPath, `${JSON.stringify(dictionary, null, 2)}\n`);
-}
-
-export interface PrepareDictionaryEntriesOptions {
-  dictionariesByNamespace: Record<string, DictionaryJson>;
-  delivery: DeliveryMode;
-  localeFallback?: LocaleFallbackMap | undefined;
-  requestLocales?: readonly string[] | undefined;
-  deliveryArtifacts?: DeliveryArtifactsMap | undefined;
-}
-
-export interface PrepareDictionariesResult {
-  resolvedEntries: NamespaceEntry[];
-  splitPathsByNamespace: Record<string, Record<string, string>>;
-  compiledFiles: string[];
-}
-
-/**
- * Phase 2 of codegen: materialize JSON artifacts on disk (locale/area split).
- * Returns `splitPathsByNamespace` consumed by namespace-loader emitters.
- */
-export function prepareDictionaryEntries(
-  projectRoot: string,
-  entries: NamespaceEntry[],
-  generatedDirRelative: string,
-  options: PrepareDictionaryEntriesOptions
-): PrepareDictionariesResult {
-  const delivery = options.delivery;
-  const { dictionariesByNamespace, localeFallback, requestLocales, deliveryArtifacts } = options;
-  const resolvedEntries: NamespaceEntry[] = [];
-  const splitPathsByNamespace: Record<string, Record<string, string>> = {};
-  const compiledFiles: string[] = [];
-
-  if (delivery === "split-by-locale" && (!requestLocales || requestLocales.length === 0)) {
-    throw new Error(
-      "[Codegen Error] split-by-locale delivery requires at least one request locale."
-    );
-  }
-
-  if (
-    delivery === "custom" &&
-    (!deliveryArtifacts || Object.keys(deliveryArtifacts).length === 0)
-  ) {
-    throw new Error("[Codegen Error] custom delivery requires deliveryArtifacts.");
-  }
-
-  for (const entry of entries) {
-    const sourceAbsolutePath = path.resolve(projectRoot, entry.filePath);
-    const format = getDictionaryFormat(entry.filePath);
-
-    if (!format) {
-      throw new Error(
-        `[Codegen Error] Namespace "${entry.namespace}" uses unsupported dictionary extension in "${entry.filePath}". Use .json, .yaml, or .yml.`
-      );
-    }
-
-    const dictionary = dictionariesByNamespace[entry.namespace];
-    if (!dictionary) {
-      throw new Error(
-        `[Codegen Error] Missing parsed dictionary for namespace "${entry.namespace}".`
-      );
-    }
-
-    if (delivery === "split-by-locale") {
-      const splitPaths: Record<string, string> = {};
-      const dictionariesByLocale = splitDictionaryByLocale(
-        dictionary,
-        requestLocales!,
-        localeFallback
-      );
-
-      for (const locale of requestLocales!) {
-        const splitRelativePath = resolveSplitJsonPath(
-          entry.filePath,
-          locale,
-          generatedDirRelative
-        );
-        const splitAbsolutePath = path.resolve(projectRoot, splitRelativePath);
-        const wroteFile = writeCompiledJson(splitAbsolutePath, dictionariesByLocale[locale]!);
-
-        if (wroteFile) {
-          compiledFiles.push(
-            `${path.relative(projectRoot, sourceAbsolutePath)} → ${splitRelativePath}`
-          );
-        }
-
-        splitPaths[locale] = splitRelativePath;
-      }
-
-      splitPathsByNamespace[entry.namespace] = splitPaths;
-      resolvedEntries.push(entry);
-      continue;
-    }
-
-    const splitPaths: Record<string, string> = {};
-    const dictionariesByArea = splitDictionaryByDeliveryArea(
-      dictionary,
-      deliveryArtifacts!,
-      localeFallback
-    );
-
-    for (const area of Object.keys(deliveryArtifacts!).sort()) {
-      const areaRelativePath = resolveAreaJsonPath(entry.filePath, area, generatedDirRelative);
-      const areaAbsolutePath = path.resolve(projectRoot, areaRelativePath);
-      const wroteFile = writeCompiledJson(areaAbsolutePath, dictionariesByArea[area]!);
-
-      if (wroteFile) {
-        compiledFiles.push(
-          `${path.relative(projectRoot, sourceAbsolutePath)} → ${areaRelativePath}`
-        );
-      }
-
-      splitPaths[area] = areaRelativePath;
-    }
-
-    splitPathsByNamespace[entry.namespace] = splitPaths;
-    resolvedEntries.push(entry);
-  }
-
-  return { resolvedEntries, splitPathsByNamespace, compiledFiles };
-}

package/src/codegen/regenerate-namespaces.ts

@@ -1,180 +0,0 @@
-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

@@ -1,230 +0,0 @@
-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/);
-  });
-});