i18nsmith 0.1.0

package/src/utils/exit-codes.ts

@@ -0,0 +1,201 @@
+/**
+ * Exit Code Reference for i18nsmith CLI
+ *
+ * This module centralizes all exit codes used by the CLI for consistent
+ * behavior across commands and improved CI/CD integration.
+ *
+ * ## Exit Code Ranges
+ *
+ * | Range  | Category              | Description                           |
+ * |--------|-----------------------|---------------------------------------|
+ * | 0      | Success               | Command completed successfully        |
+ * | 1      | General Error         | Unspecified error or crash            |
+ * | 2-5    | Diagnostics           | Workspace diagnostic conflicts        |
+ * | 10-19  | Check Command         | Health check warnings/conflicts       |
+ * | 1-4    | Sync Command          | Sync drift/validation issues          |
+ *
+ * Note: Sync exit codes overlap with diagnostics for backward compatibility.
+ * Use `--prefer-diagnostics-exit` in `check` command to disambiguate.
+ *
+ * ## Usage in CI/CD
+ *
+ * ```bash
+ * # Basic CI check
+ * npx i18nsmith check --fail-on conflicts
+ * if [ $? -eq 11 ]; then
+ *   echo "Blocking conflicts found"
+ * fi
+ *
+ * # Strict sync check
+ * npx i18nsmith sync --check --strict
+ * case $? in
+ *   0) echo "All clear" ;;
+ *   1) echo "Locale drift detected" ;;
+ *   2) echo "Placeholder mismatch" ;;
+ *   4) echo "Suspicious keys found" ;;
+ * esac
+ * ```
+ */
+
+/**
+ * Exit codes for the `sync` command.
+ *
+ * Used when running `i18nsmith sync --check` or `--strict` mode.
+ */
+export const SYNC_EXIT_CODES = {
+  /** Locale drift detected (missing or unused keys) */
+  DRIFT: 1,
+  /** Placeholder/interpolation mismatch between locales */
+  PLACEHOLDER_MISMATCH: 2,
+  /** Empty or placeholder values in locale files */
+  EMPTY_VALUES: 3,
+  /** Suspicious key patterns detected (e.g., key=value, raw text keys) */
+  SUSPICIOUS_KEYS: 4,
+} as const;
+
+/**
+ * Exit codes for the `check` command.
+ *
+ * Used when running `i18nsmith check --fail-on <level>`.
+ */
+export const CHECK_EXIT_CODES = {
+  /** Warnings detected (when --fail-on warnings) */
+  WARNINGS: 10,
+  /** Blocking conflicts detected (when --fail-on conflicts) */
+  CONFLICTS: 11,
+} as const;
+
+/**
+ * Exit codes for the `diagnose` command and diagnostic conflicts.
+ *
+ * These are also used by `check` when `--prefer-diagnostics-exit` is set.
+ */
+export const DIAGNOSTICS_EXIT_CODES = {
+  /** Missing source locale file */
+  MISSING_SOURCE_LOCALE: 2,
+  /** Invalid JSON in locale file */
+  INVALID_LOCALE_JSON: 3,
+  /** Provider/adapter clash detected */
+  UNSAFE_PROVIDER_CLASH: 4,
+  /** General diagnostics conflict (fallback) */
+  GENERAL_CONFLICT: 5,
+} as const;
+
+/**
+ * General exit codes used across all commands.
+ */
+export const GENERAL_EXIT_CODES = {
+  /** Success - no issues found */
+  SUCCESS: 0,
+  /** General error (catch-all for exceptions) */
+  ERROR: 1,
+} as const;
+
+/**
+ * Type for all sync exit codes
+ */
+export type SyncExitCode = (typeof SYNC_EXIT_CODES)[keyof typeof SYNC_EXIT_CODES];
+
+/**
+ * Type for all check exit codes
+ */
+export type CheckExitCode = (typeof CHECK_EXIT_CODES)[keyof typeof CHECK_EXIT_CODES];
+
+/**
+ * Type for all diagnostics exit codes
+ */
+export type DiagnosticsExitCode = (typeof DIAGNOSTICS_EXIT_CODES)[keyof typeof DIAGNOSTICS_EXIT_CODES];
+
+/**
+ * Human-readable descriptions for sync exit codes.
+ */
+export const SYNC_EXIT_DESCRIPTIONS: Record<number, string> = {
+  [SYNC_EXIT_CODES.DRIFT]: 'Locale drift detected (missing or unused keys)',
+  [SYNC_EXIT_CODES.PLACEHOLDER_MISMATCH]: 'Placeholder mismatch between locales',
+  [SYNC_EXIT_CODES.EMPTY_VALUES]: 'Empty or placeholder values in locale files',
+  [SYNC_EXIT_CODES.SUSPICIOUS_KEYS]: 'Suspicious key patterns detected',
+};
+
+/**
+ * Human-readable descriptions for check exit codes.
+ */
+export const CHECK_EXIT_DESCRIPTIONS: Record<number, string> = {
+  [CHECK_EXIT_CODES.WARNINGS]: 'Warnings detected',
+  [CHECK_EXIT_CODES.CONFLICTS]: 'Blocking conflicts detected',
+};
+
+/**
+ * Human-readable descriptions for diagnostics exit codes.
+ */
+export const DIAGNOSTICS_EXIT_DESCRIPTIONS: Record<number, string> = {
+  [DIAGNOSTICS_EXIT_CODES.MISSING_SOURCE_LOCALE]: 'Missing source locale file',
+  [DIAGNOSTICS_EXIT_CODES.INVALID_LOCALE_JSON]: 'Invalid JSON in locale file',
+  [DIAGNOSTICS_EXIT_CODES.UNSAFE_PROVIDER_CLASH]: 'Provider/adapter clash detected',
+  [DIAGNOSTICS_EXIT_CODES.GENERAL_CONFLICT]: 'General diagnostics conflict',
+};
+
+/**
+ * All exit code descriptions by command context.
+ */
+export const EXIT_CODE_DESCRIPTIONS = {
+  general: {
+    [GENERAL_EXIT_CODES.SUCCESS]: 'Success - no issues found',
+    [GENERAL_EXIT_CODES.ERROR]: 'General error',
+  },
+  sync: SYNC_EXIT_DESCRIPTIONS,
+  check: CHECK_EXIT_DESCRIPTIONS,
+  diagnostics: DIAGNOSTICS_EXIT_DESCRIPTIONS,
+} as const;
+
+/**
+ * Get a human-readable description for an exit code.
+ *
+ * @param code - The exit code
+ * @param context - Optional context to disambiguate overlapping codes
+ * @returns Description string, or 'Unknown exit code' if not recognized
+ */
+export function getExitCodeDescription(
+  code: number,
+  context?: 'sync' | 'check' | 'diagnostics'
+): string {
+  // Check context-specific first
+  if (context) {
+    const contextMap = EXIT_CODE_DESCRIPTIONS[context];
+    if (contextMap[code]) {
+      return contextMap[code];
+    }
+  }
+
+  // Try general codes
+  if (code in EXIT_CODE_DESCRIPTIONS.general) {
+    return EXIT_CODE_DESCRIPTIONS.general[code as keyof typeof EXIT_CODE_DESCRIPTIONS.general];
+  }
+
+  // Search all contexts
+  for (const ctxMap of [SYNC_EXIT_DESCRIPTIONS, CHECK_EXIT_DESCRIPTIONS, DIAGNOSTICS_EXIT_DESCRIPTIONS]) {
+    if (ctxMap[code]) {
+      return ctxMap[code];
+    }
+  }
+
+  return `Unknown exit code: ${code}`;
+}
+
+/**
+ * Helper to set process exit code with optional logging.
+ *
+ * @param code - The exit code to set
+ * @param options - Optional configuration
+ */
+export function setExitCode(
+  code: number,
+  options?: { silent?: boolean }
+): void {
+  process.exitCode = code;
+  if (!options?.silent && code !== 0) {
+    // Only log in development/debug mode
+    if (process.env.DEBUG?.includes('i18nsmith')) {
+      console.error(`[i18nsmith] Exit code ${code}: ${getExitCodeDescription(code)}`);
+    }
+  }
+}

