@agile-team/wl-skills-ui 1.6.2

package/scanner/rules/index.mjs

@@ -0,0 +1,58 @@
+/**
+ * scanner/rules/index.mjs — 规则注册中心
+ *
+ * 内置规则按类别拆分在各子文件中。
+ * 支持外部插件通过 addRules(rules) 动态注入自定义规则。
+ *
+ * 导出：
+ *   - BUILT_IN_RULES     内置规则数组（只读）
+ *   - addRules(rules)    注册外部规则（插件式扩展）
+ *   - getRules()         获取当前全部规则（内置 + 外部）
+ *   - getRuleById(id)    按 ID 查找规则
+ */
+import { tableRules } from "./table.mjs";
+import { formRules } from "./form.mjs";
+import { buttonRules } from "./button.mjs";
+import { colorRules } from "./color.mjs";
+import { dialogRules } from "./dialog.mjs";
+import { tagRules } from "./tag.mjs";
+import { componentFamilyRules } from "./componentFamily.mjs";
+
+export const BUILT_IN_RULES = [
+  ...tableRules,
+  ...formRules,
+  ...buttonRules,
+  ...colorRules,
+  ...dialogRules,
+  ...tagRules,
+  ...componentFamilyRules,
+];
+
+const _externalRules = [];
+
+/**
+ * 注册外部自定义规则（插件式扩展）
+ * @param {Array} rules - 规则对象数组，每条规则需含 id / category / severity / check 方法
+ */
+export function addRules(rules) {
+  for (const r of rules) {
+    if (!r.id || typeof r.check !== "function")
+      throw new Error(
+        `[wk-scan] addRules: 规则 "${r.id}" 必须提供 id 和 check() 方法`,
+      );
+    _externalRules.push(r);
+  }
+}
+
+/** 返回全部规则（内置 + 外部插件） */
+export function getRules() {
+  return [...BUILT_IN_RULES, ..._externalRules];
+}
+
+/** 按 ID 查找规则 */
+export function getRuleById(id) {
+  return getRules().find((r) => r.id === id);
+}
+
+/** 兼容：直接 default 导出全部规则数组 */
+export default getRules;

package/scanner/rules/table.mjs

