@xndrjs/i18n 0.8.1 → 0.8.2-alpha.0

package/src/codegen/config.test.ts

@@ -1,231 +0,0 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { codegenConfigKeys, resolveCodegenPaths } from "./codegen-config-schema.js";
-import { loadConfig, resolveArtifactsPath } from "./config.js";
-
-function writeConfig(dir: string, config: Record<string, unknown>) {
-  const configPath = join(dir, "i18n.codegen.json");
-  writeFileSync(configPath, JSON.stringify(config, null, 2));
-  return configPath;
-}
-
-const validMultiConfig = {
-  projectName: "App",
-  namespaces: {
-    default: "translations/default.json",
-  },
-  codegenPath: "generated",
-};
-
-describe("loadConfig", () => {
-  let tempDir: string;
-
-  afterEach(() => {
-    if (tempDir) {
-      rmSync(tempDir, { recursive: true, force: true });
-    }
-  });
-
-  it("accepts a valid multi-namespace config and defaults delivery to split-by-locale", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, validMultiConfig);
-
-    expect(loadConfig(configPath)).toEqual({
-      ...validMultiConfig,
-      delivery: "split-by-locale",
-      loaderStrategy: "import",
-    });
-  });
-
-  it("accepts fetch loaderStrategy", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      loaderStrategy: "fetch",
-    });
-
-    expect(loadConfig(configPath)).toMatchObject({
-      loaderStrategy: "fetch",
-    });
-  });
-
-  it("rejects unknown config keys", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      notARealKey: true,
-    });
-
-    expect(() => loadConfig(configPath)).toThrow();
-  });
-
-  it("resolves code paths and type names from projectName + codegenPath", () => {
-    expect(resolveCodegenPaths(validMultiConfig)).toMatchObject({
-      typesOutput: "generated/i18n-types.generated.ts",
-      instanceOutput: "generated/instance.generated.ts",
-      namespaceLoadersOutput: "generated/namespace-loaders.generated.ts",
-      dictionarySchemaOutput: "generated/dictionary-schema.generated.ts",
-      artifactsPath: "generated",
-      paramsTypeName: "AppParams",
-      schemaTypeName: "AppSchema",
-      localeTypeName: "AppLocale",
-      factoryName: "createI18n",
-      localeFallbackConstName: "LOCALE_FALLBACK",
-    });
-  });
-
-  it("throws on invalid config JSON", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = join(tempDir, "i18n.codegen.json");
-    writeFileSync(configPath, "{ not json");
-
-    expect(() => loadConfig(configPath)).toThrow(
-      `[Codegen Error] Failed to parse config JSON (${configPath})`
-    );
-  });
-
-  it("throws on unknown top-level keys and reports allowed keys", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      typoKey: true,
-    });
-
-    const act = () => loadConfig(configPath);
-    expect(act).toThrow("Invalid i18n.codegen.json");
-    expect(act).toThrow("typoKey");
-    expect(act).toThrow(`Allowed keys: ${codegenConfigKeys.join(", ")}`);
-  });
-
-  it("throws when required fields are missing", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      namespaces: validMultiConfig.namespaces,
-    });
-
-    const act = () => loadConfig(configPath);
-    expect(act).toThrow("projectName");
-    expect(act).toThrow("codegenPath");
-    expect(act).toThrow("Allowed keys:");
-  });
-
-  it("throws when projectName is not PascalCase", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      projectName: "my-app",
-    });
-
-    expect(() => loadConfig(configPath)).toThrow("projectName must be PascalCase");
-  });
-
-  it("throws when a namespace name is not a valid identifier", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      namespaces: {
-        default: "translations/default.json",
-        "user-area": "translations/user-area.json",
-      },
-    });
-
-    expect(() => loadConfig(configPath)).toThrow(
-      'Invalid namespace name "user-area" (allowed: letters, digits, underscore; must not start with a digit).'
-    );
-  });
-
-  it("accepts artifactsPath for custom json artifact directory", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      artifactsPath: "public/i18n",
-    });
-
-    expect(loadConfig(configPath)).toMatchObject({
-      artifactsPath: "public/i18n",
-      delivery: "split-by-locale",
-    });
-  });
-
-  it("resolveArtifactsPath defaults to codegenPath", () => {
-    expect(
-      resolveArtifactsPath({
-        codegenPath: "generated",
-      })
-    ).toBe("generated");
-    expect(
-      resolveArtifactsPath({
-        codegenPath: "generated",
-        artifactsPath: "public/i18n",
-      })
-    ).toBe("public/i18n");
-  });
-
-  it("accepts custom delivery with deliveryArtifacts", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      delivery: "custom",
-      deliveryArtifacts: {
-        eu: ["it", "fr"],
-        us: ["en-US"],
-      },
-      localeFallback: {
-        "en-US": null,
-        it: "en-US",
-        fr: null,
-      },
-    });
-
-    expect(loadConfig(configPath)).toMatchObject({
-      delivery: "custom",
-      deliveryArtifacts: {
-        eu: ["it", "fr"],
-        us: ["en-US"],
-      },
-    });
-  });
-
-  it("throws when delivery is custom without deliveryArtifacts", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      delivery: "custom",
-    });
-
-    expect(() => loadConfig(configPath)).toThrow(
-      'deliveryArtifacts is required when delivery is "custom"'
-    );
-  });
-
-  it("throws when deliveryArtifacts is set for non-custom delivery", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      delivery: "split-by-locale",
-      deliveryArtifacts: {
-        eu: ["it"],
-      },
-    });
-
-    expect(() => loadConfig(configPath)).toThrow(
-      'deliveryArtifacts is only allowed when delivery is "custom"'
-    );
-  });
-
-  it("throws when deliveryArtifacts has duplicate locales across areas", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      delivery: "custom",
-      deliveryArtifacts: {
-        eu: ["it", "fr"],
-        us: ["fr"],
-      },
-    });
-
-    expect(() => loadConfig(configPath)).toThrow('Locale "fr" appears in both "eu" and "us"');
-  });
-});

