doxy

针对 JavaScript 和 TypeScript 的静态 API 兼容性验证工具
在 lint 阶段捕获已废弃、已移除和未来的 API —— 在它们导致运行时崩溃之前。

安装  •  快速开始  •  CLI 参考  •  配置  •  工作原理

可以将 doxy 视为 **“npm 包的 caniuse”** —— 它会读取你已安装或声明的依赖版本和精选的 API 数据，以在 lint 阶段发现不匹配之处，实现零运行时开销。 ``` $ doxy verify src/App.tsx 5:17 warning react.createFactory is deprecated since 16.13.0. deprecated-api dxy_a1b2c3d4 Use React.createElement or JSX instead. 11:18 warning react-dom.findDOMNode is deprecated since 16.6.0. deprecated-api dxy_e5f6a7b8 Use refs instead. src/Dashboard.tsx 3:14 error react.useId is not available in 17.0.2. future-api dxy_c9d0e1f2 It was added in 18.0.0. 3 findings (1 error, 2 warnings) ``` ## 为什么选择 doxy？ | 问题 | 没有 doxy 时 | 有 doxy 时 | |---|---|---| | 使用已废弃的 API | （可能）在代码审查时发现 | 在 lint 阶段被捕获 | | 升级后调用已移除的 API | 生产环境中的运行时崩溃 | 在部署前被捕获 | | 使用了更高版本才有的 API | `undefined is not a function` | 提供包含版本信息的清晰错误 | | 参数数量错误 | 隐蔽的 Bug，静默失败 | 根据预期的参数数量被捕获 | ## 功能特性 - **废弃 API 检测** —— 在你使用了当前安装版本中已废弃的 API 时发出警告 - **移除 API 检测** —— 在你使用了当前安装版本中已移除的 API 时报错 - **未来 API 检测** —— 在你使用了需要更高安装版本的 API 时报错 - **参数数量错误检测** —— 在你调用函数时传递了错误数量的参数时报错 - **行内抑制** —— 使用 `// doxy-ignore` 注释忽略特定的检测结果 - **配置级抑制** —— 使用基于 glob 的规则在项目范围内忽略特定模式 - **多种输出格式** —— 人类可读格式、JSON、JSONL - **框架感知** —— 理解 React 导入模式和 ReactDOM 子路径 - **快速** —— 由 SWC 驱动进行解析（比 TypeScript 编译器快约 100 倍） ## 安装说明 ``` npm install --save-dev doxy ``` ``` pnpm add -D doxy ``` ``` yarn add -D doxy ``` ## 快速开始 ``` # 在你的项目上运行验证 npx doxy verify # 输出为 JSON 以进行工具集成 npx doxy verify --json # 输出为 JSONL 用于 agent 或 streaming 工作流 npx doxy verify --jsonl ``` ## CLI 参考 ### 命令 | 命令 | 描述 | |---|---| | `doxy verify [files...]` | 运行验证（默认命令） | ### Verify 标志 | 标志 | 描述 | |---|---| | `--json` | 将检测结果输出为 JSON | | `--jsonl` | 将检测结果输出为换行符分隔的 JSON | | `--fail-on ` | 当检测结果达到或高于 `error`、`warning` 或 `info` 级别时以非零状态码退出 | | `[files...]` | 用于分析的可选显式文件，代替配置中的 glob 模式 | ### 退出码 | 代码 | 含义 | |---|---| | `0` | 没有达到或高于 `--fail-on` 严重级别的检测结果 | | `1` | 存在达到或高于 `--fail-on` 严重级别的检测结果 | | `2` | 配置错误 | | `3` | 项目错误（无法读取项目） | | `4` | 权威数据错误 | | `5` | 内部错误 | ## 配置 在你的项目根目录中创建一个 `doxy.config.json` 文件： ``` { "include": ["src/**/*.{ts,tsx,js,jsx}"], "exclude": ["**/*.test.*", "**/*.spec.*"], "severity": "warning", "failOn": "error", "frameworks": {}, "pathAliases": {}, "suppressions": [], "requireSuppressionReason": false, "authorityDataSources": ["builtin"] } ``` ### 抑制规则 使用配置规则在项目范围内忽略检测结果： ``` { "suppressions": [ { "paths": ["src/legacy/**"], "kind": "deprecated-api", "reason": "Legacy module — migrating to new APIs in Q2" }, { "package": "react", "export": "findDOMNode", "kind": "*", "reason": "Used in legacy adapter, isolated and tested" } ] } ``` ### 行内抑制 直接在代码中忽略个别的检测结果： ``` // Suppress the next line // doxy-ignore deprecated-api -- Legacy compat layer const factory = createFactory("div"); // Suppress current line const node = findDOMNode(this); // doxy-ignore-line deprecated-api // Suppress a block /* doxy-ignore-start deprecated-api -- Entire legacy section */ const a = createFactory("div"); const b = createFactory("span"); /* doxy-ignore-end */ ``` ## 工作原理 ``` Source files ─┐ ├─► SWC Parser ─► Import Resolver ─► Authority Store Query ─► Findings Lockfile ─────┘ │ │ │ │ │ │ Normalized AST SymbolUsage[] Version-aware lookup (deprecated? removed? future? wrong arity?) ``` 1. **解析 (Parse)** —— SWC 将你的源文件解析为标准化的 AST 2. **解析 (Resolve)** —— 导入解析器将 `import` 语句映射到包/导出对 3. **查询 (Query)** —— 根据你安装的版本的精选权威数据检查每个符号 4. **发出 (Emit)** —— 生成包含严重级别、消息和修复建议的检测结果 5. **过滤 (Filter)** —— 应用行内和配置级的抑制规则 6. **报告 (Report)** —— 以人类可读格式、JSON 或 JSONL 格式输出检测结果 doxy 绝不会执行你的代码。它会读取你的 lockfile 以获取已安装的版本，并使用精选的 API 规范来静态检测问题。 ## 支持的框架 | 框架 | 状态 | 包 | |---|---|---| | React | 已支持 | `react`, `react-dom` | 权威数据目前涵盖了 React 和 ReactDOM API，包括 hooks、生命周期方法、渲染 API 和废弃时间线。 ## 检测结果类型 | 类型 | 严重级别 | 描述 | |---|---|---| | `deprecated-api` | warning | API 在你安装的版本中已被废弃 | | `removed-api` | error | API 在你安装的版本中已被移除 | | `future-api` | error | API 需要高于当前安装的版本 | | `wrong-arity` | error | 调用函数时使用了错误的参数数量 | | `unknown-export` | info | 在权威数据中未找到该导出 | ## CI 集成 ``` # GitHub Actions - name: Check API compatibility run: npx doxy verify --fail-on error ``` doxy 会将**检测结果写入 stdout**，将**所有其他内容写入 stderr**，从而可以轻松地在 CI 流水线中对输出进行管道传输和解析。 ### 项目结构 ``` doxy/ ├── src/ │ ├── cli/ `verify` command + reporters │ ├── core/ Pure analysis logic │ │ ├── types/ All shared type definitions │ │ ├── repo-context/ Version detection from manifests │ │ ├── files/ File discovery from config globs │ │ ├── import-resolver/ Import → package/export mapping │ │ ├── analyzer/ Per-file analysis orchestration │ │ ├── suppression/ Inline + config suppression │ ├── authority/ Authority data store │ ├── adapters/ Framework-specific adapters │ ├── parser/ SWC-based AST parsing ├── authority-data/ Curated API spec datasets └── fixtures/ Test fixture mini-projects ``` ### 运行测试 ``` npm test # run all tests npm run test:watch # watch mode npm run typecheck # type check only npm run lint # lint only npm run check # all of the above ``` ## 许可证 [MIT](./LICENSE)

标签：API兼容性, CMS安全, JavaScript, Linter, MITM代理, NPM包管理, pptx, SEO优化, TypeScript, 人工智能, 代码分析, 代码安全, 代码审查工具, 代码索引, 依赖管理, 凭证管理, 前端工程化, 威胁情报, 安全插件, 废弃API检测, 开发者工具, 文档智能, 文档结构分析, 漏洞枚举, 用户模式Hook绕过, 自动化攻击, 运行时错误预防, 错误基检测, 静态代码分析