Files
ai-platform/scripts/check-module-styles.mjs
2026-10-18 23:02:15 +08:00

268 lines
7.9 KiB
JavaScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env node
/**
* 模块样式命名空间检查(门禁脚本)
*
* 平台规则:src/modules 下所有 .css 中选择器必须挂在模块根容器类(命名空间)下,
* 禁止全局作用选择器(裸标签 / :root / 通配符 / 裸伪类 / 裸属性选择器等)跨模块污染。
*
* 实现:状态机逐字符解析(模块内存在数 MB 的 minified CSS,含大量 data URI
* 字符串与花括号,不能依赖简单正则)。零依赖,Node >= 18。
*/
import { readdirSync, readFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const MODULES_DIR = path.join(ROOT, 'src', 'modules');
const MAX_LEN = 80;
/* ---------------------------------- 文件收集 ---------------------------------- */
function collectCssFiles(dir) {
const out = [];
let entries;
try {
entries = readdirSync(dir, { withFileTypes: true });
} catch {
return out;
}
for (const entry of entries) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) {
out.push(...collectCssFiles(full));
} else if (entry.isFile() && entry.name.toLowerCase().endsWith('.css')) {
out.push(full);
}
}
return out;
}
/* --------------------------------- 选择器判定 --------------------------------- */
/**
* 判定单个选择器(已 trim)是否为全局作用选择器。
* 返回 null 表示合法(挂在类/ID 命名空间下),否则返回原因字符串。
*/
function classifySelector(sel) {
if (!sel || sel.startsWith('@')) return null;
// 裸伪类/伪元素::root、:focus-visible、::-webkit-scrollbar 等,等价于通配符
if (sel.startsWith(':')) {
if (/^:root(?![a-zA-Z0-9_-])/.test(sel)) return '裸 :root 选择器(全局作用)';
return '裸伪类/伪元素(等价于通配符,全局作用)';
}
if (sel.startsWith('*')) return '通配符 *(全局作用)';
if (sel.startsWith('[')) return '裸属性选择器(全局作用)';
// 裸标签:首 token 匹配 /^[a-zA-Z][a-zA-Z0-9-]*$/ 且不是 CSS 函数(后面紧跟 "(")
const m = sel.match(/^[a-zA-Z][a-zA-Z0-9-]*/);
if (m) {
const next = sel.charAt(m[0].length);
if (next !== '(') {
return `裸标签选择器「${m[0]}」(未挂在模块根容器下)`;
}
}
return null;
}
/**
* 按顶层逗号拆分选择器列表:括号 ( ) 与属性选择器 [ ] 内的逗号不拆分,
* 引号字符串内的逗号不拆分。
*/
function splitTopLevelCommas(s) {
const parts = [];
let cur = '';
let paren = 0;
let bracket = 0;
let quote = null;
let escaped = false;
for (const ch of s) {
if (quote) {
cur += ch;
if (escaped) escaped = false;
else if (ch === '\\') escaped = true;
else if (ch === quote) quote = null;
continue;
}
if (ch === '"' || ch === "'") {
quote = ch;
cur += ch;
continue;
}
if (ch === '(') paren++;
else if (ch === ')') paren = Math.max(0, paren - 1);
else if (ch === '[') bracket++;
else if (ch === ']') bracket = Math.max(0, bracket - 1);
if (ch === ',' && paren === 0 && bracket === 0) {
parts.push(cur);
cur = '';
continue;
}
cur += ch;
}
parts.push(cur);
return parts;
}
function truncate(s) {
return s.length > MAX_LEN ? `${s.slice(0, MAX_LEN - 3)}...` : s;
}
/* --------------------------------- 状态机解析 --------------------------------- */
/**
* 逐字符解析 CSS 文本。
* - 跳过块注释与字符串内容(data URI 中的 { } ; ( ) 不影响结构);
* - 跟踪大括号深度与栈帧:'media'(@media/@supports 内继续扫描)、
* 'rule'(普通规则块,声明不扫描)、'skip'(@keyframes/@font-face 等块内不扫描);
* - prelude("{" 之前的文本)在扫描态下累积,用于选择器判定与 @import 检查。
*
* onRule(prelude, line) —— 每条普通规则回调;
* onImport(prelude, line) —— 每条顶层(或 @media 内)@import 回调。
*/
function parseCss(source, onRule, onImport) {
const stack = [];
let prelude = '';
let preludeLine = -1;
let line = 1;
let inComment = false;
let quote = null;
let escaped = false;
const scanMode = () => stack.length === 0 || stack[stack.length - 1] === 'media';
const resetPrelude = () => {
prelude = '';
preludeLine = -1;
};
for (let i = 0; i < source.length; i++) {
const ch = source[i];
if (ch === '\n') line++;
if (inComment) {
if (ch === '*' && source[i + 1] === '/') {
inComment = false;
i++;
}
continue;
}
if (quote) {
// 字符串内容原样跳过(不解析其中的 { } ; 等);
// 为支持 @import 目标检查,扫描态下仍原样记录进 prelude。
if (escaped) {
escaped = false;
} else if (ch === '\\') {
escaped = true;
} else if (ch === quote) {
quote = null;
}
if (scanMode()) prelude += ch;
continue;
}
if (ch === '"' || ch === "'") {
quote = ch;
if (scanMode()) {
if (preludeLine === -1 && /\S/.test(ch)) preludeLine = line;
prelude += ch;
}
continue;
}
if (ch === '/' && source[i + 1] === '*') {
inComment = true;
i++;
continue;
}
if (ch === '{') {
const trimmed = prelude.trim();
let frame;
if (scanMode() && trimmed.startsWith('@')) {
const m = trimmed.match(/^@([a-zA-Z0-9-]+)/);
const name = m ? m[1].toLowerCase() : '';
// @media / @supports 递归继续扫描内部规则;其余 at-rule 跳过块内选择器
frame = name === 'media' || name === 'supports' ? 'media' : 'skip';
} else if (scanMode()) {
if (trimmed) onRule(trimmed, preludeLine === -1 ? line : preludeLine);
frame = 'rule';
} else {
frame = 'skip';
}
stack.push(frame);
resetPrelude();
continue;
}
if (ch === '}') {
if (stack.length) stack.pop();
resetPrelude();
continue;
}
if (ch === ';') {
if (scanMode()) {
const trimmed = prelude.trim();
if (/^@import\b/.test(trimmed)) {
onImport(trimmed, preludeLine === -1 ? line : preludeLine);
}
}
resetPrelude();
continue;
}
if (scanMode()) {
if (preludeLine === -1 && /\S/.test(ch)) preludeLine = line;
prelude += ch;
}
}
}
/* ------------------------------------ 主流程 ----------------------------------- */
function main() {
const files = collectCssFiles(MODULES_DIR).sort();
const violations = [];
const addViolation = (rel, line, selector, reason) => {
violations.push(`[违规] ${rel}:${line} ${truncate(selector)} ${reason}`);
};
for (const file of files) {
const rel = path.relative(ROOT, file).split(path.sep).join('/');
const source = readFileSync(file, 'utf8');
parseCss(
source,
(prelude, line) => {
for (const part of splitTopLevelCommas(prelude)) {
const sel = part.trim();
const reason = classifySelector(sel);
if (reason) addViolation(rel, line, sel, reason);
}
},
(prelude, line) => {
if (/(^|[^a-z0-9])(reset|normalize)/i.test(prelude)) {
addViolation(rel, line, prelude, '@import 引入 reset/normalize 样式(全局污染)');
}
},
);
}
if (violations.length > 0) {
for (const v of violations) console.log(v);
const badFiles = new Set(violations.map((v) => v.split(' ')[0])).size;
console.log(
`[汇总] 模块样式命名空间检查失败:共 ${violations.length} 条违规,涉及 ${badFiles} 个文件(共扫描 ${files.length} 个文件)`,
);
process.exit(1);
}
console.log(`✓ 模块样式检查通过(扫描 ${files.length} 个文件)`);
process.exit(0);
}
main();