diff --git a/docs/README.md b/docs/README.md index 2ca64d37..586744a7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -192,7 +192,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것 | --- | --- | | `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) | | `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 | -| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | +| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. `docs/registries/*.yaml`은 값과 주석에 적은 repo 경로를 본다(행의 `source`·`registered_by`가 옮긴 파일을 가리키면 PR에서 걸린다). 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | | `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 | | `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 | | `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 | diff --git a/docs/upgrade/2026-11-round9-observability.md b/docs/upgrade/2026-11-round9-observability.md index 8de169ca..b790ca46 100644 --- a/docs/upgrade/2026-11-round9-observability.md +++ b/docs/upgrade/2026-11-round9-observability.md @@ -1,7 +1,8 @@ # 업그레이드 안내 — 2026-11 관측 registry·로그 내용·로컬 비밀 기본값 - 범위: 2026-11-12 전체 리뷰의 관측 registry 묶음, 로그 내용 묶음, 비밀·IP 문서 묶음을 고친 변경. 지표·MDC·헤더 registry를 코드에 - 맞췄고, 로그 줄이 원본 경로·SQL·요청 값을 덜 싣게 했고, 로컬 비밀 기본값을 `__LOCAL_DEV_` 규칙에 맞췄다. + 맞췄고, 로그 줄이 원본 경로·SQL·요청 값을 덜 싣게 했고, 로컬 비밀 기본값을 `__LOCAL_DEV_` 규칙에 맞췄다. 2026-11-18에 + registry가 가리키는 경로를 PR에서 보는 문서 검사를 더했다(14번). - 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 RR9-02-05·07·08·09·10·12·13·15·21·22·26·27, RR9-03-05 @@ -27,6 +28,7 @@ compose로 개발하는 사람이다. | 11 | 단일 인스턴스(in-process) lock도 `lock.acquisition`을 센다 | 단일 인스턴스 배포의 lock 경보 기준선을 다시 잡는다 | 새로 생긴 값으로 경보가 울릴 수 있다 | persistence-jpa를 켠 서비스 | | 12 | `docs/registries/mdc-keys.yaml`은 코드가 MDC에 넣는 다섯 key(`request_id`, `trace_id`, `span_id`, `correlation_id`, `user_principal`)만 적는다. `headers.yaml`에서 아무도 쓰지 않던 `Deprecation`·`Sunset`을 지우고 쓰는 헤더 행을 더했다(`tracestate`는 W3C 전파가 쓰므로 `framework:` 행으로 둔다). 지표·헤더 행마다 `source`가 있다 | 자기 MDC key·헤더·지표를 더한 서비스는 `MdcKeys`·행을 같이 더하고 `source`를 적는다 | 새 정합 시험이 실패한다 | registry에 행을 더한 서비스 | | 13 | testFixtures `CardinalityBounds`: `STATUS_CODE`가 7에서 40(숫자 HTTP status)으로, `RESILIENCE4J_OUTCOME`(5)이 `OUTCOME`(6)으로 바뀌었고 `uri` key가 더해졌다. `MetricNaming.ALLOWED_UNITS`는 이름 접미사가 아니라 `unit` 칸의 값이다 | 그 상수를 쓰던 시험을 새 이름·값으로 고친다 | 시험 컴파일이 실패한다 | 그 fixture를 쓰는 서비스 | +| 14 | `scripts/check-docs.py`의 `reference` 검사가 `docs/registries/*.yaml`의 값과 주석에 적은 repo 경로(`src/`·`docs/`·`scripts/` 등으로 시작하는 것)도 본다. 행의 `source`·`registered_by`가 옮기거나 지운 파일을 가리키면 PR 단계에서 걸린다(전에는 main 단계의 대조 시험만 `source`·`registered_by`를 봤고 주석은 아무도 보지 않았다) | `python3 scripts/check-docs.py --only reference`로 자기 registry 행과 주석의 경로가 지금 트리에 있는지 본다. 코드를 옮기는 변경에서 그 행도 고친다 | PR 단계 `documentCheck`가 「없는 경로다」로 실패한다 | registry에 행이나 주석을 더한 서비스 | ## 3. 바뀌지 않은 것 diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index f6757859..8d052685 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -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` | diff --git a/scripts/check-docs.py b/scripts/check-docs.py index 6fb11731..b4c18ede 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -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"(? 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) diff --git a/scripts/tests/test_check_docs.py b/scripts/tests/test_check_docs.py index 7e54169a..bcca29a1 100644 --- a/scripts/tests/test_check_docs.py +++ b/scripts/tests/test_check_docs.py @@ -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]: