i18nsmith 0.1.0

package/src/integration.test.ts

@@ -0,0 +1,438 @@
+/**
+ * Integration tests for CLI commands
+ * These tests run the actual CLI commands against real file systems
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Get the correct CLI path regardless of where tests are run from
+const CLI_PATH = path.resolve(__dirname, '../dist/index.js');
+
+// Helper to run CLI commands
+function runCli(
+  args: string[],
+  options: { cwd?: string } = {}
+): { stdout: string; stderr: string; output: string; exitCode: number } {
+  const result = spawnSync('node', [CLI_PATH, ...args], {
+    cwd: options.cwd ?? process.cwd(),
+    encoding: 'utf8',
+    timeout: 30000,
+    env: {
+      ...process.env,
+      CI: 'true',
+      NO_COLOR: '1',
+      FORCE_COLOR: '0',
+    },
+  });
+
+  const stdout = result.stdout ?? '';
+  const stderr = result.stderr ?? '';
+
+  return {
+    stdout,
+    stderr,
+    output: stdout + stderr,
+    exitCode: result.status ?? 1,
+  };
+}
+
+// Helper to extract JSON from CLI output (may contain log messages before JSON)
+function extractJson<T>(output: string): T {
+  const jsonMatch = output.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) {
+    throw new Error(`No JSON found in output: ${output.slice(0, 200)}...`);
+  }
+  return JSON.parse(jsonMatch[0]);
+}
+
+describe('CLI Integration Tests', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'i18nsmith-cli-integration-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('preflight command', () => {
+    it('should fail when no config file exists', async () => {
+      const result = runCli(['preflight'], { cwd: tmpDir });
+
+      expect(result.exitCode).toBe(1);
+      expect(result.output).toContain('Config File');
+    });
+
+    it('should pass with valid config and locales', async () => {
+      const config = {
+        sourceLanguage: 'en',
+        targetLanguages: ['fr'],
+        localesDir: 'locales',
+        include: ['src/**/*.tsx'],
+      };
+      await fs.writeFile(path.join(tmpDir, 'i18n.config.json'), JSON.stringify(config, null, 2));
+      await fs.mkdir(path.join(tmpDir, 'locales'));
+      await fs.writeFile(path.join(tmpDir, 'locales', 'en.json'), '{}');
+      await fs.mkdir(path.join(tmpDir, 'src'));
+      await fs.writeFile(path.join(tmpDir, 'src', 'App.tsx'), 'export function App() { return <div>Hello</div>; }');
+
+      const result = runCli(['preflight'], { cwd: tmpDir });
+
+      expect(result.output).toContain('Config File');
+      expect(result.output).toContain('pass');
+    });
+
+    it('should output JSON when --json flag is used', async () => {
+      const config = {
+        sourceLanguage: 'en',
+        targetLanguages: ['fr'],
+        localesDir: 'locales',
+        include: ['src/**/*.tsx'],
+      };
+      await fs.writeFile(path.join(tmpDir, 'i18n.config.json'), JSON.stringify(config, null, 2));
+      await fs.mkdir(path.join(tmpDir, 'locales'));
+      await fs.writeFile(path.join(tmpDir, 'locales', 'en.json'), '{}');
+      await fs.mkdir(path.join(tmpDir, 'src'));
+      await fs.writeFile(path.join(tmpDir, 'src', 'App.tsx'), 'export function App() {}');
+
+      const result = runCli(['preflight', '--json'], { cwd: tmpDir });
+
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed).toHaveProperty('passed');
+      expect(parsed).toHaveProperty('checks');
+      expect(Array.isArray(parsed.checks)).toBe(true);
+    });
+
+    it('should create missing directories with --fix', async () => {
+      const config = {
+        sourceLanguage: 'en',
+        targetLanguages: ['fr'],
+        localesDir: 'i18n/locales',
+        include: ['src/**/*.tsx'],
+      };
+      await fs.writeFile(path.join(tmpDir, 'i18n.config.json'), JSON.stringify(config, null, 2));
+      await fs.mkdir(path.join(tmpDir, 'src'));
+      await fs.writeFile(path.join(tmpDir, 'src', 'App.tsx'), 'export function App() {}');
+
+      runCli(['preflight', '--fix'], { cwd: tmpDir });
+
+      const localesDirExists = await fs.access(path.join(tmpDir, 'i18n', 'locales'))
+        .then(() => true)
+        .catch(() => false);
+      
+      expect(localesDirExists).toBe(true);
+    });
+  });
+
+  describe('scan command', () => {
+    beforeEach(async () => {
+      const config = {
+        sourceLanguage: 'en',
+        targetLanguages: ['fr', 'de'],
+        localesDir: 'locales',
+        include: ['src/**/*.tsx'],
+      };
+      await fs.writeFile(path.join(tmpDir, 'i18n.config.json'), JSON.stringify(config, null, 2));
+      await fs.mkdir(path.join(tmpDir, 'locales'));
+      await fs.writeFile(path.join(tmpDir, 'locales', 'en.json'), '{}');
+      await fs.mkdir(path.join(tmpDir, 'src'), { recursive: true });
+    });
+
+    it('should scan and find translatable strings', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `
+import React from 'react';
+
+export function App() {
+  return (
+    <div>
+      <h1>Welcome to our app</h1>
+      <p>This is a description</p>
+    </div>
+  );
+}
+`
+      );
+
+      const result = runCli(['scan'], { cwd: tmpDir });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.output).toContain('Scanned');
+    });
+
+    it('should output JSON when --json flag is used', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `export function App() { return <div>Hello</div>; }`
+      );
+
+      const result = runCli(['scan', '--json'], { cwd: tmpDir });
+      const parsed = extractJson<{ filesScanned: number; candidates: unknown[] }>(result.stdout);
+
+      expect(parsed).toHaveProperty('filesScanned');
+      expect(parsed).toHaveProperty('candidates');
+    });
+  });
+
+  describe('sync command', () => {
+    beforeEach(async () => {
+      const config = {
+        sourceLanguage: 'en',
+        targetLanguages: ['fr'],
+        localesDir: 'locales',
+        include: ['src/**/*.tsx'],
+      };
+      await fs.writeFile(path.join(tmpDir, 'i18n.config.json'), JSON.stringify(config, null, 2));
+      await fs.mkdir(path.join(tmpDir, 'locales'));
+      await fs.writeFile(
+        path.join(tmpDir, 'locales', 'en.json'),
+        JSON.stringify({ 'existing.key': 'Existing Value' }, null, 2)
+      );
+      await fs.writeFile(
+        path.join(tmpDir, 'locales', 'fr.json'),
+        JSON.stringify({ 'existing.key': 'Valeur existante' }, null, 2)
+      );
+      await fs.mkdir(path.join(tmpDir, 'src'), { recursive: true });
+    });
+
+    it('should run dry-run by default', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `
+import { useTranslation } from 'react-i18next';
+
+export function App() {
+  const { t } = useTranslation();
+  return <div>{t('new.key')}</div>;
+}
+`
+      );
+
+      const result = runCli(['sync'], { cwd: tmpDir });
+
+      expect(result.output).toContain('DRY RUN');
+    });
+
+    it('should add missing keys with --write', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `
+import { useTranslation } from 'react-i18next';
+
+export function App() {
+  const { t } = useTranslation();
+  return <div>{t('new.key')}</div>;
+}
+`
+      );
+
+      const result = runCli(['sync', '--write', '-y'], { cwd: tmpDir });
+      expect(result.exitCode).toBe(0);
+
+      const enContent = await fs.readFile(path.join(tmpDir, 'locales', 'en.json'), 'utf8');
+      const enData = JSON.parse(enContent);
+      expect(enData).toHaveProperty('new.key');
+    });
+
+    it('should not prune by default even with --write', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `export function App() { return <div>Hello</div>; }`
+      );
+
+      runCli(['sync', '--write', '-y'], { cwd: tmpDir });
+
+      const enContent = await fs.readFile(path.join(tmpDir, 'locales', 'en.json'), 'utf8');
+      const enData = JSON.parse(enContent);
+      expect(enData).toHaveProperty('existing.key');
+    });
+
+    it('should prune unused keys with --write --prune', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `export function App() { return <div>Hello</div>; }`
+      );
+
+      runCli(['sync', '--write', '--prune', '-y'], { cwd: tmpDir });
+
+      const enContent = await fs.readFile(path.join(tmpDir, 'locales', 'en.json'), 'utf8');
+      const enData = JSON.parse(enContent);
+      expect(enData).not.toHaveProperty('existing.key');
+    });
+
+    it('should create backup when pruning', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `export function App() { return <div>Hello</div>; }`
+      );
+
+      runCli(['sync', '--write', '--prune', '-y'], { cwd: tmpDir });
+
+      const backupDir = path.join(tmpDir, '.i18nsmith-backup');
+      const backupExists = await fs.access(backupDir).then(() => true).catch(() => false);
+      expect(backupExists).toBe(true);
+    });
+
+    it('should skip backup with --no-backup', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `export function App() { return <div>Hello</div>; }`
+      );
+
+      runCli(['sync', '--write', '--prune', '-y', '--no-backup'], { cwd: tmpDir });
+
+      const backupDir = path.join(tmpDir, '.i18nsmith-backup');
+      const backupExists = await fs.access(backupDir).then(() => true).catch(() => false);
+      expect(backupExists).toBe(false);
+    });
+  });
+
+  describe('backup commands', () => {
+    beforeEach(async () => {
+      const config = {
+        sourceLanguage: 'en',
+        targetLanguages: ['fr'],
+        localesDir: 'locales',
+        include: ['src/**/*.tsx'],
+      };
+      await fs.writeFile(path.join(tmpDir, 'i18n.config.json'), JSON.stringify(config, null, 2));
+      await fs.mkdir(path.join(tmpDir, 'locales'));
+      await fs.writeFile(
+        path.join(tmpDir, 'locales', 'en.json'),
+        JSON.stringify({ 'original.key': 'Original' }, null, 2)
+      );
+      await fs.mkdir(path.join(tmpDir, 'src'));
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `export function App() { return <div>Hello</div>; }`
+      );
+    });
+
+    it('should list no backups when none exist', async () => {
+      const result = runCli(['backup-list'], { cwd: tmpDir });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.output).toContain('No backups found');
+    });
+
+    it('should list backups after sync creates one', async () => {
+      runCli(['sync', '--write', '--prune', '-y'], { cwd: tmpDir });
+
+      const result = runCli(['backup-list'], { cwd: tmpDir });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.output).toContain('Found');
+      expect(result.output).toContain('backup');
+    });
+  });
+
+  describe('transform command', () => {
+    beforeEach(async () => {
+      const config = {
+        sourceLanguage: 'en',
+        targetLanguages: ['fr'],
+        localesDir: 'locales',
+        include: ['src/**/*.tsx'],
+        translationAdapter: {
+          module: 'react-i18next',
+          hookName: 'useTranslation',
+          translationIdentifier: 't',
+        },
+      };
+      await fs.writeFile(path.join(tmpDir, 'i18n.config.json'), JSON.stringify(config, null, 2));
+      await fs.mkdir(path.join(tmpDir, 'locales'));
+      await fs.writeFile(path.join(tmpDir, 'locales', 'en.json'), '{}');
+      await fs.mkdir(path.join(tmpDir, 'src'));
+    });
+
+    it('should run dry-run by default', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `export function App() { return <div>Hello World</div>; }`
+      );
+
+      const result = runCli(['transform'], { cwd: tmpDir });
+
+      expect(result.output).toContain('DRY RUN');
+    });
+
+    it('should output JSON with --json flag', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `export function App() { return <div>Hello</div>; }`
+      );
+
+      const result = runCli(['transform', '--json'], { cwd: tmpDir });
+      const parsed = extractJson<{ filesScanned: number; candidates: unknown[] }>(result.stdout);
+
+      expect(parsed).toHaveProperty('filesScanned');
+      expect(parsed).toHaveProperty('candidates');
+      expect(Array.isArray(parsed.candidates)).toBe(true);
+    });
+  });
+
+  describe('check command', () => {
+    beforeEach(async () => {
+      const config = {
+        sourceLanguage: 'en',
+        targetLanguages: ['fr'],
+        localesDir: 'locales',
+        include: ['src/**/*.tsx'],
+      };
+      await fs.writeFile(path.join(tmpDir, 'i18n.config.json'), JSON.stringify(config, null, 2));
+      await fs.mkdir(path.join(tmpDir, 'locales'));
+      await fs.writeFile(path.join(tmpDir, 'locales', 'en.json'), JSON.stringify({ 'hello': 'Hello' }, null, 2));
+      await fs.writeFile(path.join(tmpDir, 'locales', 'fr.json'), JSON.stringify({ 'hello': 'Bonjour' }, null, 2));
+      await fs.mkdir(path.join(tmpDir, 'src'));
+    });
+
+    it('should run health check successfully', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `
+import { useTranslation } from 'react-i18next';
+
+export function App() {
+  const { t } = useTranslation();
+  return <div>{t('hello')}</div>;
+}
+`
+      );
+
+      const result = runCli(['check'], { cwd: tmpDir });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.output).toContain('Locales directory');
+    });
+
+    it('should output JSON with --json flag', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'src', 'App.tsx'),
+        `
+import { useTranslation } from 'react-i18next';
+
+export function App() {
+  const { t } = useTranslation();
+  return <div>{t('hello')}</div>;
+}
+`
+      );
+
+      const result = runCli(['check', '--json'], { cwd: tmpDir });
+      const parsed = extractJson<{ diagnostics: unknown; sync: unknown }>(result.stdout);
+
+      expect(parsed).toHaveProperty('diagnostics');
+      expect(parsed).toHaveProperty('sync');
+    });
+  });
+});

