quad/.claude/tools/doc-check.py

#!/usr/bin/env python3
"""
.claude/ 코퍼스 기계 점검 — 깊은 수동 감사가 반복되는 걸 막기 위한 도구.

배경: 2026-08-13 일곱/여덟 번째 세션에 6+6라운드 수동 감사를 돌려 총 39+16건을
찾았는데, **그중 대부분이 grep으로 잡히는 종류**였음(옮겨간 절을 가리키는 참조,
색인 누락, 날짜 없는 "아직 안 함" 주장). 사람/에이전트의 성실성에 기대는 대신
기계가 매번 같은 걸 확인하게 함.

실행:  python3 .claude/tools/doc-check.py
       python3 .claude/tools/doc-check.py --quiet   # 실패한 검사만
종료코드: 오류(ERROR)가 하나라도 있으면 1, 경고만 있으면 0.

검사 항목  ([2026-08-16 정정] 1·2번의 심각도를 실제 코드에 맞춰 고침 —
           예전엔 둘 다 [ERROR]라고 적어놨지만 코드는 그렇게 동작한 적이 없음)
  1. [ERROR/WARN] 깨진 파일 참조 — 라이브 문서가 가리키는 .md/.luau가 실제로
     없음. 파일명이 이 레포의 명명 관례(`OURS`)에 걸리면 ERROR, 아니면
     외부 문서명일 수 있어 WARN.
  2. [ERROR] 깨진 절 참조 — `foo.md` "절 제목" 이 그 파일에 없음
     (문서를 쪼개거나 헤딩을 고칠 때 가장 잘 걸리는 것 — 아홉 번째 세션에
      bind-system-plan.md를 분할하며 20곳이 여기 걸렸음)
     [2026-08-16] 판정 규칙은 `BOLD_LEAD` 주석과 `conventions.md`의
     "절 인용 규약"이 소스 — `#` 헤딩은 부분문자열, `**볼드**` 절은 줄머리 +
     앞부분일치. 예전엔 `#` 헤딩만 읽어서 볼드 절 인용을 전부 오탐으로
     냈고(78건 중 30건), "의역 인용 관례 때문에 오탐이 섞인다"며 WARN에
     묶여 있었다. 의역 인용을 규약으로 금지하고 불일치를 78→0으로 정리한
     뒤 ERROR로 승격함.
  3. [ERROR] 색인 누락 — base/research/archive/reference 파일이 README에 없음
  4. [WARN]  날짜 없는 시한부 주장 — "아직 안 돌려봄", "열린 질문 없음" 등
     시간이 지나면 거짓이 되는데 언제 기준인지 안 적힌 문장
  5. [WARN]  미반영 배너를 단 파일 vs 반영 목록 일치 여부

검사 대상에서 제외되는 폴더는 `SKIP_DIRS`가 소스 — `session/`(원문 보존),
`initreq/`(읽기 전용 클론), `worktrees/`, `tools/`(이 스크립트 자신이 여기
있으므로 **doc-check.py는 자기 자신을 검사하지 않음**, 이 docstring의 주장은
사람이 손으로 확인해야 함).
`archive/`와 `.claude/session-summary.md`는 검사 대상이되 **히스토리 문서**라
절 참조/시한부 주장 검사는 면제(`is_history()` 참고).
"""
import os, re, sys, collections

ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
CLAUDE = os.path.join(ROOT, '.claude')
SKIP_DIRS = ('session', 'initreq', 'worktrees', 'tools')

errors, warns = [], []


def live_docs():
    out = []
    for base in (CLAUDE, ROOT):
        for dp, dn, fn in os.walk(base):
            rel = os.path.relpath(dp, ROOT)
            if any(p in rel.split(os.sep) for p in SKIP_DIRS):
                dn[:] = []
                continue
            if base is ROOT and rel != '.' and not rel.startswith('.claude'):
                continue
            for f in fn:
                if f.endswith('.md'):
                    out.append(os.path.join(dp, f))
        if base is ROOT:
            break
    # 루트 md 직접 추가
    for f in ('CLAUDE.md', 'ROADMAP.md', 'HUMAN_TODO.md', 'SAFETY.md'):
        p = os.path.join(ROOT, f)
        if os.path.exists(p):
            out.append(p)
    return sorted(set(out))


