From 2d43356136a8eb2336b64eae82ac4728ca8f9773 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 18:31:33 +0900 Subject: [PATCH] =?UTF-8?q?ci(docs):=20=EC=B0=B8=EC=A1=B0=20=EA=B2=80?= =?UTF-8?q?=EC=82=AC=EA=B0=80=20=EB=94=94=EC=8A=A4=ED=81=AC=EC=97=90?= =?UTF-8?q?=EB=A7=8C=20=EB=82=A8=EC=9D=80=20=ED=8F=B4=EB=8D=94=EB=A5=BC=20?= =?UTF-8?q?=EC=9E=88=EB=8A=94=20=EA=B2=BD=EB=A1=9C=EB=A1=9C=20=EC=84=B8?= =?UTF-8?q?=EC=A7=80=20=EC=95=8A=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 참조 검사(reference)와 머리 블록의 「현재 정본」·「대체됨」 검사는 경로가 있는지를 파일 시스템(Path.exists)으로 본다. git mv는 옮긴 뒤 빈 옛 폴더를 디스크에 남긴다. 그래서 지운 폴더를 가리키는 살아 있는 문서가 노트북에서는 통과하고, 빈 폴더가 없는 새 checkout(PR workflow)에서만 실패한다. 알림 ADR을 옮길 때(39d4f248) 실제로 그랬다: docs/README.md에 쓴 옛 폴더 경로가 빈 docs/notification/adr/ 때문에 통과했고, 폴더를 지운 뒤에야 걸렸다. 「있다」를 git이 아는 파일(추적 + 무시되지 않은 새 파일, 문서 목록과 같은 git ls-files)과 그 위 폴더로 바꿨다(known_paths). leaf 기준 상대 경로를 위 폴더로 올라가며 찾는 규칙은 그대로다. 무시되는 경로(src/.env 등)는 전처럼 git check-ignore가 건너뛴다. 버린 대안: 빈 폴더만 따로 빼기. 아무도 추가하지 않은 파일(디스크에만 있는 build 밖 산출물)도 같은 거짓 통과를 만든다. git이 보는 것과 같게 하면 노트북과 PR workflow가 같은 답을 낸다. 자기 시험 셋을 더했다(79 OK): 빈 폴더를 가리키는 참조가 실패, 파일이 든 폴더는 통과, 빈 폴더를 가리키는 「현재 정본」이 실패. 변이 시험: 디스크의 모든 경로를 다시 세게 하면 rc=1, 빈 폴더 시험 둘이 실패한다. 검증(노트북): check-docs.py OK(여섯 검사 걸림 0, 0.8초), 자기 시험 79 OK. 빈 docs/notification/adr/를 다시 만들어도 known_paths는 그 폴더를 모른다. --- scripts/check-docs.py | 40 ++++++++++++++++++++++++-------- scripts/tests/test_check_docs.py | 13 +++++++++++ 2 files changed, 43 insertions(+), 10 deletions(-) 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"), [])