i18n-smell-detector 0.3.0 → 0.4.0

package/README.md

@@ -28,6 +28,7 @@ npm install -D i18n-smell-detector
 Run the check:
 
 ```bash
+npx i18n-smell-detector check --config i18n-smell.config.mjs
 npx i18n-smell-detector check-identical --config i18n-smell.config.mjs
 npx i18n-smell-detector check-hardcoded --config i18n-smell.config.mjs
 ```
@@ -39,20 +40,82 @@ npx i18n-smell-detector check-identical --format console
 npx i18n-smell-detector check-identical --format json
 npx i18n-smell-detector check-identical --format markdown
 npx i18n-smell-detector check-hardcoded --format json
+npx i18n-smell-detector check --format markdown --output i18n-report.md
 ```
 
+CLI options:
+
+| Option | Description |
+|---|---|
+| `-c, --config <path>` | Use a specific config file. |
+| `--format <format>` | Print `console`, `json`, or `markdown` output. |
+| `--fail-on <level>` | Exit with code `1` for findings at `high`, `medium`, or `low`. Use `none` while tuning. |
+| `--include-ignored` | Include ignored findings in the report. |
+| `--output <path>` | Write the full report to a file and print a short summary. |
+| `--baseline <path>` | Suppress findings stored in a baseline file. |
+| `--update-baseline` | Write the current findings to the baseline file. |
+| `-h, --help` | Show CLI help. |
+
 ## CI usage
 
 Use `--fail-on` to choose the lowest severity that should make the command exit with code `1`.
 
 ```bash
-npx i18n-smell-detector check-identical --config i18n-smell.config.mjs --fail-on high
+npx i18n-smell-detector check --config i18n-smell.config.mjs --fail-on high
 ```
 
 For a new project, it is often easier to start in reporting mode while tuning allowlists:
 
 ```bash
