From 1c00f89765b62b5b05e83e33f305f11190884014 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 12:26:37 +0900 Subject: [PATCH] =?UTF-8?q?ci(docs):=20=EB=AC=B8=EC=84=9C=20=EC=96=B8?= =?UTF-8?q?=EC=96=B4=C2=B7=EB=A8=B8=EB=A6=AC=20=EB=B8=94=EB=A1=9D=C2=B7?= =?UTF-8?q?=EC=B0=B8=EC=A1=B0=C2=B7=EC=88=AB=EC=9E=90=EB=A5=BC=20PR?= =?UTF-8?q?=EC=97=90=EC=84=9C=20=EA=B2=80=EC=82=AC=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 살아 있는 문서의 언어, 기록의 상태 표시, 인라인 코드 경로, 복사한 버전·개수를 아무 검사도 보지 않는다. lychee는 마크다운 링크만 보는데 경로 대부분은 인라인 코드로 쓰여 있고, leaf CLAUDE.md는 Spring Boot 버전을 4.0.0으로 적어 둔 채 낡았다. 고른 방법: Gradle 밖 scripts/check-docs.py 하나에 검사 넷을 둔다. - language: 살아 있는 문서와 ADR 본문이 한국어인가. 판정은 보고 언어 훅 H11과 같다(코드·명령·경로·인용을 빼고 영어 낱말 3개 이상, 한글 비율 0.3 미만이면 영어). - head: 기록·ADR 맨 위 머리 블록의 칸, 종류별 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로. - reference: 인라인 코드 안 src/·docs/·scripts/·infra/·.github/ 경로와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, 「> 이력」 인용, 제거 표, upgrade/는 건너뛴다. leaf 기준 경로는 어느 파일의 끝부분과 맞으면 있다고 본다. - number: Spring Boot x.y.z와 leaf 개수 문장. 예외 목록(scripts/check-docs-exceptions.txt)은 2026-11-07 기준선 217줄이고 줄기만 한다. 줄마다 sha256 지문이 스크립트의 FROZEN에 있어야 해서 목록에 새 줄을 더하면 실패하고, 더는 걸리지 않는 줄을 남겨 두면 실패한다. workflow docs-check.yml이 PR마다 경로 필터 없이 자기 시험과 검사를 돌린다. 코드에서 파일을 지우는 변경이 문서를 낡게 만들기 때문이다. 같은 커밋에서 지도 CLAUDE.md의 Spring Boot 버전 복사를 정본 가리키기로 고쳤다. 버린 대안: 예외 목록 하나에 「늘리지 않는다」는 약속만 두는 방식(테스트의 KNOWN_DEVIATIONS와 같은 꼴)은 brief가 요구한 「더하면 실패」를 기계로 막지 못한다. 기준선을 git 이력(merge-base)과 비교하는 방식은 얕은 checkout에서 깨진다. 검사를 link-check.yml에 더하는 방식은 그 workflow가 docs 경로에만 걸리고 repository-contract 테스트가 trigger를 고정한다. CI 재편 때 단계 workflow로 접는다. 위험·한계: 타입 이름 검사(지운 클래스 이름)는 넣지 않았다. 외부 타입과 구분하려면 git 전체 이력이 필요하다. 경로 검사는 루트 폴더로 시작하는 경로만 보므로 src/ 기준 상대 경로(adapter/outbound/...)는 보지 않는다. leaf 개수 규칙은 설계 문서의 개수 같은 정당한 숫자도 잡을 수 있다(지금 generator 출력 예 하나가 예외 목록에 있다). 구조 정리가 src/messaging 등을 옮기면 예외 줄의 경로가 바뀌므로 그 병합에서 FROZEN을 함께 고쳐야 한다. 레지스트리 yaml 설명 칸의 언어는 보지 않는다. 검증: python3 -m unittest discover -s scripts/tests 42개 통과. 변이 시험: 기준선 확인·낡은 예외 확인·언어 판정·이력 인용 건너뛰기·소스 세트 이름· 끝부분 대조·상태 어휘를 하나씩 끄면 해당 시험이 실패했다. python3 scripts/check-docs.py rc=0(language 181·reference 7·number 29가 모두 예외, head 0), check-work-docs.py rc=0. --- .github/workflows/docs-check.yml | 28 ++ CLAUDE.md | 3 +- docs/README.md | 20 ++ scripts/check-docs-exceptions.txt | 228 +++++++++++++ scripts/check-docs.py | 543 ++++++++++++++++++++++++++++++ scripts/tests/test_check_docs.py | 252 ++++++++++++++ 6 files changed, 1073 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/docs-check.yml create mode 100644 scripts/check-docs-exceptions.txt create mode 100755 scripts/check-docs.py create mode 100644 scripts/tests/test_check_docs.py diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 00000000..932a3fa6 --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,28 @@ +name: docs-check + +# Document language, record head blocks, references and copied numbers (scripts/check-docs.py). +# It runs on every pull request, not on a docs/** path filter: deleting a file or a Gradle project +# in code is exactly what makes a living document point at nothing, and that change touches no +# document. The checker is plain Python outside Gradle, because the build does not parse documents. +on: + pull_request: + push: + branches: ["main"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - name: Test the document checker + run: python3 -m unittest discover -s scripts/tests + - name: Check documents + run: python3 scripts/check-docs.py diff --git a/CLAUDE.md b/CLAUDE.md index 3014839f..ececa1cf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ ## 1. 이 repo -- Java 21 + Spring Boot 4.0.8 Gradle 멀티모듈 Clean Architecture 백엔드 템플릿이다. 서비스는 이 repo를 받아 도메인을 채운다. +- Java 21 + Spring Boot Gradle 멀티모듈(버전은 `src/gradle/libs.versions.toml`) Clean Architecture 백엔드 템플릿이다. 서비스는 이 repo를 받아 도메인을 채운다. - Gradle 루트는 `src/`다. Gradle 명령은 `src/`에서 실행한다. - 규칙의 정본은 `AGENTS.md`다. leaf 목록·경로·허용 의존의 정본은 `src/config/architecture/modules.json`(registry)이다. 각 leaf의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`가 정한다. @@ -51,6 +51,7 @@ brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이 - 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. 전체 `test`·`check`·`ci`는 brief가 시킬 때 돌린다. - 게이트 목록(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck` 등)과 바꾼 것에 맞는 게이트는 [docs/work/reference/gates.md](docs/work/reference/gates.md)다. - `docs/work/`, 이 파일, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`를 돌린다(분량, 본문 이력 ID 0, 상대 링크). +- 문서(`.md`)나 문서가 가리키는 경로·Gradle 프로젝트를 바꿨으면 `python3 scripts/check-docs.py`를 돌린다(언어, 기록의 머리 블록, 참조, 복사한 숫자). PR마다 `docs-check` workflow가 같은 검사를 돈다. 규칙은 [docs/README.md](docs/README.md)다. ## 5. 코드만 보고는 헷갈리는 곳 diff --git a/docs/README.md b/docs/README.md index e10c5606..d098e065 100644 --- a/docs/README.md +++ b/docs/README.md @@ -120,6 +120,26 @@ - 루트 README는 「프로젝트 구조」(최상위 폴더와 `src/` 폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이 어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서는 design-docs `conventions/docs-system.md` 6절이다. +## 문서 검사 + +`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 넷을 본다. PR마다 workflow `docs-check`가 +돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이 +문서를 낡게 만든다. + +| 검사 | 보는 것 | +| --- | --- | +| `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) | +| `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 | +| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `infra/`, `.github/`로 시작)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | +| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가 | + +- 하나만 돌리기: `python3 scripts/check-docs.py --only head`. +- 예외 목록 `scripts/check-docs-exceptions.txt`는 2026-11-07의 기준선이고 줄기만 한다. 문서를 번역하거나 고쳐서 + 더는 걸리지 않으면 그 줄을 지운다(남겨 두면 실패한다). 목록에 새 줄을 더하면 실패한다. 기준선을 늘리는 것은 + 규칙을 바꾸는 일이라 소유자 결정이 필요하다. +- 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`. +- 마크다운 상대 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다. + ## 여기에 없는 것 - 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다. diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt new file mode 100644 index 00000000..a40b3255 --- /dev/null +++ b/scripts/check-docs-exceptions.txt @@ -0,0 +1,228 @@ +# scripts/check-docs.py의 예외 목록. 2026-11-07 기준선이고 줄기만 한다. +# +# - 이 목록에 새 줄을 더하면 검사가 실패한다. 줄마다 check-docs.py의 FROZEN에 지문이 있어야 한다. +# - 번역하거나 고쳐서 더는 걸리지 않는 줄은 지운다. 남겨 두면 검사가 실패한다. +# - 형식: <검사><탭><경로>[<탭><걸린 값>]. 「#」으로 시작하는 줄과 빈 줄은 읽지 않는다. + +# 언어: 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR. 다음 단계(살아 있는 문서 번역, ADR 번역)에서 지운다. +language .github/dependency-vulnerability-policy.md +language .github/pull_request_template.md +language docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md +language docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md +language docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md +language docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md +language docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md +language docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md +language docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md +language docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md +language docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md +language docs/adr/ADR-JPA-001-domain-owns-persistence-model.md +language docs/adr/ADR-JPA-002-full-transaction-retry.md +language docs/adr/ADR-JPA-003-completion-unknown.md +language docs/adr/ADR-JPA-004-flyway-schema-source-of-truth.md +language docs/adr/ADR-JPA-005-postgresql-real-contract.md +language docs/adr/ADR-JPA-006-canonical-technical-audit.md +language docs/adr/ADR-MONGO-001-platform-boundary.md +language docs/adr/ADR-MONGO-002-bson-representation.md +language docs/adr/ADR-MONGO-003-transaction-retry.md +language docs/adr/ADR-MONGO-004-index-schema-admin-plane.md +language docs/adr/ADR-MONGO-ADV-001-capability-promotion.md +language docs/adr/ADR-WEB-ADV-001-streaming-is-live-delivery.md +language docs/adr/ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md +language docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md +language docs/adr/ADR-WS-001-platform-as-packages-and-its-boundaries.md +language docs/adr/ADR-WS-002-resume-and-cluster.md +language docs/adr/ADR-WS-003-stomp-and-broker-relay.md +language docs/compatibility/grpc-advanced-support-matrix.md +language docs/compatibility/grpc-support-matrix.md +language docs/fileserver/configuration.md +language docs/fileserver/design-deviations.md +language docs/fileserver/http-contract.md +language docs/fileserver/operations.md +language docs/fileserver/security.md +language docs/fileserver/storage-certification.md +language docs/fileserver/support-matrix.md +language docs/fileserver/upgrade-guide.md +language docs/httpclient/configuration-reference.md +language docs/httpclient/operations.md +language docs/httpclient/performance-baseline.md +language docs/httpclient/release-checklist.md +language docs/httpclient/repository-adaptation.md +language docs/httpclient/retry-and-ambiguity.md +language docs/httpclient/security.md +language docs/httpclient/streaming.md +language docs/httpclient/support-matrix.md +language docs/jpa/batch-write-guide.md +language docs/jpa/entity-mapping-guide.md +language docs/jpa/experimental-promotion-checklist.md +language docs/jpa/experimental-support-matrix.md +language docs/jpa/migration-guide.md +language docs/jpa/observability.md +language docs/jpa/postgresql-extensions.md +language docs/jpa/query-fetch-guide.md +language docs/jpa/repository-adaptation.md +language docs/jpa/runbooks.md +language docs/jpa/security.md +language docs/jpa/support-matrix.md +language docs/jpa/transaction-guide.md +language docs/mongodb/advanced/encryption.md +language docs/mongodb/advanced/multi-tenancy.md +language docs/mongodb/advanced/sharding.md +language docs/mongodb/advanced/signoff/README.md +language docs/mongodb/bson-mapping-guide.md +language docs/mongodb/consistency-transaction-guide.md +language docs/mongodb/document-modeling-guide.md +language docs/mongodb/query-aggregation-guide.md +language docs/mongodb/repository-adaptation.md +language docs/mongodb/runbooks/failover.md +language docs/mongodb/runbooks/unknown-commit.md +language docs/mongodb/schema-index-migration-guide.md +language docs/mongodb/security-observability.md +language docs/mongodb/support-matrix.md +language docs/notification/adr/NOTIF-ADR-001-durable-acceptance.md +language docs/notification/adr/NOTIF-ADR-002-event-ledger-projection.md +language docs/notification/adr/NOTIF-ADR-003-ambiguous-submission.md +language docs/notification/adr/NOTIF-ADR-004-fcm-fid-primary.md +language docs/notification/at-rest-threat-model.md +language docs/notification/callback-reconciliation.md +language docs/notification/configuration-reference.md +language docs/notification/delivery-evidence.md +language docs/notification/migration-guide.md +language docs/notification/module-mapping.md +language docs/notification/operations.md +language docs/notification/provider-runbooks.md +language docs/notification/security-privacy.md +language docs/notification/support-matrix.md +language docs/observability/log-fields.md +language docs/redis/command-policy.md +language docs/redis/operations.md +language docs/redis/support-matrix.md +language docs/redis/upgrade-guide.md +language docs/runbooks/adapter-adapter-disabled.md +language docs/runbooks/auth-audience-mismatch.md +language docs/runbooks/auth-claim-mapping-failed.md +language docs/runbooks/auth-issuer-mismatch.md +language docs/runbooks/auth-jwks-unavailable.md +language docs/runbooks/auth-kid-unknown.md +language docs/runbooks/auth-public-path-misconfiguration.md +language docs/runbooks/auth-token-expired.md +language docs/runbooks/auth-token-invalid-signature.md +language docs/runbooks/auth-token-malformed.md +language docs/runbooks/auth-token-missing.md +language docs/runbooks/authz-insufficient-permission.md +language docs/runbooks/authz-tenant-mismatch.md +language docs/runbooks/cache-stampede-lock-timeout.md +language docs/runbooks/cache-unavailable.md +language docs/runbooks/db-deadlock.md +language docs/runbooks/db-idle-in-tx-timeout.md +language docs/runbooks/db-query-canceled.md +language docs/runbooks/db-serialization-failure.md +language docs/runbooks/db-unavailable.md +language docs/runbooks/dependency-4xx-client.md +language docs/runbooks/dependency-5xx-server.md +language docs/runbooks/dependency-circuit-open.md +language docs/runbooks/dependency-connect-failed.md +language docs/runbooks/dependency-dns-failed.md +language docs/runbooks/dependency-timeout.md +language docs/runbooks/file-download-streaming-failure.md +language docs/runbooks/grpc-advanced-capabilities.md +language docs/runbooks/grpc-platform-operations.md +language docs/runbooks/idempotency-unavailable.md +language docs/runbooks/lock-acquisition-timeout.md +language docs/runbooks/management-actuator-forbidden.md +language docs/runbooks/migration-failed.md +language docs/runbooks/runtime-jvm-oom.md +language docs/runbooks/startup-profile-mismatch.md +language docs/runbooks/startup-required-adapter-disabled.md +language docs/runbooks/startup-validation-failed.md +language docs/runbooks/template.md +language docs/storage-capability-boundary.md +language docs/web/advanced-capabilities.md +language docs/web/openapi-32-compatibility.md +language docs/web/patch-contract.md +language docs/web/repository-adaptation.md +language docs/web/runbook.md +language docs/web/streaming-contract.md +language docs/web/virtual-thread-profile.md +language docs/websocket/runbook.md +language infra/httpclient/README.md +language infra/httpclient/oauth2/README.md +language infra/httpclient/proxy/README.md +language infra/httpclient/tls/README.md +language infra/jpa/postgres/README.md +language infra/keycloak/README.md +language infra/messaging/tls/README.md +language infra/redis-sdk/README.md +language infra/redis-sdk/acl/README.md +language src/adapter/inbound/messaging/CLAUDE.md +language src/adapter/inbound/web-advanced/CLAUDE.md +language src/adapter/inbound/web/CLAUDE.md +language src/adapter/inbound/websocket/CLAUDE.md +language src/adapter/outbound/cache-redis/CLAUDE.md +language src/adapter/outbound/cache-redis/README.md +language src/adapter/outbound/fileserver/CLAUDE.md +language src/adapter/outbound/fileserver/README.md +language src/adapter/outbound/httpclient/CLAUDE.md +language src/adapter/outbound/httpclient/README.md +language src/adapter/outbound/identifier/CLAUDE.md +language src/adapter/outbound/messaging-kafka/CLAUDE.md +language src/adapter/outbound/messaging/CLAUDE.md +language src/adapter/outbound/notification/CLAUDE.md +language src/adapter/outbound/objectstorage/CLAUDE.md +language src/adapter/outbound/objectstorage/README.md +language src/adapter/outbound/persistence-fileserver/CLAUDE.md +language src/adapter/outbound/persistence-jpa/CLAUDE.md +language src/adapter/outbound/persistence-mongo/CLAUDE.md +language src/adapter/outbound/persistence-notification/CLAUDE.md +language src/adapter/outbound/redis-sdk/README.md +language src/adapter/outbound/support/CLAUDE.md +language src/app-bootstrap/CLAUDE.md +language src/app-bootstrap/src/test/resources/developer-experience/broken-readme.md +language src/application-core/CLAUDE.md +language src/build-logic/README.md +language src/composition/outbox-relay/CLAUDE.md +language src/config/architecture/README.md +language src/domain-core/CLAUDE.md +language src/optional-platforms/README.md +language src/sample-portfolio/CLAUDE.md +language src/shared-contract/CLAUDE.md + +# 참조: 지금 트리·registry에 없는 경로. 고치거나 「> 이력」 인용 블록으로 옮기면 지운다. +reference AGENTS.md src/build-tools/ +reference docs/mongodb/consumer-leaf-guide.md :adapter:outbound:persistence-note:check +reference docs/web/http-contract.md docs/architecture/backend-api-and-server-state-contract.md +reference docs/work/operate.md :a:test +reference docs/work/operate.md :b:test +reference src/README.md .github/ci-gate-matrix.yml +reference src/README.md .github/scripts/verify-gate-matrix.sh + +# 숫자: 정본(src/gradle/libs.versions.toml, registry)이 정하는 값을 복사한 곳. 정본을 가리키게 고치면 지운다. +number docs/compatibility/grpc-support-matrix.md Spring Boot 4.0.8 +number docs/httpclient/repository-adaptation.md 19 leaf +number docs/httpclient/repository-adaptation.md Spring Boot 4.0.8 +number docs/jpa/repository-adaptation.md 19 leaf +number docs/jpa/repository-adaptation.md Spring Boot 4.0.8 +number docs/manual/01-generator.md 5 leaf +number docs/mongodb/repository-adaptation.md 19 leaf +number docs/mongodb/repository-adaptation.md Spring Boot 4.0.8 +number src/adapter/inbound/graphql/CLAUDE.md Spring Boot 4.0.0 +number src/adapter/inbound/graphql/README.md 19개 leaf +number src/adapter/inbound/graphql/README.md 24개 leaf +number src/adapter/inbound/graphql/README.md 43개 leaf +number src/adapter/inbound/grpc/CLAUDE.md Spring Boot 4.0.0 +number src/adapter/inbound/web/CLAUDE.md Spring Boot 4.0.0 +number src/adapter/inbound/websocket/CLAUDE.md Spring Boot 4.0.8 +number src/adapter/outbound/cache-redis/CLAUDE.md Spring Boot 4.0.0 +number src/adapter/outbound/fileserver/CLAUDE.md Spring Boot 4.0.0 +number src/adapter/outbound/httpclient/CLAUDE.md Spring Boot 4.0.0 +number src/adapter/outbound/identifier/CLAUDE.md Spring Boot 4.0.8 +number src/adapter/outbound/messaging/CLAUDE.md Spring Boot 4.0.8 +number src/adapter/outbound/notification/CLAUDE.md Spring Boot 4.0.0 +number src/adapter/outbound/objectstorage/CLAUDE.md Spring Boot 4.0.0 +number src/adapter/outbound/persistence-jpa/CLAUDE.md Spring Boot 4.0.0 +number src/adapter/outbound/persistence-mongo/CLAUDE.md Spring Boot 4.0.0 +number src/adapter/outbound/support/CLAUDE.md Spring Boot 4.0.0 +number src/app-bootstrap/CLAUDE.md Spring Boot 4.0.0 +number src/domain-core/CLAUDE.md Spring Boot 4.0.0 +number src/sample-portfolio/CLAUDE.md Spring Boot 4.0.0 +number src/shared-contract/CLAUDE.md Spring Boot 4.0.0 diff --git a/scripts/check-docs.py b/scripts/check-docs.py new file mode 100755 index 00000000..1b83b9f1 --- /dev/null +++ b/scripts/check-docs.py @@ -0,0 +1,543 @@ +#!/usr/bin/env python3 +"""문서 검사 넷: 언어, 기록의 머리 블록, 참조, 복사한 숫자. 하나라도 걸리면 rc=1이다. + +규칙의 정본은 design-docs `conventions/docs-system.md`이고, 이 repo의 적용은 `docs/README.md` +「문서 수명과 언어」다. 이 스크립트는 그 규칙 중 기계로 볼 수 있는 것만 본다. + + language 살아 있는 문서(기록이 아닌 .md)는 한국어다. 판정은 보고 언어 훅 H11과 같다: + 코드·명령·인용·링크·URL·경로·파일 이름을 빼고, 영어 낱말이 3개 이상이고 + 한글 덩어리 비율이 0.3 미만이면 영어다. + head 기록(docs/design, docs/history, docs/adr, docs/notification/adr)의 .md는 맨 위에 + 머리 블록이 있다. 상태는 종류별 고정 어휘, 작성일은 날짜, 요약은 한국어, 현재 + 정본과 대체됨이 가리키는 경로는 지금 있다. + reference 살아 있는 문서의 인라인 코드 안 repo 경로(src/, docs/, scripts/, infra/, .github/로 + 시작)와 Gradle 경로(:a:b)가 지금 트리와 registry에 있다. 코드 블록과 「이력」으로 + 시작하는 인용 블록은 건너뛴다. 마크다운 링크는 lychee와 check-work-docs.py --links가 본다. + number 살아 있는 문서가 정본이 정하는 숫자를 복사하지 않는다: Spring Boot 버전, leaf 개수. + +예외 목록(scripts/check-docs-exceptions.txt)은 줄기만 한다. + - 목록의 줄은 아래 FROZEN(2026-11-07 기준선의 지문)에 있어야 한다. 목록에 새 줄을 더하면 실패한다. + - 목록의 줄이 더는 걸리지 않으면(번역했거나 고쳤으면) 그 줄을 지우라고 실패한다. + - FROZEN을 늘리는 것은 규칙을 바꾸는 일이다. 소유자 결정 없이 하지 않는다. 파일을 옮겨 경로만 + 바뀐 줄은 FROZEN에서 옛 지문을 새 지문으로 바꾼다. 지문은 그 줄(탭 포함)의 sha256 앞 16자다: + python3 -c 'import hashlib,sys; print(hashlib.sha256(sys.argv[1].encode()).hexdigest()[:16])' "<줄>" + + python3 scripts/check-docs.py # 넷 모두 + python3 scripts/check-docs.py --only head # 하나만 (language, head, reference, number) + python3 -m unittest discover -s scripts/tests # 이 검사의 시험 + +Gradle 밖에 둔다. 빌드는 문서를 파싱하지 않는다(AGENTS.md 「Gradle 정책 권위」). +""" + +from __future__ import annotations + +import datetime +import hashlib +import json +import re +import subprocess +import sys +from dataclasses import dataclass +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent +EXCEPTIONS_FILE = "scripts/check-docs-exceptions.txt" +REGISTRY_FILE = "src/config/architecture/modules.json" +CHECKS = ("language", "head", "reference", "number") + +# 기록: 본문은 쓴 때의 원문이다. 머리 블록만 고친다. 종류는 폴더가 정한다. +RECORD_KINDS = [ + ("docs/design/", "설계서"), + ("docs/history/plans/evidence/", "증거"), + ("docs/history/plans/", "계획서"), + ("docs/history/packages/", "납품 패키지"), + ("docs/history/evidence/", "증거"), + ("docs/history/study/", "학습 문서"), + ("docs/adr/", "결정 기록"), + ("docs/notification/adr/", "결정 기록"), +] +# 리뷰도 기록이다. 머리 블록은 아직 요구하지 않는다(docs/README.md). +NOT_LIVING = ("docs/design/", "docs/history/", "docs/reviews/") +DECISION_PREFIXES = ("docs/adr/", "docs/notification/adr/") +# 살아 있는 문서 중 지운 것을 일부러 적는 곳: 제거 표, 파생 서비스용 변경 안내, 매뉴얼 규칙의 근거 기록. +# 참조·숫자 검사는 이 문서들을 보지 않는다(docs/README.md 「문서와 코드를 같은 변경에서 고친다」). +HISTORY_HOLDERS = ("docs/capability-status.md", "docs/upgrade/", "docs/work/evidence.md") + +STATUS = { + "설계서": ("제안", "채택", "구현됨", "보류", "폐기", "대체됨", "확인 안 함"), + "결정 기록": ("제안", "채택", "채택(보완)", "폐기", "대체됨"), + "계획서": ("실행 중", "끝남", "중단", "대체됨", "확인 안 함"), + "납품 패키지": ("보관",), + "증거": ("보관",), + "학습 문서": ("보관",), +} +HEAD_START = "" +HEAD_END = "" +RECORD_LABEL = "> **기록 · {kind}** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다." +DECISION_LABEL = "> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다." +HEAD_FIELDS = ("상태", "작성일", "요약", "현재 정본") +HEAD_OPTIONAL = ("대체", "대체됨") +HEAD_SEARCH_LINES = 20 + +# 2026-11-07 기준선. 예외 목록의 줄마다 sha256 앞 16자. 늘리지 않는다(맨 위 설명). +FROZEN: frozenset[str] = frozenset({ + "0176963415821bbe", "01984fd96d72b997", "02810bf817c5098f", "02f77e3cc483fa7b", "05fff3c3ff8a5c9a", + "06ea362843468b89", "0767d62996355ba0", "077f1849fe8bebcc", "07f88b24645a4899", "09f6eb7c3c494379", + "0a929e243076b4cb", "0d60ec2d41d698e3", "0d9db88d1d98c32b", "0f84458cb40e7c5e", "10894a287a405274", + "110ff8adc628d4e9", "115eed80f3bb629c", "14121ef25eb4aa46", "150219e901d062f4", "199044717780f929", + "1adc480d397a24fc", "1aedb5c86be16e62", "1ef3eec4c410622e", "1f3199d6bef7b3ab", "20a46563da0c570d", + "234a0dffc4f308bf", "23aa784e28c7f730", "24e61cd8377137f1", "26cdb5786cd3cef8", "26f59b7362b9e68d", + "29fa254236927dae", "2a0c27bb25080cdb", "2aa755121374e148", "2bcc75d4e1ebaa5d", "2e77660bd44c1d2c", + "2e7d24cb488ae4f9", "30c75a928243de75", "354c37493e90b01b", "3e867d0b440f18f5", "3fe449c9eca66d87", + "3ff905af6cc2df16", "4053b182a2b89223", "41f268d8aa836143", "4347c5b0dd84ec9b", "449fc1cac0f9380f", + "457310fef9d100a6", "4611a0bfd81bf42c", "462a63de89507bc6", "468248c165ce65f0", "47c9a2b490ceae84", + "4866a2abc9be3133", "48ca99496ac8265e", "494b23454cfaf902", "49d560912ccd3bd6", "49ee572590d74921", + "4c3afe5f9f4265d3", "4cef6042d25d7ce2", "4f4516913c6de5d6", "4f9b0fa57d925ddc", "50cecf0fd2f1ed1f", + "511ed51b27f98b9c", "52879b9f3cbdd66f", "52d9b8b42edf92c5", "52dd5ae3e9bfef22", "53f304d4f21e321e", + "5503b8002ae2673f", "55397a6480705e90", "561988b22b65f79f", "5640b6d1a24b9ad6", "56d9c8bc2e2d7a01", + "570b7b7be5396079", "57603aa52f880d03", "57c4df2758097604", "59e238f79e31e3db", "5acb4cacd9aa7a71", + "5b1f0d60cdd91b33", "5b783704ccce90b9", "5b833f85df94c6fd", "5caaf9a02506595e", "5cd2de3ab18314a9", + "5cda11b0371e8b48", "5e17fde0e8281e0b", "61241c19f875d528", "614d8160fecebe42", "62ac6e83f597894a", + "62ae3935928ec875", "62ae5138ca3f54bf", "62e6864d5d950d57", "63887df3233e4e7f", "63bbbd89d07abcc5", + "63d3556d23363430", "6407c8198a2ce80f", "6669b8199b2f15be", "6710e607f9ae6ba2", "6c60928d93ca7831", + "6e57bc847800e849", "6f2fef4ed95b870d", "70f8b4b8cb326639", "7227a51a80d75567", "728afb0024d5da55", + "745fabbdac49b041", "74622ec18c9f9985", "74eab10487ee91a4", "7548695a3a57c058", "76030078f4c446ec", + "7698729bcfd126f7", "77ed807b2db1bdb4", "782bc48fcd75361c", "7846dce0563bde1f", "78b5bea3cfb3f84f", + "7a41c841fa3c71c3", "7b3944471a209cdc", "7ba95fb426152c3b", "814a101266f1e722", "8232460887910a0e", + "82b97043efd185d0", "83b56cb713adb544", "84ebb93c8c137862", "8559d433706ac279", "85e199be8e5a5df5", + "86c327f4147ec696", "8c3417a9291e07cf", "9031db861c91b202", "90697a358931eba2", "9084568d44e608c3", + "945be2a3aaccbb2c", "94c5248d3fe6f83f", "95feaea41a059d9a", "966dd5354d327ba4", "97c036827ae94466", + "97fed7ecb0c23137", "982773d6151ae295", "993631c9efdbaa48", "999cc41aeaa485d9", "9b976d47e8cca045", + "9db89af226707449", "9e9437780d412b86", "9ee05526226dd121", "9f6cb144b5b0013d", "a14aae022e52cabd", + "a2db3c73eea72747", "a6e2e42521f27aa8", "a7b7a83d8e7b5914", "a84c5847e6bc413a", "a9cdf0e474dfa4ca", + "ab9a1c81f4d00b17", "ac208a7edf8e6b9e", "ac524f5b860f4b73", "af6bfc4105841865", "b25dfdea45b42ece", + "b2ee46983b09686b", "b6c96aabf4daba15", "b99ef0dca48e547c", "bc89c106ed0333da", "bd2e62413d04468c", + "bd2edda7ff995e5a", "c0f36dd22b6d1df4", "c1cbe5ed9ccaf41a", "c2e62316bf302721", "c30f7e945ca5204b", + "c446b7882073d116", "c555077d0a4ca6dc", "c5556985dac877fb", "c66938fdb57ac8bd", "c7d3f2a6e0e819c7", + "c86415926ea888fb", "c9147167591ac87f", "c9682c8986bdfa3f", "c9f15a774cbbb296", "c9f895250a7f6b1f", + "ca9ac59c7e4dd0dd", "ccfd7af308666817", "cde221c994e186e9", "d1c59fa1e5fd22ca", "d2c0d56090ffb617", + "d3a72db1fb71eaf6", "d58784f8ae176897", "d88381653e2c64f9", "d934528c9e7966f7", "da73ed73f0ec1dd9", + "da8381da9de5df66", "dd4f9524437dcc45", "dd6384bc82ce9677", "df5a6c2edc20af59", "e076b4232fc136e9", + "e1ada69597a5d6cd", "e1d8a4d6d6bbfb2e", "e2af4a0f5b0957d5", "e313fbfdd61fba0c", "e347453420828b08", + "e368dfa3ca97d4c7", "e3cc20cbd63d0adb", "e4435ba963a1fbef", "e5182c24f72e2747", "e660a27969605244", + "e7dad258cbc844a0", "e97d1ef509983caa", "e997a8c038464efb", "eb66b6c389ec09e4", "ed7764b9ec0265a0", + "ee8e568418c22e81", "ef22d97e0a67bed8", "f0baa883ab5f959d", "f12cb9b454600534", "f135bd1f9697ad4c", + "f166b8797656c86e", "f191a6842f342b74", "f3ea04dd3a66f76a", "f4c93c2e841f1c68", "f4d7edfeee65b0c3", + "f6528fa83345165e", "fa4172e085723211", "fc0c07879a70ce33", "fd706bf633a51444", "fd793c8cfa94f318", + "fe800048b661a783", "ff9a9a9da9aced39", +}) + +# --- 언어 판정: ~/.claude/hooks/guard_report.py의 H11과 같은 규칙(design-docs conventions/delegation-loop.md 11절) +MIN_ENGLISH = 3 +MIN_KOREAN_SHARE = 0.3 +HANGUL = re.compile(r"[가-힣]+") +FENCE = re.compile(r"^[ \t]*(`{3,}|~{3,})") +INLINE = re.compile(r"(`+)(?:(?!\1).)+?\1", re.S) +MDLINK = re.compile(r"\[[^\]\n]*\]\([^)\s]*\)") +URL = re.compile(r"(?:\b[a-z][a-z0-9+.-]*://|\bwww\.)\S+", re.I) +PATHLIKE = re.compile(r"[^\s가-힣]*[/\\][^\s가-힣]*") +FILELIKE = re.compile(r"[^\s가-힣]+\.[A-Za-z]{1,10}(?::\d+)*(?![A-Za-z])") +QUOTED = re.compile(r"\"[^\"\n]*\"|“[^”\n]*”") +TOKEN = re.compile(r"[^\s가-힣]+") +WORD = re.compile(r"^[(\[\"'“‘*_]*[A-Za-z][a-z]*(?:['’][a-z]+)?(?:-[a-z]+)*[)\]\"'”’*_.,;:!?…]*$") + +# --- 참조 +PATH_ROOTS = ("src/", "docs/", "scripts/", "infra/", ".github/") +PLACEHOLDER = re.compile(r"[*?<>{}\[\]$…]|\.\.\.|YYYY|NNN|[가-힣]") +LINE_SUFFIX = re.compile(r"(?::\d+(?:[-,]\d+)*)+$") +# 모든 leaf에 있는 소스 세트 이름(src/test, src/main/java)은 어느 leaf의 것인지 문장이 정한다. +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*(?:\*\*)?이력") + +# --- 복사한 숫자 +COPIED_NUMBERS = [ + ("Spring Boot 버전", re.compile(r"Spring Boot \d+\.\d+\.\d+")), + ("leaf 개수", re.compile(r"\b\d+\s*개의?\s*leaf|\bleaf\s*\d+\s*개|\b\d+\s+(?:registered\s+)?lea(?:f|ves)\b", + re.I)), +] + + +@dataclass(frozen=True) +class Problem: + check: str + path: str + key: str + message: str + line: int = 0 + + def exception_line(self) -> str: + return "\t".join(part for part in (self.check, self.path, self.key) if part) + + def render(self) -> str: + where = f"{self.path}:{self.line}" if self.line else self.path + return f"[{self.check}] {where}: {self.message}" + + +def fingerprint(line: str) -> str: + return hashlib.sha256(line.encode("utf-8")).hexdigest()[:16] + + +def tracked_markdown(root: Path) -> list[str]: + """Markdown files git knows or would add: tracked plus untracked files that are not ignored.""" + result = subprocess.run( + ["git", "-C", str(root), "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "*.md"], + capture_output=True, check=True) + names = {name for name in result.stdout.decode("utf-8").split("\0") if name} + return sorted(name for name in names if (root / name).is_file()) + + +def record_kind(path: str) -> str | None: + for prefix, kind in RECORD_KINDS: + if path.startswith(prefix): + return kind + return None + + +def is_living(path: str) -> bool: + return not path.startswith(NOT_LIVING) + + +def strip_head_block(lines: list[str]) -> list[str]: + if lines and lines[0] == HEAD_START and HEAD_END in lines[:HEAD_SEARCH_LINES]: + return lines[lines.index(HEAD_END) + 1:] + return lines + + +def strip_front_matter(lines: list[str]) -> list[str]: + if lines and lines[0].strip() == "---": + for index in range(1, len(lines)): + if lines[index].strip() == "---": + return lines[index + 1:] + return lines + + +def body_lines(text: str) -> list[str]: + return strip_front_matter(strip_head_block(text.split("\n"))) + + +def prose(text: str) -> str: + """판정에서 뺄 것(코드·명령·인용·링크·URL·경로·파일 이름)을 지운 글. H11의 prose()와 같다.""" + lines, fence = [], None + for line in text.split("\n"): + match = FENCE.match(line) + if fence: + if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence): + fence = None + continue + if match: + fence = match.group(1) + continue + if not line.lstrip().startswith(("$ ", ">")): + lines.append(line) + text = "\n".join(lines) + for pattern in (INLINE, MDLINK, URL, QUOTED, PATHLIKE, FILELIKE): + text = pattern.sub(" ", text) + return text + + +def language_counts(text: str) -> tuple[int, int]: + cleaned = prose(text) + korean = len(HANGUL.findall(cleaned)) + english = sum(1 for token in TOKEN.findall(cleaned) if WORD.match(token)) + return korean, english + + +def is_english(text: str) -> bool: + korean, english = language_counts(text) + return english >= MIN_ENGLISH and korean / (korean + english) < MIN_KOREAN_SHARE + + +def check_language(root: Path, files: list[str]) -> list[Problem]: + problems = [] + for path in files: + if not is_living(path): + continue + body = "\n".join(body_lines((root / path).read_text(encoding="utf-8"))) + if is_english(body): + korean, english = language_counts(body) + problems.append(Problem("language", path, "", + f"영어 문서다(한글 {korean}, 영어 낱말 {english}). 한국어로 쓴다")) + return problems + + +def head_block(lines: list[str]) -> tuple[list[str], int] | None: + if not lines or lines[0] != HEAD_START: + return None + window = lines[:HEAD_SEARCH_LINES] + if HEAD_END not in window: + return None + end = window.index(HEAD_END) + return lines[1:end], end + + +def backticked_paths(value: str) -> list[str]: + return re.findall(r"`([^`]+)`", value) + + +def check_head(root: Path, files: list[str]) -> list[Problem]: + problems = [] + for path in files: + kind = record_kind(path) + if kind is None: + continue + + def fail(message: str, line: int = 1) -> None: + problems.append(Problem("head", path, "", message, line)) + + lines = (root / path).read_text(encoding="utf-8").split("\n") + found = head_block(lines) + if found is None: + fail(f"맨 위에 머리 블록이 없다. 첫 줄은 `{HEAD_START}`, 블록은 `{HEAD_END}`로 닫는다") + continue + block, _ = found + label = DECISION_LABEL if kind == "결정 기록" else RECORD_LABEL.format(kind=kind) + if not block or block[0] != label: + fail(f"머리 블록 둘째 줄은 「{label}」이다", 2) + fields: dict[str, tuple[str, int]] = {} + for offset, line in enumerate(block[1:], start=3): + if not line.strip(): + continue + match = re.match(r"^- ([^:]+): (.+)$", line) + if not match: + fail(f"머리 블록의 줄은 `- 칸: 값`이다: {line!r}", offset) + continue + name, value = match.group(1).strip(), match.group(2).strip() + if name not in HEAD_FIELDS + HEAD_OPTIONAL: + fail(f"머리 블록에 없는 칸이다: {name}", offset) + elif name in fields: + fail(f"칸이 두 번 나온다: {name}", offset) + else: + fields[name] = (value, offset) + for name in HEAD_FIELDS: + if name not in fields: + fail(f"「{name}」 칸이 없다") + status, at = fields.get("상태", ("", 1)) + if "상태" in fields and status not in STATUS[kind]: + fail(f"{kind}의 상태는 {' · '.join(STATUS[kind])} 중 하나다: {status!r}", at) + written, at = fields.get("작성일", ("", 1)) + if "작성일" in fields: + try: + datetime.date.fromisoformat(written) + except ValueError: + fail(f"작성일은 YYYY-MM-DD다: {written!r}", at) + summary, at = fields.get("요약", ("", 1)) + if "요약" in fields and (not HANGUL.search(summary) or is_english(summary)): + fail("요약은 한국어 한 문장이다", at) + canonical, at = fields.get("현재 정본", ("", 1)) + if "현재 정본" in fields: + targets = backticked_paths(canonical) + if not canonical.startswith("없음") and not targets: + fail("현재 정본은 `경로`(여럿이면 쉼표) 또는 「없음 — 이유」다", at) + for target in targets: + if not (root / target).exists(): + fail(f"현재 정본 경로가 없다: {target}", at) + if status == "대체됨" and "대체됨" not in fields: + fail("상태가 대체됨이면 「대체됨」 칸에 대체한 문서를 적는다") + for name in HEAD_OPTIONAL: + if name in fields: + value, at = fields[name] + targets = backticked_paths(value) + if not targets: + fail(f"「{name}」 칸은 `경로`를 적는다", at) + for target in targets: + if not (root / target).exists(): + fail(f"「{name}」 경로가 없다: {target}", at) + return problems + + +def inline_spans(lines: list[str]) -> list[tuple[int, str]]: + """(줄 번호, 인라인 코드) — 코드 블록과 「이력」 인용 블록 밖에서만.""" + spans, fence, history = [], None, False + for number, line in enumerate(lines, start=1): + match = FENCE.match(line) + if fence: + if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence): + fence = None + continue + if match: + fence = match.group(1) + continue + quoted = line.lstrip().startswith(">") + if quoted and HISTORY_QUOTE.match(line): + history = True + elif not quoted: + history = False + if history: + continue + for found in INLINE.finditer(line): + spans.append((number, found.group(0).strip("`").strip())) + return spans + + +def registry_projects(root: Path) -> set[str]: + registry = root / REGISTRY_FILE + if not registry.is_file(): + return set() + modules = json.loads(registry.read_text(encoding="utf-8")).get("modules", []) + projects: set[str] = set() + for module in modules: + parts = module["gradle_path"].split(":")[1:] + for end in range(1, len(parts) + 1): + projects.add(":" + ":".join(parts[:end])) + return projects + + +def path_candidate(token: str) -> str | None: + token = token.strip().strip("'\"()[],;") + if token.startswith("./"): + token = token[2:] + if not token.startswith(PATH_ROOTS) or PLACEHOLDER.search(token) or "://" in token: + return None + token = LINE_SUFFIX.sub("", token.split("#", 1)[0]).rstrip(".:") + return token or None + + +def resolves(root: Path, document: str, target: str) -> bool: + if (root / target).exists(): + return True + # src/main/... in a leaf document is written relative to that leaf. + folder = (root / document).parent + while folder != root and root in folder.parents: + if (folder / target).exists(): + return True + folder = folder.parent + return False + + +def ignored(root: Path, paths: set[str]) -> set[str]: + if not paths: + return set() + result = subprocess.run(["git", "-C", str(root), "check-ignore", "--no-index", "--stdin"], + input="\n".join(sorted(paths)).encode("utf-8"), capture_output=True) + return set(result.stdout.decode("utf-8").split("\n")) - {""} + + +def checked_for_drift(path: str) -> bool: + return is_living(path) and not path.startswith(DECISION_PREFIXES) and not path.startswith(HISTORY_HOLDERS) + + +def path_suffixes(root: Path) -> set[str]: + """Every trailing part of every file and folder git knows: `src/test/resources/x.sha256` written in a + manual about any leaf resolves when some leaf has it.""" + result = subprocess.run( + ["git", "-C", str(root), "ls-files", "-z", "--cached", "--others", "--exclude-standard"], + capture_output=True, check=True) + suffixes: set[str] = set() + for name in result.stdout.decode("utf-8").split("\0"): + parts = name.split("/") + for end in range(1, len(parts) + 1): + for start in range(end): + suffixes.add("/".join(parts[start:end])) + return suffixes + + +def check_reference(root: Path, files: list[str]) -> list[Problem]: + projects = registry_projects(root) + missing: list[tuple[str, int, str]] = [] + problems = [] + for path in files: + if not checked_for_drift(path): + continue + lines = body_lines((root / path).read_text(encoding="utf-8")) + offset = len((root / path).read_text(encoding="utf-8").split("\n")) - len(lines) + seen: set[str] = set() + for number, span in inline_spans(lines): + for token in span.split(): + gradle = token.strip(".,;'\"()") + if GRADLE_PATH.match(gradle): + parent = gradle.rsplit(":", 1)[0] + if projects and gradle not in projects and parent not in projects and gradle not in seen: + seen.add(gradle) + problems.append(Problem("reference", path, gradle, + f"registry에 없는 Gradle 경로다: {gradle}", number + offset)) + continue + target = path_candidate(token) + if target and SOURCE_SET.match(target): + continue + if target and target not in seen and not resolves(root, path, target): + seen.add(target) + missing.append((path, number + offset, target)) + skip = ignored(root, {target for _, _, target in missing}) + if missing: + skip |= path_suffixes(root) + for path, number, target in missing: + if target.rstrip("/") not in skip and target not in skip: + problems.append(Problem("reference", path, target, f"없는 경로다: {target}", number)) + return problems + + +def check_number(root: Path, files: list[str]) -> list[Problem]: + problems = [] + for path in files: + if not checked_for_drift(path): + continue + seen: set[str] = set() + for number, line in enumerate((root / path).read_text(encoding="utf-8").split("\n"), start=1): + for label, pattern in COPIED_NUMBERS: + for match in pattern.finditer(line): + text = match.group(0) + if text not in seen: + seen.add(text) + problems.append(Problem("number", path, text, + f"{label}를 복사했다: {text!r}. 정본을 가리킨다", number)) + return problems + + +RUNNERS = {"language": check_language, "head": check_head, "reference": check_reference, "number": check_number} + + +def read_exceptions(text: str) -> list[str]: + return [line for line in text.split("\n") if line.strip() and not line.startswith("#")] + + +def run(root: Path, only: tuple[str, ...] = CHECKS, exceptions: str | None = None, + frozen: frozenset[str] = FROZEN) -> tuple[list[str], list[str]]: + """(실패 줄, 보고 줄). 예외 목록을 적용한 뒤의 결과다.""" + if exceptions is None: + exceptions_path = root / EXCEPTIONS_FILE + exceptions = exceptions_path.read_text(encoding="utf-8") if exceptions_path.is_file() else "" + allowed = read_exceptions(exceptions) + files = tracked_markdown(root) + errors: list[str] = [] + report: list[str] = [] + for entry in allowed: + if fingerprint(entry) not in frozen: + errors.append(f"[exceptions] {EXCEPTIONS_FILE}: 기준선에 없는 예외다. 예외 목록은 늘지 않는다: {entry!r}") + allowed_set = set(allowed) + for check in only: + problems = RUNNERS[check](root, files) + hit = {problem.exception_line() for problem in problems} + unexcused = [problem for problem in problems if problem.exception_line() not in allowed_set] + stale = [entry for entry in allowed if entry.split("\t", 1)[0] == check and entry not in hit] + errors += [problem.render() for problem in unexcused] + errors += [f"[exceptions] {EXCEPTIONS_FILE}: 더는 걸리지 않는다. 이 줄을 지운다: {entry!r}" for entry in stale] + excused = len(problems) - len(unexcused) + report.append(f"{check}: 걸림 {len(problems)}, 예외 {excused}, 실패 {len(unexcused)}") + return errors, report + + +def main(argv: list[str]) -> int: + only = CHECKS + if argv[:1] == ["--only"]: + if len(argv) != 2 or argv[1] not in CHECKS: + print(f"usage: check-docs.py [--only {'|'.join(CHECKS)}]", file=sys.stderr) + return 2 + only = (argv[1],) + elif argv: + print(f"usage: check-docs.py [--only {'|'.join(CHECKS)}]", file=sys.stderr) + return 2 + errors, report = run(REPO_ROOT, only) + for line in report: + print(line) + if errors: + print(f"\nFAILED: {len(errors)}", file=sys.stderr) + for error in errors: + print(f" {error}", file=sys.stderr) + return 1 + print("\nOK") + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/scripts/tests/test_check_docs.py b/scripts/tests/test_check_docs.py new file mode 100644 index 00000000..1f9702f4 --- /dev/null +++ b/scripts/tests/test_check_docs.py @@ -0,0 +1,252 @@ +"""scripts/check-docs.py의 시험. 고장 낸 입력에서 실패하고, 맞는 입력에서 통과하는지 본다. + + python3 -m unittest discover -s scripts/tests +""" + +from __future__ import annotations + +import importlib.util +import json +import subprocess +import sys +import tempfile +import unittest +from pathlib import Path + +SCRIPTS = Path(__file__).resolve().parent.parent +_spec = importlib.util.spec_from_file_location("check_docs", SCRIPTS / "check-docs.py") +check_docs = importlib.util.module_from_spec(_spec) +sys.modules["check_docs"] = check_docs +_spec.loader.exec_module(check_docs) + +KOREAN = "이 문서는 한국어로 쓴 살아 있는 문서다. 코드와 같은 변경에서 고친다.\n" +ENGLISH = "This document is written in English and explains how the module works in detail.\n" + + +def head(kind: str = "설계서", status: str = "구현됨", written: str = "2026-08-11", + summary: str = "한국어로 쓴 요약 한 문장이다.", canonical: str = "`docs/live.md`", + extra: str = "", label: str | None = None) -> str: + if label is None: + label = check_docs.DECISION_LABEL if kind == "결정 기록" else check_docs.RECORD_LABEL.format(kind=kind) + lines = [check_docs.HEAD_START, label, "", f"- 상태: {status}", f"- 작성일: {written}", + f"- 요약: {summary}", f"- 현재 정본: {canonical}"] + if extra: + lines.append(extra) + lines += [check_docs.HEAD_END, ""] + return "\n".join(lines) + "\n" + + +class Repository: + """A throwaway git working tree with a registry, so the checker sees what git sees.""" + + def __init__(self) -> None: + self._directory = tempfile.TemporaryDirectory() + self.root = Path(self._directory.name) + subprocess.run(["git", "init", "-q", str(self.root)], check=True) + self.write("docs/live.md", KOREAN) + self.write(check_docs.REGISTRY_FILE, json.dumps({"modules": [ + {"id": "app", "gradle_path": ":app", "source_path": "src/app"}, + {"id": "adapter-web", "gradle_path": ":adapter:inbound:web", "source_path": "src/adapter/inbound/web"}, + ]})) + + def write(self, path: str, text: str) -> None: + target = self.root / path + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(text, encoding="utf-8") + + def run(self, only: tuple[str, ...] = check_docs.CHECKS, exceptions: str = "", + frozen: frozenset[str] | None = None) -> list[str]: + if frozen is None: + frozen = frozenset(check_docs.fingerprint(line) for line in check_docs.read_exceptions(exceptions)) + errors, _ = check_docs.run(self.root, only, exceptions=exceptions, frozen=frozen) + return errors + + def close(self) -> None: + self._directory.cleanup() + + +class RepositoryTestCase(unittest.TestCase): + def setUp(self) -> None: + self.repo = Repository() + self.addCleanup(self.repo.close) + + def assertFailsWith(self, errors: list[str], fragment: str) -> None: + self.assertTrue(any(fragment in error for error in errors), f"no error with {fragment!r}: {errors}") + + +class LanguageTest(RepositoryTestCase): + def test_an_english_living_document_fails(self) -> None: + self.repo.write("docs/guide.md", "# Guide\n\n" + ENGLISH * 3) + self.assertFailsWith(self.repo.run(("language",)), "docs/guide.md: 영어 문서다") + + def test_a_korean_living_document_passes(self) -> None: + self.repo.write("src/app/README.md", "# 앱\n\n" + KOREAN * 3) + self.assertEqual(self.repo.run(("language",)), []) + + def test_code_commands_and_paths_do_not_make_a_korean_document_english(self) -> None: + code = "```bash\n" + "./gradlew :app:test --console=plain and many more english words here\n" * 20 + "```\n" + self.repo.write("docs/guide.md", "# 안내\n\n" + KOREAN + code + "`src/app/Foo.java`를 본다.\n") + self.assertEqual(self.repo.run(("language",)), []) + + def test_a_record_body_keeps_its_original_language(self) -> None: + self.repo.write("docs/design/2026-08-11-x-design.md", head() + "# Design\n\n" + ENGLISH * 3) + self.assertEqual(self.repo.run(("language",)), []) + + def test_an_english_decision_record_body_fails(self) -> None: + self.repo.write("docs/adr/ADR-X-001.md", head(kind="결정 기록", status="채택") + "# ADR\n\n" + ENGLISH * 3) + self.assertFailsWith(self.repo.run(("language",)), "docs/adr/ADR-X-001.md: 영어 문서다") + + +class ExceptionListTest(RepositoryTestCase): + LINE = "language\tdocs/guide.md" + + def test_a_frozen_exception_excuses_its_document(self) -> None: + self.repo.write("docs/guide.md", ENGLISH * 3) + self.assertEqual(self.repo.run(("language",), exceptions=self.LINE + "\n"), []) + + def test_adding_a_line_to_the_exception_list_fails(self) -> None: + self.repo.write("docs/guide.md", ENGLISH * 3) + errors = self.repo.run(("language",), exceptions=self.LINE + "\n", frozen=frozenset()) + self.assertFailsWith(errors, "기준선에 없는 예외다") + + def test_an_exception_that_no_longer_fails_must_be_removed(self) -> None: + self.repo.write("docs/guide.md", KOREAN * 3) + self.assertFailsWith(self.repo.run(("language",), exceptions=self.LINE + "\n"), "더는 걸리지 않는다") + + def test_an_exception_for_one_check_does_not_excuse_another(self) -> None: + self.repo.write("docs/guide.md", "`docs/gone.md`를 본다. " + KOREAN) + errors = self.repo.run(("reference",), exceptions="number\tdocs/guide.md\tdocs/gone.md\n") + self.assertFailsWith(errors, "없는 경로다: docs/gone.md") + + def test_every_line_of_the_real_exception_list_is_in_the_frozen_baseline(self) -> None: + text = (SCRIPTS.parent / check_docs.EXCEPTIONS_FILE).read_text(encoding="utf-8") + outside = [line for line in check_docs.read_exceptions(text) + if check_docs.fingerprint(line) not in check_docs.FROZEN] + self.assertEqual(outside, []) + + def test_a_new_line_in_the_real_exception_list_is_not_in_the_frozen_baseline(self) -> None: + self.assertNotIn(check_docs.fingerprint("language\tdocs/brand-new-english.md"), check_docs.FROZEN) + + +class HeadBlockTest(RepositoryTestCase): + PATH = "docs/design/2026-08-11-x-design.md" + + def errors_for(self, text: str) -> list[str]: + self.repo.write(self.PATH, text + "# Original\n\nbody\n") + return self.repo.run(("head",)) + + def test_a_complete_head_block_passes(self) -> None: + self.assertEqual(self.errors_for(head()), []) + + def test_canonical_none_with_a_reason_passes(self) -> None: + self.assertEqual(self.errors_for(head(canonical="없음 — 지운 기능이다")), []) + + def test_a_record_without_a_head_block_fails(self) -> None: + self.assertFailsWith(self.errors_for(""), "맨 위에 머리 블록이 없다") + + def test_a_status_outside_the_vocabulary_fails(self) -> None: + self.assertFailsWith(self.errors_for(head(status="Accepted")), "설계서의 상태는") + + def test_a_plan_status_on_a_decision_record_fails(self) -> None: + self.repo.write("docs/adr/ADR-X-001.md", head(kind="결정 기록", status="끝남") + "# ADR\n") + self.assertFailsWith(self.repo.run(("head",)), "결정 기록의 상태는") + + def test_a_malformed_date_fails(self) -> None: + self.assertFailsWith(self.errors_for(head(written="2026-13-01")), "작성일은 YYYY-MM-DD다") + + def test_an_english_summary_fails(self) -> None: + self.assertFailsWith(self.errors_for(head(summary="A design for the module boundary.")), "요약은 한국어") + + def test_a_canonical_path_that_does_not_exist_fails(self) -> None: + self.assertFailsWith(self.errors_for(head(canonical="`docs/missing.md`")), "현재 정본 경로가 없다") + + def test_a_canonical_value_without_a_path_fails(self) -> None: + self.assertFailsWith(self.errors_for(head(canonical="jpa 문서")), "현재 정본은") + + def test_superseded_without_its_replacement_fails(self) -> None: + self.assertFailsWith(self.errors_for(head(status="대체됨")), "「대체됨」 칸에 대체한 문서") + + def test_superseded_with_its_replacement_passes(self) -> None: + self.assertEqual(self.errors_for(head(status="대체됨", extra="- 대체됨: `docs/live.md`")), []) + + def test_a_wrong_kind_label_fails(self) -> None: + self.assertFailsWith(self.errors_for(head(label="> **기록 · 계획서** 다른 종류다.")), "머리 블록 둘째 줄은") + + def test_an_unknown_field_fails(self) -> None: + self.assertFailsWith(self.errors_for(head(extra="- 담당: 누군가")), "머리 블록에 없는 칸이다") + + def test_the_kind_follows_the_folder(self) -> None: + self.repo.write("docs/history/plans/evidence/x.md", head(kind="증거", status="보관") + "# Evidence\n") + self.assertEqual(self.repo.run(("head",)), []) + + +class ReferenceTest(RepositoryTestCase): + def errors_for(self, text: str, path: str = "docs/guide.md") -> list[str]: + self.repo.write(path, KOREAN + text) + return self.repo.run(("reference",)) + + def test_a_missing_repository_path_fails(self) -> None: + self.assertFailsWith(self.errors_for("`docs/gone.md`를 읽는다.\n"), "없는 경로다: docs/gone.md") + + def test_an_existing_path_with_a_line_number_passes(self) -> None: + self.assertEqual(self.errors_for("`docs/live.md:12`를 읽는다.\n"), []) + + def test_a_path_inside_a_command_is_checked(self) -> None: + self.assertFailsWith(self.errors_for("`python3 scripts/gone.py --all`을 돌린다.\n"), "scripts/gone.py") + + def test_fenced_code_is_skipped(self) -> None: + self.assertEqual(self.errors_for("```text\n`docs/gone.md`\n```\n"), []) + + def test_a_history_quote_is_skipped(self) -> None: + self.assertEqual(self.errors_for("> 이력: `docs/gone.md`는 2026-09-25에 지웠다.\n> `src/gone/` 도.\n"), []) + + def test_a_placeholder_path_is_skipped(self) -> None: + self.assertEqual(self.errors_for("`docs/reviews/<폴더>`와 `src/**/CLAUDE.md`를 본다.\n"), []) + + def test_a_leaf_relative_source_path_resolves_through_some_leaf(self) -> None: + self.repo.write("src/app/src/test/resources/contracts/x.sha256", "x") + self.assertEqual(self.errors_for("각 leaf의 `src/test/resources/contracts/x.sha256`을 본다.\n"), []) + + def test_a_source_set_name_every_leaf_has_is_skipped(self) -> None: + self.assertEqual(self.errors_for("테스트는 각 leaf의 `src/test`와 `src/main/java/` 옆에 둔다.\n"), []) + + def test_a_gradle_path_outside_the_registry_fails(self) -> None: + self.assertFailsWith(self.errors_for("`./gradlew :sample:check`를 돌린다.\n"), "registry에 없는 Gradle 경로다: :sample:check") + + def test_a_task_of_a_registered_project_passes(self) -> None: + self.assertEqual(self.errors_for("`./gradlew :adapter:inbound:web:test`와 `:app:check`를 돌린다.\n"), []) + + def test_the_removal_table_is_not_checked(self) -> None: + self.assertEqual(self.errors_for("`src/gone/Old.java`를 지웠다.\n", path="docs/capability-status.md"), []) + + def test_a_record_is_not_checked(self) -> None: + self.repo.write("docs/design/2026-08-11-x-design.md", head() + "`docs/gone.md`\n") + self.assertEqual(self.repo.run(("reference",)), []) + + +class NumberTest(RepositoryTestCase): + def errors_for(self, text: str) -> list[str]: + self.repo.write("src/app/CLAUDE.md", KOREAN + text) + return self.repo.run(("number",)) + + def test_a_copied_spring_boot_version_fails(self) -> None: + self.assertFailsWith(self.errors_for("Runtime baseline: Spring Boot 4.0.8.\n"), "'Spring Boot 4.0.8'") + + def test_a_major_version_passes(self) -> None: + self.assertEqual(self.errors_for("Spring Boot 4 위에서 돈다.\n"), []) + + def test_a_copied_leaf_count_fails(self) -> None: + self.assertFailsWith(self.errors_for("registry는 leaf 65개를 가진다.\n"), "leaf 개수") + self.assertFailsWith(self.errors_for("declares exactly 19 leaf identities.\n"), "leaf 개수") + + def test_a_word_count_of_leaves_passes(self) -> None: + self.assertEqual(self.errors_for("leaf 하나를 고른다.\n"), []) + + +class CommandLineTest(unittest.TestCase): + def test_an_unknown_check_is_a_usage_error(self) -> None: + self.assertEqual(check_docs.main(["--only", "spelling"]), 2) + + +if __name__ == "__main__": + unittest.main()