#!/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 ? '仅测试/死链引用' : '被可达文件引用?!'}`); } } }