package/src/utils/diagnostics-exit.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import type { DiagnoseConflict } from '@i18nsmith/core';
+import { selectExitSignal } from './diagnostics-exit';
+import { DIAGNOSTICS_EXIT_CODES, DIAGNOSTICS_EXIT_DESCRIPTIONS } from './exit-codes';
+
+describe('selectExitSignal', () => {
+  it('returns null when there are no conflicts', () => {
+    expect(selectExitSignal([])).toBeNull();
+  });
+
+  it('returns the mapped exit code for missing source locale conflicts', () => {
+    const conflicts: DiagnoseConflict[] = [
+      { kind: 'missing-source-locale', message: 'Source locale missing' },
+    ];
+
+    const result = selectExitSignal(conflicts);
+    expect(result).toEqual({
+      code: DIAGNOSTICS_EXIT_CODES.MISSING_SOURCE_LOCALE,
+      reason: DIAGNOSTICS_EXIT_DESCRIPTIONS[DIAGNOSTICS_EXIT_CODES.MISSING_SOURCE_LOCALE],
+    });
+  });
+
+  it('prefers higher severity codes when multiple conflicts exist', () => {
+    const conflicts: DiagnoseConflict[] = [
+      { kind: 'missing-source-locale', message: 'Source missing' },
+      { kind: 'invalid-locale-json', message: 'Invalid JSON detected' },
+    ];
+
+    const result = selectExitSignal(conflicts);
+    expect(result).toEqual({
+      code: DIAGNOSTICS_EXIT_CODES.INVALID_LOCALE_JSON,
+      reason: DIAGNOSTICS_EXIT_DESCRIPTIONS[DIAGNOSTICS_EXIT_CODES.INVALID_LOCALE_JSON],
+    });
+  });
+
+  it('falls back to a general conflict exit code for unknown kinds', () => {
+    const conflicts: DiagnoseConflict[] = [
+      { kind: 'custom-conflict', message: 'Something unexpected happened' },
+    ];
+
+    const result = selectExitSignal(conflicts);
+    expect(result).toEqual({
+      code: DIAGNOSTICS_EXIT_CODES.GENERAL_CONFLICT,
+      reason: 'Something unexpected happened',
+    });
+  });
+});

