coderaph 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+# Coderaph
+
+TypeScript 코드베이스의 의존성 관계를 인터랙티브 3D 그래프로 시각화하는 CLI 도구.
+
+![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)
+![Three.js](https://img.shields.io/badge/Three.js-000000?logo=three.js&logoColor=white)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## 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
+
+```bash
+# 설치
+npm install -g coderaph
+
+# 또는 npx로 바로 실행
+npx coderaph analyze ./my-project -o graph.json
+npx coderaph view graph.json
+```
+
+## Usage
+
+### 프로젝트 분석
+
+```bash
+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` 파일은 자동으로 제외됩니다.
+
+### 웹 뷰어 실행
+
+```bash
+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](https://ts-morph.com/), [Commander.js](https://github.com/tj/commander.js)
+- **Web**: Vanilla JS, [Three.js](https://threejs.org/) (CDN ESM)
+- **Build**: `tsc` (CLI만 컴파일, 웹은 빌드 없이 서빙)
+
+## Development
+
+```bash
+git clone https://github.com/yoonhoGo/coderaph.git
+cd coderaph
+npm install
+npm run build
+
+# 개발 모드 (watch)
+npm run dev
+```
+
+## License
+
+MIT

package/dist/cli/analyzer.d.ts

@@ -0,0 +1,13 @@
+import { Project, SourceFile } from 'ts-morph';
+export interface AnalyzerOptions {
+    projectPath: string;
+    include?: string[];
+    exclude?: string[];
+}
+/**
+ * Loads a TypeScript project and returns filtered source files.
+ */
+export declare function loadProject(options: AnalyzerOptions): {
+    project: Project;
+    sourceFiles: SourceFile[];
+};

package/dist/cli/analyzer.js

@@ -0,0 +1,68 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { Project } from 'ts-morph';
+/**
+ * Simple glob matcher that supports `*` as a wildcard for any characters.
+ * If the pattern contains no `*`, it falls back to substring matching.
+ */
+function matchGlob(filePath, pattern) {
+    if (!pattern.includes('*')) {
+        return filePath.includes(pattern);
+    }
+    // Convert glob pattern to regex: escape special chars, replace * with .*
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '.*');
+    const regex = new RegExp(`^${escaped}$`);
+    return regex.test(filePath);
+}
+/**
+ * Loads a TypeScript project and returns filtered source files.
+ */
+export function loadProject(options) {
+    const tsConfigFilePath = path.resolve(options.projectPath, 'tsconfig.json');
+    if (!fs.existsSync(tsConfigFilePath)) {
+        throw new Error(`tsconfig.json not found at ${tsConfigFilePath}. Please ensure the project path is correct.`);
+    }
+    const project = new Project({ tsConfigFilePath });
+    let sourceFiles = project.getSourceFiles().filter((file) => {
+        const filePath = file.getFilePath();
+        // Exclude node_modules and declaration files
+        if (filePath.includes('node_modules'))
+            return false;
+        if (filePath.endsWith('.d.ts'))
+            return false;
+        return true;
+    });
+    // Apply include patterns (keep only files matching at least one pattern)
+    if (options.include && options.include.length > 0) {
+        const includePatterns = options.include;
+        sourceFiles = sourceFiles.filter((file) => {
+            const relativePath = path.relative(options.projectPath, file.getFilePath());
+            return includePatterns.some((pattern) => matchGlob(relativePath, pattern));
+        });
+    }
+    // Apply exclude patterns (remove files matching any pattern)
+    if (options.exclude && options.exclude.length > 0) {
+        const excludePatterns = options.exclude;
+        sourceFiles = sourceFiles.filter((file) => {
+            const relativePath = path.relative(options.projectPath, file.getFilePath());
+            return !excludePatterns.some((pattern) => matchGlob(relativePath, pattern));
+        });
+    }
+    // Check for syntax errors and skip problematic files
+    sourceFiles = sourceFiles.filter((file) => {
+        const diagnostics = file.getPreEmitDiagnostics();
+        const syntaxErrors = diagnostics.filter((d) => d.getCategory() === 1 // DiagnosticCategory.Error
+        );
+        if (syntaxErrors.length > 0) {
+            console.warn(`Warning: Skipping ${path.relative(options.projectPath, file.getFilePath())} due to ${syntaxErrors.length} syntax error(s)`);
+            return false;
+        }
+        return true;
+    });
+    if (sourceFiles.length === 0) {
+        console.warn('Warning: No source files found after filtering.');
+    }
+    return { project, sourceFiles };
+}

package/dist/cli/file-graph.d.ts

@@ -0,0 +1,6 @@
+import { SourceFile } from 'ts-morph';
+import { FileNode, Edge } from '../types/graph.js';
+export declare function buildFileGraph(sourceFiles: SourceFile[], projectPath: string): {
+    files: FileNode[];
+    edges: Edge[];
+};

package/dist/cli/file-graph.js

@@ -0,0 +1,32 @@
+import path from 'node:path';
+export function buildFileGraph(sourceFiles, projectPath) {
+    // Build a Set of all source file paths (absolute) for quick lookup
+    const sourceFilePaths = new Set(sourceFiles.map((f) => f.getFilePath()));
+    // Create FileNode for each source file
+    const files = sourceFiles.map((f) => ({
+        id: path.relative(projectPath, f.getFilePath()),
+        symbols: [],
+    }));
+    // Build edges from import declarations
+    const edgeSet = new Set();
+    const edges = [];
+    for (const sourceFile of sourceFiles) {
+        const sourceId = path.relative(projectPath, sourceFile.getFilePath());
+        for (const importDecl of sourceFile.getImportDeclarations()) {
+            const targetFile = importDecl.getModuleSpecifierSourceFile();
+            // Skip if unresolved or not in our source files set
+            if (!targetFile)
+                continue;
+            const targetPath = targetFile.getFilePath();
+            if (!sourceFilePaths.has(targetPath))
+                continue;
+            const targetId = path.relative(projectPath, targetPath);
+            const edgeKey = `${sourceId}::${targetId}`;
+            if (!edgeSet.has(edgeKey)) {
+                edgeSet.add(edgeKey);
+                edges.push({ source: sourceId, target: targetId });
+            }
+        }
+    }
+    return { files, edges };
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { loadProject } from './analyzer.js';
+import { buildFileGraph } from './file-graph.js';
+import { buildSymbolGraph } from './symbol-graph.js';
+import fs from 'node:fs';
+import path from 'node:path';
+const program = new Command();
+program
+    .name('coderaph')
+    .description('TypeScript dependency graph 3D visualizer')
+    .version('0.1.0');
+program
+    .command('analyze <project-path>')
+    .description('Analyze TypeScript project and generate dependency graph JSON')
+    .option('-o, --output <path>', 'Output JSON file path', 'coderaph-output.json')
+    .option('--include <patterns...>', 'Include glob patterns')
+    .option('--exclude <patterns...>', 'Exclude glob patterns')
+    .action((projectPath, options) => {
+    try {
+        const resolvedPath = path.resolve(projectPath);
+        console.log(`Analyzing ${resolvedPath}...`);
+        const { sourceFiles } = loadProject({
+            projectPath: resolvedPath,
+            include: options.include,
+            exclude: options.exclude,
+        });
+        console.log(`Found ${sourceFiles.length} source files`);
+        if (sourceFiles.length === 0) {
+            console.warn('No source files to analyze');
+        }
+        const { files, edges: fileEdges } = buildFileGraph(sourceFiles, resolvedPath);
+        const { symbols, edges: symbolEdges } = buildSymbolGraph(sourceFiles, resolvedPath);
+        // Populate FileNode.symbols arrays
+        const fileSymbolMap = new Map();
+        for (const symbol of symbols) {
+            const existing = fileSymbolMap.get(symbol.fileId) || [];
+            existing.push(symbol.id);
+            fileSymbolMap.set(symbol.fileId, existing);
+        }
+        for (const file of files) {
+            file.symbols = fileSymbolMap.get(file.id) || [];
+        }
+        const output = {
+            version: 1,
+            files,
+            symbols,
+            fileEdges,
+            symbolEdges,
+        };
+        const outputPath = path.resolve(options.output);
+        fs.writeFileSync(outputPath, JSON.stringify(output, null, 2));
+        console.log(`Output written to ${outputPath}`);
+        console.log(`Files: ${files.length}, Symbols: ${symbols.length}, File edges: ${fileEdges.length}, Symbol edges: ${symbolEdges.length}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+});
+program
+    .command('view <json-path>')
+    .description('Start web viewer for dependency graph')
+    .option('-p, --port <number>', 'Server port', '3000')
+    .action(async (jsonPath, options) => {
+    const { startServer } = await import('./server.js');
+    startServer(path.resolve(jsonPath), parseInt(options.port, 10));
+});
+program.parse();

