@agile-team/wl-skills-ui 1.8.0 → 1.8.1

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to **@agile-team/wl-skills-ui** will be documented in this f
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.8.1] - 2026-05-13
+
+### Added
+
+- 新增 **`scanner/drift.mjs`** 漂移检测模块：对比基线与当前扫描 JSON，输出 gained / fixed / regressed 结构化报告。
+- 新增 CLI `wl-scan drift --baseline <f> --current <f>` 子命令，支持 `--output json` 和 `--fail-on-error` 门槛。
+- 新增 MCP 工具 **`wl_ui_drift`**：AI 可直接传入两份扫描 JSON 拿漂移报告。
+
 ## [1.8.0] - 2026-05-12
 
 ### Added

package/README.md

@@ -213,7 +213,7 @@ yarn add @agile-team/wl-skills-ui
 
 ## 版本亮点
 
-当前 v1.8.0 版本完成 R-rule 治理体系单一事实源化，并落地业务项目长效治理方案：
+当前 v1.8.1 版本完成 R-rule 治理体系单一事实源化，并落地业务项目长效治理方案：
 
 - 新增 **`standards/rules.json`** 作为 29 条 R-rule 的单一事实源；所有 standards 文档、SKILL.md、scanner、MCP、未来 ESLint 插件均从此派生
 - 新增 **`standards/rules-loader.mjs`** 共享加载器；新增 MCP 工具 **`wl_ui_list_rules`** / **`wl_ui_describe_rule`**，AI 写代码前一键查规则

package/mcp/server.js

@@ -133,6 +133,25 @@ const TOOLS = [
       required: ["id"],
     },
   },
+  {
+    name: "wl_ui_drift",
+    description:
+      "对比基线与当前扫描 JSON，输出漂移报告（gained / fixed / regressed）。用于 PR 级增量门槛。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        baselineJson: {
+          type: "string",
+          description: "基线扫描 JSON 字符串（.wl-baseline.json 的内容）",
+        },
+        currentJson: {
+          type: "string",
+          description: "当前扫描 JSON 字符串",
+        },
+      },
+      required: ["baselineJson", "currentJson"],
+    },
+  },
   {
     name: "wl_ui_recommend_flow",
     description:
@@ -495,6 +514,31 @@ async function dispatchTool(id, name, args) {
       });
       return;
     }
