i18nsmith 0.1.9 → 0.2.1

package/dist/test-helpers/ensure-cli-built.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureCliBuilt(cliPath: string): Promise<void>;
+//# sourceMappingURL=ensure-cli-built.d.ts.map

package/dist/test-helpers/ensure-cli-built.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-cli-built.d.ts","sourceRoot":"","sources":["../../src/test-helpers/ensure-cli-built.ts"],"names":[],"mappings":"AAUA,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBnE"}

package/dist/utils/preview.d.ts

@@ -0,0 +1,13 @@
+export interface PreviewPayload<TSummary> {
+    type: string;
+    version: number;
+    command: string;
+    args: string[];
+    timestamp: string;
+    summary: TSummary;
+}
+export type PreviewKind = 'sync' | 'transform' | 'rename-key' | 'translate';
+export declare function writePreviewFile<TSummary>(kind: PreviewKind, summary: TSummary, outputPath: string): Promise<string>;
+export declare function readPreviewFile<TSummary>(expectedKind: PreviewKind, previewPath: string): Promise<PreviewPayload<TSummary>>;
+export declare function applyPreviewFile(expectedKind: PreviewKind, previewPath: string, extraArgs?: string[]): Promise<void>;
+//# sourceMappingURL=preview.d.ts.map

package/dist/utils/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/utils/preview.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc,CAAC,QAAQ;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,CAAC;AAE5E,wBAAsB,gBAAgB,CAAC,QAAQ,EAC7C,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,QAAQ,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAC5C,YAAY,EAAE,WAAW,EACzB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAWnC;AAED,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,WAAW,EACzB,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,MAAM,EAAO,GACvB,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/utils/preview.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=preview.test.d.ts.map

package/dist/utils/preview.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.test.d.ts","sourceRoot":"","sources":["../../src/utils/preview.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18nsmith",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "description": "CLI for i18nsmith",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/debug-patterns.test.ts

