# Breaking Change Rule Engine 설계

## 1. 개요

Structured Diff JSON을 입력받아 **코드 기반**으로 Breaking Change 여부를 판단한다.
LLM을 사용하지 않으며, 결과는 완전히 deterministic하다.

> **카탈로그 맥락에서의 Breaking 정의**: `custom-values.yaml`을 수정해야 하는 상황.
> 카탈로그는 신규 배포를 위한 차트 보관소이며, 운영 클러스터 직접 변경과 무관하다.
> Breaking 판단의 기준은 "기존 `custom-values.yaml`이 새 차트 버전에서 유효한가?"이다.

> 설계 의도: LLM이 "이건 Breaking인 것 같아"라고 추론하는 대신, 코드가 명확한 기준으로 판단한다.

---

## 2. Breaking Change 판단 기준

### 2.0 공통 원칙

모든 values 관련 규칙에서 **`custom-values.yaml`에 해당 key가 존재하는지 여부**가 breaking 판단의 핵심 조건이다.

- `custom-values.yaml`이 없거나 해당 key를 사용하지 않는 경우 → `warning`으로 처리 (실제 수정 불필요)
- `custom-values.yaml`에 해당 key가 존재하는 경우 → `breaking`으로 처리 (수정 필요)

### 2.1 Values 관련

| 조건 | 판정 | 조건 상세 |
|------|------|---------|
| values key 삭제 | ✅ Breaking | 해당 key가 `custom-values.yaml`에 **있을** 때 — 기존 override가 무시됨 |
| values key 삭제 | ⚠️ Warning | 해당 key가 `custom-values.yaml`에 **없을** 때 (또는 custom-values.yaml 없음) |
| values type 변경 | ✅ Breaking | 해당 key가 `custom-values.yaml`에 **있을** 때 — 파싱 오류 또는 예상치 못한 동작 |
| values type 변경 | ⚠️ Warning | 해당 key가 `custom-values.yaml`에 **없을** 때 |
| values key 추가 | ℹ️ Info | 항상 — 신규 기능, 필요 시 custom-values.yaml에 추가 검토 |
| default 값 변경 | ⚠️ Warning | custom-values.yaml에서 명시적으로 override하지 않는 경우 동작 변경 가능 |

> **`custom-values.yaml` 없는 차트**: 해당 차트에 custom override가 없으므로 values 삭제는 모두 `warning`으로 처리.

### 2.2 Template / 리소스 관련

카탈로그 맥락에서 Template 변경은 `custom-values.yaml` 수정 요인이 아니므로 **Warning**으로 처리한다.
담당자가 신규 배포 시 참고할 수 있도록 업그레이드 주의사항 문서에 기록한다.

| 조건 | 판정 | 이유 |
|------|------|------|
| Service port 변경 | ⚠️ Warning | 카탈로그 신규 배포 시 주의사항. custom-values.yaml에서 port override 가능 |
| Service type 변경 (ClusterIP → NodePort 등) | ⚠️ Warning | 네트워크 구성 변경 필요, 주의사항으로 기록 |
| Deployment selector 변경 | ⚠️ Warning | 재배포 시 주의사항. custom-values.yaml 수정 요인 아님 |
| StatefulSet selector 변경 | ⚠️ Warning | 동일 |
| StatefulSet volumeClaimTemplate 변경 | ⚠️ Warning | 동일 |
| container 이름 변경 | ⚠️ Warning | 참조 변경 필요, 주의사항 기록 |
| 리소스 삭제 | ⚠️ Warning | 의존 서비스 변경 필요, 주의사항 기록 |
| resource limits 변경 | ℹ️ Info | 참고 사항 |
| replicas 기본값 변경 | ℹ️ Info | custom-values.yaml에서 명시적 설정 시 영향 없음 |

### 2.3 CRD 관련

CRD 변경은 기존 Custom Resource의 유효성에 영향을 미치므로 Breaking으로 처리한다.