package/src/utils/package-manager.ts

@@ -0,0 +1,44 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { spawn } from 'child_process';
+
+export type PackageManager = 'pnpm' | 'yarn' | 'npm';
+
+export async function detectPackageManager(workspaceRoot = process.cwd()): Promise<PackageManager> {
+  if (await fileExists(path.join(workspaceRoot, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+  if (await fileExists(path.join(workspaceRoot, 'yarn.lock'))) {
+    return 'yarn';
+  }
+  return 'npm';
+}
+
+export async function installDependencies(manager: PackageManager, deps: string[], workspaceRoot = process.cwd()) {
+  const args = manager === 'npm' ? ['install', ...deps] : ['add', ...deps];
+
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(manager, args, {
+      cwd: workspaceRoot,
+      stdio: 'inherit',
+    });
+
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`${manager} exited with code ${code}`));
+      }
+    });
+  });
+}
+
+async function fileExists(target: string) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/pkg.ts

@@ -0,0 +1,23 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+
+export async function readPackageJson(cwd?: string) {
+  const pkgPath = path.join(cwd ?? process.cwd(), 'package.json');
+  try {
+    const content = await fs.readFile(pkgPath, 'utf8');
+    return JSON.parse(content) as Record<string, unknown>;
+  } catch (error: unknown) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return undefined;
+    }
+    console.warn('Unable to read package.json for dependency checks.');
+    return undefined;
+  }
+}
+
+export function hasDependency(pkg: Record<string, unknown> | undefined, dep: string) {
+  if (!pkg) return false;
+  const deps = pkg.dependencies as Record<string, unknown> | undefined;
+  const devDeps = pkg.devDependencies as Record<string, unknown> | undefined;
+  return Boolean(deps?.[dep] || devDeps?.[dep]);
+}

