# kadlint

> 화장품·건강기능식품 마케팅 카피를 위한 한국 광고 규정 린터 — 금지 표현을 근거 조항·심각도·대체 표현과 함께 탐지합니다.

[![npm version](https://img.shields.io/npm/v/kadlint.svg)](https://www.npmjs.com/package/kadlint)
[![CI](https://github.com/feelyday/kadlint/actions/workflows/ci.yml/badge.svg)](https://github.com/feelyday/kadlint/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/kadlint.svg)](./LICENSE)

[English README](./README.md)

## 왜 필요한가

한국의 화장품·건강기능식품 광고 규제는 까다롭습니다. 크림이 "여드름을 치료"한다고 쓰면 화장품법상 의약품 오인 광고이고, 기능성 인정을 받지 않은 유산균이 "면역력 강화"를 표방하면 부당 광고이며, "1위"·"100% 천연" 같은 표현은 표시광고법상 객관적 실증이 없으면 거짓·과장 광고입니다. 식약처는 매년 온라인 부당광고 점검에서 화장품·건강기능식품 분야의 위반 광고를 수천 건 단위로 적발·차단하고 있고(2025년 점검에서도 의약품 오인·기능성 오인 표현이 다수 적발), 적발 시 광고 정지·판매 정지·과징금 등 실질적 제재로 이어집니다.

`kadlint`는 아래 법령·지침에서 추출해 검수한 **규칙 299개**(화장품 183, 건강기능식품 51, 공통 65) 사전으로 카피를 검사합니다.

- 화장품법·화장품법 시행규칙(별표5)
- 건강기능식품법·식품표시광고법
- 표시광고법 및 공정위 고시
- 식약처 표시·광고 가이드라인 및 적발 사례

모든 발견 항목에 위반 유형, 법적 근거 조항, 심각도(`high`/`medium`/`low`), 설명, 대체 표현이 함께 제공됩니다.

## 설치

```sh
npm install -g kadlint     # CLI
npm install kadlint        # 라이브러리
```

Node.js 18 이상이 필요합니다.

## CLI

```sh
kadlint check 광고카피.txt
kadlint check ./상세페이지 --format json --min-severity high
kadlint check - < 초안.md                  # 표준입력
kadlint check 배너.html --domain cosmetics,common
```

```
광고카피.txt:1:1 [HIGH] '여드름 치료' — 의약품 오인 표현 (cos-113)
    근거: 화장품법 제13조제1항제1호, 식약처 「화장품 표시·광고 관리 지침」
    대체 표현: 피지·각질 케어로 매끈한 피부결 / (실증 보유 시) 여드름성 피부에 사용 적합

✖ 1건 발견 (high 1 · medium 0 · low 0) — 파일 1개, 규칙 299개 검사
```

- 지원 입력: `.txt`, `.md`, `.html`(태그 제거, 위치 보존), 디렉토리(재귀), `-`(표준입력)
- 종료 코드: `0` 위반 없음, `1` `--min-severity` 이상 위반 발견, `2` 사용법 오류
- literal 규칙은 글자 사이에 공백·중간점·하이픈이 끼어도 매칭합니다(`살 균`, `살·균`, `살-균` — 흔한 검열 회피 표기). `--no-normalize`로 끌 수 있습니다.

## API

```ts
import { lint, lintFile } from 'kadlint';

const result = lint('여드름 치료에 탁월한 크림', { domains: ['cosmetics'] });
for (const f of result.findings) {
  console.log(f.ruleId, f.severity, f.match, f.legalBasis, f.alternatives);
}

const fileResult = lintFile('상세페이지.html', { minSeverity: 'medium' });
```

옵션: `domains`(`cosmetics` | `health_food` | `common`), `minSeverity`, `normalize`(기본 `true`).

규칙의 `exceptions` 문구(예: 인정받은 기능성 문구를 그대로 사용하는 경우)가 매치 지점 주변 80자 내에 존재하면 심각도를 `low`로 강등하고 `note`에 사유를 남깁니다.

## MCP 서버

`kadlint-mcp`는 stdio 기반 MCP 서버로 `check_ad_copy { text, domain? }` 툴을 제공합니다. LLM이 카피를 쓰면서 바로 규정 검사를 할 수 있습니다.

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "kadlint": {
      "command": "npx",
      "args": ["-y", "kadlint", "kadlint-mcp"]
    }
  }
}
```

전역 설치했다면 간단히:

```json
{
  "mcpServers": {
    "kadlint": { "command": "kadlint-mcp" }
  }
}
```

Claude Code:

```sh
claude mcp add kadlint -- kadlint-mcp
```

또는 프로젝트의 `.mcp.json`:

```json
{
  "mcpServers": {
    "kadlint": {
      "command": "kadlint-mcp",
      "args": []
    }
  }
}
```

## 플레이그라운드

`playground/index.html`은 의존성 없는 단일 정적 페이지입니다(GitHub Pages 배포 가능). 카피를 붙여 넣으면 매치 하이라이트와 함께 위반·근거·대체 표현 카드를 보여줍니다.

## 규칙 사전 구조와 기여

규칙은 `data/*.json`에 있습니다.

```json
{
  "id": "cos-113",
  "pattern": "여드름.{0,8}(개선|치료|완화|박멸|없애|케어|예방)",
  "pattern_type": "regex",
  "violation": "의약품 오인 표현",
  "legal_basis": "화장품법 제13조제1항제1호",
  "severity": "high",
  "message": "금지 사유 설명",
  "alternatives": ["피지·각질 케어로 매끈한 피부결"],
  "exceptions": ["여드름성 피부 완화 기능성화장품 심사(보고) 효능효과"]
}
```

`data/_needs_review.json`은 아직 검증되지 않은 후보 규칙 백로그로, npm 배포에서 제외됩니다. 규칙 추가·수정 기여를 환영합니다 — 코딩이 필요 없으며, 모든 규칙은 근거 조항이 필수입니다. [CONTRIBUTING.md](./CONTRIBUTING.md)를 참고하세요.

## 면책 조항

- kadlint는 **법률 자문이 아닙니다**. 수작업으로 정리한 사전 기반의 휴리스틱 도구입니다.
- 무탐지가 적법을 보장하지 않습니다 — 패턴 매칭 특성상 false negative가 존재하고, 규정은 계속 바뀝니다.
- 광고의 최종 법적 책임은 **광고주**에게 있습니다. 중요한 카피는 반드시 전문가 검토를 거치세요.

## 로드맵

- **v0.2**: PyPI 미러(`pip install kadlint`), `_needs_review.json` 백로그 25개 규칙 검토, 식약처 지침 개정 추적 파이프라인

## 라이선스

MIT © 2026 Jungkyun Lim