transduck 0.0.1

package/tests/ait.test.ts

@@ -0,0 +1,213 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { createHash } from 'crypto';
+import { join } from 'path';
+import { mkdtempSync } from 'fs';
+import { tmpdir } from 'os';
+import type { TransduckConfig } from '../src/config.js';
+
+function hash(text: string): string {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+function makeConfig(tmpDir: string): TransduckConfig {
+  return {
+    projectName: 'test',
+    projectContext: 'A test site',
+    sourceLang: 'EN',
+    targetLangs: ['DE', 'ES'],
+    storagePath: join(tmpDir, 'test.duckdb'),
+    apiKeyEnv: 'OPENAI_API_KEY',
+    backendModel: 'gpt-4.1-mini',
+    backendTimeout: 10,
+    backendMaxRetries: 2,
+  };
+}
+
+describe('ait', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    // Dynamic import to get fresh module state
+    const mod = await import('../src/index.js');
+    mod._resetState();
+    tmpDir = mkdtempSync(join(tmpdir(), 'transduck-test-'));
+    process.env.OPENAI_API_KEY = 'test-key';
+  });
+
+  it('returns source text when same language', async () => {
+    const { ait, setLanguage, initialize } = await import('../src/index.js');
+    await initialize(makeConfig(tmpDir));
+    setLanguage('EN');
+    const result = await ait('Hello');
+    expect(result).toBe('Hello');
+  });
+
+  it('returns cached translation', async () => {
+    const { ait, setLanguage, initialize, _getStore } = await import('../src/index.js');
+    const cfg = makeConfig(tmpDir);
+    await initialize(cfg);
+    setLanguage('DE');
+
+    // Pre-insert into storage
+    const store = _getStore();
+    await store!.insert({
+      sourceText: 'Hello', sourceLang: 'EN', targetLang: 'DE',
+      projectContextHash: hash('A test site'), stringContextHash: hash(''),
+      translatedText: 'Hallo', model: 'gpt-4.1-mini', status: 'translated',
+    });
+
+    const result = await ait('Hello');
+    expect(result).toBe('Hallo');
+  });
+
+  it('throws if not initialized', async () => {
+    const { ait } = await import('../src/index.js');
+    await expect(ait('Hello')).rejects.toThrow();
+  });
+
+  it('throws if no language set', async () => {
+    const { ait, initialize } = await import('../src/index.js');
+    await initialize(makeConfig(tmpDir));
+    await expect(ait('Hello')).rejects.toThrow('Target language not set');
+  });
+
+  // --- vars tests ---
+
+  it('interpolates vars in same-language return', async () => {
+    const { ait, setLanguage, initialize } = await import('../src/index.js');
+    await initialize(makeConfig(tmpDir));
+    setLanguage('EN');
+    const result = await ait('Welcome {name}', undefined, { name: 'Tim' });
+    expect(result).toBe('Welcome Tim');
+  });
+
+  it('interpolates vars in cached translation', async () => {
+    const { ait, setLanguage, initialize, _getStore } = await import('../src/index.js');
+    const cfg = makeConfig(tmpDir);
+    await initialize(cfg);
+    setLanguage('DE');
+
+    const store = _getStore();
+    await store!.insert({
+      sourceText: 'Welcome {name}', sourceLang: 'EN', targetLang: 'DE',
+      projectContextHash: hash('A test site'), stringContextHash: hash(''),
+      translatedText: 'Willkommen {name}', model: 'gpt-4.1-mini', status: 'translated',
+    });
+
+    const result = await ait('Welcome {name}', undefined, { name: 'Tim' });
+    expect(result).toBe('Willkommen Tim');
+  });
+
+  it('returns text with placeholders when no vars provided', async () => {
+    const { ait, setLanguage, initialize } = await import('../src/index.js');
+    await initialize(makeConfig(tmpDir));
+    setLanguage('EN');
+    const result = await ait('Welcome {name}');
+    expect(result).toBe('Welcome {name}');
+  });
+});
+
+describe('aitPlural', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    const mod = await import('../src/index.js');
+    mod._resetState();
+    tmpDir = mkdtempSync(join(tmpdir(), 'transduck-plural-test-'));
+    process.env.OPENAI_API_KEY = 'test-key';
+  });
+
+  it('throws if not initialized', async () => {
+    const { aitPlural } = await import('../src/index.js');
+    await expect(aitPlural('{count} msg', '{count} msgs', 5)).rejects.toThrow();
+  });
+
+  it('same-language 2-form: selects one for count=1', async () => {
+    const { aitPlural, setLanguage, initialize } = await import('../src/index.js');
+    await initialize(makeConfig(tmpDir));
+    setLanguage('EN');
+    const result = await aitPlural('{count} message', '{count} messages', 1);
+    expect(result).toBe('1 message');
+  });
+
+  it('same-language 2-form: selects other for count=5', async () => {
+    const { aitPlural, setLanguage, initialize } = await import('../src/index.js');
+    await initialize(makeConfig(tmpDir));
+    setLanguage('EN');
+    const result = await aitPlural('{count} message', '{count} messages', 5);
+    expect(result).toBe('5 messages');
+  });
+
+  it('same-language 2-form: selects other for count=0', async () => {
+    const { aitPlural, setLanguage, initialize } = await import('../src/index.js');
+    await initialize(makeConfig(tmpDir));
+    setLanguage('EN');
+    const result = await aitPlural('{count} message', '{count} messages', 0);
+    expect(result).toBe('0 messages');
+  });
+
+  it('same-language: includes custom vars', async () => {
+    const { aitPlural, setLanguage, initialize } = await import('../src/index.js');
+    await initialize(makeConfig(tmpDir));
+    setLanguage('EN');
+    const result = await aitPlural(
+      '{count} item in {name}\'s cart',
+      '{count} items in {name}\'s cart',
+      3,
+      { vars: { name: 'Tim' } },
+    );
+    expect(result).toBe("3 items in Tim's cart");
+  });
+
+  it('returns cached plural form', async () => {
+    const { aitPlural, setLanguage, initialize, _getStore } = await import('../src/index.js');
+    const cfg = makeConfig(tmpDir);
+    await initialize(cfg);
+    setLanguage('DE');
+
+    const store = _getStore();
+    const sourceKey = '{count} message\x00{count} messages';
+    const lookupParams = {
+      sourceText: sourceKey, sourceLang: 'EN', targetLang: 'DE',
+      projectContextHash: hash('A test site'), stringContextHash: hash(''),
+    };
+
+    await store!.insertPlural({
+      ...lookupParams,
+      pluralCategory: 'one',
+      translatedText: '{count} Nachricht',
+      model: 'gpt-4.1-mini', status: 'translated',
+    });
+    await store!.insertPlural({
+      ...lookupParams,
+      pluralCategory: 'other',
+      translatedText: '{count} Nachrichten',
+      model: 'gpt-4.1-mini', status: 'translated',
+    });
+
+    const result1 = await aitPlural('{count} message', '{count} messages', 1);
+    expect(result1).toBe('1 Nachricht');
+
+    const result5 = await aitPlural('{count} message', '{count} messages', 5);
+    expect(result5).toBe('5 Nachrichten');
+  });
+
+  it('auto-includes count in vars', async () => {
+    const { aitPlural, setLanguage, initialize } = await import('../src/index.js');
+    await initialize(makeConfig(tmpDir));
+    setLanguage('EN');
+    // count is auto-added even without explicit vars
+    const result = await aitPlural('{count} message', '{count} messages', 42);
+    expect(result).toBe('42 messages');
+  });
+
+  it('does not override explicit count in vars', async () => {
+    const { aitPlural, setLanguage, initialize } = await import('../src/index.js');
+    await initialize(makeConfig(tmpDir));
+    setLanguage('EN');
+    // If user provides count in vars, that value should be used
+    const result = await aitPlural('{count} message', '{count} messages', 1, { vars: { count: 99 } });
+    // count=1 selects "one" form, but the {count} var is 99 from explicit vars
+    expect(result).toBe('99 message');
+  });
+});

