Files
clean-architecture-backend-…/scripts/check-review-index.py
T
DongHyeonka 51230caf62 fix(scripts): 색인 절을 총괄이 쓰는 라운드의 색인 검사를 --extra-index로 한다
문제: 독립 리뷰어 둘이나 여러 리뷰 세션이 한 라운드를 나눠 보면, 정본 리뷰어는
영역 문서를 리뷰 폴더에 커밋하지만 README 색인 절은 총괄이 쓴다. 그래서 정본
리뷰어가 커밋한 트리의 색인 검사는 반드시 rc=1인데, improve.md는 리뷰어에게
rc=0을 요구했다(round8 발견 RR8-06-01). 두 규칙을 함께 지킬 수 없었다.

고른 방법: check-review-index.py에 --extra-index <파일>을 더했다. 리뷰어가
보고에 둔 색인 표 파일을 색인의 일부로 센다. improve.md 4.1절 7·8단계와 5절,
delegate.md 4.1절, 결정 색인 「리뷰 README 분담」에 쓰는 법을 적었다. 버린 안:
리뷰가 권한 "보고 표를 붙인 README 임시 사본" 절차 — 복사·붙이기 단계가 늘고
같은 대조를 손으로 한다. 정본 리뷰어가 README 색인 절을 먼저 쓰는 안 — 결정
「리뷰 README 분담」을 뒤집는다.

위험·한계: --extra-index는 넘긴 파일 전체를 색인으로 읽는다. 표만 담은 파일을
넘겨야 한다(노트 전체를 넘기면 본문에 나온 ID도 색인으로 센다). 매뉴얼에
"색인 표만 담은 파일"로 적었다.

검증(트리 3c305d7a, desktop 로그 ~/manual-gap-fix-2-logs/B-*):
- RED: 정본 리뷰어 커밋 27260ad0의 리뷰 폴더에 옵션 없이 rc=1(180 중 172)
- GREEN: 리뷰어 A의 색인 표를 --extra-index로 넘기면 rc=0(180/180)
- 지금 트리 docs/reviews/2026-11-03-rereview rc=0(182/182), 없는 파일을
  넘기면 rc=1
- check-work-docs.py 기본·--history docs/manual·--links rc=0

Refs: docs/reviews/2026-11-03-rereview/round8/06-manual-scripts.md RR8-06-01
2026-11-07 07:02:09 +09:00

153 lines
6.7 KiB
Python
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/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.
When the orchestrating session writes the round's index section after two reviews are merged, the
reviewer who committed the area documents must not edit the README, so the committed tree fails
this check until that section exists. --extra-index takes the index table the reviewer puts in the
report (a file holding that table only) and counts it as part of the index, so the reviewer can show
that the table names every finding before handing it over.
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
python3 scripts/check-review-index.py docs/reviews/2026-11-03-rereview --extra-index <index-table.md>
"""
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)")
parser.add_argument(
"--extra-index",
type=Path,
action="append",
default=[],
help="a file holding a round's index table that is not in the README yet; may repeat",
)
args = parser.parse_args()
readme = args.review / "README.md"
if not readme.is_file():
print(f"{readme}: missing", file=sys.stderr)
return 1
missing_extra = [str(path) for path in args.extra_index if not path.is_file()]
if missing_extra:
print(f"--extra-index: missing {', '.join(missing_extra)}", file=sys.stderr)
return 1
findings = area_findings(args.review)
texts = [index_text(readme, args.index_heading)]
texts += [path.read_text(encoding="utf-8") for path in args.extra_index]
indexed = indexed_ids("\n".join(texts))
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}")
for path in args.extra_index:
print(f"index: + {path} (--extra-index)")
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())