@agile-team/wl-skills-kit 2.11.1 → 2.11.2

package/lib/ast-rules.js

@@ -7,7 +7,7 @@
  * 依赖：@vue/compiler-sfc（解析 .vue）、@babel/parser（解析 <script> AST）
  * 这两个包在 Vue 3 + Vite 项目中天然存在，用 try-require 做优雅降级。
  *
- * 规则编号 R1~R12 对应 standards 02/06/07/10/12/13 中的语义约束：
+ * 规则编号 R1~R14 对应 standards 02/04/06/07/09/10/12/13 中的语义约束：
  *   R1: index.vue <script setup> 业务逻辑行数超阈值 → warn（02）
  *   R2: index.vue 含禁止 import（getAction/postAction/sessionStorage 等）→ error（02/06）
  *   R3: 页面用 <el-table> 但未用 <BaseTable> → error（12/13）
@@ -20,17 +20,23 @@
  *   R10: 平台组件替换检测 — el-form/el-select/el-date-picker 等应替换为平台封装 → error（13）
  *   R11: data.ts 禁止 import Pinia Store → error（10）
  *   R12: 硬编码 IP/URL 检测 → error/warn（07）
+ *   R13: 单函数圈复杂度 > 10（Mcabe，与 ESLint complexity 定义一致）→ error（04）
+ *   R14: 文件类型错误零容忍 — vue-tsc/tsc --noEmit 产物解析 → error（09）
+ *        注：R14 为项目级检查，体积较大，validate 默认不跑，
+ *        需显式 --typecheck（CLI）/ typecheck:true（MCP）触发，优雅降级为 warn
  *
  * 导出函数：
  *   runAstRules(targetDir, scanRel, { stagedFiles }) → { issues, pages }
  *   parseVueScript(absPath) → { content, template, source } | null
  *   countEffectiveLines(scriptContent) → number
+ *   computeFunctionComplexity(fnNode) → number
+ *   runTypeCheck(root) → { issues, ran, errorCount }
  *   hasAstAvailable() → boolean
  */
 
 const fs = require("fs");
 const path = require("path");
-const { execFileSync } = require("child_process");
+const { execFileSync, spawnSync } = require("child_process");
 
 // ─── AST 依赖探测（优雅降级）──────────────────────────────────────────
 //
@@ -159,6 +165,10 @@ const CONFIG = {
   ],
   FORBIDDEN_GLOBALS: ["sessionStorage", "localStorage"],
   WARN_IMPORTS: ["useRoute"],
+  // R13: 单函数圈复杂度上限（Mcabe），与 ESLint complexity 规则阈值一致
+  MAX_CYCLOMATIC_COMPLEXITY: 10,
+  // R14: 单页类型错误采集上限（避免输出爆炸）
+  TYPECHECK_ERROR_CAP: 50,
   SKIP_DIRS: ["node_modules", "dist", ".git", "demo", "template"],
 };
 
@@ -238,22 +248,30 @@ function countEffectiveLines(scriptContent) {
 }
 
 /**
- * 用 babel/parser 解析 script，提取 import 标识符和来源
+ * 用 babel/parser 解析 script 为 AST（复用给 extractScriptInfo / 圈复杂度计算）
  */
