@chaoswise/intl 3.1.0 → 3.1.2

package/bin/chaoswise-intl.js

@@ -4,8 +4,9 @@ const runUpdate = require('./scripts/update');
 const runInitConfig = require('./scripts/initConfig');
 const runAddLocale = require('./scripts/addLocale');
 const runNoZhCn = require('./scripts/nozhcn');
+const runVerify = require('./scripts/verify');
 
-const SCRIPTS = ['intl', 'collect', 'update', 'nozhcn', 'addLocale', 'init'];
+const SCRIPTS = ['intl', 'collect', 'update', 'nozhcn', 'addLocale', 'init', 'verify'];
 
 const args = process.argv.slice(2);
 
@@ -24,6 +25,20 @@ if (script === 'update') {
 if (script === 'addLocale') {
   runAddLocale();
 }
+// verify: 检测代码中所有 intl.get('id') 是否都在 relationKey.json 或本地 locale 文件中
+// Usage:
+//   chaoswise-intl verify              → 发现孤立 id 时 exit(1)（CI 门禁）
+//   chaoswise-intl verify --warn       → 仅警告，不 exit(1)
+//   chaoswise-intl verify fix          → 将孤立 id 的 intl 调用降级回字符串字面量（downgrade 策略）
+if (script === 'verify') {
+  const subCommand = args[scriptIndex + 1];
+  if (subCommand === 'fix') {
+    runVerify.fix();
+  } else {
+    const exitOnMissing = !args.includes('--warn');
+    runVerify({ exitOnMissing });
+  }
+}
 // nozhcn: detect (and optionally fix) Chinese characters in source files
 // Usage:
 //   chaoswise-intl nozhcn           → check mode  (CI gate, exit 1 on findings)

package/bin/scripts/util/makeVisitorDowngrade.js

@@ -0,0 +1,82 @@
+const t = require('@babel/types');
+
+/**
+ * makeVisitorDowngrade
+ *
+ * 将代码中所有孤立 id（missingIdSet 中的 id）的 intl 调用降级回原始字符串字面量，
+ * 便于后续重新执行 collect → update 完成国际化。
+ *
+ * 支持两种形态：
+ *
+ *   形态 A（有 .d() 兜底）：
+ *     intl.get('orphan-id').d('确认提交')
+ *     → '确认提交'
+ *
+ *   形态 B（裸 id，无默认文案）：
+ *     intl.get('orphan-id')
+ *     → 无法恢复文案，记录到 noDefaultIds，由调用方输出警告，代码不修改
+ *
+ * @param {{ i18nObject, i18nMethod, i18nDefaultFunctionKey }} opts  来自 conf
+ * @param {{ missingIdSet: Set<string>, noDefaultIds: string[] }} returns
+ */
+module.exports = function makeVisitorDowngrade(
+  { i18nObject, i18nMethod, i18nDefaultFunctionKey },
+  returns
+) {
+  const { missingIdSet, noDefaultIds } = returns;
+
+  /**
+   * 判断一个节点是否是 intl.get('xxx') 调用，
+   * 返回第一个参数的字符串值，否则返回 null。
+   */
+  function matchIntlCall(node) {
+    if (
+      node.type === 'CallExpression' &&
+      ((node.callee.type === 'MemberExpression' &&
+        node.callee.object.name === i18nObject &&
+        node.callee.property.name === i18nMethod) ||
+        (!i18nObject &&
+          node.callee.type === 'Identifier' &&
+          node.callee.name === i18nMethod))
+    ) {
+      const firstArg = node.arguments[0];
+      if (firstArg && firstArg.type === 'StringLiteral') {
+        return firstArg.value;
+      }
+    }
+    return null;
+  }
+
+  return {
+    // 形态 A：intl.get('orphan-id').d('默认文案')
+    // 对应 AST：CallExpression { callee: MemberExpression('.d'), object: intl.get(...) }
+    CallExpression(path) {
+      const { node } = path;
+
+      if (
+        node.callee.type === 'MemberExpression' &&
+        node.callee.property.name === i18nDefaultFunctionKey &&
+        node.callee.object.type === 'CallExpression'
+      ) {
+        const id = matchIntlCall(node.callee.object);
+        if (id && missingIdSet.has(id)) {
+          // 取 .d() 的第一个参数作为恢复后的字符串
+          const defaultArg = node.arguments[0];
+          if (defaultArg && defaultArg.type === 'StringLiteral') {
+            returns.hasTouch = true;
+            path.replaceWith(t.StringLiteral(defaultArg.value));
+            path.skip();
+            return;
+          }
+        }
+      }
+
+      // 形态 B：裸 intl.get('orphan-id')，无 .d()
+      const id = matchIntlCall(node);
+      if (id && missingIdSet.has(id)) {
+        // 无法恢复文案，记录警告，不修改代码
+        noDefaultIds.push({ id, loc: node.loc });
+      }
+    },
+  };
+};

package/bin/scripts/util/makeVisitorUpdate.js

@@ -9,11 +9,14 @@ module.exports = function f(
   const { replaceWords, downloadIds, defaultKeyWordMap } = returns;
 
   // XXX: [TRICKY] 防止中文转码为 unicode
+  // NOTE: recast 的 StringLiteral 打印分支直接使用 node.value（nodeStr），
+  // 不像 @babel/generator 那样读取 extra.raw，所以必须把真实 id 写入 node.value。
   function hackValue(value, id) {
-    return Object.assign(t.StringLiteral(value), {
+    const finalId = id || value;
+    return Object.assign(t.StringLiteral(finalId), {
       extra: {
-        raw: `'${id}'`, // id
-        rawValue: value, // 临时id
+        raw: `'${finalId}'`,
+        rawValue: finalId,
       },
     });
   }

package/bin/scripts/util/transformAst.js

@@ -17,6 +17,7 @@ const presetTypescript = require("@babel/preset-typescript").default;
 
 const makeVisitorCollect = require("./makeVisitorCollect");
 const makeVisitorUpdate = require("./makeVisitorUpdate");
+const makeVisitorDowngrade = require("./makeVisitorDowngrade");
 const log = require("./log");
 
 // 获取文件中需要忽略转化通用国际化API规范的所有行号
@@ -84,7 +85,7 @@ function getIgnoreLines(ast) {
   return ignoreLines;
 }
 
-module.exports = function (type, files = [], conf = {}, replaceWords) {
+module.exports = function (type, files = [], conf = {}, replaceWords, extraData) {
   const {
     entry,
     output,
@@ -152,6 +153,11 @@ module.exports = function (type, files = [], conf = {}, replaceWords) {
       hasImport: false, // 是否已经引入通用国际化API，import {init} from ...;
       hasTouch: false, // 是否存在需要替换的词条
     };
+    // downgrade 模式：注入孤立 id 集合和无默认文案收集数组
+    if (type === "downgrade") {
+      r.missingIdSet = replaceWords; // 复用 replaceWords 参数位传入 Set<string>
+      r.noDefaultIds = extraData;   // 无法恢复的裸 id 收集数组
+    }
     const sourceCode = fs.readFileSync(filePath, "utf8");
 
     let ast;
@@ -178,6 +184,8 @@ module.exports = function (type, files = [], conf = {}, replaceWords) {
     let makeVisitor = makeVisitorCollect;
     if (type === "update") {
       makeVisitor = makeVisitorUpdate;
+    } else if (type === "downgrade") {
+      makeVisitor = makeVisitorDowngrade;
     }
 
     try {
@@ -192,7 +200,7 @@ module.exports = function (type, files = [], conf = {}, replaceWords) {
 
     // 不传入需要替换的文词条则不进行文件修改
     // 在只需要提取中文词条的情况下不传入replaceWords
-    if (!replaceWords) return;
+    if (type !== "downgrade" && !replaceWords) return;
 
     // 使用 recast 输出代码，仅重新打印被修改的 AST 节点，保留原始格式
     let code = recast.print(recastAst).code;
@@ -200,6 +208,7 @@ module.exports = function (type, files = [], conf = {}, replaceWords) {
     if (!r.hasTouch) {
       code = sourceCode;
     } else if (
+      type !== "downgrade" &&
       !r.hasImport &&
       !file.special &&
       importCode &&

package/bin/scripts/verify.js

@@ -0,0 +1,185 @@
+const fs = require('fs');
+const path = require('path');
+const glob = require('glob');
+
+const getConf = require('./conf');
+const { targetOutputFiles } = require('./util/getTargetFiles');
+const transformAst = require('./util/transformAst');
+const log = require('./util/log');
+const file = require('./util/file');
+
+// ── 公共：扫描并分类所有 id ────────────────────────────────────────────────────
+function scanIds(conf, files) {
+  const info = transformAst('update', files, conf, {});
+  const allIds = [...new Set(info.downloadIds.filter(Boolean))];
+
+  const relationKey = file.readJson('relationKey.json') || {};
+  const pendingKeySet = new Set(Object.keys(relationKey));
+
+  const rootPath = process.cwd();
+  const localeDir = path.resolve(rootPath, conf.localeOutput, 'locales');
+  const localeFiles = glob.sync(`${localeDir}/*.json`);
+  const localIdSet = new Set();
+  localeFiles.forEach((f) => {
+    try {
+      const json = JSON.parse(fs.readFileSync(f, 'utf-8'));
+      Object.keys(json).forEach((k) => localIdSet.add(k));
+    } catch (e) {
+      log.error(`读取 locale 文件失败：${f}`);
+    }
+  });
+
+  const pending = [];
+  const missing = [];
+  const ok = [];
+
+  for (const id of allIds) {
+    if (pendingKeySet.has(id)) {
+      pending.push({ tempKey: id, realId: relationKey[id] });
+    } else if (localIdSet.has(id)) {
+      ok.push(id);
+    } else {
+      missing.push(id);
+    }
+  }
+
+  return { allIds, pending, missing, ok };
+}
+
+// ── 公共：打印分类结果 ─────────────────────────────────────────────────────────
+function printResult({ allIds, pending, missing, ok }, files) {
+  console.log('');
+  log.info(`扫描到 ${allIds.length} 个唯一 id（文件数：${files.length}）`);
+
+  if (ok.length) {
+    log.success(`✓ ${ok.length} 个 id 已在本地 locale 文件中覆盖`);
+  }
+  if (pending.length) {
+    log.warnToLog(`⚠ ${pending.length} 个临时 key 尚未执行 update 替换：`);
+    pending.forEach(({ tempKey, realId }) => {
+      log.warnToLog(`    ${tempKey}  →  ${realId}`);
+    });
+  }
+  if (missing.length) {
+    log.error(`✗ ${missing.length} 个孤立 id（relationKey.json 和本地 locale 文件中均不存在）：`);
+    missing.forEach((id) => log.error(`    ${id}`));
+    console.log('');
+    log.error('提示：孤立 id 可能是未上传到国际化平台、未执行 update 拉取，或已在平台删除的词条');
+  }
+}
+
+/**
+ * verify: 检测当前工程输出文件中所有 intl.get('id') 的 id
+ *   - pending  : 临时 key，存在于 relationKey.json（尚未执行 update 替换）
+ *   - ok       : 已在本地 locale 文件中找到
+ *   - missing  : 两处均找不到，属于"孤立 id"，运行时将无法解析
+ *
+ * 用法：
+ *   chaoswise-intl verify          → 发现 missing 时 exit(1)（CI 门禁）
+ *   chaoswise-intl verify --warn   → 仅警告，不 exit(1)
+ */
+async function verify({ exitOnMissing = true } = {}) {
+  log.info('词条 id 校验中...');
+
+  const conf = getConf();
+  const files = targetOutputFiles(conf);
+
+  if (!files.length) {
+    log.warnToLog('未找到需要扫描的文件，请检查 output 配置');
+    return;
+  }
+
+  const result = scanIds(conf, files);
+
+  if (!result.allIds.length) {
+    log.success('未发现任何国际化 id，无需校验');
+    return;
+  }
+
+  printResult(result, files);
+
+  if (result.missing.length) {
+    if (exitOnMissing) {
+      process.exit(1);
+    }
+  } else {
+    console.log('');
+    log.success('★★★ 所有词条 id 均已覆盖，校验通过 ★★★');
+  }
+}
+
+/**
+ * verifyFix: 将孤立 id 对应的 intl 调用降级回字符串字面量（downgrade 策略）
+ *
+ * 形态 A  intl.get('orphan-id').d('默认文案')  →  '默认文案'
+ * 形态 B  intl.get('orphan-id')               →  无法自动恢复，仅打印警告 + 行号
+ *
+ * 修复完成后重新扫描，确认无残留孤立 id。
+ *
+ * 用法：
+ *   chaoswise-intl verify fix
+ */
+async function verifyFix() {
+  log.info('孤立词条降级修复中...');
+
+  const conf = getConf();
+  const files = targetOutputFiles(conf);
+
+  if (!files.length) {
+    log.warnToLog('未找到需要扫描的文件，请检查 output 配置');
+    return;
+  }
+
+  // ── Step 1: 扫描，找出孤立 id ────────────────────────────────────────────
+  const { missing, allIds } = scanIds(conf, files);
+
+  if (!allIds.length) {
+    log.success('未发现任何国际化 id，无需处理');
+    return;
+  }
+
+  if (!missing.length) {
+    log.success('没有孤立 id，无需修复');
+    return;
+  }
+
+  log.info(`共 ${missing.length} 个孤立 id，开始降级处理...`);
+  missing.forEach((id) => log.warnToLog(`  - ${id}`));
+  console.log('');
+
+  // ── Step 2: 执行 downgrade AST 变换（写回文件）────────────────────────────
+  const missingIdSet = new Set(missing);
+  const noDefaultIds = []; // 形态B：无法自动恢复的裸 id
+
+  // transformAst 的 replaceWords 参数传入非空对象才触发写文件，
+  // downgrade visitor 通过 returns.missingIdSet / noDefaultIds 通信
+  transformAst('downgrade', files, conf, missingIdSet, noDefaultIds);
+
+  // ── Step 3: 打印形态 B 警告 ──────────────────────────────────────────────
+  if (noDefaultIds.length) {
+    console.log('');
+    log.warnToLog(`⚠ ${noDefaultIds.length} 处孤立 id 没有 .d() 默认文案，无法自动恢复，需手动处理：`);
+    noDefaultIds.forEach(({ id, loc }) => {
+      const locStr = loc ? `  (行 ${loc.start.line}，列 ${loc.start.column + 1})` : '';
+      log.warnToLog(`    ${id}${locStr}`);
+    });
+  }
+
+  // ── Step 4: 重新扫描，确认修复结果 ──────────────────────────────────────
+  console.log('');
+  log.info('修复完成，重新扫描验证...');
+  const after = scanIds(conf, files);
+  printResult(after, files);
+
+  if (!after.missing.length) {
+    console.log('');
+    log.success('★★★ 孤立 id 已全部降级，请执行 chaoswise-intl collect 重新国际化 ★★★');
+  } else {
+    console.log('');
+    log.error(`仍有 ${after.missing.length} 个孤立 id 未能自动修复（均为形态 B），请手动处理后重试`);
+    process.exit(1);
+  }
+}
+
+module.exports = verify;
+module.exports.fix = verifyFix;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaoswise/intl",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "author": "cloudwiser",
   "description": "intl",
   "main": "lib/index.js",