package/src/utils/diagnostics-exit.ts

@@ -0,0 +1,63 @@
+import type { DiagnoseConflict, DiagnosisReport } from '@i18nsmith/core';
+import { DIAGNOSTICS_EXIT_CODES, DIAGNOSTICS_EXIT_DESCRIPTIONS } from './exit-codes.js';
+
+export interface DiagnosisExitSignal {
+  code: number;
+  reason: string;
+}
+
+const CONFLICT_EXIT_SIGNALS: Record<string, DiagnosisExitSignal> = {
+  'missing-source-locale': {
+    code: DIAGNOSTICS_EXIT_CODES.MISSING_SOURCE_LOCALE,
+    reason: DIAGNOSTICS_EXIT_DESCRIPTIONS[DIAGNOSTICS_EXIT_CODES.MISSING_SOURCE_LOCALE],
+  },
+  'invalid-locale-json': {
+    code: DIAGNOSTICS_EXIT_CODES.INVALID_LOCALE_JSON,
+    reason: DIAGNOSTICS_EXIT_DESCRIPTIONS[DIAGNOSTICS_EXIT_CODES.INVALID_LOCALE_JSON],
+  },
+  'unsafe-provider-clash': {
+    code: DIAGNOSTICS_EXIT_CODES.UNSAFE_PROVIDER_CLASH,
+    reason: DIAGNOSTICS_EXIT_DESCRIPTIONS[DIAGNOSTICS_EXIT_CODES.UNSAFE_PROVIDER_CLASH],
+  },
+};
+
+export function getDiagnosisExitSignal(report: Pick<DiagnosisReport, 'conflicts'>): DiagnosisExitSignal | null {
+  return selectExitSignal(report.conflicts);
+}
+
+export function selectExitSignal(conflicts: DiagnoseConflict[]): DiagnosisExitSignal | null {
+  if (!conflicts.length) {
+    return null;
+  }
+
+  let chosen: DiagnosisExitSignal | null = null;
+
+  for (const conflict of conflicts) {
+    const knownSignal = CONFLICT_EXIT_SIGNALS[conflict.kind];
+    if (knownSignal) {
+      if (!chosen || knownSignal.code > chosen.code) {
+        chosen = knownSignal;
+      }
+      continue;
+    }
+
+    const fallbackSignal: DiagnosisExitSignal = {
+      code: DIAGNOSTICS_EXIT_CODES.GENERAL_CONFLICT,
+      reason: conflict.message,
+    };
+
+    if (!chosen || fallbackSignal.code > chosen.code) {
+      chosen = fallbackSignal;
+    }
+  }
+
+  return chosen;
+}
+
+export function describeDiagnosisExitCodes(): Array<{ code: number; reason: string }> {
+  const entries = Object.values(CONFLICT_EXIT_SIGNALS).sort((a, b) => a.code - b.code);
+  return entries.concat({
+    code: DIAGNOSTICS_EXIT_CODES.GENERAL_CONFLICT,
+    reason: DIAGNOSTICS_EXIT_DESCRIPTIONS[DIAGNOSTICS_EXIT_CODES.GENERAL_CONFLICT],
+  });
+}

