ci(docs)!: 문서 검사가 registry YAML이 가리키는 경로도 본다
pr / done (pull_request) Successful in 2m29s

문제: 코드 파일을 옮기는 PR은 docs/registries/*.yaml 행의 source·
registered_by가 옛 경로로 남아도 초록이다. scripts/check-docs.py의 reference
검사는 마크다운만 읽고, 행과 코드를 대조하는 MetricsRegistryCodeAlignmentTest·
HeaderRegistryRuntimeAlignmentTest는 main 단계에서만 돈다. #38이 이렇게
병합돼 main이 빨강이 됐고, main이 빨강인 동안 다른 PR 병합이 모두 멈췄다.

방법: reference 검사가 docs/registries/*.yaml의 줄에서 repo 경로 모양의 낱말
(PATH_ROOTS로 시작, 공백·따옴표·한글에서 끊는다)을 찾아 git이 아는 파일인지
본다. headers.yaml의 "service: src/..." 같은 접두어 붙은 값과 주석의 경로도
같은 규칙으로 잡는다. gates.md 2절에 「지표·헤더를 등록하는 코드를 옮기거나
바꿈 → :app-bootstrap:documentContractTest」 행을 따로 두고, 「지우거나 옮김」
행에 registry YAML을 적는다. docs/README.md 「문서 검사」 표와 관측 업그레이드
안내(14번 행)를 고친다.
버린 대안: (1) 대조 시험을 PR 단계로 옮기기 — 문서 대조는 main 단계라는
결정(2026-09-16)을 바꾸고 Gradle lane 하나를 PR에 더한다. (2) gates.md에
사람이 돌릴 lane만 적기 — #38도 그 표를 따랐어야 했지만 기계가 막지 않으면
다시 샌다.

PR 단계에 두는 이유(gates.md 7절 5번): 이미 PR에서 도는 check-docs.py의
기존 검사가 볼 파일만 넓힌다. 새 태스크·job이 없고 Gradle 없이 1초 안에
끝난다. 옮기는 PR에서 잡지 못하면 main이 빨강이 되어 모든 병합이 멈춘다.

위험·한계: 경로가 있는지만 본다. 파일은 남고 등록 줄만 다른 파일로 옮긴
경우는 여전히 main 단계 document-contract lane이 잡는다(gates.md 새 행).
파생 서비스는 registry 주석에 적은 경로가 없으면 PR에서 새로 실패한다. 주석은
지금까지 어떤 검사도 보지 않았다. source·registered_by는 main 단계 대조
시험에서 이미 실패하던 경로다.

검증: 노트북 `bash scripts/verify.sh docs` rc=0(스크립트 시험 170개 통과).
옛 metrics.yaml에서 `check-docs.py --only reference`가 rc=1로
metrics.yaml:878을 가리킨다. 새 시험 셋은 옛 check-docs.py에서 실패하고, 정규식
변이 셋(따옴표 안 값만 보기, 한글에서 안 끊기, 주석 건너뛰기)이 각각 시험
하나 이상을 실패시킨다.

BREAKING CHANGE: docs/registries/*.yaml의 값과 주석에 적은 repo 경로가 지금
트리에 없으면 PR 단계 documentCheck가 실패한다. 파생 서비스는
`python3 scripts/check-docs.py --only reference`로 자기 행·주석을 확인한다
(docs/upgrade/2026-11-round9-observability.md 14번).
This commit is contained in:
DongHyeonka
2026-11-18 21:17:34 +09:00
parent b43fd78c23
commit a00d559c84
5 changed files with 50 additions and 4 deletions
+15 -1
View File
@@ -17,7 +17,9 @@
registry에 있다. 「있다」는 git이 아는 파일(추적 + 무시되지 않은 새 파일)과 그 위 폴더다. 디스크에만
있는 것(git mv가 남긴 빈 폴더 등)은 새 checkout에 없으므로 세지 않는다. 기록의 「현재 정본」·「대체됨」
경로도 같다. 코드 블록과 「이력」으로 시작하는 인용 블록은 건너뛴다. 마크다운
링크는 lychee와 check-work-docs.py --links가 본다.
링크는 lychee와 check-work-docs.py --links가 본다. registry(docs/registries/*.yaml)의 값(따옴표가 있든
없든)과 주석에 적은 repo 경로도 본다: 행의 `source`·`registered_by`가 옮긴 파일을 가리키면 main
단계의 대조 시험(document-contract)보다 먼저 PR에서 걸린다.
number 살아 있는 문서가 정본이 정하는 숫자를 복사하지 않는다: Spring Boot 버전, leaf 개수.
Spring Boot 버전은 이름 바로 뒤(「Spring Boot」·「Boot」 뒤의 세 자리 버전)만이 아니라 `Spring Boot`
칸이 있는 표 행의 세 자리 버전과, 정본(gradle/libs.versions.toml의 springBoot)과 같은
@@ -134,6 +136,10 @@ LINE_SUFFIX = re.compile(r"(?::\d+(?:[-,]\d+)*)+$")
SOURCE_SET = re.compile(r"^src/[A-Za-z]+(?:/(?:java|resources|proto|kotlin|groovy))?/?$")
GRADLE_PATH = re.compile(r"^:[A-Za-z][\w-]*(?::[A-Za-z][\w-]*)+$")
HISTORY_QUOTE = re.compile(r"^\s*>\s*(?:\*\*)?이력")
# registry YAML: 행이 가리키는 코드 파일. 마크다운이 아니라 인라인 코드가 없으니 경로 모양의 낱말을 본다.
# 한글에서 끊는다: 주석의 「docs/a.yaml에 적는다」는 조사 앞까지가 경로다.
REGISTRY_FILES = "docs/registries/*.yaml"
REGISTRY_PATH = re.compile(r"(?<![\w./-])((?:" + "|".join(re.escape(root) for root in PATH_ROOTS) + r")[^\s\"'`,;()가-힣]+)")
# --- 복사한 숫자
SPRING_BOOT = "Spring Boot 버전"
@@ -562,6 +568,14 @@ def check_reference(root: Path, files: list[str]) -> list[Problem]:
if target and target not in seen and not resolves(root, path, target, known):
seen.add(target)
missing.append((path, number + offset, target))
for path in tracked_files(root, REGISTRY_FILES):
seen = set()
for number, line in enumerate((root / path).read_text(encoding="utf-8").split("\n"), start=1):
for match in REGISTRY_PATH.finditer(line):
target = path_candidate(match.group(1))
if target and target not in seen and not resolves(root, path, target, known):
seen.add(target)
missing.append((path, number, target))
skip = ignored(root, {target for _, _, target in missing})
if missing:
skip |= path_suffixes(root)