ci(docs): FROZEN에 목록에 없는 지문이 남으면 문서 검사가 실패한다

예외 목록은 줄기만 해야 하는데 빈틈이 있다. check-docs.py는 목록의
줄이 FROZEN에 있는지만 보고, FROZEN의 지문이 목록에 있는지는 보지
않는다. 그래서 번역해서 지운 줄의 지문이 FROZEN에 남고, 같은 줄을 다시
더해도 검사가 통과한다. 기준 커밋 03a313ed에서 이미 FROZEN 217개 중
9개가 목록에 줄이 없었다(앞 단계의 이름 바꾸기에서 남은 것).

- run()이 FROZEN - (목록 줄의 지문)을 실패로 낸다. --only와 상관없이
  돈다(목록의 줄이 FROZEN에 있는지 보는 검사와 같다).
- 합친 트리의 목록이 비었으므로 FROZEN에서 217개를 모두 뺐다. 이제
  목록에 어떤 줄을 더해도 실패한다.
- 설명(스크립트 머리, 예외 목록 머리 주석, docs/README.md 「문서
  검사」)에 「줄을 지우면 FROZEN에서 그 지문도 뺀다」를 더했다.
  스크립트 머리의 「넷 모두」를 지금의 여섯 검사로 고쳤다.

버린 대안: FROZEN을 그대로 두고 자기 시험만 더하기. 실제 검사(PR
workflow)는 자기 시험과 따로 돌므로, 목록과 FROZEN이 어긋난 트리가
check-docs.py만으로는 통과한다. 검사 자신이 막아야 한다.

자기 시험(scripts/tests/test_check_docs.py)에 셋을 더했다.
- test_a_frozen_fingerprint_whose_line_was_removed_fails: 고장 낸 입력
  (빈 목록 + 지문 하나)이 language·head 어느 검사로 돌려도 실패한다.
- test_a_removed_line_added_back_fails_once_its_fingerprint_is_gone:
  지문을 뺀 뒤 줄을 다시 더하면 「기준선에 없는 예외다」로 실패하고,
  남은 줄에는 고아 지문 오류가 나지 않는다.
- test_every_frozen_fingerprint_has_its_line_in_the_real_exception_list:
  실제 FROZEN과 실제 목록이 맞는다.

조건을 끈 변이 시험(사본에 문자열 치환, 자기 시험 실행):
- 고아 지문 검사를 지움 → rc=1, 첫째 시험 실패
- FROZEN을 03a313ed의 217개로 되돌림 → rc=1, 셋째 시험 실패.
  실제 트리의 check-docs.py도 고아 지문 217건으로 실패한다.
- 둘 다(바꾸기 전 코드) → rc=1, 첫째·셋째 시험 실패

