ci(docs): 참조 검사가 디스크에만 남은 폴더를 있는 경로로 세지 않는다

참조 검사(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는 그 폴더를 모른다.
This commit is contained in:
DongHyeonka
2026-11-07 18:31:33 +09:00
parent 83e9bd3dc3
commit 2d43356136
2 changed files with 43 additions and 10 deletions
+30 -10
View File
@@ -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})
+13
View File
@@ -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"), [])