@abdess76/i18nkit 1.0.0

package/bin/core/applier-utils.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const fs = require('./fs-adapter');
+const readline = require('readline');
+const { createBackup, getBackupFiles } = require('./backup');
+
+const isValidFinding = f => f.file && f.text && f.key && !f.context?.startsWith('ts_');
+
+function addFindingToMap(map, finding) {
+  if (!map.has(finding.file)) {
+    map.set(finding.file, []);
+  }
+  map.get(finding.file).push(finding);
+}
+
+function groupFindingsByFile(findings) {
+  const findingsByFile = new Map();
+  findings.filter(isValidFinding).forEach(f => addFindingToMap(findingsByFile, f));
+  return findingsByFile;
+}
+
+function promptUser(question, interactive) {
+  if (!interactive) {
+    return Promise.resolve(true);
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const { promise, resolve } = Promise.withResolvers();
+  rl.question(`${question} (y/N) `, answer => {
+    rl.close();
+    resolve(['y', 'yes'].includes(answer.toLowerCase()));
+  });
+  return promise;
+}
+
+async function confirmFileModifications(findingsByFile, interactive, log) {
+  if (!interactive || findingsByFile.size === 0) {
+    return true;
+  }
+  log(`\nAbout to modify ${findingsByFile.size} file(s):`);
+  for (const [file, fileFindings] of findingsByFile) {
+    log(`  ${file} (${fileFindings.length} replacement(s))`);
+  }
+  const proceed = await promptUser('\nProceed with modifications?', interactive);
+  if (!proceed) {
+    log('Aborted by user.');
+  }
+  return proceed;
+}
+
+function loadFileForReplacement(filePath, relativeFile, verbose) {
+  if (!fs.existsSync(filePath)) {
+    if (verbose) {
+      console.warn(`Skipped (not found): ${relativeFile}`);
+    }
+    return null;
+  }
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    if (verbose) {
+      console.warn(`Skipped (read error): ${relativeFile}`);
+    }
+    return null;
+  }
+}
+
+function applyReplacementsToContent(content, fileFindings, adapter) {
+  let result = content;
+  let count = 0;
+  for (const finding of fileFindings) {
+    const transformed = adapter.transform(
+      result,
+      finding.rawText || finding.text,
+      finding.key,
+      finding.context,
+    );
+    result = transformed.content;
+    count += transformed.replacements;
+  }
+  return { content: result, count };
+}
+
+function tryUpdateTsImports(tsFile, opts) {
+  const { backupDir, adapter, backup = true, dryRun = false } = opts;
+  createBackup(tsFile, backupDir, { enabled: backup, dryRun });
+  const tsContent = fs.readFileSync(tsFile, 'utf-8');
+  const updatedTs = adapter.updateImports(tsContent);
+  if (updatedTs === tsContent) {
+    return false;
+  }
+  if (!dryRun) {
+    fs.writeFileSync(tsFile, updatedTs, 'utf-8');
+  }
+  return true;
+}
+
+function logBackupInfo(opts, log) {
+  const backupFiles = getBackupFiles();
+  if (opts.backup && !opts.dryRun && backupFiles.size > 0) {
+    log(`Backups created:   ${backupFiles.size} (in ${opts.backupDir})`);
+  }
+}
+
+function logModifiedFiles(modifiedFiles, dryRun, log) {
+  if (!dryRun && modifiedFiles.length > 0) {
+    log('\nModified files:');
+    modifiedFiles.forEach(({ file, count }) => log(`  ${file} (${count})`));
+  }
+}
+
+function logApplyResults(results, opts) {
+  const { log = console.log } = opts;
+  log(`\nFiles modified:    ${results.totalFiles}`);
+  log(`Replacements:      ${results.totalReplacements}`);
+  logBackupInfo(opts, log);
+  logModifiedFiles(results.modifiedFiles, opts.dryRun, log);
+}
+
+function loadAndValidateReport(reportPath) {
+  if (!fs.existsSync(reportPath)) {
+    throw new Error(
+      `Report file not found: ${reportPath}\nRun with --json first to generate a report file.`,
+    );
+  }
+  try {
+    const report = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+    if (!Array.isArray(report.findings)) {
+      throw new Error('missing findings array');
+    }
+    return report;
+  } catch (err) {
+    throw new Error(`Cannot parse report: ${err.message}`);
+  }
+}
+
+module.exports = {
+  groupFindingsByFile,
+  confirmFileModifications,
+  loadFileForReplacement,
+  applyReplacementsToContent,
+  tryUpdateTsImports,
+  logApplyResults,
+  loadAndValidateReport,
+};

