Files
clean-architecture-backend-…/scripts/tests/test_check_docs.py
T
DongHyeonka fc3cad7dcc ci(docs): 참조 검사가 루트 compose 폴더 경로도 본다
문제: 구조 정리로 저장소 루트에 `compose/`(개발 compose의 보조 파일)가
생겼다. 참조 검사는 `src/`, `docs/`, `scripts/`, `infra/`, `.github/`로
시작하는 인라인 코드만 본다. 그래서 살아 있는 문서가 가리키는
`compose/redis/acl/README.md` 같은 경로는 파일이 옮겨지거나 지워져도
걸리지 않는다. 지금 살아 있는 문서 여덟 개가 `compose/` 경로를 쓴다.

고친 방법: PATH_ROOTS에 `compose/`를 더한다. 정본 design-docs
`conventions/docs-system.md` K3는 「repo 경로」 전체를 말하고 접두사 목록을
정하지 않으므로 규칙 변경이 아니라 새 루트 폴더를 적용한 것이다. 지운
`infra/`는 남겨 둔다(다시 쓰이면 낡은 참조로 걸린다). 루트 파일
(`compose.yaml` 등)은 지금처럼 보지 않는다.

위험·한계: 새로 걸린 참조는 없다(지금 트리의 `compose/` 참조는 모두 있다).

검증: 새 시험 `test_a_missing_path_under_the_root_compose_folder_fails`가
고치기 전 실패(RED: 오류 목록이 비어 있음), 고친 뒤 43개 모두 통과.
check-docs.py rc=0(참조 걸림 7·예외 7).
2026-11-07 15:04:17 +09:00

256 lines
12 KiB
Python

