复杂度扫描器

它解决的是哪类问题

一个文件 3000 行、圈复杂度常年 40 以上、谁都不想碰的模块，通常不是某一次提交写坏的，而是几十次需求叠加后没人回头统计的结果。complexity-scanner 瞄准的就是这个阶段：它不判断代码对错，只回答「这段代码现在有多难改，以及下一步往哪里拆」。

它在三个时间点最有用：代码评审时给可量化红线，重构前给现状快照，CI 里做阈值回归拦截。

它如何工作

核心是一次静态扫描，逐文件计算八项指标：有效代码行 LOC、函数数、最大与平均圈复杂度、扇出、扇入、最大嵌套深度、综合耦合分。再按区间映射到四个等级：<15 低、15–34 中、35–59 高、≥60 危险，并对每个越界文件给出一条具体建议，如 split-file、extract-module、split-function、reduce-nesting、reduce-coupling、use-dependency-injection。

实现细节上值得注意几点：

• TypeScript 走 Compiler API 做 AST 级解析，分支与循环计数来自语法树而非正则匹配。
• Swift、Kotlin、Java、Objective-C、JS/JSX 使用各自定制的启发式规则，精度低于 TS 路径。
• 扇入/扇出基于文件间导入关系统计，能定位耦合热点，但不等于架构分层是否正确。
• 阈值全部可覆盖：-t、--file-threshold、--func-threshold、--fanout-threshold、--nesting-threshold，换语言或换项目可重新标定。
• 输出支持 table、json、summary，--top 只看最复杂的 N 个文件，--critical-only 只看严重问题，--lang 与 --exclude 控制扫描范围。

适用边界

指标是启发式，不是判决书。解析器、状态机、协议编解码这类天然分支密集的代码，圈复杂度偏高可能是设计使然，直接套默认阈值 15 会刷出大量噪声。阈值要结合团队对可维护性的实际预期来调，而不是抄一份通用配置。

它看不到运行时。静态分析能告诉你一个文件被多少人导入、嵌了多少层，但无法判断某个高扇入模块是否真该下沉成公共层，也识别不了动态调用、反射和依赖注入框架带来的隐式耦合。use-dependency-injection 只是提示方向，重构判断仍要人来做。

另外它只分析能解析的文件。构建产物、生成代码、未纳入版本管理的目录需要用 --exclude 显式排除，否则统计会被噪音拉偏。