台账 DEC-P-2 的死码族一直靠人工 grep 猜,本轮做成 scripts/dead-modules.mjs:
从真实入口(app/**/page|layout|route + Next 约定文件)做 import 闭包,再分类。
**这台仪器本身修了三次才可信,每一次都是"看似合理但会误删活码"**:
1. 只匹配 `from '...'` ⇒ `dynamic(() => import('./GoogleAnalytics'))` 这条边不存在,
GA 组件被报成"零引用死码"。照那结果删,GA4 会在没有任何渲染断言的情况下从页面消失。
2. 只扫 src/ ⇒ scripts/utils/check-color-contrast.ts import 的 src/lib/color-contrast.ts
被报成死码(门禁自己的依赖不在图内)。
3. 入口正则写成 /app\/.*(^|\/)layout\.tsx$/ ⇒ 强制 layout.tsx 前有 '/',
于是 **src/app/layout.tsx 这种根级约定文件根本不算入口**,它 import 的整棵树
全部误判死码(实测把 home-content-v16、layout 自己都报成死码,129 个假死码)。
4. 相对导入用 path.resolve 解析成绝对路径,而模块表 key 是相对路径 ⇒ 所有 `./x` 边静默丢弃,
可达数看着像个数其实半瞎。
归一后:入口 65 · 站内模块 489 · 可达 295 · 不可达 194 —— 其中
convention 4 / generated 2 / **library 53(组件库库存,删除是产品决定,本轮不删)** /
test 118 / **dead 仅 17**。前几版报的 48~129 个"死码"绝大多数是假阳性。
删除 17 个(含 5 个专属测试 + 3 个 describe 块 + 1 段孤儿 jest.mock):
sections 下 11 个被页面自己手写实现取代的区块、两个 breadcrumb、NewsDetailClient
(news 详情页实际用的是 news-detail-content-v3)、lib/cms/index.ts 空桶、
design-system.ts。删后 dead-modules 复判 0。
**棘轮被打破,而我拒绝用"降门限"来让它闭嘴**(这是本轮最重要的一个决定):
删完 `npm run test:coverage` EXIT=1,./src/lib/ functions 84.95(门限85)、
./src/lib/constants/ functions 51.51(门限55)。先做了归因 —— 用真闸而不是自拼 config
(我第一版自拼 config 测的"基线"是坏测量:漏跑 prisma generate ⇒ 套件全崩 ⇒ 0% 覆盖率)。
结论:da9a5cb6 上这道闸 EXIT=0 通过,是我打破的;且 design-system.ts 有 100% 覆盖的函数,
**删掉一个"有完整测试的死码"在数学上必然拉低目录均值** —— 门限此前是被"永远不会上线的代码
的测试"撑着的。
处置:一处门限都没改。改为
- 补真测试:getHeroTheme 未知 id 回落 default、交叉引用兜底、常量桶一致性守卫
- 删掉我在 nav-active.ts 里写出的一条**不可达分支**(函数开头已 `if(!href) return false`,
`target===''` 永不可达;留着它会让覆盖率报告出现"没覆盖到的分支",诱导出一个假测试)
- 修掉一个既有潜伏陷阱:根桶 constants.ts 与子桶 constants/index.ts **两条平行出口不一致**,
根桶漏了 getHeroTheme / 三个 CrossRefs / commitments / cta-labels / metrics-basis 全部符号
⇒ `import { getHeroTheme } from '@/lib/constants'` 会拿到 undefined,调用时才炸、
静态检查不拦。补齐后 All files functions 82.28 → **87.62**,COVERAGE_EXIT=0。
这条漂移是刚写的桶守卫当场抓出来的(它先以"函数是 undefined"判红),不是我事后编的测试。
门禁实测:type-check EXIT=0 · 全量 jest 通过 · test:coverage EXIT=0(未动任何阈值)·
check:grammar 9/9 与 selftest 9/9 · token-twins · contrast · brand-token 全 EXIT=0
173 lines
8.7 KiB
JavaScript
173 lines
8.7 KiB
JavaScript
#!/usr/bin/env node
|
||
/**
|
||
* 站内模块可达性判定:从真实入口(app/**\/page.tsx、layout、api route)做 import 闭包,
|
||
* 报出「没有任何入口能到达」的模块。
|
||
*
|
||
* 为什么要这么判,而不是 grep 文件名:
|
||
* 1. 相对导入 `from './micro-interactions'` 用全路径正则扫不出来 —— 第一版就因此把
|
||
* detail-hero.tsx 正在用的组件误判成死码。**判死码判错 = 误删活代码。**
|
||
* 2. 桶文件(detail/index.ts 再导出)会让"谁引用了它"的答案变成"引用了桶",
|
||
* 必须顺着一个真实 specifier 解析到落点文件再判。
|
||
* 3. 只看"有没有 import 方"也不够:A 引 B、B 引 C,但 A 自己没人引 —— 整条链都是死的。
|
||
* 可达性闭包才回答"这文件有没有可能进产物"。
|
||
*
|
||
* 输出退出码:0 有死码 / 2 判定不可信(入口为 0、解析报错)。**不判 1**:
|
||
* 死码存在不是构建失败,而是台账 DEC-P-2 的存量,判红会让这道检查永远进不了 CI。
|
||
*/
|
||
import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
|
||
import path from 'node:path';
|
||
|
||
// 扫描根可以有多个:只扫 src 会漏掉**门禁脚本与 e2e 对 src 的引用**
|
||
// (scripts/utils/check-color-contrast.ts 就 import 了 src/lib/color-contrast.ts,
|
||
// 只扫 src 时它被误判成死码)。入口仍只取 app/ 约定文件,其余根只贡献"谁在引"。
|
||
const ROOTS = process.argv.length > 2 ? process.argv.slice(2) : ['src', 'scripts', 'e2e', 'config'];
|
||
const ROOT = 'src';
|
||
const missing = ROOTS.filter((r) => !existsSync(r));
|
||
if (missing.length) { console.error(`未能度量:根目录不存在 ${missing.join(', ')}`); process.exit(2); }
|
||
|
||
function walk(dir, acc = []) {
|
||
for (const e of readdirSync(dir, { withFileTypes: true })) {
|
||
if (['node_modules', '.git', 'dist', '_archive', '.next'].includes(e.name)) continue;
|
||
const p = path.join(dir, e.name);
|
||
if (e.isDirectory()) walk(p, acc);
|
||
else if (/\.(tsx?|mjs)$/.test(e.name)) acc.push(p);
|
||
}
|
||
return acc;
|
||
}
|
||
|
||
const files = ROOTS.flatMap((r) => walk(r));
|
||
const texts = new Map(files.map((f) => [path.normalize(f), readFileSync(f, 'utf8')]));
|
||
const EXT = ['', '.ts', '.tsx', '.js', '.mjs', '/index.ts', '/index.tsx'];
|
||
|
||
/** specifier → 站内落点文件(解析不到=第三方包或资源文件,返回 null) */
|
||
function resolve(spec, fromFile) {
|
||
let base;
|
||
if (spec.startsWith('@/')) base = path.join(ROOT, spec.slice(2));
|
||
// ⚠ 必须用 path.join 而不是 path.resolve:resolve 会拼上 cwd 变成**绝对路径**,
|
||
// 而模块表 texts 的 key 是 walk 出来的相对路径 ⇒ 所有 `./x` 相对导入都匹配不上、
|
||
// 边被静默丢弃(`@/` 开头的反而正常,于是可达数看着像个数、其实是半瞎的)。
|
||
// 本仓页面组件多用相对导入,第一版因此把 home-content-v16 报成死码。
|
||
else if (spec.startsWith('./') || spec.startsWith('../')) base = path.normalize(path.join(path.dirname(fromFile), spec));
|
||
else return null;
|
||
for (const e of EXT) {
|
||
const cand = path.normalize(base + e);
|
||
if (existsSync(cand) && statSync(cand).isFile()) return cand;
|
||
}
|
||
return null;
|
||
}
|
||
|
||
/**
|
||
* 静态 from、再导出 from、**动态 import()**、require() 都要算边。
|
||
* 第一版只匹配 `from '...'`,于是 GoogleAnalyticsWrapper 里的
|
||
* const GoogleAnalytics = dynamic(() => import('./GoogleAnalytics'))
|
||
* 这条边不存在 ⇒ GA 组件被报成"零引用死码"。按那结果删掉它,
|
||
* GA4 会在没有单测、没有 e2e 断言渲染的情况下从页面上消失。
|
||
* 动态导入的 specifier 是字符串字面量,这里一并抓(模式串无法静态解析,按字面量解析)。
|
||
*/
|
||
const IMPORT_RE = /(?:from|import|require)\s*\(?\s*['"]([^'"]+)['"]/g;
|
||
const edgesFrom = (file) => {
|
||
const txt = texts.get(file);
|
||
if (txt === undefined) return [];
|
||
const out = [];
|
||
for (const m of txt.matchAll(IMPORT_RE)) {
|
||
const t = resolve(m[1], file);
|
||
if (t && texts.has(t)) out.push(t);
|
||
}
|
||
return out;
|
||
};
|
||
|
||
/**
|
||
* App Router 的入口 = 位于 app/ 之下、文件名属于 Next 约定的那些模块。
|
||
* ⚠ 第一版写成 /(^|\/)app\/.*(^|\/)layout\.tsx$/ —— 中间的 (^|\/) 强制要求
|
||
* `layout.tsx` 前面有一个 `/`,于是 src/app/layout.tsx 这种**根级约定文件根本没被认成入口**,
|
||
* 连带它 import 的整棵树全部误判成死码(实测把 home-content-v16、layout 自己都报成"零引用")。
|
||
* 带着那版结果去删码就是删活码。判据改成按目录段 + 基名精确匹配。
|
||
*/
|
||
const NEXT_CONVENTION_BASENAMES = new Set([
|
||
'page.tsx', 'page.ts', 'layout.tsx', 'layout.ts', 'template.tsx', 'loading.tsx',
|
||
'error.tsx', 'global-error.tsx', 'not-found.tsx', 'route.ts', 'route.tsx',
|
||
'sitemap.ts', 'robots.ts', 'manifest.ts', 'opengraph-image.tsx', 'icon.tsx',
|
||
]);
|
||
const isEntry = (f) => {
|
||
const segments = f.split(path.sep);
|
||
if (!segments.includes('app')) return false;
|
||
const base = segments[segments.length - 1];
|
||
if (NEXT_CONVENTION_BASENAMES.has(base)) return true;
|
||
// 应用级非 import 入口:根 layout 之外的约定文件与 instrumentation/proxy 同理靠文件名而非路径深度
|
||
return segments.length === 2 && segments[0] === 'src'
|
||
&& /^(instrumentation|proxy)\.ts$/.test(base);
|
||
};
|
||
|
||
const norm = files.map((f) => path.normalize(f));
|
||
const entries = norm.filter(isEntry);
|
||
// 非 src 根(scripts/e2e/config)里的每个文件都当成一个使用者种子:
|
||
// 它们引用的 src 模块不是死码,哪怕页面 import 图到不了。
|
||
const consumerSeeds = norm.filter((f) => !f.startsWith(ROOT + path.sep));
|
||
if (entries.length === 0) { console.error('未能度量:找不到任何入口文件'); process.exit(2); }
|
||
|
||
const reachable = new Set();
|
||
const stack = [...entries, ...consumerSeeds];
|
||
while (stack.length) {
|
||
const cur = stack.pop();
|
||
if (reachable.has(cur)) continue;
|
||
reachable.add(cur);
|
||
for (const t of edgesFrom(cur)) if (!reachable.has(t)) stack.push(t);
|
||
}
|
||
|
||
// 反向引用表(含测试与桶文件,供报告用)
|
||
const importers = new Map();
|
||
for (const f of texts.keys()) for (const t of edgesFrom(f)) {
|
||
if (!importers.has(t)) importers.set(t, new Set());
|
||
importers.get(t).add(f);
|
||
}
|
||
|
||
const testFile = (f) => /\.test\.|__tests__/.test(f);
|
||
const barrel = (f) => /(^|\/)index\.ts$/.test(f);
|
||
|
||
const all = [...texts.keys()].filter((f) => !reachable.has(f)).sort();
|
||
|
||
/**
|
||
* 关键一步:不可达 ≠ 死码。第一版直接把 48 个不可达文件全列成"死码",
|
||
* 里面混着三类**必须**排除的东西 —— 照单删就会删掉在跑的生产代码:
|
||
* · 框架约定文件:由 Next/运行时按文件名加载,永远不会出现在 import 图里
|
||
* (proxy.ts = Next 16 的中间件约定、instrumentation*.ts、*.d.ts 是环境声明)
|
||
* · 生成物:src/generated/** 由 prisma generate 产出,不在入口闭包内
|
||
* · 组件库库存:src/components/ui/** 的 shadcn/Radix 原语是**故意**给后台与未来页面用的
|
||
* (avatar/switch/slider/progress/scroll-area 等还承载 check:grammar R2/R9 的"功能性的圆"),
|
||
* 删它们是个产品决定,不是清理。
|
||
*/
|
||
const CATEGORY_RULES = [
|
||
['convention', (f) => /(^|\/)(proxy|instrumentation|instrumentation-client)\.ts$/.test(f)
|
||
|| /\.d\.ts$/.test(f)
|
||
|| /(^|\/)(not-found|global-error|error|loading|template)\.tsx?$/.test(f)],
|
||
['generated', (f) => /(^|\/)generated\//.test(f)],
|
||
['library', (f) => /(^|\/)components\/ui\//.test(f)],
|
||
['test', (f) => testFile(f)],
|
||
];
|
||
const buckets = new Map();
|
||
for (const f of all) {
|
||
const cat = CATEGORY_RULES.find(([, pred]) => pred(f))?.[0] ?? 'dead';
|
||
if (!buckets.has(cat)) buckets.set(cat, []);
|
||
buckets.get(cat).push(f);
|
||
}
|
||
|
||
console.log(`入口 ${entries.length} 个 · 站内模块 ${texts.size} 个 · 可达 ${reachable.size} 个 · 不可达 ${all.length} 个`);
|
||
for (const cat of ['convention', 'generated', 'library', 'test', 'dead']) {
|
||
const list = buckets.get(cat) || [];
|
||
const label = {
|
||
convention: '框架约定/环境声明(不可达属正常,勿删)',
|
||
generated: '生成物(不在 import 图内,勿删)',
|
||
library: '组件库库存(未被引用但是库存,删除是产品决定)',
|
||
test: '测试文件本身',
|
||
dead: '*** 可判为死码 ***',
|
||
}[cat];
|
||
console.log(`\n[${cat}] ${list.length} 个 — ${label}`);
|
||
if (cat === 'dead' || cat === 'library') {
|
||
for (const f of list) {
|
||
const refBy = [...(importers.get(f) || [])];
|
||
const onlyDeadOrTests = refBy.length === 0 || refBy.every((r) => testFile(r) || barrel(r) || !reachable.has(r));
|
||
console.log(` ${f} ← ${refBy.length === 0 ? '零引用' : onlyDeadOrTests ? '仅测试/死链引用' : '被可达文件引用?!'}`);
|
||
}
|
||
}
|
||
}
|