package/src/codegen/config.ts

@@ -1,42 +0,0 @@
-import fs from "node:fs";
-import type { NamespaceEntry } from "./types.js";
-import {
-  CodegenConfig,
-  codegenConfigSchema,
-  formatCodegenConfigIssues,
-} from "./codegen-config-schema.js";
-
-export {
-  resolveCodegenPaths,
-  resolveArtifactsPath,
-  GENERATED_BASENAMES,
-  DEFAULT_FACTORY_NAME,
-  DEFAULT_LOCALE_FALLBACK_CONST_NAME,
-} from "./codegen-config-schema.js";
-
-/** Parses and validates `i18n.codegen.json`; first step of the codegen pipeline. */
-export function loadConfig(configPath: string): CodegenConfig {
-  let raw: unknown;
-
-  try {
-    raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`[Codegen Error] Failed to parse config JSON (${configPath}): ${message}`);
-  }
-
-  const result = codegenConfigSchema.safeParse(raw);
-  if (!result.success) {
-    throw new Error(formatCodegenConfigIssues(result.error));
-  }
-
-  return result.data;
-}
-
-/** Maps config namespaces to namespace entries. */
-export function resolveNamespaces(config: CodegenConfig): NamespaceEntry[] {
-  return Object.entries(config.namespaces).map(([namespace, filePath]) => ({
-    namespace,
-    filePath,
-  }));
-}

package/src/codegen/constants.ts

@@ -1,9 +0,0 @@
-export const SUPPORTED_IMPORT_EXTENSIONS = ["none", ".ts", ".js"] as const;
-export type SupportedImportExtension = (typeof SUPPORTED_IMPORT_EXTENSIONS)[number];
-
-// Translation keys and namespace names become TypeScript identifiers and
-// template-literal type segments in the generated code, so they must be valid
-// identifiers (e.g. "app.title" would emit the broken type `"app.title:..."`).
-export const IDENTIFIER_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
-export const IDENTIFIER_NAME_REQUIREMENT =
-  "allowed: letters, digits, underscore; must not start with a digit";

package/src/codegen/delivery-artifacts.test.ts

