@xndrjs/i18n 0.3.2 → 0.3.3

package/README.md

@@ -21,14 +21,14 @@ The core idea: your ICU strings live in local JSON files that act as **type-safe
 ### Install
 
 ```bash
-npm install @xndrjs/i18n tsx
-# optional — external dictionary validation
-npm install zod
+npm install @xndrjs/i18n zod
+npm install -D tsx
 ```
 
-`tsx` is a **peer dependency** required by `xndrjs-i18n-codegen`: the CLI runs the TypeScript codegen script directly (no precompiled JS bundle). Add it to your app or monorepo root.
+`tsx` and `zod` are **peer dependencies** of `@xndrjs/i18n`:
 
-`zod` is optional — only needed when you use `dictionarySchemaOutput` and the generated `validateExternalDictionary()` helpers.
+- **`tsx`** — required by `xndrjs-i18n-codegen` and `xndrjs-i18n-audit` (CLIs run TypeScript directly). Install as a **devDependency** — only needed at build/CI time.
+- **`zod`** — required by codegen/audit config validation (`i18n.codegen.json`) and by `@xndrjs/i18n/validation` when using `dictionarySchemaOutput` and `validateExternalDictionary()`. Use a **devDependency** if validation runs only at build time; a regular **dependency** if you validate CMS payloads in production.
 
 ### Quick setup (single file)
 
