i18n-smell-detector 0.5.2 → 0.6.1

package/README.md

@@ -27,11 +27,61 @@ Current scope: text classification is rule-based and conservative, so projects w
 npm install -D i18n-smell-detector
 ```
 
+## Quick Start
+
+Installing the package only adds the CLI. Generate a starter config in your project root:
+
+```bash
+npx i18n-smell-detector init
+```
+
+This creates `i18n-smell.config.mjs`. A typical config looks like this:
+
+```js
+export default {
+  baseLocale: 'en',
+  locales: {
+    en: './src/locales/en.json',
+    zh: './src/locales/zh.json',
+    'zh-Hans': './src/locales/zh-Hans.json'
+  },
+  source: [
+    'src/**/*.{vue,js,jsx,ts,tsx}'
+  ],
+  failOn: 'none'
+};
+```
+
+When possible, `init` discovers locale JSON files in common project directories and writes them into `locales` automatically. It checks the first matching directory from this list:
+
+- `src/locales`
+- `src/i18n`
+- `locales`
+- `i18n`
+
+For example, if `src/locales/en.json` and `src/locales/ja.json` exist, `init` writes both entries and uses `en` as `baseLocale`. If no locale JSON files are found in those directories, it falls back to a starter `en` and `zh` config. Locale keys that contain `-`, such as `'zh-Hans'`, must be quoted as shown above.
+
+Adjust `locales` and `source` if needed, then run:
+
+```bash
+npx i18n-smell-detector check --config i18n-smell.config.mjs --fail-on none
+```
+
+If your config file lives somewhere else, pass that path:
+
+```bash
+npx i18n-smell-detector init --config ./config/i18n-smell.config.mjs
+npx i18n-smell-detector check --config ./config/i18n-smell.config.mjs
+```
+
+`init` refuses to overwrite an existing config. Use `--force` only when you intentionally want to replace it. Locale and source paths inside the config are resolved relative to the config file. Locale discovery is intentionally conservative: it only checks direct `.json` files in the project directories listed above, and it does not scan unrelated JSON files elsewhere.
+
 ## Usage
 
 Run the check:
 
 ```bash
+npx i18n-smell-detector init
 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
@@ -117,7 +167,7 @@ jobs:
 
 ## Configuration
 
-Create `i18n-smell.config.mjs`:
+Create `i18n-smell.config.mjs` and adjust `locales` and `source` to match your project:
 
 ```js
 export default {
@@ -134,6 +184,7 @@ export default {
   locales: {
     en: './src/locales/en.json',
     zh: './src/locales/zh.json',
+    'zh-Hans': './src/locales/zh-Hans.json',
     ja: './src/locales/ja.json'
   },
 
@@ -478,7 +529,8 @@ export default {
   baseLocale: 'en',
   locales: {
     en: './src/locales/en.json',
-    zh: './src/locales/zh.json'
+    zh: './src/locales/zh.json',
+    'zh-Hans': './src/locales/zh-Hans.json'
   },
   allowIdenticalKeys: [
     'brand.*',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18n-smell-detector",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "Find copied locale values, placeholder mismatches, and hardcoded user-visible strings.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { access, mkdir, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { Command, InvalidArgumentError } from 'commander';
 import { applyBaseline, loadBaseline, writeBaseline } from './baseline.js';
@@ -17,6 +17,7 @@ Usage:
   i18n-smell-detector check-hardcoded [options]
   i18n-smell-detector check-placeholders [options]
   i18n-smell-detector check [options]
+  i18n-smell-detector init [options]
 
 Options:
   -c, --config <path>       Config file path
@@ -26,20 +27,44 @@ Options:
   --baseline <path>         Read a baseline file
   --update-baseline         Write the current issues to the baseline file
   --include-ignored         Print ignored matches as well
+  --force                   Overwrite an existing config file with init
   -h, --help                Show help
 
 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
+  i18n-smell-detector init
 `;
 
