Files
clean-architecture-backend-…/scripts/check-repo-layout.py
T
DongHyeonka e13a29024f ci(repo)!: 최상위 폴더 허용 목록 검사를 더한다
문제: src/ 아래 계층이 아닌 폴더가 2026-07-24의 둘에서 두 달 사이
여덟으로 늘었고, 루트에는 compose 파일과 infra/가 쌓였다. 어느 커밋도
최상위 모양을 묻지 않았고 리뷰 기준에도 그 칸이 없었다.

고른 방법(소유자 결정 2026-11-07, 설계 10.3절): scripts/check-repo-layout.py
- 저장소 루트와 src/ 바로 아래의 추적 항목이 허용 목록 안에 있는가
- registry source_path가 허용된 src/ 폴더 아래인가
- (경고) compose·스크립트·compose 보조 파일을 아무 추적 파일도 가리키지
  않는가
를 본다. ci-quality-gates.yml quality-gates job에 한 단계로 붙인다.
Gradle 밖 스크립트다(문서·배치를 파싱하는 Gradle 검사를 두지 않는 정책).
버린 대안: registry에서 허용 폴더를 파생하기. 새 vendored 폴더를 registry
에 등록하는 것만으로 통과해, 막으려는 drift를 막지 못한다.

위험·한계: 참조 0 경고는 경로를 변수로 조립하는 workflow를 따라가지
못해 경고로만 둔다. 리뷰 기준·playbook 문장은 매뉴얼 보강 작업이 넣는다.

검증:
- 노트북·desktop: python3 scripts/check-repo-layout.py rc=0, 경고 0
- 일부러 infra/, src/messaging/, 고아 compose/orphan.sh를 둔 임시 저장소:
  rc=1, 실패 3건과 경고 1건
- desktop(트리 c7cacf54): :app-bootstrap:repositoryContractTest
  :app-bootstrap:documentContractTest rc=0, :verifyStrictLaneStages --dry-run rc=0
- check-work-docs.py rc=0
- 업그레이드 안내 B-50~B-52의 근거 칸을 커밋 해시로 채운다

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 10.3
BREAKING CHANGE: 저장소 루트나 src/에 허용 목록 밖의 최상위 폴더를 둔 파생 서비스는 PR 게이트가 실패한다. docs/upgrade/2026-11-maturity-review.md B-53.
2026-11-07 13:09:05 +09:00

211 lines
8.2 KiB
Python
Executable File