@@ -533,7 +533,7 @@ Enable validation by adding `dictionarySchemaOutput` to `i18n/i18n.codegen.json`
 }
 ```
 
-Add `zod` as a dependency in the consumer app (optional peer of `@xndrjs/i18n`).
+Add `zod` as a dependency in the consumer app (required peer of `@xndrjs/i18n`).
 
 Codegen emits `DICTIONARY_SPEC` and `validateExternalDictionary()`. Validation runs in two phases:
 
@@ -641,5 +641,5 @@ pnpm run demo:multi            # tsx multi/src/index.ts
 - **TypeScript 6** (`strict`, `resolveJsonModule`, `moduleResolution: "bundler"`)
 - **[intl-messageformat](https://www.npmjs.com/package/intl-messageformat)** — runtime ICU formatting
 - **[@formatjs/icu-messageformat-parser](https://www.npmjs.com/package/@formatjs/icu-messageformat-parser)** — build-time AST parsing
-- **[zod](https://www.npmjs.com/package/zod)** — optional peer for external dictionary validation
+- **[zod](https://www.npmjs.com/package/zod)** — peer dependency (config validation, external dictionary validation)
 - **[tsx](https://www.npmjs.com/package/tsx)** — runs TypeScript scripts directly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xndrjs/i18n",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Compiler-first, type-safe ICU MessageFormat i18n with runtime dictionary override from external sources.",
   "private": false,
   "license": "MIT",
@@ -45,11 +45,6 @@
     "tsx": ">=4",
     "zod": "^4.0.0"
   },
-  "peerDependenciesMeta": {
-    "zod": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",

package/src/audit/audit-dictionaries.ts

@@ -1,7 +1,8 @@
 import path from "node:path";
-import type { CodegenConfig, DictionaryJson } from "../codegen/types.js";
+import type { DictionaryJson } from "../codegen/types.js";
 import { buildRequiredLocales, enrichLocaleFallback } from "../codegen/locale-policy.js";
 import { resolveLocaleTemplate } from "../resolve-locale.js";
+import { CodegenConfig } from "../codegen/codegen-config-schema.js";
 
 export type FailOnCriterion = "effective" | "direct" | "any";
 
@@ -105,7 +106,7 @@ export function auditDictionaries(options: AuditDictionariesOptions): I18nAuditR
 
   return {
     requiredLocales,
-    localeFallback: localeFallbackForAudit,
+    ...(localeFallbackForAudit !== undefined ? { localeFallback: localeFallbackForAudit } : {}),
     summary,
     missingDirectByLocale,
     missingEffectiveByLocale,
@@ -162,7 +163,9 @@ export async function runAuditFromConfig(options: RunAuditOptions): Promise<RunA
   const report = auditDictionaries({
     namespaces,
     config,
-    treatEmptyAsMissing: options.treatEmptyAsMissing,
+    ...(options.treatEmptyAsMissing !== undefined
+      ? { treatEmptyAsMissing: options.treatEmptyAsMissing }
+      : {}),
   });
 
   const exitCode =

package/src/audit/run-audit.ts

@@ -37,7 +37,12 @@ export function parseAuditArgs(argv: string[]): AuditCliOptions {
 
   const treatEmptyAsMissing = !argv.includes("--allow-empty");
 
-  return { configPath, outPath, failOn, treatEmptyAsMissing };
+  return {
+    configPath,
+    treatEmptyAsMissing,
+    ...(outPath !== undefined ? { outPath } : {}),
+    ...(failOn !== undefined ? { failOn } : {}),
+  };
 }
 
 export async function runAuditCli(argv = process.argv.slice(2)): Promise<number> {
@@ -56,7 +61,7 @@ export async function runAuditCli(argv = process.argv.slice(2)): Promise<number>
     config,
     configPath: options.configPath,
     treatEmptyAsMissing: options.treatEmptyAsMissing,
-    failOn: options.failOn,
+    ...(options.failOn !== undefined ? { failOn: options.failOn } : {}),
   });
 
   const json = `${JSON.stringify(report, null, 2)}\n`;

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

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { SUPPORTED_IMPORT_EXTENSIONS } from "./constants.js";
+
+const localeFallbackSchema = z.record(z.string(), z.union([z.string(), z.null()]));
+
+const codegenConfigShape = {
+  dictionary: z.string().min(1).optional(),
+  namespaces: z.record(z.string(), z.string().min(1)).optional(),
+  defaultNamespace: z.string().min(1).optional(),
+  typesOutput: z.string().min(1),
+  dictionaryOutput: z.string().min(1),
+  instanceOutput: z.string().min(1),
+  dictionarySchemaOutput: z.string().min(1).optional(),
+  loadOnInit: z.array(z.string().min(1)).optional(),
+  namespaceLoadersOutput: z.string().min(1).optional(),
+  importExtension: z.enum(SUPPORTED_IMPORT_EXTENSIONS).optional(),
+  paramsTypeName: z.string().min(1),
+  schemaTypeName: z.string().min(1),
+  localeTypeName: z.string().min(1).optional(),
+  localeFallbackConstName: z.string().min(1).optional(),
+  localeFallback: localeFallbackSchema.optional(),
+  factoryName: z.string().min(1).optional(),
+};
+
+export const codegenConfigKeys = Object.keys(
+  codegenConfigShape
+) as (keyof typeof codegenConfigShape)[];
+
+export const codegenConfigSchema = z
+  .object(codegenConfigShape)
+  .strict()
+  .superRefine((config, ctx) => {
+    const hasDictionary = config.dictionary !== undefined;
+    const hasNamespaces = config.namespaces !== undefined;
+
+    if (hasDictionary === hasNamespaces) {
+      ctx.addIssue({
+        code: "custom",
+        message: 'Specify exactly one of "dictionary" or "namespaces".',
+      });
+    }
+  });
+
+export type CodegenConfig = z.infer<typeof codegenConfigSchema>;
+
+export function formatCodegenConfigIssues(error: z.ZodError): string {
+  const issueLines = error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+    return `  - ${path}: ${issue.message}`;
+  });
+
+  return [
+    "[Codegen Error] Invalid i18n.codegen.json:",
+    ...issueLines,
+    "",
+    `Allowed keys: ${codegenConfigKeys.join(", ")}`,
+  ].join("\n");
+}

package/src/codegen/config.test.ts

@@ -0,0 +1,106 @@
+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 { codegenConfigKeys } from "./codegen-config-schema.js";
+import { loadConfig } 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 = {
+  namespaces: {
+    default: "translations/default.json",
+  },
+  typesOutput: "generated/i18n-types.generated.ts",
+  dictionaryOutput: "generated/dictionary.generated.ts",
+  instanceOutput: "generated/instance.generated.ts",
+  paramsTypeName: "AppParams",
+  schemaTypeName: "AppSchema",
+};
+
+describe("loadConfig", () => {
+  let tempDir: string;
+
+  afterEach(() => {
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("accepts a valid multi-namespace config", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, validMultiConfig);
+
+    expect(loadConfig(configPath)).toEqual(validMultiConfig);
+  });
+
+  it("fails 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);
+
+    expect(() => loadConfig(configPath)).toThrow("process.exit");
+    expect(errorSpy).toHaveBeenCalled();
+
+    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(", ")}`);
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  it("fails when both dictionary and namespaces are present", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      ...validMultiConfig,
+      dictionary: "translations/default.json",
+    });
+
+    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("process.exit");
+
+    const message = String(errorSpy.mock.calls[0]?.[0]);
+    expect(message).toContain('Specify exactly one of "dictionary" or "namespaces".');
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  it("fails when required fields are missing", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
+    const configPath = writeConfig(tempDir, {
+      namespaces: validMultiConfig.namespaces,
+    });
+
+    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("process.exit");
+
+    const message = String(errorSpy.mock.calls[0]?.[0]);
+    expect(message).toContain("typesOutput");
+    expect(message).toContain("Allowed keys:");
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+});