"""scripts/check-docs.py의 시험. 고장 낸 입력에서 실패하고, 맞는 입력에서 통과하는지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import importlib.util
import json
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path
SCRIPTS = Path(__file__).resolve().parent.parent
_spec = importlib.util.spec_from_file_location("check_docs", SCRIPTS / "check-docs.py")
check_docs = importlib.util.module_from_spec(_spec)
sys.modules["check_docs"] = check_docs
_spec.loader.exec_module(check_docs)
KOREAN = "이 문서는 한국어로 쓴 살아 있는 문서다. 코드와 같은 변경에서 고친다.\n"
ENGLISH = "This document is written in English and explains how the module works in detail.\n"
def head(kind: str = "설계서", status: str = "구현됨", written: str = "2026-08-11",
summary: str = "한국어로 쓴 요약 한 문장이다.", canonical: str = "`docs/live.md`",
extra: str = "", label: str | None = None) -> str:
if label is None:
label = check_docs.DECISION_LABEL if kind == "결정 기록" else check_docs.RECORD_LABEL.format(kind=kind)
lines = [check_docs.HEAD_START, label, "", f"- 상태: {status}", f"- 작성일: {written}",
f"- 요약: {summary}", f"- 현재 정본: {canonical}"]
if extra:
lines.append(extra)
lines += [check_docs.HEAD_END, ""]
return "\n".join(lines) + "\n"
class Repository:
"""A throwaway git working tree with a registry, so the checker sees what git sees."""
def __init__(self) -> None:
self._directory = tempfile.TemporaryDirectory()
self.root = Path(self._directory.name)
subprocess.run(["git", "init", "-q", str(self.root)], check=True)
self.write("docs/live.md", KOREAN)
self.write(check_docs.REGISTRY_FILE, json.dumps({"modules": [
{"id": "app", "gradle_path": ":app", "source_path": "src/app"},
{"id": "adapter-web", "gradle_path": ":adapter:inbound:web", "source_path": "src/adapter/inbound/web"},
]}))
def write(self, path: str, text: str) -> None:
target = self.root / path
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(text, encoding="utf-8")
def run(self, only: tuple[str, ...] = check_docs.CHECKS, exceptions: str = "",
frozen: frozenset[str] | None = None) -> list[str]:
if frozen is None:
frozen = frozenset(check_docs.fingerprint(line) for line in check_docs.read_exceptions(exceptions))
errors, _ = check_docs.run(self.root, only, exceptions=exceptions, frozen=frozen)
return errors
def close(self) -> None:
self._directory.cleanup()
class RepositoryTestCase(unittest.TestCase):
def setUp(self) -> None:
self.repo = Repository()
self.addCleanup(self.repo.close)
def assertFailsWith(self, errors: list[str], fragment: str) -> None:
self.assertTrue(any(fragment in error for error in errors), f"no error with {fragment!r}: {errors}")
class LanguageTest(RepositoryTestCase):
def test_an_english_living_document_fails(self) -> None:
self.repo.write("docs/guide.md", "# Guide\n\n" + ENGLISH * 3)
self.assertFailsWith(self.repo.run(("language",)), "docs/guide.md: 영어 문서다")
def test_a_korean_living_document_passes(self) -> None:
self.repo.write("src/app/README.md", "# 앱\n\n" + KOREAN * 3)
self.assertEqual(self.repo.run(("language",)), [])
def test_code_commands_and_paths_do_not_make_a_korean_document_english(self) -> None:
code = "```bash\n" + "./gradlew :app:test --console=plain and many more english words here\n" * 20 + "```\n"
self.repo.write("docs/guide.md", "# 안내\n\n" + KOREAN + code + "`src/app/Foo.java`를 본다.\n")
self.assertEqual(self.repo.run(("language",)), [])
def test_a_record_body_keeps_its_original_language(self) -> None:
self.repo.write("docs/design/2026-08-11-x-design.md", head() + "# Design\n\n" + ENGLISH * 3)
self.assertEqual(self.repo.run(("language",)), [])
def test_an_english_decision_record_body_fails(self) -> None:
self.repo.write("docs/adr/ADR-X-001.md", head(kind="결정 기록", status="채택") + "# ADR\n\n" + ENGLISH * 3)
self.assertFailsWith(self.repo.run(("language",)), "docs/adr/ADR-X-001.md: 영어 문서다")
class ExceptionListTest(RepositoryTestCase):
LINE = "language\tdocs/guide.md"
def test_a_frozen_exception_excuses_its_document(self) -> None:
self.repo.write("docs/guide.md", ENGLISH * 3)
self.assertEqual(self.repo.run(("language",), exceptions=self.LINE + "\n"), [])
def test_adding_a_line_to_the_exception_list_fails(self) -> None:
self.repo.write("docs/guide.md", ENGLISH * 3)
errors = self.repo.run(("language",), exceptions=self.LINE + "\n", frozen=frozenset())
self.assertFailsWith(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"), "더는 걸리지 않는다")
def test_an_exception_for_one_check_does_not_excuse_another(self) -> None:
self.repo.write("docs/guide.md", "`docs/gone.md`를 본다. " + KOREAN)
errors = self.repo.run(("reference",), exceptions="number\tdocs/guide.md\tdocs/gone.md\n")
self.assertFailsWith(errors, "없는 경로다: docs/gone.md")
def test_every_line_of_the_real_exception_list_is_in_the_frozen_baseline(self) -> None:
text = (SCRIPTS.parent / check_docs.EXCEPTIONS_FILE).read_text(encoding="utf-8")
outside = [line for line in check_docs.read_exceptions(text)
if check_docs.fingerprint(line) not in check_docs.FROZEN]
self.assertEqual(outside, [])
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)
class HeadBlockTest(RepositoryTestCase):
PATH = "docs/design/2026-08-11-x-design.md"
def errors_for(self, text: str) -> list[str]:
self.repo.write(self.PATH, text + "# Original\n\nbody\n")
return self.repo.run(("head",))
def test_a_complete_head_block_passes(self) -> None:
self.assertEqual(self.errors_for(head()), [])
def test_canonical_none_with_a_reason_passes(self) -> None:
self.assertEqual(self.errors_for(head(canonical="없음 — 지운 기능이다")), [])
def test_a_record_without_a_head_block_fails(self) -> None:
self.assertFailsWith(self.errors_for(""), "맨 위에 머리 블록이 없다")
def test_a_status_outside_the_vocabulary_fails(self) -> None:
self.assertFailsWith(self.errors_for(head(status="Accepted")), "설계서의 상태는")
def test_a_plan_status_on_a_decision_record_fails(self) -> None:
self.repo.write("docs/adr/ADR-X-001.md", head(kind="결정 기록", status="끝남") + "# ADR\n")
self.assertFailsWith(self.repo.run(("head",)), "결정 기록의 상태는")
def test_a_malformed_date_fails(self) -> None:
self.assertFailsWith(self.errors_for(head(written="2026-13-01")), "작성일은 YYYY-MM-DD다")
def test_an_english_summary_fails(self) -> None:
self.assertFailsWith(self.errors_for(head(summary="A design for the module boundary.")), "요약은 한국어")
def test_a_canonical_path_that_does_not_exist_fails(self) -> None:
self.assertFailsWith(self.errors_for(head(canonical="`docs/missing.md`")), "현재 정본 경로가 없다")
def test_a_canonical_value_without_a_path_fails(self) -> None:
self.assertFailsWith(self.errors_for(head(canonical="jpa 문서")), "현재 정본은")
def test_superseded_without_its_replacement_fails(self) -> None:
self.assertFailsWith(self.errors_for(head(status="대체됨")), "「대체됨」 칸에 대체한 문서")
def test_superseded_with_its_replacement_passes(self) -> None:
self.assertEqual(self.errors_for(head(status="대체됨", extra="- 대체됨: `docs/live.md`")), [])
def test_a_wrong_kind_label_fails(self) -> None:
self.assertFailsWith(self.errors_for(head(label="> **기록 · 계획서** 다른 종류다.")), "머리 블록 둘째 줄은")
def test_an_unknown_field_fails(self) -> None:
self.assertFailsWith(self.errors_for(head(extra="- 담당: 누군가")), "머리 블록에 없는 칸이다")
def test_the_kind_follows_the_folder(self) -> None:
self.repo.write("docs/history/plans/evidence/x.md", head(kind="증거", status="보관") + "# Evidence\n")
self.assertEqual(self.repo.run(("head",)), [])
class ReferenceTest(RepositoryTestCase):
def errors_for(self, text: str, path: str = "docs/guide.md") -> list[str]:
self.repo.write(path, KOREAN + text)
return self.repo.run(("reference",))
def test_a_missing_repository_path_fails(self) -> None:
self.assertFailsWith(self.errors_for("`docs/gone.md`를 읽는다.\n"), "없는 경로다: docs/gone.md")
def test_an_existing_path_with_a_line_number_passes(self) -> None:
self.assertEqual(self.errors_for("`docs/live.md:12`를 읽는다.\n"), [])
def test_a_missing_path_under_the_root_compose_folder_fails(self) -> None:
self.assertFailsWith(self.errors_for("`compose/gone/README.md`를 읽는다.\n"), "없는 경로다: compose/gone/README.md")
def test_a_path_inside_a_command_is_checked(self) -> None:
self.assertFailsWith(self.errors_for("`python3 scripts/gone.py --all`을 돌린다.\n"), "scripts/gone.py")
def test_fenced_code_is_skipped(self) -> None:
self.assertEqual(self.errors_for("```text\n`docs/gone.md`\n```\n"), [])
def test_a_history_quote_is_skipped(self) -> None:
self.assertEqual(self.errors_for("> 이력: `docs/gone.md`는 2026-09-25에 지웠다.\n> `src/gone/` 도.\n"), [])
def test_a_placeholder_path_is_skipped(self) -> None:
self.assertEqual(self.errors_for("`docs/reviews/<폴더>`와 `src/**/CLAUDE.md`를 본다.\n"), [])
def test_a_leaf_relative_source_path_resolves_through_some_leaf(self) -> None:
self.repo.write("src/app/src/test/resources/contracts/x.sha256", "x")
self.assertEqual(self.errors_for("각 leaf의 `src/test/resources/contracts/x.sha256`을 본다.\n"), [])
def test_a_source_set_name_every_leaf_has_is_skipped(self) -> None:
self.assertEqual(self.errors_for("테스트는 각 leaf의 `src/test`와 `src/main/java/` 옆에 둔다.\n"), [])
def test_a_gradle_path_outside_the_registry_fails(self) -> None:
self.assertFailsWith(self.errors_for("`./gradlew :sample:check`를 돌린다.\n"), "registry에 없는 Gradle 경로다: :sample:check")
def test_a_task_of_a_registered_project_passes(self) -> None:
self.assertEqual(self.errors_for("`./gradlew :adapter:inbound:web:test`와 `:app:check`를 돌린다.\n"), [])
def test_the_removal_table_is_not_checked(self) -> None:
self.assertEqual(self.errors_for("`src/gone/Old.java`를 지웠다.\n", path="docs/capability-status.md"), [])
def test_a_record_is_not_checked(self) -> None:
self.repo.write("docs/design/2026-08-11-x-design.md", head() + "`docs/gone.md`\n")
self.assertEqual(self.repo.run(("reference",)), [])
class NumberTest(RepositoryTestCase):
def errors_for(self, text: str) -> list[str]:
self.repo.write("src/app/CLAUDE.md", KOREAN + text)
return self.repo.run(("number",))
def test_a_copied_spring_boot_version_fails(self) -> None:
self.assertFailsWith(self.errors_for("Runtime baseline: Spring Boot 4.0.8.\n"), "'Spring Boot 4.0.8'")
def test_a_major_version_passes(self) -> None:
self.assertEqual(self.errors_for("Spring Boot 4 위에서 돈다.\n"), [])
def test_a_copied_leaf_count_fails(self) -> None:
self.assertFailsWith(self.errors_for("registry는 leaf 65개를 가진다.\n"), "leaf 개수")
self.assertFailsWith(self.errors_for("declares exactly 19 leaf identities.\n"), "leaf 개수")
def test_a_word_count_of_leaves_passes(self) -> None:
self.assertEqual(self.errors_for("leaf 하나를 고른다.\n"), [])
class CommandLineTest(unittest.TestCase):
def test_an_unknown_check_is_a_usage_error(self) -> None:
self.assertEqual(check_docs.main(["--only", "spelling"]), 2)
if __name__ == "__main__":
unittest.main()