def rel(p):
    return os.path.relpath(p, ROOT)


# ---------- 1 & 2: 참조 무결성 ----------
# `(경로/)파일.md` 또는 `파일.luau`  (+ 바로 뒤에 "절 제목"이 오면 절 검사도)
# [2026-08-14] 파일명과 "절 제목"이 **줄바꿈에 걸쳐 있어도** 잡도록 개행 허용.
# 예전엔 줄 단위로 돌려서 `base/\nbind-system-plan.md`의 "Length/Offset" 같은
# 자연스러운 줄바꿈 인용을 통째로 놓쳤고, 실제로 문서 분할 후 stale 참조
# 20여 곳이 이 사각지대로 빠져나갔음(14차 세션 리뷰에서 발견).
# [2026-08-16] 인용 길이 상한을 60→160자로 넓힘. 60자를 넘는 절 인용은 매치
# 자체가 안 걸려 **검사에서 조용히 빠져나갔다** — 위양성보다 나쁜 종류의 구멍.
REF = re.compile(r'`\.?/?((?:[\w.-]+/\s*)*[\w.@-]+\.(?:md|luau))`(\s*(?:의\s*)?"([^"]{2,160})")?')

def resolve(target, src):
    """참조 문자열을 실제 경로로 해석 — 상대/부분 경로를 관대하게 매칭."""
    cands = [
        os.path.join(ROOT, target),
        os.path.join(CLAUDE, target),
        os.path.join(os.path.dirname(src), target),
    ]
    for c in cands:
        if os.path.exists(c):
            return c
    # 파일명만으로 찾히면 인정(initreq 포함 — 읽기 전용 클론이지만 실재함)
    name = os.path.basename(target)
    for dp, dn, fn in os.walk(CLAUDE):
        if 'worktrees' in os.path.relpath(dp, ROOT).split(os.sep):
            dn[:] = []
            continue
        if name in fn:
            return os.path.join(dp, name)
    return None


# 이 레포의 문서 명명 관례 — 여기 걸리면 "우리 문서"이므로 못 찾으면 ERROR.
# 안 걸리면 외부 문서명(Compose 가이드라인 등)일 수 있어 WARN으로 낮춤.
OURS = re.compile(r'(-plan|-reversed|-rejected|-findings|-map|-audit|-verification'
                  r'|^README|^STATUS|^CLAUDE|^ROADMAP|^HUMAN_TODO|^SAFETY'
                  r'|^question|^architecture|^agent-mistake'
                  # [2026-08-16] CLAUDE.md 분할 산물. 여기 안 넣으면 이 파일들로
                  # 가는 깨진 참조가 ERROR가 아니라 WARN으로만 잡힌다 — 일곱 번째
                  # 세션에 store-semantics.md에서 실제로 당했던 사각지대.
                  r'|^conventions|^project-context|^todos|^session-summary)\.md$')