package/src/codegen/config.ts

@@ -1,10 +1,28 @@
 import fs from "node:fs";
-import type { CodegenConfig, LoadOnInitResolution, NamespaceEntry } from "./types.js";
+import type { LoadOnInitResolution, NamespaceEntry } from "./types.js";
+import {
+  CodegenConfig,
+  codegenConfigSchema,
+  formatCodegenConfigIssues,
+} from "./codegen-config-schema.js";
 import { fail } from "./paths.js";
 
 export function loadConfig(configPath: string): CodegenConfig {
-  const raw = fs.readFileSync(configPath, "utf8");
-  return JSON.parse(raw) as CodegenConfig;
+  let raw: unknown;
+
+  try {
+    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}`);
+  }
+
+  const result = codegenConfigSchema.safeParse(raw);
+  if (!result.success) {
+    fail(formatCodegenConfigIssues(result.error));
+  }
+
+  return result.data;
 }
 
 export function resolveNamespaces(config: CodegenConfig): NamespaceEntry[] {

package/src/codegen/constants.ts

@@ -0,0 +1 @@
+export const SUPPORTED_IMPORT_EXTENSIONS = ["none", ".ts", ".js"] as const;

package/src/codegen/generate-i18n-types.test.ts

@@ -795,7 +795,10 @@ describe("generate-i18n-types", () => {
 
     const result = runCodegen(tempDir);
     expect(result.status).not.toBe(0);
-    expect(result.stderr).toContain('importExtension must be "none", ".ts", or ".js"');
+    expect(result.stderr).toContain("Invalid i18n.codegen.json");
+    expect(result.stderr).toContain("importExtension");
+    expect(result.stderr).toContain('one of "none"|".ts"|".js"');
+    expect(result.stderr).toContain("Allowed keys:");
   });
 
   it("compiles yaml dictionaries to json and generates json imports", () => {

package/src/codegen/paths.ts

@@ -1,6 +1,7 @@
 import path from "node:path";
-import type { CodegenConfig, ImportExtension } from "./types.js";
-import { SUPPORTED_IMPORT_EXTENSIONS } from "./types.js";
+import type { ImportExtension } from "./types.js";
+import { SUPPORTED_IMPORT_EXTENSIONS } from "./constants.js";
+import { CodegenConfig } from "./codegen-config-schema.js";
 
 export const GENERATED_FILE_BANNER = "// Automatically generated code. Do not edit manually.\n";
 export const DEFAULT_IMPORT_EXTENSION: ImportExtension = "none";

package/src/codegen/types.ts

@@ -1,25 +1,6 @@
-export const SUPPORTED_IMPORT_EXTENSIONS = ["none", ".ts", ".js"] as const;
-export type ImportExtension = (typeof SUPPORTED_IMPORT_EXTENSIONS)[number];
+import type { SUPPORTED_IMPORT_EXTENSIONS } from "./constants.js";
 
-export interface CodegenConfig {
-  dictionary?: string;
-  namespaces?: Record<string, string>;
-  defaultNamespace?: string;
-  typesOutput: string;
-  dictionaryOutput: string;
-  instanceOutput: string;
-  dictionarySchemaOutput?: string;
-  loadOnInit?: string[];
-  namespaceLoadersOutput?: string;
-  /** Extension used in relative imports between generated modules. Default: "none" */
-  importExtension?: ImportExtension;
-  paramsTypeName: string;
-  schemaTypeName: string;
-  localeTypeName?: string;
-  localeFallbackConstName?: string;
-  localeFallback?: Record<string, string | null>;
-  factoryName?: string;
-}
+export type ImportExtension = (typeof SUPPORTED_IMPORT_EXTENSIONS)[number];
 
 export interface NamespaceEntry {
   namespace: string;