package/tests/backend.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, vi } from 'vitest';
+import { buildMessages, translate, buildPluralMessages, translatePlural } from '../src/backend.js';
+
+describe('buildMessages', () => {
+  it('builds system and user messages', () => {
+    const messages = buildMessages({
+      sourceText: 'Our Events',
+      sourceLang: 'EN',
+      targetLang: 'DE',
+      projectContext: 'A travel site about Mallorca',
+      stringContext: 'Events are concerts and shows',
+    });
+    expect(messages).toHaveLength(2);
+    expect(messages[0].role).toBe('system');
+    expect(messages[0].content).toContain('EN');
+    expect(messages[0].content).toContain('DE');
+    expect(messages[0].content).toContain('Mallorca');
+    expect(messages[1].role).toBe('user');
+    expect(messages[1].content).toContain('Our Events');
+    expect(messages[1].content).toContain('concerts and shows');
+  });
+
+  it('uses "none" when no string context', () => {
+    const messages = buildMessages({
+      sourceText: 'Book Now',
+      sourceLang: 'EN',
+      targetLang: 'DE',
+      projectContext: 'A travel site',
+      stringContext: null,
+    });
+    expect(messages[1].content.toLowerCase()).toContain('none');
+  });
+});
+
+describe('translate', () => {
+  it('calls OpenAI and returns translated text', async () => {
+    const mockCreate = vi.fn().mockResolvedValue({
+      choices: [{ message: { content: 'Unsere Veranstaltungen' } }],
+    });
+
+    const result = await translate({
+      sourceText: 'Our Events',
+      sourceLang: 'EN',
+      targetLang: 'DE',
+      projectContext: 'A travel site',
+      stringContext: null,
+      apiKey: 'test-key',
+      model: 'gpt-4.1-mini',
+      timeout: 10,
+      maxRetries: 2,
+      _clientOverride: { chat: { completions: { create: mockCreate } } } as any,
+    });
+    expect(result).toBe('Unsere Veranstaltungen');
+  });
+
+  it('strips whitespace from response', async () => {
+    const mockCreate = vi.fn().mockResolvedValue({
+      choices: [{ message: { content: '  Hallo  \n' } }],
+    });
+
+    const result = await translate({
+      sourceText: 'Hello',
+      sourceLang: 'EN',
+      targetLang: 'DE',
+      projectContext: 'test',
+      stringContext: null,
+      apiKey: 'test-key',
+      model: 'gpt-4.1-mini',
+      timeout: 10,
+      maxRetries: 2,
+      _clientOverride: { chat: { completions: { create: mockCreate } } } as any,
+    });
+    expect(result).toBe('Hallo');
+  });
+});
+
+describe('buildPluralMessages', () => {
+  it('builds plural system and user messages', () => {
+    const messages = buildPluralMessages({
+      one: '{count} message',
+      other: '{count} messages',
+      sourceLang: 'EN',
+      targetLang: 'DE',
+      projectContext: 'A messaging app',
+      stringContext: 'inbox count',
+    });
+    expect(messages).toHaveLength(2);
+    expect(messages[0].role).toBe('system');
+    expect(messages[0].content).toContain('EN');
+    expect(messages[0].content).toContain('DE');
+    expect(messages[0].content).toContain('CLDR plural');
+    expect(messages[0].content).toContain('A messaging app');
+    expect(messages[1].role).toBe('user');
+    expect(messages[1].content).toContain('{count} message');
+    expect(messages[1].content).toContain('{count} messages');
+    expect(messages[1].content).toContain('inbox count');
+  });
+
+  it('preserves placeholders in template (not interpreted as template vars)', () => {
+    const messages = buildPluralMessages({
+      one: '{count} item in {name}\'s cart',
+      other: '{count} items in {name}\'s cart',
+      sourceLang: 'EN',
+      targetLang: 'DE',
+      projectContext: 'E-commerce',
+      stringContext: null,
+    });
+    // The user message should contain the literal {count} and {name} placeholders
+    expect(messages[1].content).toContain('{count} item in {name}');
+    expect(messages[1].content).toContain('{count} items in {name}');
+    // System message should still mention {name} as an example placeholder
+    expect(messages[0].content).toContain('{name}');
+    expect(messages[0].content).toContain('{count}');
+  });
+
+  it('uses "none" for null string context', () => {
+    const messages = buildPluralMessages({
+      one: '{count} msg',
+      other: '{count} msgs',
+      sourceLang: 'EN',
+      targetLang: 'DE',
+      projectContext: 'test',
+      stringContext: null,
+    });
+    expect(messages[1].content).toContain('none');
+  });
+});
+
+describe('translatePlural', () => {
+  it('calls OpenAI and returns parsed JSON of plural forms', async () => {
+    const mockCreate = vi.fn().mockResolvedValue({
+      choices: [{ message: { content: '{"one": "{count} Nachricht", "other": "{count} Nachrichten"}' } }],
+    });
+
+    const result = await translatePlural({
+      one: '{count} message',
+      other: '{count} messages',
+      sourceLang: 'EN',
+      targetLang: 'DE',
+      projectContext: 'test',
+      stringContext: null,
+      apiKey: 'test-key',
+      model: 'gpt-4.1-mini',
+      timeout: 10,
+      maxRetries: 2,
+      _clientOverride: { chat: { completions: { create: mockCreate } } } as any,
+    });
+
+    expect(result).toEqual({
+      one: '{count} Nachricht',
+      other: '{count} Nachrichten',
+    });
+  });
+
+  it('returns multiple categories for Russian', async () => {
+    const mockCreate = vi.fn().mockResolvedValue({
+      choices: [{ message: { content: JSON.stringify({
+        one: '{count} сообщение',
+        few: '{count} сообщения',
+        many: '{count} сообщений',
+        other: '{count} сообщений',
+      }) } }],
+    });
+
+    const result = await translatePlural({
+      one: '{count} message',
+      other: '{count} messages',
+      sourceLang: 'EN',
+      targetLang: 'RU',
+      projectContext: 'test',
+      stringContext: null,
+      apiKey: 'test-key',
+      model: 'gpt-4.1-mini',
+      timeout: 10,
+      maxRetries: 2,
+      _clientOverride: { chat: { completions: { create: mockCreate } } } as any,
+    });
+
+    expect(result.one).toBe('{count} сообщение');
+    expect(result.few).toBe('{count} сообщения');
+    expect(result.many).toBe('{count} сообщений');
+    expect(result.other).toBe('{count} сообщений');
+  });
+});

