rogerchappel/typegap

# typegap [](https://www.npmjs.com/package/typegap) [](https://www.typescriptlang.org/) [](LICENSE) TypeScript 的强大程度仅取决于它的类型注解。在快速原型设计阶段，`any` 会悄然潜入，函数会失去显式的返回类型，而 `noImplicitAny` 则“暂时”保持禁用状态。久而久之，这就会破坏安全网。 **typegap** 以静态方式工作——它会解析 `.ts`/`.tsx` 文件中的 AST，并报告类型漏洞，**且不需要 `tsc` 成功运行。** ## 快速开始 ``` # 安装 npm install -g typegap # 扫描当前目录 typegap # 扫描特定目录并显示详细信息 typegap ./src --detail # 输出为 JSON typegap --format json # 设置最低覆盖率阈值（若低于该值则退出码为 1） typegap --min-coverage 90 # 保存并比较 baselines typegap --baseline coverage.json # ... 之后 ... typegap --compare coverage.json ``` ## 它能捕获什么 | 问题 | 描述 | |---|---| | 🔴 **any** | 显式指定为 `any` 的参数或返回类型 | | 🟣 **unknown** | 指定为 `unknown` 的参数 | | ⚠️ **implicit** | 缺失类型注解——隐式的 `any` 或缺失的返回类型 | 它还能捕获隐藏在泛型（如 `Array` 和 `Record`）中的弱类型。 ## 输出 ### 文本摘要（默认） ``` TypeGap — Type Coverage Report Coverage: 64.3% Files: 12 Annotatable: 140 Annotated: 90 Implicit: 50 Any: 8 Unknown: 2 Files ┌────────────────────────────────────────────────────────────┐ │ 100.0% ✓ src/utils/helpers.ts │ 75.0% src/core/parser.ts (1 any, 2 implicit) │ 50.0% src/api/handler.ts (5 any, 3 implicit) └────────────────────────────────────────────────────────────┘ ``` ### 详情模式（`--detail`） ``` Details src/api/handler.ts:42 any → process(data) src/api/handler.ts:58 implicit → transform(params) src/core/utils.ts:15 implicit → format(value) ``` ## 参数 | 参数 | 描述 | |---|---| | `[directory]` | 要扫描的目录（默认：`.`） | | `--ignore ` | 要忽略的 glob 模式（逗号分隔） | | `--format ` | 输出格式：`text` 或 `json`（默认：`text`） | | `--detail` | 显示每个文件的类型注解详情 | | `--baseline ` | 将覆盖率基线保存到 JSON 文件 | | `--compare ` | 与已保存的基线进行比较 | | `--min-coverage ` | 如果覆盖率低于 `n`%，则以非零状态退出 | | `--pattern ` | 用于目标文件的自定义 glob 模式 | ## CI 集成 ``` # .github/workflows/types-lint.yml - name: Check type coverage run: npx typegap --min-coverage 80 ``` ## 工作原理 1. 使用 glob 查找所有 `.ts` / `.tsx` 文件 2. 使用 `@typescript-eslint/typescript-estree` 解析每个文件 3. 遍历 AST 中的函数、箭头函数、参数和变量 4. 对每个可注解的节点进行分类：显式（explicit）、`any`、`unknown` 或隐式（implicit） 5. 按公式 `(total - implicit) / total * 100` 计算覆盖率 ### 什么算作“可注解” - 函数 / 箭头函数返回类型 - 函数 / 箭头函数参数（包括解构参数和剩余参数） - 带有显式类型注解的变量声明 - catch 子句参数 constructor 方法被排除在外（它们不能有返回类型）。仅推断的变量（例如 `const x = 5`）不会被标记——仅会对显式注解的位置进行审查。 ### 快速开发设置 ``` git clone https://github.com/rogerchappel/typegap.git cd typegap npm install npm run build npm test ``` ## 许可证 MIT © [Roger Chappel](https://github.com/rogerchappel) ## 开发 在提交 PR 之前，请运行与 CI 相同的发布检查： ``` npm run release:check ``` 发布检查涵盖： - `npm run check` - tsc --noEmit - `npm run lint` - eslint src --ext .ts - `npm run build` - tsc - `npm test` - vitest run --coverage - `npm run smoke` - npm run build && node dist/cli.js --help && node dist/cli.js fixtures --format text - `npm run validate` - bash scripts/validate.sh - `npm run package:smoke` - npm pack --dry-run - `npm run release:check` - npm run check && npm test && npm run smoke && npm run package:smoke

标签：MITM代理, SOC Prime, TypeScript, 云安全监控, 安全插件, 开发工具, 自动化攻击, 静态分析