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
+29
View File
@@ -261,6 +261,35 @@ class ReferenceTest(RepositoryTestCase):
self.repo.write("docs/design/2026-08-11-x-design.md", head() + "`docs/gone.md`\n")
self.assertEqual(self.repo.run(("reference",)), [])
def test_a_registry_row_that_names_a_moved_file_fails(self) -> None:
# A meter registration moved to another leaf while its metrics.yaml row kept the old path
# (2026-11-13): only the main-stage document-contract lane saw it.
self.repo.write("src/app/src/main/java/Worker.java", "class Worker {}\n")
self.repo.write("docs/registries/metrics.yaml",
"metrics:\n - name: queue.depth\n"
" registered_by: \"src/gone/src/main/java/Worker.java\"\n")
self.assertFailsWith(self.repo.run(("reference",)),
"docs/registries/metrics.yaml:3: 없는 경로다: src/gone/src/main/java/Worker.java")
def test_a_missing_registry_path_after_a_prefix_fails(self) -> None:
self.repo.write("docs/registries/headers.yaml",
"headers:\n - source: \"service: src/gone/src/main/java/Headers.java\"\n")
self.assertFailsWith(self.repo.run(("reference",)),
"headers.yaml:2: 없는 경로다: src/gone/src/main/java/Headers.java")
def test_a_missing_registry_path_in_a_comment_fails_even_before_a_korean_particle(self) -> None:
self.repo.write("docs/registries/env-keys.yaml", "# 정본은 docs/gone.yaml에 적는다.\nkeys: []\n")
self.assertFailsWith(self.repo.run(("reference",)), "env-keys.yaml:1: 없는 경로다: docs/gone.yaml")
def test_registry_paths_that_exist_pass_with_or_without_a_prefix(self) -> None:
self.repo.write("src/app/src/main/java/Headers.java", "class Headers {}\n")
self.repo.write("docs/registries/headers.yaml",
"# 정본은 `docs/live.md`다.\nheaders:\n"
" - source: \"src/app/src/main/java/Headers.java\"\n"
" - source: \"service: src/app/src/main/java/Headers.java\"\n"
" - source: \"framework: spring\"\n")
self.assertEqual(self.repo.run(("reference",)), [])
class NumberTest(RepositoryTestCase):
def errors_for(self, text: str) -> list[str]: