@choi2021/next-route-visualizer/README.md

🗺️ Visualize Next.js routes as an interactive diagram with advanced function analysis. Supports dynamic route detection, function-based navigation patterns, and comprehensive Next.js route mapping. Generate JSON data and beautiful HTML reports to explore

# 🗺️ Next.js Route Visualizer

**Next.js 프로젝트의 라우트 구조와 네비게이션을 한 눈에 시각화해보세요!**

한 번의 명령어로 라우트 그래프 JSON과 인터랙티브 HTML 리포트를 생성합니다.

## ✨ 특징

- 🚀 **원클릭 실행**: `npx` 명령어 하나로 즉시 시각화
- 📊 **라우트 분석**: 페이지와 다이내믹 라우트 관계 추적
- 🎯 **동적 함수 분석**: `Router.push(getRoute())`와 같은 동적 함수 호출 내부 분석
- 🔍 **고급 네비게이션 감지**: Routes 상수, 화살표 함수, 조건부 네비게이션 지원
- 🎨 **두 가지 시각화 모드**:
  - 📈 **그래프 다이어그램**: 드래그, 줌, 필터링 가능한 노드-링크 시각화
  - 📋 **인터랙티브 리포트**: 페이지 선택형 연결 탐색 인터페이스
- 💾 **JSON 출력**: 다른 도구에서도 활용 가능한 데이터
- 🌐 **자동 브라우저**: 생성 즉시 브라우저에서 열림

## 🚀 빠른 시작

### Next.js 프로젝트에서 바로 실행

```bash
# 현재 디렉터리 분석 (기본: 그래프 다이어그램)
npx @choi2021/next-route-visualizer

# 인터랙티브 HTML 리포트 생성
npx @choi2021/next-route-visualizer report

# 특정 프로젝트 분석
npx @choi2021/next-route-visualizer ./my-next-app
npx @choi2021/next-route-visualizer report ./my-next-app
```

### 명령어 옵션

```bash
# 기본 그래프 시각화
npx @choi2021/next-route-visualizer map [project-path]

# 인터랙티브 HTML 리포트
npx @choi2021/next-route-visualizer report [project-path] [-o output.html]
```

### 결과

**그래프 시각화 (`map` 명령어):**

- `route-graph.json` - 라우트 데이터
- `route-visualizer.html` - 노드-링크 그래프 시각화

**HTML 리포트 (`report` 명령어):**

- `route-graph.json` - 라우트 데이터
- `route-report.html` - 페이지 선택형 인터랙티브 리포트

## 📋 시스템 요구사항

- Node.js 14.0.0 이상
- Next.js 프로젝트 (pages/ 또는 src/pages/ 구조)

## 💡 사용 예시

```bash
$ npx @choi2021/next-route-visualizer report

📊 Next.js Route HTML Report Generator v1.0.0

🔄 라우트 분석 중...
📊 HTML 리포트 생성 중...

✅ HTML 리포트가 생성되었습니다: route-report.html
📊 총 9개 페이지, 139개 연결 분석 완료

🌐 브라우저에서 리포트를 열었습니다!
```

## 🎨 시각화 모드

### 1. 📈 그래프 다이어그램 (`map`)

- **컬러 코딩**: 페이지(파란색), 다이내믹 라우트(주황색)
- **인터랙티브 그래프**: 노드 드래그, 줌 인/아웃, 팬
- **세부 정보**: 호버시 파일 경로, 코드 스니펫, 라인 번호 표시
- **연결 추적**: 페이지간 네비게이션 관계 시각화

### 2. 📋 인터랙티브 리포트 (`report`)

- **사이드바**: 연결 수 기준 정렬된 페이지 목록
- **페이지 상세**: 선택된 페이지의 incoming/outgoing 연결 표시
- **프로젝트 통계**: 전체 페이지, 연결 수, 평균 연결 수
- **검색 기능**: 페이지 경로 실시간 검색
- **클릭 네비게이션**: 연결된 페이지 간 쉬운 이동

## 📊 출력 데이터 구조

`route-graph.json`의 구조:

```json
{
  "nodes": [
    {
      "id": "/",
      "path": "/",
      "type": "page",
      "filePath": "pages/index.tsx",
      "fileSize": 2203,
      "metadata": { "depth": 0, "segments": [""] }
    }
  ],
  "edges": [
    {
      "source": "/",
      "target": "/about",
      "method": "link",
      "lineNumber": 25,
      "codeSnippet": "<Link href='/about'>",
      "fileName": "pages/index.tsx"
    }
  ],
  "summary": {
    "totalPages": 9,
    "totalConnections": 139,
    "avgConnections": 15.4
  }
}
```

## 🔍 연결 분석 타입

- **link**: Next.js Link 컴포넌트
- **router**: router.push(), router.replace() 등
- **component**: 컴포넌트를 통한 간접 네비게이션

## 🛠️ 개발 및 디버깅

### 로컬 개발

```bash
git clone https://github.com/your-username/next-route-map.git
cd next-route-map
npm install
npm run build

# 예제 프로젝트 테스트
npm run test:example

# HTML 리포트 테스트
npm run test:report
```

## 🤝 기여하기

버그 리포트와 기능 제안은 [GitHub Issues](https://github.com/your-username/next-route-map/issues)에서 환영합니다.

## 📄 라이선스

MIT License

---

**⭐ 프로젝트가 유용하다면 GitHub에서 별표를 눌러주세요!**

## 🎯 고급 분석 기능 (v1.1.0)

### 동적 함수 분석

이제 다음과 같은 복잡한 네비게이션 패턴도 정확히 분석합니다:

```typescript
// 1. 조건부 동적 함수 (✅ 모든 가능한 경로 감지)
const getRoute = () => {
  if (condition) {
    return V2_Routes.ADMIN_PANEL(); // → /v2/admin/panel
  } else {
    return Routes.PROFILE(); // → /profile
  }
};

const handleClick = () => {
  Router.push(getRoute()); // 두 경로 모두 시각화됨!
};

// 2. 화살표 함수 Routes 상수 (✅ 지원)
export const V2_Routes = {
  ADMIN_PANEL: () => "/v2/admin/panel",
  USER_PROFILE: (id) => `/v2/user/${id}`,
};

// 3. getServerSideProps 리디렉션 (✅ 지원)
export async function getServerSideProps() {
  if (!authenticated) {
    return { redirect: { destination: "/login" } };
  }
}

// 4. 대소문자 구분 (✅ 모두 감지)
Router.push(Routes.HOME()); // 대문자 Router
router.push(Routes.PROFILE()); // 소문자 router
```

### 지원하는 네비게이션 패턴

- ✅ **정적 경로**: `"/dashboard"`, `'/profile'`
- ✅ **Routes 상수**: `Routes.HOME`, `ROUTES.DASHBOARD`
- ✅ **함수형 Routes**: `Routes.PROFILE()`, `V2_Routes.ADMIN()`
- ✅ **동적 함수 호출**: `Router.push(getRoute())`
- ✅ **조건부 리턴**: `if/else` 블록 내 네비게이션
- ✅ **템플릿 리터럴**: `` `/dashboard?tab=${tab}` ``
- ✅ **getServerSideProps 리디렉션**
- ✅ **useEffect 내 네비게이션**
- ✅ **훅 기반 네비게이션**