diff --git a/scripts/check-docs.py b/scripts/check-docs.py index 759254bd..cb5628f3 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -12,7 +12,9 @@ 정본과 대체됨이 가리키는 경로는 지금 있다. reference 살아 있는 문서의 인라인 코드 안 repo 경로(src/, docs/, scripts/, compose/, .github/로 시작. 2026-11-07에 지운 infra/ 아래 경로도 본다)와 Gradle 경로(:a:b)가 지금 트리와 - registry에 있다. 코드 블록과 「이력」으로 시작하는 인용 블록은 건너뛴다. 마크다운 + registry에 있다. 「있다」는 git이 아는 파일(추적 + 무시되지 않은 새 파일)과 그 위 폴더다. 디스크에만 + 있는 것(git mv가 남긴 빈 폴더 등)은 새 checkout에 없으므로 세지 않는다. 기록의 「현재 정본」·「대체됨」 + 경로도 같다. 코드 블록과 「이력」으로 시작하는 인용 블록은 건너뛴다. 마크다운 링크는 lychee와 check-work-docs.py --links가 본다. number 살아 있는 문서가 정본이 정하는 숫자를 복사하지 않는다: Spring Boot 버전, leaf 개수. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」·「Boot」 뒤의 세 자리 버전)만이 아니라 `Spring Boot` @@ -49,6 +51,7 @@ from __future__ import annotations import datetime import hashlib import json +import posixpath import re import subprocess import sys @@ -270,6 +273,7 @@ def backticked_paths(value: str) -> list[str]: def check_head(root: Path, files: list[str]) -> list[Problem]: problems = [] + known = known_paths(root) for path in files: kind = record_kind(path) if kind is None: @@ -323,7 +327,7 @@ def check_head(root: Path, files: list[str]) -> list[Problem]: if not canonical.startswith("없음") and not targets: fail("현재 정본은 `경로`(여럿이면 쉼표) 또는 「없음 — 이유」다", at) for target in targets: - if not (root / target).exists(): + if not is_known(known, target): fail(f"현재 정본 경로가 없다: {target}", at) if status == "대체됨" and "대체됨" not in fields: fail("상태가 대체됨이면 「대체됨」 칸에 대체한 문서를 적는다") @@ -334,7 +338,7 @@ def check_head(root: Path, files: list[str]) -> list[Problem]: if not targets: fail(f"「{name}」 칸은 `경로`를 적는다", at) for target in targets: - if not (root / target).exists(): + if not is_known(known, target): fail(f"「{name}」 경로가 없다: {target}", at) return problems @@ -386,15 +390,30 @@ def path_candidate(token: str) -> str | None: return token or None -def resolves(root: Path, document: str, target: str) -> bool: - if (root / target).exists(): +def known_paths(root: Path) -> set[str]: + """Every file git knows or would add, and every folder above one. A path that is only on disk does not + count: an empty folder `git mv` leaves behind, or a file nobody added, is not in a fresh checkout.""" + paths: set[str] = set() + for name in tracked_files(root, "."): + parts = name.split("/") + for end in range(1, len(parts) + 1): + paths.add("/".join(parts[:end])) + return paths + + +def is_known(known: set[str], path: str) -> bool: + return posixpath.normpath(path) in known + + +def resolves(root: Path, document: str, target: str, known: set[str]) -> bool: + if is_known(known, target): return True # src/main/... in a leaf document is written relative to that leaf. - folder = (root / document).parent - while folder != root and root in folder.parents: - if (folder / target).exists(): + folder = posixpath.dirname(document) + while folder: + if is_known(known, f"{folder}/{target}"): return True - folder = folder.parent + folder = posixpath.dirname(folder) return False @@ -427,6 +446,7 @@ def path_suffixes(root: Path) -> set[str]: def check_reference(root: Path, files: list[str]) -> list[Problem]: projects = registry_projects(root) + known = known_paths(root) missing: list[tuple[str, int, str]] = [] problems = [] for path in files: @@ -448,7 +468,7 @@ def check_reference(root: Path, files: list[str]) -> list[Problem]: target = path_candidate(token) if target and SOURCE_SET.match(target): continue - if target and target not in seen and not resolves(root, path, target): + if target and target not in seen and not resolves(root, path, target, known): seen.add(target) missing.append((path, number + offset, target)) skip = ignored(root, {target for _, _, target in missing}) diff --git a/scripts/tests/test_check_docs.py b/scripts/tests/test_check_docs.py index b36c630d..2924849e 100644 --- a/scripts/tests/test_check_docs.py +++ b/scripts/tests/test_check_docs.py @@ -182,6 +182,10 @@ class HeadBlockTest(RepositoryTestCase): 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_folder_left_empty_on_disk_fails(self) -> None: + (self.repo.root / "docs/moved").mkdir(parents=True) + self.assertFailsWith(self.errors_for(head(canonical="`docs/moved/`")), "현재 정본 경로가 없다: docs/moved/") + def test_a_canonical_value_without_a_path_fails(self) -> None: self.assertFailsWith(self.errors_for(head(canonical="jpa 문서")), "현재 정본은") @@ -210,6 +214,15 @@ class ReferenceTest(RepositoryTestCase): def test_a_missing_repository_path_fails(self) -> None: self.assertFailsWith(self.errors_for("`docs/gone.md`를 읽는다.\n"), "없는 경로다: docs/gone.md") + def test_a_folder_left_empty_on_disk_fails(self) -> None: + # `git mv` leaves the old folder behind. A fresh checkout does not have it, so it is not a path. + (self.repo.root / "docs/moved").mkdir(parents=True) + self.assertFailsWith(self.errors_for("`docs/moved/`를 읽는다.\n"), "없는 경로다: docs/moved/") + + def test_a_folder_that_holds_a_file_passes(self) -> None: + self.repo.write("docs/kept/a.md", KOREAN) + self.assertEqual(self.errors_for("`docs/kept/`를 읽는다.\n"), []) + def test_an_existing_path_with_a_line_number_passes(self) -> None: self.assertEqual(self.errors_for("`docs/live.md:12`를 읽는다.\n"), [])