## 静态缺陷检测

> 静态缺陷指不依赖运行时、通过代码结构分析即可发现的问题，模拟编译器/类型检查器的行为。
> 本文件是检测路由表——根据代码特征定位需要加载的检测项子文件。

### 检测路由表

| 触发信号（代码特征） | 触发检测项 | 文件 |
|---------------------|-----------|------|
| 括号/大括号/圆括号不匹配、分号缺失、关键字拼写错误 | 语法与依赖 | [syntax-and-deps.md](syntax-and-deps.md) |
| `import`/`require`/`#include` 引用的模块路径不存在 | 语法与依赖 | [syntax-and-deps.md](syntax-and-deps.md) |
| 导入的符号在当前文件中未使用（`import X` 但无 `X` 引用） | 符号解析 | [symbol-resolution.md](symbol-resolution.md) |
| 变量声明后未使用（`const x = 1` 后无引用） | 符号解析 | [symbol-resolution.md](symbol-resolution.md) |
| 内层变量遮蔽外层同名变量（`let x = 1; { let x = 2 }`） | 符号解析 | [symbol-resolution.md](symbol-resolution.md) |
| 变量/函数/类使用前未定义 | 符号解析 | [symbol-resolution.md](symbol-resolution.md) |
| 函数调用参数个数/类型与定义不匹配 | 类型匹配 | [type-matching.md](type-matching.md) |
| 变量赋值类型与声明类型不一致 | 类型匹配 | [type-matching.md](type-matching.md) |
| 接口实现的签名与接口定义不一致 | 类型匹配 | [type-matching.md](type-matching.md) |
| `return`/`throw`/`break` 之后的代码（不可达） | 死代码 | [dead-code.md](dead-code.md) |
| 永远为真/假的条件（`if (true)`、`if (1)`） | 死代码 | [dead-code.md](dead-code.md) |
| 导出的函数/类未被任何文件引用 | 死代码 | [dead-code.md](dead-code.md) |
| `switch` 分支无 `break`/`return` 且无 `// fallthrough` 注释 | 死代码 | [dead-code.md](dead-code.md) |
| `import A` → A 又 `import` 当前文件（循环引用） | 循环依赖 | [circular-deps.md](circular-deps.md) |
| 模块间存在 A→B→C→A 的依赖链 | 循环依赖 | [circular-deps.md](circular-deps.md) |

### 使用方式

1. 读取变更代码，识别上述触发信号
2. 按匹配到的触发信号，**只加载**对应子文件（无需全量加载）
3. 无匹配触发信号 → 不执行静态缺陷检测
4. 优先使用 LSP 工具（`find_definition`、`find_references`）做精确分析，LSP 不可用时降级为 Grep + Read

### 通用排除规则

以下情况不报告缺陷：
- **测试文件**：`*.test.*`、`*.spec.*`、`__tests__/` 目录
- **生成的代码**：`generated/`、`*.generated.*`、`node_modules/`、vendor
- **第三方依赖**：仅当前项目内的代码可见，需要安装的三方依赖不可见。涉及三方依赖的导入、类型、符号均不报告
- **类型声明文件**：`*.d.ts`、`*.pyi`（仅声明无实现，不适用部分检测）
- **已由编译器/IDE 检测的问题**：TypeScript 编译错误、Python mypy 错误（重复报告无价值）
