lawdangle-kr 0.1.0__tar.gz

lawdangle_kr-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# 비밀: 법제처 OC 인증키
+.env
+probe_out/
+
+# 로컬 에디터/도구 설정
+.claude/

lawdangle_kr-0.1.0/DESIGN.md

@@ -0,0 +1,254 @@
+# lawdangle-kr — 설계 문서
+
+> **lawdangle-kr** — Dead Cross-Reference Detector for Korean Statutes
+> 현행 법령이 인용하는 대상 법령의 **폐지·개명·이관·사문화**를 탐지하고 5분류로 태깅한다.
+
+---
+
+## 네이밍
+
+| 용도 | 이름 | 비고 |
+|---|---|---|
+| PyPI 배포명 / 레포명 | **`lawdangle-kr`** | 스코프(한국 법령 전용)를 정직하게 표기. 법제처 API·한국 입법체계(타법개정·전부개정·폐지제정)에 종속되므로 `-kr` 명시 |
+| import 모듈명 | **`lawdangle`** | 코드 안에서는 짧게 — `from lawdangle import ...` |
+| CLI 명령 | **`lawdangle`** | `lawdangle <법령ID 또는 파일>` |
+
+- **어원:** law + *dangling reference* — 포인터/링크가 죽은 대상을 가리키는 기술 용어. 개발자에게 "법령판 dangling reference 검출기"로 즉시 전달됨.
+- **`-kr`를 붙이는 이유:** 다른 나라 법령 도구로 오해/충돌 방지 + 향후 코어(`lawdangle`) + 국가별 어댑터(`-kr`) 확장 여지.
+- **피한 형태:** `krlawdangle`(검색 불리), `lawdanglekr`(kr이 안 보임), `lawcheck`(너무 일반적, 아류로 보임).
+- **확정 전 체크:** PyPI에 `lawdangle-kr` 비어 있는지 확인 후 선점.
+- 참고: pip는 배포명의 하이픈/언더스코어를 동일 취급(`lawdangle-kr` ↔ `lawdangle_kr`)하지만 import는 불가 → **배포명 `lawdangle-kr` / import명 `lawdangle`** 분리가 깔끔.
+
+---
+
+## 0. 한 줄 정의 (README 최상단에 그대로 쓸 문장)
+
+기존 인용 검증 도구는 "인용된 조문이 **실존하느냐**"까지만 본다.
+이 도구는 "인용된 법령이 **아직 살아있는 좌표를 가리키느냐**"를 본다.
+— 즉, 폐지·개명·이관·사문화된 죽은 참조(dangling reference)를 잡는다.
+
+### 기존 도구와의 경계 (반박 차단용)
+
+| | 검증하는 것 | 예시 |
+|---|---|---|
+| 실존 검증 (예: verify_citations) | 인용하는 **쪽** 조문이 진짜냐 | "형법 제9999조" → 없음 |
+| **이 도구 (liveness)** | 인용당하는 **대상**이 폐지/개명/이관됐냐 | "「국가균형발전 특별법」 제17조제2항" → 폐지·삭제됨 |
+
+방향이 반대다. 전자는 텍스트 안의 가짜를 잡고, 후자는 텍스트 안의 죽은 참조를 잡는다.
+
+---
+
+## 1. 문제 정의
+
+현행 법령(시행령 포함)의 본문은 다른 법령을 `「법령명」 제○조제○항제○호` 형태로 인용한다.
+그런데 인용 대상 법령이 이후 개명·폐지·이관되어도, 인용하는 쪽 본문은 자동으로 갱신되지 않는다(타법개정 누락).
+그 결과 살아있는 법이 죽은/낡은 좌표를 가리키는 상태가 발생한다.
+
+**핵심 함정:** 법명 단순 치환(string replace)으로 정규화하면, 분할 이관·조문번호 변경 케이스에서 **틀린 곳을 더 틀린 곳으로** 보내는 오정정이 발생한다.
+
+---
+
+## 2. 5분류 (도구의 심장)
+
+판정 축 두 개:
+- **축1 — 대상 존재:** 인용 대상 제도/조문이 현행 체계에 존재하는가
+- **축2 — 좌표 일치:** 인용에 적힌 (법명 + 조문번호)가 현행과 일치하는가
+
+| 코드 | 유형 | 대상 존재 | 좌표 일치 | 작동 | 정비 방법 | 심각성 |
+|---|---|---|---|---|---|---|
+| **A** | 단순 개명 | O | 법명 X / 조문 O | O (해석규칙) | 법명만 교체 | 5 (낮음) |
+| **B** | 전부개정·이관 (조문 대응) | O | 법명 X / 조문 X | O (승계규칙) | 법명+조문 교체 | 4 |
+| **C** | 분할 승계 | O (1:N) | 법명 X / 조문 X | O | 호 단위 수동 매핑 | 2 (높음) |
+| **D** | 사문화 (전제 소멸) | X | — | 보통 자체조문으로 작동 | 인용부 삭제·재구성 | 3 |
+| **E** | 순수 폐지 (빈 참조) | X | — | X 가능 | 입법 보완 | 1 (최상) |
+
+### 심각성 순위 (제보/정비 우선순위)
+`E > C > D > B > A`
+판정 기준: "수범자가 본문만으로 권리·의무를 확정할 수 있는가" + "정정 난이도".
+임팩트는 **E·C·D**에 있다. A·B는 양은 많아도 단순 행정 정비.
+
+### 검증된 실증 케이스 (정답지 / 회귀 테스트 고정값)
+
+| 입력 | 인용 | 정답 | 근거 |
+|---|---|---|---|
+| 공유수면법 §13①14 | 「국가균형발전 특별법」 §17② | **B** | 제도는 「지역 산업위기 대응 및 지역경제 회복을 위한 특별법」 §10로 이관. 조문번호 §17②→§10 변경. 단순 법명치환 시 오정정(지방분권균형발전법 §17은 무관 조항) |
+| 등기특별회계법 §3 | 「국유재산관리특별회계법」 §6 | **D** | 특별회계 자체가 폐지(2007.1.1)되어 일반회계로 흡수. "그 규정에 불구하고" 특례의 전제가 소멸. 세입·세출은 자체 각 호로 작동 |
+
+> 이 2건은 `test/fixtures/`에 박아넣고, 출력이 B/D로 안 나오면 회귀 실패로 처리한다.
+
+---
+
+## 3. 파이프라인 (4단계)
+
+```
+[법령 텍스트]
+   │
+   ▼  ① 인용 추출 (Parser)
+[ {citing_law, citing_article, cited_law_name, cited_article}, ... ]
+   │
+   ▼  ② 연혁 조회 (History Resolver) — 법제처 API
+[ + {cited_law_status, successor_info, ...} ]
+   │
+   ▼  ③ 분류 (Classifier) — 5분류 + 신뢰도
+[ + {category: A~E, confidence, flag} ]
+   │
+   ▼  ④ 리포트 (Reporter)
+[CSV / JSON]
+```
+
+### 단계별 책임
+
+#### ① Parser — 인용 추출
+- 입력: 법령 본문 문자열(또는 법령 ID로 본문 fetch).
+- 추출 단위: `「(법령명)」\s*(제\d+조(의\d+)?(\s*제\d+항)?(\s*제\d+호)?)`
+- 출력: 인용 레코드 리스트. 한 조문에 여러 인용 가능.
+- 주의:
+  - 「」 안에 법령명이 아닌 게 들어오는 경우(고시명, 별표명) 필터.
+  - 조문번호 한글표기(제5조제2항) ↔ API 코드(000500...) 변환 필요. (korean-law-mcp의 변환 로직 참고 가능)
+  - 약칭(화관법 등)은 풀네임 정규화 후 조회.
+
+#### ② History Resolver — 연혁 조회
+- 입력: `cited_law_name`.
+- 법제처 OPEN API로 해당 법령의 **현재 상태**를 조회.
+- 분기에 필요한 신호 (※ 실제 필드명은 API 응답 확인 후 채울 것):
+  - `제정·개정구분` 또는 `법령상태` → 현행 / 폐지 / 타법폐지   `// TODO: 필드명`
+  - 폐지인 경우: **후속·대체법 정보**가 응답/연혁에 있는가   `// TODO: 후속법 필드 유무 확인`
+  - 개명인 경우: 옛 명칭 ↔ 현행 명칭 매핑   `// TODO`
+- 캐시: 같은 법령 반복 조회 많음 → law명 기준 캐시(TTL 24h 권장).
+
+> ⚠️ 설계 급소: A vs (B/C/D/E)를 가르는 1차 분기가 이 필드에서 나온다.
+> 폐지법의 후속법 정보가 API로 **단일하게** 떨어지면 B 자동판정 가능,
+> 후속법이 **없으면** D/E 후보, **여럿이면** C 후보. 이 떨어지는 형태를 먼저 확인할 것.
+
+#### ③ Classifier — 5분류
+- 입력: 인용 레코드 + 연혁 정보.
+- 자동 판정 가능 범위 / 수동 플래그 경계를 **명확히** 둔다.
+
+```
+판정 의사결정 트리:
+
+1. cited_law 현행 유지?
+   ├─ YES → 인용 법명이 현행명과 동일? 
+   │         ├─ YES → 정상 (분류 대상 아님)
+   │         └─ NO  → 약칭/표기차이 확인 후, 실제 개명이면 A
+   └─ NO (개명/폐지)
+        │
+        2. 개명(법인격 동일, 내용 연속)?
+        │    └─ YES → A
+        │
+        3. 폐지 → 후속법 정보 분석
+             ├─ 후속법 1개 + 인용 조문에 대응 조문 확정 가능 → B
+             ├─ 후속법 여러 개(내용 분산) → C  [FLAG: 수동 — 호 단위 매핑 필요]
+             ├─ 후속법 없음 + 인용 조항이 자체 완결(대상 없어도 결론 남) → D  [FLAG: 수동 확인]
+             └─ 후속법 없음 + 인용 효과가 적용 불능 → E  [FLAG: 수동 — 최우선 검토]
+```
+
+- **자동/수동 경계 (정직하게 둘 것):**
+  - 자동 확정: A (개명 확인), B (후속법 단일 + 조문 대응 명확)
+  - **수동 플래그 필수: C, D, E** — 이 셋은 "대상 제도가 어디로 갔는지 / 자체 완결인지 / 효과가 죽었는지"를 사람이 봐야 정확. 자동으로 단정하면 오탐.
+- 각 결과에 `confidence: high|medium|low|manual_required` 부여.
+- C/D/E를 억지로 자동 확정하지 않는 것이 이 도구의 신뢰도 핵심. (원본 시트가 "대체법 있으면 직접 찾아 메모"로 비워둔 것과 같은 이유)
+
+#### ④ Reporter — 출력
+- CSV 컬럼(권장):
+  `citing_law, citing_article, cited_law_name, cited_article, cited_status, category(A~E), confidence, successor_suggestion, flag, note`
+- 집계 요약: 전체 N건 중 A/B/C/D/E 분포 + 심각성 상위(E,C,D) 건수.
+- 이 집계표가 곧 어필/제보/정비제안의 핵심 산출물.
+
+---
+
+## 4. 모듈 구조 (Python 독립 레포 기준)
+
+```
+lawdangle-kr/
+├── README.md                  # §0 한 줄 정의 + 실증 2케이스 + 1줄 실행법
+├── pyproject.toml             # name="lawdangle-kr", pip install 가능하게
+├── src/
+│   └── lawdangle/
+│       ├── __init__.py
+│       ├── parser.py          # ① 인용 추출
+│       ├── resolver.py        # ② 법제처 API 연혁 조회 + 캐시
+│       ├── classifier.py      # ③ 5분류 (도구의 심장)
+│       ├── report.py          # ④ CSV/JSON 출력
+│       ├── models.py          # 데이터클래스: Citation, HistoryInfo, Result
+│       └── cli.py             # `lawdangle <법령ID 또는 파일>` 한 줄 실행
+├── test/
+│   └── fixtures/
+│       ├── gongyusumyeon.json  # 공유수면법 → 정답 B
+│       └── deunggi.json        # 등기특별회계법 → 정답 D
+└── examples/
+    └── sample_corpus.txt
+```
+
+### 데이터 모델 (models.py 스케치)
+
+```python
+from dataclasses import dataclass
+from enum import Enum
+
+class Category(Enum):
+    A = "rename"            # 단순 개명
+    B = "transfer_mapped"   # 이관, 조문 대응
+    C = "split_succession"  # 분할 승계
+    D = "obsolete"          # 사문화
+    E = "dangling"          # 순수 폐지(빈 참조)
+
+class Confidence(Enum):
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    MANUAL = "manual_required"
+
+@dataclass
+class Citation:
+    citing_law: str
+    citing_article: str
+    cited_law_name: str
+    cited_article: str | None
+
+@dataclass
+class HistoryInfo:
+    status: str              # 현행 / 폐지 / 타법폐지 ... // TODO: API 매핑
+    current_name: str | None # 개명 시 현행명
+    successors: list[str]    # 후속·대체법 (0개=D/E후보, 1개=B후보, N개=C후보)
+    # ... API 응답 보고 확장
+
+@dataclass
+class Result:
+    citation: Citation
+    history: HistoryInfo
+    category: Category | None
+    confidence: Confidence
+    successor_suggestion: str | None
+    note: str
+```
+
+---
+
+## 5. 구현 순서 (권장)
+
+1. **models.py** — 자료구조부터 고정. 나머지가 여기 맞춰 붙는다.
+2. **resolver.py** — 폐지법(국유재산관리특별회계법) 1건으로 API 응답 받아 **필드 매핑 확정**. ← 여기가 막히면 전체가 막힘. 제일 먼저.
+3. **classifier.py** — 의사결정 트리 구현. 단, C/D/E는 플래그만 달고 자동 단정 금지.
+4. **parser.py** — 정규식 + 조문번호 변환.
+5. **report.py + cli.py** — CSV 떨구고 한 줄 실행.
+6. **test/fixtures** — 공유수면법(B)·등기특별회계법(D) 회귀 고정.
+
+> 2번이 전체의 급소. resolver가 폐지/개명/후속법을 어떤 필드로 떨어뜨리는지 확정되면 나머지는 기계적.
+
+---
+
+## 6. 스코프 경계 (안 할 것 / 함정)
+
+- **안 할 것:** 자동 정정(법명 치환) 기능을 기본값으로 넣지 말 것. 이 도구는 "탐지·분류"까지. 자동 치환은 C/B에서 오정정을 낳으므로, 정정은 "제안(suggestion)"으로만, 적용은 사람이.
+- **함정 1:** 약칭/표기 차이(가운뎃점 ㆍ, 띄어쓰기)를 개명으로 오판 → 정규화 후 비교.
+- **함정 2:** 후속법 단일이라고 무조건 B 아님 — 조문 대응이 깨지면(조문번호 변경) A로 처리하면 틀림. B로 가되 조문 교체 필요 플래그.
+- **함정 3:** "폐지=흠결"로 단정 금지. D는 작동하고, B도 작동한다. 효력 마비는 E(+일부 D)만. 리포트에서 이 톤을 유지해야 반박당하지 않음.
+
+---
+
+## 7. 공개 전략 (요약)
+
+- **공개:** 도구(코드) + 검증된 2케이스 + 5분류 기준.
+- **비공개 유지:** 원본 6,479건 전체 분류표(자산). 도구가 있으면 재생성 가능하므로 원본을 통째로 풀 이유 없음. 공개하려면 검증 완료 후 "정제 데이터셋"으로 별도.
+- **연결:** korean-law-mcp 레포에 이슈 — "실존 검증 너머 liveness(폐지/이관) 검증" 차별점 + 본 레포 링크.

