# /gate - Gate 검증 (Shovel 핵심)

> **"Gate PASS만이 진실이다"**
>
> 1. lint → test → build → audit **순서 고정**
> 2. 하나라도 실패 = **0점 처리, 즉시 중단**
> 3. 통과 시 **EVIDENCE.md 자동 생성**
> 4. "됐다" 금지, **Gate PASS만이 완료**

---

## 사용법

```bash
# 전체 Gate 실행
/gate

# 스크립트 직접 실행
pnpm gate
# 또는
bash scripts/gate.sh

# 개별 단계만 (디버깅용)
/gate lint
/gate test
/gate build
/gate audit
```

---

## Gate 단계

### 순서 (고정, 변경 불가)

```
1. Lint (코드 스타일)
   ↓ 실패 시 중단
2. Test (테스트)
   ↓ 실패 시 중단
3. Build (빌드)
   ↓ 실패 시 중단
4. Audit (보안 취약점)
   ↓ Critical만 중단
━━━━━━━━━━━━━━━━━━━━
✅ GATE PASS → EVIDENCE.md 생성
```

---

## Step 1: Lint

### 실행

```bash
pnpm lint
# 또는
pnpm eslint . --ext .ts,.tsx
```

### 성공 시

```markdown
## ✅ Step 1/4: Lint PASS

| 항목 | 값 |
|------|-----|
| 파일 수 | {N} |
| 에러 | 0 |
| 경고 | {N} |
| 시간 | {X}s |

→ Step 2로 진행
```

### 실패 시

```markdown
## ❌ Step 1/4: Lint FAIL

### Gate 중단됨

```
src/{path}/{file}.ts:23:5
  error  'result' is defined but never used  @typescript-eslint/no-unused-vars
```

### 수정 방법

**자동 수정 가능:**
```bash
pnpm lint --fix
```

**수동 수정 필요:**
1. {파일}:{라인} - {설명}

### 수정 후 재실행
```bash
pnpm gate
```

⚠️ **Gate 0점 처리. 이후 단계 실행되지 않음.**
```

---

## Step 2: Test

### 실행

```bash
pnpm test
# 또는
pnpm vitest run
```

### 성공 시

```markdown
## ✅ Step 2/4: Test PASS

| 항목 | 값 |
|------|-----|
| Test Files | {N} passed |
| Tests | {M} passed |
| 커버리지 | {X}% |
| 시간 | {X}s |

→ Step 3로 진행
```

### 실패 시

```markdown
## ❌ Step 2/4: Test FAIL

### Gate 중단됨

```
FAIL  src/auth/login.test.ts
  ✕ should return 200 on valid credentials (15ms)
    Expected: 200
    Received: 401
```

### 5 Whys 분석

**Why 1**: 테스트가 왜 실패?
→ 401 응답 반환

**Why 2**: 왜 401?
→ 토큰 검증 실패

**Why 3**: 왜 검증 실패?
→ JWT_SECRET 미설정

**Why 4**: 왜 미설정?
→ .env.test 누락

**Why 5 (근본 원인)**: 
→ .env.example에 문서화 안 됨

### 수정 방법
1. `.env.example`에 JWT_SECRET 추가
2. `.env.test` 생성
3. 테스트 재실행

### 수정 후 재실행
```bash
pnpm gate
```

⚠️ **Gate 0점 처리. 이후 단계 실행되지 않음.**
```

### 테스트 없음

```markdown
## ❌ Step 2/4: Test FAIL

### Gate 중단됨

**사유**: 테스트 파일 없음

Shovel 시스템은 **최소 8개 테스트 케이스**를 요구합니다.

### 필요한 테스트
- *.test.ts 또는 *.spec.ts 파일
- 성공/실패 케이스 모두 포함
- inject 테스트 권장

### 테스트 생성 후 재실행
```bash
pnpm gate
```

⚠️ **테스트 없음 = 출시 불가**
```

---

## Step 3: Build

### 실행

```bash
pnpm build
# 또는
pnpm tsc && pnpm vite build
```

### 성공 시

```markdown
## ✅ Step 3/4: Build PASS

| 항목 | 값 |
|------|-----|
| 빌드 시간 | {X}s |
| 출력 크기 | {X}KB |
| 번들 수 | {N} |

→ Step 4로 진행
```

### 실패 시

```markdown
## ❌ Step 3/4: Build FAIL

### Gate 중단됨

```
error TS2307: Cannot find module '@/core/errors'
```

### 원인 분석
- 경로 별칭 설정 누락
- tsconfig.json paths 확인 필요

### 수정 방법
```json
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```

### 수정 후 재실행
```bash
pnpm gate
```

⚠️ **Gate 0점 처리. 이후 단계 실행되지 않음.**
```

