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
+2 -1
View File
@@ -64,7 +64,8 @@ workflow에만 있는 job: `pr.yml` `done`의 마지막 step과 `main.yml`의 `v
| 공개 경로·보안 체인 | `verifyPublicPathSnapshot` |
| 의존성 | `verifyDependencyLocks` |
| 문서(`docs/**`, `AGENTS.md`·`CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) + `python3 scripts/check-docs.py` |
| 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서가 가리키던 경로가 사라진다) |
| 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서와 `docs/registries/*.yaml`이 가리키던 경로가 사라진다) |
| 지표·헤더를 등록하는 코드(이름 상수, 등록 줄, 그 파일)를 옮기거나 바꿈 | `:app-bootstrap:documentContractTest`(registry 행과 등록 코드를 대조한다. 파일은 남고 등록만 다른 파일로 간 행은 이 lane만 본다) |
| `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서 | `python3 scripts/check-work-docs.py` |
| 다른 매뉴얼에서 이력 ID를 걷어냄 | `python3 scripts/check-work-docs.py --history <파일 또는 폴더>` |
| build-logic·workflow(`.gitea/`) | `-p build-logic check javadoc`, `verifyStrictLaneStages --dry-run` |