@xndrjs/i18n 0.4.0 → 0.5.0

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

@@ -4,7 +4,7 @@ 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 } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { parseAuditArgs, runAuditCli } from "./run-audit.js";
 
 const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
@@ -119,6 +119,40 @@ describe("runAuditCli", () => {
     }
   });
 
+  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" },

package/src/audit/run-audit.ts

@@ -1,7 +1,7 @@
 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 { fail } from "../codegen/paths.js";
 import { type FailOnCriterion, runAuditFromConfig } from "./audit-dictionaries.js";
 
 const FAIL_ON_VALUES = new Set<FailOnCriterion>(["effective", "direct", "any"]);
@@ -30,7 +30,7 @@ export function parseAuditArgs(argv: string[]): AuditCliOptions {
   if (failOnArgIndex >= 0) {
     const value = argv[failOnArgIndex + 1];
     if (!value || !FAIL_ON_VALUES.has(value as FailOnCriterion)) {
-      fail(`[Audit Error] --fail-on must be one of: effective, direct, any`);
+      throw new Error(`[Audit Error] --fail-on must be one of: effective, direct, any`);
     }
     failOn = value as FailOnCriterion;
   }
@@ -46,20 +46,28 @@ export function parseAuditArgs(argv: string[]): AuditCliOptions {
 }
 
 export async function runAuditCli(argv = process.argv.slice(2)): Promise<number> {
-  const options = parseAuditArgs(argv);
+  let options: AuditCliOptions;
+  let config: CodegenConfig;
 
-  if (!fs.existsSync(options.configPath)) {
-    console.error(`[Audit Error] Config file not found: ${options.configPath}`);
+  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 config = loadConfig(options.configPath);
 
   const { report, exitCode } = await runAuditFromConfig({
     projectRoot,
     config,
-    configPath: options.configPath,
     treatEmptyAsMissing: options.treatEmptyAsMissing,
     ...(options.failOn !== undefined ? { failOn: options.failOn } : {}),
   });

package/src/codegen/codegen-config-schema.ts

@@ -1,7 +1,17 @@
 import { z } from "zod";
-import { SUPPORTED_IMPORT_EXTENSIONS } from "./constants.js";
+import path from "node:path";
+import {
+  IDENTIFIER_NAME_PATTERN,
+  IDENTIFIER_NAME_REQUIREMENT,
+  SUPPORTED_IMPORT_EXTENSIONS,
+} from "./constants.js";
+import { getDeliveryArtifactsStructureIssues } from "./delivery-artifacts.js";
 
 const localeFallbackSchema = z.record(z.string(), z.union([z.string(), z.null()]));
+const deliveryArtifactsSchema = z.record(z.string(), z.array(z.string().min(1)));
+
+export const DELIVERY_MODES = ["canonical", "split-by-locale", "custom"] as const;
+export type DeliveryMode = (typeof DELIVERY_MODES)[number];
 
 const codegenConfigShape = {
   dictionary: z.string().min(1).optional(),
@@ -20,6 +30,9 @@ const codegenConfigShape = {
   localeFallbackConstName: z.string().min(1).optional(),
   localeFallback: localeFallbackSchema.optional(),
   factoryName: z.string().min(1).optional(),
+  delivery: z.enum(DELIVERY_MODES).optional().default("canonical"),
+  deliveryArtifacts: deliveryArtifactsSchema.optional(),
+  deliveryOutput: z.string().min(1).optional(),
 };
 
 export const codegenConfigKeys = Object.keys(
@@ -39,10 +52,64 @@ export const codegenConfigSchema = z
         message: 'Specify exactly one of "dictionary" or "namespaces".',
       });
     }
+
+    if (config.namespaces) {
+      for (const namespace of Object.keys(config.namespaces)) {
+        if (!IDENTIFIER_NAME_PATTERN.test(namespace)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["namespaces", namespace],
+            message: `Invalid namespace name "${namespace}" (${IDENTIFIER_NAME_REQUIREMENT}).`,
+          });
+        }
+      }
+    }
+
+    if (
+      config.defaultNamespace !== undefined &&
+      !IDENTIFIER_NAME_PATTERN.test(config.defaultNamespace)
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["defaultNamespace"],
+        message: `Invalid namespace name "${config.defaultNamespace}" (${IDENTIFIER_NAME_REQUIREMENT}).`,
+      });
+    }
+
+    if (config.delivery === "custom") {
+      if (!config.deliveryArtifacts) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["deliveryArtifacts"],
+          message: 'deliveryArtifacts is required when delivery is "custom".',
+        });
+      } else {
+        for (const issue of getDeliveryArtifactsStructureIssues(config.deliveryArtifacts)) {
+          ctx.addIssue({
+            code: "custom",
+            path: issue.path,
+            message: issue.message,
+          });
+        }
+      }
+    } else if (config.deliveryArtifacts !== undefined) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["deliveryArtifacts"],
+        message: 'deliveryArtifacts is only allowed when delivery is "custom".',
+      });
+    }
   });
 