검증(노트북): check-docs.py OK(여섯 검사 걸림 0), 자기 시험 68 OK,
check-work-docs.py OK.
This commit is contained in:
DongHyeonka
2026-11-07 18:15:29 +09:00
parent 39d4f24803
commit 80e7ef12a2
4 changed files with 38 additions and 49 deletions
+11 -48
View File
@@ -26,13 +26,16 @@
예외 목록(scripts/check-docs-exceptions.txt)은 줄기만 한다.
- 목록의 줄은 아래 FROZEN(2026-11-07 기준선의 지문)에 있어야 한다. 목록에 새 줄을 더하면 실패한다.
- FROZEN의 지문은 목록에 그 줄이 있어야 한다. 줄을 지우면 같은 변경에서 FROZEN에서 그 지문도 뺀다.
남겨 두면 실패한다. 남은 지문은 지운 줄을 다시 더하는 길이 되기 때문이다.
- 목록의 줄이 더는 걸리지 않으면(번역했거나 고쳤으면) 그 줄을 지우라고 실패한다.
- FROZEN을 늘리는 것은 규칙을 바꾸는 일이다. 소유자 결정 없이 하지 않는다. 파일을 옮겨 경로만
바뀐 줄은 FROZEN에서 옛 지문을 새 지문으로 바꾼다. 지문은 그 줄(탭 포함)의 sha256 앞 16자다:
python3 -c 'import hashlib,sys; print(hashlib.sha256(sys.argv[1].encode()).hexdigest()[:16])' "<줄>"
- 2026-11-07 번역 단계에서 목록의 줄을 모두 지워 목록과 FROZEN이 비었다.
python3 scripts/check-docs.py # 넷 모두
python3 scripts/check-docs.py --only head # 하나만 (language, head, reference, number)
python3 scripts/check-docs.py # 여섯 모두
python3 scripts/check-docs.py --only head # 하나만 (language, head, reference, number, map, readme)
python3 -m unittest discover -s scripts/tests # 이 검사의 시험
Gradle 밖에 둔다. 빌드는 문서를 파싱하지 않는다(AGENTS.md 「Gradle 정책 권위」).
@@ -98,52 +101,8 @@ README_SECTIONS = ("프로젝트 구조", "시작하기", "기능 켜고 끄기"
"규칙과 기여")
# 2026-11-07 기준선. 예외 목록의 줄마다 sha256 앞 16자. 늘리지 않는다(맨 위 설명).
FROZEN: frozenset[str] = frozenset({
"0176963415821bbe", "01984fd96d72b997", "02810bf817c5098f", "02f77e3cc483fa7b", "05fff3c3ff8a5c9a",
"06ea362843468b89", "0767d62996355ba0", "077f1849fe8bebcc", "07f88b24645a4899", "09f6eb7c3c494379",
"0a929e243076b4cb", "0d60ec2d41d698e3", "0d9db88d1d98c32b", "0f84458cb40e7c5e", "10894a287a405274",
"110ff8adc628d4e9", "115eed80f3bb629c", "14121ef25eb4aa46", "150219e901d062f4", "199044717780f929",
"1adc480d397a24fc", "1aedb5c86be16e62", "1ef3eec4c410622e", "1f3199d6bef7b3ab", "20a46563da0c570d",
"234a0dffc4f308bf", "23aa784e28c7f730", "24e61cd8377137f1", "26cdb5786cd3cef8", "26f59b7362b9e68d",
"29fa254236927dae", "2a0c27bb25080cdb", "2aa755121374e148", "2bcc75d4e1ebaa5d", "2e77660bd44c1d2c",
"2e7d24cb488ae4f9", "30c75a928243de75", "354c37493e90b01b", "3e867d0b440f18f5", "3fe449c9eca66d87",
"3ff905af6cc2df16", "4053b182a2b89223", "41f268d8aa836143", "4347c5b0dd84ec9b", "449fc1cac0f9380f",
"457310fef9d100a6", "4611a0bfd81bf42c", "462a63de89507bc6", "468248c165ce65f0", "47c9a2b490ceae84",
"4866a2abc9be3133", "48ca99496ac8265e", "494b23454cfaf902", "49d560912ccd3bd6", "49ee572590d74921",
"4c3afe5f9f4265d3", "4cef6042d25d7ce2", "4f4516913c6de5d6", "4f9b0fa57d925ddc", "50cecf0fd2f1ed1f",
"511ed51b27f98b9c", "52879b9f3cbdd66f", "52d9b8b42edf92c5", "52dd5ae3e9bfef22", "53f304d4f21e321e",
"5503b8002ae2673f", "55397a6480705e90", "561988b22b65f79f", "5640b6d1a24b9ad6", "56d9c8bc2e2d7a01",
"570b7b7be5396079", "57603aa52f880d03", "57c4df2758097604", "59e238f79e31e3db", "5acb4cacd9aa7a71",
"5b1f0d60cdd91b33", "5b783704ccce90b9", "5b833f85df94c6fd", "5caaf9a02506595e", "5cd2de3ab18314a9",
"5cda11b0371e8b48", "5e17fde0e8281e0b", "61241c19f875d528", "614d8160fecebe42", "62ac6e83f597894a",
"62ae3935928ec875", "62ae5138ca3f54bf", "29b4daf7b7befa61", "63887df3233e4e7f", "63bbbd89d07abcc5",
"63d3556d23363430", "6407c8198a2ce80f", "6669b8199b2f15be", "6710e607f9ae6ba2", "6c60928d93ca7831",
"6e57bc847800e849", "6f2fef4ed95b870d", "70f8b4b8cb326639", "7227a51a80d75567", "728afb0024d5da55",
"745fabbdac49b041", "74622ec18c9f9985", "74eab10487ee91a4", "7548695a3a57c058", "76030078f4c446ec",
"7698729bcfd126f7", "77ed807b2db1bdb4", "782bc48fcd75361c", "7846dce0563bde1f", "78b5bea3cfb3f84f",
"7a41c841fa3c71c3", "7b3944471a209cdc", "7ba95fb426152c3b", "814a101266f1e722", "8232460887910a0e",
"82b97043efd185d0", "83b56cb713adb544", "84ebb93c8c137862", "8559d433706ac279", "85e199be8e5a5df5",
"86c327f4147ec696", "8c3417a9291e07cf", "9031db861c91b202", "90697a358931eba2", "9084568d44e608c3",
"945be2a3aaccbb2c", "94c5248d3fe6f83f", "95feaea41a059d9a", "966dd5354d327ba4", "97c036827ae94466",
"97fed7ecb0c23137", "982773d6151ae295", "993631c9efdbaa48", "999cc41aeaa485d9", "9b976d47e8cca045",
"9db89af226707449", "9e9437780d412b86", "9ee05526226dd121", "9f6cb144b5b0013d", "a14aae022e52cabd",
"a2db3c73eea72747", "a6e2e42521f27aa8", "a7b7a83d8e7b5914", "a84c5847e6bc413a", "a9cdf0e474dfa4ca",
"ab9a1c81f4d00b17", "ac208a7edf8e6b9e", "ac524f5b860f4b73", "af6bfc4105841865", "b25dfdea45b42ece",
"b2ee46983b09686b", "b6c96aabf4daba15", "b99ef0dca48e547c", "bc89c106ed0333da", "399e08b7f60cd570",
"bd2edda7ff995e5a", "c0f36dd22b6d1df4", "c1cbe5ed9ccaf41a", "c2e62316bf302721", "c30f7e945ca5204b",
"c446b7882073d116", "c555077d0a4ca6dc", "c5556985dac877fb", "c66938fdb57ac8bd", "c7d3f2a6e0e819c7",
"437e813553f5782e", "c9147167591ac87f", "c9682c8986bdfa3f", "c9f15a774cbbb296", "c9f895250a7f6b1f",
"ca9ac59c7e4dd0dd", "ccfd7af308666817", "cde221c994e186e9", "d1c59fa1e5fd22ca", "d2c0d56090ffb617",
"d3a72db1fb71eaf6", "d58784f8ae176897", "d88381653e2c64f9", "d934528c9e7966f7", "da73ed73f0ec1dd9",
"da8381da9de5df66", "dd4f9524437dcc45", "dd6384bc82ce9677", "df5a6c2edc20af59", "e076b4232fc136e9",
"e1ada69597a5d6cd", "e1d8a4d6d6bbfb2e", "e2af4a0f5b0957d5", "e313fbfdd61fba0c", "e347453420828b08",
"e368dfa3ca97d4c7", "e3cc20cbd63d0adb", "e4435ba963a1fbef", "e5182c24f72e2747", "e660a27969605244",
"e7dad258cbc844a0", "e97d1ef509983caa", "e997a8c038464efb", "eb66b6c389ec09e4", "ed7764b9ec0265a0",
"ee8e568418c22e81", "ef22d97e0a67bed8", "f0baa883ab5f959d", "f12cb9b454600534", "f135bd1f9697ad4c",
"f166b8797656c86e", "f191a6842f342b74", "f3ea04dd3a66f76a", "f4c93c2e841f1c68", "f4d7edfeee65b0c3",
"f6528fa83345165e", "fa4172e085723211", "fc0c07879a70ce33", "fd706bf633a51444", "fd793c8cfa94f318",
"fe800048b661a783", "6cfa7cfc6f6a4a7e",
})
# 처음 217개였다. 2026-11-07 번역 단계에서 목록이 비어 모두 뺐다.
FROZEN: frozenset[str] = frozenset()
# --- 언어 판정: ~/.claude/hooks/guard_report.py의 H11과 같은 규칙(design-docs conventions/delegation-loop.md 11절)
MIN_ENGLISH = 3
@@ -638,6 +597,10 @@ def run(root: Path, only: tuple[str, ...] = CHECKS, exceptions: str | None = Non
for entry in allowed:
if fingerprint(entry) not in frozen:
errors.append(f"[exceptions] {EXCEPTIONS_FILE}: 기준선에 없는 예외다. 예외 목록은 늘지 않는다: {entry!r}")
listed = {fingerprint(entry) for entry in allowed}
for orphan in sorted(frozen - listed):
errors.append(f"[exceptions] scripts/check-docs.py FROZEN: 예외 목록에 그 줄이 없는 지문이다. "
f"지운 줄의 지문은 FROZEN에서도 뺀다: {orphan}")
allowed_set = set(allowed)
for check in only:
problems = RUNNERS[check](root, files)