@@ -1,167 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  formatDeliveryArtifactsBlock,
-  formatLocaleDeliveryAreaBlock,
-  getDeliveryAreaNames,
-  getDeliveryArtifactsIssues,
-  getDeliveryArtifactsPartitionIssues,
-  getDeliveryArtifactsStructureIssues,
-  getDeliveryArtifactsTypeName,
-  getLocaleDeliveryAreaMap,
-} from "./delivery-artifacts.js";
-
-describe("delivery-artifacts", () => {
-  const validArtifacts = {
-    eu: ["it", "fr"],
-    us: ["en-US"],
-  };
-
-  it("accepts a valid structure", () => {
-    expect(getDeliveryArtifactsStructureIssues(validArtifacts)).toEqual([]);
-  });
-
-  it("rejects invalid area names", () => {
-    const issues = getDeliveryArtifactsStructureIssues({
-      "1eu": ["it"],
-    });
-
-    expect(issues).toHaveLength(1);
-    expect(issues[0]?.message).toContain('Invalid delivery area name "1eu"');
-  });
-
-  it("rejects empty area locale lists", () => {
-    const issues = getDeliveryArtifactsStructureIssues({
-      eu: [],
-      us: ["en-US"],
-    });
-
-    expect(issues).toHaveLength(1);
-    expect(issues[0]?.message).toContain('Delivery area "eu" must include at least one locale');
-  });
-
-  it("rejects duplicate locales across areas", () => {
-    const issues = getDeliveryArtifactsStructureIssues({
-      eu: ["it", "fr"],
-      us: ["fr", "en-US"],
-    });
-
-    expect(issues).toHaveLength(1);
-    expect(issues[0]?.message).toContain('Locale "fr" appears in both "eu" and "us"');
-  });
-
-  it("requires an exhaustive partition of request locales", () => {
-    const requestLocales = new Set(["it", "fr", "en-US"]);
-
-    expect(getDeliveryArtifactsPartitionIssues(validArtifacts, requestLocales)).toEqual([]);
-  });
-
-  it("reports missing request locales", () => {
-    const issues = getDeliveryArtifactsPartitionIssues(
-      { eu: ["it"] },
-      new Set(["it", "fr", "en-US"])
-    );
-
-    expect(issues).toHaveLength(1);
-    expect(issues[0]?.message).toContain("missing locales");
-    expect(issues[0]?.message).toContain("fr");
-    expect(issues[0]?.message).toContain("en-US");
-  });
-
-  it("reports excess locales not in request set", () => {
-    const issues = getDeliveryArtifactsPartitionIssues(validArtifacts, new Set(["it"]));
-
-    expect(issues).toHaveLength(1);
-    expect(issues[0]?.message).toContain("includes locales not required");
-    expect(issues[0]?.message).toContain("fr");
-    expect(issues[0]?.message).toContain("en-US");
-  });
-
-  it("getDeliveryArtifactsIssues merges structure and partition errors", () => {
-    const issues = getDeliveryArtifactsIssues(
-      {
-        eu: [],
-        "1bad": ["it"],
-        us: ["it"],
-      },
-      new Set(["it", "en-US"])
-    );
-
-    expect(issues.map((issue) => issue.message)).toEqual(
-      expect.arrayContaining([
-        expect.stringContaining('Delivery area "eu" must include at least one locale'),
-        expect.stringContaining('Invalid delivery area name "1bad"'),
-        expect.stringContaining('Locale "it" appears in both "1bad" and "us"'),
-        expect.stringContaining("missing locales"),
-        expect.stringContaining("en-US"),
-      ])
-    );
-  });
-
-  it("returns sorted delivery area names", () => {
-    expect(
-      getDeliveryAreaNames({
-        us: ["en-US"],
-        eu: ["it", "fr"],
-      })
-    ).toEqual(["eu", "us"]);
-  });
-
-  it("builds locale to delivery area map", () => {
-    expect(
-      getLocaleDeliveryAreaMap({
-        amer: ["en-US", "es-AR"],
-        eu: ["en", "it", "fr", "es"],
-      })
-    ).toEqual({
-      en: "eu",
-      "en-US": "amer",
-      "es-AR": "amer",
-      es: "eu",
-      fr: "eu",
-      it: "eu",
-    });
-  });
-
-  it("formats locale delivery area block for generated types", () => {
-    expect(
-      formatLocaleDeliveryAreaBlock(
-        {
-          eu: ["it", "fr"],
-          us: ["en-US"],
-        },
-        "LOCALE_DELIVERY_AREA",
-        "AppLocale",
-        "AppDeliveryArea"
-      )
-    ).toBe(
-      "export const LOCALE_DELIVERY_AREA = {\n" +
-        '  "en-US": "us",\n' +
-        '  "fr": "eu",\n' +
-        '  "it": "eu",\n' +
-        "} as const satisfies Record<AppLocale, AppDeliveryArea>;\n\n"
-    );
-  });
-
-  it("formats delivery artifacts block for generated types", () => {
-    expect(getDeliveryArtifactsTypeName("AppDeliveryArea")).toBe("AppDeliveryArtifacts");
-
-    expect(
-      formatDeliveryArtifactsBlock(
-        {
-          eu: ["it", "fr"],
-          us: ["en-US"],
-        },
-        "DELIVERY_ARTIFACTS",
-        "AppLocale",
-        "AppDeliveryArea"
-      )
-    ).toBe(
-      "export const DELIVERY_ARTIFACTS = {\n" +
-        '  "eu": ["fr", "it"] as const,\n' +
-        '  "us": ["en-US"] as const,\n' +
-        "} as const satisfies Record<AppDeliveryArea, readonly AppLocale[]>;\n\n" +
-        "export type AppDeliveryArtifacts = typeof DELIVERY_ARTIFACTS;\n\n" +
-        "export type LocalesForDeliveryArea<A extends AppDeliveryArea> = AppDeliveryArtifacts[A][number];\n\n"
-    );
-  });
-});

