dep-graph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dependency Graph

依赖图谱

프로젝트 내 파일 간 import 의존성을 분석하여 vis-network 기반 인터랙티브 HTML 보고서를 생성합니다.

핵심 원칙:

노드 단위: 파일 (범용적, 구현 단순)
추출: Python 스크립트 우선, 수동 분석 폴백
시각화: vis-network CDN (단일 파일, 물리 내장)
색상: 최상위 디렉토리 기반 자동 배정 (12색 팔레트)

分析项目内文件之间的import依赖关系，生成基于vis-network的交互式HTML报告。

核心原则:

节点单位：文件（通用、实现简单）
提取：优先使用Python脚本，手动分析作为备选
可视化：使用vis-network CDN（单文件、内嵌资源）
颜色：基于顶级目录自动分配（12色调色板）

Quick Reference

快速参考

bash

/dep-graph                          # 현재 디렉토리 전체
/dep-graph --scope=src/             # 특정 디렉토리만
/dep-graph --depth=2                # import 깊이 제한
/dep-graph --exclude="**/*.test.*"  # 테스트 파일 제외

bash

/dep-graph                          # 当前整个目录
/dep-graph --scope=src/             # 仅特定目录
/dep-graph --depth=2                # 限制导入深度
/dep-graph --exclude="**/*.test.*"  # 排除测试文件

Instructions

使用说明

Phase 0: 스크립트 실행 (권장)

阶段0：执行脚本（推荐）

Python3가 설치되어 있으면 스크립트로 전체 파이프라인을 실행한다.

bash

python3 {SKILL_DIR}/scripts/build-graph.py \
  --root {PROJECT_ROOT} \
  --template {SKILL_DIR}/templates/report.html \
  --output dep-graph.html \
  [--scope {scope}] [--depth {depth}] [--exclude {pattern}]

```
{SKILL_DIR}
```
: 이 스킬의 디렉토리 경로 (SKILL.md가 있는 곳)
```
{PROJECT_ROOT}
```
: 분석 대상 프로젝트 루트
인자는 사용자 입력(
```
--scope
```
,
```
--depth
```
,
```
--exclude
```
)이 있으면 전달

스크립트가 성공하면 Phase 4-4 결과 보고로 바로 이동. 실패 시 Phase 1부터 수동 진행.

若已安装Python3，可通过脚本运行完整流程。

bash

python3 {SKILL_DIR}/scripts/build-graph.py \
  --root {PROJECT_ROOT} \
  --template {SKILL_DIR}/templates/report.html \
  --output dep-graph.html \
  [--scope {scope}] [--depth {depth}] [--exclude {pattern}]

```
{SKILL_DIR}
```
：本技能的目录路径（SKILL.md所在位置）
```
{PROJECT_ROOT}
```
：待分析项目的根目录
若有用户输入参数（
```
--scope
```
,
```
--depth
```
,
```
--exclude
```
），请一并传入

脚本执行成功后，直接跳至阶段4-4 结果报告。若执行失败，则从阶段1开始手动操作。

Phase 1: 스코프 및 언어 감지 (수동 폴백)

阶段1：范围与语言检测（手动备选）

1-1. 대상 파일 수집

bash

undefined

1-1. 收集目标文件

bash

undefined

scope 인자 해석

解析--scope参数

--scope=<path> → 해당 경로 하위 (없으면) → 현재 작업 디렉토리 전체


Glob으로 소스 파일 수집:

