# kadlint에 기여하기

kadlint의 가치는 규칙 사전의 품질에서 나옵니다. **코딩을 몰라도** 규칙을 추가·수정할 수 있고, 그런 기여가 가장 환영받습니다. 이 문서는 규칙 하나를 추가해서 PR을 올리기까지의 전 과정을 안내합니다.

## 대원칙: 근거 조항 없는 규칙은 받지 않습니다

모든 규칙은 `legal_basis`에 **실제 법령 조항 또는 공식 지침**을 인용해야 합니다. "이 표현은 위험해 보여서"는 근거가 되지 않습니다. 좋은 근거의 예:

- `화장품법 제13조제1항제1호` (의약품 오인 광고 금지)
- `화장품법 시행규칙 별표5 제2호다목`
- `건강기능식품법 제18조제1항제1호`
- `표시광고법 제3조제1항제1호` + 관련 공정위 고시
- 식약처 가이드라인 문서명 + 해당 항목

확신이 없으면 규칙을 `data/_needs_review.json`(백로그)에 추가해 주세요. 메인테이너가 검토 후 승격합니다.

## 규칙 JSON 작성법

규칙은 도메인별 파일에 들어갑니다.

- `data/cosmetics.json` — 화장품 (id 접두사 `cos-`)
- `data/health_food.json` — 건강기능식품 (id 접두사 `hf-`)
- `data/common.json` — 업종 공통(가격·후기·최상급 표현 등, id 접두사 `com-`)

항목 하나의 형태:

```json
{
  "id": "cos-184",
  "pattern": "모공\\s*축소",
  "pattern_type": "regex",
  "violation": "의약품 오인 표현(신체 개선)",
  "legal_basis": "화장품법 제13조제1항제1호, 식약처 「화장품 표시·광고 관리 지침」",
  "severity": "high",
  "message": "모공 '축소'는 신체 구조 변화를 표방하는 의약품 오인 표현입니다. 일시적 수렴 효과는 실증자료가 있으면 '일시적 모공 케어'로 표현할 수 있습니다.",
  "alternatives": ["(실증 시) 일시적으로 모공을 케어", "피부 결 정돈"],
  "exceptions": ["인체적용시험자료로 실증한 일시적 효과 표현"]
}
```

필드 설명:

| 필드 | 필수 | 설명 |
| --- | --- | --- |
| `id` | O | 도메인 접두사 + 3자리 번호. 파일 내 마지막 번호 + 1을 쓰세요. 전체에서 유일해야 합니다. |
| `pattern` | O | 잡아낼 표현. `pattern_type`이 `literal`이면 그냥 단어(예: `"여드름"`), `regex`면 정규식. |
| `pattern_type` | O | `literal` 또는 `regex`. 단어 하나면 `literal`, 변형이 많으면 `regex`. |
| `violation` | O | 위반 유형 한 줄 요약 (예: `의약품 오인 표현`). |
| `legal_basis` | O | 근거 조항. 위 대원칙 참고. |
| `severity` | O | `high`(명백한 금지), `medium`(실증 없으면 위반), `low`(주의·문맥 의존). |
| `message` | O | 왜 금지인지, 어떤 조건이면 가능한지 1~3문장. |
| `alternatives` | O | 대체 표현 배열. 없으면 빈 배열 `[]`. |
| `exceptions` | O | 허용되는 예외 문맥 배열. 없으면 `[]`. 이 문구가 매치 주변 80자 내에 있으면 심각도가 `low`로 강등됩니다. |

작성 팁:

- **literal 패턴은 정규화 매칭됩니다.** `"살균"`은 `살 균`, `살·균`, `살-균`도 자동으로 잡으므로 띄어쓰기 변형을 정규식으로 만들 필요가 없습니다.
- **regex는 JSON 문자열**이므로 백슬래시를 두 번 씁니다: `\s` → `"\\s"`.
- 정규식에는 `gu` 플래그가 자동 적용됩니다. 과하게 넓은 패턴(`.*` 등)은 피하세요 — false positive는 별도 이슈 템플릿으로 신고받을 만큼 민감한 문제입니다.

## PR 절차

1. 저장소를 포크하고 브랜치를 만듭니다: `git checkout -b rule/cos-184-모공축소`
2. 해당 JSON 파일에 규칙을 추가합니다 (기존 항목 뒤, 마지막 `]` 앞).
3. 검증을 돌립니다 (Node 18+ 필요):

   ```sh
   npm install
   npm run build
   npm test        # 사전 무결성 테스트가 JSON 문법·필수 필드·정규식 컴파일·id 중복을 검사합니다
   ```

   Node가 없다면 JSON 문법만이라도 온라인 검사기로 확인해 주세요. CI가 나머지를 검증합니다.
4. 가능하면 실제 적발 사례나 지침 원문 링크를 PR 본문에 첨부합니다.
5. PR 템플릿의 체크리스트를 채워 제출합니다.

## 규칙 외 기여

- **false positive 신고**: 정상 카피가 잘못 걸리면 [false-positive 이슈 템플릿](.github/ISSUE_TEMPLATE/false-positive.md)으로 알려 주세요.
- **새 규칙 제안만** 하고 싶다면 [rule-proposal 템플릿](.github/ISSUE_TEMPLATE/rule-proposal.md)을 쓰세요. JSON 작성은 메인테이너가 대신할 수 있습니다.
- 코드 기여는 일반적인 규칙을 따릅니다: 테스트를 추가하고 `npm test`가 통과해야 합니다.

## 행동 강령

서로 존중하고, 법 해석에 대한 이견은 근거 조항으로 이야기합니다.