package/src/codegen/delivery-artifacts.ts

@@ -1,154 +0,0 @@
-/** Valid TypeScript identifier / filename segment for a delivery area id. */
-export const DELIVERY_AREA_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
-
-export type DeliveryArtifactsMap = Record<string, readonly string[]>;
-
-export type DeliveryArtifactsIssue = {
-  path: (string | number)[];
-  message: string;
-};
-
-export function getDeliveryArtifactsStructureIssues(
-  deliveryArtifacts: DeliveryArtifactsMap
-): DeliveryArtifactsIssue[] {
-  const issues: DeliveryArtifactsIssue[] = [];
-
-  for (const [area, locales] of Object.entries(deliveryArtifacts)) {
-    if (!DELIVERY_AREA_NAME_PATTERN.test(area)) {
-      issues.push({
-        path: ["deliveryArtifacts", area],
-        message: `Invalid delivery area name "${area}": must match ${DELIVERY_AREA_NAME_PATTERN.source}`,
-      });
-    }
-
-    if (locales.length === 0) {
-      issues.push({
-        path: ["deliveryArtifacts", area],
-        message: `Delivery area "${area}" must include at least one locale.`,
-      });
-    }
-  }
-
-  const localeToArea = new Map<string, string>();
-  for (const [area, locales] of Object.entries(deliveryArtifacts)) {
-    for (const locale of locales) {
-      const previousArea = localeToArea.get(locale);
-      if (previousArea) {
-        issues.push({
-          path: ["deliveryArtifacts", area],
-          message: `Locale "${locale}" appears in both "${previousArea}" and "${area}".`,
-        });
-      } else {
-        localeToArea.set(locale, area);
-      }
-    }
-  }
-
-  return issues;
-}
-
-export function getDeliveryArtifactsPartitionIssues(
-  deliveryArtifacts: DeliveryArtifactsMap,
-  requestLocales: ReadonlySet<string>
-): DeliveryArtifactsIssue[] {
-  const issues: DeliveryArtifactsIssue[] = [];
-  const artifactLocales = new Set<string>();
-
-  for (const locales of Object.values(deliveryArtifacts)) {
-    for (const locale of locales) {
-      artifactLocales.add(locale);
-    }
-  }
-
-  const missing = [...requestLocales].filter((locale) => !artifactLocales.has(locale)).sort();
-  if (missing.length > 0) {
-    issues.push({
-      path: ["deliveryArtifacts"],
-      message: `deliveryArtifacts is missing locales required by dictionaries and localeFallback: ${missing.join(", ")}`,
-    });
-  }
-
-  const excess = [...artifactLocales].filter((locale) => !requestLocales.has(locale)).sort();
-  if (excess.length > 0) {
-    issues.push({
-      path: ["deliveryArtifacts"],
-      message: `deliveryArtifacts includes locales not required by dictionaries and localeFallback: ${excess.join(", ")}`,
-    });
-  }
-
-  return issues;
-}
-
-/** Pre-emit validation gate for `deliveryArtifacts` in custom delivery mode. */
-export function getDeliveryArtifactsIssues(
-  deliveryArtifacts: DeliveryArtifactsMap,
-  requestLocales: ReadonlySet<string>
-): DeliveryArtifactsIssue[] {
-  return [
-    ...getDeliveryArtifactsStructureIssues(deliveryArtifacts),
-    ...getDeliveryArtifactsPartitionIssues(deliveryArtifacts, requestLocales),
-  ];
-}
-
-export function getDeliveryAreaNames(deliveryArtifacts: DeliveryArtifactsMap): string[] {
-  return Object.keys(deliveryArtifacts).sort();
-}
-
-export function getLocaleDeliveryAreaMap(
-  deliveryArtifacts: DeliveryArtifactsMap
-): Record<string, string> {
-  const localeToArea: Record<string, string> = {};
-
-  for (const [area, locales] of Object.entries(deliveryArtifacts)) {
-    for (const locale of locales) {
-      localeToArea[locale] = area;
-    }
-  }
-
-  return localeToArea;
-}
-
-export function formatLocaleDeliveryAreaBlock(
-  deliveryArtifacts: DeliveryArtifactsMap,
-  constName: string,
-  localeTypeName: string,
-  deliveryAreaTypeName: string
-): string {
-  const localeToArea = getLocaleDeliveryAreaMap(deliveryArtifacts);
-  const lines = Object.keys(localeToArea)
-    .sort()
-    .map((locale) => `  ${JSON.stringify(locale)}: ${JSON.stringify(localeToArea[locale])},`)
-    .join("\n");
-
-  return `export const ${constName} = {\n${lines}\n} as const satisfies Record<${localeTypeName}, ${deliveryAreaTypeName}>;\n\n`;
-}
-
-export function getDeliveryArtifactsTypeName(deliveryAreaTypeName: string): string {
-  return deliveryAreaTypeName.endsWith("DeliveryArea")
-    ? deliveryAreaTypeName.replace(/DeliveryArea$/, "DeliveryArtifacts")
-    : `${deliveryAreaTypeName}Artifacts`;
-}
-
-export function formatDeliveryArtifactsBlock(
-  deliveryArtifacts: DeliveryArtifactsMap,
-  constName: string,
-  localeTypeName: string,
-  deliveryAreaTypeName: string
-): string {
-  const deliveryArtifactsTypeName = getDeliveryArtifactsTypeName(deliveryAreaTypeName);
-  const areaEntries = getDeliveryAreaNames(deliveryArtifacts)
-    .map((area) => {
-      const locales = [...deliveryArtifacts[area]!]
-        .sort()
-        .map((locale) => JSON.stringify(locale))
-        .join(", ");
-      return `  ${JSON.stringify(area)}: [${locales}] as const,`;
-    })
-    .join("\n");
-
-  return (
-    `export const ${constName} = {\n${areaEntries}\n} as const satisfies Record<${deliveryAreaTypeName}, readonly ${localeTypeName}[]>;\n\n` +
-    `export type ${deliveryArtifactsTypeName} = typeof ${constName};\n\n` +
-    `export type LocalesForDeliveryArea<A extends ${deliveryAreaTypeName}> = ${deliveryArtifactsTypeName}[A][number];\n\n`
-  );
-}

package/src/codegen/dictionary-spec-contract.test.ts

@@ -1,28 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  buildDictionarySpecFromAnalysis,
-  namespaceContractsMatch,
-} from "./dictionary-spec-contract.js";
-
-describe("dictionary-spec-contract", () => {
-  it("namespaceContractsMatch compares keys and VariableSpec", () => {
-    const entries = [{ namespace: "default", filePath: "translations/default.json" }];
-    const current = buildDictionarySpecFromAnalysis(entries, {
-      default: { welcome: { name: "string" }, login: {} },
-    });
-    const established = buildDictionarySpecFromAnalysis(entries, {
-      default: { welcome: { name: "string" }, login: {} },
-    });
-    expect(namespaceContractsMatch(["default"], current, established)).toBe(true);
-
-    const changedArgs = buildDictionarySpecFromAnalysis(entries, {
-      default: { welcome: { name: "string", extra: "string" }, login: {} },
-    });
-    expect(namespaceContractsMatch(["default"], changedArgs, established)).toBe(false);
-
-    const changedKeys = buildDictionarySpecFromAnalysis(entries, {
-      default: { welcome: { name: "string" } },
-    });
-    expect(namespaceContractsMatch(["default"], changedKeys, established)).toBe(false);
-  });
-});