Files
novalon-website/scripts/dead-modules.mjs
zhangxiang ffc43fdeb7 refactor(deadcode): 删 17 个不可达模块并做成可复跑的可达性判定,棘轮回到绿且未降任何门限
台账 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
2026-10-17 00:17:40 +08:00

173 lines
8.7 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
/**
* 站内模块可达性判定:从真实入口(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 ? '仅测试/死链引用' : '被可达文件引用?!'}`);
}
}
}