package/src/utils/diff-utils.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi } from 'vitest';
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { writeLocaleDiffPatches, printLocaleDiffs } from './diff-utils';
+
+describe('diff-utils', () => {
+  it('writes patch files for provided diffs', async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'i18nsmith-test-'));
+    const diffs = [
+      { locale: 'en', path: '/locales/en.json', diff: '--- a\n+++ b\n+"hello": "Hello"', added: ['hello'], updated: [], removed: [] },
+      { locale: 'fr', path: '/locales/fr.json', diff: '--- a\n+++ b\n+"hello": "Bonjour"', added: ['hello'], updated: [], removed: [] },
+    ];
+
+    await writeLocaleDiffPatches(diffs as any, tmp);
+
+    const files = await fs.readdir(tmp);
+    expect(files.length).toBe(2);
+
+    const enContent = await fs.readFile(path.join(tmp, 'en.patch'), 'utf8');
+    expect(enContent).toContain('Hello');
+
+    // cleanup
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it('prints diffs without throwing', () => {
+    const diffs = [
+      { locale: 'en', path: '/locales/en.json', diff: '--- a\n+++ b\n+"hello": "Hello"', added: [], updated: [], removed: [] },
+    ];
+
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    expect(() => printLocaleDiffs(diffs as any)).not.toThrow();
+    spy.mockRestore();
+  });
+});

