whobreaks (F1729)

whobreaks

在触碰文件之前，找出什么会破裂。

whobreaks 构建代码库的实时依赖关系图，并在您进行更改之前告诉您任何更改的爆炸半径。可作为人工智能编码工具的CLI、HTTP API和MCP服务器使用。

# Without whobreaks:
AI edits UserService.ts → breaks 14 files → you spend 2 hours fixing

# With whobreaks:
AI queries whobreaks first → knows 14 files depend on UserService → makes safe changes

______________________________________________________________________

快速开始

npx whobreaks .

  ╭──────────────────────────────────────╮
  │  💥 whobreaks v0.1.0                 │
  │  Scanning your codebase...           │
  ╰──────────────────────────────────────╯

  📁 Found 247 files
  ⏱️  Analyzed in 1.2s

  ┌─ Summary ──────────────────────────────┐
  │                                        │
  │  Files:              247               │
  │  Edges:            1,847               │
  │  Avg depth:          4.2               │
  │  Max depth:           11               │
  │                                        │
  └────────────────────────────────────────┘

  ⚠️  Issues Found:

  🔄 Circular Dependencies (3)
     src/services/auth.ts ↔ src/services/user.ts
     src/models/order.ts → src/models/product.ts → src/models/order.ts

  🏝️  Orphan Files — imported by nothing (12)
     src/utils/old-helpers.ts
     src/components/DeprecatedButton.tsx

  🕸️  God Modules — imported by 20+ files (2)
     src/utils/helpers.ts        → 89 dependents
     src/lib/api-client.ts       → 47 dependents

  💣 High-Impact Files — editing these affects the most files
     src/types/index.ts          → 142 files affected
     src/utils/helpers.ts        → 89 files affected

  📁 Output: .whobreaks/graph.json

______________________________________________________________________

MCP设置

whobreaks作为MCP服务器运行，因此AI工具（Claude Code、Cursor、Windsurf）可以在编辑文件之前查询它。设置一次；AI会自动使用它。

克劳德代码

claude mcp add whobreaks npx whobreaks mcp

就是这样。验证：

claude mcp list
# whobreaks: npx whobreaks mcp

光标

创建 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "whobreaks": {
      "command": "npx",
      "args": ["whobreaks", "mcp"]
    }
  }
}

VS代码（副驾驶/GitHub副驾驶聊天）

创建 .vscode/mcp.json 在项目根目录中：

{
  "servers": {
    "whobreaks": {
      "type": "stdio",
      "command": "npx",
      "args": ["whobreaks", "mcp"]
    }
  }
}

帆板运动

创建 .windsurf/mcp_config.json 在项目根目录中：

{
  "mcpServers": {
    "whobreaks": {
      "command": "npx",
      "args": ["whobreaks", "mcp"]
    }
  }
}

______________________________________________________________________

告诉AI使用它（CLAUDE.md/.cursorules）

把这个放在你的 CLAUDE.md 或 .cursorrules:

## Architectural awareness

This project has whobreaks running as an MCP server.

Before editing any file, call:
- `get_impact` — see how many files depend on it and which exports are critical
- `get_context` — understand what it imports/exports and its risk level

Before creating a new file or moving an export, call:
- `find_related` — check if similar functionality already exists

Files with 20+ dependents are god modules — treat export changes as breaking changes.
Files in circular dependencies require extra care — changes propagate in both directions.

______________________________________________________________________

可用的MCP工具

get_impact("src/services/user.ts")
→ Editing this file will affect 14 files:
  Direct dependents (3): auth.ts, dashboard.ts, settings.ts
  Transitive (11): app.tsx, router.ts, ... +9 more
  High-usage exports: getUserById, UserSchema

get_context("src/services/user.ts")
→ ## src/services/user.ts
  Imports from (2): db/client.ts, utils/crypto.ts
  Imported by (3): auth.ts, dashboard.ts, settings.ts
  Exports: getUserById (function), UserSchema (type), updateUser (function)
  Risk level: MEDIUM (3 dependents)
  Lines: 187

______________________________________________________________________

观看模式+实时仪表板

npx whobreaks watch . --port 3001

启动文件监视器和HTTP服务器。打开 http://localhost:3001 用于交互式依赖关系图仪表板。

文件更改时，仪表板会自动重新加载。每个节点的大小按依赖计数确定，按风险着色，并可点击以查看完整的影响分析面板。

______________________________________________________________________

HTTP API

运行时可用 whobreaks watch 或 whobreaks . --port .

______________________________________________________________________

输出文件

每次扫描都会写入 .whobreaks/ 在项目根目录中：

添加 .whobreaks/ 到 .gitignore 或承诺 summary.md 作为活的文件。

______________________________________________________________________

命令

npx whobreaks [path]              # One-shot scan (default: current directory)
npx whobreaks watch [path]        # Watch mode + HTTP API + dashboard
npx whobreaks mcp                 # MCP server (uses current directory)

选项：

______________________________________________________________________

运作原理

┌─────────────────────────────────────────────────┐
│                  whobreaks                       │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│  │  Watcher  │→│ Analyzer  │→│  Graph Store  │  │
│  │(chokidar) │ │ (regex)   │ │ (in-memory)   │  │
│  └──────────┘  └──────────┘  └──────────────┘  │
│                                     │           │
│                          ┌──────────┴────┐      │
│                          │               │      │
│                    ┌─────▼──┐    ┌───────▼──┐   │
│                    │  CLI   │    │ MCP/HTTP  │   │
│                    │ Output │    │  Server   │   │
│                    └────────┘    └──────────┘   │
│                                                  │
│              ┌──────────────────┐                │
│              │  Web Dashboard   │                │
│              │ (D3 force graph) │                │
│              └──────────────────┘                │
└─────────────────────────────────────────────────┘

• 观察者 — 监视器 手表 **/*.{ts,tsx,js,jsx}，消除快速变化
• 分析器 --基于正则表达式的原始源文本导入/导出提取。删除评论、摘录 import/export 语句，通过以下方式解析说明符 tsconfig.json 路径、工作区包名和文件系统探测。没有编译器开销——在约2.5秒内扫描2500个文件。
• 图形存储 --在记忆中 Map 具有正向和反向索引。文件更改时的增量更新。
• MCP服务器 — @模型上下文协议/sdk 将图形暴露给Claude Code、Cursor、Windsurf和任何兼容MCP的客户端。
• 仪表盘 --单个HTML文件，D3强制导向图，由内置的HTTP服务器提供服务。无构建步骤。

______________________________________________________________________

与替代品相比

whobreaks： npx whobreaks . -没有Docker，没有API密钥，没有数据库。零配置。

______________________________________________________________________

发展

git clone https://github.com/f1729/whobreaks
cd whobreaks
npm install
npm run build
node dist/index.js .

npm run dev    # tsc --watch

______________________________________________________________________

许可证

麻省理工学院