| 조건 | 판정 | 이유 |
|------|------|------|
| CRD field 삭제 | ✅ Breaking | 기존 CR의 해당 필드 손실 |
| required field 추가 | ✅ Breaking | 기존 CR validation 실패 |
| storage version 변경 | ✅ Breaking | migration 없이 롤백 불가 |
| conversion webhook 제거 | ✅ Breaking | 구버전 API 호출 실패 |
| field 추가 (optional) | ❌ Not Breaking | 하위 호환 |
| schema 제약 완화 | ❌ Not Breaking | 기존 CR은 계속 유효 |

### 2.4 Dependency 관련

서브차트의 values를 `custom-values.yaml`에서 override하는 경우에만 breaking이다.

| 조건 | 판정 | 조건 상세 |
|------|------|---------|
| 하위 chart major version 변경 | ✅ Breaking | `custom-values.yaml`에 해당 subchart prefix key가 **있을** 때 (예: `postgresql.*`) |
| 하위 chart major version 변경 | ⚠️ Warning | `custom-values.yaml`에 해당 subchart 관련 key가 **없을** 때 |
| 하위 chart 제거 | ⚠️ Warning | 항상 — 주의사항으로 기록 |
| 하위 chart 추가 | ℹ️ Info | 항상 — 신규 리소스 생성만 발생 |

### 2.5 Deprecated K8s API 감지

| 조건 | 판정 | 이유 |
|------|------|------|
| Deprecated API 사용 (extensions/v1beta1 등) | ⚠️ Warning | K8s 버전에 따라 영향 있을 수 있음 |

감지 방법: `helm template` 결과의 `apiVersion` 필드를 K8s deprecated API 목록과 대조.

---

## 3. Rule Engine 출력

## 2.6 Rule 우선순위 및 충돌 처리

- 동일 리소스에 여러 Rule이 매칭되면 **가장 높은 severity**를 최종 severity로 채택한다.
- reasons는 모두 남기되, `severity`는 max 기준으로 집계한다.
- `breaking=true`는 `reasons`에 항목이 하나라도 있을 때만 설정된다.

### 3.1 기본 출력

```json
{
  "breaking": true,
  "severity": "high",
  "reasons": [
    {
      "type": "values_key_removed",
      "key": "ingress.enabled",
      "detail": "custom-values.yaml에서 사용 중인 key가 삭제됨 — custom-values.yaml 수정 필요"
    }
  ],
  "warnings": [
    {
      "type": "service_port_changed",
      "resource": "Service/airflow-webserver",
      "detail": "port changed from 8080 to 8081 — 신규 배포 시 참고"
    },
    {
      "type": "values_key_removed",
      "key": "old_setting",
      "detail": "custom-values.yaml에서 사용하지 않는 key 삭제 — 수정 불필요"
    }
  ]
}
```

### 3.2 severity 정의

| severity | 조건 |
|----------|------|
| `critical` | CRD storage version 변경 |
| `high` | custom-values.yaml에서 사용 중인 values key 삭제/타입 변경, CRD required field 추가 |
| `medium` | custom-values.yaml에서 사용 중인 subchart dependency major version 변경 |
| `warning` | Deprecated API 사용, 미사용 values key 삭제, template 변경 (port, resource 등) |

---

## 4. 확장 방법

새로운 Breaking 조건을 추가하려면 Rule 정의 파일에 항목을 추가한다.
각 Rule은 다음 인터페이스를 구현한다:

```python
class BreakingRule:
    name: str
    severity: str  # critical / high / medium / warning

    def check(self, diff: StructuredDiffJSON, custom_keys: set[str]) -> list[BreakingReason]:
        ...
```

Rule 목록은 설정 파일(`rules.yaml`)로 활성화/비활성화 가능하도록 설계한다.

---

## 5. 관련 문서

- [01-helm-diff-engine.md](01-helm-diff-engine.md) — Structured Diff JSON 생성
- [03-llm-summarizer.md](03-llm-summarizer.md) — Breaking Change 결과를 LLM에 전달
- [04-skill-interface.md](04-skill-interface.md) — `breaking_change_check` Skill 인터페이스