zaxovaiko/depretec
GitHub: zaxovaiko/depretec
一款专注于检测并映射 JS/TS 项目中 @deprecated 注解的零配置 CLI 工具。
Stars: 0 | Forks: 0
# depretec
在你的 JS/TS 项目中查找 `@deprecated` JSDoc 用法并映射到其替换项。
- 扫描你的源码 **和** `node_modules` 类型中的 `@deprecated` 符号。
- 从 `{@link X}` 和自由文本（“Use `X` instead”、“Replaced by `X`”、“Prefer `X`”）中提取替换提示。
- 输出美观的表格、JSON（LLM 友好）或 Markdown（PR 友好）。
- 零配置。尊重你的 `.gitignore` 和 `tsconfig.json`，跳过 `@generated` 文件。
## 安装 / 运行
```
# 不安装
npx depretec
bunx depretec
# 或固定版本
bun add -D depretec
```
## 示例：zod v4
`src/schema.ts`:
```
import { z } from 'zod'
export const Schema = z.object({
email: z.string().email(),
site: z.string().url(),
})
```
```
$ npx depretec
┌───────────────────┬─────────────────┬───┬─────────────┐
│ Location │ Deprecated │ → │ Replacement │
├───────────────────┼─────────────────┼───┼─────────────┤
│ src/schema.ts:3:21│ ZodString.email │ → │ z.email() │
├───────────────────┼─────────────────┼───┼─────────────┤
│ src/schema.ts:4:20│ ZodString.url │ → │ z.url() │
└───────────────────┴─────────────────┴───┴─────────────┘
```
## 喂给 LLM
```
npx depretec --format json | llm -s "Apply these replacements to the files."
```
## 选项
```
Usage: depretec [paths...] [options]
Options:
-f, --format
pretty | json | md (default: pretty)
-p, --project path to tsconfig.json (default: auto-detect)
--include extra glob (repeatable)
--exclude exclude glob (repeatable)
--no-deps only scan user source, skip node_modules
--fail-on-found exit 1 if any occurrence (for CI)
-h, --help
-v, --version
```
位置参数 `paths` 选择项目根（首个路径生效）。默认为 `cwd`。
## 程序化 API
```
import { scan } from 'depretec'
const report = await scan({ cwd: './my-project' })
for (const o of report.occurrences) {
console.log(`${o.file}:${o.line} ${o.deprecation.qualifiedName} → ${o.deprecation.replacement ?? '?'}`)
}
```
## 工作原理
通过 [`ts-morph`](https://ts-morph.com) 构建 TypeScript Program 的两轮遍历：
1. **收集** 所有带有 `@deprecated` JSDoc 标签的声明（`function`、`method`、`class`、`property`、`variable`、`type`、`interface`、`enum`、访问器），包括源码和 `.d.ts` 中的。
2. **匹配** 使用 TypeScript 类型检查器将源码中的每个标识符与这些声明匹配（遵循 re-export，解析通过方法链的属性访问，如 `z.string().email()`）。
替换提取按顺序尝试：`{@link X}` / `{@linkcode X}` / `{@linkplain X}`，然后是自由文本启发式（`use \`X\``、`replaced by \`X\``、`prefer \`X\`` 以及裸词变体）。
## 非目标（目前）
- 自动修复 / 写入文件（计划支持 `--fix`）。
- `.vue` / `.svelte` / `.astro`。
- 运行时弃用检测。
## 许可证
MIT
标签：AST解析, CI集成, CMS安全, GNU通用公共许可证, JavaScript, JSDoc, MITM代理, Node.js, SEO: depretec, SEO: JS扫描, SEO: TypeScript工具, SEO: 代码迁移, SEO: 废弃标记, TypeScript, WebSocket, 云安全监控, 代码维护, 依赖分析, 安全插件, 弃用标记, 源码分析, 自动化攻击, 自动化迁移, 零配置, 静态分析