dsh-import-graph

dsh-import-graph

DeepSeek Harness 的依赖图工具箱：build_graph 解析 JS/TS 源码的 import / require 依赖构建图，find_cycles 检测循环依赖，orphan_files 找孤立源码，influence 计算某个文件的下游影响面。支持 tsconfig/jsconfig 别名映射（如 @/），四个工具都可输出 output_format=json。只读、零运行时依赖，启发式解析而非完整 AST。

功能说明

「这个模块删掉会影响谁？」、「A 和 B 是不是循环依赖？」、「仓库里哪些文件其实没人用了？」——单看文件列表回答不了这些问题，要看文件之间的依赖关系。

本插件用启发式扫描给出四档信息，帮你把模块边界和依赖健康状况摸清楚：

• 依赖图（build_graph）：递归扫描目录里的 JS/TS 家族源码，解析 import / require / export...from / 动态 import()，构建「文件 → 它依赖的文件」的边，并统计入度 / 出度与孤立文件。
• 循环依赖（find_cycles）：在依赖图上用深度优先找环（A→B→C→A）。循环依赖常导致初始化顺序问题、命名空间污染、难以安全拆分，是代码质量的常见隐患。
• 孤立文件（orphan_files）：找出无入边（不被任何本地文件引用）且无出边（也不引用任何本地文件）的源码。这类文件可能是废弃模块、被动态加载/注册调用的入口，也可能是移出模块边界的遗留。
• 下游影响面（influence）：给定一个文件，沿「谁 import 我」的反向边遍历，列出直接依赖它、以及间接依赖它（可限 max_depth 跳数）的文件，用来评估「改这个文件会波及哪些模块」。

四个工具都支持 output_format=json，输出结构化依赖数据供脚本消费；并支持 别名解析：自动探测项目根的 tsconfig.json / jsconfig.json，读取 compilerOptions.paths 与 baseUrl（JSONC 注释会被正确剥离），把 @/xxx 这类别名映射到真实本地文件、计入依赖边；也可用 aliases 参数显式传入映射。

解析是启发式的：默认只解析以 ./ ../ 开头的相对引用；配置了别名（tsconfig paths 或 aliases 参数）时，命中的别名说明符（如 @/service）也会映射到真实本地文件并计入边；其余 npm 包 / 内置模块不计为本地边。用「字符串 / 注释剥离 + 正则」近似识别语句，不是完整 AST，个别边界可能不精确，但用于结构判断足够。

安装

npm install dsh-import-graph

安装后在 cordis.patch.yml 中加入：

- insert:
    - id: import-graph
      name: "dsh-import-graph"

使用说明

build_graph

解析目录（或单个文件）的依赖关系，输出依赖边与出入度统计。path 传目录或文件；exclude 逗号分隔排除子串；show_edges 控制列出多少条边。

扫描路径：./src（排除 node_modules）
代码文件 6 个；依赖边 7 条；孤立文件 1 个
依赖边（前 5 / 共 7条）：
1. src/a.js → src/b.js
2. src/a.js → src/util.js
3. src/b.js → src/c.js
4. src/cycle1.js → src/cycle2.js
5. src/cycle2.js → src/cycle1.js
孤立文件（无入边且无出边，共 1）：
  - src/e.js
说明：依赖解析为启发式（字符串/注释剥离 + 正则），非完整 AST；npm 包与内置模块不计入本地边。

参数：path（必填）；exclude；max_files（默认 500）；max_size（默认 10240 KB）；show_edges（默认 20）；max_chars。

用户：这个 src 目录里文件都互相依赖谁，画个清单

助手：调用 build_graph，path=src、exclude=node_modules，输出依赖边与孤立文件

用户：删掉 util.js 会影响哪些文件

助手：调用 build_graph，看 util.js 的入边（谁依赖它）

find_cycles

在依赖图上检测循环依赖，每个环输出一条 A→B→C→A 链路。同一个环即使多次出现在栈中也只输出一次（按规范化键去重）。

扫描路径：./src；代码文件 6 个
发现循环依赖 1 个（前 1）：
1. src/cycle1.js → src/cycle2.js → src/cycle1.js
提示：打破循环可先分析环中各边，常从「依赖最轻/最稳定」的节点切断。

