ci(docs): 문서 지도와 루트 README 절을 문서 검사가 본다
문제: 「모든 문서 폴더가 `docs/README.md` 지도에 있다」와 「루트 README가 정해진 절을 가진다」(design-docs `conventions/docs-system.md` 7절 K5·K6)를 아무것도 지키지 않는다. 테스트 자원 `broken-readme.md`(일부러 깨뜨린 입력)를 살아 있는 문서로 보고 언어 검사 예외에 둔다. 고른 방법: `scripts/check-docs.py`에 검사 둘을 더한다. docs-check workflow가 인자 없이 돌리므로 PR에서 바로 실패로 돈다. - `map`: `docs/` 바로 아래 폴더가 모두 지도 표의 첫 칸에 있어야 한다. 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. `.md`가 없는 폴더(스냅숏, yaml)도 본다. 지도에 있지만 없는 폴더도 실패다. - `readme`: 첫 줄 `# 제목`, 그 아래 한 문단, `README_SECTIONS`의 `##` 절이 그 순서로 있어야 한다. 사이에 다른 절은 있어도 된다. - 소스 세트 resources 폴더 아래 `.md`(`/src/<세트>/resources/`)는 문서로 보지 않는다. 그래서 `broken-readme.md` 예외 줄을 지운다. 버린 대안: 지도 폴더를 모든 깊이까지 요구하기. 리뷰 라운드 폴더, 납품 패키지 폴더마다 행이 생겨 지도가 목록이 된다. 절을 정확히 일곱 개만 허용하기. 서비스가 절을 더할 수 없게 된다. 위험·한계: `FROZEN` 지문은 건드리지 않았다. leaf·family README 절 검사(K6 뒷부분)와 파일 이름 규칙·실행 산출물 검사(K5 뒷부분)는 넣지 않았다. 검증: - `python3 -m unittest discover -s scripts/tests` 65건 rc=0(새 시험 22건). - 판정 조건 18개를 하나씩 끈 사본마다 자기 시험이 실패했다(rc=1). - `python3 scripts/check-docs.py` rc=0.
This commit is contained in:
@@ -246,6 +246,127 @@ class NumberTest(RepositoryTestCase):
|
||||
self.assertEqual(self.errors_for("leaf 하나를 고른다.\n"), [])
|
||||
|
||||
|
||||
class ScopeTest(RepositoryTestCase):
|
||||
def test_markdown_under_a_source_set_resources_folder_is_not_a_document(self) -> None:
|
||||
self.repo.write("src/app/src/test/resources/fixtures/broken-readme.md", "# Broken\n\n" + ENGLISH * 3)
|
||||
self.assertEqual(self.repo.run(("language",)), [])
|
||||
|
||||
def test_markdown_beside_a_source_set_is_still_a_document(self) -> None:
|
||||
self.repo.write("src/app/src/test/README.md", "# Tests\n\n" + ENGLISH * 3)
|
||||
self.assertFailsWith(self.repo.run(("language",)), "src/app/src/test/README.md: 영어 문서다")
|
||||
|
||||
|
||||
def table(*rows: str) -> str:
|
||||
return "| 폴더 | 무엇 |\n| --- | --- |\n" + "".join(f"| {row} | 설명 |\n" for row in rows)
|
||||
|
||||
|
||||
class MapTest(RepositoryTestCase):
|
||||
def errors_for(self, text: str) -> list[str]:
|
||||
self.repo.write(check_docs.MAP_FILE, "# docs\n\n" + KOREAN + text)
|
||||
return self.repo.run(("map",))
|
||||
|
||||
def test_a_map_that_names_every_folder_passes(self) -> None:
|
||||
self.repo.write("docs/jpa/guide.md", KOREAN)
|
||||
self.repo.write("docs/history/plans/2026-08-11-x-plan.md", KOREAN)
|
||||
checks = "| 검사 | 보는 것 |\n| --- | --- |\n| `language` | 언어 |\n"
|
||||
self.assertEqual(self.errors_for(table("`jpa/`", "`history/plans/`") + "\n" + checks), [])
|
||||
|
||||
def test_a_folder_missing_from_the_map_fails(self) -> None:
|
||||
self.repo.write("docs/redis/operations.md", KOREAN)
|
||||
self.assertFailsWith(self.errors_for(table()), "지도에 없는 문서 폴더다: docs/redis/")
|
||||
|
||||
def test_a_folder_without_markdown_must_be_mapped_too(self) -> None:
|
||||
self.repo.write("docs/security/public-paths-snapshot.txt", "/api/healthcheck\n")
|
||||
self.assertFailsWith(self.errors_for(table()), "지도에 없는 문서 폴더다: docs/security/")
|
||||
|
||||
def test_a_folder_that_only_holds_folders_is_covered_by_its_subfolders(self) -> None:
|
||||
self.repo.write("docs/history/plans/2026-08-11-x-plan.md", KOREAN)
|
||||
self.repo.write("docs/history/study/x.md", KOREAN)
|
||||
errors = self.errors_for(table("`history/`", "`history/plans/`"))
|
||||
self.assertFailsWith(errors, "지도에 없는 문서 폴더다: docs/history/study/")
|
||||
self.assertFalse(any("docs/history/plans/" in error for error in errors), errors)
|
||||
|
||||
def test_folders_below_the_mapped_level_need_no_row(self) -> None:
|
||||
self.repo.write("docs/history/packages/jpa/README.md", KOREAN)
|
||||
self.repo.write("docs/mongodb/advanced/sharding.md", KOREAN)
|
||||
self.repo.write("docs/mongodb/guide.md", KOREAN)
|
||||
self.assertEqual(self.errors_for(table("`history/packages/`", "`mongodb/`")), [])
|
||||
|
||||
def test_a_mapped_folder_that_does_not_exist_fails(self) -> None:
|
||||
self.assertFailsWith(self.errors_for(table("`gone/`")), "지도의 폴더가 없다: docs/gone/")
|
||||
|
||||
def test_a_folder_named_outside_the_first_cell_does_not_count(self) -> None:
|
||||
self.repo.write("docs/redis/operations.md", KOREAN)
|
||||
self.assertFailsWith(self.errors_for(table("운영") + "| 캐시 | `redis/` |\n"),
|
||||
"지도에 없는 문서 폴더다: docs/redis/")
|
||||
|
||||
def test_a_folder_inside_a_code_block_does_not_count(self) -> None:
|
||||
self.repo.write("docs/redis/operations.md", KOREAN)
|
||||
self.assertFailsWith(self.errors_for("```text\n" + table("`redis/`") + "```\n"),
|
||||
"지도에 없는 문서 폴더다: docs/redis/")
|
||||
|
||||
def test_a_folder_may_be_written_from_the_repository_root(self) -> None:
|
||||
self.repo.write("docs/redis/operations.md", KOREAN)
|
||||
self.assertEqual(self.errors_for(table("`docs/redis/`")), [])
|
||||
|
||||
def test_a_placeholder_folder_is_not_an_entry(self) -> None:
|
||||
self.assertEqual(self.errors_for(table("`history/packages/<어댑터>/`")), [])
|
||||
|
||||
def test_a_repository_without_the_map_fails(self) -> None:
|
||||
self.assertFailsWith(self.repo.run(("map",)), "문서 지도가 없다")
|
||||
|
||||
|
||||
def readme(sections: tuple[str, ...] = check_docs.README_SECTIONS, title: str = "# 템플릿",
|
||||
intro: str = "이 저장소가 무엇이고 누가 쓰는지 쓴 한 문단이다.") -> str:
|
||||
parts = [title, "", intro, ""] if intro else [title, ""]
|
||||
for section in sections:
|
||||
parts += [section if section.startswith("#") else f"## {section}", "", KOREAN]
|
||||
return "\n".join(parts)
|
||||
|
||||
|
||||
class ReadmeTest(RepositoryTestCase):
|
||||
def errors_for(self, text: str) -> list[str]:
|
||||
self.repo.write(check_docs.README_FILE, text)
|
||||
return self.repo.run(("readme",))
|
||||
|
||||
def test_every_section_in_order_passes(self) -> None:
|
||||
self.assertEqual(self.errors_for(readme()), [])
|
||||
|
||||
def test_other_sections_between_the_required_ones_pass(self) -> None:
|
||||
sections = check_docs.README_SECTIONS[:2] + ("부록",) + check_docs.README_SECTIONS[2:]
|
||||
self.assertEqual(self.errors_for(readme(sections)), [])
|
||||
|
||||
def test_each_missing_section_fails(self) -> None:
|
||||
for missing in check_docs.README_SECTIONS:
|
||||
with self.subTest(missing=missing):
|
||||
sections = tuple(section for section in check_docs.README_SECTIONS if section != missing)
|
||||
self.assertFailsWith(self.errors_for(readme(sections)), f"「## {missing}」 절이 없다")
|
||||
|
||||
def test_sections_out_of_order_fail(self) -> None:
|
||||
sections = ("시작하기", "프로젝트 구조") + check_docs.README_SECTIONS[2:]
|
||||
self.assertFailsWith(self.errors_for(readme(sections)), "「## 시작하기」 절은 「## 프로젝트 구조」 절 뒤에 온다")
|
||||
|
||||
def test_a_readme_that_does_not_start_with_a_title_fails(self) -> None:
|
||||
self.assertFailsWith(self.errors_for(readme(title="템플릿 소개")), "첫 줄은 `# 제목`이다")
|
||||
self.assertFailsWith(self.errors_for("소개 한 줄\n\n" + readme()), "첫 줄은 `# 제목`이다")
|
||||
|
||||
def test_a_readme_without_an_introduction_fails(self) -> None:
|
||||
self.assertFailsWith(self.errors_for(readme(intro="")), "한 문단을 둔다")
|
||||
|
||||
def test_a_section_heading_at_another_level_does_not_count(self) -> None:
|
||||
sections = tuple("### 문서 지도" if section == "문서 지도" else section
|
||||
for section in check_docs.README_SECTIONS)
|
||||
self.assertFailsWith(self.errors_for(readme(sections)), "「## 문서 지도」 절이 없다")
|
||||
|
||||
def test_a_section_heading_inside_a_code_block_does_not_count(self) -> None:
|
||||
sections = tuple(section for section in check_docs.README_SECTIONS if section != "검증")
|
||||
text = readme(sections) + "\n```markdown\n## 검증\n```\n"
|
||||
self.assertFailsWith(self.errors_for(text), "「## 검증」 절이 없다")
|
||||
|
||||
def test_a_repository_without_a_readme_fails(self) -> None:
|
||||
self.assertFailsWith(self.repo.run(("readme",)), "루트 README가 없다")
|
||||
|
||||
|
||||
class CommandLineTest(unittest.TestCase):
|
||||
def test_an_unknown_check_is_a_usage_error(self) -> None:
|
||||
self.assertEqual(check_docs.main(["--only", "spelling"]), 2)
|
||||
|
||||
Reference in New Issue
Block a user