package/src/utils/diff-utils.ts

@@ -0,0 +1,42 @@
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import type { SyncSummary } from '@i18nsmith/core';
+
+export function printLocaleDiffs(diffs: SyncSummary['diffs']) {
+  if (!diffs.length) {
+    console.log(chalk.gray('No locale diffs to display.'));
+    return;
+  }
+
+  console.log(chalk.blue('\nUnified locale diffs:'));
+  diffs.forEach((entry) => {
+    console.log(chalk.yellow(`\n--- ${entry.locale} (${entry.path})`));
+    console.log(entry.diff.trimEnd());
+  });
+}
+
+export async function writeLocaleDiffPatches(diffs: SyncSummary['diffs'], directory: string) {
+  if (!diffs.length) {
+    console.log(chalk.gray('No locale diffs to write.'));
+    return;
+  }
+
+  const targetDir = path.isAbsolute(directory) ? directory : path.resolve(process.cwd(), directory);
+  await fs.mkdir(targetDir, { recursive: true });
+
+  await Promise.all(
+    diffs.map((entry) => {
+      const safeLocale = entry.locale.replace(/[^a-z0-9_-]/gi, '-');
+      const fileName = `${safeLocale || 'locale'}.patch`;
+      const filePath = path.join(targetDir, fileName);
+      return fs.writeFile(filePath, `${entry.diff.trimEnd()}\n`, 'utf8');
+    })
+  );
+
+  console.log(
+    chalk.green(
+      `Wrote ${diffs.length} locale patch file${diffs.length === 1 ? '' : 's'} to ${targetDir}.`
+    )
+  );
+}