package/bin/core/applier.js

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * @fileoverview Translation replacement engine.
+ * Applies extracted i18n keys to source files with backup and rollback support.
+ * @module applier
+ */
+
+const fs = require('./fs-adapter');
+const path = require('path');
+const { createBackup } = require('./backup');
+const {
+  groupFindingsByFile,
+  confirmFileModifications,
+  loadFileForReplacement,
+  applyReplacementsToContent,
+  tryUpdateTsImports,
+  logApplyResults,
+  loadAndValidateReport,
+} = require('./applier-utils');
+
+function getCompanionTsFile(htmlFilePath) {
+  return htmlFilePath.replace(/\.html$/, '.ts');
+}
+
+function logTsUpdate(updated, tsFile, opts) {
+  if (updated && opts.verbose) {
+    console.log(`  + TranslocoPipe added to ${path.relative(opts.srcDir, tsFile)}`);
+  }
+}
+
+function updateCompanionTsFile(htmlFilePath, opts) {
+  const tsFile = getCompanionTsFile(htmlFilePath);
+  if (!fs.existsSync(tsFile)) {
+    return;
+  }
+  try {
+    logTsUpdate(tryUpdateTsImports(tsFile, opts), tsFile, opts);
+  } catch {
+    if (opts.verbose) {
+      console.warn(`  Warning: Could not update ${tsFile}`);
+    }
+  }
+}
+
+function applyTsPostProcessing(content, opts) {
+  return opts.adapter.updateImports(content);
+}
+
+function applyPostProcessing(ctx) {
+  const { relativeFile, content, count, filePath, opts } = ctx;
+  if (count > 0 && /\.ts$/.test(relativeFile)) {
+    return applyTsPostProcessing(content, opts);
+  }
+  if (count > 0 && /\.html$/.test(relativeFile)) {
+    updateCompanionTsFile(filePath, opts);
+  }
+  return content;
+}
+
+function buildFileResult(ctx) {
+  const { filePath, content, originalContent, count } = ctx;
+  return {
+    filePath,
+    content,
+    originalContent,
+    fileReplacements: count,
+    hasChanges: content !== originalContent,
+  };
+}
+
+function processFileReplacements(relativeFile, fileFindings, opts) {
+  const { srcDir, backupDir, backup = true, dryRun = false, verbose = false, adapter } = opts;
+  const filePath = path.join(srcDir, relativeFile);
+  const originalContent = loadFileForReplacement(filePath, relativeFile, verbose);
+  if (!originalContent) {
+    return null;
+  }
+  createBackup(filePath, backupDir, { enabled: backup, dryRun });
+  const { content: replaced, count } = applyReplacementsToContent(
+    originalContent,
+    fileFindings,
+    adapter,
+  );
+  const content = applyPostProcessing({ relativeFile, content: replaced, count, filePath, opts });
+  return buildFileResult({ filePath, content, originalContent, count });
+}
+
+function writeFileChanges(ctx) {
+  const { relativeFile, result, modifiedFiles, dryRun, verbose, log } = ctx;
+  if (!result.hasChanges) {
+    return { files: 0, replacements: 0 };
+  }
+  if (dryRun) {
+    log(`[DRY RUN] ${relativeFile}: ${result.fileReplacements} replacement(s)`);
+  } else {
+    fs.writeFileSync(result.filePath, result.content, 'utf-8');
+    modifiedFiles.push({ file: relativeFile, count: result.fileReplacements });
+    if (verbose) {
+      log(`Modified: ${relativeFile} (${result.fileReplacements} replacement(s))`);
+    }
+  }
+  return { files: 1, replacements: result.fileReplacements };
+}
+
+function processSingleFile(ctx) {
+  const { relativeFile, fileFindings, modifiedFiles, opts } = ctx;
+  const result = processFileReplacements(relativeFile, fileFindings, opts);
+  if (!result) {
+    return { files: 0, replacements: 0 };
+  }
+  const { dryRun = false, verbose = false, log = console.log } = opts;
+  return writeFileChanges({ relativeFile, result, modifiedFiles, dryRun, verbose, log });
+}
+
+function processAllFiles(findingsByFile, opts) {
+  const modifiedFiles = [];
+  let totalFiles = 0;
+  let totalReplacements = 0;
+  for (const [relativeFile, fileFindings] of findingsByFile) {
+    const counts = processSingleFile({ relativeFile, fileFindings, modifiedFiles, opts });
+    totalFiles += counts.files;
+    totalReplacements += counts.replacements;
+  }
+  return { totalFiles, totalReplacements, modifiedFiles };
+}
+
+/**
+ * Applies translation replacements from findings array
+ * @param {Finding[]} findings
+ * @param {ApplyOptions} [opts]
+ * @returns {Promise<ApplyResult>}
+ */
+async function applyFindings(findings, opts = {}) {
+  const { log = console.log, interactive = false } = opts;
+  log('Auto-Apply Translations');
+  log('-'.repeat(50));
+  const findingsByFile = groupFindingsByFile(findings);
+  const shouldProceed = await confirmFileModifications(findingsByFile, interactive, log);
+  if (!shouldProceed) {
+    return { success: false, aborted: true };
+  }
+  const results = processAllFiles(findingsByFile, opts);
+  logApplyResults(results, opts);
+  return { success: true, ...results };
+}
+
+/**
+ * Applies translations from a JSON report file
+ * @param {string} reportPath - Path to extracted-keys.json
+ * @param {ApplyOptions} [opts]
+ * @returns {Promise<ApplyResult>}
+ * @example
+ * await applyTranslations('./extracted-keys.json', { srcDir: './src', adapter });
+ */
+function applyTranslations(reportPath, opts = {}) {
+  const { log = console.log } = opts;
+  log('Apply Translations');
+  log('='.repeat(50));
+  log(`Report: ${reportPath}\n`);
+  const report = loadAndValidateReport(reportPath);
+  return applyFindings(report.findings, opts);
+}
+
+module.exports = { applyFindings, applyTranslations };

