# CodePulse CLI — 전체 문서 (파트 1/3)

> 버전: **5.2.0** | 패키지: `@archpulse/codepulse` | 라이선스: MIT | Node.js ≥ 16

---

## 목차

- [파트 1](#): 개요, 스택, 아키텍처, 설치, 설정, `scan`
- [파트 2](#): `watch`, `diff`, `time-machine`, `health-trend`, `heatmap`, `coupling`, `audit`
- [파트 3](#): `profile`, `ghost`, `synth`, `verify`, `pr-risk`, `review`, `agent`, `license`, `detect-reward-hacking`, MCP 서버, GitHub Actions, 플러그인, i18n

---

## 1. CodePulse란 무엇인가

**CodePulse**는 대규모 JS/TS 및 Python 프로젝트를 위해 설계된 심층 정적 및 구조적 코드 분석 CLI 도구입니다. 이 도구의 핵심 철학은 **"Engineering Honesty" (엔지니어링의 정직함)**입니다. 아키텍처적 문제를 미화하거나 숨기지 않고 정직하게 드러냅니다.

### 주요 기능

- AST 분석을 통해 프로젝트 전체의 **의존성 그래프** 구축
- **God Files** (비대해진 파일), **Critical Nodes** (임계 노드), **순환 의존성** 감지
- 코드베이스의 전반적인 건강 상태를 나타내는 통합 지표인 **Health Score** (0–100) 계산
- **핫스팟 (Hotspots)** 감지 — 높은 복잡도와 빈번한 변경이 동시에 발생하는 파일 식별
- Git 이력을 기반으로 파일 간의 **시간적 결합도 (Temporal Coupling)** 분석
- **외부 린터** 연동 (ESLint, Oxlint, Ruff, Cppcheck, ShellCheck, GolangCI-Lint 등)
- AI 에이전트(Claude, Cursor, Cline, Gemini, Copilot 등)를 위한 **MCP 서버** 지원
- Git 히스토리를 통해 프로젝트 상태 지표의 변화 흐름을 추적하는 **타임머신 (Time Machine)** 기능
- **HTML 보고서**, **SARIF 파일**, **SVG 배지** 자동 생성
- Health Score가 설정된 임계값 아래로 떨어질 경우 Slack, Discord, Telegram으로 **웹훅 알림** 발송
- CI/CD 파이프라인에 즉시 통합 가능한 **GitHub Action** 지원

---

## 2. 기술 스택

| 분류 | 기술 | 용도 |
|---|---|---|
| 언어 | TypeScript 6.0 | CLI 전체 소스 코드 코드베이스 |
| 빌드 | `tsc` | `dist/` 디렉터리로 컴파일 |
| CLI 프레임워크 | Commander.js 14 | 명령어 및 플래그 파싱 |
| AST (JS/TS) | `@babel/parser` + `@babel/traverse` | JS/TS 파일 구문 분석 |
| AST (고급) | `ts-morph` 28 | 심층 TypeScript 구조 분석 |
| TUI 대시보드 | `blessed` + `blessed-contrib` | 터미널 대시보드 인터페이스 (`watch`, `heatmap`) |
| 의사 터미널 | `node-pty` | `watch` 대시보드 내부의 내장 터미널 구현 |
| 파일 감시 | `chokidar` 5 | 실시간 파일 변경 감시 |
| 스피너 | `ora` | CLI 작업 진행 스피너 |
| 터미널 색상 | `chalk` 4 | 다채로운 터미널 출력 지원 |
| 템플릿 | `handlebars` | HTML 보고서 생성 |
| Glob | `glob` 13 | 패턴 매칭 기반 파일 검색 |
| GitHub API | `@octokit/rest` + `@actions/core` | GitHub Actions 연동 및 PR 댓글 생성 |
| MCP | `@modelcontextprotocol/sdk` | AI 에이전트를 위한 MCP 서버 연동 |
| 테스트 | `vitest` 4 | 단위 테스트 수행 |

---

## 3. 프로젝트 아키텍처

```
codepulse-cli/
├── src/
│   ├── index.ts                    # CLI 진입점 (Entry Point)
│   ├── explain.ts                  # 아키텍처 개념에 대한 지식 베이스
│   ├── mcp-setup.ts                # 에이전트용 MCP 설정 파일 생성 및 연동
│   ├── mcp-paths.ts                # MCP 설정 파일 경로 정의
│   │
│   ├── cli/commands/               # CLI 명령어 등록 (Commander.js)
│   │   ├── advanced-commands.ts    # coupling, pr-risk, explain, time-machine, profile, plugins
│   │   └── ...
│   │
│   ├── commands/                   # 명령어 세부 구현
│   │   ├── scan.ts          (412라인)  # codepulse scan
│   │   ├── watch.ts        (1868라인)  # codepulse watch — TUI 대시보드 (God File)
│   │   ├── diff.ts          (435라인)  # codepulse diff
│   │   ├── time-machine.ts  (197라인)  # codepulse time-machine
│   │   ├── health-trend.ts  (369라인)  # codepulse health-trend
│   │   ├── heatmap.ts       (247라인)  # codepulse heatmap
│   │   ├── coupling.ts       (60라인)  # codepulse coupling
│   │   ├── audit.ts          (98라인)  # codepulse audit
│   │   ├── profile.ts       (174라인)  # codepulse profile
│   │   ├── ghost.ts          (65라인)  # codepulse ghost
│   │   ├── review.ts        (117라인)  # codepulse review
│   │   ├── synth.ts          (80라인)  # codepulse synth
│   │   ├── verify.ts        (218라인)  # codepulse verify
│   │   ├── pr-risk.ts       (195라인)  # codepulse pr-risk
│   │   ├── reward-hacking.ts(131라인)  # codepulse detect-reward-hacking
│   │   ├── agent.ts         (342라인)  # codepulse agent
│   │   ├── license.ts       (204라인)  # codepulse license
│   │   ├── badge.ts                      # SVG 배지 생성
│   │   ├── install-deps.ts  (398라인)  # 외부 린터 자동 설치 로직
│   │   └── output.ts                     # 통계 출력 포맷팅
│   │
│   ├── analyzer/                   # 핵심 분석 엔진
│   │   ├── index.ts                # 메인 analyze() 함수
│   │   ├── scanner.ts              # 파일 스캔 및 필터링 (glob)
│   │   ├── ast.ts                  # Babel 기반 JS/TS AST 분석
│   │   ├── graph.ts                # 의존성 그래프 빌드 및 중앙성(centrality), 임계 노드 계산
│   │   ├── git.ts                  # Git 메트릭 분석: churn, 시간적 결합도
│   │   ├── workers.ts              # 병렬 분석을 위한 워커 스레드 구현
│   │   ├── cache.ts                # 결과 캐싱 엔진 (zlib 압축 활용)
│   │   ├── python.ts               # Python 파일 분석기
│   │   ├── rust.ts                 # Rust 파일 분석기
│   │   ├── generic.ts              # 기타 지원 언어 파일 분석기
│   │   ├── ast-fingerprint.ts      # AST 지문 인식을 통한 코드 중복 감지
│   │   ├── architecture.ts         # 아키텍처 레이어 경계 검증
│   │   ├── context.ts              # .codepulse.json 설정 파일 로딩
│   │   ├── zlib.ts                 # 압축 유틸리티
│   │   └── time-machine/
│   │       ├── engine.ts           # Git 히스토리 분석 엔진
│   │       ├── cache.ts            # 스냅샷 캐싱 (.codepulse-cache/snapshots/)
│   │       ├── sampling.ts         # 커밋 샘플링 전략 수립
│   │       └── git-diff.ts         # 커밋 간 Diff 추출 유틸리티
│   │
│   ├── rules/                      # 분석 규칙 및 린터 정의
│   │   ├── index.ts                # 분석 오케스트레이터 (모든 규칙 조율 및 실행)
│   │   ├── security.ts             # 보안 취약점 패턴 분석 (정규표현식 기반)
│   │   ├── fastLinter.ts           # 초고속 내장 정적 분석기
│   │   ├── agents/registry.ts      # AI 에이전트 레지스트리 및 CodePulse 마스터 룰
│   │   └── linters/                # 외부 린터 어댑터
│   │       ├── javascript.ts       # ESLint / Oxlint
│   │       ├── python.ts           # Ruff
│   │       ├── rust.ts             # Clippy
│   │       ├── go.ts               # GolangCI-Lint, Revive
│   │       ├── cpp.ts              # Cppcheck
│   │       ├── lua.ts              # Luacheck, Selene
│   │       └── shell.ts            # ShellCheck
│   │
│   ├── mcp/                        # MCP 서버 연동
│   │   ├── server.ts               # MCP 서버 실행 (stdio 전송 계층)
│   │   ├── handlers-health.ts      # codepulse_identity, get_project_stats, analyze_project...
│   │   ├── handlers-architecture.ts# visualize_subgraph, get_blast_radius, find_cycles...
│   │   ├── handlers-agent.ts       # optimize_context, simulate_edit, store_memory...
│   │   └── definitions/            # MCP 도구 정의용 JSON 스키마
│   │
│   ├── reporter/
│   │   ├── html.ts                 # HTML 보고서 생성기
│   │   ├── sarif.ts                # SARIF 파일 포맷 내보내기
│   │   ├── health.ts               # Health Score 계산 모델
│   │   └── stats.ts                # 프로젝트 통계 데이터 애그리게이터
│   │
│   ├── utils/
│   │   ├── i18n.ts                 # 다국어 번역 시스템 (7개 언어 지원)
│   │   ├── webhooks.ts             # Slack, Discord, Telegram 알림 웹훅 발송기
│   │   ├── plugins.ts              # 외부 플러그인 동적 로딩 유틸리티
│   │   └── terminal.ts             # 터미널 특수문자 지원 (UTF-8 / ASCII fallback)
│   │
│   └── locales/                    # 다국어 번역 리소스 파일 (JSON)
│       └── en.json, ru.json, ua.json, de.json, fr.json, ko.json, cs.json
│
├── plugins/                        # 커스텀 사용자 플러그인 디렉터리
├── rules/                          # 커스텀 분석 규칙 디렉터리
├── translations/                   # 다국어 README 리소스
├── action.yml                      # GitHub Action 설정 파일
└── .codepulse.json                 # 프로젝트 루트 설정 파일
```

---

## 4. 설치 방법

### npm을 활용한 전역(global) 설치

```bash
npm install -g @archpulse/codepulse
```

### npx를 이용한 즉시 실행 (설치 없음)

```bash
npx @archpulse/codepulse scan .
```

### 소스 코드 빌드 및 로컬 설치

```bash
git clone https://github.com/archpulse/codepulse-cli.git
cd codepulse-cli
npm install
npm run build
npm link   # 'codepulse' 명령어를 글로벌 명령어로 등록
```

### 시스템 요구사항

- **Node.js ≥ 16.0.0**
- Git (시간적 결합도, 타임머신 분석에 필수)
- 선택 사항: `oxlint`, `ruff`, `cppcheck`, `shellcheck`, `golangci-lint` (CodePulse의 `install-deps` 명령어로 한 번에 자동 설치 가능)

---

## 5. `.codepulse.json` 설정 파일

프로젝트 루트에 설정하는 `.codepulse.json` 파일은 분석 엔진의 모든 동작 방식을 정밀하게 제어합니다.

### 주석이 포함된 설정 구성 예시

```json
{
  "exclude": ["benchmark", "dist", "node_modules"],
  "rootDir": "src",
  "godFileLines": 500,
  "godFileImports": 20,
  "criticalNodeThreshold": 15,
  "alerts": {
    "slack": "$CODEPULSE_SLACK_WEBHOOK",
    "discord": "$CODEPULSE_DISCORD_WEBHOOK",
    "telegram": {
      "token": "$TELEGRAM_BOT_TOKEN",
      "chatId": "$TELEGRAM_CHAT_ID"
    },
    "threshold": 80,
    "branches": ["main", "master"]
  },
  "architecture": {
    "layers": [
      {
        "name": "Domain",
        "pattern": "src/domain/**",
        "allowDependenciesFrom": []
      },
      {
        "name": "Application",
        "pattern": "src/commands/**",
        "allowDependenciesFrom": ["Domain"]
      }
    ]
  }
}
```

### 주요 파라미터 상세 항목

| 설정 속성 | 타입 | 기본값 | 상세 설명 |
|---|---|---|---|
| `exclude` | `string[]` | `[]` | 스캔 및 분석 대상에서 영구 제외할 디렉터리 패턴 목록 |
| `rootDir` | `string` | `"."` | 스캔을 수행할 타깃 프로젝트 기준 디렉터리 경로 |
| `godFileLines` | `number` | `500` | God File로 판단할 기준 코드 라인 수 임계값 |
| `godFileImports` | `number` | `20` | God File로 판단할 기준 import 구문 개수 임계값 |
| `criticalNodeThreshold` | `number` | `15` | Critical Node로 판단할 중앙성(centrality) 값의 기준값 |
| `alerts.slack` | `string` | — | Slack Incoming Webhook 주소 |
| `alerts.discord` | `string` | — | Discord Webhook 주소 |
| `alerts.telegram.token` | `string` | — | 텔레그램 봇 토큰 주소 |
| `alerts.telegram.chatId` | `string` | — | 텔레그램 알림을 발송할 대상 채팅방 혹은 채널 고유 ID |
| `alerts.threshold` | `number` | `80` | 해당 설정된 Health Score 점수 미만으로 떨어질 때만 웹훅 발송 |
| `alerts.branches` | `string[]` | `["main","master"]` | 경고 웹훅 알림이 정상 작동할 기준 Git 브랜치 이름 목록 |
| `architecture.layers` | `Layer[]` | — | 모듈 경계를 정의하고 비허용 의존성 관계를 감지하기 위한 레이어 매핑 구조 |

> **환경 변수 매핑:** 환경 변수를 주입하기 위해 사용된 `"$VAR_NAME"` 형태의 문자열은 설정 초기화 시 `process.env`로부터 자동으로 주입됩니다.

### 아키텍처 레이어 규칙 (`architecture.layers`)

프로젝트 내에 존재하는 각 모듈 간의 단방향 통신 흐름이나 의존성 계층 구조를 강제할 수 있습니다. 레이어 규칙 위반 사항이 발견되면 CodePulse는 `architecture-violation` 이슈를 기록합니다.

```json
{
  "name": "Infrastructure",
  "pattern": "src/db/**",
  "allowDependenciesFrom": ["Domain", "Application"]
}
```

- `name` — 설정 레이어 고유 이름
- `pattern` — 해당 레이어에 소속될 파일들을 분류할 glob 매칭 패턴
- `allowDependenciesFrom` — 현 레이어 내부 파일이 의존(import)할 수 있는 다른 승인 레이어들의 이름 목록

---

## 6. `scan` 명령어

프로젝트 전체를 고정 정밀도로 단 한 번 깊게 검사하는 메인 유틸리티 기능입니다.

### 사용 문법

```bash
codepulse scan [dir] [options]
```

### `scan` 명령어의 전체 실행 순서

1. 인수로 전달한 타깃 디렉터리가 실재하는지 검증합니다.
2. 분석 대상 언어군에 유효한 도구 중 설치되지 않은 린터가 있으면 자동으로 인스톨합니다 (`runInstallDepsForProject`).
3. 활성화할 린터 엔진의 강제 여부를 감지합니다 (ESLint, Oxlint 또는 Auto).
4. 심층 분석 프로세스 `analyze()`를 백그라운드 스레드로 실행합니다 (AST, 의존성 그래프, Git 분석, 보안 룰, 린터 작동).
5. 분석 상세 데이터를 시각적으로 탐색할 수 있는 반응형 HTML 리포트를 `.codepulse-report/index.html`에 생성합니다.
6. 최종 Health Score 점수를 평가하고 전용 `.codepulse-report/badge.svg` 이미지를 출력합니다.
7. 필요한 경우 보안 진단 내보내기용 standard SARIF 파일을 동시 생성합니다.
8. 설정된 Health Score 기준값 미만으로 떨어진 것을 감지하면 Slack/Discord/Telegram 등으로 알람 웹훅을 전송합니다.
9. 전체 수치 통계 리포트 피드백 데이터를 사용자 터미널 화면에 보기 좋게 구조화하여 렌더링합니다.

### 명령어 플래그 설명

| 명령어 플래그 | 상세 동작 |
|---|---|
| `--json` | 순수 구조화 분석 결과 원본 데이터를 JSON 텍스트 상태로 stdout 채널에만 인쇄 (상세 UI 로그 미출력) |
| `--sarif` | GitHub 보안 스캔 탭에 직접 로딩 가능한 SARIF 스키마 진단 리포트 파일 생성 |
| `--open` | 분석이 완료되는 즉시 시스템 디폴트 브라우저를 활성화해 HTML 보고서 화면을 자동으로 오픈 |
| `--strict` | 엄격 분석 모드 작동: `dead-export` 및 `god-file` 경고 레벨을 `error` 강제 적용 |
| `--debug` | 타사 외부 린터 진단 예외 사항은 출력을 생략하고, CodePulse 내부 처리 중 발생한 크리티컬 로직 에러만 필터링 출력 |
| `--ld` | 오직 외부 도구 린터의 상세 실행 로그와 정밀 결과 정보 데이터에 포커스를 둔 로깅 디버그 활성화 |
| `--focus <type>` | 검출된 여러 이슈 중 특정 문제 타입에 필터를 설정해 결과 제한 출력 |
| `--severity <level>` | 위험성 강도를 기준으로 이슈 선별: `error`, `warning`, `info` |
| `--group-by <field>` | 통계 정렬 및 그룹 바인딩 기준 적용: `file`, `type`, `severity` |
| `--max-issues <n>` | 터미널 화면에 노출될 최대 이슈 보고 리스트 개수를 N개로 제한 |
| `--ignore-warnings` / `-iw` | 주의 경보에 해당하는 Warning 등급 이하 보고서 데이터를 터미널 화면에서 완전 숨김 |
| `--fail-on <severity>` | 설정한 세버리티 이상의 주요 위험 인자가 단 하나라도 포함된 경우 전체 CLI 종료 상태를 1번 에러로 강제 종료 |
| `--precision` / `--eslint` | 무조건 타이트한 ESLint 엔진을 분석 수단으로 채택 (속도는 느리지만 문맥 평가의 정확도가 비약적으로 향상) |
| `--engine oxlint` | 무조건 초고속 Rust 기반 Oxlint 엔진으로 강제 스캔 (극강의 속도 보장) |

### 커스텀 단축 파라미터 매핑 정보

| 간략화 문법 | 실제 내부 전개 구조 |
|---|---|
| `-ld` | `--ld` |
| `-iw` | `--ignore-warnings` |
| `-diw` | `--debug --ignore-warnings` |
| `-ldiw` | `--ld --ignore-warnings` |

### 이슈 필터 카테고리 (`--focus`)

| 카테고리 이름 | 상세 내용 |
|---|---|
| `dead-export` | 파일 밖으로 export되었으나 프로젝트 전체에서 아무도 참조하지 않는 미사용 심볼 |
| `god-file` | 코드 볼륨 및 import 개수가 비정상적으로 비대해진 거대 모노리스 구조 |
| `critical-node` | 강한 의존 허브 역할을 수행 중이라 영향도가 너무 큰 중요 임계 파일 |
| `circular-dependency` | 패키지 순환 참조 구조를 형성한 위험성 높은 임포트 구조체 |
| `vulnerability` | 소스 내부에 정밀 삽입된 알려진 토큰 노출 등 정보 보안 위험군 |
| `architecture-violation` | 지정 아키텍처 경계를 이탈해 통신이 불가능한 상위 의존 관계 침해 이슈 |
| `linter` | ESLint 또는 Ruff 등 연동된 서드파티 린터에 의해 검출된 로컬 스타일 문제군 |
| `high-complexity` | 순환 복잡도 수치가 상한 임계값을 초과해 코드 해석이 불리한 함수/클래스 |
| `duplication` | AST 해싱을 거쳐 분석된 완벽한 로직 중복 코드 세그먼트 |

### 활용 예제

```bash
# 기본 모드로 현재 경로 스캔 실행
codepulse scan .

# CI 파이프라인에서 결과값 원본을 받아 후가공하기 위해 JSON으로 저장
codepulse scan . --json

# 크리티컬 에러만 단독으로 식별 출력
codepulse scan . --severity error

# 엄격 모드를 적용하며 에러 발생 시 빌드 파이프라인 중단을 위해 종료 코드 1 강제
codepulse scan . --strict --fail-on error

# 미사용 청소 타깃 코드 파악에 초점
codepulse scan . --focus dead-export

# 검출된 결함들을 해당 파일 단위로 묶어 정렬 인쇄
codepulse scan . --group-by file

# HTML 리포트 자동 생성 후 로컬 브라우저로 리포트 확인
codepulse scan . --open
```

### 터미널 화면 피드백 구조

```
  ◆ CodePulse v5 — Engineering Honesty
  Scanning /path/to/project

  Engine: Auto (Resolving...)
  ✔ Analysis complete!

  Report: .codepulse-report/index.html
  Badge:  .codepulse-report/badge.svg
  Score:  87/100

  Files: 101  Lines: 16486  AvgComplexity: 2.90
  Issues: 2 errors  1 warning  (3 total)
```

### 점수 평가 감점 규칙

| 감점 타깃 항목 | 단일 파일/건당 감점 폭 |
|---|---|
| God Files (거대 모노리스) | −10 점 |
| 순환 의존성 관계 구조체 | −8 점 |
| 임계 집중 모듈 (Critical Nodes) | −5 점 |
| 보안 위험성 취약 부분 발견 | −7 점 |
| 미사용 export 심볼 (Dead Exports) | −1 점 |
| 정의된 아키텍처 규칙 위반 | −6 점 |
| 변경과 피로도가 집중된 핫스팟 파일 | −2 점 |

전체 스코어 가이드라인: **0점부터 100점까지**. 상태 표시 색상 매핑: 🟢 ≥ 90 / 🟡 ≥ 70 / 🔴 < 70.

---

# CodePulse CLI — 전체 문서 (파트 2/3)

## 7. `watch` 명령어

실시간 TUI(터미널 사용자 인터페이스) 대시보드를 제공합니다. 코드 변경을 실시간 감지하여 자동 재분석을 진행합니다.

### 사용 문법

```bash
codepulse watch [dir]
```

### 대시보드 구조

대시보드는 멀티 뷰포트 스크롤링 기법을 도입하여 설계되었으며, `Tab` 키로 포커스를 제어할 수 있습니다.

- **Health Gauge:** 대시보드 맨 상단에 나타나는 색상 게이지 막대 (건강 지수 표시)
- **Cockpit Terminal:** 대시보드 내부 내장 터미널 셸 (코드 분석 명령어를 대시보드 안에서 즉시 단독 수행 가능)
- **Telemetry:** 전체 파일 크기, 라인 볼륨, 에러 건수 등 고차원 분석 통계 메트릭 모듈
- **Complexity Chart:** 대시보드 내부 좌측 그래프 (최근 10회 검침 데이터에 기반한 복잡도 변경 추이 표시)
- **Hotspots Table:** 점수가 가장 많이 하락한 고위험 핵심 핫스팟 TOP 5 상세 그리드
- **Hazard Log:** 결함, 아키텍처 이탈 등 실시간 검출 경보 메시지 피드 (위치 및 위치 추적 확인)
- **Warp Log:** Git 트렌킹 추적 히스토리, 웹훅 전송 성공 로그, 파일 변경 이벤트 리포트 트레이스
- **Clock Bar:** 사용자 로케일 언어 규칙을 준수하는 시계 인터페이스 모듈 (가장 하단 위치)

### 실시간 터미널 핫키 (Hotkeys)

| 제어 단축키 | 제어 범위 및 동작 |
|---|---|
| `Tab` | 대시보드 내의 패널을 순차적으로 포커싱 전환 |
| `1`–`9` | 지정 인덱스 번호에 할당된 컴포넌트로 포커스 강제 스위칭 |
| `Esc` | 현재 포커스 포커싱 탈출 (키보드 전체 뷰포트 롤링 모드 적용) |
| `c` | 포커스 윈도 패널 축소(접기) 및 원상 복구 |
| `+` / `-` | 타깃 윈도의 상하 스팬 높이 값 조절 |
| `[` / `]` | 타깃 윈도의 좌우 스팬 너비 넓이 값 조절 |
| `a` | **Add Mode** (추가 모드) 진입 (감춰진 패널이나 임의 bash 셸 패널 생성) |
| `s` | **Swap Mode** (위치 전환 모드) 활성화 (타깃 창과 타 창 위치 변경) |
| `x` | 현재 활성화된 패널 창 제거 및 화면 재배열 |
| `Ctrl+C` | 실시간 대시보드 엔진 종료 및 원 상태 셸 복구 |

### Add Mode (`a`) 기능 상세

상태 표시줄이 노란색으로 반짝일 때, `t` 키를 누르면 시스템 내부 bash 인터페이스에 고정 바인딩된 실제 독립 실행형 셸 CLI 뷰포트 창이 화면 내부에 삽입됩니다. 이와 더불어 감춰진 Heatmap 차트 맵이나 그래프 서브 패널도 실시간으로 다시 생성하여 대시보드에 적재할 수 있습니다.

---

## 8. `diff` 명령어

현재 프로젝트의 아키텍처 상태를 지정 타깃 브랜치 상태와 대조 분석하여 품질 변화 리포트를 출력합니다.

### 사용 문법

```bash
codepulse diff <branch> [options]
```

### 아키텍처 비교 프로세스

1. 현재 활성화 상태인 소스 소속 브랜치의 정보 기억
2. 현재 활성화된 소스 상태에 맞춰 `analyze()` 스캔 정보 버퍼 적재
3. 커밋 전 유실 위험 방지를 위해 임시 변경 내용을 `git stash`에 백업
4. 자동으로 target 브랜치로 전환 (`git checkout <branch>`) 후 분석 진행
5. 다시 원래 기점 브랜치로 자동 롤백 및 `git stash pop`으로 코드 복구
6. 두 분석 지점 사이의 상세 품질 차이점 비교 분석 결과를 구조화 출력

---

## 9. `time-machine` 명령어

Git 커밋 히스토리를 순회 분석하여, 시간 경과에 따른 소프트웨어 품질과 의존성 관계 복잡도 변경 추세를 추적합니다.

### 사용 문법

```bash
codepulse time-machine [dir] [options]
```

### 주요 샘플링 정책 (`--strategy`)

- `max-points`: 분석 부하와 리소스를 억제하기 위해 전체 이력 중 고르게 N개의 포인트만 등간격 추출 검출 (기본값)
- `every-nth`: 매 N번째 누적 커밋을 균등 방식으로 스캔 처리
- `interval`: 날짜 시간 베이스로 정밀 샘플링 (`daily`, `weekly`, `monthly`)
- `tag-only`: 오로지 Tag 릴리스 버전 커밋만 선별 스캔

자동 반복 분석 부하 방지를 위한 전용 지능형 스냅샷 데이터베이스 캐시(`.codepulse-cache/snapshots/`)를 내장하여 뛰어난 캐시 적중 효율성을 실현했습니다.

---

## 10. `health-trend` 명령어

Time Machine에 캐싱 보관된 상태 점수 시각화 요약 리포트를 통해 터미널 전용 텍스트 차트(Unicode Sparklines) 통계 지표 분석 리포트를 렌더링합니다.

### 사용 문법

```bash
codepulse health-trend [dir] [options]
```

### 화면 출력 예시

```
  ══════════════════════════════════════════════════════════════
  Health Score Evolution
  ══════════════════════════════════════════════════════════════

  Health    ▅▆▇▇▆▅▄▄▅▆▆▇▇  95 → 82  (↓13)  Regressing ✗
  Complex   ▂▂▃▃▃▄▄▄▄▅▅▅▅  2.1 → 2.9  (↑0.8)  Regressing ✗
  Files     ▂▃▃▄▄▄▅▅▆▆▆▇▇  45 → 101  (+56)  Growing
  Issues    ▁▁▁▂▂▂▃▃▄▄▄▅▅  0 → 3  (↑3)  Regressing ✗
```

---

## 11. `heatmap` 명령어

전체 파일을 대상으로 산출된 아키텍처적 결함 가중치 리스크 인덱스 지표를 기하학적 색상 기반 터미널 그래픽으로 표현합니다.

### 사용 문법

```bash
codepulse heatmap [dir]
```

### 리스크 스코어 (Risk Score) 계산 산식

```
Risk = Complexity × log₂(Churn + 1) × (1 + Centrality / MaxCentrality)
```

- **Complexity:** 내부 구문 순환 복잡도 인덱스
- **Churn:** Git 히스토리 변경 빈도 카운팅
- **Centrality:** 의존성 그래프 상의 노드 중심성 가중치

---

## 12. `coupling` 명령어

동일한 Git 커밋 내부에서 상습적으로 자주 엮여 동반 수정이 일어난 위험성 높은 파일들을 식별합니다.

### 사용 문법

```bash
codepulse coupling [dir]
```

### 시간적 결합도란 무엇인가

정규 의존성 임포트 구조가 존재하지 않더라도, 코드 수정 시 함께 변해야만 하는 두 모듈 간의 숨겨진 물리적 의존성 및 강결합 경고 사유를 감지합니다. SRP(단일 책임 원칙) 위배나 과다한 의존 문제를 조기 색출하기에 완벽한 기능입니다.

---

## 13. `audit` 명령어

종합 검사를 원버튼 형태로 단독 자동화해 전체 분석 세부 내용을 담은 `AUDIT.md` 파일을 프로젝트 루트에 자동 덤프 생성합니다.

### 사용 문법

```bash
codepulse audit [dir]
```

---

# CodePulse CLI — 전체 문서 (파트 3/3)

## 14. `profile` 명령어

로컬 런타임 프로파일링 데이터 정보(V8 `.cpuprofile` 또는 Python `.prof`)를 AST 메트릭 정보에 기하적으로 바인딩하여 시스템 자원 낭비를 유발하는 부채 영역을 진단합니다.

### 사용 문법

```bash
codepulse profile <file> [options]
```

---

## 15. `ghost` 명령어

특정 핵심 파일의 구조적 의존 관계를 재귀 순회하여, 대상 소스가 소멸되거나 개편될 때 영향을 입게 되는 프로젝트 파급 영향 지표(Blast Radius)를 수치와 시각적 데이터로 즉각 산출합니다.

### 사용 문법

```bash
codepulse ghost <file> [options]
```

---

## 16. `synth` 명령어

주요 임계 노드 및 거대 모노리스(God Files)를 표적으로 하는 자동 연동 목킹(Mocking) 및 오류 고립화 시뮬레이션 상세 시나리오 지침 명세서인 `STRESS_TEST_PLAN.md`를 프로젝트에 즉각 작성합니다.

---

## 17. `verify` 명령어

아키텍처 변경이나 소스 수정이 수행된 대상 영역을 빌드/타입체크/린트/테스트의 유기적 프로세스로 자동 통합 테스트하는 특화 검증 유틸리티입니다. 변경과 의존성 관계에 영향을 받는 테스트 세트만 선별 동작하여 처리 속도가 탁월합니다.

---

## 18. `pr-risk` 명령어

Pull Request를 통해 수정 예정인 소스들의 아키텍처적 결함도를 0점부터 100점까지의 리스크 가중 점수(Risk Score) 모델로 예측 진단합니다. 만약 시간적 결합도가 높은 동반 수정 누락 의혹 파일이 있는 경우 강한 주의 알람 지침 경고가 표시됩니다.

---

## 19. `review` 명령어

CI 시스템에 특화된 명령어로, PR 생성 코드를 스캔 및 품질 산정한 뒤, 구조화된 Markdown 보고서 피드백을 대상 GitHub PR의 실제 코드 댓글 형태로 API 주입을 실행해 자동 게시합니다 (`--github`).

---

## 20. `agent` 명령어

Cursor, Cline, Claude Code, Gemini CLI 등 23종의 최신 고기능성 AI 개발 시스템 및 챗봇들이 CodePulse의 분석 기능들을 완벽히 장악하여 의존 관계 이슈나 리팩토링 경로 수립을 조율할 수 있도록 전용 가이드라인 파일(`.cursorrules`, `.clinerules`, `CLAUDE.md`, `.antigravityrules` 등)을 자동 인젝션 설정합니다.

---

## 21. `license` 명령어

프로젝트 루트에 타깃 조건 라이선스 명세서 파일(`LICENSE`)을 john doe 양식으로 즉각 신규 인쇄 배치 생성합니다. MIT, ISC, Apache, GPL 등 다수 규격을 지원합니다.

---

## 22. `detect-reward-hacking` 명령어

AI 코드 에이전트 등이 생성 과정 중 성능 수치 개선을 유도하기 위해 테스트나 벤치마크 시스템을 무력화하거나, 하드코딩된 단락 지름길 분기 기법을 사용해 결과를 날조하는 등의 꼼수 행태(Reward Hacking)를 AST 구문 분석 기법을 통하여 명확히 검출합니다.

---

## 23. `install-deps` 명령어

개발 머신의 현재 OS 유형(APT, Brew, Pacman 등)을 다이나믹하게 체크하여 파이썬의 Ruff나 C++용 Cppcheck, 셸 진단용 ShellCheck 등 프로젝트 소스 언어 성향에 필요한 부가 도구 모음들을 선별하여 원버튼 자동 인스톨합니다.

---

## 24. MCP 서버 지원

CodePulse는 AI 개발 보조 프로그램 및 협업용 에이전트들이 도구 형태로 호출하여 고품질 아키텍처 처리를 수행할 수 있도록 고성능 **Model Context Protocol (MCP) 서버** 구동 인터페이스를 일체형 내장 지원합니다.

```bash
codepulse mcp          # stdio 기반 서버 구동 시작
codepulse mcp setup    # Cursor 및 Claude Desktop에 설정값 직접 등록
```

---

## 25. GitHub Actions 구성

```yaml
- name: CodePulse Review
  uses: archpulse/codepulse-cli@v5
  with:
    command: review
    github_token: ${{ secrets.GITHUB_TOKEN }}
```

---

## 26. 플러그인 확장 아키텍처

로컬 `plugins/` 또는 전역 사용자 저장소 `~/.codepulse/plugins` 경로에 타입스크립트로 정의한 아키텍처 탐색 규칙들을 드롭다운 적재하여 CodePulse의 기능을 사용자 고유 아키텍처 탐색 규칙 수준에 맞춰 무제한 확장할 수 있습니다.

---

## 27. 다국어 지원 정책 (i18n)

현재 7가지의 실시간 로케일 지원 정책을 충족합니다: 영어(`en`), 러시아어(`ru`), 우크라이나어(`ua`), 독일어(`de`), 프랑스어(`fr`), 한국어(`ko`), 체코어(`cs`).

아래와 같이 간편하게 기본 번역 설정을 스위칭할 수 있습니다:

```bash
codepulse lang ko
```

---

## 28. 시스템 종료 코드 (Exit Codes)

- `0`: 감지된 중요 결함 결여 및 정상 종료 완료
- `1`: 크리티컬 결함 위험 단계 감지 (엄격 모드, PR 스코어 임계 이탈 등 결함 발견 단계)
- `1`: 검증 실패 및 런타임 오류 감지

---

## 29. 퀵 치트 시트 (Cheat Sheet)

```bash
# 기본 모드 스캔
codepulse scan .

# 실시간 TUI 그래픽 모니터링 실행
codepulse watch .

# 타깃 브랜치 대비 품질 결함 변화 분석
codepulse diff main --threshold 5

# 리스크 히트맵 시각화 활성화
codepulse heatmap .

# 아키텍처 인젝션 명세 계획 작성
codepulse audit .

# Cursor 전용 AI 행동 강령 적용 설정
codepulse agent cursor default
```