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
+22
View File
@@ -109,6 +109,23 @@ class ExceptionListTest(RepositoryTestCase):
errors = self.repo.run(("language",), exceptions=self.LINE + "\n", frozen=frozenset())
self.assertFailsWith(errors, "기준선에 없는 예외다")
def test_a_frozen_fingerprint_whose_line_was_removed_fails(self) -> None:
# The line was deleted from the list but its fingerprint stayed: the same line could come back.
orphan = frozenset({check_docs.fingerprint(self.LINE)})
for only in (("language",), ("head",)):
errors = self.repo.run(only, exceptions="", frozen=orphan)
self.assertFailsWith(errors, "예외 목록에 그 줄이 없는 지문이다")
def test_a_removed_line_added_back_fails_once_its_fingerprint_is_gone(self) -> None:
self.repo.write("docs/guide.md", ENGLISH * 3)
remaining = "language\tdocs/other.md"
self.repo.write("docs/other.md", ENGLISH * 3)
exceptions = remaining + "\n" + self.LINE + "\n"
errors = self.repo.run(("language",), exceptions=exceptions,
frozen=frozenset({check_docs.fingerprint(remaining)}))
self.assertFailsWith(errors, "기준선에 없는 예외다")
self.assertFalse(any("예외 목록에 그 줄이 없는 지문이다" in error for error in errors), errors)
def test_an_exception_that_no_longer_fails_must_be_removed(self) -> None:
self.repo.write("docs/guide.md", KOREAN * 3)
self.assertFailsWith(self.repo.run(("language",), exceptions=self.LINE + "\n"), "더는 걸리지 않는다")
@@ -124,6 +141,11 @@ class ExceptionListTest(RepositoryTestCase):
if check_docs.fingerprint(line) not in check_docs.FROZEN]
self.assertEqual(outside, [])
def test_every_frozen_fingerprint_has_its_line_in_the_real_exception_list(self) -> None:
text = (SCRIPTS.parent / check_docs.EXCEPTIONS_FILE).read_text(encoding="utf-8")
listed = {check_docs.fingerprint(line) for line in check_docs.read_exceptions(text)}
self.assertEqual(sorted(check_docs.FROZEN - listed), [])
def test_a_new_line_in_the_real_exception_list_is_not_in_the_frozen_baseline(self) -> None:
self.assertNotIn(check_docs.fingerprint("language\tdocs/brand-new-english.md"), check_docs.FROZEN)