# [2026-08-16] 이 코퍼스의 "절"은 `#` 헤딩만이 아니다 — `**볼드**`로 시작하는
# 줄을 하위 절로 쓰고, 다른 문서들이 그걸 "절"이라 부르며 인용해왔다. 그걸
# 안 읽어서 절 참조 WARN 상당수가 위양성이었음 — 라운드별 실측 수치는
# `session/2026-08-16-03-doc-check-section-convention.md`가 소스(여기 복제 안 함).
#
# 다만 볼드를 통째로 절 제목으로 인정하면 검사가 장식이 된다 — 실측상 볼드는
# `#` 헤딩보다 압도적으로 흔하고 대부분은 그냥 강조다. 인용이 무관한 강조
# 스팬에 우연히 걸리면 검사가 조용히 통과해버려 진짜 rot을 놓친다. 그래서
# 규칙을 비대칭으로 둔다:
#   - `#` 헤딩  : **부분문자열** 인용 허용 (명시적 절 마커라 오인 위험 없음)
#   - `**볼드**` 절: 빈 줄 다음이나 리스트 항목 머리에 있고, 인용이 제목
#                    **앞부분부터**일 때만 인정
# 이 비대칭이 곧 `conventions.md`의 "절 인용 규약"이다. 느슨한 규칙과 해소
# 건수는 같으면서 매칭 표면만 좁다는 걸 실측으로 확인하고 채택했다.
# 절 제목으로 인정하는 볼드는 **빈 줄 다음** 또는 **리스트 항목**뿐이다.
# 그냥 "줄머리 볼드"로 두면 **문단이 줄바꿈되며 우연히 줄머리에 걸린 강조**까지
# 절로 잡힌다 — `architecture.md`의 `**pluggable 디스패치 엔진 자체도 …**`가
# 실제 사례로, 진짜 절은 두 줄 위의 `**패키지 경계**`인데 두 문서가 그 우연한
# 자리를 절이라며 인용하고 있었다(커밋 전 감사가 잡음).
# 리스트 마커는 `-`/`*`/`>`뿐 아니라 `1.`도 인정 — `conventions.md`의 핸드오버
# 체크리스트처럼 **번호 항목 자체가 절**이고 다른 문서가 그걸 인용하는 형태가 있다.
BOLD_LEAD = re.compile(
    r'(?:\A|\n[ \t]*\n)[ \t]{0,6}\*\*(.+?)\*\*'                    # 빈 줄 다음
    r'|(?:\A|\n)[ \t]{0,6}(?:[-*>]|\d+\.)[ \t]+\*\*(.+?)\*\*',     # 리스트 항목
    re.S)
# 선두 장식(⚠️/⭐ 등)은 인용할 때 관례적으로 생략되므로 양쪽에서 벗겨내고 비교
DECOR = re.compile(r'^[^\w가-힣`(\[]+')
# 선두 상태/날짜 태그(`[2026-08-16 신설]`, `[해소됨, …]`)도 제목의 일부가 아니다 —
# 시간이 지나면 내용이 바뀌는 메타 표시라 여기에 인용을 묶으면 태그가 갱신될 때마다
# 참조가 깨진다. 양쪽에서 똑같이 벗겨내므로 태그째 인용해도 여전히 매칭된다.
TAG = re.compile(r'^\[[^\]]{2,80}\]\s*')


def norm_section(s):
    """절 제목/인용문을 비교 가능한 형태로 정규화."""
    s = re.sub(r'\s+', ' ', re.sub(r'[`*]', '', s)).strip()
    s = DECOR.sub('', s).strip()
    stripped = DECOR.sub('', TAG.sub('', s)).strip()
    return stripped or s   # 태그가 제목 전부였다면 원본을 남긴다


def squash(s):
    """비교 전용 — 정규화 후 공백까지 전부 제거(줄바꿈 인용 대응)."""
    return re.sub(r'\s+', '', norm_section(s))


def headings(path):
    if not path.endswith('.md') or not os.path.exists(path):
        return None
    hs = []
    for line in open(path, encoding='utf-8'):
        if line.startswith('#'):
            # 백틱/강조 표기는 인용할 때 자주 빠지므로 정규화해서 비교
            hs.append(norm_section(line.lstrip('#')))
    return hs


def bold_leads(path):
    """줄머리 `**볼드**` 절 제목. 위 BOLD_LEAD 주석의 비대칭 규칙 참고."""
    if not path.endswith('.md') or not os.path.exists(path):
        return []
    txt = open(path, encoding='utf-8').read()
    return [norm_section(a or b) for a, b in BOLD_LEAD.findall(txt)]