package/bin/core/args.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * @typedef {Object} ParsedFlags
+ * @property {boolean} verbose
+ * @property {boolean} jsonOutput
+ * @property {boolean} strict
+ * @property {boolean} dryRun
+ * @property {boolean} ciMode
+ * @property {boolean} useDeepL
+ * @property {boolean} merge
+ * @property {boolean} skipTranslated
+ * @property {boolean} extractTsObjects
+ * @property {boolean} autoApply
+ * @property {boolean} backup
+ * @property {boolean} interactive
+ * @property {string|null} lang
+ * @property {string} format
+ * @property {string|null} translatePair
+ * @property {string|null} translateEmail
+ * @property {string[]} initLangs
+ */
+
+const { getFlag, getArgValue, getArgList } = require('./config');
+
+const flag = (args, config, opts) => getFlag(args, config, opts);
+const value = (args, config, opts) => getArgValue(args, config, opts);
+
+/**
+ * Parse command line arguments into structured flags
+ * @param {string[]} args
+ * @param {Object} config
+ * @returns {ParsedFlags}
+ */
+function parseCiMode(args, config) {
+  const ciMode = flag(args, config, { flag: '--ci', configKey: 'ci' });
+  if (!ciMode) {
+    return { ciMode: false, jsonOutput: false, strict: false };
+  }
+  return { ciMode: true, jsonOutput: true, strict: true };
+}
+
+function parseBooleanFlags(args, config) {
+  return {
+    verbose: flag(args, config, { flag: '--verbose', configKey: 'verbose' }),
+    dryRun: flag(args, config, { flag: '--dry-run', configKey: 'dryRun' }),
+    useDeepL: flag(args, config, { flag: '--deepl', configKey: 'deepl' }),
+    merge: flag(args, config, { flag: '--merge', configKey: 'merge' }),
+    skipTranslated: !flag(args, config, {
+      flag: '--include-translated',
+      configKey: 'includeTranslated',
+    }),
+    extractTsObjects: flag(args, config, {
+      flag: '--extract-ts-objects',
+      configKey: 'extractTsObjects',
+    }),
+    autoApply: flag(args, config, { flag: '--auto-apply', configKey: 'autoApply' }),
+    interactive: flag(args, config, { flag: '--interactive', configKey: 'interactive' }),
+  };
+}
+
+function parseBackupFlag(args, config) {
+  if (args.includes('--no-backup')) {
+    return false;
+  }
+  return flag(args, config, { flag: '--backup', configKey: 'backup', defaultValue: true });
+}
+
+function parseValueFlags(args, config) {
+  return {
+    lang: value(args, config, { flag: '--lang', configKey: 'lang' }),
+    format: value(args, config, { flag: '--format', configKey: 'format', defaultValue: 'nested' }),
+    translatePair: value(args, config, { flag: '--translate', configKey: 'translate' }),
+    translateEmail: value(args, config, { flag: '--email', configKey: 'email' }),
+    initLangs: getArgList(args, config, { flag: '--init-langs', configKey: 'initLangs' }),
+  };
+}
+
+function parseArgs(args, config = {}) {
+  const ci = parseCiMode(args, config);
+  const bools = parseBooleanFlags(args, config);
+  const vals = parseValueFlags(args, config);
+  const jsonOutput = ci.jsonOutput || flag(args, config, { flag: '--json', configKey: 'json' });
+  const strict = ci.strict || flag(args, config, { flag: '--strict', configKey: 'strict' });
+  return {
+    ...bools,
+    ...vals,
+    ciMode: ci.ciMode,
+    jsonOutput,
+    strict,
+    backup: parseBackupFlag(args, config),
+  };
+}
+
+const COMMAND_ALIASES = {
+  orphans: 'find-orphans',
+  '--orphans': 'find-orphans',
+  '--find-orphans': 'find-orphans',
+  '--check-sync': 'check-sync',
+  '--watch': 'watch',
+};
+
+const POSITIONAL_COMMANDS = [
+  'check-sync',
+  'find-orphans',
+  'translate',
+  'apply',
+  'watch',
+  'extract',
+];
+
+function detectFromFlags(args) {
+  if (args.some(a => a.startsWith('--translate'))) {
+    return 'translate';
+  }
+  if (args.some(a => a.startsWith('--apply'))) {
+    return 'apply';
+  }
+  const flagCmd = args.find(a => COMMAND_ALIASES[a]);
+  return flagCmd ? COMMAND_ALIASES[flagCmd] : null;
+}
+
+function detectHelpOrVersion(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    return 'help';
+  }
+  if (args.includes('--version') || args.includes('-v')) {
+    return 'version';
+  }
+  return null;
+}
+
+function detectPositionalCommand(args) {
+  const firstArg = args[0];
+  if (!firstArg || !POSITIONAL_COMMANDS.includes(firstArg)) {
+    return null;
+  }
+  return COMMAND_ALIASES[firstArg] || firstArg;
+}
+
+function detectCommand(args) {
+  return (
+    detectHelpOrVersion(args) || detectPositionalCommand(args) || detectFromFlags(args) || 'extract'
+  );
+}
+
+module.exports = { parseArgs, detectCommand };

