문제: 독립 리뷰어 둘이나 여러 리뷰 세션이 한 라운드를 나눠 보면, 정본 리뷰어는
영역 문서를 리뷰 폴더에 커밋하지만 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
153 lines
6.7 KiB
Python
Executable File
153 lines
6.7 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.
|
||
|
||
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())
|