dep-scope

dep-scope

Florian BRUNIAUX · Méthode Aristote の AI 創業エンジニア @ Méthode Aristote 開発者から CTO／VP Eng まで 13 年 · ブログ ↗ · プロジェクト ↗

TypeScript／JavaScript プロジェクト向けのシンボルレベルの依存関係分析＋LLM 対応の移行プロンプトです。

「Knip は未使用のものを教えてくれます。dep-scope は、残したものをどのように使っているかを教え、それを削除するためのプロンプトを生成します。」

dep-scope を使う場面

適した用途：

• レガシープロジェクトの監査：lodash の関数に、ネイティブの代替機能が登場していないか確認する
• ライブラリの統合：アイコンライブラリが 3 つも本当に必要でしょうか？
• 移行：コンテキストを考慮したプロンプトを生成し、Claude Code にリファクタリングを任せる
• 興味・関心：「この 50KB のライブラリから、実際にどのシンボルを使っているのでしょうか？」

適したツールではない場合：

• 未使用の依存関係だけを調べたい → 代わりに Knip を使ってください
• コードベースがすでに適切に保守されている → dep-scope はほとんどの場合「KEEP」と表示します

簡単な例

$ 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 マイクロユーティリティの対応	❌	❌	❌	✅
推移的グラフの分析	❌	❌	❌	✅
モノレポのワークスペース対応	⚠️	❌	❌	✅
重複の検出	❌	❌	❌	✅
LLM 移行プロンプト	❌	❌	❌	✅
MCP サーバー（AI エディター）	❌	❌	❌	✅
オープンソース／無料	✅	✅	❌ 企業向け	✅

推奨：未使用の検出には Knip、より詳細な分析と移行には dep-scope を使ってください。両者は相性よく連携します（dep-scope は Knip がインストールされていれば自動検出します）。

インストール

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"]

これらのパッケージは、REMOVEではなく、INVESTIGATE（十分に使用されている場合はKEEP）として表示されます。

無効化 — .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	1つのパッケージをシンボル単位で分析
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"]
    }
  }
}

接続すると、CLIコマンドを実行しなくても、セッション中にAIエディターへscan_projectやgenerate_migration_promptを直接呼び出すよう依頼できます。

ドキュメント

• コマンドリファレンス
• 設定
• AIプロンプト＋Claude Codeスラッシュコマンド
• MCP サーバーのセットアップ
• プログラム用API
• アーキテクチャと内部仕様

要件

• Node.js >= 18.0.0
• package.jsonを含むTypeScript/JavaScriptプロジェクト

エコシステムを探索する

これらのプロジェクトは、このツールと機能が重複することなく、ワークフローを拡張します。

• claude-code-pluginsで自動化する：コード品質ワークフローにシンボルレベルの依存関係分析を追加します。
• Claude Code Ultimate Guideで学ぶ：CLI と MCP のどちらを使うか選び、品質チェックの方針を定めます。

オープンソースのエコシステム全体を見る

ライセンス

MIT