i18n-smell-detector 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18n-smell-detector",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Find copied locale values, placeholder mismatches, and hardcoded user-visible strings.",
   "type": "module",
   "bin": {
@@ -46,6 +46,7 @@
     "@babel/parser": "^7.29.7",
     "@vue/compiler-dom": "^3.5.39",
     "@vue/compiler-sfc": "^3.5.39",
+    "commander": "^12.1.0",
     "fast-glob": "^3.3.3"
   },
   "devDependencies": {

package/src/check-hardcoded.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import fg from 'fast-glob';
+import { appError } from './errors.js';
 import { scanJsSource } from './source/scan-js-source.js';
 import { scanVueSfc } from './source/scan-vue-sfc.js';
 
@@ -20,7 +21,7 @@ export async function checkHardcodedStrings(config, baseDir) {
   });
 
   if (files.length === 0) {
-    throw new Error(`No source files matched: ${config.source.join(', ')}`);
+    throw appError(`No source files matched: ${config.source.join(', ')}`, 'SOURCE_NOT_FOUND');
   }
 
   const issues = [];

package/src/cli.js

@@ -1,7 +1,9 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { Command, InvalidArgumentError } from 'commander';
 import { applyBaseline, loadBaseline, writeBaseline } from './baseline.js';
 import { loadConfig, resolveConfigPath } from './config.js';
+import { appError } from './errors.js';
 import { flattenResults, renderCombinedReport, summarizeResults } from './reporters/combined.js';
 import { renderReport } from './reporters/index.js';
 import { enabledChecks, runChecks } from './run-checks.js';
