268 lines
7.9 KiB
JavaScript
268 lines
7.9 KiB
JavaScript
#!/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();
|