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()