---

## Step 4: Audit

### 실행

```bash
pnpm audit
# 또는
npm audit
```

### 성공 시

```markdown
## ✅ Step 4/4: Audit PASS

| 항목 | 값 |
|------|-----|
| 취약점 | 0 |
| Critical | 0 |
| High | 0 |

→ **GATE PASS!**
```

### 경고 (비차단)

```markdown
## ⚠️ Step 4/4: Audit WARN

| 심각도 | 개수 |
|--------|------|
| Critical | 0 |
| High | 2 |
| Moderate | 5 |

**High 취약점은 경고지만 Gate 통과됩니다.**
추후 수정 권장.

→ **GATE PASS (경고 있음)**
```

### 실패 시 (Critical)

```markdown
## ❌ Step 4/4: Audit FAIL

### Gate 중단됨

**Critical 취약점 발견**

```
lodash  <4.17.21
Severity: critical
Prototype Pollution
```

### 수정 방법
```bash
pnpm update lodash
# 또는
pnpm audit fix
```

### 수정 후 재실행
```bash
pnpm gate
```

⚠️ **Critical 취약점은 배포 불가.**
```

---

## GATE PASS: EVIDENCE.md 생성

모든 단계 통과 시 자동 생성:

```markdown
# Gate Evidence Report

> **Generated**: 2026-01-09T14:30:00Z
> **Status**: ✅ PASS

---

## 📋 Summary

| Step | Result | Details |
|------|--------|---------|
| Lint | ✅ PASS | 0 errors, 3 warnings |
| Test | ✅ PASS | 12/12 passed, 85% coverage |
| Build | ✅ PASS | 2.3s, 450KB |
| Audit | ✅ PASS | 0 vulnerabilities |

---

## 🔍 Environment

| Property | Value |
|----------|-------|
| Timestamp | 2026-01-09T14:30:00Z |
| Git Commit | `abc1234` |
| Git Branch | `feature/login` |
| Node Version | v20.10.0 |
| pnpm Version | 8.15.0 |

---

## ✅ Gate Result

```
 ██████╗  █████╗ ████████╗███████╗    ██████╗  █████╗ ███████╗███████╗
██╔════╝ ██╔══██╗╚══██╔══╝██╔════╝    ██╔══██╗██╔══██╗██╔════╝██╔════╝
██║  ███╗███████║   ██║   █████╗      ██████╔╝███████║███████╗███████╗
██║   ██║██╔══██║   ██║   ██╔══╝      ██╔═══╝ ██╔══██║╚════██║╚════██║
╚██████╔╝██║  ██║   ██║   ███████╗    ██║     ██║  ██║███████║███████║
 ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝    ╚═╝     ╚═╝  ╚═╝╚══════╝╚══════╝
```

**이 프로젝트는 Gate를 통과했습니다. 배포/납품 준비 완료.**

---

*Generated by Shovel Gate System v2*
```

---

## 최종 출력

### GATE PASS

```markdown
## ✅ GATE PASS

### Evidence
- 시각: 2026-01-09T14:30:00Z
- Commit: `abc1234`
- Branch: `feature/login`

### 결과
| 단계 | 상태 | 상세 |
|------|------|------|
| Lint | ✅ | 0 errors |
| Test | ✅ | 12/12 passed |
| Build | ✅ | 2.3s |
| Audit | ✅ | 0 critical |

### 생성된 파일
- `EVIDENCE.md` ✅

### 다음 단계
1. `/review` - 코드 리뷰
2. 커밋: `git commit -m "feat: ..."`
3. PR 생성

**Gate PASS = 완료. 커밋 가능.**
```

### GATE FAIL

```markdown
## ❌ GATE FAIL

### 실패 단계
**{단계명}** ({N}/4 단계에서 중단)

### 에러 요약
{에러 내용}

### 수정 방안
1. {수정 방법}

### 재실행
```bash
pnpm gate
```

**Gate 0점 처리. 커밋 불가.**
```

---

## Flaky 테스트 감지

테스트가 랜덤하게 성공/실패하는 경우:

```markdown
## ⚠️ Flaky Test 감지

- 1차 실행: PASS
- 2차 실행: FAIL
- 3차 실행: PASS

**이것은 테스트 버그입니다.**

결정론 위반: 동일 입력 → 동일 출력 원칙 위배

### 원인 가능성
1. 시간 의존 로직 (Date.now())
2. 랜덤 값 (Math.random())
3. 외부 API 의존
4. 테스트 순서 의존

### 해결 필수 후 Gate 재실행

⚠️ **Flaky = 버그. 재현 불가능 = 출시 불가.**
```