-npx i18n-smell-detector check-identical --config i18n-smell.config.mjs --fail-on none
+npx i18n-smell-detector check --config i18n-smell.config.mjs --fail-on none
+```
+
+### GitHub Actions example
+
+Add a workflow such as `.github/workflows/i18n-smell.yml`:
+
+```yaml
+name: i18n smell check
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  i18n-smell:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - run: npm ci
+
+      - name: Run i18n checks
+        run: npx i18n-smell-detector check --config i18n-smell.config.mjs --fail-on high
+
+      - name: Write Markdown report
+        if: always()
+        run: npx i18n-smell-detector check --config i18n-smell.config.mjs --format markdown --output reports/i18n-smell.md --fail-on none
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: i18n-smell-report
+          path: reports/i18n-smell.md
+```
+
+For this repository, the local smoke commands are:
+
+```bash
+npm test
+npm run check
+npm run example:basic
+node bin/i18n-smell-detector.js --help
 ```
 
 ## Configuration
@@ -62,6 +125,10 @@ Create `i18n-smell.config.mjs`:
 ```js
 export default {
   baseLocale: 'en',
+  checks: {
+    identical: true,
+    hardcoded: true
+  },
   source: [
     'src/**/*.vue'
   ],
@@ -117,6 +184,8 @@ export default {
   trimWhitespace: true,
   ignoreCase: false,
   includeIgnored: false,
+  format: 'console',
+  baseline: '.i18n-smell-baseline.json',
   failOn: 'high'
 };
 ```
@@ -126,6 +195,7 @@ export default {
 | Option | Type | Default | Description |
 |---|---|---:|---|
 | `baseLocale` | `string` | `'en'` | Locale used as the comparison source. It must also be listed in `locales`. |
+| `checks` | `{ identical?: boolean, hardcoded?: boolean }` | both enabled | Checks run by the combined `check` command. Existing single-check commands ignore this setting. |
 | `source` | `string[]` | `['src/**/*.vue']` | Source globs used by `check-hardcoded`. `node_modules` is ignored. |
 | `locales` | `Record<string, string>` | `{}` | Map of locale codes to JSON locale file paths. Relative paths are resolved from the config file directory. |
 | `allowIdenticalKeys` | `(string \| RegExp)[]` | `[]` | Key rules that are allowed to match the base locale. String rules support `*` wildcards, for example `brand.*`. `RegExp` rules are tested against the flattened key. |
@@ -140,6 +210,9 @@ export default {
 | `ignoreCase` | `boolean` | `false` | Compare values case-insensitively when set to `true`. |
 | `ignoreSameLanguageFamily` | `boolean` | `true` | Ignore regional variants that share the same language family, such as `en` and `en-GB`. Set to `false` to check regional variants too. |
 | `includeIgnored` | `boolean` | `false` | Include ignored findings in reports. Can also be enabled with `--include-ignored`. |
+| `format` | `'console' \| 'json' \| 'markdown'` | `'console'` | Default report format. CLI `--format` takes precedence. |
+| `output` | `string` | unset | Report file path. CLI `--output` takes precedence. |
+| `baseline` | `string` | unset | Baseline file path used by `--baseline` or `--update-baseline`. |
 
 ## Example output
 
@@ -241,6 +314,69 @@ JSON output includes source locations:
 }
 ```
 
+## Running All Checks
+
+Use `check` to run every enabled check in one command:
+
+```bash
+npx i18n-smell-detector check --config i18n-smell.config.mjs
+```
+
+Disable checks during gradual rollout:
+
+```js
+export default {
+  checks: {
+    identical: true,
+    hardcoded: false
+  }
+};
+```
+
+Combined JSON output groups counts by check:
+
+```json
+{
+  "summary": {
+    "identical": {
+      "high": 2,
+      "medium": 1,
+      "low": 0,
+      "ignored": 16
+    },
+    "hardcoded": {
+      "high": 3,
+      "medium": 2,
+      "low": 0,
+      "ignored": 3
+    }
+  },
+  "issues": []
+}
+```
+
+## Writing Reports
+
+Use `--output` to write the full report to a file. The CLI prints a short summary to stdout after writing.
+
+```bash
+npx i18n-smell-detector check --format markdown --output reports/i18n-report.md
+npx i18n-smell-detector check --format json --output reports/i18n-report.json
+```
+
+Markdown output for `check` includes a summary table and one section per check, which makes it suitable for CI artifacts.
+
+## Gradual Adoption
+
+Use a baseline to ignore existing findings while still failing CI for new ones:
+
+```bash
+npx i18n-smell-detector check --baseline .i18n-smell-baseline.json --update-baseline
+npx i18n-smell-detector check --baseline .i18n-smell-baseline.json
+```
+
+The baseline stores stable issue identifiers. Updating it removes findings that no longer exist and records the current visible findings.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -326,6 +462,7 @@ Useful tuning patterns:
 npm install
 npm test
 npm run check
+npm run example:basic
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18n-smell-detector",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Find locale values copied from the base locale.",
   "type": "module",
   "bin": {
@@ -21,9 +21,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "check": "npm run check:identical && npm run check:hardcoded",
+    "check": "node ./bin/i18n-smell-detector.js check --config ./examples/vue-vite/i18n-smell.config.mjs --fail-on none",
     "check:identical": "node ./bin/i18n-smell-detector.js check-identical --config ./examples/vue-vite/i18n-smell.config.mjs --fail-on none",
     "check:hardcoded": "node ./bin/i18n-smell-detector.js check-hardcoded --config ./examples/vue-vite/i18n-smell.config.mjs --fail-on none",
+    "example:basic": "node ./bin/i18n-smell-detector.js check --config ./examples/basic/i18n-smell.config.mjs --fail-on none",
     "test": "node --test"
   },
   "keywords": [

package/src/baseline.js

@@ -0,0 +1,75 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export function issueId(check, issue) {
+  if (check === 'identical') return `identical:${issue.targetLocale}:${issue.key}`;
+  return `hardcoded:${issue.file}:${issue.line}:${issue.column}:${issue.value}`;
+}
+
+export async function loadBaseline(filePath) {
+  if (!filePath) return new Set();
+
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') return new Set();
+    throw new Error(`Failed to read baseline file: ${filePath}\nReason: ${error.message}`);
+  }
+
+  if (!parsed || !Array.isArray(parsed.issues)) {
+    throw new Error(`Invalid baseline file: ${filePath}`);
+  }
+
+  return new Set(parsed.issues.map((issue) => issue.id).filter(Boolean));
+}
+
+export function applyBaseline(results, ids) {
+  if (!ids.size) return results;
+
+  return results.map((result) => ({
+    ...result,
+    issues: result.issues.map((issue) => {
+      const id = issueId(result.check, issue);
+      if (!ids.has(id)) return { ...issue, id };
+      return { ...issue, id, severity: 'ignored', reason: 'baseline' };
+    }),
+  }));
+}
+
+export async function writeBaseline(filePath, results) {
+  const issues = [];
+
+  for (const result of results) {
+    for (const issue of result.issues) {
+      if (issue.severity === 'ignored') continue;
+      issues.push(toBaselineIssue(result.check, issue));
+    }
+  }
+
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify({ version: 1, issues }, null, 2)}\n`);
+  return issues.length;
+}
+
+function toBaselineIssue(check, issue) {
+  const base = {
+    id: issueId(check, issue),
+    value: issue.value,
+  };
+
+  if (check === 'identical') {
+    return {
+      ...base,
+      key: issue.key,
+      targetLocale: issue.targetLocale,
+    };
+  }
+
+  return {
+    ...base,
+    file: issue.file,
+    line: issue.line,
+    column: issue.column,
+  };
+}

package/src/cli.js

@@ -1,9 +1,10 @@
+import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { checkHardcodedStrings } from './check-hardcoded.js';
-import { checkIdenticalTranslations } from './check-identical.js';
+import { applyBaseline, loadBaseline, writeBaseline } from './baseline.js';
 import { loadConfig, resolveConfigPath } from './config.js';
-import { loadFlattenedLocales } from './locale/load-locales.js';
+import { flattenResults, renderCombinedReport, summarizeResults } from './reporters/combined.js';
 import { renderReport } from './reporters/index.js';
+import { enabledChecks, runChecks } from './run-checks.js';
 import { failRank, severityRank } from './severity.js';
 
 const HELP = `
@@ -18,6 +19,9 @@ Options:
   -c, --config <path>       Config file path
   --format <format>         console | json | markdown  (default: console)
   --fail-on <level>         high | medium | low | none (default: config.failOn or high)
+  --output <path>           Write the full report to a file
+  --baseline <path>         Read a baseline file
+  --update-baseline         Write the current issues to the baseline file
   --include-ignored         Print ignored matches as well
   -h, --help                Show help
 
@@ -29,7 +33,7 @@ Example:
 function parseArgs(argv) {
   const args = argv.slice(2);
   const command = args[0] && !args[0].startsWith('-') ? args.shift() : 'check-identical';
-  const options = { command, format: 'console', includeIgnored: false, help: false };
+  const options = { command, includeIgnored: false, help: false, updateBaseline: false };
 
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
@@ -42,6 +46,12 @@ function parseArgs(argv) {
       options.format = readChoice(args[++index], ['console', 'json', 'markdown'], '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 {
@@ -76,24 +86,88 @@ export async function runCli(argv) {
   const effectiveConfig = {
     ...config,
     failOn: options.failOn || config.failOn || 'high',
+    format: options.format || config.format || 'console',
+    output: options.output || config.output,
+    baseline: options.baseline || config.baseline,
     includeIgnored: options.includeIgnored || config.includeIgnored || false,
   };
 
   const configDir = path.dirname(configPath);
-  const isHardcoded = options.command === 'check-hardcoded';
-  const issues = isHardcoded
-    ? await checkHardcodedStrings(effectiveConfig, configDir)
-    : checkIdenticalTranslations(await loadFlattenedLocales(effectiveConfig, configDir), effectiveConfig);
+  const checks = commandChecks(options.command, effectiveConfig);
+  const rawResults = await runChecks(effectiveConfig, configDir, checks);
+
+  if (options.updateBaseline) {
+    if (!effectiveConfig.baseline) throw new Error('Baseline path is required for --update-baseline');
+    const baselinePath = resolveFromConfigDir(effectiveConfig.baseline, configDir);
+    const count = await writeBaseline(baselinePath, rawResults);
+    console.log(`Baseline updated: ${effectiveConfig.baseline} (${count} issues)`);
+    return;
+  }
 
-  console.log(renderReport(issues, {
-    format: options.format,
+  const baselineIds = await loadBaseline(resolveOptional(effectiveConfig.baseline, configDir));
+  const results = applyBaseline(rawResults, baselineIds);
+  const reportOptions = {
+    format: effectiveConfig.format,
     includeIgnored: effectiveConfig.includeIgnored || false,
-    title: isHardcoded ? 'hardcoded strings' : 'identical translations',
-    heading: isHardcoded ? 'Hardcoded strings' : 'Identical translations',
-    emptyMessage: isHardcoded ? 'No hardcoded strings found.' : 'No copied base-locale values found.',
-  }));
+  };
+  const report = options.command === 'check'
+    ? renderCombinedReport(results, reportOptions)
+    : renderSingleReport(results[0], reportOptions);
+
+  if (effectiveConfig.output) {
+    await writeOutput(resolveFromConfigDir(effectiveConfig.output, configDir), report);
+    console.log(renderWriteSummary(results, effectiveConfig.output));
+  } else {
+    console.log(report);
+  }
 
-  const visible = effectiveConfig.includeIgnored ? issues : issues.filter((issue) => issue.severity !== 'ignored');
+  const visible = options.command === 'check'
+    ? flattenResults(results, { includeIgnored: effectiveConfig.includeIgnored || false })
+    : visibleIssues(results[0].issues, effectiveConfig.includeIgnored || false);
   const shouldFail = visible.some((issue) => severityRank[issue.severity] >= failRank(effectiveConfig.failOn || 'high'));
   if (shouldFail) process.exit(1);
 }
+
+function commandChecks(command, config) {
+  if (command === 'check-identical') return ['identical'];
+  if (command === 'check-hardcoded') return ['hardcoded'];
+  return enabledChecks(config);
+}
+
+function renderSingleReport(result, options) {
+  return renderReport(result.issues, {
+    ...options,
+    title: result.title,
+    heading: result.heading,
+    emptyMessage: result.emptyMessage,
+  });
+}
+
+function visibleIssues(issues, includeIgnored) {
+  return includeIgnored ? issues : issues.filter((issue) => issue.severity !== 'ignored');
+}
+
+function resolveFromConfigDir(filePath, configDir) {
+  return path.isAbsolute(filePath) ? filePath : path.resolve(configDir, filePath);
+}
+
+function resolveOptional(filePath, configDir) {
+  return filePath ? resolveFromConfigDir(filePath, configDir) : undefined;
+}
+
+async function writeOutput(filePath, report) {
+  try {
+    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}`);
+  }
+}
+
+function renderWriteSummary(results, output) {
+  const summary = summarizeResults(results);
+  const counts = Object.entries(summary)
+    .map(([check, item]) => `${check}: high=${item.high} medium=${item.medium} low=${item.low} ignored=${item.ignored}`)
+    .join('; ');
+  return `Report written to ${output}\n${counts}`;
+}

package/src/config.js

@@ -98,6 +98,22 @@ function validateConfig(config) {
     throw new Error('Config hardcoded must be an object');
   }
 
+  if ('checks' in candidate && (!candidate.checks || typeof candidate.checks !== 'object' || Array.isArray(candidate.checks))) {
+    throw new Error('Config checks must be an object');
+  }
+
+  if ('format' in candidate && !['console', 'json', 'markdown'].includes(candidate.format)) {
+    throw new Error('Config format must be console, json, or markdown');
+  }
+
+  if ('output' in candidate && typeof candidate.output !== 'string') {
+    throw new Error('Config output must be a file path string');
+  }
+
+  if ('baseline' in candidate && typeof candidate.baseline !== 'string') {
+    throw new Error('Config baseline must be a file path string');
+  }
+
   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');
@@ -118,7 +134,17 @@ function withDefaults(config) {
     ignoreCase: false,
     includeIgnored: false,
     failOn: 'high',
+    checks: {
+      identical: true,
+      hardcoded: true,
+      ...(config.checks || {}),
+    },
     ...config,
+    checks: {
+      identical: true,
+      hardcoded: true,
+      ...(config.checks || {}),
+    },
     source: config.source || ['src/**/*.vue'],
     hardcoded: normalizeHardcodedConfig(config.hardcoded || {}),
     placeholderPatterns: normalizePlaceholderPatterns(config.placeholderPatterns || DEFAULT_PLACEHOLDER_PATTERNS),

package/src/reporters/combined.js

@@ -0,0 +1,66 @@
+import { renderConsoleReport } from './console.js';
+import { renderMarkdownReport } from './markdown.js';
+import { summarizeIssues } from './summary.js';
+
+export function renderCombinedReport(results, options) {
+  if (options.format === 'json') return renderCombinedJson(results, options);
+  if (options.format === 'markdown') return renderCombinedMarkdown(results, options);
+  return renderCombinedConsole(results, options);
+}
+
+export function flattenResults(results, options) {
+  return results.flatMap((result) => {
+    const issues = options.includeIgnored ? result.issues : result.issues.filter((issue) => issue.severity !== 'ignored');
+    return issues.map((issue) => ({ check: result.check, ...issue }));
+  });
+}
+
+export function summarizeResults(results) {
+  return Object.fromEntries(results.map((result) => [result.check, summarizeIssues(result.issues)]));
+}
+
+function renderCombinedJson(results, options) {
+  return `${JSON.stringify({
+    summary: summarizeResults(results),
+    issues: flattenResults(results, options),
+  }, null, 2)}\n`;
+}
+
+function renderCombinedConsole(results, options) {
+  return results.map((result) => renderConsoleReport(result.issues, {
+    ...options,
+    title: result.title,
+    emptyMessage: result.emptyMessage,
+  })).join('\n\n');
+}
+
+function renderCombinedMarkdown(results, options) {
+  const lines = [
+    '# i18n-smell-detector report',
+    '',
+    '## Summary',
+    '',
+    '| Check | High | Medium | Low | Ignored |',
+    '|---|---:|---:|---:|---:|',
+  ];
+
+  for (const result of results) {
+    const summary = summarizeIssues(result.issues);
+    lines.push(`| ${result.check} | ${summary.high} | ${summary.medium} | ${summary.low} | ${summary.ignored} |`);
+  }
+
+  for (const result of results) {
+    lines.push('');
+    lines.push(asSection(renderMarkdownReport(result.issues, {
+      ...options,
+      heading: result.heading,
+      emptyMessage: result.emptyMessage,
+    }).trim()));
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function asSection(markdown) {
+  return markdown.replace(/^# /, '## ');
+}

package/src/run-checks.js

@@ -0,0 +1,35 @@
+import { checkHardcodedStrings } from './check-hardcoded.js';
+import { checkIdenticalTranslations } from './check-identical.js';
+import { loadFlattenedLocales } from './locale/load-locales.js';
+
+const CHECK_META = {
+  identical: {
+    title: 'identical translations',
+    heading: 'Identical translations',
+    emptyMessage: 'No copied base-locale values found.',
+  },
+  hardcoded: {
+    title: 'hardcoded strings',
+    heading: 'Hardcoded strings',
+    emptyMessage: 'No hardcoded strings found.',
+  },
+};
+
+export async function runChecks(config, configDir, names) {
+  const results = [];
+
+  for (const check of names) {
+    if (check === 'identical') {
+      const locales = await loadFlattenedLocales(config, configDir);
+      results.push({ check, ...CHECK_META[check], issues: checkIdenticalTranslations(locales, config) });
+    } else if (check === 'hardcoded') {
+      results.push({ check, ...CHECK_META[check], issues: await checkHardcodedStrings(config, configDir) });
+    }
+  }
+
+  return results;
+}
+
+export function enabledChecks(config) {
+  return ['identical', 'hardcoded'].filter((check) => config.checks[check]);
+}

package/src/types.js

@@ -10,6 +10,10 @@
  * @property {(string | RegExp)[]=} placeholderPatterns
  * @property {string[]=} source
  * @property {{vueAttributes: string[], ignoreValues: (string | RegExp)[], ignorePatterns: RegExp[]}=} hardcoded
+ * @property {{identical: boolean, hardcoded: boolean}=} checks
+ * @property {ReportFormat=} format
+ * @property {string=} output
+ * @property {string=} baseline
  * @property {boolean=} ignoreCodeLike
  * @property {boolean=} ignoreSameLanguageFamily
  * @property {boolean=} trimWhitespace