From 7de272026acd3d931cc8032b494e056ec4528101 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 22 Nov 2026 01:43:32 +0900 Subject: [PATCH 1/4] =?UTF-8?q?fix(scripts)!:=20=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EA=B2=80=EC=82=AC=EA=B0=80=20task=20=EC=97=86=EB=8A=94=20leaf?= =?UTF-8?q?=20=EA=B2=BD=EB=A1=9C=EC=99=80=20=ED=95=9C=20=EB=A7=88=EB=94=94?= =?UTF-8?q?=20Gradle=20=EA=B2=BD=EB=A1=9C=EB=A5=BC=20=EB=8C=80=EC=A1=B0?= =?UTF-8?q?=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문서 검사 reference는 문서의 Gradle 경로를 registry와 대조한다고 하지만 두 꼴을 놓친다. registry_projects가 leaf뿐 아니라 모든 앞부분(:adapter, :adapter:inbound)을 넣고 부모가 그 집합에 있으면 통과시켜서, 이름을 바꾼 leaf를 task 없이 쓴 `:adapter:inbound:web-old`가 통과한다. GRADLE_PATH가 두 마디 이상만 봐서 `:gone-leaf` 같은 한 마디 경로는 아예 검사 밖이다. 비교 대상을 registry leaf, 루트 task, `:` 셋으로 좁힌다. 루트 task는 루트 build.gradle의 tasks.register·tasks.named 이름, 루트에 적용한 plugin(ca.architecture, ca.strict-lane-stages)이 만드는 task, Gradle 도움 task(help, tasks 등)다. plugin task 목록은 시험이 두 plugin 소스와 대조한다. 한 마디 경로는 SQL의 이름 붙은 인자(`lease_owner = :workerId`)나 문장 속 표기(각 leaf의 `:test`)와 모양이 같아서, gradlew·gradle·verify.sh 명령 안에서, 또는 인라인 코드 맨 앞에서 leaf 이름(마디가 `-`로 이어짐)·루트 task 이름(camelCase) 모양일 때만 본다. 버린 안: task 이름까지 대조 — Gradle 없이 알 수 없고, 빌드는 문서를 읽지 않는다는 규칙과 부딪힌다. 맨 앞 한 마디를 늘 Gradle 경로로 보기 — 문장 속 `:test`·`:authority`가 거짓 실패한다. docs/README.md 「문서 검사」의 reference 행을 같은 규칙으로 고치고, 파생 서비스 문서가 새로 실패하는 꼴을 docs/upgrade/2026-11-docs-check-references.md에 적는다. 한계: `:`의 task 이름은 여전히 보지 않는다. 소문자 한 낱말 경로(`:app`)는 명령 밖에서 보지 않는다. 루트 plugin이 새 루트 task를 만들면 PLUGIN_ROOT_TASKS에 더해야 한다(시험이 알린다). 검증: python3 -m unittest discover -s scripts/tests -p 'test_check_*docs.py' OK(121), python3 scripts/check-docs.py rc=0. Refs: REV-BE-0009 BREAKING CHANGE: 문서 검사 reference가 task 없이 쓴 leaf 경로, 묶음 폴더의 task(`:adapter:inbound:check`), 한 마디 경로(`:gone-leaf`)를 registry leaf·루트 task와 대조한다. 파생 서비스 문서에 그런 낡은 경로가 있으면 PR 단계 documentCheck가 실패한다. 할 일은 docs/upgrade/2026-11-docs-check-references.md 1·2번이다. --- docs/README.md | 2 +- docs/upgrade/2026-11-docs-check-references.md | 33 +++++++++ scripts/check-docs.py | 67 ++++++++++++++----- scripts/tests/test_check_docs.py | 51 ++++++++++++++ 4 files changed, 136 insertions(+), 17 deletions(-) create mode 100644 docs/upgrade/2026-11-docs-check-references.md diff --git a/docs/README.md b/docs/README.md index 586744a7..5e552b5e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -192,7 +192,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것 | --- | --- | | `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) | | `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 | -| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. `docs/registries/*.yaml`은 값과 주석에 적은 repo 경로를 본다(행의 `source`·`registered_by`가 옮긴 파일을 가리키면 PR에서 걸린다). 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | +| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. Gradle 경로는 registry의 leaf, 루트 task(루트 `build.gradle`이 이름을 적은 것, 루트 plugin과 Gradle 도움 task), `:` 중 하나여야 한다. 한 마디 경로(`:domain-core`)는 `gradlew`·`gradle`·`verify.sh` 명령 안에서, 또는 인라인 코드 맨 앞에서 leaf·루트 task 이름 모양일 때만 본다. `docs/registries/*.yaml`은 값과 주석에 적은 repo 경로를 본다(행의 `source`·`registered_by`가 옮긴 파일을 가리키면 PR에서 걸린다). 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | | `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 | | `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 | | `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 | diff --git a/docs/upgrade/2026-11-docs-check-references.md b/docs/upgrade/2026-11-docs-check-references.md new file mode 100644 index 00000000..215a1d50 --- /dev/null +++ b/docs/upgrade/2026-11-docs-check-references.md @@ -0,0 +1,33 @@ +# 업그레이드 안내 — 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 경로와 `<묶음 폴더>:`를 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. 바뀌지 않은 것 + +- 코드, 빌드, 설정, workflow는 그대로다. 검사가 보는 문서(살아 있는 문서, `docs/registries/*.yaml`)와 건너뛰는 곳(코드 블록, + `> 이력` 인용 블록, 제거 표, `upgrade/`, 기록 문서)도 그대로다. +- `:`의 task 이름은 Gradle 없이 알 수 없어 여전히 보지 않는다. + +## 4. 확인하는 법 + +merge한 트리에서 돌린다. rc=0이면 할 일이 없다. + +```bash +python3 scripts/check-docs.py --only reference +python3 scripts/check-work-docs.py --links docs README.md +``` diff --git a/scripts/check-docs.py b/scripts/check-docs.py index b4c18ede..698c3277 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -13,8 +13,13 @@ 머리 블록이 있다. 상태는 종류별 고정 어휘, 작성일은 날짜, 요약은 한국어, 현재 정본과 대체됨이 가리키는 경로는 지금 있다. reference 살아 있는 문서의 인라인 코드 안 repo 경로(src/, docs/, scripts/, compose/, .github/, .gitea/로 - 시작. 2026-11-07에 지운 infra/ 아래 경로도 본다)와 Gradle 경로(:a:b)가 지금 트리와 - registry에 있다. 「있다」는 git이 아는 파일(추적 + 무시되지 않은 새 파일)과 그 위 폴더다. 디스크에만 + 시작. 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), `:` 중 하나다. task 이름은 Gradle 없이 알 수 없어 보지 않는다. 한 마디 + 경로는 gradlew·gradle·verify.sh 명령 안에서, 또는 인라인 코드 맨 앞에서 leaf·루트 task 이름 모양 + (`:domain-core`, `:prCheck`)일 때만 본다. SQL 인자 `:workerId`, 문장 속 `:test`와 모양이 같기 때문이다. + 「있다」는 git이 아는 파일(추적 + 무시되지 않은 새 파일)과 그 위 폴더다. 디스크에만 있는 것(git mv가 남긴 빈 폴더 등)은 새 checkout에 없으므로 세지 않는다. 기록의 「현재 정본」·「대체됨」 경로도 같다. 코드 블록과 「이력」으로 시작하는 인용 블록은 건너뛴다. 마크다운 링크는 lychee와 check-work-docs.py --links가 본다. registry(docs/registries/*.yaml)의 값(따옴표가 있든 @@ -134,7 +139,26 @@ 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에 적는다」는 조사 앞까지가 경로다. @@ -464,17 +488,24 @@ 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]: + """`:` 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 `:`. 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 path_candidate(token: str) -> str | None: @@ -542,7 +573,9 @@ def path_suffixes(root: Path) -> set[str]: 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 +586,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)) diff --git a/scripts/tests/test_check_docs.py b/scripts/tests/test_check_docs.py index bcca29a1..d650226c 100644 --- a/scripts/tests/test_check_docs.py +++ b/scripts/tests/test_check_docs.py @@ -7,6 +7,7 @@ from __future__ import annotations import importlib.util import json +import re import subprocess import sys import tempfile @@ -254,6 +255,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"), []) -- 2.54.0 From 6000ef1f351e5a0143e84fdb79748c5b190d90ff Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 22 Nov 2026 01:43:52 +0900 Subject: [PATCH 2/4] =?UTF-8?q?fix(scripts)!:=20=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EA=B2=80=EC=82=AC=EA=B0=80=20.claude/=20=EA=B2=BD=EB=A1=9C?= =?UTF-8?q?=EB=A5=BC=20=EB=B3=B4=EA=B3=A0=20=EA=BC=AC=EB=A6=AC=20=EB=8C=80?= =?UTF-8?q?=EC=A1=B0=EB=A5=BC=20leaf=20=EC=95=88=EC=9C=BC=EB=A1=9C=20?= =?UTF-8?q?=EC=A2=81=ED=9E=8C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문서 검사 reference의 경로 뿌리(PATH_ROOTS)에 .claude/가 없어서, 진입 문서가 가리키는 .claude/rules/*.md·.claude/skills/*의 이름을 바꿔도 실패하지 않는다. 또 없는 경로가 git이 아는 아무 파일·폴더의 꼬리와 같으면 통과시켜서, scripts/feature-scaffold/templates/src/ 아래 템플릿 때문에 지운 leaf 폴더 `src/adapter/inbound/old/` 같은 경로도 통과한다. docstring은 뿌리를 여섯으로 적고 코드는 아홉이다. PATH_ROOTS에 .claude/를 더한다. 꼬리 대조는 leaf 상대 경로, 곧 `src/` 다음 첫 마디가 registry leaf의 src/ 아래 소스 세트 이름(main, test, testFixtures 등)인 경로에만 쓰고, 꼬리는 registry leaf 폴더 아래 파일을 그 leaf에서 쓴 경로로만 만든다. 그래서 템플릿의 src/ 나무나 leaf 폴더 안 docs/는 leaf 경로를 살리지 않는다. 나머지는 저장소 루트나 문서 폴더에서 읽혀야 한다. docstring과 docs/README.md 「문서 검사」의 뿌리 목록·꼬리 규칙을 코드에 맞추고(README는 PATH_ROOTS를 가리킨다), 업그레이드 안내에 새로 실패하는 꼴 둘을 더한다. 한계: config/ 뿌리는 자원 폴더 상대 경로(config/module-defaults/*.yml)가 많아 이번에 더하지 않는다(카드 범위의 「바꾸지 말 것」). 검증: python3 -m unittest discover -s scripts/tests -p 'test_check_*docs.py' OK(124), python3 scripts/check-docs.py rc=0. Refs: REV-BE-0010 BREAKING CHANGE: 문서 검사 reference가 인라인 코드의 .claude/ 경로를 지금 트리와 대조하고, leaf 상대 경로는 registry leaf 폴더 아래에 있을 때만 통과시킨다. 파생 서비스 문서에 옮긴 .claude/ 파일이나 템플릿·다른 파일의 꼬리로만 통과하던 경로가 있으면 PR 단계 documentCheck가 실패한다. 할 일은 docs/upgrade/2026-11-docs-check-references.md 3·4번이다. --- docs/README.md | 2 +- docs/upgrade/2026-11-docs-check-references.md | 2 + scripts/check-docs.py | 61 +++++++++++-------- scripts/tests/test_check_docs.py | 30 +++++++++ 4 files changed, 70 insertions(+), 25 deletions(-) diff --git a/docs/README.md b/docs/README.md index 5e552b5e..c042309c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -192,7 +192,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것 | --- | --- | | `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) | | `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 | -| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. Gradle 경로는 registry의 leaf, 루트 task(루트 `build.gradle`이 이름을 적은 것, 루트 plugin과 Gradle 도움 task), `:` 중 하나여야 한다. 한 마디 경로(`:domain-core`)는 `gradlew`·`gradle`·`verify.sh` 명령 안에서, 또는 인라인 코드 맨 앞에서 leaf·루트 task 이름 모양일 때만 본다. `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), `:` 중 하나여야 한다. 한 마디 경로(`: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가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 | diff --git a/docs/upgrade/2026-11-docs-check-references.md b/docs/upgrade/2026-11-docs-check-references.md index 215a1d50..f936bbf6 100644 --- a/docs/upgrade/2026-11-docs-check-references.md +++ b/docs/upgrade/2026-11-docs-check-references.md @@ -16,6 +16,8 @@ | --- | --- | --- | --- | --- | | 1 | task 없이 쓴 Gradle 경로와 `<묶음 폴더>:`를 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나 템플릿에만 있는 경로를 문서에 쓴 서비스 | ## 3. 바뀌지 않은 것 diff --git a/scripts/check-docs.py b/scripts/check-docs.py index 698c3277..38833774 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -12,17 +12,19 @@ head 기록(docs/design, docs/history, docs/adr)의 .md는 맨 위에 머리 블록이 있다. 상태는 종류별 고정 어휘, 작성일은 날짜, 요약은 한국어, 현재 정본과 대체됨이 가리키는 경로는 지금 있다. - reference 살아 있는 문서의 인라인 코드 안 repo 경로(src/, docs/, scripts/, compose/, .github/, .gitea/로 - 시작. 2026-11-07에 지운 infra/ 아래 경로도 본다)와 + 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), `:` 중 하나다. task 이름은 Gradle 없이 알 수 없어 보지 않는다. 한 마디 경로는 gradlew·gradle·verify.sh 명령 안에서, 또는 인라인 코드 맨 앞에서 leaf·루트 task 이름 모양 (`:domain-core`, `:prCheck`)일 때만 본다. SQL 인자 `:workerId`, 문장 속 `:test`와 모양이 같기 때문이다. - 「있다」는 git이 아는 파일(추적 + 무시되지 않은 새 파일)과 그 위 폴더다. 디스크에만 - 있는 것(git mv가 남긴 빈 폴더 등)은 새 checkout에 없으므로 세지 않는다. 기록의 「현재 정본」·「대체됨」 - 경로도 같다. 코드 블록과 「이력」으로 시작하는 인용 블록은 건너뛴다. 마크다운 - 링크는 lychee와 check-work-docs.py --links가 본다. registry(docs/registries/*.yaml)의 값(따옴표가 있든 + 「있다」는 git이 아는 파일(추적 + 무시되지 않은 새 파일)과 그 위 폴더다. 문서 폴더에서 읽어도 + 된다(leaf 문서의 src/main/…). leaf 상대 경로(src/<소스 세트>/…)는 registry의 어느 leaf 폴더 아래에 + 있으면 된다(템플릿 폴더의 src/ 나무는 세지 않는다). 디스크에만 있는 것(git mv가 남긴 빈 폴더 등)은 + 새 checkout에 없으므로 세지 않는다. + 기록의 「현재 정본」·「대체됨」 경로도 같다. 코드 블록과 「이력」으로 시작하는 인용 블록은 + 건너뛴다. 마크다운 링크는 lychee와 check-work-docs.py --links가 본다. registry(docs/registries/*.yaml)의 값(따옴표가 있든 없든)과 주석에 적은 repo 경로도 본다: 행의 `source`·`registered_by`가 옮긴 파일을 가리키면 main 단계의 대조 시험(document-contract)보다 먼저 PR에서 걸린다. number 살아 있는 문서가 정본이 정하는 숫자를 복사하지 않는다: Spring Boot 버전, leaf 개수. @@ -134,7 +136,8 @@ 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의 것인지 문장이 정한다. @@ -508,6 +511,17 @@ def unknown_gradle_path(gradle: str, leaves: set[str], tasks: set[str]) -> bool: 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 `/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: token = token.strip().strip("'\"()[],;") if token.startswith("./"): @@ -557,19 +571,13 @@ 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//…`) + 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]: @@ -612,11 +620,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 diff --git a/scripts/tests/test_check_docs.py b/scripts/tests/test_check_docs.py index d650226c..fe533e48 100644 --- a/scripts/tests/test_check_docs.py +++ b/scripts/tests/test_check_docs.py @@ -246,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"), []) -- 2.54.0 From 2bd4a815fb5600c9425969fe116ac6c59c987c1f Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 22 Nov 2026 01:44:00 +0900 Subject: [PATCH 3/4] =?UTF-8?q?docs(jpa):=20=EC=97=86=EB=8A=94=20=EA=B3=84?= =?UTF-8?q?=ED=9A=8D=20=EA=B2=BD=EB=A1=9C=20=EB=8C=80=EC=8B=A0=20=EA=B3=84?= =?UTF-8?q?=ED=9A=8D=20=EB=AC=B8=EC=84=9C=EB=A5=BC=20=EA=B0=80=EB=A6=AC?= =?UTF-8?q?=ED=82=A8=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/jpa/repository-adaptation.md의 계획 대조 표 한 칸이 지금 없는 build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt를 백틱 없이 적는다. 레이아웃을 옮긴 커밋이 PATH_ROOTS에 build-logic/을 더하면서 이 칸의 백틱을 빼 참조 검사를 피했다. 칸을 계획 문서와 그 줄(218줄)을 가리키는 말로 바꾼다. 계획 문서는 있는 경로라 참조 검사가 계속 본다. 버린 안: 행 전체를 「이력」 인용 블록으로 옮기기 — 표 안이라 블록으로 옮길 수 없다. 검증: git grep -n 'build-logic/src/test/kotlin' -- docs/jpa/repository-adaptation.md rc=1(없음), python3 scripts/check-docs.py rc=0. Refs: REV-BE-0015 --- docs/jpa/repository-adaptation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/jpa/repository-adaptation.md b/docs/jpa/repository-adaptation.md index fbeffa3e..69c89fa4 100644 --- a/docs/jpa/repository-adaptation.md +++ b/docs/jpa/repository-adaptation.md @@ -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`가 한다. | -- 2.54.0 From f0ab268e9e5a0f4a0511d102d78fa788fccdba22 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 22 Nov 2026 01:44:53 +0900 Subject: [PATCH 4/4] =?UTF-8?q?fix(scripts)!:=20check-work-docs=EC=9D=98?= =?UTF-8?q?=20=EC=83=81=EB=8C=80=20=EB=A7=81=ED=81=AC=20=EA=B2=80=EC=82=AC?= =?UTF-8?q?=EA=B0=80=20check-docs=20link=20=EA=B7=9C=EC=B9=99=EC=9D=84=20?= =?UTF-8?q?=EC=93=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 상대 링크 검사가 둘이고 규칙이 갈라졌다. check-docs.py의 link는 git이 아는 경로만 받고 저장소 밖(..)은 실패로 본다. check-work-docs.py는 디스크를 exists()로 봐서 git이 모르는 파일, git mv가 남긴 빈 폴더, 저장소 밖 형제 clone(../design-docs/…)도 통과시킨다. 기본 실행은 같은 PR 단계에서 check-docs.py link가 다시 보지만, lychee 없는 기계에서 손으로 쓰는 --links는 약한 쪽의 답만 준다. check-docs.py의 check_link 몸통을 broken_relative_links(known, path, text)로 뽑고(규칙은 그대로) check-work-docs.py가 그 모듈을 불러 기본 실행과 --links 모두 같은 함수를 쓴다. 그래서 링크 규칙을 한 곳에서 고친다. --links에 저장소 밖 파일이나 이 저장소 git이 모르는 파일(무시된 다른 checkout .claude/worktrees/…, 빌드 출력)을 주면 그 git으로는 대조할 수 없으므로 rc=2로 거절한다. 버린 안: check-work-docs.py에 git 대조를 따로 구현 — 규칙이 다시 둘이 된다. 위험: check-work-docs.py 기본 실행도 이제 코드 블록·인라인 코드·「이력」 인용 블록 안의 링크를 보지 않는다(check-docs.py link와 같다). 지금 트리에서 깨진 링크 0은 그대로다. 옛 --links가 깨짐으로 본 인라인 코드 속 링크 표기 (docs/upgrade/2026-11-round9-followups.md:31)는 이제 링크로 보지 않는다. 시험 fixture가 git 저장소가 됐다(known_paths가 git ls-files를 쓴다). 검증: python3 -m unittest discover -s scripts/tests -p 'test_check_*docs.py' OK(129), python3 scripts/check-work-docs.py rc=0, python3 scripts/check-work-docs.py --links docs README.md rc=0(536 링크, 깨짐 0), python3 scripts/check-docs.py rc=0. Refs: REV-BE-0017 BREAKING CHANGE: check-work-docs.py --links가 저장소 루트를 넘는 링크와 git이 모르는 곳을 가리키는 링크를 깨짐(rc=1)으로 보고, 저장소 밖이나 git이 모르는 파일을 받으면 rc=2로 거절한다. 그 명령을 스크립트로 쓰는 파생 서비스는 docs/upgrade/2026-11-docs-check-references.md 5번을 본다. --- docs/upgrade/2026-11-docs-check-references.md | 1 + scripts/check-docs.py | 30 +++++++---- scripts/check-work-docs.py | 43 +++++++++++----- scripts/tests/test_check_work_docs.py | 51 +++++++++++++++++-- 4 files changed, 100 insertions(+), 25 deletions(-) diff --git a/docs/upgrade/2026-11-docs-check-references.md b/docs/upgrade/2026-11-docs-check-references.md index f936bbf6..dc87cad8 100644 --- a/docs/upgrade/2026-11-docs-check-references.md +++ b/docs/upgrade/2026-11-docs-check-references.md @@ -18,6 +18,7 @@ | 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. 바뀌지 않은 것 diff --git a/scripts/check-docs.py b/scripts/check-docs.py index 38833774..f079ff47 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -24,7 +24,7 @@ 있으면 된다(템플릿 폴더의 src/ 나무는 세지 않는다). 디스크에만 있는 것(git mv가 남긴 빈 폴더 등)은 새 checkout에 없으므로 세지 않는다. 기록의 「현재 정본」·「대체됨」 경로도 같다. 코드 블록과 「이력」으로 시작하는 인용 블록은 - 건너뛴다. 마크다운 링크는 lychee와 check-work-docs.py --links가 본다. registry(docs/registries/*.yaml)의 값(따옴표가 있든 + 건너뛴다. 마크다운 링크는 link와 lychee가 본다. registry(docs/registries/*.yaml)의 값(따옴표가 있든 없든)과 주석에 적은 repo 경로도 본다: 행의 `source`·`registered_by`가 옮긴 파일을 가리키면 main 단계의 대조 시험(document-contract)보다 먼저 PR에서 걸린다. number 살아 있는 문서가 정본이 정하는 숫자를 복사하지 않는다: Spring Boot 버전, leaf 개수. @@ -36,6 +36,9 @@ 그 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다. readme 루트 README.md가 정해진 절을 정해진 순서로 가진다: 첫 줄의 제목, 그 아래 한 문단, 그리고 README_SECTIONS의 ## 제목. 그 사이에 다른 절이 있어도 된다. + link 살아 있는 문서의 상대 링크가 git이 아는 파일·폴더를 가리킨다. 저장소 밖(..)으로 나가면 실패다. + 코드 블록·인라인 코드·「이력」 인용 블록 안은 링크로 보지 않는다. check-work-docs.py(--links + 포함)도 같은 함수(broken_relative_links)를 불러 규칙이 한 곳에 있다. 소스 세트의 resources 폴더 아래 .md(src/**/src/<세트>/resources/)는 시험 입력이나 실행 자원이라 문서로 보지 않는다. @@ -435,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 diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py index eb544e9f..ef3a04e7 100755 --- a/scripts/check-work-docs.py +++ b/scripts/check-work-docs.py @@ -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) diff --git a/scripts/tests/test_check_work_docs.py b/scripts/tests/test_check_work_docs.py index f87900e1..3228addf 100644 --- a/scripts/tests/test_check_work_docs.py +++ b/scripts/tests/test_check_work_docs.py @@ -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() -- 2.54.0