package/tests/cli.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import { mkdtempSync } from 'fs';
+import { tmpdir } from 'os';
+import { createHash } from 'crypto';
+
+import { runInit, runStats, runTranslate, runTranslatePlural, runWarm } from '../src/cli.js';
+import { TranslationStore } from '../src/storage.js';
+
+function hash(text: string): string {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+function makeTmpDir(): string {
+  return mkdtempSync(join(tmpdir(), 'transduck-cli-test-'));
+}
+
+function writeConfig(dir: string): string {
+  const configPath = join(dir, 'transduck.yaml');
+  writeFileSync(configPath, `
+project:
+  name: test-project
+  context: "A test site"
+languages:
+  source: EN
+  targets:
+    - DE
+storage:
+  path: ./translations.duckdb
+backend:
+  api_key_env: OPENAI_API_KEY
+  model: gpt-4.1-mini
+  timeout_seconds: 10
+  max_retries: 2
+`);
+  return configPath;
+}
+
+describe('CLI functions', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+    process.env.OPENAI_API_KEY = 'test-key';
+  });
+
+  it('init creates config and db', async () => {
+    await runInit({
+      dir: tmpDir,
+      name: 'test-project',
+      context: 'A test site',
+      sourceLang: 'EN',
+      targetLangs: ['DE'],
+    });
+    const { existsSync } = await import('fs');
+    expect(existsSync(join(tmpDir, 'transduck.yaml'))).toBe(true);
+    expect(existsSync(join(tmpDir, 'translations.duckdb'))).toBe(true);
+  });
+
+  it('stats on empty db shows zero', async () => {
+    const configPath = writeConfig(tmpDir);
+    const output = await runStats({ configPath });
+    expect(output).toContain('0');
+  });
+
+  // --- translate with vars ---
+
+  it('translate returns cached with vars interpolated', async () => {
+    const configPath = writeConfig(tmpDir);
+    const dbPath = join(tmpDir, 'translations.duckdb');
+
+    // Pre-populate the DB
+    const store = new TranslationStore(dbPath);
+    await store.initialize();
+    await store.insert({
+      sourceText: 'Welcome {name}', sourceLang: 'EN', targetLang: 'DE',
+      projectContextHash: hash('A test site'), stringContextHash: hash(''),
+      translatedText: 'Willkommen {name}', model: 'gpt-4.1-mini', status: 'translated',
+    });
+    store.close();
+
+    const output = await runTranslate({
+      text: 'Welcome {name}', targetLang: 'DE',
+      configPath, vars: { name: 'Tim' },
+    });
+    expect(output).toBe('[cached] Willkommen Tim');
+  });
+
+  // --- translate-plural ---
+
+  it('translate-plural returns cached plural form', async () => {
+    const configPath = writeConfig(tmpDir);
+    const dbPath = join(tmpDir, 'translations.duckdb');
+
+    // Pre-populate the DB with plural forms
+    const store = new TranslationStore(dbPath);
+    await store.initialize();
+    const sourceKey = '{count} message\x00{count} messages';
+    const baseParams = {
+      sourceText: sourceKey, sourceLang: 'EN', targetLang: 'DE',
+      projectContextHash: hash('A test site'), stringContextHash: hash(''),
+    };
+    await store.insertPlural({
+      ...baseParams,
+      pluralCategory: 'one',
+      translatedText: '{count} Nachricht',
+      model: 'gpt-4.1-mini', status: 'translated',
+    });
+    await store.insertPlural({
+      ...baseParams,
+      pluralCategory: 'other',
+      translatedText: '{count} Nachrichten',
+      model: 'gpt-4.1-mini', status: 'translated',
+    });
+    store.close();
+
+    const output1 = await runTranslatePlural({
+      one: '{count} message', other: '{count} messages',
+      count: 1, targetLang: 'DE', configPath,
+    });
+    expect(output1).toBe('[cached] 1 Nachricht');
+
+    const output5 = await runTranslatePlural({
+      one: '{count} message', other: '{count} messages',
+      count: 5, targetLang: 'DE', configPath,
+    });
+    expect(output5).toBe('[cached] 5 Nachrichten');
+  });
+
+  // --- warm with plural entries ---
+
+  it('warm handles plural entries', async () => {
+    const configPath = writeConfig(tmpDir);
+    const dbPath = join(tmpDir, 'translations.duckdb');
+
+    // Pre-populate some plural forms so warm skips them
+    const store = new TranslationStore(dbPath);
+    await store.initialize();
+    const sourceKey = '{count} message\x00{count} messages';
+    await store.insertPlural({
+      sourceText: sourceKey, sourceLang: 'EN', targetLang: 'DE',
+      projectContextHash: hash('A test site'), stringContextHash: hash(''),
+      pluralCategory: 'one',
+      translatedText: '{count} Nachricht',
+      model: 'gpt-4.1-mini', status: 'translated',
+    });
+    store.close();
+
+    // Write warm input with both regular and plural entries
+    const warmFile = join(tmpDir, 'warm.json');
+    writeFileSync(warmFile, JSON.stringify([
+      { plural: true, one: '{count} message', other: '{count} messages' },
+    ]));
+
+    const output = await runWarm({
+      filePath: warmFile, langs: ['DE'], configPath,
+    });
+    // Since plural forms already exist, should be skipped
+    expect(output).toContain('Skipped: 1');
+  });
+});