+    if (name === "wl_ui_drift") {
+      const { drift, formatDriftJson } = await import("../scanner/drift.mjs");
+      try {
+        const baseline = JSON.parse(args.baselineJson);
+        const current = JSON.parse(args.currentJson);
+        const result = drift(baseline, current);
+        sendResult(id, {
+          content: [{ type: "text", text: formatDriftJson(result) }],
+        });
+      } catch (e) {
+        sendResult(id, {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                { ok: false, reason: String(e.message) },
+                null,
+                2,
+              ),
+            },
+          ],
+        });
+      }
+      return;
+    }
     if (name === "wl_ui_recommend_flow") {
       sendResult(id, {
         content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 项目通用化妆/原生双模式（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",

package/scanner/drift.mjs

@@ -0,0 +1,179 @@
+/**
+ * scanner/drift.mjs — 漂移检测
+ *
+ * 对比 baseline（基线 JSON）与 current（当前扫描 JSON），输出结构化漂移报告。
+ * 指纹策略：file + rule（行号不稳定，不参与指纹）。同一 file+rule 多条则按数量 diff。
+ *
+ * 用法：
+ *   import { drift, formatDriftText } from '@agile-team/wl-skills-ui/scanner/drift.mjs'
+ *   const result = drift(baselineJson, currentJson)
+ *   console.log(formatDriftText(result))
+ *
+ * CLI（由 scanner/index.mjs 调用）：
+ *   npx wl-ui drift --baseline .wl-baseline.json --current .wl-current.json
+ *
+ * 事实源：standards/rules.json
+ */
+import { readFileSync, existsSync } from "node:fs";
+
+// ── 指纹 ────────────────────────────────────────────────────────────────────
+
+function fingerprint(issue) {
+  return `${issue.file}\x00${issue.rule}`;
+}
+
+function buildCountMap(issues) {
+  const map = new Map();
+  for (const iss of issues) {
+    const key = fingerprint(iss);
+    map.set(key, (map.get(key) || 0) + 1);
+  }
+  return map;
+}
+
+// ── 核心 diff ───────────────────────────────────────────────────────────────
+
+/**
+ * @param {object} baseline  JSON 扫描结果（含 issues 数组）
+ * @param {object} current   JSON 扫描结果（含 issues 数组）
+ * @returns {DriftResult}
+ */
+export function drift(baseline, current) {
+  const baseIssues = baseline.issues || [];
+  const curIssues = current.issues || [];
+  const baseMap = buildCountMap(baseIssues);
+  const curMap = buildCountMap(curIssues);
+
+  const allKeys = new Set([...baseMap.keys(), ...curMap.keys()]);
+
+  const gained = []; // 新增（当前有、基线无 或 当前 > 基线）
+  const fixed = []; // 消化（基线有、当前无 或 当前 < 基线）
+  const regressed = []; // 回归预留（后续可扩展 fix-then-break 检测）
+
+  for (const key of allKeys) {
+    const [file, rule] = key.split("\x00");
+    const baseCount = baseMap.get(key) || 0;
+    const curCount = curMap.get(key) || 0;
+    const delta = curCount - baseCount;
+    if (delta > 0) {
+      gained.push({ file, rule, delta, baseCount, curCount });
+    } else if (delta < 0) {
+      fixed.push({ file, rule, delta, baseCount, curCount });
+    }
+    // delta === 0 → 无变化，跳过
+  }
+
+  // 按规则 & 目录 聚合
+  const byRule = aggregate(gained, "rule");
+  const byDir = aggregateDir(gained);
+  const fixedByRule = aggregate(fixed, "rule");
+
+  return {
+    baselineTotal: baseIssues.length,
+    currentTotal: curIssues.length,
+    netDelta: curIssues.length - baseIssues.length,
+    gained: { count: sumDelta(gained), items: gained },
+    fixed: { count: Math.abs(sumDelta(fixed)), items: fixed },
+    regressed: { count: 0, items: regressed },
+    topGainedByRule: sortDesc(byRule).slice(0, 5),
+    topGainedByDir: sortDesc(byDir).slice(0, 5),
+    topFixedByRule: sortDesc(fixedByRule).slice(0, 5),
+  };
+}
+
+function sumDelta(arr) {
+  return arr.reduce((s, i) => s + Math.abs(i.delta), 0);
+}
+
+function aggregate(items, field) {
+  const map = new Map();
+  for (const it of items) {
+    const key = it[field];
+    map.set(key, (map.get(key) || 0) + Math.abs(it.delta));
+  }
+  return [...map.entries()].map(([key, count]) => ({ key, count }));
+}
+
+function aggregateDir(items) {
+  const map = new Map();
+  for (const it of items) {
+    const parts = it.file.split("/");
+    const dir = parts.length > 1 ? parts.slice(0, -1).join("/") : ".";
+    map.set(dir, (map.get(dir) || 0) + Math.abs(it.delta));
+  }
+  return [...map.entries()].map(([key, count]) => ({ key, count }));
+}
+
+function sortDesc(arr) {
+  return arr.sort((a, b) => b.count - a.count);
+}
+
+// ── 文本格式化 ──────────────────────────────────────────────────────────────
+
+export function formatDriftText(result) {
+  const lines = [];
+  lines.push("╭──────────────────────────────────────╮");
+  lines.push("│        wl-skills-ui 漂移报告         │");
+  lines.push("╰──────────────────────────────────────╯");
+  lines.push("");
+  lines.push(`基线违规: ${result.baselineTotal}  →  当前违规: ${result.currentTotal}  (${result.netDelta >= 0 ? "+" : ""}${result.netDelta})`);
+  lines.push("");
+  lines.push(`  🔴 gained   +${result.gained.count}  新增违规`);
+  lines.push(`  🟢 fixed    -${result.fixed.count}  消化历史`);
+  if (result.regressed.count > 0) {
+    lines.push(`  🟡 regressed +${result.regressed.count}  回归`);
+  }
+  lines.push("");
+
+  if (result.topGainedByRule.length > 0) {
+    lines.push("新增 Top 规则:");
+    for (const { key, count } of result.topGainedByRule) {
+      lines.push(`  ${key}  +${count}`);
+    }
+    lines.push("");
+  }
+
+  if (result.topGainedByDir.length > 0) {
+    lines.push("新增 Top 目录:");
+    for (const { key, count } of result.topGainedByDir) {
+      lines.push(`  ${key}  +${count}`);
+    }
+    lines.push("");
+  }
+
+  if (result.topFixedByRule.length > 0) {
+    lines.push("消化 Top 规则:");
+    for (const { key, count } of result.topFixedByRule) {
+      lines.push(`  ${key}  -${count}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// ── JSON 格式化 ─────────────────────────────────────────────────────────────
+
+export function formatDriftJson(result) {
+  return JSON.stringify(result, null, 2);
+}
+
+// ── 文件级便捷 API ──────────────────────────────────────────────────────────
+
+/**
+ * 从两个 JSON 文件路径生成漂移报告
+ * @param {string} baselinePath
+ * @param {string} currentPath
+ * @returns {DriftResult}
+ */
+export function driftFromFiles(baselinePath, currentPath) {
+  if (!existsSync(baselinePath)) {
+    throw new Error(`基线文件不存在: ${baselinePath}`);
+  }
+  if (!existsSync(currentPath)) {
+    throw new Error(`当前扫描结果不存在: ${currentPath}`);
+  }
+  const baseline = JSON.parse(readFileSync(baselinePath, "utf8"));
+  const current = JSON.parse(readFileSync(currentPath, "utf8"));
+  return drift(baseline, current);
+}

package/scanner/index.mjs

@@ -11,6 +11,7 @@
  *   wl-scan fix --target <path> --dry-run
  *   wl-scan all --project <path>          # 接入检查 + 风格扫描 + 报告
  *   wl-scan init                          # 打印接入指引
+ *   wl-scan drift --baseline <f> --current <f>  # 漂移检测
  *   wl-scan snapshot list                  # 列出快照
  *   wl-scan snapshot rollback [--id <id>]  # 回退到快照（默认最新）
  *   wl-scan snapshot diff [--id <id>]      # 查看快照与当前差异
@@ -43,6 +44,7 @@ const SUBCOMMANDS = new Set([
   "fix",
   "all",
   "init",
+  "drift",
   "snapshot",
 ]);
 let subcommand = "scan";
@@ -67,6 +69,8 @@ const { values } = parseArgs({
     keep: { type: "string", default: "5" },
     "no-snapshot": { type: "boolean", default: false },
     exempt: { type: "string", default: "" },
+    baseline: { type: "string", default: "" },
+    current: { type: "string", default: "" },
   },
   strict: false,
 });
@@ -263,6 +267,27 @@ if (subcommand === "check") {
   process.exit(values["fail-on-error"] && hasError ? 1 : 0);
 }
 
+if (subcommand === "drift") {
+  const { driftFromFiles, formatDriftText, formatDriftJson } =
+    await import("./drift.mjs");
+  const baselinePath = resolve(values.baseline || ".wl-baseline.json");
+  const currentPath = resolve(values.current);
+  if (!values.current) {
+    console.error(
+      "用法: wl-scan drift --baseline .wl-baseline.json --current .wl-current.json",
+    );
+    process.exit(1);
+  }
+  const result = driftFromFiles(baselinePath, currentPath);
+  if (values.output === "json") {
+    console.log(formatDriftJson(result));
+  } else {
+    console.log(formatDriftText(result));
+  }
+  const hasNew = result.gained.count > 0;
+  process.exit(values["fail-on-error"] && hasNew ? 1 : 0);
+}
+
 if (subcommand === "snapshot") {
   const projectRoot = resolve(values.project);
   const sub = args[0] || "list";