package/dist/cli/server.d.ts

@@ -0,0 +1 @@
+export declare function startServer(jsonPath: string, port: number): void;

package/dist/cli/server.js

@@ -0,0 +1,68 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+const MIME_TYPES = {
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.css': 'text/css',
+};
+export function startServer(jsonPath, port) {
+    const absoluteJsonPath = path.resolve(jsonPath);
+    if (!fs.existsSync(absoluteJsonPath)) {
+        console.error(`Error: file not found — ${absoluteJsonPath}`);
+        process.exit(1);
+    }
+    const webDir = fileURLToPath(new URL('../../src/web/', import.meta.url));
+    const server = http.createServer((req, res) => {
+        const url = req.url ?? '/';
+        if (req.method === 'GET' && url === '/api/graph') {
+            fs.readFile(absoluteJsonPath, 'utf-8', (err, data) => {
+                if (err) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Failed to read graph file' }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(data);
+            });
+            return;
+        }
+        // Serve static files from web directory
+        const filePath = path.join(webDir, url === '/' ? 'index.html' : url);
+        // Prevent directory traversal
+        if (!filePath.startsWith(webDir)) {
+            res.writeHead(403);
+            res.end('Forbidden');
+            return;
+        }
+        fs.readFile(filePath, (err, data) => {
+            if (err) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('Not Found');
+                return;
+            }
+            const ext = path.extname(filePath);
+            const contentType = MIME_TYPES[ext] ?? 'application/octet-stream';
+            res.writeHead(200, { 'Content-Type': contentType });
+            res.end(data);
+        });
+    });
+    server.listen(port, () => {
+        const url = `http://localhost:${port}`;
+        console.log(`Coderaph viewer running at ${url}`);
+        // Open browser automatically
+        switch (process.platform) {
+            case 'darwin':
+                execFile('open', [url], () => { });
+                break;
+            case 'win32':
+                execFile('cmd', ['/c', 'start', url], () => { });
+                break;
+            default:
+                execFile('xdg-open', [url], () => { });
+                break;
+        }
+    });
+}