package/bin/core/backup.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * @fileoverview File backup and restore for safe source modifications.
+ * Creates timestamped backups before applying changes.
+ * @module backup
+ */
+
+const fs = require('./fs-adapter');
+const path = require('path');
+
+const backupFiles = new Map();
+
+function buildBackupPath(filePath, backupDir) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const relativePath = path.relative(process.cwd(), filePath);
+  return path.join(backupDir, `${timestamp}_${relativePath.replace(/[/\\]/g, '_')}`);
+}
+
+function writeBackupFile(filePath, backupPath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    fs.writeFileSync(backupPath, content, 'utf-8');
+    backupFiles.set(filePath, backupPath);
+    return backupPath;
+  } catch (err) {
+    console.warn(`Warning: Cannot backup ${filePath}: ${err.message}`);
+    return null;
+  }
+}
+
+function shouldSkipBackup(enabled, dryRun) {
+  return !enabled || dryRun;
+}
+
+/**
+ * Creates a timestamped backup of a file
+ * @param {string} filePath
+ * @param {string} backupDir
+ * @param {Object} [options]
+ * @returns {string|null} Backup path or null if skipped
+ */
+function createBackup(filePath, backupDir, options = {}) {
+  const { enabled = true, dryRun = false } = options;
+  if (shouldSkipBackup(enabled, dryRun)) {
+    return null;
+  }
+  fs.mkdirSync(backupDir, { recursive: true });
+  return writeBackupFile(filePath, buildBackupPath(filePath, backupDir));
+}
+
+/**
+ * Restores all backed-up files to their original locations
+ * @returns {number} Count of restored files
+ */
+function restoreBackups() {
+  let restored = 0;
+  for (const [original, backup] of backupFiles) {
+    try {
+      const content = fs.readFileSync(backup, 'utf-8');
+      fs.writeFileSync(original, content, 'utf-8');
+      restored++;
+    } catch {
+      console.error(`Cannot restore ${original} from ${backup}`);
+    }
+  }
+  return restored;
+}
+
+function getBackupFiles() {
+  return backupFiles;
+}
+
+module.exports = { createBackup, restoreBackups, getBackupFiles };

