archtracker-mcp 0.4.3 → 0.5.0

package/README.md

@@ -16,6 +16,7 @@
 <p align="center">
   <a href="#quick-start">Quick Start</a> &bull;
   <a href="#features">Features</a> &bull;
+  <a href="#multi-layer-architecture">Multi-Layer</a> &bull;
   <a href="#web-viewer">Web Viewer</a> &bull;
   <a href="#mcp-tools">MCP Tools</a> &bull;
   <a href="#cli-commands">CLI</a> &bull;
@@ -34,17 +35,19 @@ When AI agents modify code, they **miss cascading impacts**:
 | File renamed during refactor | AI references stale paths next session | `context` command gives current valid paths |
 | New dependency added | No visibility into coupling increase | Diff report flags the architectural change |
 | PR review | Manual dependency tracing | CI auto-checks for architecture drift |
+| Multi-service project | No cross-boundary visibility | Layer-aware analysis with cross-layer link detection |
 
 **archtracker-mcp** provides dependency analysis, snapshot diffing, impact simulation, and interactive visualization — all accessible via MCP tools, CLI, web UI, or Claude Code Skills.
 
 ## Features
 
 - **Dependency Graph Analysis** — Regex-based static analysis for **13 languages** (JS/TS, Python, Rust, Go, Java, C/C++, C#, Ruby, PHP, Swift, Kotlin, Dart, Scala)
-- **Interactive Web Viewer** — Force-directed graph, hierarchy diagram, diff view with D3.js
+- **Multi-Layer Architecture** — Analyze multiple services/layers as a unified graph with cross-layer connection detection (NEW in v0.5.0)
+- **Interactive Web Viewer** — Force-directed graph with convex hull layer grouping, hierarchy diagram, diff view with D3.js
 - **Impact Simulation** — Click any file to visualize transitive dependents (BFS traversal)
 - **Snapshot Diffing** — Save architecture snapshots and detect drift over time
 - **MCP Server** — 5 tools for Claude Code / AI agents via Model Context Protocol
-- **Claude Code Skills** — 5 slash commands (`/arch-check`, `/arch-snapshot`, etc.)
+- **Claude Code Skills** — 6 slash commands (`/arch-check`, `/arch-snapshot`, `/arch-serve`, etc.)
 - **CI Integration** — `--ci` mode + auto-generated GitHub Actions workflow
 - **Bilingual** — Full English/Japanese support (auto-detected from `LANG` env)
 - **Dark/Light Theme** — Settings persist via localStorage
@@ -83,6 +86,72 @@ archtracker serve --target src --watch
 archtracker check --target src
 ```
 
+## Multi-Layer Architecture
+
+For projects with multiple services or layers (e.g. frontend + backend + shared libraries), archtracker can analyze them as a unified graph.
+
+### Setup
+
+Create `.archtracker/layers.json` in your project root:
+
+```json
+{
+  "version": "1.0",
+  "layers": [
+    {
+      "name": "Frontend",
+      "targetDir": "frontend/src",
+      "language": "javascript",
+      "color": "#58a6ff",
+      "description": "React Web App"
+    },
+    {
+      "name": "Backend",
+      "targetDir": "backend/app",
+      "language": "python",
+      "color": "#3fb950",
+      "description": "FastAPI Server"
+    }
+  ],
+  "connections": [
+    {
+      "fromLayer": "Frontend",
+      "fromFile": "api/client.ts",
+      "toLayer": "Backend",
+      "toFile": "main.py",
+      "type": "api-call",
+      "label": "REST API"
+    }
+  ]
+}
+```
+
+Or generate a template:
+
+```bash
+archtracker layers init
+```
+
+### Usage
+
+When `layers.json` exists, all commands automatically use multi-layer mode:
+
+```bash
+archtracker analyze --root .          # Analyzes all layers
+archtracker serve --root . --watch    # Web viewer with layer tabs and convex hulls
+archtracker check --root .            # Cross-layer diff check
+```
+
+Each layer is analyzed independently with its own language setting, then merged into a unified graph with prefixed paths (e.g. `Backend/worker.py`).
+
+### Web Viewer with Layers
+
+- **Layer tabs**: Multi-select toggle to focus on specific layers (Shift+click for solo mode)
+- **Convex hulls**: Each layer is visually grouped with a colored boundary
+- **Cross-layer links**: Dashed lines showing connections between layers (toggleable in settings)
+- **Layer Cohesion slider**: Adjust how tightly nodes cluster within their layer
+- **Diff highlighting**: Layer boundaries are highlighted when they contain changed files
+
 ## Web Viewer
 
 The interactive web viewer provides three visualization modes:
@@ -93,8 +162,8 @@ The interactive web viewer provides three visualization modes:
 
 - Drag, zoom, and click nodes to explore dependencies
 - Click a node to **pin** its highlight — hover other nodes to compare
-- Filter by directory with bottom pills
-- Adjust gravity, node size, font size, link opacity
+- Filter by directory with bottom pills, by layer with top tabs
+- Adjust gravity, layer cohesion, node size, font size, link opacity
 - **Impact mode**: click any file to see all transitively affected files
 
 ![Impact Simulation](docs/screenshots/impact-simulation.png)
@@ -105,7 +174,7 @@ The interactive web viewer provides three visualization modes:
 
 - Layered top-down layout showing dependency depth
 - Click-to-pin highlighting with detail panel
-- Directory-based color coding with legend
+- Layer-aware filtering with compact relayout
 
 ### Diff View
 
@@ -113,6 +182,7 @@ The interactive web viewer provides three visualization modes:
 
 - Color-coded visualization of architecture changes
 - Green = added, Red = removed, Yellow = modified, Blue = affected
+- Layer grouping with highlighted boundaries for changed layers
 - Available when a snapshot exists for comparison
 
 ```bash
@@ -137,12 +207,15 @@ Add archtracker as an MCP server for Claude Code or any MCP-compatible AI agent:
 
 | Tool | Description |
 |------|-------------|
-| `generate_map` | Analyze dependency graph and return structured JSON |
+| `generate_map` | Analyze dependency graph and return raw JSON (for programmatic use) |
+| `analyze_existing_architecture` | Comprehensive human-readable analysis report |
 | `save_architecture_snapshot` | Save snapshot to `.archtracker/snapshot.json` |
 | `check_architecture_diff` | Compare snapshot with current code, show impacts |
 | `get_current_context` | Get valid file paths and architecture summary |
 | `search_architecture` | Search by path, impact, criticality, or orphans |
 
+All tools auto-detect multi-layer projects when `.archtracker/layers.json` exists.
+
 ## CLI Commands
 
 ```
@@ -152,6 +225,8 @@ archtracker check [options]      Compare snapshot with current code
 archtracker context [options]    Show architecture context (for AI sessions)
 archtracker serve [options]      Launch interactive web viewer
 archtracker ci-setup [options]   Generate GitHub Actions workflow
+archtracker layers init          Create template layers.json
+archtracker layers list          List configured layers
 
 Options:
   -t, --target <dir>       Target directory (default: "src")
@@ -167,6 +242,8 @@ Options:
   --lang <locale>          Language: en | ja (auto-detected from LANG)
 ```
 
+> **Multi-layer note**: When `.archtracker/layers.json` exists and `--target` is not explicitly set, all commands automatically use multi-layer analysis. Use `--root` to specify the project root.
+
 ## Claude Code Skills
 
 Copy the `skills/` directory to your project:
@@ -182,12 +259,16 @@ cp -r node_modules/archtracker-mcp/skills/ .claude/skills/
 | `/arch-snapshot` | Save current architecture snapshot |
 | `/arch-context` | Initialize AI session with valid paths |
 | `/arch-search` | Search architecture (path, impact, critical, orphan) |
+| `/arch-serve` | Launch interactive web viewer in browser |
+
+All skills support multi-layer projects automatically.
 
 ## Programmatic API
 
 ```typescript
 import {
   analyzeProject,
+  analyzeMultiLayer,
   saveSnapshot,
   loadSnapshot,
   computeDiff,
@@ -195,9 +276,16 @@ import {
   formatAnalysisReport,
 } from "archtracker-mcp";
 
-// Analyze
+// Single-directory analysis
 const graph = await analyzeProject("src", { exclude: ["__tests__"] });
 
+// Multi-layer analysis
+const layers = [
+  { name: "Frontend", targetDir: "frontend/src", language: "javascript" },
+  { name: "Backend", targetDir: "backend/app", language: "python" },
+];
+const multi = await analyzeMultiLayer(".", layers);
+
 // Snapshot
 const snapshot = await saveSnapshot(".", graph);
 
@@ -284,17 +372,19 @@ AI エージェントがコードを修正する際、**波及的な影響を見
 | リファクタでファイル名変更 | 次のセッションで古いパスを参照 | `context` コマンドで現在の有効パスを取得 |
 | 新しい依存関係を追加 | 結合度の増加が見えない | 差分レポートがアーキテクチャ変更を検出 |
 | PRレビュー | 手動で依存関係を追跡 | CIが自動でアーキテクチャドリフトをチェック |
+| マルチサービス構成 | サービス境界を跨ぐ影響が見えない | レイヤー対応分析でクロスレイヤー接続を検出 |
 
 **archtracker-mcp** は依存関係分析、スナップショット差分、影響シミュレーション、インタラクティブな可視化を提供します。MCP ツール、CLI、Web UI、Claude Code Skills からアクセス可能です。
 
 ## 機能
 
 - **依存関係グラフ分析** — 正規表現ベースの静的解析、**13言語**対応（JS/TS, Python, Rust, Go, Java, C/C++, C#, Ruby, PHP, Swift, Kotlin, Dart, Scala）
-- **インタラクティブ Web ビューア** — D3.js による力学モデルグラフ、階層図、差分ビュー
+- **マルチレイヤーアーキテクチャ** — 複数サービス/レイヤーを統合グラフとして分析、クロスレイヤー接続の自動検出（v0.5.0 新機能）
+- **インタラクティブ Web ビューア** — D3.js による力学モデルグラフ（凸包レイヤーグループ表示）、階層図、差分ビュー
 - **影響シミュレーション** — ファイルをクリックして推移的な被依存ファイルを可視化（BFS探索）
 - **スナップショット差分** — アーキテクチャスナップショットを保存し、ドリフトを検出
 - **MCP サーバー** — Model Context Protocol 経由で5つのツールを提供
-- **Claude Code Skills** — 5つのスラッシュコマンド（`/arch-check`、`/arch-snapshot` 等）
+- **Claude Code Skills** — 6つのスラッシュコマンド（`/arch-check`、`/arch-snapshot`、`/arch-serve` 等）
 - **CI 統合** — `--ci` モード + GitHub Actions ワークフロー自動生成
 - **多言語対応** — 日本語・英語完全対応（`LANG` 環境変数から自動検出）
 - **ダーク/ライトテーマ** — localStorage で設定を永続化
@@ -333,6 +423,72 @@ archtracker serve --target src --watch
 archtracker check --target src
 ```
 
+## マルチレイヤーアーキテクチャ
+
+フロントエンド + バックエンド + 共有ライブラリなど、複数のサービスやレイヤーを持つプロジェクトを統合的に分析できます。
+
+### セットアップ
+
+プロジェクトルートに `.archtracker/layers.json` を作成：
+
+```json
+{
+  "version": "1.0",
+  "layers": [
+    {
+      "name": "Frontend",
+      "targetDir": "frontend/src",
+      "language": "javascript",
+      "color": "#58a6ff",
+      "description": "React Web App"
+    },
+    {
+      "name": "Backend",
+      "targetDir": "backend/app",
+      "language": "python",
+      "color": "#3fb950",
+      "description": "FastAPI Server"
+    }
+  ],
+  "connections": [
+    {
+      "fromLayer": "Frontend",
+      "fromFile": "api/client.ts",
+      "toLayer": "Backend",
+      "toFile": "main.py",
+      "type": "api-call",
+      "label": "REST API"
+    }
+  ]
+}
+```
+
+テンプレートの自動生成：
+
+```bash
+archtracker layers init
+```
+
+### 使い方
+
+`layers.json` が存在する場合、全コマンドが自動的にマルチレイヤーモードで動作します：
+
+```bash
+archtracker analyze --root .          # 全レイヤーを分析
+archtracker serve --root . --watch    # レイヤータブ・凸包表示付き Web ビューア
+archtracker check --root .            # クロスレイヤー差分チェック
+```
+
+各レイヤーは独立した言語設定で個別に分析され、プレフィックス付きパス（例: `Backend/worker.py`）で統合グラフにマージされます。
+
+### Web ビューアでのレイヤー表示
+
+- **レイヤータブ**: 複数選択トグルで特定レイヤーにフォーカス（Shift+クリックでソロモード）
+- **凸包グループ**: 各レイヤーが色付きの境界で視覚的にグループ化
+- **クロスレイヤーリンク**: レイヤー間接続を点線で表示（設定で切替可能）
+- **Layer Cohesion スライダー**: レイヤー内ノードの凝集度を調整
+- **差分ハイライト**: 変更を含むレイヤーの境界がハイライト
+
 ## Web ビューア
 
 インタラクティブな Web ビューアは3つの可視化モードを提供します：
@@ -343,8 +499,8 @@ archtracker check --target src
 
 - ドラッグ、ズーム、クリックでノードの依存関係を探索
 - ノードをクリックでハイライトを**ピン固定** — 他のノードをホバーして比較
-- 下部のピルでディレクトリごとにフィルタリング
-- 重力、ノードサイズ、フォントサイズ、リンク透明度を調整可能
+- 下部のピルでディレクトリごと、上部のタブでレイヤーごとにフィルタリング
+- 重力、レイヤー凝集力、ノードサイズ、フォントサイズ、リンク透明度を調整可能
 - **影響モード**: ファイルをクリックして推移的に影響を受ける全ファイルを表示
 
 ![影響シミュレーション](docs/screenshots/impact-simulation.png)
@@ -355,7 +511,7 @@ archtracker check --target src
 
 - 依存の深さを示すレイヤー型トップダウンレイアウト
 - クリックでピン固定 + 詳細パネル
-- ディレクトリベースの色分け + 凡例
+- レイヤー対応フィルタリング + コンパクト再配置
 
 ### 差分ビュー
 
@@ -363,6 +519,7 @@ archtracker check --target src
 
 - アーキテクチャ変更の色分け可視化
 - 緑=追加、赤=削除、黄=変更、青=影響
+- 変更を含むレイヤー境界のハイライト表示
 - スナップショットが存在する場合に利用可能
 
 ```bash
@@ -387,12 +544,15 @@ archtracker を MCP サーバーとして Claude Code や MCP 互換 AI エー
 
 | ツール | 説明 |
 |--------|------|
-| `generate_map` | 依存関係グラフを解析し構造化JSONで返す |
+| `generate_map` | 依存関係グラフを解析し構造化JSONで返す（プログラム用） |
+| `analyze_existing_architecture` | 包括的な人間向け分析レポート |
 | `save_architecture_snapshot` | `.archtracker/snapshot.json` にスナップショットを保存 |
 | `check_architecture_diff` | スナップショットと現在のコードを比較し影響を表示 |
 | `get_current_context` | 有効なファイルパスとアーキテクチャサマリーを取得 |
 | `search_architecture` | パス、影響範囲、重要度、孤立ファイルで検索 |
 
+`.archtracker/layers.json` が存在する場合、全ツールがマルチレイヤーモードを自動検出します。
+
 ## CLI コマンド
 
 ```
@@ -402,6 +562,8 @@ archtracker check [options]      スナップショットと現在のコード
 archtracker context [options]    アーキテクチャコンテキストを表示（AIセッション用）
 archtracker serve [options]      インタラクティブ Web ビューアを起動
 archtracker ci-setup [options]   GitHub Actions ワークフローを生成
+archtracker layers init          テンプレート layers.json を作成
+archtracker layers list          設定済みレイヤーを一覧表示
 
 オプション:
   -t, --target <dir>       対象ディレクトリ（デフォルト: "src"）
@@ -417,6 +579,8 @@ archtracker ci-setup [options]   GitHub Actions ワークフローを生成
   --lang <locale>          言語: en | ja（LANG から自動検出）
 ```
 
+> **マルチレイヤー**: `.archtracker/layers.json` が存在し `--target` が明示指定されていない場合、全コマンドが自動的にマルチレイヤー分析を使用します。`--root` でプロジェクトルートを指定してください。
+
 ## Claude Code Skills
 
 `skills/` ディレクトリをプロジェクトにコピー：
@@ -432,12 +596,16 @@ cp -r node_modules/archtracker-mcp/skills/ .claude/skills/
 | `/arch-snapshot` | 現在のアーキテクチャスナップショットを保存 |
 | `/arch-context` | 有効なファイルパスでAIセッションを初期化 |
 | `/arch-search` | アーキテクチャ検索（パス、影響、重要度、孤立） |
+| `/arch-serve` | インタラクティブ Web ビューアを起動 |
+
+全スキルがマルチレイヤープロジェクトに自動対応します。
 
 ## プログラマティック API
 
 ```typescript
 import {
   analyzeProject,
+  analyzeMultiLayer,
   saveSnapshot,
   loadSnapshot,
   computeDiff,
@@ -445,9 +613,16 @@ import {
   formatAnalysisReport,
 } from "archtracker-mcp";
 
-// 分析
+// 単一ディレクトリ分析
 const graph = await analyzeProject("src", { exclude: ["__tests__"] });
 
+// マルチレイヤー分析
+const layers = [
+  { name: "Frontend", targetDir: "frontend/src", language: "javascript" },
+  { name: "Backend", targetDir: "backend/app", language: "python" },
+];
+const multi = await analyzeMultiLayer(".", layers);
+
 // スナップショット
 const snapshot = await saveSnapshot(".", graph);
 

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/bin.ts
-var CLI_COMMANDS = ["init", "analyze", "check", "context", "serve", "ci-setup", "help"];
+var CLI_COMMANDS = ["init", "analyze", "check", "context", "serve", "ci-setup", "layers", "help"];
 var CLI_FLAGS = ["--help", "-h", "--version", "-V"];
 var args = process.argv.slice(2);
 var hasCommand = args.some((arg) => CLI_COMMANDS.includes(arg));

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/bin.ts"],"sourcesContent":["/**\n * Smart entry point for `archtracker-mcp` binary.\n *\n * - If CLI subcommands are detected (serve, analyze, init, etc.) → run CLI\n * - Otherwise → start MCP server on stdio\n *\n * This allows both:\n *   npx archtracker-mcp                          → MCP server\n *   npx archtracker-mcp serve --target src        → Web viewer (CLI mode)\n *   npx archtracker-mcp analyze --target src      → Analysis report (CLI mode)\n */\n\nconst CLI_COMMANDS = [\"init\", \"analyze\", \"check\", \"context\", \"serve\", \"ci-setup\", \"help\"];\nconst CLI_FLAGS = [\"--help\", \"-h\", \"--version\", \"-V\"];\n\nconst args = process.argv.slice(2);\nconst hasCommand = args.some((arg) => CLI_COMMANDS.includes(arg));\nconst hasFlag = args.some((arg) => CLI_FLAGS.includes(arg));\n\nif (hasCommand || hasFlag) {\n  await import(\"./cli/index.js\");\n} else {\n  await import(\"./mcp/index.js\");\n}\n\nexport {};\n"],"mappings":";;;AAYA,IAAM,eAAe,CAAC,QAAQ,WAAW,SAAS,WAAW,SAAS,YAAY,MAAM;AACxF,IAAM,YAAY,CAAC,UAAU,MAAM,aAAa,IAAI;AAEpD,IAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AACjC,IAAM,aAAa,KAAK,KAAK,CAAC,QAAQ,aAAa,SAAS,GAAG,CAAC;AAChE,IAAM,UAAU,KAAK,KAAK,CAAC,QAAQ,UAAU,SAAS,GAAG,CAAC;AAE1D,IAAI,cAAc,SAAS;AACzB,QAAM,OAAO,gBAAgB;AAC/B,OAAO;AACL,QAAM,OAAO,gBAAgB;AAC/B;","names":[]}
+{"version":3,"sources":["../src/bin.ts"],"sourcesContent":["/**\n * Smart entry point for `archtracker-mcp` binary.\n *\n * - If CLI subcommands are detected (serve, analyze, init, etc.) → run CLI\n * - Otherwise → start MCP server on stdio\n *\n * This allows both:\n *   npx archtracker-mcp                          → MCP server\n *   npx archtracker-mcp serve --target src        → Web viewer (CLI mode)\n *   npx archtracker-mcp analyze --target src      → Analysis report (CLI mode)\n */\n\nconst CLI_COMMANDS = [\"init\", \"analyze\", \"check\", \"context\", \"serve\", \"ci-setup\", \"layers\", \"help\"];\nconst CLI_FLAGS = [\"--help\", \"-h\", \"--version\", \"-V\"];\n\nconst args = process.argv.slice(2);\nconst hasCommand = args.some((arg) => CLI_COMMANDS.includes(arg));\nconst hasFlag = args.some((arg) => CLI_FLAGS.includes(arg));\n\nif (hasCommand || hasFlag) {\n  await import(\"./cli/index.js\");\n} else {\n  await import(\"./mcp/index.js\");\n}\n\nexport {};\n"],"mappings":";;;AAYA,IAAM,eAAe,CAAC,QAAQ,WAAW,SAAS,WAAW,SAAS,YAAY,UAAU,MAAM;AAClG,IAAM,YAAY,CAAC,UAAU,MAAM,aAAa,IAAI;AAEpD,IAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AACjC,IAAM,aAAa,KAAK,KAAK,CAAC,QAAQ,aAAa,SAAS,GAAG,CAAC;AAChE,IAAM,UAAU,KAAK,KAAK,CAAC,QAAQ,UAAU,SAAS,GAAG,CAAC;AAE1D,IAAI,cAAc,SAAS;AACzB,QAAM,OAAO,gBAAgB;AAC/B,OAAO;AACL,QAAM,OAAO,gBAAgB;AAC/B;","names":[]}