package/dist/cli/symbol-graph.d.ts

@@ -0,0 +1,6 @@
+import { SourceFile } from 'ts-morph';
+import { SymbolNode, Edge } from '../types/graph.js';
+export declare function buildSymbolGraph(sourceFiles: SourceFile[], projectPath: string): {
+    symbols: SymbolNode[];
+    edges: Edge[];
+};

package/dist/cli/symbol-graph.js

@@ -0,0 +1,112 @@
+import path from 'node:path';
+import { SyntaxKind } from 'ts-morph';
+export function buildSymbolGraph(sourceFiles, projectPath) {
+    const allSymbols = [];
+    // Map: filePath -> Map<symbolName, symbolId>
+    const fileSymbolMap = new Map();
+    // 1. Extract top-level symbols from each file
+    for (const file of sourceFiles) {
+        const filePath = file.getFilePath();
+        const fileId = path.relative(projectPath, filePath);
+        const nameToId = new Map();
+        const addSymbol = (name, kind, node) => {
+            if (!name)
+                return;
+            const id = `${fileId}#${name}`;
+            allSymbols.push({ id, name, kind, fileId, node });
+            nameToId.set(name, id);
+        };
+        for (const cls of file.getClasses()) {
+            addSymbol(cls.getName(), 'class', cls);
+        }
+        for (const fn of file.getFunctions()) {
+            addSymbol(fn.getName(), 'function', fn);
+        }
+        for (const iface of file.getInterfaces()) {
+            addSymbol(iface.getName(), 'interface', iface);
+        }
+        for (const alias of file.getTypeAliases()) {
+            addSymbol(alias.getName(), 'type', alias);
+        }
+        for (const en of file.getEnums()) {
+            addSymbol(en.getName(), 'enum', en);
+        }
+        for (const stmt of file.getVariableStatements()) {
+            for (const decl of stmt.getDeclarations()) {
+                addSymbol(decl.getName(), 'variable', decl);
+            }
+        }
+        fileSymbolMap.set(filePath, nameToId);
+    }
+    // 2. Build edges by resolving imports and tracking references
+    const edgeSet = new Set();
+    const edges = [];
+    for (const file of sourceFiles) {
+        // Build import map: importedName -> target symbol ID
+        const importMap = new Map();
+        for (const importDecl of file.getImportDeclarations()) {
+            const targetFile = importDecl.getModuleSpecifierSourceFile();
+            if (!targetFile)
+                continue;
+            const targetSymbols = fileSymbolMap.get(targetFile.getFilePath());
+            if (!targetSymbols)
+                continue;
+            // Named imports
+            for (const named of importDecl.getNamedImports()) {
+                const importedName = named.getAliasNode()?.getText() ?? named.getName();
+                const originalName = named.getName();
+                const targetId = targetSymbols.get(originalName);
+                if (targetId) {
+                    importMap.set(importedName, targetId);
+                }
+            }
+            // Default import
+            const defaultImport = importDecl.getDefaultImport();
+            if (defaultImport) {
+                const localName = defaultImport.getText();
+                // Default exports typically match a symbol named "default" or the class/function name
+                // Try to find a matching symbol — check 'default' first, then the local name
+                const targetId = targetSymbols.get('default') ?? targetSymbols.get(localName);
+                if (targetId) {
+                    importMap.set(localName, targetId);
+                }
+            }
+        }
+        if (importMap.size === 0)
+            continue;
+        // For each symbol in this file, find references to imported names
+        const fileId = path.relative(projectPath, file.getFilePath());
+        const fileEntries = allSymbols.filter((s) => s.fileId === fileId);
+        for (const symbol of fileEntries) {
+            try {
+                const identifiers = symbol.node.getDescendantsOfKind(SyntaxKind.Identifier);
+                const seen = new Set();
+                for (const ident of identifiers) {
+                    const text = ident.getText();
+                    if (seen.has(text))
+                        continue;
+                    const targetId = importMap.get(text);
+                    if (targetId) {
+                        seen.add(text);
+                        const edgeKey = `${symbol.id}::${targetId}`;
+                        if (!edgeSet.has(edgeKey)) {
+                            edgeSet.add(edgeKey);
+                            edges.push({ source: symbol.id, target: targetId });
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                console.warn(`[symbol-graph] Warning: failed to resolve references for symbol "${symbol.id}":`, err instanceof Error ? err.message : err);
+            }
+        }
+    }
+    // Convert to SymbolNode[] (strip the `node` property)
+    const symbols = allSymbols.map(({ id, name, kind, fileId }) => ({
+        id,
+        name,
+        kind,
+        fileId,
+    }));
+    return { symbols, edges };
+}

package/dist/types/graph.d.ts

@@ -0,0 +1,22 @@
+export type SymbolKind = 'class' | 'function' | 'interface' | 'type' | 'enum' | 'variable';
+export interface FileNode {
+    id: string;
+    symbols: string[];
+}
+export interface SymbolNode {
+    id: string;
+    name: string;
+    kind: SymbolKind;
+    fileId: string;
+}
+export interface Edge {
+    source: string;
+    target: string;
+}
+export interface CoderaphOutput {
+    version: 1;
+    files: FileNode[];
+    symbols: SymbolNode[];
+    fileEdges: Edge[];
+    symbolEdges: Edge[];
+}

package/dist/types/graph.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "coderaph",
+  "version": "0.1.0",
+  "description": "TypeScript dependency graph 3D visualizer",
+  "type": "module",
+  "bin": {
+    "coderaph": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "src/web/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "ts-morph": "^25.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}