i18nsmith 0.1.0

package/src/commands/rename.ts

@@ -0,0 +1,264 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { loadConfig, KeyRenamer, type KeyRenameSummary, type KeyRenameBatchSummary, type KeyRenameMapping } from '@i18nsmith/core';
+
+interface ScanOptions {
+  config: string;
+  json?: boolean;
+  report?: string;
+}
+
+interface RenameMapOptions extends ScanOptions {
+  map: string;
+  write?: boolean;
+  diff?: boolean;
+}
+
+/**
+ * Registers rename-related commands (rename-key, rename-keys)
+ */
+export function registerRename(program: Command): void {
+  program
+    .command('rename-key')
+    .description('Rename translation keys across source files and locale JSON')
+    .argument('<oldKey>', 'Existing translation key')
+    .argument('<newKey>', 'Replacement translation key')
+    .option('-c, --config <path>', 'Path to i18nsmith config file', 'i18n.config.json')
+    .option('--json', 'Print raw JSON results', false)
+    .option('--report <path>', 'Write JSON summary to a file (for CI or editors)')
+    .option('--write', 'Write changes to disk (defaults to dry-run)', false)
+    .action(async (oldKey: string, newKey: string, options: ScanOptions & { write?: boolean }) => {
+      console.log(chalk.blue(options.write ? 'Renaming translation key...' : 'Planning key rename (dry-run)...'));
+
+      try {
+        const config = await loadConfig(options.config);
+        const renamer = new KeyRenamer(config);
+        const summary = await renamer.rename(oldKey, newKey, { write: options.write });
+
+        if (options.report) {
+          const outputPath = path.resolve(process.cwd(), options.report);
+          await fs.mkdir(path.dirname(outputPath), { recursive: true });
+          await fs.writeFile(outputPath, JSON.stringify(summary, null, 2));
+          console.log(chalk.green(`Rename report written to ${outputPath}`));
+        }
+
+        if (options.json) {
+          console.log(JSON.stringify(summary, null, 2));
+          return;
+        }
+
+        printRenameSummary(summary);
+
+        if (!options.write) {
+          console.log(chalk.cyan('\n📋 DRY RUN - No files were modified'));
+          console.log(chalk.yellow('Run again with --write to apply changes.'));
+        }
+      } catch (error) {
+        console.error(chalk.red('Rename failed:'), (error as Error).message);
+        process.exitCode = 1;
+      }
+    });
+
+  program
+    .command('rename-keys')
+    .description('Rename multiple translation keys using a mapping file')
+    .requiredOption('-m, --map <path>', 'Path to JSON map file (object or array of {"from","to"})')
+    .option('-c, --config <path>', 'Path to i18nsmith config file', 'i18n.config.json')
+    .option('--json', 'Print raw JSON results', false)
+    .option('--report <path>', 'Write JSON summary to a file (for CI or editors)')
+    .option('--write', 'Write changes to disk (defaults to dry-run)', false)
+    .option('--diff', 'Display unified diffs for files that would change', false)
+    .action(async (options: RenameMapOptions) => {
+      console.log(
+        chalk.blue(options.write ? 'Renaming translation keys from map...' : 'Planning batch rename (dry-run)...')
+      );
+
+      try {
+        const config = await loadConfig(options.config);
+        const mappings = await loadRenameMappings(options.map);
+        const renamer = new KeyRenamer(config);
+        const summary = await renamer.renameBatch(mappings, { write: options.write, diff: options.diff });
+
+        if (options.report) {
+          const outputPath = path.resolve(process.cwd(), options.report);
+          await fs.mkdir(path.dirname(outputPath), { recursive: true });
+          await fs.writeFile(outputPath, JSON.stringify(summary, null, 2));
+          console.log(chalk.green(`Batch rename report written to ${outputPath}`));
+        }
+
+        if (options.json) {
+          console.log(JSON.stringify(summary, null, 2));
+          return;
+        }
+
+        printRenameBatchSummary(summary);
+
+        // Print source file diffs if requested
+        if (options.diff && summary.diffs.length > 0) {
+          console.log(chalk.blue('\nSource file changes:'));
+          for (const diff of summary.diffs) {
+            console.log(chalk.cyan(`\n--- ${diff.relativePath} (${diff.changes} change${diff.changes === 1 ? '' : 's'}) ---`));
+            console.log(diff.diff);
+          }
+        }
+
+        if (!options.write) {
+          console.log(chalk.cyan('\n📋 DRY RUN - No files were modified'));
+          console.log(chalk.yellow('Run again with --write to apply changes.'));
+        }
+      } catch (error) {
+        console.error(chalk.red('Batch rename failed:'), (error as Error).message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+function printRenameSummary(summary: KeyRenameSummary) {
+  console.log(
+    chalk.green(
+      `Updated ${summary.occurrences} occurrence${summary.occurrences === 1 ? '' : 's'} across ${summary.filesUpdated.length} file${summary.filesUpdated.length === 1 ? '' : 's'}.`
+    )
+  );
+
+  if (summary.filesUpdated.length) {
+    console.log(chalk.blue('Files updated:'));
+    summary.filesUpdated.forEach((file) => console.log(`  • ${file}`));
+  }
+
+  if (summary.localeStats.length) {
+    console.log(chalk.blue('Locale updates:'));
+    summary.localeStats.forEach((stat) => {
+      console.log(
+        `  • ${stat.locale}: ${stat.added.length} added, ${stat.updated.length} updated, ${stat.removed.length} removed (total ${stat.totalKeys})`
+      );
+    });
+  } else if (summary.localePreview.length) {
+    console.log(chalk.blue('Locale impact preview:'));
+    summary.localePreview.forEach((preview) => {
+      const status = preview.missing
+        ? chalk.yellow('missing source key')
+        : preview.duplicate
+        ? chalk.red('destination already exists')
+        : chalk.green('ready');
+      console.log(`  • ${preview.locale}: ${status}`);
+    });
+  }
+
+  if (summary.missingLocales.length) {
+    console.log(
+      chalk.yellow(
+        `Locales missing the original key: ${summary.missingLocales.join(', ')}. Update them manually if needed.`
+      )
+    );
+  }
+}
+
+function printRenameBatchSummary(summary: KeyRenameBatchSummary) {
+  console.log(
+    chalk.green(
+      `Updated ${summary.occurrences} occurrence${summary.occurrences === 1 ? '' : 's'} across ${summary.filesUpdated.length} file${summary.filesUpdated.length === 1 ? '' : 's'}.`
+    )
+  );
+
+  if (summary.mappingSummaries.length === 0) {
+    console.log(chalk.yellow('No mappings were applied.'));
+  } else {
+    console.log(chalk.blue('Mappings:'));
+    summary.mappingSummaries.slice(0, 50).forEach((mapping) => {
+      const refLabel = `${mapping.occurrences} reference${mapping.occurrences === 1 ? '' : 's'}`;
+      console.log(`  • ${mapping.from} → ${mapping.to} (${refLabel})`);
+
+      const duplicates = mapping.localePreview
+        .filter((preview) => preview.duplicate)
+        .map((preview) => preview.locale);
+      const missing = mapping.missingLocales;
+
+      const annotations = [
+        missing.length ? `missing locales: ${missing.join(', ')}` : null,
+        duplicates.length ? `target already exists in: ${duplicates.join(', ')}` : null,
+      ].filter(Boolean);
+
+      if (annotations.length) {
+        console.log(chalk.gray(`      ${annotations.join(' · ')}`));
+      }
+    });
+
+    if (summary.mappingSummaries.length > 50) {
+      console.log(chalk.gray(`  ...and ${summary.mappingSummaries.length - 50} more.`));
+    }
+  }
+
+  if (summary.filesUpdated.length) {
+    console.log(chalk.blue('Files updated:'));
+    summary.filesUpdated.forEach((file) => console.log(`  • ${file}`));
+  }
+
+  if (summary.localeStats.length) {
+    console.log(chalk.blue('Locale updates:'));
+    summary.localeStats.forEach((stat) => {
+      console.log(
+        `  • ${stat.locale}: ${stat.added.length} added, ${stat.updated.length} updated, ${stat.removed.length} removed (total ${stat.totalKeys})`
+      );
+    });
+  }
+}
+
+async function loadRenameMappings(mapPath: string): Promise<KeyRenameMapping[]> {
+  if (!mapPath) {
+    throw new Error('A path to the rename map is required.');
+  }
+
+  const resolvedPath = path.isAbsolute(mapPath) ? mapPath : path.resolve(process.cwd(), mapPath);
+  let fileContents: string;
+
+  try {
+    fileContents = await fs.readFile(resolvedPath, 'utf8');
+  } catch (error) {
+    const err = error as NodeJS.ErrnoException;
+    if (err.code === 'ENOENT') {
+      throw new Error(`Rename map not found at ${resolvedPath}.`);
+    }
+    throw new Error(`Unable to read rename map at ${resolvedPath}: ${err.message}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fileContents);
+  } catch (error) {
+    throw new Error(`Rename map contains invalid JSON: ${(error as Error).message}`);
+  }
+
+  const mappings = normalizeRenameMap(parsed);
+  if (!mappings.length) {
+    throw new Error('Rename map is empty. Provide at least one {"from": "foo", "to": "bar"} entry.');
+  }
+
+  return mappings;
+}
+
+function normalizeRenameMap(input: unknown): KeyRenameMapping[] {
+  if (Array.isArray(input)) {
+    return input
+      .map((item) => {
+        if (typeof item !== 'object' || item === null) {
+          return undefined;
+        }
+        const from = 'from' in item ? String((item as Record<string, unknown>).from ?? '') : '';
+        const to = 'to' in item ? String((item as Record<string, unknown>).to ?? '') : '';
+        return { from: from.trim(), to: to.trim() };
+      })
+      .filter((entry): entry is KeyRenameMapping =>
+        Boolean(entry && entry.from && entry.to && entry.from !== entry.to)
+      );
+  }
+
+  if (input && typeof input === 'object') {
+    return Object.entries(input as Record<string, unknown>)
+      .map(([from, to]) => ({ from: from.trim(), to: typeof to === 'string' ? to.trim() : '' }))
+      .filter((entry) => Boolean(entry.from) && Boolean(entry.to) && entry.from !== entry.to);
+  }
+
+  throw new Error('Rename map must be either an object ("old":"new") or an array of {"from","to"}.');
+}

package/src/commands/scaffold-adapter.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Command } from 'commander';
+import { registerScaffoldAdapter } from './scaffold-adapter';
+import * as scaffoldModule from '../utils/scaffold.js';
+
+vi.mock('@i18nsmith/core', () => ({
+  loadConfig: vi.fn().mockResolvedValue({
+    version: 1,
+    sourceLanguage: 'en',
+    targetLanguages: ['es'],
+    localesDir: 'locales',
+    include: ['src/**/*.{ts,tsx}'],
+    exclude: [],
+    minTextLength: 1,
+    translationAdapter: { module: 'react-i18next', hookName: 'useTranslation' },
+    keyGeneration: { namespace: 'common', shortHashLen: 6 },
+    seedTargetLocales: false,
+    sync: {
+      translationIdentifier: 't',
+      validateInterpolations: false,
+      placeholderFormats: ['doubleCurly', 'percentCurly', 'percentSymbol'],
+      emptyValuePolicy: 'warn',
+      emptyValueMarkers: ['todo'],
+      dynamicKeyAssumptions: [],
+    },
+  }),
+  diagnoseWorkspace: vi.fn().mockResolvedValue({
+    localesDir: 'locales',
+    localeFiles: [],
+    detectedLocales: [],
+    runtimePackages: [],
+    providerFiles: [],
+    adapterFiles: [],
+    translationUsage: {
+      hookName: 'useTranslation',
+      translationIdentifier: 't',
+      filesExamined: 0,
+      hookOccurrences: 0,
+      identifierOccurrences: 0,
+      hookExampleFiles: [],
+      identifierExampleFiles: [],
+    },
+    actionableItems: [],
+    conflicts: [],
+    recommendations: [],
+  }),
+}));
+
+vi.mock('inquirer', () => ({
+  default: {
+    prompt: vi.fn().mockResolvedValue({
+      type: 'custom',
+      sourceLanguage: 'en',
+      localesDir: 'locales',
+      filePath: 'src/contexts/translation-context.tsx',
+      force: false,
+    }),
+  },
+}));
+
+vi.mock('../utils/scaffold.js', () => ({
+  scaffoldTranslationContext: vi.fn().mockResolvedValue({
+    path: 'src/contexts/translation-context.tsx',
+    content: '// mock content',
+    written: true,
+  }),
+  scaffoldI18next: vi.fn().mockResolvedValue({
+    i18nPath: 'src/lib/i18n.ts',
+    providerPath: 'src/components/i18n-provider.tsx',
+    i18nResult: { path: 'src/lib/i18n.ts', content: '// i18n', written: true },
+    providerResult: { path: 'src/components/i18n-provider.tsx', content: '// provider', written: true },
+  }),
+}));
+
+vi.mock('../utils/pkg.js', () => ({
+  readPackageJson: vi.fn().mockResolvedValue({}),
+  hasDependency: vi.fn().mockReturnValue(false),
+}));
+
+describe('scaffold-adapter command', () => {
+  it('should register the scaffold-adapter command', () => {
+    const program = new Command();
+    registerScaffoldAdapter(program);
+    const command = program.commands.find((cmd) => cmd.name() === 'scaffold-adapter');
+    expect(command).toBeDefined();
+  });
+
+  describe('--dry-run flag', () => {
+    beforeEach(() => {
+      vi.clearAllMocks();
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('should pass dryRun option to scaffoldTranslationContext', async () => {
+      const scaffoldSpy = vi.spyOn(scaffoldModule, 'scaffoldTranslationContext');
+      scaffoldSpy.mockResolvedValue({
+        path: 'src/contexts/translation-context.tsx',
+        content: '// mock dry-run content',
+        written: false,
+      });
+
+      // Verify the dryRun parameter is passed correctly through the scaffold options
+      expect(scaffoldSpy).not.toHaveBeenCalled();
+      // Note: Full integration test would require mocking more dependencies
+    });
+  });
+});

package/src/commands/scaffold-adapter.ts

@@ -0,0 +1,250 @@
+import { Command } from 'commander';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { diagnoseWorkspace, loadConfig } from '@i18nsmith/core';
+import { scaffoldTranslationContext, scaffoldI18next, ScaffoldResult } from '../utils/scaffold.js';
+import { readPackageJson, hasDependency } from '../utils/pkg.js';
+import { detectPackageManager, installDependencies } from '../utils/package-manager.js';
+import { maybeInjectProvider } from '../utils/provider-injector.js';
+
+interface ScaffoldCommandOptions {
+  type?: 'custom' | 'react-i18next';
+  sourceLanguage?: string;
+  path?: string;
+  i18nPath?: string;
+  providerPath?: string;
+  localesDir?: string;
+  force?: boolean;
+  installDeps?: boolean;
+  dryRun?: boolean;
+  skipIfDetected?: boolean;
+}
+
+interface ScaffoldAnswers {
+  type: 'custom' | 'react-i18next';
+  sourceLanguage: string;
+  localesDir: string;
+  force: boolean;
+  filePath: string;
+  i18nPath: string;
+  providerPath: string;
+}
+
+export function registerScaffoldAdapter(program: Command) {
+  program
+    .command('scaffold-adapter')
+    .description('Scaffold translation adapter files')
+    .option('-t, --type <type>', 'Adapter type: custom or react-i18next')
+    .option('-l, --source-language <lang>', 'Source language code', 'en')
+    .option('-p, --path <path>', 'Path for custom adapter file', 'src/contexts/translation-context.tsx')
+    .option('--i18n-path <path>', 'Path for react-i18next initializer', 'src/lib/i18n.ts')
+    .option('--provider-path <path>', 'Path for I18nProvider component', 'src/components/i18n-provider.tsx')
+    .option('--locales-dir <dir>', 'Locales directory relative to project root', 'locales')
+    .option('-f, --force', 'Overwrite files if they already exist', false)
+    .option('--install-deps', 'Automatically install adapter dependencies when missing', false)
+    .option('--dry-run', 'Preview provider injection changes without modifying files', false)
+    .option('--no-skip-if-detected', 'Force scaffolding even if existing adapters/providers are detected')
+    .action(async (options: ScaffoldCommandOptions) => {
+      console.log(chalk.blue('Scaffolding translation resources...'));
+
+      const answers = await inquirer.prompt<ScaffoldAnswers>([
+        {
+          type: 'list',
+          name: 'type',
+          message: 'Choose adapter type',
+          choices: [
+            { name: 'Custom context (zero dependencies)', value: 'custom' },
+            { name: 'react-i18next (standard)', value: 'react-i18next' },
+          ],
+          default: options.type || 'custom',
+        },
+        {
+          type: 'input',
+          name: 'sourceLanguage',
+          message: 'Source language code',
+          default: options.sourceLanguage || 'en',
+        },
+        {
+          type: 'input',
+          name: 'localesDir',
+          message: 'Locales directory (relative to project root)',
+          default: options.localesDir || 'locales',
+        },
+        {
+          type: 'input',
+          name: 'filePath',
+          message: 'Path to scaffold translation context file',
+          default: options.path || 'src/contexts/translation-context.tsx',
+          when: (answers) => answers.type === 'custom',
+        },
+        {
+          type: 'input',
+          name: 'i18nPath',
+          message: 'Path for i18next initializer (i18n.ts)',
+          default: options.i18nPath || 'src/lib/i18n.ts',
+          when: (answers) => answers.type === 'react-i18next',
+        },
+        {
+          type: 'input',
+          name: 'providerPath',
+          message: 'Path for I18nProvider component',
+          default: options.providerPath || 'src/components/i18n-provider.tsx',
+          when: (answers) => answers.type === 'react-i18next',
+        },
+        {
+          type: 'confirm',
+          name: 'force',
+          message: 'Overwrite files if they exist?',
+          default: Boolean(options.force),
+        },
+      ]);
+
+      if ((options.skipIfDetected ?? true) && !options.force && !answers.force) {
+        const detection = await detectExistingRuntime();
+        if (detection) {
+          console.log(
+            chalk.yellow(
+              `Existing i18n runtime detected (${detection}). Skipping scaffold. Use --no-skip-if-detected or --force to override.`
+            )
+          );
+          return;
+        }
+      }
+
+      try {
+        const dryRun = Boolean(options.dryRun);
+
+        if (answers.type === 'custom') {
+          const result = await scaffoldTranslationContext(answers.filePath, answers.sourceLanguage, {
+            localesDir: answers.localesDir,
+            force: answers.force,
+            dryRun,
+          });
+
+          if (dryRun) {
+            console.log(chalk.blue('\n📋 DRY RUN - No files were modified\n'));
+            console.log(chalk.cyan(`Would create: ${result.path}`));
+            console.log(chalk.gray('─'.repeat(60)));
+            console.log(result.content);
+            console.log(chalk.gray('─'.repeat(60)));
+          } else {
+            console.log(chalk.green(`Translation context scaffolded at ${result.path}`));
+          }
+
+          console.log(chalk.blue('\nUpdate your i18n.config.json:'));
+          console.log(`{
+  "translationAdapter": {
+    "module": "${answers.filePath.replace(/\\\\/g, '/').replace(/\.tsx?$/, '')}",
+    "hookName": "useTranslation"
+  }
+}`);
+        } else if (answers.type === 'react-i18next') {
+          const { i18nPath, providerPath, i18nResult, providerResult } = await scaffoldI18next(
+            answers.i18nPath,
+            answers.providerPath,
+            answers.sourceLanguage,
+            answers.localesDir,
+            { force: answers.force, dryRun }
+          );
+
+          if (dryRun) {
+            console.log(chalk.blue('\n📋 DRY RUN - No files were modified\n'));
+            console.log(chalk.cyan(`Would create: ${i18nResult.path}`));
+            console.log(chalk.gray('─'.repeat(60)));
+            console.log(i18nResult.content);
+            console.log(chalk.gray('─'.repeat(60)));
+            console.log(chalk.cyan(`\nWould create: ${providerResult.path}`));
+            console.log(chalk.gray('─'.repeat(60)));
+            console.log(providerResult.content);
+            console.log(chalk.gray('─'.repeat(60)));
+          } else {
+            console.log(chalk.green('\nScaffolded react-i18next runtime:'));
+            console.log(chalk.green(`  • ${i18nPath}`));
+            console.log(chalk.green(`  • ${providerPath}`));
+          }
+
+          const pkg = await readPackageJson();
+          const missingDeps = ['react-i18next', 'i18next'].filter((dep) => !hasDependency(pkg, dep));
+          if (missingDeps.length) {
+            console.log(chalk.yellow('\nDependencies missing:'));
+            missingDeps.forEach((dep) => console.log(chalk.yellow(`  • ${dep}`)));
+
+            if (dryRun) {
+              console.log(chalk.blue('\nIn write mode, install them with:'));
+              console.log(chalk.cyan('  pnpm add react-i18next i18next'));
+            } else if (options.installDeps) {
+              try {
+                const manager = await detectPackageManager();
+                console.log(chalk.blue(`\nInstalling dependencies with ${manager}...`));
+                await installDependencies(manager, missingDeps);
+                console.log(chalk.green('Dependencies installed successfully.'));
+              } catch (error) {
+                console.error(chalk.red('Failed to install dependencies automatically:'), (error as Error).message);
+                console.log(chalk.blue('You can install them manually:'));
+                console.log(chalk.cyan('  pnpm add react-i18next i18next'));
+              }
+            } else {
+              console.log(chalk.blue('Install them with:'));
+              console.log(chalk.cyan('  pnpm add react-i18next i18next'));
+            }
+          }
+
+          console.log(chalk.blue('\nWrap your app with the provider (e.g. Next.js providers.tsx):'));
+          console.log(chalk.cyan(`import { I18nProvider } from '${answers.providerPath.replace(/\\\\/g, '/').replace(/\.tsx?$/, '')}';`));
+          console.log(chalk.cyan('<I18nProvider>{children}</I18nProvider>'));
+
+          const injectionResult = await maybeInjectProvider({
+            providerComponentPath: providerPath,
+            dryRun: Boolean(options.dryRun),
+          });
+
+          if (injectionResult.status === 'injected') {
+            console.log(chalk.green(`\nUpdated ${injectionResult.file} to wrap <I18nProvider>.`));
+          } else if (injectionResult.status === 'preview') {
+            console.log(
+              chalk.blue(`\nProvider dry-run for ${injectionResult.file}: changes previewed below (no files modified).`)
+            );
+            console.log(injectionResult.diff.trimEnd());
+          } else if (injectionResult.status === 'skipped') {
+            console.log(
+              chalk.yellow(`\nProvider file ${injectionResult.file} already uses I18nProvider. Skipping injection.`)
+            );
+          } else if (injectionResult.status === 'failed') {
+            console.log(
+              chalk.red(
+                `\nCould not safely inject I18nProvider into ${injectionResult.file}: ${injectionResult.reason}\n` +
+                  'Please manually wrap your layout or providers file with <I18nProvider> and rerun.'
+              )
+            );
+          } else {
+            console.log(chalk.gray('\nNo Next.js provider file detected for automatic injection.'));
+          }
+        }
+      } catch (error) {
+        console.error(chalk.red('Failed to scaffold adapter:'), (error as Error).message);
+      }
+    });
+}
+
+async function detectExistingRuntime(): Promise<string | null> {
+  try {
+    const config = await loadConfig();
+    const report = await diagnoseWorkspace(config);
+    type AdapterInfo = (typeof report.adapterFiles)[number];
+    type ProviderInfo = (typeof report.providerFiles)[number];
+
+    if (report.adapterFiles.length) {
+      return report.adapterFiles.map((adapter: AdapterInfo) => adapter.path).join(', ');
+    }
+    const provider = report.providerFiles.find((entry: ProviderInfo) => entry.hasI18nProvider);
+    if (provider) {
+      return provider.relativePath;
+    }
+  } catch (error) {
+    if ((error as Error).message?.includes('Config file not found')) {
+      return null;
+    }
+    console.warn(chalk.gray(`Skipping adapter detection: ${(error as Error).message}`));
+  }
+  return null;
+}