package/tests/config.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { loadConfig, type TransduckConfig } from '../src/config.js';
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { mkdtempSync } from 'fs';
+import { tmpdir } from 'os';
+
+function makeTmpDir(): string {
+  return mkdtempSync(join(tmpdir(), 'transduck-test-'));
+}
+
+const VALID_YAML = `
+project:
+  name: test-project
+  context: "A test travel site"
+languages:
+  source: EN
+  targets:
+    - DE
+    - ES
+storage:
+  path: ./translations.duckdb
+backend:
+  api_key_env: OPENAI_API_KEY
+  model: gpt-4.1-mini
+  timeout_seconds: 10
+  max_retries: 2
+`;
+
+describe('loadConfig', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+  });
+
+  it('loads config from explicit path', () => {
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, VALID_YAML);
+    const cfg = loadConfig(configPath);
+    expect(cfg.projectName).toBe('test-project');
+    expect(cfg.projectContext).toBe('A test travel site');
+    expect(cfg.sourceLang).toBe('EN');
+    expect(cfg.targetLangs).toEqual(['DE', 'ES']);
+    expect(cfg.backendModel).toBe('gpt-4.1-mini');
+    expect(cfg.backendTimeout).toBe(10);
+    expect(cfg.backendMaxRetries).toBe(2);
+    expect(cfg.apiKeyEnv).toBe('OPENAI_API_KEY');
+  });
+
+  it('normalizes language codes to uppercase', () => {
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, VALID_YAML.replace('EN', 'en').replace('DE', 'de').replace('ES', 'es'));
+    const cfg = loadConfig(configPath);
+    expect(cfg.sourceLang).toBe('EN');
+    expect(cfg.targetLangs).toEqual(['DE', 'ES']);
+  });
+
+  it('resolves storage path relative to config file', () => {
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, VALID_YAML);
+    const cfg = loadConfig(configPath);
+    expect(cfg.storagePath).toBe(join(tmpDir, 'translations.duckdb'));
+  });
+
+  it('discovers config from TRANSDUCK_CONFIG env var', () => {
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, VALID_YAML);
+    process.env.TRANSDUCK_CONFIG = configPath;
+    const cfg = loadConfig();
+    expect(cfg.projectName).toBe('test-project');
+    delete process.env.TRANSDUCK_CONFIG;
+  });
+
+  it('throws if config not found', () => {
+    delete process.env.TRANSDUCK_CONFIG;
+    expect(() => loadConfig(join(tmpDir, 'nonexistent.yaml'))).toThrow();
+  });
+});