balance/LINT.md

# Kotlin Lint 설정 가이드

## 개요

이 프로젝트는 Kotlin 코드 품질을 유지하기 위해 **ktlint**를 사용합니다.

## 사용 가능한 Lint 도구

### 1. ktlint (활성화됨 ✅)

Kotlin 공식 코드 스타일 가이드를 따르는 린터 및 포맷터입니다.

**특징:**
- 코드 스타일 체크
- 자동 포맷팅 기능
- Kotlin 2.2.21과 완벽 호환

### 2. detekt (현재 비활성화됨 ⚠️)

정적 코드 분석 도구로 코드 냄새, 복잡도, 잠재적 버그를 탐지합니다.

**비활성화 이유:**
- Kotlin 2.2.21과 호환성 문제
- detekt 1.23.7은 Kotlin 2.0.10까지만 지원
- 향후 detekt가 Kotlin 2.2.x를 지원하면 재활성화 예정

**활성화 방법:**
1. `build.gradle`에서 detekt 관련 주석 제거
2. Kotlin 버전을 2.0.x로 다운그레이드하거나
3. detekt 최신 버전(Kotlin 2.2.x 지원) 출시 대기

---

## 사용 가능한 Gradle Tasks

### 코드 스타일 체크

```bash
# 모든 모듈의 Kotlin 코드 스타일 체크
./gradlew ktlintCheck

# 특정 모듈만 체크
./gradlew :balance-core-api:ktlintCheck
./gradlew :storage:ktlintCheck
```

### 자동 포맷팅

```bash
# 모든 모듈의 Kotlin 코드 자동 포맷팅
./gradlew ktlintFormat

# 특정 모듈만 포맷팅
./gradlew :balance-core-api:ktlintFormat
./gradlew :storage:ktlintFormat
```

### 빌드와 함께 실행

```bash
# 빌드 전에 자동으로 ktlint 체크 실행
./gradlew clean build

# 또는
./gradlew check  # 모든 검증 태스크 실행 (ktlint 포함)
```

---

## ktlint 설정

### 1. 기본 설정 (build.gradle)

```gradle
ktlint {
    version = '1.4.1'
    android = false
    outputToConsole = true
    coloredOutput = true
    ignoreFailures = false
    filter {
        exclude('**/generated/**')
        exclude('**/build/**')
    }
}
```

### 2. .editorconfig 설정

프로젝트 루트의 `.editorconfig` 파일에서 코드 스타일을 세부 설정할 수 있습니다.

```ini
[*.{kt,kts}]
indent_size = 4
continuation_indent_size = 4
max_line_length = 120
ij_kotlin_allow_trailing_comma = true
ij_kotlin_allow_trailing_comma_on_call_site = true
```

---

## IDE 통합

### IntelliJ IDEA / Android Studio

#### 1. ktlint 플러그인 설치

1. `Preferences` → `Plugins`
2. "ktlint" 검색
3. 설치 및 재시작

#### 2. EditorConfig 활성화

1. `Preferences` → `Editor` → `Code Style`
2. "Enable EditorConfig support" 체크

#### 3. 저장 시 자동 포맷팅 (선택사항)

1. `Preferences` → `Tools` → `Actions on Save`
2. "Reformat code" 체크
3. "Optimize imports" 체크

---

## CI/CD 통합

### GitHub Actions 예시

```yaml
name: Lint Check

on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ main ]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up JDK 24
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '24'

      - name: Grant execute permission for gradlew
        run: chmod +x gradlew

      - name: Run ktlint
        run: ./gradlew ktlintCheck

      - name: Upload ktlint reports
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: ktlint-reports
          path: '**/build/reports/ktlint/'
```

---

## 일반적인 린트 규칙

### 1. 들여쓰기
- 4 스페이스 사용 (탭 사용 금지)

### 2. 최대 줄 길이
- 120자 제한

### 3. 임포트
- 와일드카드 임포트 금지 (java.util.* 제외)
- 사용하지 않는 임포트 제거

### 4. 네이밍
- 클래스: PascalCase
- 함수/변수: camelCase
- 상수: UPPER_SNAKE_CASE

### 5. 공백
- 파일 끝에 빈 줄 추가
- 클래스 본문 시작/끝에 불필요한 빈 줄 제거
- 불필요한 공백 제거

---

## 린트 위반 사항 수정

### 자동 수정 (권장)

대부분의 스타일 위반은 자동으로 수정할 수 있습니다.

```bash
./gradlew ktlintFormat
```

### 수동 수정

자동 수정이 불가능한 경우, 린트 리포트를 확인하고 수동으로 수정합니다.

**리포트 위치:**
```
build/reports/ktlint/
├── ktlintMainSourceSetCheck.txt
└── ktlintTestSourceSetCheck.txt
```

### 특정 규칙 비활성화 (비권장)

정말 필요한 경우에만 사용합니다.

```kotlin
// 한 줄 비활성화
@Suppress("ktlint:standard:max-line-length")
val veryLongVariableName = "..."

// 파일 전체 비활성화
@file:Suppress("ktlint:standard:filename")
```

---

## 커밋 전 체크리스트

코드를 커밋하기 전에 다음을 실행하세요:

```bash
# 1. 코드 포맷팅
./gradlew ktlintFormat

# 2. 린트 체크
./gradlew ktlintCheck

# 3. 빌드 및 테스트
./gradlew clean build
```

---

## Git Hook 설정 (선택사항)

커밋 전에 자동으로 ktlint를 실행하도록 설정할 수 있습니다.

### pre-commit hook 생성

`.git/hooks/pre-commit` 파일 생성:

```bash
#!/bin/sh
echo "Running ktlint check..."
./gradlew ktlintCheck

if [ $? -ne 0 ]; then
    echo "❌ ktlint check failed. Please run './gradlew ktlintFormat' to fix."
    exit 1
fi

echo "✅ ktlint check passed!"
```

실행 권한 부여:
```bash
chmod +x .git/hooks/pre-commit
```

---

## 문제 해결

### 1. ktlint 버전 호환성 문제

**증상:**
```
Class org.jetbrains.kotlin.lexer.KtTokens does not have member field...
```

**해결:**
- `build.gradle`에서 ktlint 버전을 1.4.1 이상으로 업데이트
- Kotlin 버전과 호환되는 ktlint 버전 확인

### 2. 포맷팅 후에도 체크 실패

**원인:**
- IDE와 ktlint의 포맷팅 규칙 불일치

**해결:**
```bash
# ktlint 포맷팅 사용
./gradlew ktlintFormat

# IDE 포맷팅 사용 금지 또는 .editorconfig 확인
```

### 3. 특정 파일 제외하기

`build.gradle`의 ktlint 설정 수정:

```gradle
ktlint {
    filter {
        exclude('**/generated/**')
        exclude('**/build/**')
        exclude('**/MySpecialFile.kt')  // 특정 파일 제외
    }
}
```

---

## 참고 자료

- [ktlint 공식 문서](https://pinterest.github.io/ktlint/)
- [Kotlin 코드 스타일 가이드](https://kotlinlang.org/docs/coding-conventions.html)
- [EditorConfig](https://editorconfig.org/)

---

## 향후 계획

### detekt 재활성화

Kotlin 2.2.x를 지원하는 detekt 버전이 출시되면:

1. `build.gradle`에서 주석 해제:
```gradle
apply plugin: 'io.gitlab.arturbosch.detekt'
```

2. detekt 설정 활성화

3. 정적 분석 실행:
```bash
./gradlew detekt
```

---

**최종 업데이트:** 2026-01-11
**ktlint 버전:** 1.4.1
**Kotlin 버전:** 2.2.21