coderaph

v0.3.0

Published

11 days ago

TypeScript dependency graph 3D visualizer

0High
0Medium
0Low

yoonho_go

Coderaph

TypeScript 코드베이스의 의존성 관계를 인터랙티브 3D 그래프로 시각화하는 CLI 도구.

Features

파일/심볼 수준 의존성 분석 - ts-morph 기반 AST 분석으로 import, 참조 관계를 추출
3D Force-Directed Graph - Three.js 기반 물리 시뮬레이션 레이아웃
2D/3D 전환 - 평면 뷰와 입체 뷰 간 자유 전환
방향 화살표 - 엣지에 방향 표시로 의존성 흐름 파악
검색 & 자동완성 - 심볼/파일명 검색, 결과 내비게이션(prev/next)
필터링 - 심볼 종류(class, function, interface 등) 및 경로 기반 필터
그룹 시각화 - path:, file:, kind: 쿼리로 노드 그룹을 ConvexHull로 표시
의존성 체인 - 특정 노드의 상위/하위 의존성을 재귀적으로 추적
다크/라이트 테마 - 설정 자동 저장(localStorage)

Quick Start

# 설치
npm install -g coderaph

# 또는 npx로 바로 실행
npx coderaph analyze ./my-project -o graph.json
npx coderaph view graph.json

Usage

프로젝트 분석

coderaph analyze <project-path> [options]

| Option | Description | Default | |--------|-------------|---------| | -o, --output <path> | 출력 JSON 파일 경로 | coderaph-output.json | | --include <patterns...> | 포함할 glob 패턴 | tsconfig 전체 | | --exclude <patterns...> | 제외할 glob 패턴 | - |

tsconfig.json이 있는 TypeScript 프로젝트 디렉토리를 지정합니다. node_modules와 .d.ts 파일은 자동으로 제외됩니다.

웹 뷰어 실행

coderaph view <json-path> [--port 3000]

브라우저에서 인터랙티브 3D 그래프를 확인할 수 있습니다.

Web Viewer Controls

| Action | Description | |--------|-------------| | 마우스 드래그 | 3D: 회전 / 2D: 패닝 | | 스크롤 | 줌 인/아웃 | | 노드 클릭 | 정보 패널 표시 | | 노드 더블클릭 | 의존성 체인 필터링 | | ESC | 필터 해제 |

Settings

Theme: 다크/라이트 모드
Dimension: 2D/3D 전환
Node Size / Edge Thickness / Node Distance: 레이아웃 조정
Show Labels / Show Arrows: 라벨 및 방향 화살표 토글

Group

path:, file:, kind: 접두사를 사용하여 노드를 그룹화하고 ConvexHull로 시각화할 수 있습니다.

path:src/cli      → src/cli 경로의 파일 그룹
file:graph         → 파일명에 graph를 포함하는 노드 그룹
kind:class         → 모든 class 심볼 그룹

Project Structure

coderaph/
├── src/
│   ├── cli/
│   │   ├── index.ts          # CLI 진입점
│   │   ├── analyzer.ts       # ts-morph AST 분석
│   │   ├── file-graph.ts     # 파일 수준 그래프 생성
│   │   ├── symbol-graph.ts   # 심볼 수준 그래프 생성
│   │   └── server.ts         # 웹 뷰어 HTTP 서버
│   ├── web/
│   │   ├── index.html
│   │   ├── app.js            # Three.js 3D 렌더링
│   │   ├── graph.js          # Force-directed 레이아웃 엔진
│   │   ├── controls.js       # UI 컨트롤
│   │   └── style.css
│   └── types/
│       └── graph.ts          # JSON 스키마 타입
├── package.json
└── tsconfig.json

Tech Stack

CLI: TypeScript, ts-morph, Commander.js
Web: Vanilla JS, Three.js (CDN ESM)
Build: tsc (CLI만 컴파일, 웹은 빌드 없이 서빙)

Development

git clone https://github.com/yoonhoGo/coderaph.git
cd coderaph
npm install
npm run build

# 개발 모드 (watch)
npm run dev

License

MIT