diff --git a/docs/README.md b/docs/README.md index ca6021d5..e6f418d5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -188,6 +188,8 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 - 예외 목록 `scripts/check-docs-exceptions.txt`는 2026-11-07의 기준선이고 줄기만 한다. 문서를 번역하거나 고쳐서 더는 걸리지 않으면 그 줄을 지운다(남겨 두면 실패한다). 목록에 새 줄을 더하면 실패한다. 기준선을 늘리는 것은 규칙을 바꾸는 일이라 소유자 결정이 필요하다. +- 줄을 지우면 같은 변경에서 `scripts/check-docs.py`의 `FROZEN`에서 그 줄의 지문도 뺀다. 남겨 두면 실패한다(남은 + 지문은 지운 줄을 다시 더하는 길이다). 2026-11-07 번역 단계에서 목록과 `FROZEN`이 모두 비었다. - 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`. - 마크다운 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다. 기록 안의 외부 링크가 죽어도 기록 본문은 고치지 않는다. 그 URL을 저장소 루트의 `.lycheeignore`에 더한다. diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index ec51481b..a5ba76cd 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -2,9 +2,11 @@ # # - 이 목록에 새 줄을 더하면 검사가 실패한다. 줄마다 check-docs.py의 FROZEN에 지문이 있어야 한다. # - 번역하거나 고쳐서 더는 걸리지 않는 줄은 지운다. 남겨 두면 검사가 실패한다. +# - 줄을 지우면 같은 변경에서 FROZEN에서 그 지문도 뺀다. 남겨 두면 검사가 실패한다. +# - 2026-11-07 번역 단계에서 모든 줄을 지웠다. FROZEN도 비어 있어 어떤 줄을 더해도 실패한다. # - 형식: <검사><탭><경로>[<탭><걸린 값>]. 「#」으로 시작하는 줄과 빈 줄은 읽지 않는다. -# 언어: 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR. 다음 단계(살아 있는 문서 번역, ADR 번역)에서 지운다. +# 언어: 한국어로 옮기지 않은 살아 있는 문서와 ADR. # 참조: 지금 트리·registry에 없는 경로. 고치거나 「> 이력」 인용 블록으로 옮기면 지운다. diff --git a/scripts/check-docs.py b/scripts/check-docs.py index 52b64be4..f2ab90fc 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -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) diff --git a/scripts/tests/test_check_docs.py b/scripts/tests/test_check_docs.py index 6638bfda..c35cceb9 100644 --- a/scripts/tests/test_check_docs.py +++ b/scripts/tests/test_check_docs.py @@ -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)