dep-scope

dep-scope

Florian BRUNIAUX · Méthode Aristote 的 AI 创始工程师 @ Méthode Aristote 从开发者到 CTO / VP Eng 的 13 年 · 博客 ↗ · 项目 ↗

面向 TypeScript/JavaScript 项目的符号级依赖分析 + 适用于大模型的迁移提示词。

“Knip 告诉你哪些内容未被使用。dep-scope 告诉你如何使用保留的内容，并生成移除它的提示词。”

何时使用 dep-scope

适用场景：

• 遗留项目审计：查找 lodash 中已有原生替代方案的函数
• 库整合：我们真的需要 3 个图标库吗？
• 迁移：生成了解上下文的提示词，让 Claude Code 执行重构
• 好奇探索：“我们实际使用这个 50KB 库中的哪些符号？”

不适合的场景：

• 你只想查找未使用的依赖 → 改用 Knip
• 你的代码库已经维护良好 → dep-scope 多半只会说“保留”

快速示例

$ dep-scope scan

═══════════════════════════════════════════
  dep-scope Analysis Report
═══════════════════════════════════════════

Summary:
  Total dependencies: 45
  ✓ Keep:          38
  ↻ Recode Native: 3
  ✗ Remove:        2
  ⊕ Peer Dep:      4

Action Items:
  Remove (unused):
    ✗ moment
    ✗ has-flag

  Recode to native:
    ↻ lodash.debounce (1 symbol) → custom debounce function
    ↻ array-includes (1 symbol) → Array.prototype.includes
    ↻ left-pad (1 symbol) → String.prototype.padStart

对比

功能	Knip	Depcheck	Moderne	dep-scope
未使用项检测	✅ 出色	✅ 良好	❌	⚠️ 基础
配置文件扫描	✅	✅	❌	✅
符号级分析	❌	❌	✅	✅
原生替代方案数据库	❌	❌	✅（lodash）	✅ 195 个包
e18e 微型工具覆盖	❌	❌	❌	✅
传递依赖图分析	❌	❌	❌	✅
Monorepo 工作区支持	⚠️	❌	❌	✅
重复项检测	❌	❌	❌	✅
大模型迁移提示词	❌	❌	❌	✅
MCP 服务（AI 编辑器）	❌	❌	❌	✅
开源 / 免费	✅	✅	❌ 企业版	✅

建议：使用 Knip 检测未使用项，使用 dep-scope 进行深入分析和迁移。两者配合良好（如果已安装 Knip，dep-scope 会自动检测）。

安装

CLI（全局）：

npm install -g @florianbruniaux/dep-scope

无需安装：

npx @florianbruniaux/dep-scope scan

MCP 服务（AI 编辑器 — 无需 CLI）：

将配置添加到编辑器的 MCP 配置中，服务便会通过 npx 按需运行。请参阅下方的 MCP 服务 部分，查看各编辑器的配置示例。

从源码安装：

git clone https://github.com/FlorianBruniaux/node-dep-scope.git
cd node-dep-scope
npm install && npm run build && npm install -g .

快速开始

cd /path/to/your/project

dep-scope init                        # configure dep-scope for your project (interactive)
dep-scope scan                        # full scan
dep-scope scan --root                 # scan full project, including scripts/ tools/ bin/
dep-scope scan --check-duplicates     # include duplicate detection
dep-scope scan --check-transitive     # surface transitive polyfills (e18e database)
dep-scope scan --each-workspace       # monorepo: scan each package individually
dep-scope migrate                     # generate migration prompts for all candidates
dep-scope migrate lodash              # target a specific package
dep-scope report -o ./audit.md        # markdown report

设置：dep-scope init

首次扫描前运行 dep-scope init。向导会检测你的项目，并通过 4 个问题生成配置：

dep-scope init

  Detected: Next.js project
  Found dirs: src/, scripts/, app/

? Source directories to scan:
  ● Auto-detected: src/, scripts/, app/  (recommended)
  ○ Full project root (.) — includes everything
  ○ Choose directories manually...

? Include devDependencies in scan? (y/N)
? Symbol threshold for RECODE_NATIVE verdict: (5)
? Config format:
  ● .depscoperc.json  (simple JSON, recommended)
  ○ depscope.config.ts  (TypeScript with autocomplete)

✓ Created .depscoperc.json
  Preset: react  |  Dirs: src, scripts, app  |  Threshold: 5

在 CI 中使用 -y 跳过提示：dep-scope init --yes。

获取准确结果

