@butlerw/vellum 0.1.0

package/src/tui/i18n/__tests__/init.test.ts

@@ -0,0 +1,278 @@
+/**
+ * i18n Init Unit Tests
+ *
+ * Tests for locale resolution and initialization:
+ * - resolveLocale() priority chain
+ * - initI18n() initialization
+ * - Source tracking for each priority level
+ *
+ * @module tui/i18n/__tests__/init
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { initI18n, type ResolvedLocale, resolveLocale } from "../init.js";
+import { DEFAULT_LOCALE } from "../language-config.js";
+
+// Mock dependencies
+vi.mock("../locale-detection.js", () => ({
+  detectSystemLocale: vi.fn(),
+}));
+
+vi.mock("../settings-integration.js", () => ({
+  getSavedLanguage: vi.fn(),
+}));
+
+vi.mock("../tui-namespace.js", () => ({
+  setGlobalLocale: vi.fn(),
+}));
+
+import { detectSystemLocale } from "../locale-detection.js";
+import { getSavedLanguage } from "../settings-integration.js";
+import { setGlobalLocale } from "../tui-namespace.js";
+
+// =============================================================================
+// Test Setup
+// =============================================================================
+
+describe("init", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    process.env = { ...originalEnv };
+    delete process.env.VELLUM_LANGUAGE;
+
+    // Default mock returns
+    vi.mocked(detectSystemLocale).mockReturnValue({ locale: null, source: null });
+    vi.mocked(getSavedLanguage).mockReturnValue(undefined);
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  // ===========================================================================
+  // T023: resolveLocale Priority Chain Tests
+  // ===========================================================================
+
+  describe("resolveLocale", () => {
+    describe("priority 1: CLI flag", () => {
+      it("CLI flag has highest priority", () => {
+        // Set up all sources with different values
+        process.env.VELLUM_LANGUAGE = "en";
+        vi.mocked(getSavedLanguage).mockReturnValue("en");
+        vi.mocked(detectSystemLocale).mockReturnValue({ locale: "en", source: "LANG" });
+
+        const result = resolveLocale({ cliLanguage: "zh" });
+
+        expect(result.locale).toBe("zh");
+        expect(result.source).toBe("cli-flag");
+      });
+
+      it("returns cli-flag source for valid CLI language", () => {
+        const result = resolveLocale({ cliLanguage: "en" });
+
+        expect(result.locale).toBe("en");
+        expect(result.source).toBe("cli-flag");
+      });
+
+      it("skips invalid CLI language and checks next priority", () => {
+        process.env.VELLUM_LANGUAGE = "zh";
+
+        const result = resolveLocale({ cliLanguage: "invalid" });
+
+        expect(result.locale).toBe("zh");
+        expect(result.source).toBe("env-var");
+      });
+
+      it("skips empty CLI language", () => {
+        process.env.VELLUM_LANGUAGE = "zh";
+
+        const result = resolveLocale({ cliLanguage: "" });
+
+        expect(result.locale).toBe("zh");
+        expect(result.source).toBe("env-var");
+      });
+    });
+
+    describe("priority 2: VELLUM_LANGUAGE env var", () => {
+      it("uses VELLUM_LANGUAGE when CLI flag not provided", () => {
+        process.env.VELLUM_LANGUAGE = "zh";
+        vi.mocked(getSavedLanguage).mockReturnValue("en");
+
+        const result = resolveLocale();
+
+        expect(result.locale).toBe("zh");
+        expect(result.source).toBe("env-var");
+      });
+
+      it("returns env-var source", () => {
+        process.env.VELLUM_LANGUAGE = "en";
+
+        const result = resolveLocale();
+
+        expect(result.source).toBe("env-var");
+      });
+
+      it("skips invalid VELLUM_LANGUAGE", () => {
+        process.env.VELLUM_LANGUAGE = "invalid";
+        vi.mocked(getSavedLanguage).mockReturnValue("zh");
+
+        const result = resolveLocale();
+
+        expect(result.locale).toBe("zh");
+        expect(result.source).toBe("settings");
+      });
+    });
+
+    describe("priority 3: settings file", () => {
+      it("uses saved settings when env var not set", () => {
+        vi.mocked(getSavedLanguage).mockReturnValue("zh");
+
+        const result = resolveLocale();
+
+        expect(result.locale).toBe("zh");
+        expect(result.source).toBe("settings");
+      });
+
+      it("returns settings source", () => {
+        vi.mocked(getSavedLanguage).mockReturnValue("en");
+
+        const result = resolveLocale();
+
+        expect(result.source).toBe("settings");
+      });
+
+      it("skips invalid saved language (already filtered by getSavedLanguage)", () => {
+        // getSavedLanguage already validates, so this tests undefined return
+        vi.mocked(getSavedLanguage).mockReturnValue(undefined);
+        vi.mocked(detectSystemLocale).mockReturnValue({ locale: "zh", source: "LANG" });
+
+        const result = resolveLocale();
+
+        expect(result.locale).toBe("zh");
+        expect(result.source).toBe("system");
+      });
+    });
+
+    describe("priority 4: system locale", () => {
+      it("uses system locale when settings not available", () => {
+        vi.mocked(detectSystemLocale).mockReturnValue({ locale: "zh", source: "LANG" });
+
+        const result = resolveLocale();
+
+        expect(result.locale).toBe("zh");
+        expect(result.source).toBe("system");
+      });
+
+      it("returns system source", () => {
+        vi.mocked(detectSystemLocale).mockReturnValue({ locale: "en", source: "LC_ALL" });
+
+        const result = resolveLocale();
+
+        expect(result.source).toBe("system");
+      });
+
+      it("skips unsupported system locale", () => {
+        // detectSystemLocale returns null for unsupported
+        vi.mocked(detectSystemLocale).mockReturnValue({ locale: null, source: null });
+
+        const result = resolveLocale();
+
+        expect(result.locale).toBe(DEFAULT_LOCALE);
+        expect(result.source).toBe("default");
+      });
+    });
+
+    describe("priority 5: default locale", () => {
+      it('falls back to DEFAULT_LOCALE ("en") when no source available', () => {
+        const result = resolveLocale();
+
+        expect(result.locale).toBe("en");
+        expect(result.source).toBe("default");
+      });
+
+      it("returns default source", () => {
+        const result = resolveLocale();
+
+        expect(result.source).toBe("default");
+      });
+
+      it("DEFAULT_LOCALE is 'en'", () => {
+        expect(DEFAULT_LOCALE).toBe("en");
+      });
+    });
+
+    describe("options handling", () => {
+      it("works with undefined options", () => {
+        const result = resolveLocale(undefined);
+
+        expect(result).toBeDefined();
+        expect(result.locale).toBe("en");
+      });
+
+      it("works with empty options object", () => {
+        const result = resolveLocale({});
+
+        expect(result).toBeDefined();
+        expect(result.locale).toBe("en");
+      });
+    });
+  });
+
+  // ===========================================================================
+  // T023: initI18n Tests
+  // ===========================================================================
+
+  describe("initI18n", () => {
+    it("resolves and sets global locale", () => {
+      vi.mocked(getSavedLanguage).mockReturnValue("zh");
+
+      const result = initI18n();
+
+      expect(setGlobalLocale).toHaveBeenCalledWith("zh");
+      expect(result.locale).toBe("zh");
+      expect(result.source).toBe("settings");
+    });
+
+    it("passes CLI language option to resolveLocale", () => {
+      const result = initI18n({ cliLanguage: "zh" });
+
+      expect(setGlobalLocale).toHaveBeenCalledWith("zh");
+      expect(result.locale).toBe("zh");
+      expect(result.source).toBe("cli-flag");
+    });
+
+    it("returns resolved locale information", () => {
+      process.env.VELLUM_LANGUAGE = "en";
+
+      const result = initI18n();
+
+      expect(result).toEqual({
+        locale: "en",
+        source: "env-var",
+      } satisfies ResolvedLocale);
+    });
+
+    it("sets default locale when no sources available", () => {
+      const result = initI18n();
+
+      expect(setGlobalLocale).toHaveBeenCalledWith("en");
+      expect(result.locale).toBe("en");
+      expect(result.source).toBe("default");
+    });
+
+    it("respects full priority chain", () => {
+      // Set up lower priority sources
+      process.env.VELLUM_LANGUAGE = "en";
+      vi.mocked(getSavedLanguage).mockReturnValue("en");
+      vi.mocked(detectSystemLocale).mockReturnValue({ locale: "en", source: "LANG" });
+
+      // CLI flag should win
+      const result = initI18n({ cliLanguage: "zh" });
+
+      expect(result.locale).toBe("zh");
+      expect(result.source).toBe("cli-flag");
+    });
+  });
+});

package/src/tui/i18n/__tests__/language-config.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Language Config Unit Tests
+ *
+ * Tests for language configuration constants and utilities:
+ * - isLocaleSupported() validation
+ * - getLanguageDisplayName() returns native names
+ * - getAvailableLocales() returns all locales
+ * - SUPPORTED_LOCALES and DEFAULT_LOCALE constants
+ *
+ * @module tui/i18n/__tests__/language-config
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_LOCALE,
+  getAvailableLocales,
+  getLanguageDisplayName,
+  isLocaleSupported,
+  LANGUAGES,
+  type LocaleCode,
+  SUPPORTED_LOCALES,
+} from "../language-config.js";
+
+// =============================================================================
+// T020: isLocaleSupported Tests
+// =============================================================================
+
+describe("isLocaleSupported", () => {
+  it("returns true for 'en'", () => {
+    expect(isLocaleSupported("en")).toBe(true);
+  });
+
+  it("returns true for 'zh'", () => {
+    expect(isLocaleSupported("zh")).toBe(true);
+  });
+
+  it("returns false for 'invalid'", () => {
+    expect(isLocaleSupported("invalid")).toBe(false);
+  });
+
+  it("returns false for empty string", () => {
+    expect(isLocaleSupported("")).toBe(false);
+  });
+
+  it("returns false for unsupported locale codes", () => {
+    expect(isLocaleSupported("fr")).toBe(false);
+    expect(isLocaleSupported("de")).toBe(false);
+    expect(isLocaleSupported("ja")).toBe(false);
+  });
+
+  it("is case-sensitive", () => {
+    expect(isLocaleSupported("EN")).toBe(false);
+    expect(isLocaleSupported("En")).toBe(false);
+    expect(isLocaleSupported("ZH")).toBe(false);
+  });
+
+  it("acts as type guard narrowing to LocaleCode", () => {
+    const input: string = "en";
+    if (isLocaleSupported(input)) {
+      // TypeScript should narrow input to LocaleCode here
+      const locale: LocaleCode = input;
+      expect(locale).toBe("en");
+    } else {
+      // This should not be reached
+      expect.fail("Should have recognized 'en' as supported");
+    }
+  });
+});
+
+// =============================================================================
+// T020: getLanguageDisplayName Tests
+// =============================================================================
+
+describe("getLanguageDisplayName", () => {
+  it("returns 'English' for 'en'", () => {
+    expect(getLanguageDisplayName("en")).toBe("English");
+  });
+
+  it("returns '中文' for 'zh'", () => {
+    expect(getLanguageDisplayName("zh")).toBe("中文");
+  });
+
+  it("returns native names for all supported locales", () => {
+    for (const locale of SUPPORTED_LOCALES) {
+      const name = getLanguageDisplayName(locale);
+      expect(name).toBe(LANGUAGES[locale].nativeName);
+      expect(typeof name).toBe("string");
+      expect(name.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+// =============================================================================
+// T020: getAvailableLocales Tests
+// =============================================================================
+
+describe("getAvailableLocales", () => {
+  it("returns array containing 'en'", () => {
+    const locales = getAvailableLocales();
+    expect(locales).toContain("en");
+  });
+
+  it("returns array containing 'zh'", () => {
+    const locales = getAvailableLocales();
+    expect(locales).toContain("zh");
+  });
+
+  it("returns at least 2 locales", () => {
+    const locales = getAvailableLocales();
+    expect(locales.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("returns readonly array", () => {
+    const locales = getAvailableLocales();
+    // TypeScript compile-time check - array should be readonly
+    expect(Array.isArray(locales)).toBe(true);
+  });
+
+  it("returns same reference as SUPPORTED_LOCALES", () => {
+    expect(getAvailableLocales()).toBe(SUPPORTED_LOCALES);
+  });
+});
+
+// =============================================================================
+// T020: SUPPORTED_LOCALES Constant Tests
+// =============================================================================
+
+describe("SUPPORTED_LOCALES", () => {
+  it("contains 'en'", () => {
+    expect(SUPPORTED_LOCALES).toContain("en");
+  });
+
+  it("contains 'zh'", () => {
+    expect(SUPPORTED_LOCALES).toContain("zh");
+  });
+
+  it("is a readonly array", () => {
+    expect(Array.isArray(SUPPORTED_LOCALES)).toBe(true);
+  });
+
+  it("matches keys of LANGUAGES object", () => {
+    const languageKeys = Object.keys(LANGUAGES);
+    expect([...SUPPORTED_LOCALES].sort()).toEqual(languageKeys.sort());
+  });
+});
+
+// =============================================================================
+// T020: DEFAULT_LOCALE Constant Tests
+// =============================================================================
+
+describe("DEFAULT_LOCALE", () => {
+  it("is 'en'", () => {
+    expect(DEFAULT_LOCALE).toBe("en");
+  });
+
+  it("is a supported locale", () => {
+    expect(isLocaleSupported(DEFAULT_LOCALE)).toBe(true);
+  });
+
+  it("is included in SUPPORTED_LOCALES", () => {
+    expect(SUPPORTED_LOCALES).toContain(DEFAULT_LOCALE);
+  });
+});
+
+// =============================================================================
+// T020: LANGUAGES Object Tests
+// =============================================================================
+
+describe("LANGUAGES", () => {
+  it("has correct structure for English", () => {
+    expect(LANGUAGES.en).toEqual({
+      locale: "en",
+      name: "English",
+      nativeName: "English",
+      flag: "🇺🇸",
+    });
+  });
+
+  it("has correct structure for Chinese", () => {
+    expect(LANGUAGES.zh).toEqual({
+      locale: "zh",
+      name: "Chinese",
+      nativeName: "中文",
+      flag: "🇨🇳",
+    });
+  });
+
+  it("all entries have required properties", () => {
+    for (const [code, info] of Object.entries(LANGUAGES)) {
+      expect(info.locale).toBe(code);
+      expect(typeof info.name).toBe("string");
+      expect(typeof info.nativeName).toBe("string");
+      expect(typeof info.flag).toBe("string");
+      expect(info.name.length).toBeGreaterThan(0);
+      expect(info.nativeName.length).toBeGreaterThan(0);
+    }
+  });
+});