参数：path（必填）；exclude；max_files / max_size；top（默认 5）；max_chars。

用户：这个模块有循环依赖吗，是哪几处

助手：调用 find_cycles，path=src，列出所有环

orphan_files

找出既不被任何本地文件引用、也不引用任何本地文件的孤立源码。

扫描路径：./src；代码文件 6 个
孤立文件（无入边且无出边，共 1）：
1. src/e.js
说明：仅统计本地相对依赖；若文件经动态加载/插件注册/构建工具引用，可能为误报。

参数：path（必填）；exclude；max_files / max_size；top（默认 5）；max_chars。

用户：仓库里哪些文件其实没人用了

助手：调用 orphan_files，path=src，列出孤立文件

influence

给定一个文件，输出它的下游影响面：直接依赖它（↑）与间接依赖它（⇢）的文件。可设 max_depth 限制间接跳数（默认 0 = 不限）。

扫描路径：./src
目标文件：src/base.js
直接依赖它的文件（2）：
  ↑ src/core.js
  ↑ src/util.js
间接依赖它的文件（1）：
  ⇢ src/app.js
下游影响面合计：3 个文件
说明：沿「谁 import 我」的反向边遍历；若经动态加载/构建工具引用可能漏计。

参数：path（目录）；file（目标，相对/绝对/唯一文件名）；exclude；max_depth（默认 0 不限）；aliases / tsconfig；output_format（text/json）；max_files / max_size / max_chars。

用户：改 src/base.js 会波及哪些文件

助手：调用 influence，file=src/base.js，看直接与间接下游

用户：只看直接依赖 base 的模块

助手：调用 influence，file=src/base.js、max_depth=0（只取直接层）

典型场景

• 删除前影响面评估：删 / 移动一个文件前，用 influence 看它的全部下游（直接 + 间接），或 build_graph 看入边，避免改一个炸一片。
• 循环依赖治理：find_cycles 全量找出环，逐条分析切断点，配合重构把 A↔B 拆成单向依赖。
• 废弃代码清理：orphan_files 定位「无入无出」的文件，确认后清理或标记废弃。
• 模块边界梳理：新接手一个库，先 build_graph 整体依赖图，理解核心 / 外围模块。
• 重构验证：拆分模块后重跑 build_graph，确认环数量下降、依赖方向变清晰。
• 文档生成辅助：把 build_graph 的边列表喂给绘图工具，生成依赖可视化。
• CI 门禁：对核心目录跑 find_cycles，出现环即告警，防止循环依赖回流。

安全边界

• 只读：四个工具都不写入、不修改、不删除文件；只读取源码做文本扫描。
• 不访问网络：依赖解析全部在本地完成，无任何外部请求，也不外发源码。
• 不执行代码：只做文本扫描与字符串 / 注释剥离，不 eval、不运行被测代码。
• 跳过无关内容：默认跳过 node_modules / .git / dist / build / coverage 与隐藏目录；二进制与超过 max_size 的文件不解析；max_files 限流。
• 启发式结论，非权威：解析相对引用与已配置别名的说明符，未配置别名的 npm 包 / 裸模块 / 内置模块不计为本地边；字符串 / 注释剥离用正则近似，个别边界可能误识别。别名解析基于 tsconfig paths 的近似映射，不解析通配的多目标优先级或运行时动态别名。结果用于结构判断，不应作为唯一裁决依据。
• 动态加载误报：经 import() 变量路径、插件注册、构建工具字符串引用加载的文件可能被漏报为孤立，orphan_files 已提示此风险。

其他插件集成说明

协作插件	集成方式
dsh-code-metrics	import-graph 看依赖影响面，metrics 看体量 / 复杂度，互补定位重构目标
dsh-code-check	有环或孤立文件时用 code-check 检查相关文件的具体 lint 问题
dsh-deps-audit	import-graph 管本地模块依赖，deps-audit 管 lock 文件里的外部依赖，双层治理
dsh-template-render	用模板把依赖边列表渲染成 Markdown / 报告
dsh-chart-ascii	把各模块出入度画成条形图，直观对比依赖热度
dsh-test-report	拆环 / 清孤立后跑测试，确认没有回归