**/.{ts,tsx,js,jsx,mjs,cjs} → TypeScript/JavaScript **/.java → Java **/.py → Python **/.go → Go **/*.rs → Rust


`--exclude` 인자가 있으면 해당 패턴 제외. 기본 제외:
- `node_modules/`, `vendor/`, `build/`, `dist/`, `.git/`
- `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`

**1-2. 언어 판별**

확장자 빈도 기준 주 언어 결정. 혼합 프로젝트는 모든 언어 처리.

**1-3. depth 제한**

`--depth=N` 지정 시, 스코프 루트로부터 N단계까지만 따라감. 기본값: 무제한.

---

--scope=<path> → 该路径下的文件（无参数时） → 当前工作目录下的所有文件


通过Glob语法收集源文件：

**/.{ts,tsx,js,jsx,mjs,cjs} → TypeScript/JavaScript **/.java → Java **/.py → Python **/.go → Go **/*.rs → Rust


若传入`--exclude`参数，则排除匹配模式的文件。默认排除：
- `node_modules/`, `vendor/`, `build/`, `dist/`, `.git/`
- `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`

**1-2. 语言判定**

根据文件扩展名的出现频率确定主要语言。混合项目则处理所有涉及的语言。

**1-3. 深度限制**

若指定`--depth=N`，则仅跟踪从范围根目录开始的N层导入。默认值：无限制。

---

Phase 2: 의존성 추출

阶段2：提取依赖关系

언어별 패턴 파일 참조하여 import문 추출.

2-1. ast-grep 시도 (우선)

ast-grep이 설치되어 있으면 (

which ast-grep

) 정확한 AST 기반 추출:

bash

undefined

参考各语言对应的模式文件提取import语句。

2-1. 尝试使用ast-grep（优先）

若已安装ast-grep（执行

which ast-grep

可检查），则基于AST进行精准提取：

bash

undefined

ast-grep으로 import문 검색

使用ast-grep搜索import语句

ast-grep --pattern '<PATTERN>' --json <file>


언어별 패턴은 resources/patterns/ 참조:
- TypeScript/JavaScript → `resources/patterns/typescript.md`
- Java → `resources/patterns/java.md`

**2-2. grep 폴백**

ast-grep 미설치 시 정규식 기반 추출:

```bash

ast-grep --pattern '<PATTERN>' --json <file>


各语言对应的模式可参考resources/patterns/：
- TypeScript/JavaScript → `resources/patterns/typescript.md`
- Java → `resources/patterns/java.md`

**2-2. 备选方案：使用grep**

若未安装ast-grep，则基于正则表达式提取：

```bash

TypeScript/JavaScript

grep -nE "^import .+ from ['"]|require(['"]" <file>

Java

grep -nE "^import (static )?[a-zA-Z]" <file>

Python

grep -nE "^(from .+ import|import )" <file>

Go

grep -nE ""[a-zA-Z0-9_/.-]+"" <file> # import block 내부


**2-3. 경로 해석**

추출된 import 경로를 실제 파일 경로로 매핑:

| 유형 | 처리 |
|------|------|
| 상대 경로 (`./`, `../`) | 현재 파일 기준 resolve, 확장자 탐색 |
| 별칭 (alias) | tsconfig.json `paths`, webpack alias 등 읽어서 매핑 |
| 패키지/외부 | `external` 노드로 그룹화 (선택 표시) |
| 배럴 (`index.ts`) | 디렉토리 import 시 `index.*` 자동 탐색 |

**확장자 탐색 순서** (TypeScript):
`.ts` → `.tsx` → `.js` → `.jsx` → `/index.ts` → `/index.tsx` → `/index.js`

---

grep -nE ""[a-zA-Z0-9_/.-]+"" <file> # 仅在import块内


**2-3. 路径解析**

将提取的import路径映射为实际文件路径：

| 类型 | 处理方式 |
|------|----------|
| 相对路径 (`./`, `../`) | 基于当前文件解析，自动查找扩展名 |
| 别名 (alias) | 读取tsconfig.json的`paths`、webpack alias等进行映射 |
| 包/外部依赖 | 归为`external`节点组（可选择显示） |
| 桶文件 (`index.ts`) | 导入目录时自动查找`index.*` |

**扩展名查找顺序**（TypeScript）：
`.ts` → `.tsx` → `.js` → `.jsx` → `/index.ts` → `/index.tsx` → `/index.js`

---

Phase 3: 그래프 데이터 구성

阶段3：构建图谱数据

3-1. 데이터 구조 생성

javascript

const GRAPH_DATA = {
  nodes: [
    { id: "src/api/user.ts", label: "user.ts", group: "api", title: "src/api/user.ts\nImports: 3\nImported by: 5" }
  ],
  edges: [
    { from: "src/api/user.ts", to: "src/models/User.ts", arrows: "to" }
  ],
  groups: {
    "api": { color: "#4FC3F7" },
    "models": { color: "#81C784" }
  },
  stats: {
    totalFiles: 42,
    totalEdges: 87,
    avgDependencies: 2.07,
    maxFanOut: { file: "src/index.ts", count: 12 },
    maxFanIn: { file: "src/utils/helpers.ts", count: 15 },
    circular: [["src/a.ts", "src/b.ts", "src/a.ts"]],
    externalDeps: ["react", "lodash"]
  }
};

3-2. 노드 속성

```
id
```
: 스코프 루트 상대 경로
```
label
```
: 파일명만 (디렉토리 없이)
```
group
```
: 최상위 디렉토리명 (색상 그룹)
```
title
```
: 호버 시 표시할 상세 정보
```
size
```
: fan-in 비례 (참조 많을수록 큼)

3-3. 색상 팔레트 (12색 순환)

javascript

const PALETTE = [
  "#4FC3F7", "#81C784", "#FFB74D", "#E57373",
  "#BA68C8", "#4DD0E1", "#FFD54F", "#A1887F",
  "#90A4AE", "#F06292", "#AED581", "#7986CB"
];

최상위 디렉토리 등장 순서대로 배정.

3-4. 순환 참조 탐지

DFS로 사이클 탐지. 발견된 사이클은

stats.circular

에 기록.

3-1. 创建数据结构

javascript

const GRAPH_DATA = {
  nodes: [
    { id: "src/api/user.ts", label: "user.ts", group: "api", title: "src/api/user.ts\nImports: 3\nImported by: 5" }
  ],
  edges: [
    { from: "src/api/user.ts", to: "src/models/User.ts", arrows: "to" }
  ],
  groups: {
    "api": { color: "#4FC3F7" },
    "models": { color: "#81C784" }
  },
  stats: {
    totalFiles: 42,
    totalEdges: 87,
    avgDependencies: 2.07,
    maxFanOut: { file: "src/index.ts", count: 12 },
    maxFanIn: { file: "src/utils/helpers.ts", count: 15 },
    circular: [["src/a.ts", "src/b.ts", "src/a.ts"]],
    externalDeps: ["react", "lodash"]
  }
};

3-2. 节点属性

```
id
```
：相对于范围根目录的路径
```
label
```
：仅文件名（不含目录）
```
group
```
：顶级目录名称（用于颜色分组）
```
title
```
：鼠标悬停时显示的详细信息
```
size
```
：与fan-in成正比（被引用次数越多，节点越大）

3-3. 12色循环调色板

javascript

const PALETTE = [
  "#4FC3F7", "#81C784", "#FFB74D", "#E57373",
  "#BA68C8", "#4DD0E1", "#FFD54F", "#A1887F",
  "#90A4AE", "#F06292", "#AED581", "#7986CB"
];

按顶级目录出现的顺序分配颜色。

3-4. 循环引用检测

通过DFS算法检测循环。检测到的循环将记录在

stats.circular

中。

Phase 4: HTML 리포트 생성

阶段4：生成HTML报告

4-1. 템플릿 로딩

templates/report.html

파일을 Read로 읽는다.

4-2. 데이터 주입

템플릿 내

{{GRAPH_DATA}}

플레이스홀더를 Phase 3에서 구성한 JSON으로 교체.

</script>

문자열이 포함되면 HTML 파싱이 깨지므로 반드시 이스케이프:

javascript

const jsonStr = JSON.stringify(GRAPH_DATA)
  .replace(/</g, '\\u003c')
  .replace(/>/g, '\\u003e');
template.replace('{{GRAPH_DATA}}', jsonStr);

4-3. 파일 출력

dep-graph.html    # 프로젝트 루트에 생성

4-4. 결과 보고

생성 완료 후 사용자에게 보고:

undefined

4-1. 加载模板

读取

templates/report.html

文件。

4-2. 注入数据

将模板中的

{{GRAPH_DATA}}

占位符替换为阶段3中构建的JSON数据。

若JSON中包含

</script>

字符串，会导致HTML解析失败，因此必须进行转义：

javascript

const jsonStr = JSON.stringify(GRAPH_DATA)
  .replace(/</g, '\\u003c')
  .replace(/>/g, '\\u003e');
template.replace('{{GRAPH_DATA}}', jsonStr);

4-3. 输出文件

dep-graph.html    # 生成在项目根目录下

4-4. 结果报告

生成完成后，向用户报告结果：

undefined

Dependency Graph Report

依赖图谱报告

파일:
```
dep-graph.html
```
노드: {totalFiles}개 파일
엣지: {totalEdges}개 의존성
평균 의존성: {avgDependencies}
최대 Fan-out: {maxFanOut.file} ({maxFanOut.count})
최대 Fan-in: {maxFanIn.file} ({maxFanIn.count})
순환 참조: {circular.length}개 발견
외부 패키지: {externalDeps.length}개

브라우저에서

dep-graph.html

을 열어 확인하세요.


순환 참조가 있으면 경고와 함께 사이클 경로 표시.

文件：
```
dep-graph.html
```
节点：{totalFiles}个文件
边：{totalEdges}个依赖关系
平均依赖数：{avgDependencies}
最大Fan-out：{maxFanOut.file}（{maxFanOut.count}次）
最大Fan-in：{maxFanIn.file}（{maxFanIn.count}次）
循环引用：检测到{circular.length}个
外部依赖：{externalDeps.length}个

请在浏览器中打开

dep-graph.html

查看详情。


若存在循环引用，需同时显示警告及循环路径。

Output Format

输出格式

단일 HTML 파일 (

dep-graph.html

). 브라우저에서 열면:

사이드바: 검색, 디렉토리 필터, 통계, 노드 상세
툴바: Reset / Physics 토글 / External 토글 / Circular 하이라이트
인터랙션: 클릭→연결 하이라이트, 더블클릭→포커스, 드래그 이동
테마:
```
prefers-color-scheme
```
자동 (dark/light)

单HTML文件（

dep-graph.html

）。在浏览器中打开后可看到：

侧边栏：搜索、目录筛选、统计信息、节点详情
工具栏：重置 / 物理效果切换 / 外部依赖切换 / 循环引用高亮
交互功能：点击→高亮关联节点、双击→聚焦节点、拖拽移动
主题：根据
```
prefers-color-scheme
```
自动切换（深色/浅色）

Technical Details

技术细节

스크립트:

scripts/build-graph.py

Python 3.10+ 필요 (표준 라이브러리만 사용, 외부 의존성 없음)
지원 언어: Java, TypeScript/JavaScript, Python
Java source root 자동 탐색 (
```
**/src/main/java
```
)
Java 내부 패키지 자동 판별 (source root의 top-level 패키지 수집)
tsconfig.json
```
compilerOptions.paths
```
alias 자동 읽기 (JSONC 지원)
순환 참조 탐지 (iterative DFS, 대규모 프로젝트 안전)
```
--json
```
플래그로 stats JSON 출력 (스크립트 체이닝용)
파일 읽기 실패 시 skip + stderr 경고

脚本：

scripts/build-graph.py

需要Python 3.10+（仅使用标准库，无外部依赖）
支持语言：Java、TypeScript/JavaScript、Python
自动检测Java源码根目录（
```
**/src/main/java
```
）
自动判定Java内部包（收集源码根目录下的顶级包）
自动读取tsconfig.json的
```
compilerOptions.paths
```
别名（支持JSONC）
循环引用检测（迭代式DFS，适用于大规模项目）
支持
```
--json
```
参数输出统计数据JSON（用于脚本链式调用）
读取文件失败时自动跳过并在stderr输出警告