문제: 코드 파일을 옮기는 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:
+15
-1
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user