문제: 옛 개선 매뉴얼은 진입 경로가 717줄이었고 본문에 지난 리뷰 ID가 든 줄이 많아, 이력을 모르는 세션은 근거를 따라가지 못했다. 이것을 사람 눈으로만 지키면 다시 늘어난다. 리뷰 색인도 손으로 옮기다 발견 5건이 빠져 어떤 수정 묶음에도 배정되지 않은 적이 있다(원래 리뷰 124건이 색인에는 119건). 고른 방법: Gradle 밖 Python 스크립트 두 개를 둔다(2026-11-06 소유자 결정 D6: 이 repo는 문서를 파싱하는 Gradle 검사를 두지 않는다). - check-work-docs.py: 지도(CLAUDE.md)와 docs/work/의 분량 상한(지도 120, README 80, playbook 150, 진입 경로 350), playbook 9칸 뼈대, 「자주 하는 실수」 10줄, 본문 이력 ID 0(evidence.md와 reference/의 두 색인 문서는 제외), 상대 링크를 본다. --links, --history 모드로 다른 문서에도 쓴다. - check-review-index.py: 리뷰 폴더의 영역 문서 제목에 있는 발견 ID가 README 색인에 모두 있는지 본다. 범위(A~B)와 이어 쓰기(A·07)를 읽고, NN- 자리표시자를 잡는다. 정규식은 re.ASCII로 쓴다. Python의 \w·\b가 한글을 단어 문자로 봐서 "RR6-01-07과" 같은 표기를 놓쳤다. 버린 대안: document-contract Gradle lane(이 repo 원칙과 충돌), 검사 없이 cold-read 시험에서만 확인(매번 사람이 세야 한다). 위험·한계: check-work-docs.py가 보는 docs/work/는 다음 커밋에 들어온다. 이 커밋만으로는 "missing"으로 실패한다. 이력 ID 패턴은 이 repo가 쓴 형식만 안다 (MMDD/, RR<n>-, 묶음 이름, round<n>, 번호만 쓴 결정, 커밋 sha). 색인 검사는 "이름이 있나"만 보고 고쳤는지는 보지 않는다. 검증 - check-review-index.py docs/reviews/2026-11-01-maturity-review --index-heading "12. 발견 색인": 124/124, rc=0 - 같은 폴더를 사고 시점 34565130에서 꺼내 돌림: NN-10~NN-14 5건, rc=1 - check-review-index.py docs/reviews/2026-11-03-rereview: 157 중 135, rc=1 (README가 ID 대신 내용·건수로 적은 22건) - check-work-docs.py를 일부러 망가뜨린 사본 18가지에 돌림: 이력 ID 7형식, 분량 3종, 뼈대, 실수 줄 수, 깨진 링크, 빠진 파일은 rc=1, ID가 허용된 파일과 "결정 3개" 같은 개수 표현은 rc=0
130 lines
5.6 KiB
Python
Executable File
130 lines
5.6 KiB
Python
Executable File
#!/usr/bin/env python3
|
||
"""Fail when a finding written in a review's area documents is missing from that review's index.
|
||
|
||
A review folder (`docs/reviews/<date>-<kind>/`) holds one README and one document per area (and,
|
||
for confirmation reviews, `roundN/` documents). Each finding is a heading that starts with its ID:
|
||
`### 05-01 ...`, `#### RR-02-03 · ...`, `### RR6-01-01 · Important · ...`. Fix bundles are assigned
|
||
from the README, so a finding the README does not name is a finding nobody fixes. That happened
|
||
once: five findings were dropped while IDs were copied into the index by hand.
|
||
|
||
This compares the two mechanically. Every finding ID in an area heading must appear in the README
|
||
(or, with --index-heading, in that README section). A range such as `RR-01-11~17` or
|
||
`06-10~06-14` counts for every ID inside it. A heading ID that still has a placeholder area
|
||
(`NN-10`) is reported too, because it cannot be assigned at all.
|
||
|
||
python3 scripts/check-review-index.py docs/reviews/2026-11-01-maturity-review --index-heading "12. 발견 색인"
|
||
python3 scripts/check-review-index.py docs/reviews/2026-11-03-rereview
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import argparse
|
||
import re
|
||
import sys
|
||
from pathlib import Path
|
||
|
||
# re.ASCII: Korean letters are word characters to Python's \w, so "RR6-01-07과" would not match.
|
||
FINDING_HEADING = re.compile(r"^#{2,6}\s+`?((?:RR\d*-)?(?:\d{2}|NN)-\d{2})\b", re.ASCII)
|
||
ID = r"(?:RR\d*-)?\d{2}-\d{2}"
|
||
# A list starts with a full ID and may go on with "~NN" (a range up to NN) or "·NN" (one more number
|
||
# with the same prefix): "RR-04-06~08·10·11" is 06, 07, 08, 10 and 11. "06-10~06-14" is a range too.
|
||
LIST = re.compile(
|
||
rf"`?(?<![\w-])({ID})`?((?:\s*[~–]\s*`?(?:{ID}|\d{{2}})(?![\w-])`?|·\d{{2}}(?![\w-]))*)",
|
||
re.ASCII,
|
||
)
|
||
STEP = re.compile(rf"([~–]|·)\s*`?((?:{ID})|\d{{2}})", re.ASCII)
|
||
SINGLE = re.compile(rf"(?<![\w-])({ID})(?![\w-])", re.ASCII)
|
||
|
||
|
||
def area_findings(review: Path) -> dict[str, list[str]]:
|
||
findings: dict[str, list[str]] = {}
|
||
for path in sorted(review.rglob("*.md")):
|
||
if path.name == "README.md" and path.parent == review:
|
||
continue
|
||
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
|
||
match = FINDING_HEADING.match(line)
|
||
if match:
|
||
findings.setdefault(match.group(1), []).append(
|
||
f"{path.relative_to(review).as_posix()}:{number}"
|
||
)
|
||
return findings
|
||
|
||
|
||
def index_text(readme: Path, heading: str | None) -> str:
|
||
lines = readme.read_text(encoding="utf-8").splitlines()
|
||
if heading is None:
|
||
return "\n".join(lines)
|
||
for start, line in enumerate(lines):
|
||
match = re.match(r"^(#+)\s+(.*)$", line)
|
||
if match and match.group(2).strip() == heading:
|
||
level = len(match.group(1))
|
||
end = len(lines)
|
||
for later in range(start + 1, len(lines)):
|
||
other = re.match(r"^(#+)\s", lines[later])
|
||
if other and len(other.group(1)) <= level:
|
||
end = later
|
||
break
|
||
return "\n".join(lines[start:end])
|
||
raise SystemExit(f"{readme}: no heading '{heading}'")
|
||
|
||
|
||
def indexed_ids(text: str) -> set[str]:
|
||
ids = set(SINGLE.findall(text))
|
||
for first, tail in LIST.findall(text):
|
||
prefix, number = first.rsplit("-", 1)
|
||
current = int(number)
|
||
for kind, value in STEP.findall(tail):
|
||
if "-" in value:
|
||
value_prefix, value = value.rsplit("-", 1)
|
||
if value_prefix != prefix:
|
||
ids.add(f"{value_prefix}-{value}")
|
||
continue
|
||
target = int(value)
|
||
if kind == "·":
|
||
ids.add(f"{prefix}-{target:02d}")
|
||
else:
|
||
ids.update(f"{prefix}-{n:02d}" for n in range(current, target + 1))
|
||
current = target
|
||
return ids
|
||
|
||
|
||
def main() -> int:
|
||
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||
parser.add_argument("review", type=Path, help="review folder, e.g. docs/reviews/2026-11-01-maturity-review")
|
||
parser.add_argument("--index-heading", help="compare against this README section only (heading text)")
|
||
args = parser.parse_args()
|
||
|
||
readme = args.review / "README.md"
|
||
if not readme.is_file():
|
||
print(f"{readme}: missing", file=sys.stderr)
|
||
return 1
|
||
|
||
findings = area_findings(args.review)
|
||
indexed = indexed_ids(index_text(readme, args.index_heading))
|
||
placeholder = sorted(finding for finding in findings if "NN-" in finding)
|
||
missing = sorted(f for f in findings if f not in indexed and f not in placeholder)
|
||
duplicated = sorted(f for f, places in findings.items() if len(places) > 1)
|
||
|
||
scope = f"section '{args.index_heading}'" if args.index_heading else "whole README"
|
||
print(f"review: {args.review}")
|
||
print(f"index: README.md, {scope}")
|
||
print(f"finding headings in area documents: {len(findings)}")
|
||
print(f"found in index: {len(findings) - len(missing) - len(placeholder)}")
|
||
print(f"missing from index: {len(missing)}")
|
||
for finding in missing:
|
||
print(f" {finding} ({', '.join(findings[finding])})")
|
||
if placeholder:
|
||
print(f"placeholder area (NN-): {len(placeholder)}")
|
||
for finding in placeholder:
|
||
print(f" {finding} ({', '.join(findings[finding])})")
|
||
if duplicated:
|
||
print(f"same ID in more than one heading (check they are one finding): {len(duplicated)}")
|
||
for finding in duplicated:
|
||
print(f" {finding} ({', '.join(findings[finding])})")
|
||
|
||
return 1 if missing or placeholder else 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
sys.exit(main())
|