g0GobliN/reality-map

## 它能做什么 大多数代码库的增长速度超过了任何人的理解能力。`reality-map` 为您提供即时视觉概览——模块、依赖项、循环、耦合中心——并允许您深入到单个文件和函数。 ## 功能 ### 🗺 交互式架构图 整个项目的实时、可缩放的图形——模块、服务、数据库及其连接——在浏览器中以全交互方式渲染。 **第一阶段 · 交互** - **边缘聚焦模式** — 悬停在任意节点上以突出显示其连接的边缘；无关的边缘变为几乎不可见 - **路径高亮** — 点击一个节点以锁定焦点；其邻居发光，其他一切变为 20% 透明度；再次点击或点击画布以取消选择 - **边缘过滤** — 切换边缘视图：`all`（所有内容）、`warn`（接触循环依赖模块的边缘）、`hot`（具有 ≥ 3 个导入的边缘）、`clean`（无警告和轻量级）；至少有一个过滤器始终处于活动状态 **第二阶段 · 聚类** - **领域聚类** — 节点根据顶级路径段（例如 `src`、`lib`、`api`）自动分组，每个组都显示为半透明的组背景 - **折叠和展开** — 点击聚类切换药丸以折叠组为单个摘要卡片；集群间的边缘自动重路由和去重；再次点击卡片以展开 - **聚类聚焦** — 第二次点击聚类药丸以隔离该聚类中的节点；再次点击以返回完整图形 - **聚类指标** — 每个折叠的聚类卡片显示聚合的模块计数和警告计数 **第三阶段 · 布局与抽象** - **多种布局** — 在三种命名安排之间切换： - `server` — 服务器计算的定位（默认，保留模块层次结构） - `radial` — 节点均匀地围绕一个圆圈排列 - `force` — 有机散布，保留聚类邻近性 - **平滑过渡** — 切换布局或切换聚类触发 `fitView` 动画，以便始终保留上下文 - **持久布局** — 您最后使用的布局保存在 `localStorage` 中，并在下次打开时恢复 **核心图形功能** - 模块级图形，具有可配置的深度（1–5） - **深度 2+ 的层次布局** — 节点根据顶级文件夹（例如 `src/`、`packages/` 等）分组到水平条中，以便视觉层次结构始终与您的目录树匹配；深度 1 仅显示顶级文件夹作为单个节点 - **双击钻入** — 放大任何模块以查看其子模块，然后是文件，然后是符号；使用 **后退** 导航回上一层 - 拖动节点以重新排列，自由平移和缩放 - 动画边缘显示导入方向和权重 - 循环检测——循环依赖项以玫瑰色突出显示

### 💥 变更影响分析（新功能） 输入任何文件路径→立即看到： - 可能会损坏的每个文件（直接 + 间接） - 每个受影响文件的风险评分（1–10） - 模块级爆炸半径摘要 - 色彩编码：高 / 中 / 低风险 ### 🏥 代码库健康评分（新功能） 一个 0–100 的单一评分，基于字母等级（A–F）： - 循环依赖项计数 - 隔离文件比率 - 超大文件（>500 LOC） - 高度耦合的中心 包括一个 **可复制 README 徽章**： ```  ```

### 🧹 死代码与不可达文件检测 找到可能未使用的文件——根据置信度评分，而不仅仅是“0 导入者”： - 没有内部导入者 - 不是入口点、测试或配置文件 - 置信度评分基于多个信号 - 显示潜在的 LOC 节省 **不可达文件分析** — 跟踪哪些源文件无法从您的命名入口点（例如 `src/index.ts`、`src/main.ts`）通过任何导入路径到达。通过图遍历确定性而不是启发式方法补充死代码检测。 ``` # 报告 src/ 中无法访问的文件从入口点 npx reality-map --unreachable-files src # 以 JSON 格式输出（用于 CI / 脚本） npx reality-map --unreachable-files-json src ```

### 📦 依赖智能（新功能） 对您的 `package.json` 进行完整本地分析——无需注册上传，安装后即可离线工作。 **未使用检测** — 声明但从未在源中导入的包被标记为 `unused`。仅在配置文件（`eslint.config.js`、`vite.config.ts` 等）中找到的包被标记为 `config-only`，这是一种独特且有效的使用模式。 **过时包** — 使用 `npm outdated` 检测陈旧版本，然后对差距进行分类： **已弃用包** — 直接从 `node_modules/[pkg]/package.json` 读取 `deprecated` 字段——完全离线，无需注册调用。 | 信号 | 评分 | | ---------------------- | ------ | | 严重漏洞 | +4 | | 高漏洞 | +3 | | 中等漏洞 | +2 | | 低漏洞 | +0.5 | | 已弃用 | +2 | | 未使用（运行时依赖） | +1 | | 主版本落后 | +1.5 | | 次版本落后 | +0.5 | **包详细抽屉** — 点击任何包以查看：导入文件、漏洞详细信息（带链接）、安装版本与最新版本、风险评分分解和弃用消息。 ``` # 将依赖智能报告打印到终端 npx reality-map --deps # 以 JSON 格式输出（用于 CI / 脚本） npx reality-map --deps-json # 发现任何关键漏洞则退出 1 npx reality-map --deps --fail-on-vuln critical # 发现任何高或以上漏洞则退出 1 npx reality-map --deps --fail-on-vuln high ``` ## 使用方法 ## 忽略文件 ``` # 忽略生成的文件 src/generated/ *.generated.ts # 忽略特定目录 legacy/ ``` ## API 端点 | 端点 | 方法 | 描述 | | ---------------------------- | ------ | -------------------------------------------------------------- | | `/api/graph` | GET | 全扫描数据 | | `/api/health` | GET | 健康评分（0–100） | | `/api/impact` | POST | 变更影响 — body: `{ "paths": ["src/foo.ts"] }` | | `/api/deadcode` | GET | 死代码候选者 | | `/api/unreachable?src=` | GET | 从 `` 的入口点无法到达的文件 | | `/api/deps` | GET | 依赖智能 — 未使用、漏洞、过时、风险评分 | | `/api/search?q=` | GET | 文件搜索 | | `/api/file/:path` | GET | 文件符号 + 导入 | | `/api/rescan` | POST | 重新扫描项目 | | `/api/snapshot.html` | GET | 下载自包含的 HTML 快照 | ## 健康评分如何工作 评分等级：A（90–100）· B（80–89）· C（70–79）· D（60–69）· F（<60） ## 变更影响如何工作 1. 找到所有直接导入更改文件的文件（深度 1） 2. 找到导入这些文件的文件（深度 2、3、…） 3. 根据更改的接近度、文件大小和导入者数量对每个受影响文件进行评分 4. 按模块分组结果，以获得高级爆炸半径视图 ## 要求 ## 贡献 - 由 [Vishal Gurung](https://github.com/g0GobliN) 维护。 - 如果您使用或分享 `reality-map`，请引用作者并链接到 `https://github.com/g0GobliN/reality-map`。 - 欢迎通过拉取请求进行贡献。请首先打开一个问题来讨论较大的更改或功能请求。 - 所有更改都由维护者审查和合并。 ## 许可证 MIT © [Vishal Gurung](https://github.com/g0GobliN).

标签：多模态安全, 数据可视化, 日志审计, 自定义脚本