用途
dep-refs 是 z-code 仓库提供的 pnpm CLI 命令,用于在改动或删除 TypeScript 导出之前进行符号级引用检查。所有命令需在 z-code 仓库根目录执行。
主要能力
- 查询指定文件与导出符号的引用情况,例如:pnpm dep:refs packages/services/src/bots/botsService.ts:createBotsService
- 列出某个文件中的全部导出,适用于不确定符号确切名称时:pnpm dep:refs --list-exports packages/services/src/bots/botsService.ts
- 限定扫描范围以加快探索:pnpm dep:refs --scope packages/services packages/services/src/bots/botsService.ts:createBotsService
- 输出机器可读的 JSON,便于用 jq 汇总多个符号或比较 References 与 Re-exports 计数:pnpm -s dep:refs packages/services/src/bots/botsService.ts:createBotsService --json | jq .。需使用 pnpm 静默模式,因为普通输出带有额外横幅行。
使用方式与推荐流程
删除代码时先做广范围检查:运行 pnpm knip 找出可能未使用的导出,再对风险或不明确的导出使用 dep:refs 细查。在宣称某导出可以安全删除前,应优先执行不带 scope 的 dep:refs,以免漏掉跨包调用方。若符号只出现在 Re-exports 下,删除前需沿对外 barrel 路径追踪,因为再导出可能仍属于公共接口。重构时应依据 CLI 输出报告具体的调用方文件与行号,再决定更新调用方、保留导出还是删除。
限制
工具无法检测动态 import() 路径或基于字符串的引用,因此 References (0) 与 Re-exports (0) 仅表示“未找到静态引用”,不构成不存在动态使用的证明。--scope 仅用于有意限定的快速探索,不能替代全量检查。