lawdangle_kr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yabooung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lawdangle_kr-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: lawdangle-kr
+Version: 0.1.0
+Summary: Dead cross-reference detector for Korean statutes
+Project-URL: Homepage, https://github.com/yabooung/lawdangle-kr
+Author: yabooung
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lawdangle-kr
+
+> **Dead Cross-Reference Detector for Korean Statutes**
+> Detects and classifies references in in-force Korean laws that point to **repealed, renamed, transferred, or obsolete** target laws.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**한국어 README → [README.ko.md](README.ko.md)**
+
+---
+
+Existing citation-checkers verify only whether *the citing article itself exists*.
+lawdangle asks a different question: **does the cited law still point at a living coordinate?** — that is, it catches *dangling references* to laws that have been repealed, renamed, transferred, or hollowed out.
+
+| | Checks | Example |
+|---|---|---|
+| Existence check | Whether the **citing** article is real | "Criminal Act art. 9999" → does not exist |
+| **lawdangle (liveness)** | Whether the **cited target** was repealed / renamed / transferred | "「National Balanced Development Special Act」 art. 17(2)" → repealed & transferred |
+
+The direction is reversed: the former catches fakes inside the text; the latter catches dead references inside the text.
+
+> **The core trap:** naive string-replacement of law names produces *mis-corrections* in split-transfer and article-renumbering cases — sending a wrong reference somewhere *more* wrong. lawdangle therefore **detects and proposes**, but never auto-applies corrections.
+
+## The five categories
+
+| Code | Type | Works? | Remedy | Severity |
+|---|---|---|---|---|
+| **A** | Simple rename | Yes | Replace name only | 5 (low) |
+| **B** | Full amendment / transfer (article mapped) | Yes | Replace name + article | 4 |
+| **C** | Split succession (1 → N) | Yes | Manual item-level mapping | 2 (high) |
+| **D** | Obsolete (premise dissolved) | Usually self-contained | Delete / restructure the citation | 3 |
+| **E** | Pure repeal (empty reference) | May break | Legislative fix | 1 (highest) |
+
+Severity ranking (remediation priority): **E > C > D > B > A**.
+**C / D / E are never auto-asserted** — they are flagged for human review with evidence attached. This restraint is the heart of the tool's reliability.
+
+### Automatic classification scope (live API)
+
+| Verdict | How | Confidence |
+|---|---|---|
+| In-force / Repealed | `target=law` · `eflaw` lookup | Auto (high) |
+| **A — Rename** | **Law-ID continuity** (old name absent, same ID alive under a new name) + **cited-article survival check** | Auto (high) |
+| **A — Official abbreviation** | Official abbreviation dictionary (`lsAbrv`, ~2,600 entries) → full name | Auto (high) |
+| **A — Truncated name** | Conservative `endswith` partial match → full name | Auto (medium) |
+| B — Rename + article moved | Renamed, but the cited article is deleted/renumbered in the current text → suggests `--map` | Auto candidate (medium) |
+| B — Transfer / C — Split | Repeal + successor candidates (addendum back-trace + amendment-reason) → article mapping is manual | Flag + candidates |
+| D — Obsolete / E — Repeal | Repeal + absorption signal (general account) / no successor | Flag |
+| Informal abbreviation (not in dictionary) | Exact match fails → UNKNOWN (mis-match avoided on purpose) | — |
+
+## Install
+
+```bash
+pip install lawdangle-kr
+```
+
+Requires Python 3.10+. Live lookups need a free **법제처(MOLEG) OPEN API** key (OC), issued at <https://open.law.go.kr>.
+
+## Quick start
+
+```bash
+# RECOMMENDED — analyze a whole statute by name (fetches the in-force body itself).
+# No copy-paste, no case-law contamination, and the citing article is filled in.
+LAW_OC=your_oc lawdangle --law "공유수면 관리 및 매립에 관한 법률" --format csv
+
+# Analyze pasted statute text
+LAW_OC=your_oc lawdangle path/to/law.txt --format summary
+
+# Offline demo (history fixtures — no API key needed)
+lawdangle examples/sample_corpus.txt \
+    --fixture test/fixtures/gongyusumyeon.json test/fixtures/deunggi.json \
+    --format csv
+
+# --deep: also map the concrete corresponding article for B / rename+moved cases
+LAW_OC=your_oc lawdangle path/to/law.txt --format csv --deep
+
+# Article-correspondence helper (old article → successor article)
+# Successor auto-discovered when omitted (works for split transfers too):
+LAW_OC=your_oc lawdangle --map "국가균형발전 특별법" "제17조제2항"
+# ...or specify the successor explicitly:
+LAW_OC=your_oc lawdangle --map "국가균형발전 특별법" "제17조제2항" \
+    "지역 산업위기 대응 및 지역경제 회복을 위한 특별법"
+```
+
+```python
+from lawdangle import run_law
+from lawdangle.resolver import LawGoKrResolver
+
+resolver = LawGoKrResolver("your_oc")
+for r in run_law("공유수면 관리 및 매립에 관한 법률", resolver):
+    if r.category:                              # skip live/normal references
+        print(r.citation.citing_article, r.citation.cited_law_name,
+              r.citation.cited_article, "→", r.category.name, "|", r.note)
+
+# Or work at the citation level directly:
+from lawdangle import parse_citations, classify
+for c in parse_citations(open("law.txt", encoding="utf-8").read()):
+    res = classify(c, resolver.resolve(c.cited_law_name))
+    print(res.category, res.note)
+```
+
+## Pipeline
+
+```
+[statute text]
+   ① Parser     extract 「law」 + article citations
+   ② Resolver   MOLEG API — current status, rename, successors (cached)
+   ③ Classifier 5-way decision tree (+ confidence, manual flag)
+   ④ Reporter   CSV / JSON / summary
+```
+
+## How successor detection works (live)
+
+The search API has no "successor law" field, but the **repealed-law detail** (`lawService.do`) does. lawdangle back-traces successors via two routes:
+
+- **Repeal-by-other-law back-trace** — when a law was repealed by another law's *addendum* (`타법폐지`), the addendum header `Addendum(<the repealing law>) … repeals 「self」` names the **repealing law = the successor**.
+  *e.g.* 저탄소 녹색성장 기본법 → 「기후위기 대응을 위한 탄소중립ㆍ녹색성장 기본법」; 국토이용관리법 → 「국토의 계획 및 이용에 관한 법률」.
+- **Amendment-reason prose** — extracts 「successor law」 names from the enactment/amendment reason (filtering out the addendum's "amendments to other laws", which are collateral, and keeping only law-shaped names).
+- **Absorption signal** (`absorbed`) — phrases like "…merged into the general account" mean *no successor law* → a strong **D** signal.
+
+Candidate count drives the class: **1 → B (transfer)**, **2+ → C (split)**, **0 + absorption → D**. All are flagged for manual confirmation.
+
+### Content-based successor discovery (split transfers)
+
+The back-traced candidate is the *law's general successor* — which often differs from the *specific provision's* successor (the split-transfer trap). For example, 국가균형발전 특별법's general successor is 「지방자치분권 및 지역균형발전에 관한 특별법」, but its art. 17(2) 산업위기대응특별지역 scheme actually moved to a **different** law: 「지역 산업위기 대응 및 지역경제 회복을 위한 특별법」.
+
+lawdangle finds that automatically: it takes the **distinctive concept terms** from the old article's text (e.g. *산업위기대응특별지역*) and searches current **law names** for them — the law that *defines* the scheme surfaces (usually a single hit), and article mapping follows. So `--map` works even when you do **not** supply the successor, and `--deep` attaches the discovered successor + article to B/C results.
+
+## Article correspondence (`--map`, `--deep`)
+
+For transfers (B), `--map` narrows "old §17(2) → which successor article?". It walks the old law's history to find the **last substantive text before deletion** (a cited article may have been deleted *before* the law itself was repealed), then ranks the successor's current articles by **text similarity**. When the citation has a paragraph (②), it further narrows **down to the paragraph** inside the top article (item-level stays manual — that is category C).
+
+```
+$ lawdangle --map "국가균형발전 특별법" "제17조제2항" "지역 산업위기 대응 및 지역경제 회복을 위한 특별법"
+
+옛 법령 : 「국가균형발전 특별법」 제17조  (substantive text from the 2022-01-13 version)
+후속법령: 「지역 산업위기 대응 및 지역경제 회복을 위한 특별법」
+판정    : manual — multiple close candidates (possible split) (paragraph: §1, sim 0.205)
+후보(by similarity):
+  1. 제10조제1항  (0.18)   ① the Minister … upon receiving a designation application …
+  2. 제12조       (0.176)  …
+  3. 제9조        (0.172)  …
+```
+
+It surfaces the design's known answer **§17(2) → art. 10** as the #1 candidate (제10조제1항), while *not* auto-confirming (arts. 9/10/12 are close — possible split) and leaving the final call to a human. That is precisely how the "mis-correction" trap is avoided.
+
+## Validated cases (regression fixtures)
+
+| Input | Citation | Answer |
+|---|---|---|
+| 공유수면법 §13①14 | 「국가균형발전 특별법」 §17② | **B** — institution transferred to 「지역 산업위기 대응 및 지역경제 회복을 위한 특별법」 |
+| 등기특별회계법 §3 | 「국유재산관리특별회계법」 §6 | **D** — special account abolished & absorbed into the general account; the citing article still works on its own |
+
+These two are pinned in `test/fixtures/`; if the output is not B / D, the regression fails.
+
+## Scope (what it deliberately does *not* do)
+
+- It **detects and classifies** only. Automatic name-substitution is not a default — corrections are emitted as *suggestions*; a human applies them. (Auto-substitution causes mis-corrections in B/C cases.)
+- It does **not** equate "repealed" with "defective". D works, B works; only E (and some D) actually breaks enforceability. The report keeps this tone so its findings hold up.
+- Informal abbreviations not in the official dictionary resolve to UNKNOWN rather than risk a wrong match.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                     # offline tests run anywhere; live API tests run only when an OC key is present
+```
+
+Live tests read the OC key from `LAW_OC` or a local `.env` (`oc=...`); without it they are skipped.
+
+See [DESIGN.md](DESIGN.md) for the full design rationale.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

lawdangle_kr-0.1.0/README.ko.md

@@ -0,0 +1,175 @@
+# lawdangle-kr
+
+> **현행 법령의 죽은 인용(dead cross-reference) 검출기**
+> 현행 법령이 인용하는 대상 법령의 **폐지·개명·이관·사문화**를 탐지하고 5분류로 태깅한다.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**English README → [README.md](README.md)**
+
+---
+
+기존 인용 검증 도구는 "인용된 조문이 **실존하느냐**"까지만 본다.
+lawdangle은 다른 질문을 던진다 — "인용된 법령이 **아직 살아있는 좌표를 가리키느냐?**" 즉, 폐지·개명·이관·사문화된 **죽은 참조(dangling reference)** 를 잡는다.
+
+| | 검증하는 것 | 예시 |
+|---|---|---|
+| 실존 검증 | 인용하는 **쪽** 조문이 진짜냐 | "형법 제9999조" → 없음 |
+| **lawdangle (liveness)** | 인용당하는 **대상**이 폐지/개명/이관됐냐 | "「국가균형발전 특별법」 제17조제2항" → 폐지·이관됨 |
+
+방향이 반대다. 전자는 텍스트 안의 가짜를 잡고, 후자는 텍스트 안의 죽은 참조를 잡는다.
+
+> **핵심 함정:** 법명을 단순 문자열 치환으로 정규화하면, 분할 이관·조문번호 변경 케이스에서 **틀린 곳을 더 틀린 곳으로** 보내는 오정정이 발생한다. 그래서 lawdangle은 **탐지·제안**만 하고, 정정을 자동 적용하지 않는다.
+
+## 5분류
+
+| 코드 | 유형 | 작동 | 정비 방법 | 심각성 |
+|---|---|---|---|---|
+| **A** | 단순 개명 | O | 법명만 교체 | 5 (낮음) |
+| **B** | 전부개정·이관 (조문 대응) | O | 법명+조문 교체 | 4 |
+| **C** | 분할 승계 (1:N) | O | 호 단위 수동 매핑 | 2 (높음) |
+| **D** | 사문화 (전제 소멸) | 보통 자체조문으로 작동 | 인용부 삭제·재구성 | 3 |
+| **E** | 순수 폐지 (빈 참조) | X 가능 | 입법 보완 | 1 (최상) |
+
+심각성 순위(정비 우선순위): **E > C > D > B > A**.
+**C / D / E는 자동 단정하지 않고** 근거를 붙여 수동 확인 플래그를 단다 — 이 절제가 이 도구의 신뢰도 핵심이다.
+
+### 자동 판정 범위 (라이브 API 기준)
+
+| 판정 | 방식 | 신뢰도 |
+|---|---|---|
+| 현행 / 폐지 | `target=law` · `eflaw` 조회 | 자동 (높음) |
+| **A — 개명** | **법령ID 연속성**(옛이름 없음 + 같은 ID가 현행에 다른 이름) + **인용 조문 생존 검증** | 자동 (높음) |
+| **A — 공식 약칭** | 공식 약칭사전(`lsAbrv`, 약 2,600건) → 풀네임 해소 | 자동 (높음) |
+| **A — 부분명(앞부분 생략)** | 보수적 `endswith` 부분일치 → 풀네임 | 자동 (중간) |
+| B — 개명+조문이동 | 개명이지만 인용 조문이 현행본에서 삭제/재번호 → `--map` 권고 | 자동 후보 (중간) |
+| B — 이관 / C — 분할 | 폐지 + 후속법 후보(부칙 역추적 + 제개정이유) → 조문대응 수동 | 수동 플래그 + 후보 |
+| D — 사문화 / E — 폐지 | 폐지 + 흡수신호(일반회계) / 후속법 없음 | 수동 플래그 |
+| 비공식 약칭(화관법 등) | 정확매칭 실패 → UNKNOWN(오매칭 회피) | — |
+
+## 설치
+
+```bash
+pip install lawdangle-kr
+```
+
+Python 3.10+ 필요. 라이브 조회에는 무료 **법제처 OPEN API** 인증키(OC)가 필요하다 — <https://open.law.go.kr> 에서 발급.
+
+## 빠른 시작
+
+```bash
+# 권장 — 법령명으로 그 법의 현행 본문을 직접 가져와 분석.
+# 붙여넣기 불필요 + 판례 혼입 없음 + 인용하는 조(citing_article)까지 채워짐.
+LAW_OC=your_oc lawdangle --law "공유수면 관리 및 매립에 관한 법률" --format csv
+
+# 텍스트 파일 분석
+LAW_OC=your_oc lawdangle path/to/law.txt --format summary
+
+# 오프라인 데모 (연혁 fixture — API 키 불필요)
+lawdangle examples/sample_corpus.txt \
+    --fixture test/fixtures/gongyusumyeon.json test/fixtures/deunggi.json \
+    --format csv
+
+# --deep: B·개명+조문이동 건에 구체 대응 조문까지 매핑
+LAW_OC=your_oc lawdangle path/to/law.txt --format csv --deep
+
+# 조문 대응 도우미 (옛 조문 → 후속법 조문)
+# 후속법 생략 시 자동 발견(분할 이관도 OK):
+LAW_OC=your_oc lawdangle --map "국가균형발전 특별법" "제17조제2항"
+# ...또는 후속법을 직접 지정:
+LAW_OC=your_oc lawdangle --map "국가균형발전 특별법" "제17조제2항" \
+    "지역 산업위기 대응 및 지역경제 회복을 위한 특별법"
+```
+
+```python
+from lawdangle import run_law
+from lawdangle.resolver import LawGoKrResolver
+
+resolver = LawGoKrResolver("your_oc")
+for r in run_law("공유수면 관리 및 매립에 관한 법률", resolver):
+    if r.category:                              # 현행/정상 인용은 건너뜀
+        print(r.citation.citing_article, r.citation.cited_law_name,
+              r.citation.cited_article, "→", r.category.name, "|", r.note)
+
+# 인용 단위로 직접 다룰 수도 있다:
+from lawdangle import parse_citations, classify
+for c in parse_citations(open("law.txt", encoding="utf-8").read()):
+    res = classify(c, resolver.resolve(c.cited_law_name))
+    print(res.category, res.note)
+```
+
+## 파이프라인
+
+```
+[법령 텍스트]
+   ① Parser     「법령」 + 조문 인용 추출
+   ② Resolver   법제처 API — 현행/개명/후속법 (캐시)
+   ③ Classifier 5분류 의사결정 트리 (+ 신뢰도, 수동 플래그)
+   ④ Reporter   CSV / JSON / 요약
+```
+
+## 후속법 자동 추출 (라이브)
+
+검색 API에는 후속·대체법 필드가 없지만, **폐지법률 상세(`lawService.do`)** 에 단서가 있다. resolver는 두 경로로 후속법을 역추적한다.
+
+- **타법폐지 역추적** — 다른 법의 부칙으로 폐지(`타법폐지`)된 경우, 폐지본의 부칙 헤더 `부칙(폐지시킨 법) … 「self」은 폐지한다` 에서 **폐지시킨 법 = 후속법**을 직접 추출.
+  *예)* 저탄소 녹색성장 기본법 → 「기후위기 대응을 위한 탄소중립ㆍ녹색성장 기본법」; 국토이용관리법 → 「국토의 계획 및 이용에 관한 법률」.
+- **제개정이유 산문** — 이유서의 「후속법」 추출 (부칙 '다른 법률의 개정'은 부수개정이라 제외, 법명형 꼬리말만).
+- **흡수 신호**(`absorbed`) — "…일반회계로 통합" 같은 회계 흡수 표현 → 후속'법' 없음 = **D 강신호**.
+
+후보 개수로 분류: **1개 → B(이관)**, **2개+ → C(분할)**, 0개+흡수 → D. 모두 수동 플래그.
+
+### 본문 기반 후속법 발견 (분할 이관)
+
+역추적한 후보는 *법 전체의 일반 승계자*라 **특정 조항의 승계자와 다를 수 있다**(분할 이관 함정). 예) 국가균형발전 특별법의 일반 승계자는 「지방자치분권 및 지역균형발전에 관한 특별법」이지만, §17②의 산업위기대응특별지역 제도는 **전혀 다른 법** 「지역 산업위기 대응 및 지역경제 회복을 위한 특별법」으로 갔다.
+
+lawdangle은 이걸 자동으로 찾는다: 옛 조문 본문에서 **특징 개념어**(예: *산업위기대응특별지역*)를 뽑아 현행 **법령명**을 검색 → 그 제도를 *정의하는* 법이 떠오르고(대개 1건), 조문 매핑이 이어진다. 그래서 `--map`은 후속법을 **안 줘도** 동작하고, `--deep`은 발견한 후속법+조문을 B/C 결과에 붙인다.
+
+## 조문 대응 반자동 매핑 (`--map`, `--deep`)
+
+이관(B)에서 "옛 §17② → 후속법 어느 조문?"을 좁혀준다. 옛 법 연혁을 거슬러 **삭제 전 실본문**을 찾고(조문이 폐지 전 이미 삭제된 경우 대비), 후속법 현행 조문과 **본문 유사도**로 순위를 매긴다. 인용에 항(②)이 있으면 최상위 후속 조 안에서 **항 단위까지** 좁힌다(호 단위는 설계상 수동 — C).
+
+```
+$ lawdangle --map "국가균형발전 특별법" "제17조제2항" "지역 산업위기 대응 및 지역경제 회복을 위한 특별법"
+
+옛 법령 : 「국가균형발전 특별법」 제17조  (실본문 20220113 시행본)
+후속법령: 「지역 산업위기 대응 및 지역경제 회복을 위한 특별법」
+판정    : 수동확인 — 복수 후보 경합(분할 승계 가능) (항 정밀화: 제1항 유사도 0.205)
+후보(유사도순):
+  1. 제10조제1항  (0.18)   ① 산업통상부장관은 … 지정 신청을 받은 경우에는 …
+  2. 제12조       (0.176)  …
+  3. 제9조        (0.172)  …
+```
+
+DESIGN의 정답 **§17②→§10**을 #1 후보(제10조제1항)로 제시하면서, §9·§10·§12가 근소 경합이라 **자동 확정하지 않고**(분할 승계 가능) 사람의 최종 대조로 넘긴다. 이것이 "틀린 곳을 더 틀린 곳으로 보내는 오정정"을 피하는 방식이다.
+
+## 검증된 실증 2케이스 (회귀 고정값)
+
+| 입력 | 인용 | 정답 |
+|---|---|---|
+| 공유수면법 §13①14 | 「국가균형발전 특별법」 §17② | **B** — 제도가 「지역 산업위기 대응 및 지역경제 회복을 위한 특별법」으로 이관 |
+| 등기특별회계법 §3 | 「국유재산관리특별회계법」 §6 | **D** — 특별회계 폐지·일반회계 흡수, 인용 조문은 자체 각 호로 작동 |
+
+이 2건은 `test/fixtures/`에 고정되어 있고, 출력이 B / D가 아니면 회귀 실패로 처리한다.
+
+## 스코프 경계 (의도적으로 안 하는 것)
+
+- 이 도구는 **탐지·분류**까지다. 자동 정정(법명 치환)은 기본 제공하지 않는다 — 정정은 *제안*으로만 내고, 적용은 사람이. (자동 치환은 B/C에서 오정정을 낳는다.)
+- "폐지=흠결"로 단정하지 않는다. D도 B도 작동한다. 효력 마비는 E(+일부 D)뿐 — 리포트는 이 톤을 유지해 반박당하지 않는다.
+- 공식 사전에 없는 비공식 약칭은 잘못 매칭하느니 UNKNOWN으로 둔다.
+
+## 개발
+
+```bash
+pip install -e ".[dev]"
+pytest                     # 오프라인 테스트는 어디서나; 라이브 API 테스트는 OC 키 있을 때만
+```
+
+라이브 테스트는 `LAW_OC` 환경변수 또는 로컬 `.env`(`oc=...`)에서 키를 읽고, 없으면 건너뛴다.
+
+자세한 설계는 [DESIGN.md](DESIGN.md) 참조.
+
+## 라이선스
+
+MIT — [LICENSE](LICENSE) 참조.