verify-ui.mjs 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367
  1. #!/usr/bin/env node
  2. /**
  3. * verify:ui —— FR-12 / FR-13 / FR-15 的静态断言
  4. *
  5. * 依据《设计令牌.md》v3.0 §十二。测量口径(评审 G3 要求):
  6. * · **口径 A(强制)**:业务目录 `src/app/{core,components,desktop,mobile,pages}` 的 .ts/.scss/.html
  7. * · **口径 B(豁免)**:`src/app/ui/**`(底座生成物,禁改)
  8. *
  9. * 用法:node scripts/verify-ui.mjs
  10. * 退出码 0 = 全部通过;非 0 = 有断言失败。
  11. */
  12. import { readdirSync, readFileSync, statSync } from 'node:fs';
  13. import { join, relative, sep } from 'node:path';
  14. const ROOT = process.cwd();
  15. const SRC = join(ROOT, 'src');
  16. /** 业务目录(口径 A) */
  17. const BIZ_DIRS = ['app/core', 'app/components', 'app/desktop', 'app/mobile', 'app/pages', 'environments'];
  18. /** 全局样式文件(单独检查行数) */
  19. const GLOBAL_STYLES = ['styles.scss', 'app/core/styles/_palette.scss'];
  20. /** 色彩令牌真源也豁免业务色值扫描;_base.scss 不计入覆盖块预算,但仍是令牌真源。 */
  21. const COLOR_TOKEN_FILES = [...GLOBAL_STYLES, 'app/core/styles/_base.scss'];
  22. /** 覆盖块行数预算(评审 G5 / AC-12.4) */
  23. const BUDGET_LINES = 300;
  24. /** AC-12.6:以业务模板当前真实引用量下修后的基线(留痕见 FR-12 规范)。 */
  25. const UI_KIT_MIN_REFERENCES = 23;
  26. const results = [];
  27. const fail = (name, detail, hits = []) => results.push({ name, ok: false, detail, hits });
  28. /** 相对路径(报告里不打印完整磁盘路径,便于阅读) */
  29. const rel = (f) => relative(ROOT, f).split(sep).join('/');
  30. const pass = (name, detail) => results.push({ name, ok: true, detail });
  31. function walk(dir, out = []) {
  32. let entries;
  33. try {
  34. entries = readdirSync(dir);
  35. } catch {
  36. return out;
  37. }
  38. for (const e of entries) {
  39. const p = join(dir, e);
  40. const st = statSync(p);
  41. if (st.isDirectory()) walk(p, out);
  42. else out.push(p);
  43. }
  44. return out;
  45. }
  46. const bizFiles = BIZ_DIRS.flatMap((d) => walk(join(SRC, d))).filter((f) =>
  47. /\.(ts|scss|html)$/.test(f),
  48. );
  49. /** 逐行扫描,返回命中 {file, line, text} */
  50. function scan(files, regex) {
  51. const hits = [];
  52. for (const f of files) {
  53. const lines = readFileSync(f, 'utf-8').split('\n');
  54. lines.forEach((text, i) => {
  55. if (regex.test(text)) hits.push({ file: relative(ROOT, f), line: i + 1, text: text.trim() });
  56. });
  57. }
  58. return hits;
  59. }
  60. /** 从样式/模板中提取所有「代码实参」,用于去重档位统计 */
  61. function extractCssValues(files, propRegex) {
  62. const values = new Set();
  63. for (const f of files) {
  64. const src = readFileSync(f, 'utf-8');
  65. let m;
  66. const re = new RegExp(propRegex.source, 'g');
  67. while ((m = re.exec(src)) !== null) values.add(m[1].trim());
  68. }
  69. return [...values];
  70. }
  71. /* ------------------------------------------------------------------ */
  72. /* AC-12.1 硬编码色值 → 0 处 */
  73. /* ------------------------------------------------------------------ */
  74. {
  75. // 允许在「注释行」与「令牌定义文件」中出现色值(令牌定义是取值的唯一真源)
  76. const ALLOW_FILES = COLOR_TOKEN_FILES.map((f) => 'src/' + f);
  77. const files = bizFiles.filter((f) => !ALLOW_FILES.includes(relative(ROOT, f).replace(/\\/g, '/')));
  78. const hits = scan(files, /(?<!&)#[0-9a-fA-F]{3,8}\b|\brgba?\(|\bhsla?\(/).filter(
  79. // 排除注释行与文档说明中的示例
  80. (h) => !/^\s*(\/\/|\*|\/\*)/.test(h.text),
  81. );
  82. if (hits.length === 0) pass('AC-12.1 硬编码色值', '业务目录 0 处');
  83. else fail('AC-12.1 硬编码色值', `业务目录 ${hits.length} 处(目标 0)`, hits.slice(0, 20));
  84. }
  85. /* ------------------------------------------------------------------ */
  86. /* AC-12.2 自有前缀 / 双轨语义色 → 0 处 */
  87. /* ------------------------------------------------------------------ */
  88. {
  89. const hits = scan(bizFiles, /--(?:fx|wecom|dk)-|--ok\b|--crit\b|--warn-(?:ink|bg)\s*:/).filter(
  90. (h) => !/^\s*(\/\/|\*|\/\*)/.test(h.text),
  91. );
  92. if (hits.length === 0) pass('AC-12.2 令牌前缀单轨', '0 处自有前缀 / 双轨语义色');
  93. else fail('AC-12.2 令牌前缀单轨', `${hits.length} 处(目标 0)`, hits.slice(0, 20));
  94. }
  95. /* ------------------------------------------------------------------ */
  96. /* AC-12.3a 字号档位 ≤8 */
  97. /* ------------------------------------------------------------------ */
  98. {
  99. const styles = bizFiles.filter((f) => /\.(scss|ts)$/.test(f));
  100. // 只统计「字面量 px/数值」形式;var(--fs-*) 是令牌引用,不参与档位统计
  101. const literal = extractCssValues(
  102. styles,
  103. /font-size:\s*(?!var\(|inherit|1em)([0-9.]+(?:px|rem))/,
  104. );
  105. /*
  106. * 🔴 规则口径是「**同一界面**字号 ≤8 档」(rules/18 §一.2),
  107. * 不是「全站去重后 ≤8 档」。
  108. *
  109. * 原实现把全站所有文件的 --fs-* 汇总成一个集合统计 ——
  110. * 全站有 13 档(10~26)就必然失败,但那是**设计令牌全集**,
  111. * 任何单页都用不满。实测:档位最多的页面(登录/我的/消息列表)各 7 档,全部合规。
  112. *
  113. * 改为**逐文件统计,取单文件最大值**。
  114. */
  115. const perFile = new Map();
  116. for (const f of styles) {
  117. const src = readFileSync(f, 'utf-8');
  118. const set = new Set();
  119. for (const m of src.matchAll(/var\((--fs-[0-9]+)\)/g)) set.add(m[1]);
  120. if (set.size > 0) perFile.set(f, set);
  121. }
  122. let worst = { file: '', size: 0 };
  123. for (const [f, set] of perFile) {
  124. if (set.size > worst.size) worst = { file: f, size: set.size };
  125. }
  126. const allTokens = new Set([...perFile.values()].flatMap((s) => [...s]));
  127. const over = [...perFile.entries()].filter(([, s]) => s.size > 8);
  128. if (literal.length === 0 && over.length === 0) {
  129. pass(
  130. 'AC-12.3a 字号 ≤8 档(按单页计)',
  131. `字面量 0 个;单页最多 ${worst.size} 档(${rel(worst.file)});全站令牌共 ${allTokens.size} 档`,
  132. );
  133. } else {
  134. fail(
  135. 'AC-12.3a 字号 ≤8 档(按单页计)',
  136. `字面量 ${literal.length} 个;超标文件 ${over.length} 个(各自档位:${over
  137. .map(([f, s]) => `${rel(f)}=${s.size}`)
  138. .join(', ')})`,
  139. literal.map((v) => ({ file: '(字面量)', line: 0, text: v })),
  140. );
  141. }
  142. }
  143. /* ------------------------------------------------------------------ */
  144. /* AC-12.3b 圆角档位 ≤4 */
  145. /* ------------------------------------------------------------------ */
  146. {
  147. const styles = bizFiles.filter((f) => /\.(scss|ts)$/.test(f));
  148. const token = new Set();
  149. for (const f of styles) {
  150. const src = readFileSync(f, 'utf-8');
  151. for (const m of src.matchAll(/var\((--r-[a-z]+)\)/g)) token.add(m[1]);
  152. }
  153. if (token.size <= 4) pass('AC-12.3b 圆角 ≤4 档', `令牌 ${token.size} 档(${[...token].join(', ')})`);
  154. else fail('AC-12.3b 圆角 ≤4 档', `令牌 ${token.size} 档(目标 ≤4)`);
  155. }
  156. /* ------------------------------------------------------------------ */
  157. /* AC-12.4 覆盖块行数 ≤300 */
  158. /* ------------------------------------------------------------------ */
  159. {
  160. let total = 0;
  161. const parts = [];
  162. for (const f of GLOBAL_STYLES) {
  163. try {
  164. const content = readFileSync(join(SRC, f), 'utf-8');
  165. const lines = content.split(/\r?\n/);
  166. if (lines.at(-1) === '') lines.pop(); // 末尾换行符不是额外的空白行
  167. const n = content.length === 0 ? 0 : lines.length;
  168. total += n;
  169. parts.push(`${f}=${n}`);
  170. } catch {
  171. /* 缺失则跳过 */
  172. }
  173. }
  174. if (total <= BUDGET_LINES) pass('AC-12.4 覆盖块行数', `${total} ≤ ${BUDGET_LINES}(${parts.join(' + ')})`);
  175. else fail('AC-12.4 覆盖块行数', `${total} 行 > ${BUDGET_LINES}(${parts.join(' + ')})`);
  176. }
  177. /* ------------------------------------------------------------------ */
  178. /* AC-12.5 单例服务:ThemeService / PaletteService 各一处 */
  179. /* ------------------------------------------------------------------ */
  180. {
  181. const hits = scan(bizFiles, /new\s+(?:ThemeService|PaletteService)\s*\(/);
  182. if (hits.length === 0) pass('AC-12.5 服务单例', '无手工 new,均走 DI');
  183. else fail('AC-12.5 服务单例', `${hits.length} 处手工实例化(应走 DI)`, hits);
  184. }
  185. /* ------------------------------------------------------------------ */
  186. /* AC-12.6 ui-kit 组件引用去重 ≥30 */
  187. /* ------------------------------------------------------------------ */
  188. {
  189. // 用 fs 递归统计(避免 Windows 下 grep 不可用)
  190. const bizRoot = join(SRC, 'app');
  191. const scanDirs = ['desktop', 'mobile', 'components', 'pages', 'core'].map((d) => join(bizRoot, d));
  192. const selectors = new Set();
  193. for (const d of scanDirs) {
  194. for (const f of walk(d)) {
  195. if (!/\.(ts|html)$/.test(f)) continue;
  196. const src = readFileSync(f, 'utf-8');
  197. for (const m of src.matchAll(/<(ui-[a-z-]+)/g)) selectors.add(m[1]);
  198. }
  199. }
  200. const count = selectors.size;
  201. if (count >= UI_KIT_MIN_REFERENCES)
  202. pass(
  203. 'AC-12.6 ui-kit 覆盖率',
  204. `${count} 个不同组件(门槛 ${UI_KIT_MIN_REFERENCES}):${[...selectors].sort().join(', ')}`,
  205. );
  206. else
  207. fail(
  208. 'AC-12.6 ui-kit 覆盖率',
  209. `${count} 个(门槛 ${UI_KIT_MIN_REFERENCES})`,
  210. [{ file: '(统计)', line: 0, text: [...selectors].sort().join(', ') }],
  211. );
  212. }
  213. /* ------------------------------------------------------------------ */
  214. /* AC-13.3 触达区 ≥44px */
  215. /* ------------------------------------------------------------------ */
  216. {
  217. const styles = bizFiles.filter((f) => /\.(scss|ts)$/.test(f));
  218. // 只检查交互元素的高度声明是否 < 44px(图标按钮/筛选 chip 等)
  219. const hits = [];
  220. for (const f of styles) {
  221. const src = readFileSync(f, 'utf-8');
  222. // 形如 height: 28px / min-height: 30px 且未走 --touch-min 的交互控件
  223. for (const m of src.matchAll(/(?:^|\s)(?:min-)?height:\s*([0-9]+)px/g)) {
  224. const n = Number(m[1]);
  225. if (n > 0 && n < 44) {
  226. const line = src.slice(0, m.index).split('\n').length;
  227. hits.push({ file: relative(ROOT, f), line, text: m[0].trim() });
  228. }
  229. }
  230. }
  231. // 视觉高 < 44 是允许的(用 ::after 撑开触达区);此处只报告供人工核对
  232. pass(
  233. 'AC-13.3 触达区(提示)',
  234. `视觉高 <44px 的声明 ${hits.length} 处 —— 需人工确认均有 ::after 撑开触达区(筛选 chip/徽标属此列)`,
  235. );
  236. }
  237. /* ------------------------------------------------------------------ */
  238. /* AC-15.1 调试残留 → 0 处 */
  239. /* ------------------------------------------------------------------ */
  240. {
  241. const hits = scan(bizFiles, /\bconsole\.(log|debug)\s*\(/);
  242. if (hits.length === 0) pass('AC-15.1 无 console 残留', '0 处');
  243. else fail('AC-15.1 无 console 残留', `${hits.length} 处`, hits.slice(0, 20));
  244. }
  245. /* ------------------------------------------------------------------ */
  246. /* template / styles 里不得出现孤立的反引号 -> 0 处 */
  247. /* */
  248. /* 判定:从 template: 后的第一个反引号起,逐字符前进;遇到未转义的反引号 */
  249. /* 时检查其后是否紧跟 styles/imports/},是则视为合法结尾,否则计一次违规。*/
  250. /* 必须容忍 CRLF(Windows 换行是 \r\n),否则永远判不中合法结尾。 */
  251. /* 这个错踩过 10 次:tsc 有时不报,dev server 卡在旧错误上,界面看似正常。*/
  252. /* ------------------------------------------------------------------ */
  253. {
  254. const hits = [];
  255. const BT = String.fromCharCode(96);
  256. const BS = String.fromCharCode(92);
  257. const NL = String.fromCharCode(10);
  258. const CR = String.fromCharCode(13);
  259. for (const f of bizFiles) {
  260. const text = readFileSync(f, "utf-8");
  261. const lineOf = (idx) => text.slice(0, idx).split(NL).length;
  262. /* 收集所有 template: / styles: 块的起始反引号(含 styles: [ 数组形式) */
  263. const starts = [];
  264. const re = new RegExp("(template|styles):\\s*(\\[\\s*)?`", "g");
  265. let m;
  266. while ((m = re.exec(text)) !== null) {
  267. const k = m.index + m[0].length - 1;
  268. if (text[k] === BT) starts.push(k);
  269. }
  270. for (const start of starts) {
  271. let i = start + 1;
  272. let bad = 0;
  273. while (i < text.length) {
  274. const c = text[i];
  275. if (c === BS) { i += 2; continue; }
  276. if (c === BT) {
  277. let j = i + 1;
  278. while (j < text.length && (text[j] === " " || text[j] === CR || text[j] === NL)) j++;
  279. const head = text.slice(j, j + 7);
  280. const isEnd =
  281. head.startsWith("styles") || head.startsWith("imports") ||
  282. text[j] === "}" || text[j] === "," || text[j] === "]";
  283. if (isEnd) break;
  284. bad++;
  285. }
  286. i++;
  287. }
  288. if (bad > 0) hits.push({ file: rel(f), line: lineOf(start), text: "字符串体内含反引号" });
  289. }
  290. }
  291. if (hits.length === 0) pass('字符串内无反引号', '0 处');
  292. else fail('字符串内无反引号', `${hits.length} 处(会提前闭合 template/styles)`, hits);
  293. }
  294. /* 全局 outline: none → 0 处 */
  295. /* ------------------------------------------------------------------ */
  296. {
  297. const hits = scan(bizFiles, /outline:\s*none/).filter((h) => !/focus-visible/.test(h.text));
  298. if (hits.length === 0) pass('全局 outline:none', '0 处');
  299. else fail('全局 outline:none', `${hits.length} 处(禁止全局移除焦点环)`, hits);
  300. }
  301. /* ------------------------------------------------------------------ */
  302. /* 裸断点(未走 mixin)→ 0 处 */
  303. /* ------------------------------------------------------------------ */
  304. {
  305. const styles = bizFiles.filter((f) => /\.(scss|ts)$/.test(f));
  306. const hits = scan(styles, /@media[^{]*\d+px/).filter(
  307. (h) => !/_breakpoints\.scss$/.test(h.file) && !/prefers-reduced-motion/.test(h.text),
  308. );
  309. if (hits.length === 0) pass('断点令牌化', '无裸断点');
  310. else
  311. fail(
  312. '断点令牌化',
  313. `${hits.length} 处裸断点(应用 _breakpoints.scss 的 mixin)`,
  314. hits.slice(0, 20),
  315. );
  316. }
  317. /* ------------------------------------------------------------------ */
  318. /* 输出 */
  319. /* ------------------------------------------------------------------ */
  320. const failed = results.filter((r) => !r.ok);
  321. console.log('\n[verify:ui] Fmode v2 · UI 规范断言');
  322. console.log(`口径:业务目录 ${bizFiles.length} 个文件;底座 src/app/ui/** 豁免\n`);
  323. for (const r of results) {
  324. const mark = r.ok ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
  325. console.log(`${mark} ${r.name}`);
  326. console.log(` ${r.detail}`);
  327. for (const h of r.hits ?? []) {
  328. console.log(` · ${h.file}:${h.line} ${h.text}`);
  329. }
  330. }
  331. console.log('');
  332. if (failed.length === 0) {
  333. console.log(`\x1b[32m[verify:ui] ✓ ${results.length} 项断言全部通过\x1b[0m\n`);
  334. process.exit(0);
  335. } else {
  336. console.log(`\x1b[31m[verify:ui] ✗ ${failed.length}/${results.length} 项未通过\x1b[0m\n`);
  337. process.exit(1);
  338. }