-function extractScriptInfo(scriptContent) {
-  if (!ensureAst() || !scriptContent) {
-    return { specifiers: [], sources: [] };
-  }
-  let ast;
+function parseScriptAst(scriptContent) {
+  if (!ensureAst() || !scriptContent) return null;
   try {
-    ast = _babelParser.parse(scriptContent, {
+    return _babelParser.parse(scriptContent, {
       sourceType: "module",
       plugins: ["typescript", "jsx"],
       errorRecovery: true,
     });
   } catch {
+    return null;
+  }
+}
+
+/**
+ * 用 babel/parser 解析 script，提取 import 标识符和来源
+ */
+function extractScriptInfo(scriptContent) {
+  if (!ensureAst() || !scriptContent) {
     return { specifiers: [], sources: [] };
   }
+  const ast = parseScriptAst(scriptContent);
+  if (!ast) return { specifiers: [], sources: [] };
   const specifiers = [];
   const sources = [];
   for (const node of ast.program.body) {
@@ -272,6 +290,114 @@ function extractScriptInfo(scriptContent) {
   return { specifiers, sources };
 }
 
+// ─── R13 圈复杂度（Mcabe）──────────────────────────────────────────────
+//
+// 定义与 ESLint `complexity` 规则一致：复杂度 = 1 + 决策点数。
+// 不依赖 @babel/traverse，自写轻量遍历，避免新增运行时依赖。
+
+const COMPLEXITY_NODE_TYPES = new Set([
+  "IfStatement", // if / else if（每个 IfStatement 计 1）
+  "SwitchCase", // 每个 case / default
+  "ForStatement",
+  "ForInStatement",
+  "ForOfStatement",
+  "WhileStatement",
+  "DoWhileStatement",
+  "CatchClause",
+  "ConditionalExpression", // 三元 ?:
+  "LogicalExpression", // && / || / ??
+]);
+
+const FUNCTION_NODE_TYPES = new Set([
+  "FunctionDeclaration",
+  "FunctionExpression",
+  "ArrowFunctionExpression",
+]);
+
+function isFunctionNode(node) {
+  return Boolean(node) && FUNCTION_NODE_TYPES.has(node.type);
+}
+
+// 取节点所有子 AST 节点（跳过位置/范围元信息）
+function getChildNodes(node) {
+  const out = [];
+  for (const key of Object.keys(node)) {
+    if (key === "loc" || key === "range" || key === "start" || key === "end") {
+      continue;
+    }
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const c of child) {
+        if (c && typeof c.type === "string") out.push(c);
+      }
+    } else if (child && typeof child.type === "string") {
+      out.push(child);
+    }
+  }
+  return out;
+}
+
+// 尽力推断函数名（变量赋值 / 类方法 / 对象方法 / 命名函数表达式）
+function resolveFnName(node, parent) {
+  if (node.id && node.id.name) return node.id.name;
+  if (!parent) return "(anonymous)";
+  if (parent.type === "VariableDeclarator" && parent.id && parent.id.name) {
+    return parent.id.name;
+  }
+  if (
+    (parent.type === "MethodDefinition" || parent.type === "Property") &&
+    parent.key
+  ) {
+    return parent.key.name || parent.key.value || "(anonymous)";
+  }
+  if (parent.type === "AssignmentExpression" && parent.left) {
+    const left = parent.left;
+    if (left.property) return left.property.name || left.property.value;
+    if (left.name) return left.name;
+  }
+  return "(anonymous)";
+}
+
+// 收集整棵 AST 中的所有函数节点 + 名字（含嵌套函数，各独立计 R13）
+function collectFunctions(ast) {
+  const fns = [];
+  const stack = [];
+  function walk(node) {
+    if (!node || typeof node.type !== "string") return;
+    let pushed = false;
+    if (isFunctionNode(node)) {
+      const parent = stack.length ? stack[stack.length - 1] : null;
+      fns.push({ node, name: resolveFnName(node, parent) });
+      // 不再下钻到该函数体内部去发现"孙函数"——
+      // 嵌套函数会在遍历其父函数体时自然被收集
+    }
+    stack.push(node);
+    pushed = true;
+    for (const child of getChildNodes(node)) walk(child);
+    if (pushed) stack.pop();
+  }
+  walk(ast);
+  return fns;
+}
+
+/**
+ * 计算单个函数的圈复杂度（不下钻进嵌套函数体，嵌套函数独立计）
+ * @param {object} fnNode FunctionDeclaration / FunctionExpression / ArrowFunctionExpression
+ * @returns {number}
+ */
+function computeFunctionComplexity(fnNode) {
+  if (!fnNode) return 0;
+  let complexity = 1;
+  function walk(node) {
+    if (!node || typeof node.type !== "string") return;
+    if (node !== fnNode && isFunctionNode(node)) return; // 嵌套函数边界
+    if (COMPLEXITY_NODE_TYPES.has(node.type)) complexity++;
+    for (const child of getChildNodes(node)) walk(child);
+  }
+  walk(fnNode);
+  return complexity;
+}
+
 /**
  * 检测模板中是否有 el-table（非 BaseTable）
  */
@@ -419,6 +545,34 @@ function runAstRules(targetDir, scanRel, options) {
       });
     }
 
+    // R13: 单函数圈复杂度 ≤ MAX_CYCLOMATIC_COMPLEXITY（standard 04，Mcabe）
+    //     覆盖 index.vue <script> 与 data.ts 的所有函数/方法/箭头函数
+    if (!hasIgnoreMarker(fullSource, "R13")) {
+      const maxC = CONFIG.MAX_CYCLOMATIC_COMPLEXITY;
+      const scanComplexity = (code, label) => {
+        const ast = parseScriptAst(code);
+        if (!ast) return;
+        for (const fn of collectFunctions(ast)) {
+          const cc = computeFunctionComplexity(fn.node);
+          if (cc > maxC) {
+            issues.push({
+              level: "error",
+              dir: page.dir,
+              text:
+                label + " 函数 " + fn.name +
+                "() 圈复杂度 " + cc + "（阈值 " + maxC +
+                "），需拆分为更小函数（standard 04）",
+              rule: "R13",
+            });
+          }
+        }
+      };
+      scanComplexity(scriptContent, "index.vue");
+      if (fs.existsSync(dataPath)) {
+        scanComplexity(fs.readFileSync(dataPath, "utf8"), "data.ts");
+      }
+    }
+
     // R2: 禁止的 import / 全局 API
     if (scriptContent) {
       const { specifiers, sources } = extractScriptInfo(scriptContent);
@@ -754,11 +908,152 @@ function getStagedFiles(targetDir) {
   }
 }
 
+// ─── R14 类型错误零容忍（项目级，vue-tsc / tsc 委托）──────────────────
+//
+// 体积较大，validate 默认不触发，由 CLI --typecheck / MCP typecheck:true 显式开启。
+// 无 tsconfig / 无 checker → 优雅降级为 warn（与 AST 依赖降级策略一致）。
+// 该函数不进入 page 粒度，整项目执行一次，结果按文件归并到 issues。
+
+function runTypeCheck(root) {
+  const safeRoot = root || process.cwd();
+  const label = path.basename(safeRoot) || ".";
+  const tsconfigPath = path.join(safeRoot, "tsconfig.json");
+
+  if (!fs.existsSync(tsconfigPath)) {
+    return {
+      issues: [
+        {
+          level: "warn",
+          dir: label,
+          text: "未发现 tsconfig.json，跳过类型检查 R14",
+          rule: "R14",
+        },
+      ],
+      ran: false,
+      errorCount: 0,
+    };
+  }
+
+  const nmBin = path.join(safeRoot, "node_modules", ".bin");
+  const envPath =
+    nmBin + path.delimiter + (process.env.PATH || process.env.Path || "");
+  const env = Object.assign({}, process.env, { PATH: envPath });
+
+  // 优先 vue-tsc（.vue 项目），回退 tsc；shell:true 让 Windows 找到 .cmd
+  let checker = null;
+  for (const bin of ["vue-tsc", "tsc"]) {
+    try {
+      const probe = spawnSync(bin, ["--version"], {
+        shell: true,
+        env,
+        encoding: "utf8",
+        timeout: 20000,
+      });
+      if (probe.status === 0) {
+        checker = bin;
+        break;
+      }
+    } catch {
+      // ignore, try next
+    }
+  }
+  if (!checker) {
+    return {
+      issues: [
+        {
+          level: "warn",
+          dir: label,
+          text: "未发现 vue-tsc / tsc，跳过类型检查 R14（建议安装后纳入 CI）",
+          rule: "R14",
+        },
+      ],
+      ran: false,
+      errorCount: 0,
+    };
+  }
+
+  let result;
+  try {
+    result = spawnSync(checker, ["--noEmit"], {
+      cwd: safeRoot,
+      shell: true,
+      env,
+      encoding: "utf8",
+      timeout: 180000,
+    });
+  } catch (e) {
+    return {
+      issues: [
+        {
+          level: "warn",
+          dir: label,
+          text:
+            "类型检查执行异常：" + ((e && e.message) || String(e)),
+          rule: "R14",
+        },
+      ],
+      ran: false,
+      errorCount: 0,
+    };
+  }
+
+  const out =
+    String(result.stdout || "") + String(result.stderr || "");
+  // 标准格式：path(line,col): error TS1234: message
+  // 捕获组：1=file 2=line 3=col 4=code 5=msg
+  const errRe = /^(.+?)\((\d+),(\d+)\):\s+error\s+(TS\d+):\s*(.+)$/gm;
+  const errors = [];
+  let m;
+  while ((m = errRe.exec(out)) !== null) {
+    errors.push({ file: m[1], line: m[2], code: m[4], msg: m[5] });
+    if (errors.length >= CONFIG.TYPECHECK_ERROR_CAP) break;
+  }
+
+  if (errors.length === 0) {
+    if (result.status === 0) {
+      return { issues: [], ran: true, errorCount: 0 };
+    }
+    // 退出码非 0 但未解析出标准 error 行：疑似 tsconfig / 配置级错误
+    return {
+      issues: [
+        {
+          level: "error",
+          dir: label,
+          text:
+            checker +
+            " --noEmit 退出码 " +
+            result.status +
+            "（请检查 tsconfig / 类型配置，无标准 TS 错误输出）",
+          rule: "R14",
+        },
+      ],
+      ran: true,
+      errorCount: 1,
+    };
+  }
+
+  const issues = errors.map((e) => {
+    const rel = path.relative(safeRoot, e.file).replace(/\\/g, "/") || e.file;
+    return {
+      level: "error",
+      dir: path.dirname(rel) || ".",
+      text:
+        e.code + " " + e.msg + " (" + path.basename(rel) + ":" + e.line + ")",
+      rule: "R14",
+    };
+  });
+  return { issues, ran: true, errorCount: errors.length };
+}
+
 module.exports = {
   runAstRules,
   parseVueScript,
   countEffectiveLines,
   extractScriptInfo,
+  parseScriptAst,
+  computeFunctionComplexity,
+  collectFunctions,
+  runTypeCheck,
   hasAstAvailable,
   isAstFunctionallyUsable,
   getStagedFiles,

package/mcp/config.js

@@ -1,47 +1,47 @@
-'use strict'
-
-const fs = require('fs')
-const path = require('path')
-
-/**
- * 从项目的 .wl-skills/skills/sync/env.local.json 加载 MCP 运行配置
- * 项目根目录通过环境变量 WL_PROJECT_ROOT 传入（由 .cursor/mcp.json 注入）
- */
-function loadConfig() {
-  const projectRoot = process.env.WL_PROJECT_ROOT
-    ? path.resolve(process.env.WL_PROJECT_ROOT)
-    : process.cwd()
-
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * 从项目的 .wl-skills/skills/sync/env.local.json 加载 MCP 运行配置
+ * 项目根目录通过环境变量 WL_PROJECT_ROOT 传入（由 .cursor/mcp.json 注入）
+ */
+function loadConfig() {
+  const projectRoot = process.env.WL_PROJECT_ROOT
+    ? path.resolve(process.env.WL_PROJECT_ROOT)
+    : process.cwd()
+
   const configPath = path.join(projectRoot, '.wl-skills', 'skills', 'sync', 'env.local.json')
-
-  if (!fs.existsSync(configPath)) {
-    throw new Error(
-      `配置文件不存在: ${configPath}\n` +
-      `请先执行 pnpm dlx @agile-team/wl-skills-kit init，然后填写 .wl-skills/skills/sync/env.local.json`
-    )
-  }
-
-  let raw
-  try {
-    raw = JSON.parse(fs.readFileSync(configPath, 'utf8'))
-  } catch (e) {
-    throw new Error(`配置文件解析失败: ${e.message}`)
-  }
-
-  if (!raw.gatewayPath || raw.gatewayPath.includes('你的网关')) {
-    throw new Error('请在 env.local.json 中填写真实的 gatewayPath（当前为占位值）')
-  }
-  if (!raw.token || raw.token.includes('Bearer Token')) {
-    throw new Error('请在 env.local.json 中填写真实的 token（当前为占位值）')
-  }
-
-  return {
-    gatewayPath: raw.gatewayPath.replace(/\/$/, ''), // 去掉尾部斜杠
-    token: raw.token,
-    sysAppNo: raw.sysAppNo || '',
-    menu: raw.menu || {},
-    dict: raw.dict || {},
-  }
-}
-
-module.exports = { loadConfig }
+
+  if (!fs.existsSync(configPath)) {
+    throw new Error(
+      `配置文件不存在: ${configPath}\n` +
+      `请先执行 pnpm dlx @agile-team/wl-skills-kit init，然后填写 .wl-skills/skills/sync/env.local.json`
+    )
+  }
+
+  let raw
+  try {
+    raw = JSON.parse(fs.readFileSync(configPath, 'utf8'))
+  } catch (e) {
+    throw new Error(`配置文件解析失败: ${e.message}`)
+  }
+
+  if (!raw.gatewayPath || raw.gatewayPath.includes('你的网关')) {
+    throw new Error('请在 env.local.json 中填写真实的 gatewayPath（当前为占位值）')
+  }
+  if (!raw.token || raw.token.includes('Bearer Token')) {
+    throw new Error('请在 env.local.json 中填写真实的 token（当前为占位值）')
+  }
+
+  return {
+    gatewayPath: raw.gatewayPath.replace(/\/$/, ''), // 去掉尾部斜杠
+    token: raw.token,
+    sysAppNo: raw.sysAppNo || '',
+    menu: raw.menu || {},
+    dict: raw.dict || {},
+  }
+}
+
+module.exports = { loadConfig }

package/mcp/registry.js

@@ -296,11 +296,16 @@ const DESCRIPTORS = [
   {
     name: "wls_validate_page",
     description:
-      "校验页面是否符合 wl-skills-kit 最新页面规范：BaseTable+AGGrid+cid、defineColumns、renderOps、mock-first、api.md 等。",
+      "校验页面是否符合 wl-skills-kit 最新页面规范：BaseTable+AGGrid+cid、defineColumns、renderOps、mock-first、api.md 等。开启 typecheck 额外执行 vue-tsc/tsc 类型检查（R14）。",
     inputSchema: {
       type: "object",
       properties: {
         path: { type: "string", description: "页面或目录路径，默认 src/views" },
+        typecheck: {
+          type: "boolean",
+          description:
+            "是否额外执行 vue-tsc/tsc --noEmit 类型检查（R14，体积较大，CI 场景开启）",
+        },
       },
       required: [],
     },

package/mcp/tools/projectTools.js

@@ -4,7 +4,7 @@ const fs = require("fs");
 const path = require("path");
 const { execFileSync } = require("child_process");
 const https = require("https");
-const { runAstRules } = require("../../lib/ast-rules");
+const { runAstRules, runTypeCheck } = require("../../lib/ast-rules");
 const { alignPage } = require("../../lib/page-spec");
 
 function getProjectRoot() {
@@ -213,6 +213,14 @@ async function handleValidatePage(args) {
     }
   }
 
+  // ── 类型检查 R14（v2.11.2+，仅当 typecheck:true 触发）─────────────────
+  if (args && args.typecheck) {
+    const tc = runTypeCheck(root);
+    for (const iss of tc.issues) {
+      issues.push([iss.dir, iss.level, `[${iss.rule}] ${iss.text}`]);
+    }
+  }
+
   const errors = issues.filter((item) => item[1] === "error").length;
   const lines = [
     `✅ 页面校验完成：${scanPath}`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agile-team/wl-skills-kit",
-  "version": "2.11.1",
-  "description": "AI Skill 模板包 v2.11.1 — 14 条编码规范 + 11 个 AI Skill + 17 个 MCP Tool，一条命令导入 Vue 3 项目（.wl-skills/ 统一隔离架构）",
+  "version": "2.11.2",
+  "description": "AI Skill 模板包 v2.11.2 — 14 条编码规范 + 11 个 AI Skill + 17 个 MCP Tool，一条命令导入 Vue 3 项目（.wl-skills/ 统一隔离架构）",
   "main": "./bin/wl-skills.js",
   "packageManager": "pnpm@11.5.3",
   "bin": {