@@ -33,44 +35,79 @@ Example:
 `;
 
 function parseArgs(argv) {
-  const args = argv.slice(2);
-  const command = args[0] && !args[0].startsWith('-') ? args.shift() : 'check-identical';
-  const options = { command, includeIgnored: false, help: false, updateBaseline: false };
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-
-    if (arg === '-h' || arg === '--help') {
-      options.help = true;
-    } else if (arg === '-c' || arg === '--config') {
-      options.configPath = args[++index];
-    } else if (arg === '--format') {
-      options.format = readChoice(args[++index], ['console', 'json', 'markdown', 'sarif'], 'format');
-    } else if (arg === '--fail-on') {
-      options.failOn = readChoice(args[++index], ['none', 'low', 'medium', 'high'], 'fail-on level');
-    } else if (arg === '--output') {
-      options.output = args[++index];
-    } else if (arg === '--baseline') {
-      options.baseline = args[++index];
-    } else if (arg === '--update-baseline') {
-      options.updateBaseline = true;
-    } else if (arg === '--include-ignored') {
-      options.includeIgnored = true;
-    } else {
-      throw new Error(`Unknown option: ${arg}`);
-    }
+  const program = new Command()
+    .name('i18n-smell-detector')
+    .usage('[command] [options]')
+    .description('Find localization issues that key coverage checks miss.')
+    .argument('[command]', 'check-identical | check-hardcoded | check-placeholders | check', 'check-identical')
+    .option('-c, --config <path>', 'Config file path')
+    .option('--format <format>', 'console | json | markdown | sarif', readFormat)
+    .option('--fail-on <level>', 'high | medium | low | none', readFailOn)
+    .option('--output <path>', 'Write the full report to a file')
+    .option('--baseline <path>', 'Read a baseline file')
+    .option('--update-baseline', 'Write the current issues to the baseline file', false)
+    .option('--include-ignored', 'Print ignored matches as well', false)
+    .addHelpText('after', `
+
+Example:
+  i18n-smell-detector check-identical -c i18n-smell.config.mjs --format markdown
+  i18n-smell-detector check-hardcoded -c i18n-smell.config.mjs --format json
+  i18n-smell-detector check-placeholders -c i18n-smell.config.mjs --format json`)
+    .exitOverride()
+    .configureOutput({
+      writeOut: () => {},
+      writeErr: () => {},
+      outputError: () => {},
+    });
+
+  try {
+    program.parse(argv, { from: 'node' });
+  } catch (error) {
+    if (error.code === 'commander.helpDisplayed') return { help: true };
+    throw appError(formatCommanderError(error), 'CLI_USAGE');
+  }
+
+  const [command] = program.args;
+  if (!['check-identical', 'check-hardcoded', 'check-placeholders', 'check'].includes(command)) {
+    throw appError(`Unknown command: ${command}\n${HELP}`, 'CLI_USAGE');
   }
 
-  return options;
+  return {
+    command,
+    configPath: program.opts().config,
+    format: program.opts().format,
+    failOn: program.opts().failOn,
+    output: program.opts().output,
+    baseline: program.opts().baseline,
+    updateBaseline: program.opts().updateBaseline,
+    includeIgnored: program.opts().includeIgnored,
+    help: false,
+  };
+}
+
+function readFormat(value) {
+  return readChoice(value, ['console', 'json', 'markdown', 'sarif'], 'format');
+}
+
+function readFailOn(value) {
+  return readChoice(value, ['none', 'low', 'medium', 'high'], 'fail-on level');
 }
 
 function readChoice(value, choices, name) {
-  if (!choices.includes(value)) {
-    throw new Error(`Unsupported ${name}: ${value}`);
-  }
+  if (!choices.includes(value)) throw new InvalidArgumentError(`Unsupported ${name}: ${value}`);
   return value;
 }
 
+function formatCommanderError(error) {
+  if (error.code === 'commander.unknownOption') return `Unknown option: ${extractQuotedValue(error.message) || error.optionName || ''}`.trim();
+  if (error.code === 'commander.missingArgument') return `Missing value for option: ${error.optionName?.() || ''}`.trim();
+  return error.message.replace(/^error: /, '');
+}
+
+function extractQuotedValue(value) {
+  return value.match(/'([^']+)'/)?.[1];
+}
+
 export async function runCli(argv) {
   const options = parseArgs(argv);
 
@@ -79,10 +116,6 @@ export async function runCli(argv) {
     return;
   }
 
-  if (!['check-identical', 'check-hardcoded', 'check-placeholders', 'check'].includes(options.command)) {
-    throw new Error(`Unknown command: ${options.command}\n${HELP}`);
-  }
-
   const configPath = await resolveConfigPath(options.configPath, process.cwd());
   const config = await loadConfig(configPath);
   const effectiveConfig = {
@@ -99,7 +132,7 @@ export async function runCli(argv) {
   const rawResults = await runChecks(effectiveConfig, configDir, checks);
 
   if (options.updateBaseline) {
-    if (!effectiveConfig.baseline) throw new Error('Baseline path is required for --update-baseline');
+    if (!effectiveConfig.baseline) throw appError('Baseline path is required for --update-baseline', 'CLI_USAGE');
     const baselinePath = resolveFromConfigDir(effectiveConfig.baseline, configDir);
     const count = await writeBaseline(baselinePath, rawResults);
     console.log(`Baseline updated: ${effectiveConfig.baseline} (${count} issues)`);
@@ -164,7 +197,7 @@ async function writeOutput(filePath, report) {
     await mkdir(path.dirname(filePath), { recursive: true });
     await writeFile(filePath, report);
   } catch (error) {
-    throw new Error(`Failed to write report file: ${filePath}\nReason: ${error.message}`);
+    throw appError(`Failed to write report file: ${filePath}\nReason: ${error.message}`, 'OUTPUT_WRITE_FAILED');
   }
 }
 

package/src/config.js

@@ -2,6 +2,7 @@ import { access } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
+import { appError } from './errors.js';
 
 const require = createRequire(import.meta.url);
 
@@ -51,7 +52,7 @@ async function exists(filePath) {
 export async function resolveConfigPath(explicitPath, cwd) {
   if (explicitPath) {
     const absolute = path.isAbsolute(explicitPath) ? explicitPath : path.resolve(cwd, explicitPath);
-    if (!(await exists(absolute))) throw new Error(`Config file not found: ${absolute}`);
+    if (!(await exists(absolute))) throw appError(`Config file not found: ${absolute}`, 'CONFIG_NOT_FOUND');
     return absolute;
   }
 
@@ -60,7 +61,7 @@ export async function resolveConfigPath(explicitPath, cwd) {
     if (await exists(absolute)) return absolute;
   }
 
-  throw new Error(`Config file not found. Expected one of: ${CONFIG_FILES.join(', ')}`);
+  throw appError(`Config file not found. Expected one of: ${CONFIG_FILES.join(', ')}`, 'CONFIG_NOT_FOUND');
 }
 
 export async function loadConfig(configPath) {
@@ -79,21 +80,21 @@ export async function loadConfig(configPath) {
 
 function validateConfig(config) {
   if (!config || typeof config !== 'object') {
-    throw new Error('Config must export an object');
+    throw appError('Config must export an object', 'CONFIG_INVALID');
   }
 
   const candidate = /** @type {Record<string, unknown>} */ (config);
   if ('baseLocale' in candidate && (typeof candidate.baseLocale !== 'string' || !candidate.baseLocale)) {
-    throw new Error('Config baseLocale must be a non-empty string');
+    throw appError('Config baseLocale must be a non-empty string', 'CONFIG_INVALID');
   }
 
   if ('locales' in candidate && (!candidate.locales || typeof candidate.locales !== 'object' || Array.isArray(candidate.locales))) {
-    throw new Error('Config locales must be an object');
+    throw appError('Config locales must be an object', 'CONFIG_INVALID');
   }
 
   for (const [locale, value] of Object.entries(candidate.locales || {})) {
     if (typeof value !== 'string' || !value) {
-      throw new Error(`Config locales.${locale} must be a file path string`);
+      throw appError(`Config locales.${locale} must be a file path string`, 'CONFIG_INVALID');
     }
   }
 
@@ -101,45 +102,45 @@ function validateConfig(config) {
   validateRuleList(candidate.allowIdenticalValues, 'allowIdenticalValues');
 
   if ('placeholderPatterns' in candidate && !Array.isArray(candidate.placeholderPatterns)) {
-    throw new Error('Config placeholderPatterns must be an array of strings or RegExp objects');
+    throw appError('Config placeholderPatterns must be an array of strings or RegExp objects', 'CONFIG_INVALID');
   }
 
   if ('source' in candidate && !isStringArray(candidate.source)) {
-    throw new Error('Config source must be an array of glob strings');
+    throw appError('Config source must be an array of glob strings', 'CONFIG_INVALID');
   }
 
   if ('hardcoded' in candidate && (!candidate.hardcoded || typeof candidate.hardcoded !== 'object' || Array.isArray(candidate.hardcoded))) {
-    throw new Error('Config hardcoded must be an object');
+    throw appError('Config hardcoded must be an object', 'CONFIG_INVALID');
   }
 
   if ('checks' in candidate && (!candidate.checks || typeof candidate.checks !== 'object' || Array.isArray(candidate.checks))) {
-    throw new Error('Config checks must be an object');
+    throw appError('Config checks must be an object', 'CONFIG_INVALID');
   }
 
   if ('format' in candidate && !['console', 'json', 'markdown', 'sarif'].includes(candidate.format)) {
-    throw new Error('Config format must be console, json, markdown, or sarif');
+    throw appError('Config format must be console, json, markdown, or sarif', 'CONFIG_INVALID');
   }
 
   if ('output' in candidate && typeof candidate.output !== 'string') {
-    throw new Error('Config output must be a file path string');
+    throw appError('Config output must be a file path string', 'CONFIG_INVALID');
   }
 
   if ('baseline' in candidate && typeof candidate.baseline !== 'string') {
-    throw new Error('Config baseline must be a file path string');
+    throw appError('Config baseline must be a file path string', 'CONFIG_INVALID');
   }
 
   const hardcoded = /** @type {Record<string, unknown>} */ (candidate.hardcoded || {});
   if ('vueAttributes' in hardcoded && !isStringArray(hardcoded.vueAttributes)) {
-    throw new Error('Config hardcoded.vueAttributes must be an array of strings');
+    throw appError('Config hardcoded.vueAttributes must be an array of strings', 'CONFIG_INVALID');
   }
   if ('jsxAttributes' in hardcoded && !isStringArray(hardcoded.jsxAttributes)) {
-    throw new Error('Config hardcoded.jsxAttributes must be an array of strings');
+    throw appError('Config hardcoded.jsxAttributes must be an array of strings', 'CONFIG_INVALID');
   }
   if ('functions' in hardcoded && !isStringArray(hardcoded.functions)) {
-    throw new Error('Config hardcoded.functions must be an array of strings');
+    throw appError('Config hardcoded.functions must be an array of strings', 'CONFIG_INVALID');
   }
   if ('ignoreFiles' in hardcoded && !isStringArray(hardcoded.ignoreFiles)) {
-    throw new Error('Config hardcoded.ignoreFiles must be an array of glob strings');
+    throw appError('Config hardcoded.ignoreFiles must be an array of glob strings', 'CONFIG_INVALID');
   }
   validateRuleList(hardcoded.ignoreValues, 'hardcoded.ignoreValues');
   validateRuleList(hardcoded.ignorePatterns, 'hardcoded.ignorePatterns');
@@ -157,12 +158,6 @@ function withDefaults(config) {
     ignoreCase: false,
     includeIgnored: false,
     failOn: 'high',
-    checks: {
-      identical: true,
-      hardcoded: true,
-      placeholders: true,
-      ...(config.checks || {}),
-    },
     ...config,
     checks: {
       identical: true,
@@ -183,11 +178,11 @@ function isStringArray(value) {
 
 function validateRuleList(rules, name) {
   if (rules === undefined) return;
-  if (!Array.isArray(rules)) throw new Error(`Config ${name} must be an array`);
+  if (!Array.isArray(rules)) throw appError(`Config ${name} must be an array`, 'CONFIG_INVALID');
 
   for (const rule of rules) {
     if (typeof rule !== 'string' && !(rule instanceof RegExp)) {
-      throw new Error(`Config ${name} entries must be strings or RegExp objects`);
+      throw appError(`Config ${name} entries must be strings or RegExp objects`, 'CONFIG_INVALID');
     }
   }
 }
@@ -197,15 +192,15 @@ function normalizePlaceholderPatterns(patterns) {
     if (pattern instanceof RegExp) return withGlobalFlag(pattern);
 
     if (typeof pattern !== 'string') {
-      throw new Error('Config placeholderPatterns entries must be strings or RegExp objects');
+      throw appError('Config placeholderPatterns entries must be strings or RegExp objects', 'CONFIG_INVALID');
     }
 
     try {
       return new RegExp(pattern, 'g');
     } catch (error) {
-      throw new Error(`Invalid placeholder pattern "${pattern}": ${error.message}`);
+      throw appError(`Invalid placeholder pattern "${pattern}": ${error.message}`, 'CONFIG_INVALID');
     }
-  });
+  }).sort((a, b) => b.source.length - a.source.length);
 }
 
 function normalizeHardcodedConfig(config) {
@@ -223,13 +218,13 @@ function normalizeRegexRules(rules, name) {
   return rules.map((rule) => {
     if (rule instanceof RegExp) return rule;
     if (typeof rule !== 'string') {
-      throw new Error(`Config ${name} entries must be strings or RegExp objects`);
+      throw appError(`Config ${name} entries must be strings or RegExp objects`, 'CONFIG_INVALID');
     }
 
     try {
       return new RegExp(rule);
     } catch (error) {
-      throw new Error(`Invalid ${name} pattern "${rule}": ${error.message}`);
+      throw appError(`Invalid ${name} pattern "${rule}": ${error.message}`, 'CONFIG_INVALID');
     }
   });
 }

package/src/errors.js

@@ -0,0 +1,11 @@
+export class AppError extends Error {
+  constructor(message, code = 'APP_ERROR') {
+    super(message);
+    this.name = 'AppError';
+    this.code = code;
+  }
+}
+
+export function appError(message, code) {
+  return new AppError(message, code);
+}

package/src/reporters/markdown.js

@@ -1,7 +1,11 @@
 import { summarizeIssues } from './summary.js';
 
 function escapeCell(value) {
-  return String(value).replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\n/g, '<br>');
+  return String(value)
+    .replace(/\r?\n/g, ' ')
+    .replace(/\\/g, '\\\\')
+    .replace(/\|/g, '\\|')
+    .replace(/[*_`[\]]/g, '\\$&');
 }
 
 export function renderMarkdownReport(issues, options) {

package/src/rules/classify-identical.js

@@ -21,9 +21,7 @@ function isCodeLike(value) {
 function isPlaceholderOnly(value, patterns) {
   let text = value.trim();
 
-  const orderedPatterns = [...(patterns || [])].sort((a, b) => b.source.length - a.source.length);
-
-  for (const pattern of orderedPatterns) {
+  for (const pattern of patterns || []) {
     pattern.lastIndex = 0;
     text = text.replace(pattern, '');
   }