package/bin/core/command-interface.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * @fileoverview CLI command categorization and help formatting.
+ * Groups commands by category and generates formatted output.
+ * @module command-interface
+ */
+
+const COMMAND_CATEGORIES = Object.freeze([
+  { id: 'extraction', label: 'EXTRACTION' },
+  { id: 'validation', label: 'VALIDATION' },
+  { id: 'translation', label: 'TRANSLATION' },
+  { id: 'development', label: 'DEVELOPMENT' },
+]);
+
+const getDescription = cmd => cmd.description || cmd.meta?.description || 'No description';
+const getCategory = cmd => cmd.category || cmd.meta?.category;
+
+function formatAliases(command) {
+  return command.aliases?.length ? ` (${command.aliases.join(', ')})` : '';
+}
+
+function formatOption(opt) {
+  const required = opt.required ? ' (required)' : '';
+  return `    ${opt.flag.padEnd(24)} ${opt.description}${required}`;
+}
+
+function formatOptions(command) {
+  return (command.options || []).map(formatOption);
+}
+
+/**
+ * Formats command for CLI help output.
+ * @param {Command} command
+ * @returns {string}
+ */
+function formatCommandHelp(command) {
+  const lines = [`  ${command.name}${formatAliases(command)}`, `    ${getDescription(command)}`];
+  lines.push(...formatOptions(command));
+  return lines.join('\n');
+}
+
+/**
+ * Groups commands by category for organized help display.
+ * @param {Command[]} commands
+ * @returns {Record<string, {label: string, commands: Command[]}>}
+ */
+function groupCommandsByCategory(commands) {
+  const byCategory = Object.groupBy(commands, c => getCategory(c) || 'other');
+
+  const grouped = Object.fromEntries(
+    COMMAND_CATEGORIES.map(cat => [
+      cat.id,
+      { label: cat.label, commands: byCategory[cat.id] || [] },
+    ]),
+  );
+
+  if (byCategory.other?.length) {
+    grouped.other = { label: 'OTHER', commands: byCategory.other };
+  }
+
+  return grouped;
+}
+
+module.exports = {
+  COMMAND_CATEGORIES,
+  formatCommandHelp,
+  groupCommandsByCategory,
+};

package/bin/core/config.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * @fileoverview Configuration loader with CLI argument merging.
+ * Supports .js and .json config files with fallback chain.
+ * @module config
+ */
+
+const fs = require('./fs-adapter');
+const path = require('path');
+
+const CONFIG_FILES = ['i18nkit.config.js', 'i18nkit.config.json', '.i18nkit.config.js'];
+
+function tryLoadConfigFile(configFile, cwd = process.cwd()) {
+  const configPath = path.join(cwd, configFile);
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+  try {
+    return configFile.endsWith('.js') ?
+        require(configPath)
+      : JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch (err) {
+    console.warn(`Warning: Cannot load ${configFile}: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Loads config from .i18nkit.config.js or .json variants
+ * @param {string} [cwd=process.cwd()]
+ * @returns {Object}
+ */
+function loadConfig(cwd = process.cwd()) {
+  for (const configFile of CONFIG_FILES) {
+    const config = tryLoadConfigFile(configFile, cwd);
+    if (config) {
+      return config;
+    }
+  }
+  return {};
+}
+
+function getConfigValue(config, configKey, defaultValue) {
+  return configKey && config[configKey] !== undefined ? config[configKey] : defaultValue;
+}
+
+/**
+ * Gets boolean flag from args or config with fallback
+ * @param {string[]} args
+ * @param {Object} config
+ * @param {Object} opts
+ * @returns {boolean}
+ */
+function getFlag(args, config, opts = {}) {
+  const { flag, configKey, defaultValue = false } = opts;
+  if (args.includes(flag)) {
+    return true;
+  }
+  return getConfigValue(config, configKey, defaultValue);
+}
+
+function getValueFromArgs(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1) {
+    return null;
+  }
+  const value = args[idx + 1];
+  return value && !value.startsWith('--') ? value : null;
+}
+
+/**
+ * Gets string value from args or config with fallback
+ * @param {string[]} args
+ * @param {Object} config
+ * @param {Object} opts
+ * @returns {string|undefined}
+ */
+function getArgValue(args, config, opts = {}) {
+  const { flag, configKey, defaultValue } = opts;
+  const argValue = getValueFromArgs(args, flag);
+  if (argValue !== null) {
+    return argValue;
+  }
+  return configKey && config[configKey] !== undefined ? config[configKey] : defaultValue;
+}
+
+function parseArgListValue(value) {
+  return value
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean);
+}
+
+function getConfigAsList(config, configKey) {
+  if (!configKey || !config[configKey]) {
+    return [];
+  }
+  return Array.isArray(config[configKey]) ? config[configKey] : [config[configKey]];
+}
+
+function getArgList(args, config, opts) {
+  const { flag, configKey } = opts;
+  const argValue = getValueFromArgs(args, flag);
+  return argValue ? parseArgListValue(argValue) : getConfigAsList(config, configKey);
+}
+
+module.exports = { loadConfig, getFlag, getArgValue, getArgList };