+const DEFAULT_CONFIG_PATH = 'i18n-smell.config.mjs';
+
+const DEFAULT_CONFIG_TEMPLATE = `export default {
+  baseLocale: 'en',
+  locales: {
+    en: './src/locales/en.json',
+    zh: './src/locales/zh.json'
+  },
+  source: [
+    'src/**/*.{vue,js,jsx,ts,tsx}'
+  ],
+  failOn: 'none'
+};
+`;
+
+const LOCALE_DIR_CANDIDATES = [
+  'src/locales',
+  'src/i18n',
+  'locales',
+  'i18n',
+];
+
 function parseArgs(argv) {
   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')
+    .argument('[command]', 'init | 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)
@@ -47,12 +72,14 @@ function parseArgs(argv) {
     .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)
+    .option('--force', 'Overwrite an existing config file with init', 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`)
+  i18n-smell-detector check-placeholders -c i18n-smell.config.mjs --format json
+  i18n-smell-detector init`)
     .exitOverride()
     .configureOutput({
       writeOut: () => {},
@@ -68,7 +95,7 @@ Example:
   }
 
   const [command] = program.args;
-  if (!['check-identical', 'check-hardcoded', 'check-placeholders', 'check'].includes(command)) {
+  if (!['help', 'init', 'check-identical', 'check-hardcoded', 'check-placeholders', 'check'].includes(command)) {
     throw appError(`Unknown command: ${command}\n${HELP}`, 'CLI_USAGE');
   }
 
@@ -81,6 +108,7 @@ Example:
     baseline: program.opts().baseline,
     updateBaseline: program.opts().updateBaseline,
     includeIgnored: program.opts().includeIgnored,
+    force: program.opts().force,
     help: false,
   };
 }
@@ -116,6 +144,11 @@ export async function runCli(argv) {
     return;
   }
 
+  if (options.command === 'init') {
+    await writeDefaultConfig(options.configPath || DEFAULT_CONFIG_PATH, process.cwd(), options.force);
+    return;
+  }
+
   const configPath = await resolveConfigPath(options.configPath, process.cwd());
   const config = await loadConfig(configPath);
   const effectiveConfig = {
@@ -201,6 +234,27 @@ async function writeOutput(filePath, report) {
   }
 }
 
+async function writeDefaultConfig(configPath, cwd, force) {
+  const target = path.isAbsolute(configPath) ? configPath : path.resolve(cwd, configPath);
+
+  if (!force && await exists(target)) {
+    throw appError(`Config file already exists: ${target}\nUse --force to overwrite it.`, 'CONFIG_EXISTS');
+  }
+
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, await createConfigTemplate(path.dirname(target)));
+  console.log(`Created ${path.relative(cwd, target) || target}`);
+}
+
+async function exists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function renderWriteSummary(results, output) {
   const summary = summarizeResults(results);
   const counts = Object.entries(summary)
@@ -208,3 +262,60 @@ function renderWriteSummary(results, output) {
     .join('; ');
   return `Report written to ${output}\n${counts}`;
 }
+
+async function createConfigTemplate(baseDir) {
+  const locales = await discoverLocaleFiles(baseDir);
+  if (locales.length === 0) return DEFAULT_CONFIG_TEMPLATE;
+
+  const baseLocale = locales.some((locale) => locale.name === 'en') ? 'en' : locales[0].name;
+  const localeLines = locales.map((locale, index) => {
+    const suffix = index === locales.length - 1 ? '' : ',';
+    return `    ${quoteProperty(locale.name)}: '${locale.path}'${suffix}`;
+  });
+
+  return `export default {
+  baseLocale: '${baseLocale}',
+  locales: {
+${localeLines.join('\n')}
+  },
+  source: [
+    'src/**/*.{vue,js,jsx,ts,tsx}'
+  ],
+  failOn: 'none'
+};
+`;
+}
+
+async function discoverLocaleFiles(baseDir) {
+  for (const dir of LOCALE_DIR_CANDIDATES) {
+    const absoluteDir = path.resolve(baseDir, dir);
+    let entries;
+    try {
+      entries = await readdir(absoluteDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    const locales = entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+      .map((entry) => {
+        const localeName = entry.name.slice(0, -'.json'.length);
+        const relativePath = toConfigPath(path.relative(baseDir, path.join(absoluteDir, entry.name)));
+        return { name: localeName, path: relativePath };
+      })
+      .sort((a, b) => a.name.localeCompare(b.name));
+
+    if (locales.length > 0) return locales;
+  }
+
+  return [];
+}
+
+function toConfigPath(relativePath) {
+  const normalized = relativePath.split(path.sep).join('/');
+  return normalized.startsWith('.') ? normalized : `./${normalized}`;
+}
+
+function quoteProperty(name) {
+  return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+}

package/src/config.js

@@ -40,6 +40,16 @@ const DEFAULT_SOURCE_GLOBS = [
   'src/**/*.{vue,js,jsx,ts,tsx}',
 ];
 
+const FAIL_ON_LEVELS = ['none', 'low', 'medium', 'high'];
+const BOOLEAN_OPTIONS = [
+  'ignoreSameLanguageFamily',
+  'trimWhitespace',
+  'ignoreCase',
+  'includeIgnored',
+  'ignoreCodeLike',
+];
+const CHECK_NAMES = ['identical', 'hardcoded', 'placeholders'];
+
 async function exists(filePath) {
   try {
     await access(filePath);
@@ -117,10 +127,27 @@ function validateConfig(config) {
     throw appError('Config checks must be an object', 'CONFIG_INVALID');
   }
 
+  const checks = /** @type {Record<string, unknown>} */ (candidate.checks || {});
+  for (const check of CHECK_NAMES) {
+    if (check in checks && typeof checks[check] !== 'boolean') {
+      throw appError(`Config checks.${check} must be a boolean`, 'CONFIG_INVALID');
+    }
+  }
+
   if ('format' in candidate && !['console', 'json', 'markdown', 'sarif'].includes(candidate.format)) {
     throw appError('Config format must be console, json, markdown, or sarif', 'CONFIG_INVALID');
   }
 
+  if ('failOn' in candidate && !FAIL_ON_LEVELS.includes(candidate.failOn)) {
+    throw appError('Config failOn must be high, medium, low, or none', 'CONFIG_INVALID');
+  }
+
+  for (const option of BOOLEAN_OPTIONS) {
+    if (option in candidate && typeof candidate[option] !== 'boolean') {
+      throw appError(`Config ${option} must be a boolean`, 'CONFIG_INVALID');
+    }
+  }
+
   if ('output' in candidate && typeof candidate.output !== 'string') {
     throw appError('Config output must be a file path string', 'CONFIG_INVALID');
   }

package/src/source/scan-js-source.js

@@ -36,6 +36,10 @@ function makeIssue({ file, loc, value, kind, baseReason, config }) {
 
 export async function scanJsSource(file, config) {
   const source = await readFile(file, 'utf8');
+  return scanJsText(source, { file, config });
+}
+
+export function scanJsText(source, { file, config, lineOffset = 0 }) {
   let ast;
 
   try {
@@ -60,7 +64,7 @@ export async function scanJsSource(file, config) {
 
         const issue = makeIssue({
           file,
-          loc: argument.loc,
+          loc: offsetLoc(argument.loc, lineOffset),
           value,
           kind: `js-call:${calleeName(node.callee)}`,
           baseReason: `static string passed to ${calleeName(node.callee)}`,
@@ -74,7 +78,7 @@ export async function scanJsSource(file, config) {
     if (node.type === 'JSXText') {
       const issue = makeIssue({
         file,
-        loc: node.loc,
+        loc: offsetLoc(node.loc, lineOffset),
         value: node.value,
         kind: 'jsx-text',
         baseReason: 'static JSX text',
@@ -90,7 +94,7 @@ export async function scanJsSource(file, config) {
 
       const issue = makeIssue({
         file,
-        loc: node.value.loc,
+        loc: offsetLoc(node.value.loc, lineOffset),
         value,
         kind: `jsx-attribute:${jsxName(node.name)}`,
         baseReason: `static ${jsxName(node.name)} attribute`,
@@ -103,6 +107,17 @@ export async function scanJsSource(file, config) {
   return issues;
 }
 
+function offsetLoc(loc, lineOffset) {
+  if (!lineOffset) return loc;
+  return {
+    ...loc,
+    start: {
+      ...loc.start,
+      line: loc.start.line + lineOffset,
+    },
+  };
+}
+
 function walk(node, visitor) {
   if (!node || typeof node.type !== 'string') return;
   visitor(node);

package/src/source/scan-vue-sfc.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { parse } from '@vue/compiler-sfc';
+import { scanJsText } from './scan-js-source.js';
 import { scanVueTemplate } from './scan-vue-template.js';
 
 function lineOffsetBefore(source, offset) {
@@ -15,12 +16,25 @@ export async function scanVueSfc(file, config) {
     throw new Error(`Malformed Vue file ${file}: ${error.message || String(error)}`);
   }
 
-  const template = result.descriptor.template;
-  if (!template) return [];
+  const issues = [];
+  const { template, script, scriptSetup } = result.descriptor;
 
-  return scanVueTemplate(template.content, {
-    file,
-    lineOffset: lineOffsetBefore(source, template.loc.start.offset),
-    config,
-  });
+  if (template) {
+    issues.push(...scanVueTemplate(template.content, {
+      file,
+      lineOffset: lineOffsetBefore(source, template.loc.start.offset),
+      config,
+    }));
+  }
+
+  for (const block of [script, scriptSetup]) {
+    if (!block) continue;
+    issues.push(...scanJsText(block.content, {
+      file,
+      lineOffset: lineOffsetBefore(source, block.loc.start.offset),
+      config,
+    }));
+  }
+
+  return issues;
 }