@@ -0,0 +1,170 @@
+/** scanner/rules/table.mjs — 表格相关规则：R001 R002 R003 R014 R021 R022 */
+import { lineOf, issue, findTags } from "./_shared.mjs";
+
+export const tableRules = [
+  // R001: el-table-column 缺少 align="center"
+  {
+    id: "R001",
+    category: "table",
+    severity: "error",
+    name: 'el-table-column 缺少 align="center"',
+    check(template, file, lineOffset) {
+      const issues = [];
+      const hasCenter = (t) =>
+        /(?::?align)\s*=\s*["'](?:center|'center'|"center")["']/.test(t) ||
+        /align\s*=\s*["']center["']/.test(t);
+      const hasLeft = (t) => /align\s*=\s*["']left["']/.test(t);
+      for (const tag of findTags(template, "el-table-column")) {
+        if (!hasCenter(tag.text)) {
+          issues.push(
+            issue(
+              file,
+              lineOf(template, tag.index, lineOffset),
+              "R001",
+              "table",
+              "error",
+              hasLeft(tag.text)
+                ? '有 align="left"，应改为 align="center"'
+                : '缺少 align="center"',
+              '添加 align="center"；selection列同时加 header-align="center"、width=55，index列width=60',
+            ),
+          );
+        }
+      }
+      return issues;
+    },
+  },
+
+  // R002: el-table 缺少 empty-text
+  {
+    id: "R002",
+    category: "table",
+    severity: "warning",
+    name: 'el-table 缺少 empty-text="暂无数据"',
+    check(template, file, lineOffset) {
+      const issues = [];
+      for (const tag of findTags(template, "el-table")) {
+        if (!tag.text.includes("empty-text="))
+          issues.push(
+            issue(
+              file,
+              lineOf(template, tag.index, lineOffset),
+              "R002",
+              "table",
+              "warning",
+              "缺少 empty-text 属性",
+              '添加 empty-text="暂无数据"',
+            ),
+          );
+      }
+      return issues;
+    },
+  },
+
+  // R003: BaseTable 缺少 empty-text
+  {
+    id: "R003",
+    category: "table",
+    severity: "warning",
+    name: 'BaseTable 缺少 empty-text="暂无数据"',
+    check(template, file, lineOffset) {
+      const issues = [];
+      for (const tag of findTags(template, "BaseTable")) {
+        if (!tag.text.includes("empty-text="))
+          issues.push(
+            issue(
+              file,
+              lineOf(template, tag.index, lineOffset),
+              "R003",
+              "table",
+              "warning",
+              "BaseTable 缺少 empty-text 属性",
+              '添加 empty-text="暂无数据"',
+            ),
+          );
+      }
+      return issues;
+    },
+  },
+
+  // R014: selection 列缺少 header-align="center"
+  {
+    id: "R014",
+    category: "table",
+    severity: "warning",
+    name: 'selection 列缺少 header-align="center"',
+    check(template, file, lineOffset) {
+      const issues = [];
+      for (const tag of findTags(template, "el-table-column")) {
+        if (
+          tag.text.includes('type="selection"') &&
+          !tag.text.includes("header-align=")
+        )
+          issues.push(
+            issue(
+              file,
+              lineOf(template, tag.index, lineOffset),
+              "R014",
+              "table",
+              "warning",
+              'selection 列缺少 header-align="center"，会导致表头复选框不居中',
+              '添加 header-align="center"',
+            ),
+          );
+      }
+      return issues;
+    },
+  },
+
+  // R021: BaseTable 必须使用 AGGrid 渲染模式
+  {
+    id: "R021",
+    category: "table",
+    severity: "error",
+    name: 'BaseTable 缺少 render-type="agGrid"',
+    check(template, file, lineOffset) {
+      const issues = [];
+      for (const tag of findTags(template, "BaseTable")) {
+        if (!/render-type\s*=\s*["']agGrid["']/.test(tag.text))
+          issues.push(
+            issue(
+              file,
+              lineOf(template, tag.index, lineOffset),
+              "R021",
+              "table",
+              "error",
+              'BaseTable 必须显式配置 render-type="agGrid"',
+              '添加 render-type="agGrid"',
+            ),
+          );
+      }
+      return issues;
+    },
+  },
+
+  // R022: BaseTable 必须有唯一 cid
+  {
+    id: "R022",
+    category: "table",
+    severity: "error",
+    name: "BaseTable 缺少 cid/:cid",
+    check(template, file, lineOffset) {
+      const issues = [];
+      for (const tag of findTags(template, "BaseTable")) {
+        if (!/(^|\s)(:cid|cid)\s*=/.test(tag.text))
+          issues.push(
+            issue(
+              file,
+              lineOf(template, tag.index, lineOffset),
+              "R022",
+              "table",
+              "error",
+              "BaseTable 必须配置全局唯一 cid",
+              '添加 cid="页面缩写-唯一后缀" 或 :cid="TABLE_CID"',
+            ),
+          );
+      }
+      return issues;
+    },
+  },
+];

package/scanner/rules/tag.mjs

@@ -0,0 +1,245 @@
+/** scanner/rules/tag.mjs — 标签/状态规则：R009 R010 R012 R017 R018 */
+import { lineOf, issue, findTags } from "./_shared.mjs";
+
+/** 状态类字段名关键字（动态流转状态） */
+const STATUS_FIELD_PATTERN =
+  /(?:Status|State|Flag|status|state|flag)(?=\s*["']|:\s*["']|$)/;
+
+/** 分类字段名关键字（组织/归档属性） */
+const CLASSIFY_FIELD_PATTERN =
+  /(?:Type|Level|Kind|Class|Category|type|level|kind|class|category)(?=\s*["']|:\s*["']|$)/;
+
+export const tagRules = [
+  // R009: 状态字段纯文本渲染（应使用 renderTagNode / ElTag）
+  {
+    id: "R009",
+    category: "tag",
+    severity: "warning",
+    name: "状态字段纯文本渲染（应使用 renderTagNode / ElTag）",
+    check(template, file, lineOffset) {
+      const issues = [];
+      // 检测 el-table-column 中 name/prop 含 Status/Level/State 但无 renderTagNode/ElTag/jh-tag/defaultSlot
+      for (const tag of findTags(template, "el-table-column")) {
+        const nameMatch = tag.text.match(/(?:name|prop)\s*=\s*["'](\w+)["']/);
+        if (!nameMatch) continue;
+        const fieldName = nameMatch[1];
+        if (
+          !STATUS_FIELD_PATTERN.test(fieldName) &&
+          !CLASSIFY_FIELD_PATTERN.test(fieldName)
+        )
+          continue;
+        // 有渲染器则跳过
+        if (
+          /renderTagNode|renderOps|ElTag|jh-tag|defaultSlot|defaultNode|renderClassifyTag|renderBadge/.test(
+            tag.text,
+          )
+        )
+          continue;
+        issues.push(
+          issue(
+            file,
+            lineOf(template, tag.index, lineOffset),
+            "R009",
+            "tag",
+            "warning",
+            `状态字段 "${fieldName}" 使用纯文本渲染，应改为 renderTagNode / ElTag`,
+            `使用 defineColumns() 包裹列定义，或手动添加 defaultSlot: ({ row }) => renderTagNode(row.${fieldName}, MAP)`,
+          ),
+        );
+      }
+      return issues;
+    },
+    // 脚本式列定义（columnsDef / columns 数组）中状态字段纯文本（含 logicType:dict 但无 defaultSlot）
+    checkScript(script, file, lineOffset) {
+      const issues = [];
+      const lines = script.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const labelMatch = lines[i].match(/label:\s*["']([^"']+)["']/);
+        if (!labelMatch) continue;
+        const label = labelMatch[1];
+        if (!STATUS_FIELD_PATTERN.test(label) && !/状态|级别|类型/.test(label))
+          continue;
+        const blockStart = Math.max(0, i - 3);
+        const blockEnd = Math.min(lines.length, i + 8);
+        const block = lines.slice(blockStart, blockEnd).join("\n");
+        // 已有渲染器则跳过
+        if (
+          /defaultSlot|defaultNode|renderTag|renderClassify|renderDictClassify|renderEnable|renderBadge|ElTag/.test(
+            block,
+          )
+        )
+          continue;
+        issues.push({
+          file,
+          line: lineOffset + i + 1,
+          rule: "R009",
+          category: "tag",
+          severity: "warning",
+          description: `状态/分类列 "${label}" 纯文本渲染，应使用 renderTagNode / renderDictClassifyTag`,
+          suggestion: `添加 defaultSlot: ({ row }) => renderDictClassifyTag(row.xxx, 'dictKey') 或 renderTagNode(row.xxx, MAP)`,
+        });
+      }
+      return issues;
+    },
+  },
+
+  // R010: 分类字段使用填充色 ElTag（应使用 effect="plain"）
+  {
+    id: "R010",
+    category: "tag",
+    severity: "warning",
+    name: '分类字段使用填充色 ElTag（应使用 effect="plain" outline 风格）',
+    check(template, file, lineOffset) {
+      const issues = [];
+      // 检测含 Type/Level/Class/Category 的 el-tag 缺少 effect="plain"
+      for (const tag of findTags(template, "el-tag")) {
+        // 判断上下文是否是分类字段（前后 200 字符内含分类关键字）
+        const contextStart = Math.max(0, tag.index - 200);
+        const context = template.slice(
+          contextStart,
+          tag.index + tag.text.length,
+        );
+        if (!CLASSIFY_FIELD_PATTERN.test(context)) continue;
+        // 已有 effect="plain" 则跳过
+        if (/effect\s*=\s*["']plain["']/.test(tag.text)) continue;
+        // 有 effect="dark" 或无 effect 的分类 Tag → 建议改为 plain
+        if (
+          /effect\s*=\s*["']dark["']/.test(tag.text) ||
+          !/effect\s*=/.test(tag.text)
+        ) {
+          issues.push(
+            issue(
+              file,
+              lineOf(template, tag.index, lineOffset),
+              "R010",
+              "tag",
+              "warning",
+              '分类字段 ElTag 未使用 effect="plain"（outline 风格），视觉权重过高',
+              '添加 effect="plain"，或使用 renderClassifyTag() 自动渲染',
+            ),
+          );
+        }
+      }
+      return issues;
+    },
+  },
+
+  // R017: 编号/工号/证件号列缺少 renderBadge（脚本式 columnsDef）
+  {
+    id: "R017",
+    category: "tag",
+    severity: "warning",
+    name: "编号/工号/证件号列缺少 renderBadge（脚本式 columnsDef）",
+    checkScript(script, file, lineOffset) {
+      const issues = [];
+      /** label 关键字：编号、工号、证件号、以及常见英文组合 */
+      const BADGE_LABEL_RE =
+        /编号|工号|证件号|驾驶员证件号|车主证件号|处置人工号/;
+      const lines = script.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const labelMatch = lines[i].match(/label:\s*["']([^"']+)["']/);
+        if (!labelMatch) continue;
+        const label = labelMatch[1];
+        if (!BADGE_LABEL_RE.test(label)) continue;
+        const blockStart = Math.max(0, i - 2);
+        const blockEnd = Math.min(lines.length, i + 10);
+        const block = lines.slice(blockStart, blockEnd).join("\n");
+        if (/renderBadge|defaultSlot|defaultNode/.test(block)) continue;
+        const nameMatch = block.match(/name:\s*["']([^"']+)["']/);
+        const fieldName = nameMatch ? nameMatch[1] : "xxx";
+        issues.push({
+          file,
+          line: lineOffset + i + 1,
+          rule: "R017",
+          category: "tag",
+          severity: "warning",
+          description: `编号列 "${label}" 未使用 renderBadge，纯文本无视觉区分`,
+          suggestion: `添加 defaultSlot: ({ row }) => renderBadge(row.${fieldName})，并 import { renderBadge } from "@/util/ag-cell-renders"`,
+        });
+      }
+      return issues;
+    },
+  },
+
+  // R018: 脚本式列定义使用 logicType:dict 但缺少 defaultSlot（应改为 renderDictClassifyTag）
+  {
+    id: "R018",
+    category: "tag",
+    severity: "warning",
+    name: "dict列缺少 defaultSlot/renderDictClassifyTag（脚本式 columnsDef）",
+    checkScript(script, file, lineOffset) {
+      const issues = [];
+      const lines = script.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        if (!/logicType.*dict|BusLogicDataType\.dict/.test(lines[i])) continue;
+        const blockStart = Math.max(0, i - 5);
+        const blockEnd = Math.min(lines.length, i + 5);
+        const block = lines.slice(blockStart, blockEnd).join("\n");
+        if (
+          /defaultSlot|defaultNode|renderTag|renderClassify|renderDictClassify|renderEnable|renderBadge/.test(
+            block,
+          )
+        )
+          continue;
+        const labelMatch = block.match(/label:\s*["']([^"']+)["']/);
+        const label = labelMatch ? labelMatch[1] : "(unknown)";
+        const logicMatch = block.match(/logicValue:\s*["']([^"']+)["']/);
+        const dictKey = logicMatch ? logicMatch[1] : "dictKey";
+        const nameMatch = block.match(/name:\s*["']([^"']+)["']/);
+        const fieldName = nameMatch ? nameMatch[1] : "xxx";
+        issues.push({
+          file,
+          line: lineOffset + i + 1,
+          rule: "R018",
+          category: "tag",
+          severity: "warning",
+          description: `"${label}" 使用 logicType:dict 但无 defaultSlot，纯文本展示枚举值`,
+          suggestion: `改为 defaultSlot: ({ row }) => renderDictClassifyTag(row.${fieldName}, '${dictKey}')，删除 logicType/logicValue`,
+        });
+      }
+      return issues;
+    },
+  },
+
+  // R012: 弹窗内 el-table 缺少空状态
+  {
+    id: "R012",
+    category: "tag",
+    severity: "warning",
+    name: "弹窗内 el-table 缺少 empty-text",
+    check(template, file, lineOffset) {
+      const issues = [];
+      // 检测 el-dialog 内的 el-table 缺少 empty-text
+      const dialogPattern = /<el-dialog\b/g;
+      let dm;
+      while ((dm = dialogPattern.exec(template)) !== null) {
+        // 找到 dialog 结束标签
+        const dialogStart = dm.index;
+        const afterDialog = template.slice(dialogStart);
+        const dialogCloseMatch = afterDialog.match(/<\/el-dialog>/);
+        if (!dialogCloseMatch) continue;
+        const dialogEnd =
+          dialogStart + dialogCloseMatch.index + "</el-dialog>".length;
+        const dialogContent = template.slice(dialogStart, dialogEnd);
+
+        // 在 dialog 内容中找 el-table
+        for (const tag of findTags(dialogContent, "el-table")) {
+          if (!tag.text.includes("empty-text=")) {
+            issues.push(
+              issue(
+                file,
+                lineOf(template, dialogStart + tag.index, lineOffset),
+                "R012",
+                "tag",
+                "warning",
+                "弹窗内 el-table 缺少 empty-text 属性",
+                '添加 empty-text="暂无数据"',
+              ),
+            );
+          }
+        }
+      }
+      return issues;
+    },
+  },
+];

package/scanner/snapshot.mjs

@@ -0,0 +1,198 @@
+/**
+ * scanner/snapshot.mjs — 皮肤层快照与回退机制
+ *
+ * 核心思路：
+ *   fix 前自动对即将修改的文件做内容快照，写入一个 JSON manifest 文件。
+ *   回退时读取 manifest，一键还原所有文件内容。
+ *   不在项目里留备份文件，不影响性能，不污染 git。
+ *
+ * 快照格式（.wk-snapshot/<timestamp>.json）：
+ *   {
+ *     "version": 1,
+ *     "createdAt": "2025-05-02T17:30:00.000Z",
+ *     "command": "fix",
+ *     "targetDir": "/abs/path/src",
+ *     "totalFiles": 12,
+ *     "totalChanges": 38,
+ *     "files": {
+ *       "relative/path.vue": "<original content base64>"
+ *     }
+ *   }
+ *
+ * CLI：
+ *   wk-scan snapshot list   [--project <path>]           列出所有快照
+ *   wk-scan snapshot rollback [--id <timestamp>]          回退指定快照（默认最新）
+ *   wk-scan snapshot clean   [--keep <N>]                 清理旧快照，保留最近 N 个
+ *   wk-scan snapshot diff    [--id <timestamp>]           查看快照与当前文件差异
+ *
+ * 集成：fix.mjs 调用 createSnapshot() 即可，无需改业务逻辑。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+const SNAPSHOT_DIR = ".wk-snapshot";
+const SNAPSHOT_VERSION = 1;
+
+/**
+ * 创建快照 — 在 fix 之前调用
+ * @param {object} opts
+ * @param {string} opts.projectRoot  项目根目录
+ * @param {string} opts.targetDir    扫描目标目录（绝对路径）
+ * @param {string[]} opts.filePaths  即将被修改的文件绝对路径列表
+ * @param {string} opts.command      触发命令（fix / apply 等）
+ * @returns {{ id: string, path: string, fileCount: number }}
+ */
+export function createSnapshot({ projectRoot, targetDir, filePaths, command = "fix" }) {
+  const dir = join(projectRoot, SNAPSHOT_DIR);
+  mkdirSync(dir, { recursive: true });
+
+  const id = new Date().toISOString().replace(/[:.]/g, "-");
+  const files = {};
+
+  for (const absPath of filePaths) {
+    if (!existsSync(absPath)) continue;
+    const rel = relative(projectRoot, absPath).replace(/\\/g, "/");
+    const content = readFileSync(absPath, "utf8");
+    // base64 编码存储，避免 JSON 转义问题
+    files[rel] = Buffer.from(content, "utf8").toString("base64");
+  }
+
+  const manifest = {
+    version: SNAPSHOT_VERSION,
+    createdAt: new Date().toISOString(),
+    command,
+    targetDir: relative(projectRoot, targetDir).replace(/\\/g, "/"),
+    totalFiles: Object.keys(files).length,
+    files,
+  };
+
+  const outPath = join(dir, `${id}.json`);
+  writeFileSync(outPath, JSON.stringify(manifest, null, 2), "utf8");
+
+  return { id, path: outPath, fileCount: manifest.totalFiles };
+}
+
+/**
+ * 列出所有快照
+ * @param {string} projectRoot
+ * @returns {Array<{id, createdAt, command, targetDir, totalFiles, path}>}
+ */
+export function listSnapshots(projectRoot) {
+  const dir = join(projectRoot, SNAPSHOT_DIR);
+  if (!existsSync(dir)) return [];
+
+  return readdirSync(dir)
+    .filter(f => f.endsWith(".json"))
+    .sort()
+    .reverse()
+    .map(f => {
+      try {
+        const full = join(dir, f);
+        const data = JSON.parse(readFileSync(full, "utf8"));
+        return {
+          id: f.replace(".json", ""),
+          createdAt: data.createdAt,
+          command: data.command,
+          targetDir: data.targetDir,
+          totalFiles: data.totalFiles,
+          path: full,
+        };
+      } catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * 回退快照 — 还原所有文件到快照时的内容
+ * @param {string} projectRoot
+ * @param {string} [snapshotId]  快照 ID（不传则回退最新）
+ * @param {boolean} [dryRun=false]
+ * @returns {{ restoredFiles: string[], skippedFiles: string[] }}
+ */
+export function rollbackSnapshot(projectRoot, snapshotId, dryRun = false) {
+  const snapshots = listSnapshots(projectRoot);
+  if (snapshots.length === 0) {
+    throw new Error("没有找到任何快照。请先执行 wk-scan fix 生成快照。");
+  }
+
+  let target;
+  if (snapshotId) {
+    target = snapshots.find(s => s.id === snapshotId);
+    if (!target) throw new Error(`快照 "${snapshotId}" 不存在。`);
+  } else {
+    target = snapshots[0]; // 最新
+  }
+
+  const manifest = JSON.parse(readFileSync(target.path, "utf8"));
+  const restoredFiles = [];
+  const skippedFiles = [];
+
+  for (const [relPath, b64Content] of Object.entries(manifest.files)) {
+    const absPath = join(projectRoot, relPath);
+    const original = Buffer.from(b64Content, "base64").toString("utf8");
+
+    if (!existsSync(absPath)) {
+      skippedFiles.push(relPath);
+      continue;
+    }
+
+    if (!dryRun) {
+      writeFileSync(absPath, original, "utf8");
+    }
+    restoredFiles.push(relPath);
+  }
+
+  return { snapshotId: target.id, restoredFiles, skippedFiles };
+}
+
+/**
+ * 查看快照与当前文件的差异摘要
+ * @param {string} projectRoot
+ * @param {string} [snapshotId]
+ * @returns {Array<{file, status}>}  status: 'changed' | 'unchanged' | 'missing'
+ */
+export function diffSnapshot(projectRoot, snapshotId) {
+  const snapshots = listSnapshots(projectRoot);
+  let target;
+  if (snapshotId) {
+    target = snapshots.find(s => s.id === snapshotId);
+  } else {
+    target = snapshots[0];
+  }
+  if (!target) throw new Error("快照不存在。");
+
+  const manifest = JSON.parse(readFileSync(target.path, "utf8"));
+  const results = [];
+
+  for (const [relPath, b64Content] of Object.entries(manifest.files)) {
+    const absPath = join(projectRoot, relPath);
+    if (!existsSync(absPath)) {
+      results.push({ file: relPath, status: "missing" });
+      continue;
+    }
+    const current = readFileSync(absPath, "utf8");
+    const original = Buffer.from(b64Content, "base64").toString("utf8");
+    results.push({
+      file: relPath,
+      status: current === original ? "unchanged" : "changed",
+    });
+  }
+
+  return results;
+}
+
+/**
+ * 清理旧快照，保留最近 N 个
+ * @param {string} projectRoot
+ * @param {number} keep
+ * @returns {number} 删除数量
+ */
+export function cleanSnapshots(projectRoot, keep = 5) {
+  const snapshots = listSnapshots(projectRoot);
+  let removed = 0;
+  for (let i = keep; i < snapshots.length; i++) {
+    unlinkSync(snapshots[i].path);
+    removed++;
+  }
+  return removed;
+}