版本说明

• 0.2.0（2026-11-03）：影响面、别名与 JSON 输出。
  • 新增 influence：给定文件，沿反向边输出直接 / 间接依赖它的文件（可限 max_depth 跳数），评估改动波及面
  • 别名解析：自动探测 tsconfig.json / jsconfig.json 的 compilerOptions.paths + baseUrl（JSONC 注释安全剥离），把 @/xxx 映射到真实本地文件计入依赖边；也可用 aliases 参数显式传入；tsconfig=off 关闭探测
  • build_graph / find_cycles / orphan_files / influence 支持 output_format=json，输出结构化数据供脚本消费
  • 别名前缀按最长优先匹配；influence 目标文件支持相对路径、绝对路径或唯一文件名定位
• 0.1.0（2026-10-08）：初始版本。
  • build_graph：递归扫描目录，解析 import / require / export...from / 动态 import()，构建依赖边 + 出入度统计 + 孤立文件；默认跳过常见噪声目录
  • find_cycles：DFS 环检测，按规范化键去重，输出 A→B→C→A 链路
  • orphan_files：找出无入边且无出边的孤立源码
  • 说明符解析：相对引用补齐扩展名（js/jsx/mjs/cjs/ts/tsx）与目录 index；裸说明符（npm 包 / 别名 / 内置）不计为本地边
  • 字符串 / 模板 / 注释先剥离再做关键字识别，避免误匹配
  • 只读、二进制拒绝、多层上限

RoadMap

v0.2（已完成）

• ✅ 新增 influence：给定一个文件，输出它的下游影响面（直接 / 间接依赖它的文件）
• ✅ 支持解析别名（如 @/ ~/）与 tsconfig paths，把别名映射到真实相对路径
• ✅ 四个工具输出可选 output_format=json，便于脚本消费依赖图

v0.3（计划）

• 增加 subgraph：只导出某模块为根的子图，聚焦局部依赖
• 增加环的「切断建议」：按入度 / 稳定度给每环推荐切边
• 支持更多语言（Python import、Go import）的相对依赖解析

v0.4（展望）

• 别名解析支持 paths 多目标优先级与 monorepo workspace 映射
• influence 提供「按跳数分组」的分层视图（第 1 跳 / 第 2 跳…）
• 输出 JSON schema 版本化，供流水线稳定解析

FAQ

Q：为什么 npm 包（如 react）不算依赖边？ 只解析以 ./ ../ 开头的相对引用，因为 npm 包 / 别名 / 内置模块解析需要 node_modules 与配置，超出本插件的只读、零依赖边界。所以边表示「本地文件之间的结构关系」。

Q：import './util' 没有扩展名怎么解析？ 启发式尝试补齐扩展名：依次试 .js .jsx .mjs .cjs .ts .tsx，若指向目录则试 index.js 等。优先取第一个在扫描文件集合中命中的。

Q：循环依赖检测准吗？ DFS 环检测是标准的、准确的（给定正确的边）。边本身来自启发式解析，个别复杂 import 形态可能漏一条边，从而漏掉对应环；识别出的环都是真实存在的。

Q：同一个环为什么不会重复输出？ 一个环从不同节点进入栈会出现多次。本插件把环「旋转到最小起点」并规范化成唯一键去重，每个环只输出一次。

Q：孤立文件一定是废弃代码吗？ 不一定。可能被 import() 变量路径、插件注册、构建工具的字符串引用动态调用。orphan_files 只报告「无入无出」，是否删除需结合业务判断。

Q：为什么跳过 node_modules？ node_modules 数量大、多为第三方，解析无意义且拖慢。dist / build / coverage 同理。需要分析这些目录时用 exclude 反向指定即可（默认名单可整体绕过，但一般不推荐）。

Q：会执行我的代码吗？ 不会。只读文本扫描 + 字符串 / 注释剥离 + 正则识别，不 eval、不加载、不运行任何被测文件。

Q：目录很大会不会卡？ max_files（默认 500）限流扫描数量，max_size（默认 10240 KB）跳过超大文件，二进制文件不解析。