+export type CodegenConfigInput = z.input<typeof codegenConfigSchema>;
 export type CodegenConfig = z.infer<typeof codegenConfigSchema>;
 
+export function resolveDeliveryOutputDir(
+  config: Pick<CodegenConfig, "typesOutput" | "deliveryOutput">
+): string {
+  return config.deliveryOutput ?? path.dirname(config.typesOutput);
+}
+
 export function formatCodegenConfigIssues(error: z.ZodError): string {
   const issueLines = error.issues.map((issue) => {
     const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";

package/src/codegen/config.test.ts

@@ -1,9 +1,10 @@
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import { codegenConfigKeys } from "./codegen-config-schema.js";
-import { loadConfig } from "./config.js";
+import { loadConfig, resolveDeliveryOutputDir, resolveLoadOnInit } from "./config.js";
+import { resolveImportExtension } from "./paths.js";
 
 function writeConfig(dir: string, config: Record<string, unknown>) {
   const configPath = join(dir, "i18n.codegen.json");
@@ -35,72 +36,206 @@ describe("loadConfig", () => {
     tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
     const configPath = writeConfig(tempDir, validMultiConfig);
 
-    expect(loadConfig(configPath)).toEqual(validMultiConfig);
+    expect(loadConfig(configPath)).toEqual({
+      ...validMultiConfig,
+      delivery: "canonical",
+    });
   });
 
-  it("fails on unknown top-level keys and reports allowed keys", () => {
+  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 exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
-      throw new Error("process.exit");
-    }) as typeof process.exit);
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => void 0);
+    const act = () => loadConfig(configPath);
+    expect(act).toThrow("Invalid i18n.codegen.json");
+    expect(act).toThrow("typoKey");
+    expect(act).toThrow(`Allowed keys: ${codegenConfigKeys.join(", ")}`);
+  });
 
-    expect(() => loadConfig(configPath)).toThrow("process.exit");
-    expect(errorSpy).toHaveBeenCalled();
+  it("throws when both dictionary and namespaces are present", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      ...validMultiConfig,
+      dictionary: "translations/default.json",
+    });
 
-    const message = String(errorSpy.mock.calls[0]?.[0]);
-    expect(message).toContain("Invalid i18n.codegen.json");
-    expect(message).toContain("typoKey");
-    expect(message).toContain(`Allowed keys: ${codegenConfigKeys.join(", ")}`);
+    expect(() => loadConfig(configPath)).toThrow(
+      'Specify exactly one of "dictionary" or "namespaces".'
+    );
+  });
 
-    exitSpy.mockRestore();
-    errorSpy.mockRestore();
+  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("typesOutput");
+    expect(act).toThrow("Allowed keys:");
   });
 
-  it("fails when both dictionary and namespaces are present", () => {
+  it("throws when a namespace name is not a valid identifier", () => {
     tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
     const configPath = writeConfig(tempDir, {
       ...validMultiConfig,
-      dictionary: "translations/default.json",
+      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("throws when defaultNamespace is not a valid identifier", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      ...validMultiConfig,
+      defaultNamespace: "1default",
     });
 
-    const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
-      throw new Error("process.exit");
-    }) as typeof process.exit);
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => void 0);
+    expect(() => loadConfig(configPath)).toThrow(
+      'defaultNamespace: Invalid namespace name "1default"'
+    );
+  });
 
-    expect(() => loadConfig(configPath)).toThrow("process.exit");
+  it("accepts deliveryOutput for custom json artifact directory", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      ...validMultiConfig,
+      deliveryOutput: "public/i18n",
+    });
 
-    const message = String(errorSpy.mock.calls[0]?.[0]);
-    expect(message).toContain('Specify exactly one of "dictionary" or "namespaces".');
+    expect(loadConfig(configPath)).toMatchObject({
+      deliveryOutput: "public/i18n",
+      delivery: "canonical",
+    });
+  });
 
-    exitSpy.mockRestore();
-    errorSpy.mockRestore();
+  it("resolveDeliveryOutputDir defaults to dirname(typesOutput)", () => {
+    expect(
+      resolveDeliveryOutputDir({
+        typesOutput: "generated/i18n-types.generated.ts",
+      })
+    ).toBe("generated");
+    expect(
+      resolveDeliveryOutputDir({
+        typesOutput: "generated/i18n-types.generated.ts",
+        deliveryOutput: "public/i18n",
+      })
+    ).toBe("public/i18n");
   });
 
