nex_animation/scripts/ui/classaudit.mjs

743 lines
40 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

#!/usr/bin/env node
/**
* 类名体检:抓「写了但生成不出规则」的死类名。
*
* 为什么要它:Tailwind v4 改过一批名字(break-anywhere → wrap-anywhere、
* font-inherit 直接没了),写错不报错,只是静悄悄没有样式,肉眼很难发现。
*
* 做法:把项目真正的入口 CSS 喂给 Tailwind 编译器,逐个候选问它
* 「这个词你能生成规则吗」。产物里有对应类选择器 = 有效,没有 = 死类名。
* 判定用的是构建时同一套配置(@theme 语义色、自定义断点、@utility),不会误报。
*
* 第二道检查(2026-11 图标重设计加的):图标只许从 components/icons 取。
* 全站唯一允许 `from '@ant-design/icons'` 的文件是那张登记表。
* 为什么必须钉住:页面一旦直接 import 字形名(AppstoreOutlined),
* 「这个位置到底是网格视图还是资产库」就又只有读代码的人才知道,
* 换图标也又变成全站搜索替换——登记表当天就废掉。
*
* 第三道检查(2026-11 按钮重设计加的):裸 <button> 只许出现在「自定义表面族」里。
* 判据不是「长得特殊」,而是几何:控件的宽高由所在的那块媒体/容器决定、
* antd 三档(24/32/40)套不进去的,才是自定义表面(走带键、角标、遮罩、胶囊);
* 只要是一颗独立矩形按钮,就必须是 antd <Button>,否则它不吃 theme token,
* 换主题、改 controlHeight、加 disabled 语义时全都得手工再对一遍。
* 白名单文件必须仍然写着 nex-* 标记类——标记类是给 CSS 和截图复核用的抓手,
* 一个都不写了说明这一族已经被 antd 取代,条目就该从白名单里删掉。
*
* 第四道检查(2026-11 按钮重设计加的):浮层底部(Drawer 的 actions / Modal 的 footer)
* 是一个「动作条」,不是一堆各写各的按钮。它只有一条口径,且必须能被机器验出来:
* 从左到右 = 辅助动作 → 取消 → 主行动(和 antd Modal 自带页脚同序),整条右对齐。
* 为什么把顺序也钉进脚本:这条是**语义**约定而不是样式约定,CSS 里没处可查;
* 一旦某个抽屉把「保存」写在「取消」左边,全站抽屉就开始互相不一致,
* 而这种漂移肉眼极难发现——只能靠脚本逐块读 DOM 顺序。
*
* 用法:node scripts/ui/classaudit.mjs [src 目录]
*/
import fs from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
const HERE = path.dirname(fileURLToPath(import.meta.url))
const FRONTEND = path.resolve(HERE, '../../frontend')
const { compile } = await import(path.join(FRONTEND, 'node_modules/tailwindcss/dist/lib.mjs'))
const SRC = path.resolve(process.argv[2] || path.join(FRONTEND, 'src'))
const ENTRY = path.join(FRONTEND, 'src/styles/index.css')
/** antd 自己的类、我们的体检标记、自有组件类:都不是 Tailwind 的活 */
const FOREIGN = /^(ant|nex|nf)-/
/**
* 剥掉一行里的注释,并返回「这一行结束时是否仍在块注释里」。
*
* 症状(2026-11 第 4 道闸上线后冒出来的假阳性):块注释的**续行**不以 `*` 开头,
* 于是「… .ant-segmented-item-label 的 overflow:hidden 裁掉半个字」收尾的那一行
* 被当成源码用词,`overflow:hidden` 报成死类名——可它根本不是类名,是中文注释里的
* 一个 CSS 属性。旧判据只看行首,天然处理不了跨行注释。
* 做法:真的跟着块注释开合标记走状态;同一行内的整段抹掉,
* 行首 // 与行尾 ` // `(代码里不会出现裸双斜杠)一并抹掉。
*/
function stripComments(line, wasInBlock) {
let inBlock = wasInBlock()
let q = null // 引号内的 /* 与 // 不是注释;字符串本身要留着(className 就在引号里)
let out = ''
for (let i = 0; i < line.length; i++) {
const ch = line[i]
const two = line.slice(i, i + 2)
if (inBlock) {
if (two === '*/') { inBlock = false; i++ }
continue
}
if (q) {
out += ch
if (ch === '\\') { if (i + 1 < line.length) { out += line[i + 1]; i++ } continue }
if (ch === q) q = null
continue
}
if (ch === '"' || ch === "'" || ch === '`') { q = ch; out += ch; continue }
if (two === '/*') { inBlock = true; i++; continue }
if (two === '//') break
out += ch
}
return [out, inBlock]
}
function candidates() {
const out = new Map()
const walk = (dir) => {
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, ent.name)
if (ent.isDirectory()) { walk(p); continue }
if (!/\.(tsx|jsx)$/.test(ent.name)) continue
let inBlock = false // 块注释状态要跨行:只看行首会漏掉续行(见 stripComments)
inBlock = false
fs.readFileSync(p, 'utf8').split('\n').forEach((raw, i) => {
const [line, block] = stripComments(raw, () => inBlock)
inBlock = block
if (!line.trim()) return
for (const tok of line.split(/[\s'"`]+/)) {
if (tok.length < 3 || /-$/.test(tok) || FOREIGN.test(tok)) continue
if (/[一-龥]/.test(tok)) continue
if (!/^[a-z]/.test(tok)) continue
if (!/^[\w:[\]().,%#*/=&>+~-]+$/.test(tok)) continue
for (const ch of '[]()') {
const open = ch === '[' || ch === '('
const n = (tok.split(ch).length - 1)
const mate = open ? (ch === '[' ? ']' : ')') : (ch === ']' ? '[' : '(')
if (n !== tok.split(mate).length - 1) return
}
const at = `${path.relative(FRONTEND, p)}:${i + 1}`
if (!out.has(tok)) out.set(tok, [])
out.get(tok).push(at)
}
})
}
}
walk(SRC)
return out
}
function generated(css) {
const set = new Set()
for (const m of css.matchAll(/\.((?:\\.|[-\w])+)/g)) set.add(m[1].replace(/\\(.)/g, '$1'))
return set
}
const compiler = await compile(fs.readFileSync(ENTRY, 'utf8'), {
base: path.dirname(ENTRY),
async loadStylesheet(id, base) {
let p = id.startsWith('.') ? path.resolve(base, id) : path.resolve(FRONTEND, 'node_modules', id)
if (fs.existsSync(p) && fs.statSync(p).isDirectory()) p = path.join(p, 'index.css')
return { path: p, base: path.dirname(p), content: fs.readFileSync(p, 'utf8') }
},
async loadModule(p, base) { return { module: null, base } },
})
const cands = candidates()
const all = generated(compiler.build([...cands.keys()]))
/** 首段(grid / text / max-h …)在产物里出现过的,才认为「本该是工具类」 */
const roots = new Set()
for (const name of all) {
const core = name.split(':').pop().replace(/\[[^\]]*\].*$/, '')
roots.add(core.split('-')[0])
}
/** 文案 / props 值 / antd Menu 的 group key —— 是英语单词,不是类名 */
const PROSE = new Set([
'align', 'break', 'duration', 'flex-end', 'gap', 'items', 'left', 'list', 'max',
'max-height', 'min', 'min-width', 'not', 'object', 'order', 'pointer', 'right',
'row', 'text', 'top', 'group-global', 'group-project',
/* 2026-11 布局层改用 antd Flex 后多出来的三个 props 值 / CSS 取值:
`wrap` 是 <Flex wrap> 这个布尔属性本身、`space-between` 是 justify="space-between"、
`not-allowed` 是 style 里的 cursor、`flex-start` 是 <Flex align="flex-start">。
Tailwind 里对应的事各有正名
(flex-wrap / justify-between / cursor-not-allowed),这三个词当类名写出来必然是笔误,
但作为 props 值天天出现,逐行切词分不清引号内外,只能在这里点名。 */
'wrap', 'space-between', 'not-allowed', 'flex-start',
])
const dead = []
for (const [tok, where] of cands) {
if (all.has(tok)) continue
const core = tok.split(':').pop()
if (/^\d+$/.test(core) || /^[\w-]+\[[a-z0-9]\]$/.test(core)) continue // 模板字符串里的 key 片段
const root = core.replace(/\[[^\]]*\]/g, '').split('-').filter(Boolean)[0]
if (!root || !roots.has(root) || PROSE.has(core)) continue
dead.push([tok, where])
}
dead.sort((a, b) => a[0].localeCompare(b[0]))
for (const [tok, where] of dead) console.log(`DEAD ${tok.padEnd(26)} ${where.join(' ')}`)
console.log(`\n${dead.length} 个死类名 / ${cands.size} 个候选`)
/* ── 第 2 条:图标出口唯一 ───────────────────────────────────────────────
登记表自己是唯一可以 import 字形名的文件;其余文件一律写语义别名
(IconGrid / IconWarn / IconTimeline),要新图形先在登记表登记一行。 */
const REGISTRY = path.join(SRC, 'components/icons/index.ts')
const stray = []
const walkIcons = (dir) => {
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, ent.name)
if (ent.isDirectory()) { walkIcons(p); continue }
if (!/\.(tsx|ts)$/.test(ent.name) || p === REGISTRY) continue
fs.readFileSync(p, 'utf8').split('\n').forEach((line, i) => {
if (/from '@ant-design\/icons'/.test(line)) stray.push(`${path.relative(FRONTEND, p)}:${i + 1}: ${line.trim()}`)
})
}
}
walkIcons(SRC)
for (const hit of stray) console.log(`ICON ${hit}`)
console.log(`${stray.length} 处绕过登记表的图标 import(只许 ${path.relative(FRONTEND, REGISTRY)})`)
/* ── 第 2 条·附:登记表自身的辅助技术口径(2026-11-08 · S-2)───────────────
上面那条只管「别人不许 import 字形」,管不到登记表自己怎么写出口。
`decorative()` 把「图标默认是装饰」写死在唯一的出口上(登记表顶部规则 5);
绕过它的三种写法都会让英文字形名重新混进可读名称——「upload 导入脚本」
「down 导出」就是这么来的(取证:reports/ui_evidence/nex-s2/ax-BEFORE.json):
a) 裸 re-export: export { UploadOutlined } from '@ant-design/icons'
b) 直接赋值: export const IconUpload = UploadOutlined
c) 换名再导出: export { UploadOutlined as IconUpload }
对账逐条匹配固定形状 `export const IconX = decorative(Glyph, 'IconX')`:
加图标的人只会复制旁边一行,不会先读注释,所以形状不对就红。
反例由 scripts/ui/gateprobe.py 注入验证(改一条注释不会把这条闸改成恒绿)。 */
const REG_NAME = path.relative(FRONTEND, REGISTRY)
const regSrc = fs.readFileSync(REGISTRY, 'utf8')
const regHits = []
for (const m of regSrc.matchAll(/^export\s*\{([^}]*)\}/gm)) {
if (/\bIcon[A-Z]\w*\b|Outlined|Filled|TwoTone/.test(m[1]))
regHits.push(`${REG_NAME}: 图标走了 export {${m[1].trim().slice(0, 54)}}`
+ ` —— 不吃 decorative(),字形名会重新进辅助技术树`)
}
const regIcons = [...regSrc.matchAll(/^export const (Icon\w+)\s*=\s*([^\n]*)$/gm)]
for (const [, name, rhs] of regIcons) {
if (!new RegExp(`^decorative\\(\\w+\\s*,\\s*'${name}'\\)$`).test(rhs.trim()))
regHits.push(`${REG_NAME}: ${name} 的出口不是 decorative(Glyph, '${name}')(现在是 ${rhs.trim().slice(0, 46)})`
+ ` —— 图标默认必须 aria-hidden,需要图标自己承担语义时显式写 aria-label`)
}
if (!regIcons.length) regHits.push(`${REG_NAME}: 一条 decorative() 图标出口都没匹配到 —— 登记表结构变了,这道闸要跟着改`)
for (const hit of regHits) console.log(`ICONA ${hit}`)
console.log(`${regHits.length} 处图标出口未走 decorative()(登记表 ${regIcons.length} 条出口 / ${stray.length} 处外部 import)`)
/* ── 第 3 条:裸 <button> 收口到自定义表面族 ──────────────────────────────
每条都要写清「为什么不是 antd Button」;新增文件先进这张表,别先写裸按钮。
Controls.tsx(阶段 6 已拆成 Ctlbar.tsx + Fields.tsx)曾在表里:Chip / TagChip 后来全部改由 antd `Tag` /
`Tag.CheckableTag` / `Typography.Link` 承担,裸 <button> 命中数归零,条目已删。 */
const CUSTOM_SURFACES = {
'src/components/ui/Overlay.tsx': 'Scrim:整屏遮罩,点空白关闭;不是按钮,是命中区',
'src/components/media/MediaThumb.tsx': '版本角标 + 删除叉:压在封面上的徽标,尺寸由封面决定',
'src/components/media/AudioPlay.tsx': '走带键:三档直径 28/22/20 由音频行高决定,antd 圆钮最矮 24',
'src/components/media/MediaLightbox.tsx': '灯箱左右翻页:压在媒体上的 40px 玻璃圆钮 + 悬停位移',
'src/components/media/VersionPanel.tsx': '版本封面缩略:图块本身是热区,光标是 zoom-in',
'src/pages/project/Storyboard.tsx': '注释里解释「卡片为什么不是 button」——命中数为 0 时删条目',
}
/** 宿主元素不是字面量 <button> 的文件:Tile 用 <As>,As 可以是 button。
它们同样要带 nex-* 标记,但不参与「字面量命中」对账。 */
const HOST_ELEMENT = {
'src/components/ui/Tile.tsx': 'Tile:整块热区(瓷贴/导航行/账号胶囊),宿主标签由 onClick 决定',
}
const bare = []
const hits = new Map()
const walkButtons = (dir) => {
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, ent.name)
if (ent.isDirectory()) { walkButtons(p); continue }
if (!/\.tsx$/.test(ent.name)) continue
const rel = path.relative(FRONTEND, p)
const lines = fs.readFileSync(p, 'utf8').split('\n')
lines.forEach((line, i) => {
if (/^\s*(\*|\/\/|\/\*|#)/.test(line)) return // 注释里提到 button 不算
if (!/<button(\s|>|$)/.test(line)) return
if (/<\/button>|^\s*return <button/.test(line) || true) {
if (!hits.has(rel)) hits.set(rel, [])
hits.get(rel).push(i + 1)
}
})
}
}
walkButtons(SRC)
const ALLOWED = { ...CUSTOM_SURFACES, ...HOST_ELEMENT }
for (const [rel, rows] of [...hits].sort()) {
if (!ALLOWED[rel]) {
bare.push(`${rel}:${rows.join(',')} — 裸 <button> 不在自定义表面族白名单里,换 <Button>`)
continue
}
const src = fs.readFileSync(path.join(FRONTEND, rel), 'utf8')
if (!/\bnex-[a-z]/.test(src)) {
bare.push(`${rel} — 白名单里的文件一个 nex-* 标记类都没有了,要么补标记要么从白名单删除`)
}
}
/* 白名单要诚实:条目命中数为 0 就说明这一族已经被 antd 取代,打出来提醒删除,
但不算失败——留一天的空条目比漏一颗裸按钮危害小。 */
for (const rel of Object.keys(HOST_ELEMENT)) {
if (CUSTOM_SURFACES[rel]) bare.push(`${rel} — 同一个文件既在白名单又在宿主元素表,删一个`)
}
for (const hit of bare) console.log(`BTN ${hit}`)
const stale = Object.keys(CUSTOM_SURFACES).filter((k) => !hits.has(k))
console.log(`${bare.length} 处未收口的裸 <button>(白名单 ${Object.keys(CUSTOM_SURFACES).length} 个文件 / 实际命中 ${hits.size} 个)`
+ (stale.length ? `\n 可清理的白名单条目:${stale.join(' ')}` : ''))
/* ── 第 4 条:浮层底部动作条 ────────────────────────────────────────────
口径的权威解释在 components/ui/Overlay.tsx 的 DRAWER_ACTIONS 上方;
这里只负责让违反口径的代码无法合入。 */
/** 从 src[open](必须是 '{')找到配对的 '}',返回下标;找不到返回 -1。
字符串/模板字面量整段跳过,JSX 表达式里的 } 用深度计数处理。 */
function braceEnd(src, open) {
let depth = 0
for (let i = open; i < src.length; i++) {
const c = src[i]
if (c === '"' || c === "'" || c === '`') {
const q = c
i++
while (i < src.length) {
if (src[i] === '\\') { i += 2; continue }
if (src[i] === q) break
i++
}
continue
}
if (c === '{') depth++
else if (c === '}' && --depth === 0) return i
}
return -1
}
/** 取 <Button …> 的开标签全文(含 '>')。深度 > 0 时不认 '>',
所以 onClick={() => x} 里的箭头不会被误当成开标签结束。 */
function openTag(src, start) {
let depth = 0
for (let i = start + 1; i < src.length; i++) {
const c = src[i]
if (c === '"' || c === "'" || c === '`') {
const q = c
i++
while (i < src.length) {
if (src[i] === '\\') { i += 2; continue }
if (src[i] === q) break
i++
}
continue
}
if (c === '{') depth++
else if (c === '}') depth--
else if (c === '>' && depth === 0) return src.slice(start, i + 1)
}
return ''
}
/** 动作条的例外:整条只有一个动作、或根本不是动作条(只是把按钮当装饰塞进标题)。
每条都要写理由,别用它绕过口径。 */
const FOOTER_EXEMPT = new Set([])
/**
* 第 4 条量的是**浮层底部**(规范 §10),不是所有叫 actions / footer 的 prop。
*
* 症状:`\b(actions|footer)=\{` 这个名字碰撞把 `PageHead actions`(页头那排开关)
* 和 `Toolbar actions`(勾选后浮出的批量条)也吞了进来,报出
* 「最后一颗必须是主行动」——而页头最后一颗本来就该是「收起概况」这种
* 视图开关,主行动在 `PanelHead right`。批量条的「批量删除」是**未确认的
* 行内删除**(§10:那种才用 `type="text" danger`),也不该被判成权重反了。
* 做法:先定位 prop 属于哪个元素,只有 `<Drawer actions>` / `<Modal footer>`
* (含 kit 内部转发的 `<AntDrawer>` / `<AntModal>`)才是底部动作条。
* 实测全站 25 处:Drawer 6 + Modal 5 + AntModal 1 = 12 处受管,
* PageHead 5 + Toolbar 7 归 §7 的控件栏口径管,不在这里查。
*/
const FOOTER_HOSTS = new Set(['Drawer', 'Modal', 'AntDrawer', 'AntModal'])
/** 找 `at` 这个位置被哪个 JSX 元素包着(取起点最近的那个开标签)。 */
function hostOf(src, tags, at) {
let host = ''
let best = -1
for (const t of tags) if (t.start < at && t.end > at && t.start > best) { host = t.name; best = t.start }
return host
}
const footerViolations = []
const walkFooters = (dir) => {
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, ent.name)
if (ent.isDirectory()) { walkFooters(p); continue }
if (!/\.tsx$/.test(ent.name)) continue
const rel = path.relative(FRONTEND, p)
const src = fs.readFileSync(p, 'utf8')
const openTags = [...src.matchAll(/<(Drawer|Modal|AntDrawer|AntModal)(?=[\s/>])/g)]
.map((t) => ({ name: t[1], start: t.index, end: t.index + openTag(src, t.index).length }))
.filter((t) => t.end > t.start)
for (const m of src.matchAll(/\b(actions|footer)=\{/g)) {
if (!FOOTER_HOSTS.has(hostOf(src, openTags, m.index))) continue
const open = m.index + m[0].length - 1
const close = braceEnd(src, open)
if (close < 0) continue
const block = src.slice(open, close)
const tags = []
for (const b of block.matchAll(/<Button(?=[\s/>])/g)) {
const at = open + b.index
tags.push({ raw: openTag(src, at), line: src.slice(0, at).split('\n').length })
}
if (tags.length < 2) continue // 单动作不违反「取消在前」
if (FOOTER_EXEMPT.has(`${rel}:${m[1]}`)) continue
const at = (n) => `${rel}:${tags[0].line} (${m[1]}) ${n}`
const sizeHit = tags.find((t) => /\bsize="/.test(t.raw))
if (sizeHit) footerViolations.push(at('① 浮层底部一律 md 档,别写 size'))
const primaries = tags.filter((t) => /type="primary"/.test(t.raw))
if (primaries.length > 1) footerViolations.push(at(`② 一条底部最多一颗 type="primary",当前 ${primaries.length} 颗`))
for (const t of tags.filter((x) => /\bdanger\b/.test(x.raw))) {
if (!/type="primary"/.test(t.raw)) {
footerViolations.push(`${rel}:${t.line} (${m[1]}) ③ 破坏性动作用 type="primary" danger`
+ '——裸描边按钮比「取消」还轻,确认权重就反了')
}
}
const last = tags[tags.length - 1]
if (!/type="primary"/.test(last.raw)) {
footerViolations.push(`${rel}:${last.line} (${m[1]}) ④ 最后一颗必须是主行动 type="primary"`
+ '(DOM 顺序 = 视觉顺序:辅助 → 取消 → 主行动)')
}
}
}
}
walkFooters(SRC)
for (const hit of footerViolations) console.log(`FOOT ${hit}`)
console.log(`${footerViolations.length} 处不符合浮层底部动作口径(只查 Drawer actions / Modal footer:PageHead · Toolbar 的 actions 属 §7 控件栏)`)
/* ── 第 5 条:`import 'antd'` 只许出现在尺子、外壳与 kit 里(R8)────────────
页面一旦直接 import 组件库,主题与档位就再也收不口:换 antd 大版本、调 token、
甚至只是想让「按钮三档高度」跟着系统走,都得把 20 多个页面重扫一遍。
白名单只有三处:theme/(尺子本体)· app/(外壳没有第二份实现,直接铺 Layout/Menu)·
components/{ui,forms}(kit 唯一封装层)。
以前这条只写在文档里,没人拦——补成闸。
⚠ 2026-11 第十三轮删掉了第四处 `stores/notice.ts`:它原先是 antd `message` 的唯一出口,
吐司改成自绘队列(stores/notice.ts + components/ui/Toast.tsx)以后它不再 import antd,
留着这条等于给「以后谁想在 store 里 import 组件库」开后门。 */
const ANTD_OK = (rel) => /^(theme|app)\//.test(rel) || /^components\/(ui|forms)\//.test(rel)
const antdStray = []
const walkAntd = (dir) => {
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, ent.name)
if (ent.isDirectory()) { walkAntd(p); continue }
if (!/\.(tsx|ts)$/.test(ent.name)) continue
const rel = path.relative(FRONTEND, p).replace(/^src\//, '')
if (ANTD_OK(rel)) continue
fs.readFileSync(p, 'utf8').split('\n').forEach((line, i) => {
if (/from 'antd'/.test(line)) antdStray.push(`${rel}:${i + 1}: ${line.trim()}`)
})
}
}
walkAntd(SRC)
for (const hit of antdStray) console.log(`ANTD ${hit}`)
console.log(`${antdStray.length} 处越界的 import 'antd'(R8:只许 theme/ · app/ · components/{ui,forms})`)
/* ── 第 6 条:反馈四级表面各有唯一实现(R19)────────────────────────────
症状(2026-11 第十三轮 · 用户原话「整体修改系统中的所以提示窗、完成后的反馈tips等。
不要使用默认组件」):同一句反馈有过五种长相——浏览器原生的 `window.confirm`
灰条(字体、按钮、层级全是操作系统的)、antd 顶部那行 `message.success` 小灰字、
`Modal.confirm` 的默认问话框、`notification` 的右上大卡、页面自拼的
`border + warning-bg`。读者分不清刚才那句话是不是系统说的,破坏性确认
还经常被当成浏览器自己弹的广告直接关掉。
做法:四级表面各留唯一出口——行内 `ErrorText`/`LineHint`(贴在控件旁)
→ `Notice` 提示条(贴在内容块上方)→ `notify*`(全局吐司,右下角)
→ `confirmAction`(破坏性操作确认框)。其余写法一律判违规。
为什么用正则不用 AST:这些都是**函数名 / 组件名**层面的口径,
正则命中的就是要禁的那几个名字,AST 反而要多写一层解析;
漏报的代价是全站又长出第五套皮肤,误报的代价只是往白名单加一行。
白名单是实现本体:吐司 / 确认框 / 提示条三个组件 + 两个 store
(提示条 `Notice` 自阶段 6 起住在 `components/ui/State.tsx`,白名单同步跟上)。
2026-11-07(阶段 5):正则原本只匹配字面 `window.confirm(`,浏览器里裸调用
`confirm(...)` 是**同一个**原生对话框,Library.tsx 因此漏过 5 处。
放宽后的口径 = 「前面不是 . / $ / 词字符,可带 window. 前缀」:
/(?<![\w.$])(?:window\.)?(?:confirm|alert)\s*\(/
十一例自查(改的时候别再退回旧写法):
命中 5 —— window.confirm( / confirm( / !confirm(` / window.alert( / alert(
放行 6 —— confirmAction( / Modal.confirm( / lib.confirm( / notconfirm( / myalert( / x.window.confirm(
(`(?<![\w.$])` 放在**可选前缀之前**:写成 `(?:\bwindow\.)?(?<![\w.$])` 会让
前缀吃掉 `window.` 之后回头看那个点,把 window.confirm( 整个漏掉——阶段 5 先踩过一次。) */
const FB_IMPL = /^components\/ui\/(Toast|Confirm|State|Panel|Button|tone)\.tsx$|^stores\/(notice|confirm)\.ts$/
const FB_RULES = [
[/(?<![\w.$])(?:window\.)?(?:confirm|alert)\s*\(/, '浏览器原生 confirm / alert(含省略 window. 的裸调用)'],
[/\bModal\.confirm\s*\(/, 'antd Modal.confirm 默认问话框'],
[/\bmessage\.(success|error|warning|info|loading|open|destroy)\s*\(/, 'antd message 顶部小灰字'],
[/\bnotification\.(open|success|error|warning|info)\s*\(/, 'antd notification 右上大卡'],
[/<Alert(?=[\s/>])/, '裸 antd Alert(语义提示只有一个名字:Notice)']
]
const fbHits = []
const walkFb = (dir) => {
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, ent.name)
if (ent.isDirectory()) { walkFb(p); continue }
if (!/\.(tsx|ts)$/.test(ent.name)) continue
const rel = path.relative(FRONTEND, p).replace(/^src\//, '')
if (FB_IMPL.test(rel)) continue
fs.readFileSync(p, 'utf8').split('\n').forEach((line, i) => {
const code = line.replace(/\/\/.*$/, '')
for (const [re, why] of FB_RULES) {
if (re.test(code)) fbHits.push(`${rel}:${i + 1}: ${why} → ${code.trim().slice(0, 72)}`)
}
})
}
}
walkFb(SRC)
for (const hit of fbHits) console.log(`FEED ${hit}`)
console.log(`${fbHits.length} 处绕开反馈四级表面(R19:ErrorText/LineHint → Notice → notify* → confirmAction)`)
/* ── 第 7 条:门牌与卡头标题不挂前置图形(2026-11 第十四轮)───────────────
症状(用户原话「不要图标」,附项目总控台那颗品牌 N 的门牌截图):页头标题左边
那块主色方块(反查菜单表拿到的图形)说的是左栏高亮项已经说过的一句话,
同屏还有统计卡色块、卡头品牌 N 三颗同形状方块互相抢焦点;
它还把标题整体右推 42px,门牌与正文的左缘因此对不上。
做法:`PageHead` 的 icon / 反查机制、`.nex-pagehead-mark` 整层删除;
`<Mark>` 只剩登录页那颗品牌方牌。闸门钉住三件事:
① `<PageHead>` 不许再写 `icon=`;② 谁都不许再写 `nex-pagehead-mark` 类名;
③ `<Mark>` 只许出现在 pages/Login.tsx——一旦第二处开始用它当「标题装饰」,
这一轮删掉的东西就会从那个文件长回来。 */
const MARK_OK = new Set(['pages/Login.tsx'])
const headHits = []
const walkHead = (dir) => {
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, ent.name)
if (ent.isDirectory()) { walkHead(p); continue }
if (!/\.tsx$/.test(ent.name)) continue
const rel = path.relative(FRONTEND, p).replace(/^src\//, '')
const src = fs.readFileSync(p, 'utf8')
src.split('\n').forEach((line, i) => {
if (/nex-pagehead-mark/.test(line) && !/^\s*[*/]/.test(line)) {
headHits.push(`${rel}:${i + 1}: 门牌前置图形的类名又回来了(第十四轮已删这一层)`)
}
if (/<Mark(?=[\s>])/.test(line) && !MARK_OK.has(rel) && !/^\s*[*/]/.test(line)) {
headHits.push(`${rel}:${i + 1}: <Mark> 只许登录页当品牌方牌用,标题前不再挂方块图形`)
}
})
for (const m of src.matchAll(/<PageHead(?=[\s/>])/g)) {
// 只看 PageHead **自己那一层**的 prop:actions={<Button icon={…}/>} 里的 icon=
// 属于里面那颗按钮(R15 要求按钮带图标),不算门牌的图形——所以要跟着花括号深度走。
const tag = openTag(src, m.index)
let depth = 0
let own = ''
for (const ch of tag) {
if (ch === '{') depth++
else if (ch === '}') depth--
else if (depth === 0) own += ch
}
if (/\bicon=/.test(own)) {
headHits.push(`${rel}:${src.slice(0, m.index).split('\n').length}: <PageHead icon=> 已废弃(门牌不挂图形)`)
}
}
}
}
walkHead(SRC)
for (const hit of headHits) console.log(`HEAD ${hit}`)
console.log(`${headHits.length} 处标题前置图形(第十四轮:门牌 = 一级标题 + 右端主操作,没有图标)`)
/* ── 第 8 条:标签的 className 只许写排布类,不许写皮肤类(2026-11-07 · D16 修复)──
症状:kit 的 `Tag` 形参收了 className 却没并进 cn(),页面写 `<Tag className="ml-2">`
从 2026-11 起一直是空转(缺陷 D16,`docs/NEX-对照与例外.md` §6)。修好之后
新问题换了形状:**能不能点亮取决于属性有没有被 `.nex-tag` 独占**——
`index.css:55` 的 `@import "./app.css"` 不带 layer,未层声明高于任何 @layer,
所以 display / background / color / border-radius / padding-inline / font-size /
line-height / min-height / gap / max-width / white-space / overflow /
margin-inline-end 这十三族写上去照样是空转(明暗两档逐属性实测,
`docs/UI规范.md` §1.1.1 那张表)。
做法:把这十三族钉成禁写词。命中就是「页面以为自己在改皮肤,其实什么都没发生」,
该改 tone(accent / mono 等登记过的色调)或者回到壳里改令牌,不是再套一层 !important。
为什么只扫 kit 标签:`components/ui/Ctlbar.tsx` 里的 `Tag` 是 antd 本尊(它自己写
`nex-tag-chip` 皮肤类),不吃这条规矩;只有从 components/ui 取 Tag/Status 的文件
才是这次修的那个壳。 */
const SKIN_TOKEN = [
[/^hidden$/, 'display(壳是 inline-flex)'],
[/^(?:max|min)-[\w-]+:hidden$/, '响应式 display(同上,要藏在 wrapper 上)'],
[/^bg-/, 'background(§2.1:标签只有一档中性底)'],
[/^text-/, 'color / font-size(皮肤与字号都由壳定)'],
[/^rounded/, 'border-radius'],
[/^(?:p|px|pe)-/, 'padding-inline(壳用 --tag-px 两档下发)'],
[/^leading-/, 'line-height'],
[/^min-h-/, 'min-height(壳用 --tag-h 两档下发)'],
[/^gap-/, 'gap(壳用 --tag-gap)'],
[/^max-w-/, 'max-width(壳定 100%,防长标签捅出容器)'],
[/^whitespace-/, 'white-space(壳 nowrap)'],
[/^overflow-/, 'overflow(壳 hidden 配合内部 ellipsis)'],
[/^(?:mr|me)-/, 'margin-inline-end(壳归零,成排间距归 TagGroup 管)']
]
const tagSkinHits = []
const walkTagSkin = (dir) => {
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, ent.name)
if (ent.isDirectory()) { walkTagSkin(p); continue }
if (!/\.tsx$/.test(ent.name)) continue
const rel = path.relative(FRONTEND, p).replace(/^src\//, '')
const raw = fs.readFileSync(p, 'utf8')
// 只认真正用 kit 壳的文件:import 行里从 components/ui 取了 Tag 或 Status
const usesKit = raw.split('\n').some((l) =>
/^import\s/.test(l) && /from '[^']*components\/ui/.test(l) && /\b(Tag|Status)\b/.test(l))
if (!usesKit) continue
const src = raw.replace(/\/\*[\s\S]*?\*\//g, '') // 注释里写 <Tag className="bg-…"> 是解释,不是违规
for (const m of src.matchAll(/<(Tag|Status)(?=[\s/>])/g)) {
const tag = openTag(src, m.index)
let depth = 0, own = ''
for (const ch of tag) {
if (ch === '{') depth++
else if (ch === '}') depth--
else if (depth === 0) own += ch
}
const attr = own.match(/\bclassName=\{?"([^"]*)"|\bclassName=\{(.*?)\}\}/s)
if (!attr) continue
const bag = (attr[1] || attr[2] || '')
.replace(/\b(?:cn|clsx)\(/g, ' ')
.match(/['"`]([^'"`]*)['"`]/g)
const tokens = (bag || []).join(' ').replace(/['"`]/g, ' ').split(/\s+/).filter(Boolean)
const line = src.slice(0, m.index).split('\n').length
for (const t of tokens) {
const bare = t.replace(/^[!]/, '').replace(/^\w+:/, '') // 变体前缀与 important 后缀都改变「写的是哪个属性」
for (const [re, why] of SKIN_TOKEN) {
if (re.test(bare) || re.test(t)) {
tagSkinHits.push(`${rel}:${line}: <${m[1]} className 写了 ${t}> —— ${why},`.replace(/\s+$/, '') +
`未层壳压不住(UI规范 §1.1.1);要显眼用 tone,要隐藏套 span`)
}
}
}
}
}
}
walkTagSkin(SRC)
for (const hit of tagSkinHits) console.log(`TAGSKIN ${hit}`)
console.log(`${tagSkinHits.length} 处标签 className 写皮肤类(第 8 闸:display/底/色/圆角/内距/字号…由 .nex-tag 独占,写上去是空转)`)
/* ── 第 9 条:断点只许用「登记过的名字」(2026-11-07 · N16 断点治理)────────────
症状:阶段 7 把页面里 5 把裸 `max-[1240px]` 改名成 `--breakpoint-*` 命名变体之后,
「登记」这件事只剩两份人写的表(`styles/index.css` 的 @theme、`UI规范.md` §4
的登记表)和一句 `grep -rn "max-\[" frontend/src`。没有任何机器闸:
下一轮谁再写一个 `max-[900px]:flex`,编译得过、像素也对,只有人眼能发现;
反过来往 @theme 加一档却忘了写进 §4、或者忘了同步 `visualcheck.py` 的 `BP`,
`wantDisplay` 会对这一档**静默返回 null**——断言悄悄不跑了,比报错更糟。
做法:尺子的唯一真相是 `@theme` 里的 `--breakpoint-*`,其余四处(页面用词 / UI规范 §4
登记表 / 探针 BP 表 / 尺子自己的使用面)全部由这条闸向它对账:
① 页面与样式里不许再出现裸任意断点 `max-[…]` / `min-[…]`;
② 用到的变体名必须在 @theme 里存在(写错名字 = 这一档根本不会生成规则);
③ 登记断点(非主阶梯那几把)必须**只有一个使用者**、必须被 §4 表收录、
且不能是「登记了却没人用」的死尺子(UI规范 §4 三条口径逐条机器化);
④ 每一档都要出现在 `visualcheck.py` 的 `BP` 与 `BPORDER` 里,且 BPORDER
必须与「按 px 从大到小」一致(顺序错了 wantDisplay 会挑错赢家);
⑤ CSS 侧 `@media (max-width: Npx)` 的 N 必须是登记过的值——闸门同样管得住 .css,
否则页面归了名、样式表里再开一批私档就白干。
为什么不在这里禁「主阶梯档位用得对不对」:那是 R9 的语义判断(该不该在这一档换排布),
机器量不出来;这条闸只管「名字存不存在、有没有登记、有没有人用、探针认不认」。 */
const THEME_FILE = path.join(FRONTEND, 'src/styles/index.css')
const SPEC_DOC = path.resolve(HERE, '../../docs/UI规范.md')
const VISUAL_PROBE = path.join(HERE, 'visualcheck.py')
/** 主阶梯 = antd Grid 的档位(`@theme` 与 antd 同源);其余一律算「登记断点」 */
const MAIN_LADDER = new Set(['sm', 'md', 'lg', 'xl', '2xl'])
/** `max-width:` / `min-height:` 这类是 CSS 属性,不是断点变体(正则不吃上下文,只能点名放过) */
const NOT_A_BP = new Set(['width', 'height', 'inline', 'block', 'inline-size', 'block-size',
'w', 'h', 'min', 'max', '-content', 'vw', 'vh', 'unit'])
const themeCss = fs.readFileSync(THEME_FILE, 'utf8')
const bpTable = new Map() // 名字 → px:全站断点的唯一真相
for (const m of themeCss.matchAll(/--breakpoint-([a-z0-9-]+)\s*:\s*([0-9.]+)px/g)) {
bpTable.set(m[1], Number(m[2]))
}
const registered = [...bpTable.keys()].filter((n) => !MAIN_LADDER.has(n))
const bpValues = new Set([...bpTable.values()].map(String))
const specDoc = fs.existsSync(SPEC_DOC) ? fs.readFileSync(SPEC_DOC, 'utf8') : ''
const visualSrc = fs.existsSync(VISUAL_PROBE) ? fs.readFileSync(VISUAL_PROBE, 'utf8') : ''
const probeOrder = ((visualSrc.match(/const BPORDER = \[([^\]]*)\]/) || [, ''])[1]
.match(/'[^']*'|"[^"]*"/g) || []).map((x) => x.slice(1, -1))
const probeBP = new Map()
for (const m of ((visualSrc.match(/const BP = \{([^}]*)\}/s) || [, ''])[1]
.matchAll(/'([a-z0-9-]+)'\s*:\s*([0-9.]+)|(?<![^\s,{])"([a-z0-9-]+)"\s*:\s*([0-9.]+)|([a-z][a-z0-9-]*)\s*:\s*([0-9.]+)/g))) {
probeBP.set(m[1] || m[3] || m[5], Number(m[2] || m[4] || m[6]))
}
const bpHits = []
const bpUsers = new Map(registered.map((n) => [n, new Map()])) // 名字 → 文件 → 处数
const walkBP = (dir) => {
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, ent.name)
if (ent.isDirectory()) { walkBP(p); continue }
if (!/\.(tsx|ts|css)$/.test(ent.name)) continue
const rel = path.relative(FRONTEND, p)
let inBlock = false
fs.readFileSync(p, 'utf8').split('\n').forEach((raw, i) => {
const [line, block] = stripComments(raw, () => inBlock)
inBlock = block
if (!line.trim()) return
const at = `${rel}:${i + 1}`
/* ① 裸任意断点 */
for (const m of line.matchAll(/\b(?:max|min)-\[/g)) {
bpHits.push(`${at}: 写了裸任意断点 ${line.slice(m.index).split(/[\s'"`)/]+/)[0]}`
+ ` —— 主阶梯放不下就按 UI规范 §4 登记成 --breakpoint-*,别在页面里造私档`)
}
/* ② 变体名必须在 @theme 里 */
for (const m of line.matchAll(/\b(?:max|min)-([a-z0-9][a-z0-9-]*):/g)) {
const name = m[1]
if (NOT_A_BP.has(name)) continue
if (!bpTable.has(name)) {
bpHits.push(`${at}: 用了没登记的断点名 ${m[0]}`
+ ` —— styles/index.css 的 --breakpoint-${name} 不存在,这一档压根不生成规则`)
continue
}
/* ③ 登记断点的使用者 */
if (!MAIN_LADDER.has(name)) {
const per = bpUsers.get(name)
per.set(rel, (per.get(rel) || 0) + 1)
}
}
/* ⑤ CSS 侧 @media 的像素值 */
if (/\.css$/.test(ent.name)) {
for (const m of line.matchAll(/@media[^{]*\((?:max|min)-width:\s*([0-9.]+)px\)/g)) {
if (!bpValues.has(m[1])) {
bpHits.push(`${at}: @media 用了没登记的值 ${m[1]}px`
+ ` —— 样式表里的私档同样算私档(UI规范 §4)`)
}
}
}
})
}
}
walkBP(SRC)
/* ③ 三条登记口径:有人用、只有一个使用者、被 §4 表收录 */
for (const [name, per] of bpUsers) {
const px = bpTable.get(name)
if (!per.size) {
bpHits.push(`styles/index.css: 断点 ${name}(${px}px) 登记了却 0 个使用者`
+ ` —— 删档要连着它唯一的使用者一起删(§4 口径 ③)`)
}
if (per.size > 1) {
bpHits.push(`断点 ${name}(${px}px) 有 ${per.size} 个使用者:`
+ [...per.keys()].join(' / ')
+ ` —— 一把尺子只服务一个表面(§4 口径 ①),要共用先把它升级成主阶梯档位`)
}
if (specDoc && !new RegExp('^\\|\\s*`' + name + '`\\s*\\|', 'm').test(specDoc)) {
bpHits.push(`docs/UI规范.md §4: 登记表里没有 ${name}(${px}px)`
+ ` —— @theme 加一档必须同时留下「相邻档位为什么不行」的实测行`)
}
}
/* ④ 探针的断点表必须与 @theme 同名同值同序 */
for (const [name, px] of bpTable) {
if (!probeBP.has(name)) bpHits.push(`scripts/ui/visualcheck.py: BP 表里没有 ${name}`
+ ` —— wantDisplay 会对这一档静默返回 null,断言等于没跑`)
if (visualSrc && !probeOrder.includes(name)) bpHits.push(`scripts/ui/visualcheck.py: BPORDER 里没有 ${name}`
+ ` —— 少了名字 max-*/min-* 的赢家会算错`)
else if (probeBP.has(name) && probeBP.get(name) !== px) {
bpHits.push(`scripts/ui/visualcheck.py: BP.${name}=${probeBP.get(name)} 与 styles/index.css 的 ${px} 不一致`
+ ` —— 探针按旧尺子量,页面按新尺子排`)
}
}
if (probeOrder.length) {
const sorted = [...bpTable.keys()].sort((a, b) => bpTable.get(b) - bpTable.get(a))
if (probeOrder.join(',') !== sorted.join(',')) {
bpHits.push(`scripts/ui/visualcheck.py: BPORDER 顺序应为 ${sorted.join(', ')}`
+ `(按 px 从大到小),现在是 ${probeOrder.join(', ')}`)
}
}
for (const hit of bpHits) console.log(`BP ${hit}`)
console.log(`${bpHits.length} 处断点越界(第 9 闸:${bpTable.size} 档在册 / ${registered.length} 把登记尺子`
+ ` / 裸 max-[…] 与未登记名与文档-探针失同步)`)
process.exit(dead.length + stray.length + regHits.length + bare.length + footerViolations.length + antdStray.length
+ fbHits.length + headHits.length + tagSkinHits.length + bpHits.length ? 1 : 0)