#!/usr/bin/env python3
"""저장소 루트와 src/ 최상위에 허용 목록 밖의 항목이 생기면 실패한다.
왜: src/ 아래 계층이 아닌 폴더가 2026-07-24의 둘에서 두 달 사이 여덟으로 늘었고, 어느 커밋도 최상위
모양을 묻지 않았다. 루트에는 개발 환경·테스트 fixture·운영 인프라가 섞인 compose 파일과 infra/ 폴더가
쌓였다(2026-11-07 저장소 정리, design-docs repo-structure/01-backend-layout.md). 소유자는 배치 규칙을
리뷰 기준에 두고, 이 허용 목록 검사로도 막기로 정했다(같은 날, repo-structure/README.md 3.1절).
무엇을 보나:
1. 저장소 루트의 추적 파일·폴더가 ROOT_ALLOWED 안에 있는가.
2. src/ 바로 아래의 추적 파일·폴더가 SRC_ALLOWED 안에 있는가.
3. registry(src/config/architecture/modules.json)의 모든 source_path가 허용된 src/ 폴더 아래에 있는가.
4. (경고만) 개발 환경·테스트 fixture 파일(compose 파일, 셸 스크립트, compose/ 아래 보조 파일)을 다른
추적 파일이 하나도 가리키지 않으면 이름을 출력한다. 아무도 읽지 않는 파일이 소리 없이 남는 것이
infra/ 12개가 쌓인 방식이다. 경로를 변수로 조립하는 workflow는 이 검사가 따라가지 못하므로 경고로만 둔다.
추적 파일만 본다(git ls-files). build 출력과 IDE 폴더는 처음부터 대상이 아니다.
새 최상위 항목이 정말 필요하면 아래 목록과 루트 CLAUDE.md 5절 「최상위 폴더는 정해진 것만 둔다」를 같은
변경에서 고친다. 최상위 폴더를 만들거나 옮기는 일은 파일 하나여도 큰 일이다(docs/work/README.md 2절).
Gradle 밖에 둔다: 빌드는 저장소 배치를 판단하지 않는다(scripts/check-work-docs.py와 같은 자리).
python3 scripts/check-repo-layout.py
"""
from __future__ import annotations
import json
import subprocess
import sys
from pathlib import Path, PurePosixPath
REPO_ROOT = Path(__file__).resolve().parent.parent
REGISTRY = "src/config/architecture/modules.json"
# 저장소 루트: 문서·스크립트·CI·개발 환경과 Gradle 루트(src)뿐이다.
ROOT_ALLOWED = {
# 폴더
".claude": "에이전트 세션 설정(추적되는 settings.json)",
".github": "workflow와 공용 action",
"compose": "compose.yaml이 마운트하는 보조 파일",
"docs": "문서",
"scripts": "Gradle 밖 검사·실행 스크립트",
"src": "Gradle 루트",
# 파일
".gitattributes": "Git 설정",
".gitignore": "Git 설정",
".tool-versions": "JDK 버전 고정",
".trivyignore.yaml": "취약점 검사 예외",
"AGENTS.md": "규칙 정본",
"CLAUDE.md": "작업 지도",
"README.md": "저장소 소개",
"compose.yaml": "개발 환경(하나뿐)",
"renovate.json": "의존성 갱신 봇 설정",
"skills-lock.json": "에이전트 스킬 고정",
"testcontainers.properties.example": "Testcontainers 로컬 설정 예",
}
# src/ 바로 아래: 계층·조립 leaf, 들여온 제품 묶음, Gradle 루트 표준 폴더와 빌드 파일.
SRC_ALLOWED = {
# 계층과 조립
"domain-core": "계층",
"shared-contract": "계층",
"application-core": "계층",
"application-fileserver": "계층(capability)",
"application-notification": "계층(capability)",
"application-objectstorage": "계층(capability)",
"adapter": "계층(adapter leaf 묶음)",
"composition": "조립(Clean Architecture의 Main)",
"app-bootstrap": "조립 루트",
# 들여온 제품
"platforms": "들여온 제품(messaging, grpc, grpc-advanced)과 optional 빌드",
# Gradle 루트 표준
"build-logic": "빌드 규칙(included build)",
"config": "빌드 전체 도구 설정(registry, checkstyle, spotbugs, 테스트 이미지)",
"gradle": "wrapper와 버전 카탈로그",
# 파일
".dockerignore": "이미지 빌드 context",
".env.example": "env 계약",
".env.local.example": "로컬 env 예",
".gitignore": "Git 설정",
"Dockerfile": "릴리스 이미지",
"README.md": "빌드·env 안내",
"build.gradle": "루트 빌드",
"gradle.properties": "Gradle 설정",
"gradlew": "wrapper",
"gradlew.bat": "wrapper",
"settings-gradle.lockfile": "settings 잠금",
"settings.gradle": "settings",
}
# 아무도 가리키지 않으면 경고할 파일: 개발 환경과 테스트 fixture.
FIXTURE_SUFFIXES = (".sh", ".acl", ".json", ".yaml", ".yml")
FIXTURE_PREFIXES = ("compose/", "scripts/", "src/app-bootstrap/compose-lanes/")
HISTORY_PREFIXES = (
"docs/reviews/",
"docs/superpowers/",
"docs/evidence/",
"docs/study/",
"docs/adr/",
)
def tracked_files() -> list[str]:
result = subprocess.run(
["git", "ls-files", "-z"],
cwd=REPO_ROOT,
check=True,
capture_output=True,
)
return [path for path in result.stdout.decode("utf-8").split("\0") if path]
def top_level(paths: list[str], prefix: str) -> set[str]:
names = set()
for path in paths:
if not path.startswith(prefix):
continue
rest = path[len(prefix):]
names.add(rest.split("/", 1)[0])
return names
def registry_violations() -> list[str]:
modules = json.loads((REPO_ROOT / REGISTRY).read_text(encoding="utf-8"))["modules"]
problems = []
for module in modules:
source = PurePosixPath(module["source_path"])
parts = source.parts
if len(parts) < 2 or parts[0] != "src" or parts[1] not in SRC_ALLOWED:
problems.append(
f"{REGISTRY}: {module['id']} source_path {source} is not under an allowed src/ folder"
)
return problems
def is_fixture(path: str) -> bool:
if path.endswith(("README.md", ".gitignore")):
return False
name = PurePosixPath(path).name
if path.startswith(FIXTURE_PREFIXES) and name.endswith(FIXTURE_SUFFIXES):
return True
return "compose" in name and name.endswith((".yaml", ".yml"))
def unreferenced_fixtures(paths: list[str]) -> list[str]:
this_script = str(Path(__file__).resolve().relative_to(REPO_ROOT))
readable = [
p for p in paths if not p.startswith(HISTORY_PREFIXES) and p != this_script
]
texts = {}
for path in readable:
file = REPO_ROOT / path
try:
if file.stat().st_size > 2_000_000:
continue
texts[path] = file.read_text(encoding="utf-8")
except (UnicodeDecodeError, OSError):
continue
lonely = []
for path in sorted(p for p in paths if is_fixture(p)):
pure = PurePosixPath(path)
# The file's own path or name, or its folder when a compose file mounts the whole folder
# (./compose/redis/acl). A one-segment folder such as compose/ names too much to count.
needles = {path, pure.name}
if len(pure.parent.parts) >= 2:
needles.add(str(pure.parent))
referenced = any(
other != path and any(needle in text for needle in needles)
for other, text in texts.items()
)
if not referenced:
lonely.append(path)
return lonely
def main() -> int:
paths = tracked_files()
failures = []
for name in sorted(top_level(paths, "") - ROOT_ALLOWED.keys()):
failures.append(f"repository root: '{name}' is not in ROOT_ALLOWED")
for name in sorted(top_level(paths, "src/") - SRC_ALLOWED.keys()):
failures.append(f"src/: '{name}' is not in SRC_ALLOWED")
failures.extend(registry_violations())
for path in unreferenced_fixtures(paths):
print(f"warning: no tracked file refers to {path}")
if failures:
for failure in failures:
print(f"FAIL: {failure}", file=sys.stderr)
print(
"check-repo-layout: a new top-level entry changes the repository's shape. If it is "
"wanted, add it to the allow list in scripts/check-repo-layout.py and to CLAUDE.md "
"section 5 in the same change.",
file=sys.stderr,
)
return 1
print(
f"check-repo-layout: OK — {len(top_level(paths, ''))} root entries, "
f"{len(top_level(paths, 'src/'))} src/ entries, registry paths inside allowed folders"
)
return 0
if __name__ == "__main__":
sys.exit(main())