@@ -1,9 +1,10 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, beforeAll } from 'vitest';
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
+import { ensureCliBuilt } from '../test-helpers/ensure-cli-built';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -33,6 +34,10 @@ function runCli(args: string[], options: { cwd?: string } = {}) {
 describe('debug-patterns command', () => {
   let tmpDir: string;
 
+  beforeAll(async () => {
+    await ensureCliBuilt(CLI_PATH);
+  });
+
   beforeEach(async () => {
     tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'i18nsmith-debug-patterns-'));
     

package/src/commands/rename.ts

@@ -3,6 +3,7 @@ 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';
+import { applyPreviewFile, writePreviewFile } from '../utils/preview.js';
 
 interface ScanOptions {
   config: string;
@@ -10,6 +11,13 @@ interface ScanOptions {
   report?: string;
 }
 
+interface RenameKeyOptions extends ScanOptions {
+  write?: boolean;
+  diff?: boolean;
+  previewOutput?: string;
+  applyPreview?: string;
+}
+
 interface RenameMapOptions extends ScanOptions {
   map: string;
   write?: boolean;
@@ -29,13 +37,37 @@ export function registerRename(program: Command): void {
     .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)...'));
+    .option('--diff', 'Display unified diffs for files that would change', false)
+    .option('--preview-output <path>', 'Write preview summary (JSON) to a file (implies dry-run)')
+    .option('--apply-preview <path>', 'Apply a previously saved rename preview JSON file safely')
+    .action(async (oldKey: string, newKey: string, options: RenameKeyOptions) => {
+      if (options.applyPreview) {
+        await applyPreviewFile('rename-key', options.applyPreview);
+        return;
+      }
+
+      const previewMode = Boolean(options.previewOutput);
+      const writeEnabled = Boolean(options.write) && !previewMode;
+      if (previewMode && options.write) {
+        console.log(chalk.yellow('Preview requested; ignoring --write and running in dry-run mode.'));
+      }
+      options.write = writeEnabled;
+
+      console.log(chalk.blue(writeEnabled ? '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 });
+        const summary = await renamer.rename(oldKey, newKey, {
+          write: options.write,
+          diff: options.diff || previewMode,
+        });
+
+        if (previewMode && options.previewOutput) {
+          const savedPath = await writePreviewFile('rename-key', summary, options.previewOutput);
+          console.log(chalk.green(`Preview written to ${path.relative(process.cwd(), savedPath)}`));
+          return;
+        }
 
         if (options.report) {
           const outputPath = path.resolve(process.cwd(), options.report);

package/src/commands/review.test.ts

@@ -0,0 +1,12 @@
+import { describe, it, expect } from 'vitest';
+import { literalToRegexPattern } from './review.js';
+
+describe('literalToRegexPattern', () => {
+  it('anchors the value and escapes regex metacharacters', () => {
+    expect(literalToRegexPattern('Price (USD)+?')).toBe('^Price \\(USD\\)\\+\\?$');
+  });
+
+  it('preserves whitespace and newline characters', () => {
+    expect(literalToRegexPattern('Multi\nLine')).toBe('^Multi\nLine$');
+  });
+});

package/src/commands/review.ts

@@ -0,0 +1,228 @@
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import type { Command } from 'commander';
+import { loadConfigWithMeta, Scanner, type ScanCandidate, type ScanSummary } from '@i18nsmith/core';
+
+interface ReviewCommandOptions {
+  config?: string;
+  json?: boolean;
+  limit?: number;
+  scanCalls?: boolean;
+}
+
+type ReviewAction = 'allow' | 'deny' | 'skip' | 'stop';
+
+const DEFAULT_CONFIG_PATH = 'i18n.config.json';
+const DEFAULT_LIMIT = 20;
+
+export function literalToRegexPattern(value: string): string {
+  const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return `^${escaped}$`;
+}
+
+function normalizeLimit(value?: number): number {
+  if (typeof value !== 'number' || Number.isNaN(value) || !Number.isFinite(value)) {
+    return DEFAULT_LIMIT;
+  }
+  return Math.min(Math.max(1, Math.floor(value)), 200);
+}
+
+type BucketedScanSummary = ScanSummary & {
+  buckets?: {
+    needsReview?: ScanCandidate[];
+    skipped?: Array<{ reason: string }>;
+  };
+};
+
+function summarizeSkipReasons(skipped: Array<{ reason: string }>): string[] {
+  if (!skipped.length) {
+    return [];
+  }
+  const counts = new Map<string, number>();
+  for (const entry of skipped) {
+    counts.set(entry.reason, (counts.get(entry.reason) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([reason, count]) => `${reason}: ${count}`);
+}
+
+async function writeExtractionOverrides(
+  configPath: string,
+  allowPatterns: string[],
+  denyPatterns: string[]
+): Promise<{ allowAdded: number; denyAdded: number; wrote: boolean }> {
+  if (!allowPatterns.length && !denyPatterns.length) {
+    return { allowAdded: 0, denyAdded: 0, wrote: false };
+  }
+
+  const raw = await fs.readFile(configPath, 'utf-8');
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  const extraction = (typeof parsed.extraction === 'object' && parsed.extraction !== null)
+    ? (parsed.extraction as Record<string, unknown>)
+    : (parsed.extraction = {});
+
+  const allowList = Array.isArray(extraction.allowPatterns)
+    ? [...(extraction.allowPatterns as string[])]
+    : [];
+  const denyList = Array.isArray(extraction.denyPatterns)
+    ? [...(extraction.denyPatterns as string[])]
+    : [];
+
+  const allowAdded = appendUnique(allowList, allowPatterns);
+  const denyAdded = appendUnique(denyList, denyPatterns);
+
+  if (allowAdded === 0 && denyAdded === 0) {
+    return { allowAdded, denyAdded, wrote: false };
+  }
+
+  extraction.allowPatterns = allowList;
+  extraction.denyPatterns = denyList;
+
+  await fs.writeFile(configPath, JSON.stringify(parsed, null, 2));
+  return { allowAdded, denyAdded, wrote: true };
+}
+
+function appendUnique(target: string[], additions: string[]): number {
+  const seen = new Set(target);
+  let added = 0;
+  for (const next of additions) {
+    if (seen.has(next)) continue;
+    target.push(next);
+    seen.add(next);
+    added++;
+  }
+  return added;
+}
+
+function printCandidate(candidate: ScanCandidate) {
+  const location = `${candidate.filePath}:${candidate.position.line}:${candidate.position.column}`;
+  console.log(chalk.cyan(`\n${candidate.text}`));
+  console.log(chalk.gray(`  • Location: ${location}`));
+  console.log(chalk.gray(`  • Kind: ${candidate.kind}`));
+  if (candidate.context) {
+    console.log(chalk.gray(`  • Context: ${candidate.context}`));
+  }
+}
+
+async function promptAction(): Promise<ReviewAction> {
+  const { action } = await inquirer.prompt<{ action: ReviewAction }>([
+    {
+      type: 'list',
+      name: 'action',
+      message: 'Choose an action for this string',
+      choices: [
+        { name: 'Always translate (add to allowPatterns)', value: 'allow' },
+        { name: 'Always skip (add to denyPatterns)', value: 'deny' },
+        { name: 'Skip for now', value: 'skip' },
+        { name: 'Stop reviewing', value: 'stop' },
+      ],
+    },
+  ]);
+  return action;
+}
+
+export function registerReview(program: Command) {
+  program
+    .command('review')
+    .description('Review borderline candidates and persist allow/deny overrides')
+    .option('-c, --config <path>', 'Path to i18nsmith config file', DEFAULT_CONFIG_PATH)
+    .option('--json', 'Print raw bucket data as JSON', false)
+    .option('--limit <n>', 'Limit the number of items per session (default: 20)', (value) => parseInt(value, 10))
+    .option('--scan-calls', 'Include translation call arguments', false)
+    .action(async (options: ReviewCommandOptions) => {
+      try {
+        const { config, projectRoot, configPath } = await loadConfigWithMeta(options.config);
+        const scanner = new Scanner(config, { workspaceRoot: projectRoot });
+  const summary = scanner.scan({ scanCalls: options.scanCalls }) as BucketedScanSummary;
+  const buckets = summary.buckets ?? {};
+  const needsReview = buckets.needsReview ?? [];
+  const skipped = buckets.skipped ?? [];
+
+        if (options.json) {
+          console.log(JSON.stringify({ needsReview, skipped }, null, 2));
+          return;
+        }
+
+        if (!needsReview.length) {
+          console.log(chalk.green('No borderline candidates detected.'));
+          const reasons = summarizeSkipReasons(skipped);
+          if (reasons.length) {
+            console.log(chalk.gray('Most common skip reasons:'));
+            reasons.forEach((line) => console.log(chalk.gray(`  • ${line}`)));
+          }
+          return;
+        }
+
+        if (!process.stdout.isTTY || process.env.CI === 'true') {
+          console.log(chalk.red('Interactive review requires a TTY. Use --json for non-interactive output.'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const limit = normalizeLimit(options.limit);
+        const queue = needsReview.slice(0, limit);
+        console.log(
+          chalk.blue(
+            `Reviewing ${queue.length} of ${needsReview.length} candidate${needsReview.length === 1 ? '' : 's'} (limit=${limit}).`
+          )
+        );
+
+        const allowPatterns: string[] = [];
+        const denyPatterns: string[] = [];
+
+        for (const candidate of queue) {
+          printCandidate(candidate);
+          const action = await promptAction();
+          if (action === 'stop') {
+            break;
+          }
+          if (action === 'skip') {
+            continue;
+          }
+          const pattern = literalToRegexPattern(candidate.text);
+          if (action === 'allow') {
+            allowPatterns.push(pattern);
+            console.log(chalk.green(`  → Queued ${pattern} for allowPatterns`));
+          } else if (action === 'deny') {
+            denyPatterns.push(pattern);
+            console.log(chalk.yellow(`  → Queued ${pattern} for denyPatterns`));
+          }
+        }
+
+        if (!allowPatterns.length && !denyPatterns.length) {
+          console.log(chalk.gray('No config changes requested.'));
+          return;
+        }
+
+        const { allowAdded, denyAdded, wrote } = await writeExtractionOverrides(
+          configPath,
+          allowPatterns,
+          denyPatterns
+        );
+
+        if (!wrote) {
+          console.log(chalk.gray('Patterns already existed; config unchanged.'));
+          return;
+        }
+
+        console.log(
+          chalk.green(
+            `Updated ${relativize(configPath)} (${allowAdded} allow, ${denyAdded} deny pattern${
+              allowAdded + denyAdded === 1 ? '' : 's'
+            } added).`
+          )
+        );
+      } catch (error) {
+        console.error(chalk.red('Review failed:'), (error as Error).message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+function relativize(filePath: string): string {
+  return path.relative(process.cwd(), filePath) || filePath;
+}

package/src/commands/sync-seed.test.ts

@@ -1,12 +1,19 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, beforeAll } from 'vitest';
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
 import { execSync } from 'child_process';
+import { ensureCliBuilt } from '../test-helpers/ensure-cli-built';
+
+const CLI_PATH = path.resolve(__dirname, '..', '..', 'dist', 'index.js');
 
 describe('sync --seed-target-locales', () => {
   let tempDir: string;
 
+  beforeAll(async () => {
+    await ensureCliBuilt(CLI_PATH);
+  });
+
   beforeEach(async () => {
     tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'i18nsmith-seed-test-'));
     
@@ -55,9 +62,8 @@ export function App() {
   });
 
   const runCli = (args: string): string => {
-    const cliPath = path.resolve(__dirname, '..', '..', 'dist', 'index.js');
     try {
-      return execSync(`node ${cliPath} ${args}`, {
+      return execSync(`node ${CLI_PATH} ${args}`, {
         cwd: tempDir,
         encoding: 'utf8',
         stdio: ['pipe', 'pipe', 'pipe'],

package/src/commands/sync.ts

@@ -13,11 +13,13 @@ import {
   createRenameMappingFile,
   type SyncSummary,
   type KeyRenameBatchSummary,
+  type SyncSelection,
 } from '@i18nsmith/core';
 import {
   printLocaleDiffs,
   writeLocaleDiffPatches,
 } from '../utils/diff-utils.js';
+import { applyPreviewFile, writePreviewFile } from '../utils/preview.js';
 import { SYNC_EXIT_CODES } from '../utils/exit-codes.js';
 
 interface SyncCommandOptions {
@@ -49,6 +51,9 @@ interface SyncCommandOptions {
   shapeDelimiter?: string;
   seedTargetLocales?: boolean;
   seedValue?: string;
+  previewOutput?: string;
+  selectionFile?: string;
+  applyPreview?: string;
 }
 
 function collectAssumedKeys(value: string, previous: string[] = []) {
@@ -90,26 +95,66 @@ export function registerSync(program: Command) {
     .option('--shape-delimiter <char>', 'Delimiter for key nesting (default: ".")', '.')
     .option('--seed-target-locales', 'Add missing keys to target locale files with empty or placeholder values', false)
     .option('--seed-value <value>', 'Value to use when seeding target locales (default: empty string)', '')
+    .option('--preview-output <path>', 'Write preview summary (JSON) to a file (implies dry-run)')
+    .option('--selection-file <path>', 'Path to JSON file with selected missing/unused keys to write (used with --write)')
+    .option('--apply-preview <path>', 'Apply a previously saved sync preview JSON file safely')
     .action(async (options: SyncCommandOptions) => {
+      if (options.applyPreview) {
+        const extraArgs: string[] = [];
+        if (options.selectionFile) {
+          extraArgs.push('--selection-file', options.selectionFile);
+        }
+        if (options.prune) {
+          extraArgs.push('--prune');
+        }
+        await applyPreviewFile('sync', options.applyPreview, extraArgs);
+        return;
+      }
+
       const interactive = Boolean(options.interactive);
       const diffEnabled = Boolean(options.diff || options.patchDir);
       const invalidateCache = Boolean(options.invalidateCache);
-      const diffRequested = diffEnabled || Boolean(options.json);
+      const previewMode = Boolean(options.previewOutput);
+      const diffRequested = diffEnabled || Boolean(options.json) || previewMode;
+
       if (interactive && options.json) {
         console.error(chalk.red('--interactive cannot be combined with --json output.'));
         process.exitCode = 1;
         return;
       }
 
-      console.log(
-        chalk.blue(
-          interactive
-            ? 'Interactive sync (dry-run first)...'
-            : options.write
-            ? 'Syncing locale files...'
-            : 'Checking locale drift...'
-        )
-      );
+      if (previewMode && interactive) {
+        console.error(chalk.red('--preview-output cannot be combined with --interactive.'));
+        process.exitCode = 1;
+        return;
+      }
+
+      const writeEnabled = Boolean(options.write) && !previewMode;
+      if (previewMode && options.write) {
+        console.log(
+          chalk.yellow('Preview requested; ignoring --write and running in dry-run mode.')
+        );
+      }
+      options.write = writeEnabled;
+
+      if (options.selectionFile && !options.write) {
+        console.error(chalk.red('--selection-file requires --write (or --apply-preview) to take effect.'));
+        process.exitCode = 1;
+        return;
+      }
+
+      const selectionFromFile = options.selectionFile
+        ? await loadSelectionFile(options.selectionFile)
+        : undefined;
+
+      const banner = previewMode
+        ? 'Generating sync preview...'
+        : interactive
+        ? 'Interactive sync (dry-run first)...'
+        : writeEnabled
+        ? 'Syncing locale files...'
+        : 'Checking locale drift...';
+      console.log(chalk.blue(banner));
 
       try {
         const { config, projectRoot, configPath } = await loadConfigWithMeta(options.config);
@@ -202,11 +247,17 @@ export function registerSync(program: Command) {
           validateInterpolations: options.validateInterpolations,
           emptyValuePolicy: options.emptyValues === false ? 'fail' : undefined,
           assumedKeys: options.assume,
+          selection: selectionFromFile,
           diff: diffRequested,
           invalidateCache,
           targets: options.target,
         });
 
+        if (previewMode && options.previewOutput) {
+          const savedPath = await writePreviewFile('sync', summary, options.previewOutput);
+          console.log(chalk.green(`Preview written to ${path.relative(process.cwd(), savedPath)}`));
+        }
+
         // Show backup info if created
         if (summary.backup) {
           console.log(chalk.blue(`\n📦 ${summary.backup.summary}`));
@@ -685,6 +736,49 @@ async function runInteractiveSync(syncer: Syncer, options: SyncCommandOptions) {
   }
 }
 
+async function loadSelectionFile(filePath: string): Promise<SyncSelection> {
+  const resolvedPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  let raw: string;
+  try {
+    raw = await fs.readFile(resolvedPath, 'utf8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Unable to read selection file at ${resolvedPath}: ${message}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Selection file ${resolvedPath} contains invalid JSON: ${message}`);
+  }
+
+  const selection: SyncSelection = {};
+  const missing = (parsed as { missing?: unknown }).missing;
+  const unused = (parsed as { unused?: unknown }).unused;
+
+  if (Array.isArray(missing)) {
+    const normalized = missing.map((key) => String(key).trim()).filter(Boolean);
+    if (normalized.length) {
+      selection.missing = normalized;
+    }
+  }
+
+  if (Array.isArray(unused)) {
+    const normalized = unused.map((key) => String(key).trim()).filter(Boolean);
+    if (normalized.length) {
+      selection.unused = normalized;
+    }
+  }
+
+  if (!selection.missing?.length && !selection.unused?.length) {
+    throw new Error(`Selection file ${resolvedPath} must include at least one "missing" or "unused" entry.`);
+  }
+
+  return selection;
+}
+
 function printRenameBatchSummary(summary: KeyRenameBatchSummary) {
   console.log(
     chalk.green(