-  it("fails when required fields are missing", () => {
+  it("accepts custom delivery with deliveryArtifacts", () => {
     tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
     const configPath = writeConfig(tempDir, {
-      namespaces: validMultiConfig.namespaces,
+      ...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"],
+      },
     });
 
-    const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
-      throw new Error("process.exit");
-    }) as typeof process.exit);
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => void 0);
+    expect(() => loadConfig(configPath)).toThrow('Locale "fr" appears in both "eu" and "us"');
+  });
+});
+
+describe("resolveLoadOnInit", () => {
+  const entries = [
+    { namespace: "default", filePath: "translations/default.json" },
+    { namespace: "billing", filePath: "translations/billing.json" },
+  ];
+
+  it("throws when loadOnInit is used in single mode", () => {
+    const config = { ...validMultiConfig, delivery: "canonical" as const, loadOnInit: ["default"] };
 
-    expect(() => loadConfig(configPath)).toThrow("process.exit");
+    expect(() => resolveLoadOnInit(config, entries, true)).toThrow(
+      '[Codegen Error] "loadOnInit" is only supported in multi mode (namespaces config).'
+    );
+  });
+
+  it("throws when loadOnInit references an unknown namespace", () => {
+    const config = { ...validMultiConfig, delivery: "canonical" as const, loadOnInit: ["missing"] };
 
-    const message = String(errorSpy.mock.calls[0]?.[0]);
-    expect(message).toContain("typesOutput");
-    expect(message).toContain("Allowed keys:");
+    expect(() => resolveLoadOnInit(config, entries, false)).toThrow(
+      '[Codegen Error] loadOnInit: namespace "missing" is not defined in namespaces config.'
+    );
+  });
+});
 
-    exitSpy.mockRestore();
-    errorSpy.mockRestore();
+describe("resolveImportExtension", () => {
+  it("throws on unsupported import extensions", () => {
+    expect(() => resolveImportExtension({ importExtension: ".mjs" as never })).toThrow(
+      '[Codegen Error] importExtension must be "none", ".ts", or ".js", got ".mjs".'
+    );
   });
 });

package/src/codegen/config.ts

@@ -5,8 +5,10 @@ import {
   codegenConfigSchema,
   formatCodegenConfigIssues,
 } from "./codegen-config-schema.js";
-import { fail } from "./paths.js";
 
+export { resolveDeliveryOutputDir } 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;
 
@@ -14,17 +16,18 @@ export function loadConfig(configPath: string): CodegenConfig {
     raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    fail(`[Codegen Error] Failed to parse config JSON (${configPath}): ${message}`);
+    throw new Error(`[Codegen Error] Failed to parse config JSON (${configPath}): ${message}`);
   }
 
   const result = codegenConfigSchema.safeParse(raw);
   if (!result.success) {
-    fail(formatCodegenConfigIssues(result.error));
+    throw new Error(formatCodegenConfigIssues(result.error));
   }
 
   return result.data;
 }
 
+/** Maps config to namespace entries (`dictionary` single vs `namespaces` multi). */
 export function resolveNamespaces(config: CodegenConfig): NamespaceEntry[] {
   const hasDictionary = Boolean(config.dictionary);
   const hasNamespaces = Boolean(config.namespaces);
@@ -50,6 +53,10 @@ export function resolveNamespaces(config: CodegenConfig): NamespaceEntry[] {
   }));
 }
 
+/**
+ * Splits namespaces into eager (`loadOnInit`) and lazy sets.
+ * Drives `InitialSchema`, `defaultDictionary`, and `namespace-loaders.generated.ts`.
+ */
 export function resolveLoadOnInit(
   config: CodegenConfig,
   entries: NamespaceEntry[],
@@ -57,7 +64,9 @@ export function resolveLoadOnInit(
 ): LoadOnInitResolution {
   if (isSingle) {
     if (config.loadOnInit) {
-      fail('[Codegen Error] "loadOnInit" is only supported in multi mode (namespaces config).');
+      throw new Error(
+        '[Codegen Error] "loadOnInit" is only supported in multi mode (namespaces config).'
+      );
     }
     const all = new Set(entries.map((entry) => entry.namespace));
     return { loadOnInitSet: all, lazyEntries: [], hasLazy: false };
@@ -70,7 +79,7 @@ export function resolveLoadOnInit(
 
   for (const namespace of loadOnInitSet) {
     if (!allNamespaces.has(namespace)) {
-      fail(
+      throw new Error(
         `[Codegen Error] loadOnInit: namespace "${namespace}" is not defined in namespaces config.`
       );
     }

package/src/codegen/constants.ts

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

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatLocaleDeliveryAreaBlock,
+  getDeliveryAreaNames,
+  getDeliveryArtifactsIssues,
+  getDeliveryArtifactsPartitionIssues,
+  getDeliveryArtifactsStructureIssues,
+  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"
+    );
+  });
+});