fix(scripts)!: 문서 검사의 Gradle·경로·링크 대조 빈틈을 닫는다 #86

Merged
donghyeon.kang merged 5 commits from fix/check-docs-reference-rules into main 2026-11-21 18:16:21 +00:00
7 changed files with 303 additions and 64 deletions
+1 -1
View File
@@ -192,7 +192,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
| --- | --- |
| `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) |
| `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 |
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. `docs/registries/*.yaml`은 값과 주석에 적은 repo 경로를 본다(행의 `source`·`registered_by`가 옮긴 파일을 가리키면 PR에서 걸린다). 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`scripts/check-docs.py`의 `PATH_ROOTS`로 시작하는 것: `src/`, `docs/`, `scripts/`, `.claude/` 등과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. Gradle 경로는 registry의 leaf, 루트 task(루트 `build.gradle`이 이름을 적은 것, 루트 plugin과 Gradle 도움 task), `<leaf>:<task>` 중 하나여야 한다. 한 마디 경로(`:domain-core`)는 `gradlew`·`gradle`·`verify.sh` 명령 안에서, 또는 인라인 코드 맨 앞에서 leaf·루트 task 이름 모양일 때만 본다. leaf 상대 경로(`src/test/resources/…`)는 registry의 어느 leaf 폴더 아래에 있으면 된다. `docs/registries/*.yaml`은 값과 주석에 적은 repo 경로를 본다(행의 `source`·`registered_by`가 옮긴 파일을 가리키면 PR에서 걸린다). 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 |
| `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
+1 -1
View File
@@ -96,7 +96,7 @@ Docker가 필요한 lane은 건너뛰지 않고 닫힌 채 실패한다. 이 lea
| task마다 `git add` + `git commit` | `AGENTS.md`: 커밋 정책은 `human-only`다. 에이전트는 stage, commit, amend, push를 하지 않는다 | 구현은 stage하지 않은 채로 넘겼다. 일부러 하지 않은 계획 단계는 이것 하나이고, 여기에 기록한다. |
| Querydsl을 선택 모듈 의존성으로 | Querydsl은 이 저장소의 의존성 묶음에 없다 | `querydsl`은 계획의 계약대로 구현하되 Querydsl 타입을 `compileOnly` 뒤에 둔다. 그래서 Stable 런타임 classpath에는 Querydsl이 없고, 쓰기로 한 배포가 artifact를 직접 더한다. |
| Hibernate Envers를 모듈 의존성으로 | Envers는 이 저장소의 의존성 묶음에 없다 | Querydsl과 같다. `compileOnly` + 명시적 opt-in. 계획의 "Envers is opt-in and never enabled by a global base class"와 맞는다. |
| 계획의 build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt | `build-logic`은 있지만 Kotlin source set은 없다 | 패키지 경계는 이 leaf의 `JpaModuleBoundaryTest`(§1)가, leaf 경계는 `verifyCleanArchitectureDependencies`와 `:app-bootstrap:architectureTest`가 `gradle/modules.json`을 정본으로 강제한다. |
| 계획(`docs/history/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md` 218줄)의 Kotlin 경계 시험 | `build-logic`은 있지만 Kotlin source set은 없다 | 패키지 경계는 이 leaf의 `JpaModuleBoundaryTest`(§1)가, leaf 경계는 `verifyCleanArchitectureDependencies`와 `:app-bootstrap:architectureTest`가 `gradle/modules.json`을 정본으로 강제한다. |
| `PostgreSqlRuntimeRoleVerifierIntegrationTest` (Task 45) | 보안 lane은 모듈마다의 `integrationTest`가 아니라 이 leaf의 suite 하나다 | `PostgreSqlSecurityContractTest`(tag `jpa-security`)가 실제 서버의 실제 제한 역할에 대고 `PostgreSqlRuntimeRoleVerifier.verify`와 `.requireSafe`를 돌린다. |
| `JpaSafetyProperties`, `JpaDataSourceProperties` | `NamingConventionTest`는 모든 `@ConfigurationProperties` 타입 이름이 `Settings`나 `Policy`로 끝나기를 요구한다 | `JpaSafetySettings`로 이름을 바꿨다. 묶는 속성 prefix와 모든 칸은 그대로이고 클래스 이름만 이 저장소 관례로 옮겼다. `JpaDataSourceProperties`에 해당하는 설정 클래스는 지금 없다. datasource 검사는 `JpaDataSourceProfileValidator`가 한다. |
@@ -0,0 +1,36 @@
# 업그레이드 안내 — 2026-11 문서 검사의 경로·Gradle·링크 대조
- 범위: `scripts/check-docs.py`의 `reference` 검사와 `scripts/check-work-docs.py --links`를 엄하게 한 변경. 문서에 이미
적힌 규칙(인라인 코드의 repo 경로·Gradle 경로는 지금 트리와 registry에 있다, 상대 링크는 git이 아는 곳을 가리킨다)을
검사가 빈틈 없이 지킨다. 코드·빌드·설정·workflow는 그대로다.
- 근거: `docs/README.md` 「문서 검사」, `scripts/check-docs.py` 머리 주석의 `reference`·`link`
## 1. 누가 읽나
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 자기 문서(`docs/`, `src/**/AGENTS.md`, `.claude/`
아래)를 더하거나 고친 서비스는 merge 뒤 PR 단계 `documentCheck`가 아래 꼴에서 새로 실패할 수 있다. 문서만 고치면 된다.
## 2. 새로 실패하는 꼴과 할 일
| # | 바뀐 것 | 할 일 | 안 하면 | 해당 서비스 |
| --- | --- | --- | --- | --- |
| 1 | task 없이 쓴 Gradle 경로와 `<묶음 폴더>:<task>`를 registry leaf와 대조한다. 전에는 leaf 경로의 앞부분(`:adapter`, `:adapter:inbound`)도 project로 쳐서, 이름을 바꾼 leaf를 task 없이 쓴 것(`:adapter:inbound:web-old`)과 묶음 폴더의 task(`:adapter:inbound:check`)가 통과했다 | 문서의 Gradle 경로를 `gradle/modules.json`의 `gradle_path`로 고친다. 묶음 폴더의 leaf를 모두 돌리려면 leaf마다 적거나 루트 단계 task를 쓴다 | `documentCheck`가 「registry에 없는 Gradle 경로다」로 실패한다 | 문서에 Gradle 경로를 쓴 서비스 |
| 2 | 한 마디 Gradle 경로(`:domain-core`, `:prCheck`)도 본다: `gradlew`·`gradle`·`verify.sh` 명령 안의 것과, 인라인 코드 맨 앞에서 leaf 이름(마디가 `-`로 이어짐)이나 루트 task 이름(camelCase) 모양인 것. registry leaf, 루트 `build.gradle`이 `tasks.register`·`tasks.named`로 적은 이름, 루트 plugin task(`ca.architecture`·`ca.strict-lane-stages`가 만드는 것), Gradle 도움 task(`:help`, `:tasks` 등)면 통과한다. 소문자 한 낱말(`:test`)은 명령 밖에서 보지 않는다 | 지운 leaf·task 이름을 고친다. 자기 plugin이 루트에 만든 task를 문서에 쓰면 `scripts/check-docs.py`의 `PLUGIN_ROOT_TASKS`에 이름을 더한다. SQL 이름 붙은 인자를 인라인 코드 맨 앞에 홀로 쓰면(`:workerId`) Gradle 경로로 보므로 식과 함께 쓴다(`lease_owner = :workerId`) | 같다 | 문서에 한 마디 경로를 쓴 서비스, 루트에 자기 plugin task를 둔 서비스 |
| 3 | 인라인 코드의 `.claude/` 경로(규칙·스킬·에이전트 파일)를 지금 트리와 대조한다 | 옮기거나 지운 `.claude/rules/*.md`·`.claude/skills/*` 경로를 문서에서 고친다. gitignore한 파일(`.claude/settings.local.json`)은 보지 않는다 | `documentCheck`가 「없는 경로다」로 실패한다 | `.claude/` 아래 파일을 옮기거나 지운 서비스 |
| 4 | 다른 파일의 꼬리와 같으면 통과하던 경로를 줄였다. 꼬리로 통과하는 것은 leaf 상대 경로(`src/<소스 세트>/…`, 예: 각 leaf의 `src/test/resources/…`)가 registry leaf 폴더 아래에 있을 때뿐이다. 그 밖의 경로(`src/adapter/inbound/old/`)는 저장소 루트나 문서 폴더에서 읽혀야 하고, 템플릿 폴더(`scripts/feature-scaffold/templates/`)의 `src/` 나무는 세지 않는다 | 저장소 루트에서 쓴 전체 경로로 고치거나, leaf 문서 안에서 그 leaf 상대로 쓴다 | 같다 | 지운 leaf나 템플릿에만 있는 경로를 문서에 쓴 서비스 |
| 5 | `check-work-docs.py --links`가 `check-docs.py` `link`와 같은 규칙을 쓴다: 저장소 루트를 넘는 링크(`../` 형제 repo)와 git이 모르는 곳(git mv가 남긴 빈 폴더, 무시된 파일)을 가리키는 링크는 깨짐이다. 넘긴 파일이 저장소 밖이거나 이 저장소 git이 모르는 파일(무시된 다른 checkout `.claude/worktrees/…`, 빌드 출력)이면 rc=2로 거절한다 | 형제 repo 문서는 상대 링크 대신 코드 표기로 쓴다. `--links`에는 이 저장소 git이 아는 파일·폴더만 넘긴다 | `--links`가 rc=1이나 rc=2로 끝난다. PR 단계 검사(`check-docs.py` `link`)는 전부터 이 규칙이다 | `--links`를 손이나 스크립트로 쓰는 서비스 |
## 3. 바뀌지 않은 것
- 코드, 빌드, 설정, workflow는 그대로다. 검사가 보는 문서(살아 있는 문서, `docs/registries/*.yaml`)와 건너뛰는 곳(코드 블록,
`> 이력` 인용 블록, 제거 표, `upgrade/`, 기록 문서)도 그대로다.
- `<leaf>:<task>`의 task 이름은 Gradle 없이 알 수 없어 여전히 보지 않는다.
## 4. 확인하는 법
merge한 트리에서 돌린다. rc=0이면 할 일이 없다.
```bash
python3 scripts/check-docs.py --only reference
python3 scripts/check-work-docs.py --links docs README.md
```
+106 -46
View File
@@ -12,12 +12,19 @@
head 기록(docs/design, docs/history, docs/adr)의 .md는 맨 위에
머리 블록이 있다. 상태는 종류별 고정 어휘, 작성일은 날짜, 요약은 한국어, 현재
정본과 대체됨이 가리키는 경로는 지금 있다.
reference 살아 있는 문서의 인라인 코드 안 repo 경로(src/, docs/, scripts/, compose/, .github/, .gitea/로
시작. 2026-11-07에 지운 infra/ 아래 경로도 본다)와 Gradle 경로(:a:b)가 지금 트리와
registry에 있다. 「있다」는 git이 아는 파일(추적 + 무시되지 않은 새 파일)과 그 위 폴더다. 디스크에만
있는 것(git mv가 남긴 빈 폴더 등)은 새 checkout에 없으므로 세지 않는다. 기록의 「현재 정본」·「대체됨」
경로도 같다. 코드 블록과 「이력」으로 시작하는 인용 블록은 건너뛴다. 마크다운
링크는 lychee와 check-work-docs.py --links가 본다. registry(docs/registries/*.yaml)의 값(따옴표가 있든
reference 살아 있는 문서의 인라인 코드 안 repo 경로(PATH_ROOTS: src/, docs/, scripts/, compose/, .github/,
.gitea/, build-logic/, gradle/, .claude/로 시작. 2026-11-07에 지운 infra/ 아래 경로도 본다)와
Gradle 경로가 지금 트리와 registry에 있다. Gradle 경로는 registry의 leaf(:a:b), 루트 task(:prCheck,
루트 build.gradle의 tasks.register·tasks.named 이름, 루트 plugin task PLUGIN_ROOT_TASKS, Gradle 도움 task
GRADLE_ROOT_TASKS), `<leaf>:<task>` 중 하나다. task 이름은 Gradle 없이 알 수 없어 보지 않는다. 한 마디
경로는 gradlew·gradle·verify.sh 명령 안에서, 또는 인라인 코드 맨 앞에서 leaf·루트 task 이름 모양
(`:domain-core`, `:prCheck`)일 때만 본다. SQL 인자 `:workerId`, 문장 속 `:test`와 모양이 같기 때문이다.
「있다」는 git이 아는 파일(추적 + 무시되지 않은 새 파일)과 그 위 폴더다. 문서 폴더에서 읽어도
된다(leaf 문서의 src/main/…). leaf 상대 경로(src/<소스 세트>/…)는 registry의 어느 leaf 폴더 아래에
있으면 된다(템플릿 폴더의 src/ 나무는 세지 않는다). 디스크에만 있는 것(git mv가 남긴 빈 폴더 등)은
새 checkout에 없으므로 세지 않는다.
기록의 「현재 정본」·「대체됨」 경로도 같다. 코드 블록과 「이력」으로 시작하는 인용 블록은
건너뛴다. 마크다운 링크는 link와 lychee가 본다. registry(docs/registries/*.yaml)의 값(따옴표가 있든
없든)과 주석에 적은 repo 경로도 본다: 행의 `source`·`registered_by`가 옮긴 파일을 가리키면 main
단계의 대조 시험(document-contract)보다 먼저 PR에서 걸린다.
number 살아 있는 문서가 정본이 정하는 숫자를 복사하지 않는다: Spring Boot 버전, leaf 개수.
@@ -29,6 +36,9 @@
그 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다.
readme 루트 README.md가 정해진 절을 정해진 순서로 가진다: 첫 줄의 제목, 그 아래 한 문단, 그리고
README_SECTIONS의 ## 제목. 그 사이에 다른 절이 있어도 된다.
link 살아 있는 문서의 상대 링크가 git이 아는 파일·폴더를 가리킨다. 저장소 밖(..)으로 나가면 실패다.
코드 블록·인라인 코드·「이력」 인용 블록 안은 링크로 보지 않는다. check-work-docs.py(--links
포함)도 같은 함수(broken_relative_links)를 불러 규칙이 한 곳에 있다.
소스 세트의 resources 폴더 아래 .md(src/**/src/<세트>/resources/)는 시험 입력이나 실행 자원이라 문서로
보지 않는다.
@@ -129,12 +139,32 @@ TOKEN = re.compile(r"[^\s가-힣]+")
WORD = re.compile(r"^[(\[\"'“‘*_]*[A-Za-z][a-z]*(?:['’][a-z]+)?(?:-[a-z]+)*[)\]\"'”’*_.,;:!?…]*$")
# --- 참조
PATH_ROOTS = ("src/", "docs/", "scripts/", "compose/", "infra/", ".github/", ".gitea/", "build-logic/", "gradle/")
PATH_ROOTS = ("src/", "docs/", "scripts/", "compose/", "infra/", ".github/", ".gitea/", "build-logic/", "gradle/",
".claude/")
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-]*)+$")
GRADLE_PATH = re.compile(r"^:[A-Za-z][\w-]*(?::[A-Za-z][\w-]*)*$")
# 한 마디 경로(`:prCheck`)는 SQL의 이름 붙은 인자(`lease_owner = :workerId`)나 문장 속 표기(각 leaf의 `:test`,
# `:authority`)와 모양이 같다. Gradle 경로로 보는 것은 둘이다: Gradle 경로를 받는 명령(gradlew·gradle·verify.sh)
# 안의 것, 그리고 인라인 코드 맨 앞에서 leaf 이름(`:domain-core`, 마디가 `-`로 이어짐)이나 루트 task 이름
# (`:prCheck`, camelCase) 모양인 것. 소문자 한 낱말(`:test`)은 명령 밖에서는 보지 않는다.
GRADLE_COMMAND = re.compile(r"(?:^|\s)(?:\S*/)?(?:gradlew|gradle|verify\.sh)(?=\s|$)")
SINGLE_PART_NAME = re.compile(r"^:[a-z][a-z0-9]*(?:(?:-[a-z0-9]+)+|[A-Z]\w*)$")
ROOT_BUILD = "build.gradle"
ROOT_TASK = re.compile(r"""\btasks\.(?:register|named)\(\s*['"]([A-Za-z][\w-]*)['"]""")
# 루트 build.gradle이 이름을 적지 않는 루트 task. 루트에 적용한 build-logic plugin이 만드는 것(ca.architecture의
# ArchitecturePlugin, ca.strict-lane-stages의 StrictLaneStagesPlugin. 시험이 두 소스와 대조한다)과 Gradle이 모든
# 빌드의 루트에 두는 도움 task다.
PLUGIN_ROOT_TASKS = frozenset({
"verifyCleanArchitectureDependencies", "verifyApplicationCoreDependencyPurity", "verifyNoIgnoredSourcePackages",
"architectureCheck", "verifyStrictLaneStages",
})
GRADLE_ROOT_TASKS = frozenset({
"help", "tasks", "projects", "properties", "dependencies", "dependencyInsight", "buildEnvironment",
"outgoingVariants", "resolvableConfigurations", "javaToolchains", "init", "wrapper", "updateDaemonJvm",
})
HISTORY_QUOTE = re.compile(r"^\s*>\s*(?:\*\*)?이력")
# registry YAML: 행이 가리키는 코드 파일. 마크다운이 아니라 인라인 코드가 없으니 경로 모양의 낱말을 본다.
# 한글에서 끊는다: 주석의 「docs/a.yaml에 적는다」는 조사 앞까지가 경로다.
@@ -408,20 +438,29 @@ def link_targets(lines: list[str]) -> list[tuple[int, str]]:
return targets
def broken_relative_links(known: set[str], path: str, text: str) -> tuple[int, list[tuple[int, str]]]:
"""(본 상대 링크 수, [(파일의 줄 번호, 대상)]) — 대상이 저장소 밖(..)이거나 git이 모르는 곳인 링크.
`path`는 저장소 루트에서 본 문서 경로, `known`은 known_paths(). check-work-docs.py도 이것을 쓴다."""
lines = body_lines(text)
offset = len(text.split("\n")) - len(lines)
targets = link_targets(lines)
broken = []
for number, target in targets:
resolved = posixpath.normpath(posixpath.join(posixpath.dirname(path), target))
if resolved.startswith("..") or not is_known(known, resolved):
broken.append((number + offset, target))
return len(targets), broken
def check_link(root: Path, files: list[str]) -> list[Problem]:
known = known_paths(root)
problems = []
for path in files:
if not is_living(path):
continue
text = (root / path).read_text(encoding="utf-8")
lines = body_lines(text)
offset = len(text.split("\n")) - len(lines)
for number, target in link_targets(lines):
resolved = posixpath.normpath(posixpath.join(posixpath.dirname(path), target))
if resolved.startswith("..") or not is_known(known, resolved):
problems.append(Problem("link", path, target, f"없는 곳을 가리키는 상대 링크다: {target}",
number + offset))
_, broken = broken_relative_links(known, path, (root / path).read_text(encoding="utf-8"))
for number, target in broken:
problems.append(Problem("link", path, target, f"없는 곳을 가리키는 상대 링크다: {target}", number))
return problems
@@ -464,17 +503,35 @@ def check_style(root: Path, files: list[str]) -> list[Problem]:
return problems
def registry_projects(root: Path) -> set[str]:
def registry_modules(root: Path) -> list[dict]:
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
return []
return json.loads(registry.read_text(encoding="utf-8")).get("modules", [])
def root_tasks(root: Path) -> set[str]:
"""`:<task>` for every task the root build script registers or names, the root plugin tasks and Gradle's own."""
build = root / ROOT_BUILD
names = set(ROOT_TASK.findall(build.read_text(encoding="utf-8"))) if build.is_file() else set()
return {f":{name}" for name in names | PLUGIN_ROOT_TASKS | GRADLE_ROOT_TASKS}
def unknown_gradle_path(gradle: str, leaves: set[str], tasks: set[str]) -> bool:
"""A Gradle path is a leaf, a root task, or `<leaf>:<task>`. The leading parts of a leaf (`:adapter`,
`:adapter:inbound`) are folders that group leaves, not projects a document should name."""
return gradle not in leaves and gradle not in tasks and gradle.rsplit(":", 1)[0] not in leaves
def source_sets(modules: list[dict], known: set[str]) -> set[str]:
"""Names under `<leaf>/src/` (main, test, testFixtures, …): the first part of a leaf-relative path."""
folders = {module["source_path"].rstrip("/") + "/src/" for module in modules if module.get("source_path")}
names = set()
for path in known:
head, marker, tail = path.partition("/src/")
if marker and tail and head + marker in folders:
names.add(tail.split("/", 1)[0])
return names
def path_candidate(token: str) -> str | None:
@@ -526,23 +583,19 @@ 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 leaf_paths(modules: list[dict], known: set[str]) -> set[str]:
"""Every file and folder git knows under a registered leaf, written from that leaf: `src/test/resources/x.sha256`
in a manual about any leaf resolves when some leaf has it. Only a leaf-relative path (`src/<source set>/…`)
may resolve this way; any other path is written from the repository root or the document folder. A file
outside the leaves (a scaffold template's `src/` tree) does not make a leaf path exist."""
roots = [module["source_path"].rstrip("/") + "/" for module in modules if module.get("source_path")]
return {path[len(root):] for path in known for root in roots if path.startswith(root) and len(path) > len(root)}
def check_reference(root: Path, files: list[str]) -> list[Problem]:
projects = registry_projects(root)
modules = registry_modules(root)
leaves = {module["gradle_path"] for module in modules}
tasks = root_tasks(root)
known = known_paths(root)
missing: list[tuple[str, int, str]] = []
problems = []
@@ -553,11 +606,13 @@ def check_reference(root: Path, files: list[str]) -> list[Problem]:
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():
for index, token in enumerate(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:
if gradle.count(":") == 1 and not GRADLE_COMMAND.search(span) and \
(index or not SINGLE_PART_NAME.match(gradle)):
continue
if leaves and unknown_gradle_path(gradle, leaves, tasks) and gradle not in seen:
seen.add(gradle)
problems.append(Problem("reference", path, gradle,
f"registry에 없는 Gradle 경로다: {gradle}", number + offset))
@@ -577,11 +632,16 @@ def check_reference(root: Path, files: list[str]) -> list[Problem]:
seen.add(target)
missing.append((path, number, target))
skip = ignored(root, {target for _, _, target in missing})
if missing:
skip |= path_suffixes(root)
sets = source_sets(modules, known)
leaf_relative = {target for _, _, target in missing if target.split("/")[0] == "src" and
len(target.split("/")) > 1 and target.split("/")[1] in sets}
in_leaves = leaf_paths(modules, known) if leaf_relative else set()
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))
if target.rstrip("/") in skip or target in skip:
continue
if target in leaf_relative and target.rstrip("/") in in_leaves:
continue
problems.append(Problem("reference", path, target, f"없는 경로다: {target}", number))
return problems
+31 -12
View File
@@ -23,12 +23,14 @@ things break that, and both are mechanical:
It also checks that every playbook keeps the shared nine-section skeleton, that the
"common mistakes" section stays short, that every folder rule book src/**/AGENTS.md has a CLAUDE.md
beside it that only imports it, and that relative links in the checked files resolve.
beside it that only imports it, and that relative links in the checked files resolve. The link rule is
check-docs.py `link`'s, called from there (`broken_relative_links`): a target must be a file or folder git
knows, `..` past the repository root fails, and links in code, inline code and history quotes are skipped.
This lives outside Gradle on purpose: the build does not parse documents.
python3 scripts/check-work-docs.py
python3 scripts/check-work-docs.py --links docs README.md # relative links only, any files
python3 scripts/check-work-docs.py --links docs README.md # relative links only, files this repository's git knows
python3 scripts/check-work-docs.py --history docs/manual # history IDs only, any files
The --links form is for machines without lychee (the link checker the main-stage workflow runs).
@@ -37,6 +39,7 @@ The --history form applies the same history-ID patterns to documents outside doc
from __future__ import annotations
import importlib.util
import re
import sys
from pathlib import Path
@@ -141,7 +144,16 @@ HISTORY_PATTERNS = [
("commit sha", re.compile(r"\b(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}\b", re.ASCII)),
]
LINK = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)", re.ASCII)
def load_check_docs():
spec = importlib.util.spec_from_file_location("check_docs_links", Path(__file__).resolve().parent / "check-docs.py")
module = importlib.util.module_from_spec(spec)
sys.modules[spec.name] = module # dataclasses look the module up while the class is made
spec.loader.exec_module(module)
return module
CHECK_DOCS = load_check_docs()
def rel(path: Path) -> str:
@@ -300,17 +312,15 @@ def history_hits(files: list[Path]) -> list[tuple[Path, int, str, str]]:
return hits
def broken_links(files: list[Path]) -> tuple[int, list[tuple[Path, int, str]]]:
def broken_links(files: list[Path], known: set[str] | None = None) -> tuple[int, list[tuple[Path, int, str]]]:
if known is None:
known = CHECK_DOCS.known_paths(REPO_ROOT)
checked = 0
broken = []
for path in files:
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
for target in LINK.findall(line):
if re.match(r"^[a-z][a-z0-9+.-]*:", target) or target.startswith("#"):
continue
checked += 1
if not (path.parent / target.split("#", 1)[0]).exists():
broken.append((path, number, target))
count, found = CHECK_DOCS.broken_relative_links(known, rel(path), path.read_text(encoding="utf-8"))
checked += count
broken += [(path, number, target) for number, target in found]
return checked, broken
@@ -342,7 +352,16 @@ def markdown_files(targets: list[str]) -> list[Path]:
def links_only(targets: list[str]) -> int:
files = markdown_files(targets)
checked, broken = broken_links(files)
known = CHECK_DOCS.known_paths(REPO_ROOT)
# Links resolve against what this repository's git knows, so a file it does not know is refused: one
# outside it, or one inside that git ignores (another checkout under .claude/worktrees/, build output).
outside = [path for path in files if not path.is_relative_to(REPO_ROOT) or rel(path) not in known]
for path in outside:
where = "outside the repository" if not path.is_relative_to(REPO_ROOT) else "not a file git knows in"
print(f" {path}: {where} {REPO_ROOT}; links resolve against what its git knows", file=sys.stderr)
if outside:
return 2
checked, broken = broken_links(files, known)
print(f"files: {len(files)}, relative links checked: {checked}, broken: {len(broken)}")
for path, number, target in broken:
print(f" {path}:{number}: broken relative link '{target}'", file=sys.stderr)
+81
View File
@@ -7,6 +7,7 @@ from __future__ import annotations
import importlib.util
import json
import re
import subprocess
import sys
import tempfile
@@ -245,6 +246,36 @@ class ReferenceTest(RepositoryTestCase):
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_missing_claude_rule_or_skill_fails(self) -> None:
self.repo.write(".claude/rules/kept.md", KOREAN)
errors = self.errors_for("`.claude/rules/kept.md`와 `.claude/rules/gone.md`, `.claude/skills/gone/`을 읽는다.\n")
self.assertFailsWith(errors, "없는 경로다: .claude/rules/gone.md")
self.assertFailsWith(errors, "없는 경로다: .claude/skills/gone/")
self.assertEqual(len(errors), 2, errors)
def test_a_repository_path_does_not_resolve_through_the_tail_of_another_file(self) -> None:
# The feature scaffold keeps `src/...` trees under its templates. A removed leaf folder used to
# pass because some template path ended with it. A leaf-relative path beside it still resolves that way.
self.repo.write("scripts/tpl/src/adapter/inbound/old/x.java", "class X {}\n")
self.repo.write("src/app/src/test/resources/x.sha256", "x")
errors = self.errors_for("`src/adapter/inbound/old/`와 각 leaf의 `src/test/resources/x.sha256`을 본다.\n")
self.assertFailsWith(errors, "없는 경로다: src/adapter/inbound/old/")
self.assertEqual(len(errors), 1, errors)
def test_a_leaf_relative_path_resolves_only_through_a_registered_leaf(self) -> None:
# A template's `src/main/java/...` tree is not a leaf: a leaf-relative path only it has does not exist.
self.repo.write("scripts/tpl/src/main/java/dev/x/Gone.java", "class Gone {}\n")
self.repo.write("scripts/tpl/src/app/src/main/java/dev/x/Old.java", "class Old {}\n")
self.repo.write("src/app/src/main/java/dev/x/Kept.java", "class Kept {}\n")
# A path that is not leaf-relative (`docs/…`) does not resolve through a leaf that has it either.
self.repo.write("src/app/docs/app.md", KOREAN)
errors = self.errors_for("각 leaf의 `src/main/java/dev/x/Gone.java`, `src/main/java/dev/x/Old.java`와 "
"`src/main/java/dev/x/Kept.java`, 그리고 `docs/app.md`를 본다.\n")
self.assertFailsWith(errors, "없는 경로다: src/main/java/dev/x/Gone.java")
self.assertFailsWith(errors, "없는 경로다: src/main/java/dev/x/Old.java")
self.assertFailsWith(errors, "없는 경로다: docs/app.md")
self.assertEqual(len(errors), 3, errors)
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"), [])
@@ -254,6 +285,56 @@ class ReferenceTest(RepositoryTestCase):
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_a_leaf_path_outside_the_registry_fails(self) -> None:
# Every leading part of a leaf (`:adapter:inbound`) used to count as a project, so a renamed leaf
# written without a task passed as a task of that family.
for gradle in (":adapter:inbound:web-old", ":adapter:inbound:gone"):
with self.subTest(gradle=gradle):
self.assertFailsWith(self.errors_for(f"`{gradle}`를 본다.\n"), f"registry에 없는 Gradle 경로다: {gradle}")
def test_a_task_of_a_family_folder_fails(self) -> None:
self.assertFailsWith(self.errors_for("`./gradlew :adapter:inbound:check`를 돌린다.\n"),
"registry에 없는 Gradle 경로다: :adapter:inbound:check")
def test_a_single_part_path_outside_the_registry_and_the_root_tasks_fails(self) -> None:
for text in ("`:gone-leaf`를 본다.\n", "`scripts/verify.sh leaf :gone-leaf`를 돌린다.\n",
"`./gradlew :app:check :gone-leaf`를 돌린다.\n"):
with self.subTest(text=text):
self.assertFailsWith(self.errors_for(text), "registry에 없는 Gradle 경로다: :gone-leaf")
def test_registered_leaves_and_root_tasks_pass(self) -> None:
self.repo.write("build.gradle", "tasks.register('prCheck') {\n}\ntasks.register(\"mainCheck\", Exec)\n"
"tasks.named('architectureCheck') {\n}\n")
self.repo.write("scripts/verify.sh", "#!/usr/bin/env bash\n")
self.assertEqual(self.errors_for(
"`:app`과 `:adapter:inbound:web`, `./gradlew :prCheck :mainCheck --continue`, `:architectureCheck`,\n"
"`scripts/verify.sh leaf :app`, `./gradlew :verifyStrictLaneStages --dry-run`을 돌린다.\n"
"`./gradlew :verifyCleanArchitectureDependencies`와 `./gradlew :help --task :app:check`도 돌린다.\n"), [])
def test_every_task_the_root_plugins_register_on_the_root_is_a_root_task(self) -> None:
# The root build script applies ca.architecture and ca.strict-lane-stages; it does not name their tasks.
plugins = SCRIPTS.parent / "build-logic/src/main/java/dev/caskeleton/buildlogic"
architecture = (plugins / "architecture/ArchitecturePlugin.java").read_text(encoding="utf-8")
stages = (plugins / "strictlane/StrictLaneStagesPlugin.java").read_text(encoding="utf-8")
names = set(re.findall(r'\bproject\s*\.getTasks\(\)\s*\.register\(\s*"([A-Za-z]\w*)"', architecture))
names |= set(re.findall(r'\bTASK_NAME\s*=\s*"([A-Za-z]\w*)"', stages))
self.assertIn("verifyCleanArchitectureDependencies", names)
self.assertEqual(names - check_docs.PLUGIN_ROOT_TASKS, set())
def test_a_single_part_word_in_a_sentence_is_not_a_gradle_path(self) -> None:
# A lone lowercase word after a colon is prose (`:test` of each leaf, a URI's `:authority`), not a project.
self.assertEqual(self.errors_for("각 leaf의 `:test`, URI의 `:authority`, 단위 `:milliseconds`를 본다.\n"), [])
def test_a_single_part_path_in_a_plain_gradle_command_is_checked(self) -> None:
self.assertFailsWith(self.errors_for("`gradle :gone-leaf`를 돌린다.\n"),
"registry에 없는 Gradle 경로다: :gone-leaf")
def test_a_root_task_name_needs_the_root_build_script(self) -> None:
self.assertFailsWith(self.errors_for("`./gradlew :prCheck`를 돌린다.\n"), "registry에 없는 Gradle 경로다: :prCheck")
def test_a_named_sql_parameter_is_not_a_gradle_path(self) -> None:
self.assertEqual(self.errors_for("`lease_owner = :workerId`만 확인한다.\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"), [])
+47 -4
View File
@@ -7,6 +7,7 @@ from __future__ import annotations
import importlib.util
import io
import subprocess
import sys
import tempfile
import unittest
@@ -23,11 +24,15 @@ PLAYBOOK = "".join(f"## {heading}\n\n- 한 줄.\n\n" for heading in check_work_d
class Repository:
"""A throwaway repository with the smallest work manual the checker accepts."""
"""A throwaway git working tree with the smallest work manual the checker accepts. It sits one folder
below `outside`, so a test can put a file next to the repository that a `../` link would reach."""
def __init__(self) -> None:
self._directory = tempfile.TemporaryDirectory()
self.root = Path(self._directory.name)
self.outside = Path(self._directory.name)
self.root = self.outside / "repo"
self.root.mkdir()
subprocess.run(["git", "init", "-q", str(self.root)], check=True)
self.write("AGENTS.md", "# 정본\n\n- 지도 한 줄.\n")
self.write("CLAUDE.md", "@AGENTS.md\n\n- Claude 전용 한 줄.\n")
self.write("docs/work/README.md", "# 작업 매뉴얼\n")
@@ -50,10 +55,10 @@ class Repository:
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(text, encoding="utf-8")
def run(self) -> tuple[int, str]:
def run(self, *args: str) -> tuple[int, str]:
out, err = io.StringIO(), io.StringIO()
argv = sys.argv
sys.argv = ["check-work-docs.py"]
sys.argv = ["check-work-docs.py", *args]
try:
with redirect_stdout(out), redirect_stderr(err):
code = check_work_docs.main()
@@ -154,6 +159,44 @@ class CheckWorkDocsTest(unittest.TestCase):
self.repo.write("src/app/AGENTS.md", "# app\n\n[설계](README.md)\n")
self.assertFailsWith("src/app/AGENTS.md:3: broken relative link 'README.md'")
def links(self, text: str) -> tuple[int, str]:
self.repo.write("docs/guide.md", f"# 안내\n\n{text}")
return self.repo.run("--links", str(self.repo.root / "docs/guide.md"))
def test_links_out_of_the_repository_fail_even_when_the_file_is_there(self) -> None:
# check-docs.py `link` refuses `..` past the root; --links used to accept any file on disk.
(self.repo.outside / "x.md").write_text("# 옆 clone\n", encoding="utf-8")
code, err = self.links("[옆](../../x.md)\n")
self.assertEqual(code, 1, err)
self.assertIn("guide.md:3: broken relative link '../../x.md'", err)
def test_links_to_a_folder_git_does_not_know_fail(self) -> None:
# `git mv` leaves the old folder on disk; a fresh checkout does not have it.
(self.repo.root / "docs/moved").mkdir(parents=True)
code, err = self.links("[옛 폴더](moved/)\n")
self.assertEqual(code, 1, err)
self.assertIn("broken relative link 'moved/'", err)
def test_links_follow_the_document_checker_rules(self) -> None:
# One rule for both checkers: links in code, inline code and history quotes are not links.
code, err = self.links("[지도](../AGENTS.md)\n\n```text\n[예](gone.md)\n```\n\n`[예](gone.md)`\n\n"
"> 이력: [옛](gone.md)\n")
self.assertEqual((code, err), (0, ""))
def test_links_from_a_file_outside_the_repository_are_refused(self) -> None:
(self.repo.outside / "x.md").write_text("# 밖\n", encoding="utf-8")
code, err = self.repo.run("--links", str(self.repo.outside / "x.md"))
self.assertEqual(code, 2, err)
self.assertIn("outside the repository", err)
def test_links_from_an_ignored_checkout_inside_the_repository_are_refused(self) -> None:
# Another worktree under .claude/worktrees/ has its own git; its links say nothing about this one's.
self.repo.write(".gitignore", ".claude/worktrees/\n")
self.repo.write(".claude/worktrees/other/a.md", "# 다른 checkout\n\n[지도](../../../AGENTS.md)\n")
code, err = self.repo.run("--links", str(self.repo.root / ".claude/worktrees/other/a.md"))
self.assertEqual(code, 2, err)
self.assertIn("not a file git knows", err)
if __name__ == "__main__":
unittest.main()