package/src/utils/provider-injector.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+import { maybeInjectProvider } from './provider-injector.js';
+
+const providerComponentPath = 'src/components/i18n-provider.tsx';
+const providerTemplate = `'use client';
+
+export default function Providers({ children }: { children: React.ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>;
+}
+`;
+
+describe('provider injector', () => {
+  let workspaceRoot: string;
+  let cwdSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(async () => {
+    workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'i18nsmith-inject-'));
+    cwdSpy = vi.spyOn(process, 'cwd').mockReturnValue(workspaceRoot);
+    await fs.mkdir(path.join(workspaceRoot, 'app'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    cwdSpy.mockRestore();
+    await fs.rm(workspaceRoot, { recursive: true, force: true });
+  });
+
+  it('injects the provider when children expression exists', async () => {
+    const providerFile = path.join(workspaceRoot, 'app/providers.tsx');
+    await fs.writeFile(providerFile, providerTemplate, 'utf8');
+
+    const result = await maybeInjectProvider({ providerComponentPath });
+    expect(result.status).toBe('injected');
+    if (result.status !== 'injected') return;
+
+    const contents = await fs.readFile(providerFile, 'utf8');
+  expect(contents).toMatch(/import \{ I18nProvider \} from ['"].+i18n-provider['"];?/);
+    expect(contents).toContain('<I18nProvider>{children}</I18nProvider>');
+  });
+
+  it('previews changes without touching files when dryRun is true', async () => {
+    const providerFile = path.join(workspaceRoot, 'app/providers.tsx');
+    await fs.writeFile(providerFile, providerTemplate, 'utf8');
+
+    const result = await maybeInjectProvider({ providerComponentPath, dryRun: true });
+    expect(result.status).toBe('preview');
+    if (result.status !== 'preview') return;
+    expect(result.diff).toContain('I18nProvider');
+
+    const contents = await fs.readFile(providerFile, 'utf8');
+    expect(contents).toBe(providerTemplate);
+  });
+
+  it('fails gracefully when multiple children expressions exist', async () => {
+    const providerFile = path.join(workspaceRoot, 'app/providers.tsx');
+    await fs.writeFile(
+      providerFile,
+      `'use client';
+
+export default function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider>
+      {children}
+      <div>{children}</div>
+    </ThemeProvider>
+  );
+}
+`,
+      'utf8'
+    );
+
+    const result = await maybeInjectProvider({ providerComponentPath });
+    expect(result.status).toBe('failed');
+    if (result.status !== 'failed') return;
+    expect(result.reason).toMatch(/Multiple/);
+  });
+});

package/src/utils/provider-injector.ts

@@ -0,0 +1,315 @@
+import path from 'path';
+import { promises as fs } from 'fs';
+import { createTwoFilesPatch } from 'diff';
+import {
+  ImportDeclaration,
+  ImportSpecifier,
+  JsxExpression,
+  JsxOpeningElement,
+  JsxSelfClosingElement,
+  Node,
+  Project,
+  SourceFile,
+  SyntaxKind,
+} from 'ts-morph';
+
+export type ProviderInjectionResult =
+  | { status: 'injected'; file: string; diff?: string }
+  | { status: 'preview'; file: string; diff: string }
+  | { status: 'skipped'; file: string; existingProvider?: string }
+  | { status: 'failed'; file: string; reason: string }
+  | { status: 'not-found' };
+
+export interface ProviderDetectionResult {
+  found: boolean;
+  file?: string;
+  provider?: string;
+  candidates: string[];
+}
+
+export interface ProviderInjectionOptions {
+  providerComponentPath: string;
+  candidates?: string[];
+  dryRun?: boolean;
+}
+
+const DEFAULT_PROVIDER_CANDIDATES = [
+  // Next.js App Router patterns
+  'app/providers.tsx',
+  'app/providers.ts',
+  'app/providers.jsx',
+  'app/providers.js',
+  'src/app/providers.tsx',
+  'src/app/providers.ts',
+  'src/app/providers.jsx',
+  'src/app/providers.js',
+  // Next.js layout files (common provider host)
+  'app/layout.tsx',
+  'app/layout.ts',
+  'app/layout.jsx',
+  'app/layout.js',
+  'src/app/layout.tsx',
+  'src/app/layout.ts',
+  'src/app/layout.jsx',
+  'src/app/layout.js',
+  // Generic provider wrappers
+  'src/providers.tsx',
+  'src/providers.ts',
+  'src/providers.jsx',
+  'src/providers.js',
+];
+
+const KNOWN_I18N_PROVIDERS = [
+  'I18nProvider',
+  'IntlProvider', // react-intl
+  'NextIntlClientProvider', // next-intl
+  'NextIntlProvider', // next-intl (older)
+  'I18nextProvider', // react-i18next
+  'TranslationProvider', // common custom name
+  'LocaleProvider', // common custom name
+  'LanguageProvider', // common custom name
+];
+
+/**
+ * Detect if any provider file exists and whether an i18n provider is already wired.
+ */
+export async function detectExistingProvider(
+  candidates: string[] = DEFAULT_PROVIDER_CANDIDATES
+): Promise<ProviderDetectionResult> {
+  const workspaceRoot = process.cwd();
+  const existingFiles: string[] = [];
+
+  for (const candidate of candidates) {
+    const absoluteCandidate = path.resolve(workspaceRoot, candidate);
+    if (await fileExists(absoluteCandidate)) {
+      existingFiles.push(candidate);
+    }
+  }
+
+  if (existingFiles.length === 0) {
+    return { found: false, candidates: [] };
+  }
+
+  // Check each existing file for an i18n provider
+  for (const file of existingFiles) {
+    const absolutePath = path.resolve(workspaceRoot, file);
+    const contents = await fs.readFile(absolutePath, 'utf8');
+
+    const project = new Project({
+      useInMemoryFileSystem: false,
+      skipAddingFilesFromTsConfig: true,
+    });
+
+    const sourceFile = project.createSourceFile(absolutePath, contents, { overwrite: true });
+    const detectedProvider = getDetectedProvider(sourceFile);
+
+    if (detectedProvider) {
+      return {
+        found: true,
+        file,
+        provider: detectedProvider,
+        candidates: existingFiles,
+      };
+    }
+  }
+
+  // Files exist but no provider detected
+  return { found: false, candidates: existingFiles };
+}
+
+/**
+ * Returns the name of the detected i18n provider, or undefined if none found.
+ */
+function getDetectedProvider(sourceFile: SourceFile): string | undefined {
+  for (const pattern of KNOWN_I18N_PROVIDERS) {
+    const hasPattern =
+      sourceFile
+        .getDescendantsOfKind(SyntaxKind.JsxOpeningElement)
+        .some((element: JsxOpeningElement) => getTagName(element) === pattern) ||
+      sourceFile
+        .getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement)
+        .some((element: JsxSelfClosingElement) => getTagName(element) === pattern);
+
+    if (hasPattern) {
+      return pattern;
+    }
+  }
+
+  return undefined;
+}
+
+export async function maybeInjectProvider(
+  options: ProviderInjectionOptions
+): Promise<ProviderInjectionResult> {
+  const { providerComponentPath, candidates = DEFAULT_PROVIDER_CANDIDATES, dryRun = false } = options;
+  const workspaceRoot = process.cwd();
+  const providerAbsolute = path.resolve(providerComponentPath);
+
+  for (const candidate of candidates) {
+    const absoluteCandidate = path.resolve(workspaceRoot, candidate);
+    if (!(await fileExists(absoluteCandidate))) {
+      continue;
+    }
+
+    const injection = await injectIntoCandidate({
+      candidateRelativePath: candidate,
+      candidateAbsolutePath: absoluteCandidate,
+      providerAbsolutePath: providerAbsolute,
+      dryRun,
+    });
+
+    if (injection.status === 'not-found') {
+      // Should never happen because we only call when file exists, but keep for safety
+      continue;
+    }
+
+    return injection;
+  }
+
+  return { status: 'not-found' };
+}
+
+interface CandidateInjectionInput {
+  candidateRelativePath: string;
+  candidateAbsolutePath: string;
+  providerAbsolutePath: string;
+  dryRun: boolean;
+}
+
+async function injectIntoCandidate({
+  candidateRelativePath,
+  candidateAbsolutePath,
+  providerAbsolutePath,
+  dryRun,
+}: CandidateInjectionInput): Promise<ProviderInjectionResult> {
+  const originalContents = await fs.readFile(candidateAbsolutePath, 'utf8');
+
+  const project = new Project({
+    useInMemoryFileSystem: false,
+    skipAddingFilesFromTsConfig: true,
+  });
+
+  const sourceFile = project.createSourceFile(candidateAbsolutePath, originalContents, { overwrite: true });
+
+  const existingProvider = getDetectedProvider(sourceFile);
+  if (existingProvider) {
+    return { status: 'skipped', file: candidateRelativePath, existingProvider };
+  }
+
+  const childrenExpressions = findChildrenExpressions(sourceFile);
+  if (childrenExpressions.length === 0) {
+    return {
+      status: 'failed',
+      file: candidateRelativePath,
+      reason: 'No `{children}` expression found to wrap with <I18nProvider>.',
+    };
+  }
+
+  if (childrenExpressions.length > 1) {
+    return {
+      status: 'failed',
+      file: candidateRelativePath,
+      reason: 'Multiple `{children}` expressions detected; unsure which one to wrap.',
+    };
+  }
+
+  const providerImportPath = toRelativeImport(path.dirname(candidateAbsolutePath), providerAbsolutePath);
+  ensureProviderImport(sourceFile, providerImportPath);
+
+  const expression = childrenExpressions[0];
+  expression.replaceWithText(`<I18nProvider>${expression.getText()}</I18nProvider>`);
+
+  const updatedContents = sourceFile.getFullText();
+
+  if (updatedContents === originalContents) {
+    return { status: 'skipped', file: candidateRelativePath };
+  }
+
+  const diff = createTwoFilesPatch(
+    candidateRelativePath,
+    candidateRelativePath,
+    originalContents,
+    updatedContents,
+    '',
+    ''
+  );
+
+  if (dryRun) {
+    return { status: 'preview', file: candidateRelativePath, diff };
+  }
+
+  await fs.writeFile(candidateAbsolutePath, updatedContents, 'utf8');
+  return { status: 'injected', file: candidateRelativePath, diff };
+}
+
+function getTagName(element: JsxOpeningElement | JsxSelfClosingElement) {
+  return element.getTagNameNode().getText();
+}
+
+function findChildrenExpressions(sourceFile: SourceFile) {
+  return sourceFile
+    .getDescendantsOfKind(SyntaxKind.JsxExpression)
+    .filter((expression: JsxExpression) => {
+      const inner = expression.getExpression();
+      return inner && Node.isIdentifier(inner) && inner.getText() === 'children';
+    });
+}
+
+function ensureProviderImport(sourceFile: SourceFile, moduleSpecifier: string) {
+  const providerIdentifier = 'I18nProvider';
+  const existing = sourceFile.getImportDeclaration((declaration: ImportDeclaration) => {
+    const spec = declaration.getModuleSpecifierSourceFile();
+    if (spec && spec.getFilePath() === moduleSpecifier) {
+      return true;
+    }
+    return declaration.getModuleSpecifierValue() === moduleSpecifier;
+  });
+
+  if (existing) {
+    const hasNamed = existing
+      .getNamedImports()
+      .some((namedImport: ImportSpecifier) => namedImport.getName() === providerIdentifier);
+    if (!hasNamed) {
+      existing.addNamedImport(providerIdentifier);
+    }
+    return;
+  }
+
+  const statements = sourceFile.getStatements();
+  let insertIndex = 0;
+  for (const statement of statements) {
+    if (Node.isExpressionStatement(statement)) {
+      const expression = statement.getExpression();
+      if (Node.isStringLiteral(expression)) {
+        const literal = expression.getLiteralText();
+        if (literal.startsWith('use ')) {
+          insertIndex += 1;
+          continue;
+        }
+      }
+    }
+    break;
+  }
+
+  sourceFile.insertImportDeclaration(insertIndex, {
+    moduleSpecifier,
+    namedImports: [{ name: providerIdentifier }],
+  });
+}
+
+async function fileExists(target: string) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function toRelativeImport(fromDir: string, targetAbsolute: string) {
+  let relative = path.relative(fromDir, targetAbsolute).replace(/\\/g, '/');
+  if (!relative.startsWith('.')) {
+    relative = `./${relative}`;
+  }
+  return relative.replace(/\.(ts|tsx|js|jsx)$/i, '');
+}