自动检测范围包括：src、app、lib、pages、components、hooks、server、scripts、tools、bin、cli。如果项目的代码位于其他目录，请传入 --root 扫描所有内容，或在 .depscoperc.json 中显式设置 srcPaths：

{
  "srcPaths": ["src", "app", "scripts", "tools"]
}

“未使用”判定有误？ 该程序包可能在扫描范围之外的目录中使用（scripts/、tools/ 等）。移除任何内容之前，请运行 dep-scope scan --root 进行验证。如果扫描范围较窄时出现移除建议，dep-scope 会向你发出警告。

配置文件检测

dep-scope 会自动扫描项目根目录中的配置文件，以避免将以字符串形式引用的程序包误判为“未使用”——这在 CLI 工具、测试运行器和框架插件中很常见。

自动检测的内容：

配置文件	检测示例
package.json 脚本	"lint": "oxlint .", "format": "oxfmt ."
vitest.config.*	environment: "jsdom", setupFiles: ["@testing-library/jest-dom"]
vite.config.*	plugins: ["@vitejs/plugin-vue"]
next.config.*	turbo.rules["*.svg"].loaders: ["@svgr/webpack"]
.storybook/main.*	addons: ["@storybook/addon-mcp"]

这些程序包会标记为 INVESTIGATE（如果使用充分，则标记为 KEEP），而不是 REMOVE。

选择退出 — 在 .depscoperc.json 中禁用特定检测器：

{
  "stringReferences": {
    "disable": ["storybook-config"]
  }
}

可用的检测器 ID：package-json-scripts、vitest-config、vite-config、next-config、storybook-config。使用 "disable": "all" 可完全关闭配置扫描。

通过自定义检测器扩展 — 在 depscope.config.ts 中：

import { defineConfig, defineDetector } from "@florianbruniaux/dep-scope";

export default defineConfig({
  stringReferences: {
    detectors: [
      defineDetector({
        id: "my-tool-config",
        label: "my-tool.config.json",
        filePatterns: ["my-tool.config.json"],
        async detect(filePath, ctx) {
          // return StringReference[] for packages found in this file
          return [];
        },
      }),
    ],
  },
});

MCP 服务

dep-scope 提供 Model Context Protocol 服务，让 AI 编辑器（Claude Code、Cursor、Windsurf）可以直接查询依赖项，无需 CLI、Markdown 文件或复制粘贴。

已列入官方 MCP Registry：io.github.FlorianBruniaux/dep-scope

可用工具

工具	参数	功能
scan_project	projectPath、srcPaths、threshold、includeDev、checkDuplicates、checkTransitive、withKnip	全面扫描依赖项并给出判定
analyze_package	packageName、projectPath、srcPaths	分析单个程序包的符号级使用情况
get_migration_candidates	projectPath	列出所有 RECODE_NATIVE + CONSOLIDATE 程序包
generate_migration_prompt	packageName、projectPath	直接生成迁移提示词
find_duplicates	projectPath	检测功能重叠的库

设置

将以下 mcpServers 条目添加到编辑器的配置中。服务会通过 npx 按需运行，无需全局安装。

Claude Code — ~/.claude.json：

{
  "mcpServers": {
    "dep-scope": {
      "command": "npx",
      "args": ["--package=@florianbruniaux/dep-scope", "-y", "dep-scope-mcp"]
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "dep-scope": {
      "command": "npx",
      "args": ["--package=@florianbruniaux/dep-scope", "-y", "dep-scope-mcp"]
    }
  }
}

Cursor — ~/.cursor/mcp.json：

{
  "mcpServers": {
    "dep-scope": {
      "command": "npx",
      "args": ["--package=@florianbruniaux/dep-scope", "-y", "dep-scope-mcp"]
    }
  }
}

Windsurf — ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "dep-scope": {
      "command": "npx",
      "args": ["--package=@florianbruniaux/dep-scope", "-y", "dep-scope-mcp"]
    }
  }
}

连接后，你可以在会话过程中直接让 AI 编辑器调用 scan_project 或 generate_migration_prompt，无需运行任何 CLI 命令。

文档

• 命令参考
• 配置
• AI 提示词 + Claude Code 斜杠命令
• MCP 服务设置
• 编程 API
• 架构与内部机制

要求

• Node.js >= 18.0.0
• 包含 package.json 的 TypeScript/JavaScript 项目

探索生态

这些项目可扩展工作流，而不会重复此工具的功能：

• 使用 claude-code-plugins 自动化：将符号级依赖分析添加到代码质量工作流中。
• 通过 Claude Code Ultimate Guide 学习：选择 CLI 或 MCP，并规划质量检查。

浏览完整的开源项目集合

许可证

MIT