fix(scripts)!: 문서 검사의 Gradle·경로·링크 대조 빈틈을 닫는다 #86
+1
-1
@@ -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가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
|
||||
|
||||
@@ -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
@@ -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
@@ -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)
|
||||
|
||||
@@ -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"), [])
|
||||
|
||||
|
||||
@@ -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()
|
||||
|
||||
Reference in New Issue
Block a user