def interesting(target):
    """검사 가치가 있는 참조인가.

    제외: (a) `initreq/`(읽기 전용 클론, gitignore됨), (b) 아직 존재하지 않는
    **미래 소스 트리**의 `.luau`(구현 시작 전이라 당연히 없음 — `architecture.md`가
    설계로서 적어둔 것), (c) `YYYY-MM-DD-NN-slug.md` 같은 템플릿 자리표시자.
    실제로 지금 존재해야 하는 건 `.md` 문서와 `luau-test/`의 스파이크뿐.
    """
    if 'YYYY' in target:
        return False
    if target.endswith('.luau'):
        return 'luau-test' in target or re.match(r'^\d\d-', os.path.basename(target))
    return True


def is_history(path):
    """히스토리 문서인가 — 절 참조/시한부 주장 검사를 면제한다.

    `archive/`는 뒤집힌 결정의 원문 보존, `session-summary.md`는 세션별
    과거 기록이라 둘 다 "그때는 그렇게 적었다"가 정상이다. 여기에 현재형
    검사를 걸면 영원히 안 꺼지는 WARN만 쌓인다.
    [2026-08-16] CLAUDE.md 분할로 세션 히스토리가 별도 파일이 되면서 추가.
    """
    r = rel(path)
    return '/archive/' in r or os.path.basename(r) == 'session-summary.md'


def check_refs(docs):
    hcache = {}
    for d in docs:
        # 히스토리 문서는 절 참조까지 강제하지 않음(파일 존재만)
        is_archive = is_history(d)
        # 줄 단위가 아니라 **파일 전체**를 한 번에 스캔 — 파일명/절 제목이
        # 줄바꿈에 걸친 인용도 잡기 위함(위 REF 주석 참고). 줄 번호는 매치
        # 시작 오프셋으로 역산.
        text = open(d, encoding='utf-8').read()
        for m in REF.finditer(text):
            ln = text.count('\n', 0, m.start()) + 1
            target, _, section = m.group(1), m.group(2), m.group(3)
            target = re.sub(r'\s+', '', target)
            if section is not None:
                section = re.sub(r'\s+', ' ', section).strip()
            if not interesting(target):
                continue
            p = resolve(target, d)
            if p is None:
                name = os.path.basename(target)
                msg = f"{rel(d)}:{ln}  깨진 파일 참조 → `{target}`"
                (errors if OURS.search(name) else warns).append(
                    msg if OURS.search(name) else msg + " (외부 문서명일 수 있음)")
                continue
            # `initreq/`를 가리키는 인용은 절 검사 제외 — 읽기 전용 외부 원본이라
            # 절 구조가 없다(`raw-userinput.md`는 스스로 "정리가 없는 생각의 흐름"
            # 이라고 밝힌 원문). 저기로 가는 인용은 절 제목이 아니라 원문 문장을
            # 따오는 것이므로 헤딩과 대조하는 게 애초에 의미가 없다.
            if section and not is_archive and p.endswith('.md') \
                    and 'initreq' not in rel(p).split(os.sep):
                if p not in hcache:
                    hcache[p] = (headings(p) or [], bold_leads(p))
                heads, leads = hcache[p]
                # 공백을 뺀 형태로 비교 — 인용이 줄바꿈에 걸리면 원문엔 없는
                # 공백이 끼어든다(`canExecute/\nunbindLifetime` → "canExecute/
                # unbindLifetime"). 이것 때문에 실재하는 절이 불일치로 잡혔음.
                core = squash(section)
                if not (any(core in squash(h) for h in heads)
                        or any(squash(s).startswith(core) for s in leads)):
                    # [2026-08-16] WARN → ERROR로 승격. 예전엔 "절 제목을
                    # 의역해 인용하는 관례" 탓에 오탐이 섞여 WARN이었지만,
                    # `conventions.md`의 "절 인용 규약"이 의역을 금지하고
                    # 불일치를 78→0으로 정리한 뒤 게이트로 올렸다. 문서를
                    # 쪼개거나 헤딩을 고칠 때 여기가 제일 먼저 걸린다.
                    errors.append(
                        f"{rel(d)}:{ln}  절 참조 불일치 → {os.path.basename(p)}에 "
                        f'"{section}" 절 없음')


