템플릿 안에 프로젝트 계층이 아닌 메시징 플랫폼(src/platforms/messaging,
19개 모듈)이 있다. 소유자 결정(2026-11-07)은 라이브러리를 별도 repo에서
관리하고 템플릿은 버전으로 받는 것이다. 라이브러리는 이력째
messaging-library로 옮겨 dev.cakit.messaging 1.0.0으로 Gitea Packages에
게시했다(태그 v1.0.0 = 8c6045e, release run 28).
- 받는 법: src/settings.gradle에 exclusiveContent 저장소(group dev.cakit와
그 아래는 Gitea에서만, 나머지는 Maven Central에서만). 카탈로그
messagingLibrary = "1.0.0"과 쓰는 모듈 여섯.
- 쓰는 leaf: adapter:outbound:messaging, adapter:outbound:messaging-kafka,
adapter:inbound:messaging(admin exclude 좌표를 새 group으로), 시험만
composition:outbox-relay와 app-bootstrap architectureTest. import와
auto-configuration 이름 문자열 dev.caskeleton.messaging →
dev.cakit.messaging, 시험 stand-in도 같은 FQCN으로.
- persistence-jpa migration 시험이 라이브러리 소스 폴더를 경로
(../../../platforms/…)로 읽던 것을, 카탈로그 버전의 jar를 전용 구성
messagingMigrations(non-transitive)로 받아 db/migration을 풀어 읽게
했다. classpath에 올리면 그 leaf 시험의 Flyway가 메시징 migration까지
볼 수 있어 버렸다.
- registry: 메시징 19행을 지우고 library_groups ["dev.cakit"]와 쓰는 세
행의 allowed_libraries. 분리 전 프로젝트 edge 검사가 지키던 약속이
앞 커밋의 라이브러리 edge 검사로 그대로 남는다.
- 계약 테스트: MessagingPublicSurfaceContractTest는 라이브러리로 옮겼고,
MessagingAuthorityContractTest는 이 repo의 app.messaging 주인 하나만
본다(라이브러리 쪽 하나는 그 repo가 본다).
- system caller 규칙(ApplicationBoundaryArchitectureTest)의 「프로젝트
타입」에 dev.cakit.을 더했다. 메시지 handler가 구현하는 MessageHandler가
라이브러리 타입이 되면서, 그대로 두면 manual 09의 handler가
SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES에 걸리고 MessageHandler로
주입받는 endpoint를 USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS가
따라가지 못한다(구조 리뷰가 찾음).
- 순서 시험: 이름 정렬로도 라이브러리 root가 먼저 오게 되어 bridge 시험이
afterName을 지키지 못했다. stand-in을 맨 뒤 순서로 두고, inbox 쪽
beforeName을 지키는 시험을 더했다.
- 지움: src/platforms(와 빈 폴더), messaging-certification.yml, 카탈로그의
avro·cloudevents·protobuf 4.33.2, SpotBugs 제외의 메시징 줄,
check-repo-layout.py의 platforms. 편집 훅이 계층 leaf의 dev.cakit import를
알린다.
- lockfile: 바뀐 줄은 dev.cakit.messaging 좌표 추가 45줄뿐이다(외부
의존성 집합은 그대로, 설계 16절 H6).
버린 대안: 라이브러리 jar를 persistence-jpa testRuntimeOnly로 올려
classpath에서 읽기(위 이유). 템플릿에 docs/messaging 사본을 남기기
(라이브러리 문서와 갈라진다. 다음 커밋이 문서를 그 repo로 가리킨다).
위험: 캐시가 빈 빌드(새 기계, 이미지 builder)는 git.learn.hyeonworks.com에
닿아야 한다. 공개 owner라 토큰은 필요 없다(익명 200 확인). 이 커밋만으로는
살아 있는 문서가 지운 경로를 부른다(check-docs는 다음 커밋에서 통과).
검증: desktop에서 이 트리로 RED·GREEN(system caller 고정 시험 2건, 순서
시험 2건은 수정 전·제약 제거 시 실패, 수정 후 통과). 전체 게이트는
PR 본문.
BREAKING CHANGE: src/platforms/messaging과 project(':messaging:…') 경로가
없어졌다. dev.cakit.messaging:<모듈>:1.0.0 좌표로 받고 import를
dev.caskeleton.messaging → dev.cakit.messaging으로 바꾼다
(docs/upgrade/2026-11-maturity-review.md B-57~B-59).
Refs: design-docs repo-structure/05-library-repos.md 4·8·10·13절
210 lines
8.4 KiB
Python
Executable File
210 lines
8.4 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 폴더는 처음부터 대상이 아니다.
|
|
|
|
새 최상위 항목이 정말 필요하면 아래 목록과 루트 AGENTS.md 「지도」의 최상위 줄을 같은
|
|
변경에서 고친다. 최상위 폴더를 만들거나 옮기는 일은 파일 하나여도 큰 일이다(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": "Claude Code 세션 설정(추적: settings.json의 권한·훅, rules·skills·agents)",
|
|
".github": "workflow와 공용 action",
|
|
"compose": "compose.yaml이 마운트하는 보조 파일",
|
|
"docs": "문서",
|
|
"scripts": "Gradle 밖 검사·실행 스크립트",
|
|
"src": "Gradle 루트",
|
|
# 파일
|
|
".gitattributes": "Git 설정",
|
|
".gitignore": "Git 설정",
|
|
".lycheeignore": "링크 검사(lychee)가 건너뛸 URL. lychee는 저장소 루트의 이 이름만 읽는다",
|
|
".tool-versions": "JDK 버전 고정",
|
|
".trivyignore.yaml": "취약점 검사 예외",
|
|
"AGENTS.md": "규칙 정본이자 작업 지도",
|
|
"CLAUDE.md": "Claude Code 진입점(AGENTS.md를 가져온다)",
|
|
"README.md": "저장소 소개",
|
|
"compose.yaml": "개발 환경(하나뿐)",
|
|
"renovate.json": "의존성 갱신 봇 설정",
|
|
"testcontainers.properties.example": "Testcontainers 로컬 설정 예",
|
|
}
|
|
|
|
# src/ 바로 아래: 계층·조립 leaf, Gradle 루트 표준 폴더와 빌드 파일. 계층이 아닌 라이브러리(메시징·gRPC)는
|
|
# 2026-11-08에 별도 repo로 나갔다(docs/work/reference/related-repos.md). 그 자리(platforms)는 다시 두지 않는다.
|
|
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": "조립 루트",
|
|
# 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 the map in "
|
|
"AGENTS.md 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())
|