# ---------- 3: 색인 누락 ----------
def check_index():
    readme = os.path.join(CLAUDE, 'README.md')
    if not os.path.exists(readme):
        errors.append("`.claude/README.md`가 없음")
        return
    txt = open(readme, encoding='utf-8').read()
    for sub in ('base', 'research', 'archive', 'reference'):
        d = os.path.join(CLAUDE, sub)
        if not os.path.isdir(d):
            continue
        for f in sorted(os.listdir(d)):
            if f.endswith('.md') and f'`{f}`' not in txt:
                errors.append(f"README 색인 누락 → {sub}/{f}")


# ---------- 4: 날짜 없는 시한부 주장 ----------
TEMPORAL = [
    (r'아직 (?:사용자가 )?안 돌려\S*', '실행 여부 주장'),
    (r'결과 미확인', '실행 여부 주장'),
    (r'열린 질문(?:은)? 없(?:음|다)', '완결 주장'),
    (r'더 이상 (?:막힌|열려있는|열려 있는)\S* 없\S*', '완결 주장'),
    (r'남은 (?:유일한|건)[^\n]{0,20}뿐', '완결 주장'),
    (r'전부 확정됨', '완결 주장'),
]
DATED = re.compile(r'20\d\d-\d\d-\d\d|\[\s*(?:해소|정정|갱신|확정|역전)')

def check_temporal(docs):
    for d in docs:
        if is_history(d):
            continue
        lines = open(d, encoding='utf-8').read().split('\n')
        for i, line in enumerate(lines, 1):
            for pat, kind in TEMPORAL:
                if re.search(pat, line):
                    ctx = '\n'.join(lines[max(0, i - 3):i + 2])
                    if not DATED.search(ctx):
                        warns.append(
                            f"{rel(d)}:{i}  날짜 없는 {kind} — "
                            f"\"{re.search(pat, line).group(0)}\" "
                            f"(언제 기준인지 적을 것)")


# ---------- 5: 미반영 배너 ----------
def check_banner(docs):
    banner = [d for d in docs if '아직 반영 안 됨' in open(d, encoding='utf-8').read()]
    if not banner:
        return
    names = sorted(os.path.basename(b) for b in banner)
    plan = os.path.join(CLAUDE, 'research', 'dispatch-redispatch-diff-plan.md')
    if os.path.exists(plan):
        txt = open(plan, encoding='utf-8').read()
        missing = [n for n in names if n not in txt]
        if missing:
            warns.append(
                "미반영 ⚠️ 배너를 달고 있는데 반영 목록"
                "(dispatch-redispatch-diff-plan.md 6절)에 없는 파일: "
                + ', '.join(missing))
    warns.append(f"미반영 배너를 단 파일 {len(names)}개 — 해소 시 배너도 같이 걷을 것: "
                 + ', '.join(names))


def main():
    quiet = '--quiet' in sys.argv
    docs = live_docs()
    check_refs(docs)
    check_index()
    check_temporal(docs)
    check_banner(docs)

    # 제외 목록은 SKIP_DIRS 하나만 소스로 두고 여기서 다시 적지 않음
    # ([2026-08-16] 예전엔 "session/·initreq/ 제외"라고 하드코딩돼 있어
    #  worktrees/·tools/가 빠진 채 stale했음)
    print(f"검사 대상 라이브 문서 {len(docs)}개 "
          f"({'·'.join(d + '/' for d in SKIP_DIRS)} 제외)\n")
    if errors:
        print(f"■ ERROR {len(errors)}건 — 고쳐야 함")
        for e in errors:
            print("  " + e)
        print()
    elif not quiet:
        print("■ ERROR 0건 ✓\n")
    if warns:
        print(f"■ WARN {len(warns)}건 — 확인 권장(자동 판정 불가)")
        for w in warns:
            print("  " + w)
        print()
    elif not quiet:
        print("■ WARN 0건 ✓\n")
    return 1 if errors else 0


if __name__ == '__main__':
    sys.exit(main())