From e13a29024fa89e11a3103740be32ca8bb5a72eff Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 13:09:05 +0900 Subject: [PATCH] =?UTF-8?q?ci(repo)!:=20=EC=B5=9C=EC=83=81=EC=9C=84=20?= =?UTF-8?q?=ED=8F=B4=EB=8D=94=20=ED=97=88=EC=9A=A9=20=EB=AA=A9=EB=A1=9D=20?= =?UTF-8?q?=EA=B2=80=EC=82=AC=EB=A5=BC=20=EB=8D=94=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 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. --- .github/workflows/ci-quality-gates.yml | 4 + CLAUDE.md | 2 +- docs/upgrade/2026-11-maturity-review.md | 7 +- docs/work/reference/decisions.md | 1 + docs/work/reference/gates.md | 4 +- scripts/check-repo-layout.py | 210 ++++++++++++++++++++++++ 6 files changed, 223 insertions(+), 5 deletions(-) create mode 100755 scripts/check-repo-layout.py diff --git a/.github/workflows/ci-quality-gates.yml b/.github/workflows/ci-quality-gates.yml index 6d13fd90..d26c661c 100644 --- a/.github/workflows/ci-quality-gates.yml +++ b/.github/workflows/ci-quality-gates.yml @@ -57,6 +57,10 @@ jobs: run: ./gradlew :verifyStrictLaneStages --dry-run --stacktrace - name: Verify Compose profile contracts render exactly as declared run: bash scripts/verify-compose-profile-contracts.sh + # The repository root and src/ hold only the entries on the allow list (owner decision + # 2026-11-07): a new top-level folder is a decision, not a side effect of a feature commit. + - name: Refuse a top-level folder outside the allow list + run: python3 scripts/check-repo-layout.py optional-platforms: runs-on: ubuntu-latest diff --git a/CLAUDE.md b/CLAUDE.md index 89320333..d9d9826a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -54,7 +54,7 @@ brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이 ## 5. 코드만 보고는 헷갈리는 곳 -- **최상위 폴더는 정해진 것만 둔다.** 저장소 루트는 `compose.yaml`(개발 환경)·`compose/`(그 보조 파일)·`docs/`·`scripts/`·`src/`(Gradle 루트)다. `src/` 아래는 계층 leaf 폴더, `composition/`(조립), `platforms/`(들여온 제품: `messaging`·`grpc`·`grpc-advanced`와 optional 빌드 `optional-build`), Gradle 루트 표준(`build-logic`·`gradle`·`config`)이다. 테스트 환경 파일은 그 lane을 가진 leaf 안에 둔다. +- **최상위 폴더는 정해진 것만 둔다.** 저장소 루트는 `compose.yaml`(개발 환경)·`compose/`(그 보조 파일)·`docs/`·`scripts/`·`src/`(Gradle 루트)다. `src/` 아래는 계층 leaf 폴더, `composition/`(조립), `platforms/`(들여온 제품: `messaging`·`grpc`·`grpc-advanced`와 optional 빌드 `optional-build`), Gradle 루트 표준(`build-logic`·`gradle`·`config`)이다. 테스트 환경 파일은 그 lane을 가진 leaf 안에 둔다. `scripts/check-repo-layout.py`(PR 게이트)가 허용 목록 밖의 최상위 항목을 막는다. - **leaf 목록은 registry 하나다.** 문서는 leaf 개수를 적지 않는다(적힌 수는 leaf가 늘면 틀린다). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 registry의 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. - **`src/platforms/messaging/*`는 Clean Architecture 계층이 아니다.** 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다. `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 이 애플리케이션은 `adapter:outbound:messaging`의 bridge로만 닿는다. 이유와 지역 규칙은 `src/platforms/messaging/CLAUDE.md`다. - **`composition:*` leaf는 조립만 한다.** outbox relay, 멱등성 executor, durable operation처럼 bootstrap에서 떼어 낸 조립이다. 각각 `runtimeOnly` 한 줄로 고른다. diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index cbf54325..5a5f3ebf 100644 --- a/docs/upgrade/2026-11-maturity-review.md +++ b/docs/upgrade/2026-11-maturity-review.md @@ -132,9 +132,10 @@ | # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 | |---|---|---|---|---| | B-49 | 샘플 모듈 삭제: `src/sample-portfolio`, `src/Dockerfile.sample`, registry `sample-portfolio` 행, 루트 `build.gradle`의 샘플 태스크·단계(`sampleWebContractCheck`, `:sample-portfolio:*` 의존, strict lane 단계 `:sample-portfolio:check`), `ci-quality-gates.yml`의 `sample-portfolio` job, `SampleRuntimeDefaultsContractTest`, spotbugs 제외의 샘플 클래스. 샘플에만 있던 검사(OpenAPI 스냅숏 `openapiCheckSnapshot`, Date 헤더, 가상 스레드 MDC 전파)도 함께 없어졌다 | 샘플을 고쳐 쓰던 서비스: 병합 때 "수정 대 삭제" 충돌. 샘플을 이미 지운 서비스: 충돌 없음 | 샘플을 이미 지웠으면 할 일 없음. 고쳐 쓰고 있으면 자기 leaf로 옮기고 registry 행·빌드 줄을 자기 것으로 둔다. 위 검사가 필요하면 자기 기능 leaf에 둔다 | `ab5982e9` | -| B-50 | `infra/`에서 15개 삭제. 쓰는 곳이 없던 12개(`infra/httpclient/**`, `infra/jpa/postgres/README.md`, `infra/jpa/toxiproxy/`, `infra/messaging/{kafka,postgres,toxiproxy,tls}/`, `infra/notification/toxiproxy/`)와 운영 인프라 셋(`infra/fileserver/nginx/nginx.conf`, `infra/fileserver/kubernetes/pvc-certification-job.yaml`, `infra/jpa/roles/runtime-roles.sql`). `release.yml`의 `fileserver-pvc-certification` job도 지웠고, fileserver 지원 표에서 "Kubernetes ReadWriteOnce PVC — Limited" 주장을 「주장하지 않음」으로 옮겼다 | 그 파일을 배포에 쓰던 서비스: 병합이 파일을 지운다. 고쳐 쓰던 서비스: "수정 대 삭제" 충돌 | 그 파일은 자기 인프라 repo로 옮긴다. 지켜야 할 조건은 `docs/fileserver/operations.md` 「운영 환경이 지켜야 할 조건」, `docs/fileserver/storage-certification.md`, `docs/jpa/security.md` 「역할과 권한」·「서버 설정」에 있다 | 커밋 「쓰지 않는 파일과 운영 인프라 파일을 지운다」 | -| B-51 | compose 정리. 루트 `docker-compose.yml`·`docker-compose.local.yml`·`docker-compose.infra.yml`을 개발 환경 `compose.yaml` 하나로 합쳤다(app은 `local` 런타임, 뒷단 서비스는 capability profile `jpa`·`redis`·`kafka`·`mongo`·`objectstorage`·`auth`·`mail`). 보조 파일은 `compose/`(keycloak realm·entrypoint, minio init, Redis ACL, mailpit 인증서 폴더). 테스트 lane fixture는 그 lane을 가진 leaf로 옮겼다: `docker-compose.dev.yml`·`docker-compose.prod-smoke.yml`·`docker-compose.tls.yml`·fileserver overlay·smoke 스크립트·스키마 적용 스크립트·lane 계약 JSON(`src/config/runtime/compose-profile-contracts.json`) → `src/app-bootstrap/compose-lanes/`, Redis topology compose → `src/adapter/outbound/redis-sdk/compose/`, NFS compose → `src/adapter/outbound/fileserver/compose/nfs/`. `infra/`는 없어졌다. lane 계약의 `composeProfile`(문자열)은 `composeProfiles`(목록)로 바뀌었고 `appMemoryLimit`이 생겼다. smoke는 lane 중 컨테이너가 재시작하거나 메모리로 죽으면 실패한다. `scripts/bootstrap-local.sh`는 인자를 받지 않는다 | `docker compose -f docker-compose.yml -f docker-compose.local.yml …`을 쓰던 스크립트·문서가 "no such file"로 실패. 옛 compose 파일에 서비스를 더했으면 수정 대 삭제 충돌. lane 계약을 고쳐 쓰던 서비스는 `composeProfile` 키를 smoke 스크립트가 읽지 않는다 | 명령을 `docker compose …`(루트 `compose.yaml`)와 profile로 바꾼다. 더한 서비스는 `compose.yaml`에 capability profile을 달아 옮기고, lane 전용이면 `src/app-bootstrap/compose-lanes/lane-services.yaml`에 둔다. 경로를 적은 workflow·문서를 위 새 경로로 고친다 | 커밋 「compose 파일을 개발 환경 하나와 lane fixture로 나눈다」 | -| B-52 | `src/` 배치 정리. 들여온 플랫폼 넷을 `src/platforms/` 아래로 옮겼다: `src/messaging` → `src/platforms/messaging`, `src/grpc` → `src/platforms/grpc`, `src/grpc-advanced` → `src/platforms/grpc-advanced`, `src/optional-platforms` → `src/platforms/optional-build`(빌드 이름 `optional-platforms`는 그대로). registry `source_path`만 바뀌고 Gradle 경로(`:messaging:*`, `:grpc:*`)는 그대로다. optional 빌드는 `./gradlew -p platforms/optional-build …`로 부른다. `src/config/`에서 기능 하나가 주인인 데이터를 그 leaf의 `release/`로 옮겼다: `config/jpa/*` → `adapter/outbound/persistence-jpa/release/`, `config/messaging/**` → `adapter/outbound/messaging/release/`, `config/mongodb/release-contracts.json` → `adapter/outbound/persistence-mongo/release/` | `-p optional-platforms`를 부르는 workflow·스크립트가 "Project directory … does not exist"로 실패. 옮긴 폴더를 고쳐 쓰던 서비스는 이름 바뀜 충돌(Git이 이동으로 알아보면 자동 병합). `rootProject.file('config/jpa/…')`처럼 옛 경로를 읽던 자기 빌드 줄은 파일 없음 | workflow·스크립트의 `-p`와 경로를 새 위치로 고친다. 자기 leaf를 `src/messaging` 아래에 더했다면 `src/platforms/messaging` 아래로 옮기고 registry `source_path`를 고친다 | 커밋 「들여온 플랫폼을 src/platforms 아래로 묶는다」 | +| B-50 | `infra/`에서 15개 삭제. 쓰는 곳이 없던 12개(`infra/httpclient/**`, `infra/jpa/postgres/README.md`, `infra/jpa/toxiproxy/`, `infra/messaging/{kafka,postgres,toxiproxy,tls}/`, `infra/notification/toxiproxy/`)와 운영 인프라 셋(`infra/fileserver/nginx/nginx.conf`, `infra/fileserver/kubernetes/pvc-certification-job.yaml`, `infra/jpa/roles/runtime-roles.sql`). `release.yml`의 `fileserver-pvc-certification` job도 지웠고, fileserver 지원 표에서 "Kubernetes ReadWriteOnce PVC — Limited" 주장을 「주장하지 않음」으로 옮겼다 | 그 파일을 배포에 쓰던 서비스: 병합이 파일을 지운다. 고쳐 쓰던 서비스: "수정 대 삭제" 충돌 | 그 파일은 자기 인프라 repo로 옮긴다. 지켜야 할 조건은 `docs/fileserver/operations.md` 「운영 환경이 지켜야 할 조건」, `docs/fileserver/storage-certification.md`, `docs/jpa/security.md` 「역할과 권한」·「서버 설정」에 있다 | `a025f244` | +| B-51 | compose 정리. 루트 `docker-compose.yml`·`docker-compose.local.yml`·`docker-compose.infra.yml`을 개발 환경 `compose.yaml` 하나로 합쳤다(app은 `local` 런타임, 뒷단 서비스는 capability profile `jpa`·`redis`·`kafka`·`mongo`·`objectstorage`·`auth`·`mail`). 보조 파일은 `compose/`(keycloak realm·entrypoint, minio init, Redis ACL, mailpit 인증서 폴더). 테스트 lane fixture는 그 lane을 가진 leaf로 옮겼다: `docker-compose.dev.yml`·`docker-compose.prod-smoke.yml`·`docker-compose.tls.yml`·fileserver overlay·smoke 스크립트·스키마 적용 스크립트·lane 계약 JSON(`src/config/runtime/compose-profile-contracts.json`) → `src/app-bootstrap/compose-lanes/`, Redis topology compose → `src/adapter/outbound/redis-sdk/compose/`, NFS compose → `src/adapter/outbound/fileserver/compose/nfs/`. `infra/`는 없어졌다. lane 계약의 `composeProfile`(문자열)은 `composeProfiles`(목록)로 바뀌었고 `appMemoryLimit`이 생겼다. smoke는 lane 중 컨테이너가 재시작하거나 메모리로 죽으면 실패한다. `scripts/bootstrap-local.sh`는 인자를 받지 않는다 | `docker compose -f docker-compose.yml -f docker-compose.local.yml …`을 쓰던 스크립트·문서가 "no such file"로 실패. 옛 compose 파일에 서비스를 더했으면 수정 대 삭제 충돌. lane 계약을 고쳐 쓰던 서비스는 `composeProfile` 키를 smoke 스크립트가 읽지 않는다 | 명령을 `docker compose …`(루트 `compose.yaml`)와 profile로 바꾼다. 더한 서비스는 `compose.yaml`에 capability profile을 달아 옮기고, lane 전용이면 `src/app-bootstrap/compose-lanes/lane-services.yaml`에 둔다. 경로를 적은 workflow·문서를 위 새 경로로 고친다 | `50cd7154` | +| B-52 | `src/` 배치 정리. 들여온 플랫폼 넷을 `src/platforms/` 아래로 옮겼다: `src/messaging` → `src/platforms/messaging`, `src/grpc` → `src/platforms/grpc`, `src/grpc-advanced` → `src/platforms/grpc-advanced`, `src/optional-platforms` → `src/platforms/optional-build`(빌드 이름 `optional-platforms`는 그대로). registry `source_path`만 바뀌고 Gradle 경로(`:messaging:*`, `:grpc:*`)는 그대로다. optional 빌드는 `./gradlew -p platforms/optional-build …`로 부른다. `src/config/`에서 기능 하나가 주인인 데이터를 그 leaf의 `release/`로 옮겼다: `config/jpa/*` → `adapter/outbound/persistence-jpa/release/`, `config/messaging/**` → `adapter/outbound/messaging/release/`, `config/mongodb/release-contracts.json` → `adapter/outbound/persistence-mongo/release/` | `-p optional-platforms`를 부르는 workflow·스크립트가 "Project directory … does not exist"로 실패. 옮긴 폴더를 고쳐 쓰던 서비스는 이름 바뀜 충돌(Git이 이동으로 알아보면 자동 병합). `rootProject.file('config/jpa/…')`처럼 옛 경로를 읽던 자기 빌드 줄은 파일 없음 | workflow·스크립트의 `-p`와 경로를 새 위치로 고친다. 자기 leaf를 `src/messaging` 아래에 더했다면 `src/platforms/messaging` 아래로 옮기고 registry `source_path`를 고친다 | `8d69e599` | +| B-53 | 새 PR 검사 `python3 scripts/check-repo-layout.py`(`ci-quality-gates.yml`): 저장소 루트와 `src/` 최상위의 추적 항목이 허용 목록 안에 있어야 하고, registry `source_path`가 허용된 `src/` 폴더 아래여야 한다 | 자기 최상위 폴더(예: `infra/`, `src/<서비스 전용 폴더>`)를 둔 서비스는 PR 게이트가 실패한다 | 그 폴더가 정말 필요하면 스크립트의 `ROOT_ALLOWED`·`SRC_ALLOWED`와 자기 `CLAUDE.md` 지도에 같은 변경으로 더한다. 아니면 그 내용을 주인 leaf나 `docs/`로 옮긴다 | 커밋 「최상위 폴더 허용 목록 검사를 더한다」 | ## 4. DB 마이그레이션 diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index bd60ed44..f083fff2 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -74,6 +74,7 @@ | 생성 명령 | JPA adapter를 만들지 않음(서비스 전용 persistence leaf가 기본), 생성된 쓰기 API는 역할 매핑 전 403 | 위임 | `1101` 15절(r2-10) | | `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` 4절(RR-01-02) | | 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 `@SystemCaller(reason)` 표시로 허용 | 위임 | `1103` 9.1절(RR-01-12), 10절 r5-b | +| 배치 규칙 검사 | 저장소 루트와 `src/` 최상위 허용 목록을 `scripts/check-repo-layout.py`로 PR에서 막는다. 리뷰 기준에도 넣는다(매뉴얼 보강 작업) | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 10.3절 | | `src/` 배치 | 들여온 플랫폼 넷(`messaging`, `grpc`, `grpc-advanced`, optional 빌드)을 `src/platforms/` 아래로 묶는다. registry `source_path`만 바꾸고 Gradle 경로는 그대로 둔다. `build-logic`·`gradle`·`config`는 Gradle 루트 표준이라 남기고, `composition`은 조립 계층이라 옮기지 않는다. `config/`에서 기능 하나가 주인인 데이터 파일은 그 leaf로 보낸다. Gradle 루트를 저장소 루트로 옮길지는 CI 재편 때 다시 본다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.1절 | | 개발 compose 파일 | 저장소 루트에 `compose.yaml` 하나. 뒷단 서비스는 capability 이름 profile로 고르고, 마운트하는 보조 파일은 `compose/`에 둔다. 테스트 lane fixture는 그 lane을 가진 leaf로 보낸다(compose lane → app-bootstrap `compose-lanes/`, Redis topology → redis-sdk, NFS → fileserver). `docker-compose.dev.yml`은 `dev` 배포 프로필이 뜨는지 보는 lane fixture로 app-bootstrap에 둔다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 | | 인프라 실행 파일 | nginx 설정, Kubernetes PVC job, DB 역할 SQL은 이 repo에서 지우고, 기능이 운영 환경에 요구하는 조건만 그 기능 문서에 적는다. 아무도 쓰지 않는 `infra/` 파일도 지운다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 | diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index aa8203a2..e70416e3 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -23,6 +23,7 @@ | `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 단계에 속하는가 | PR(두 빌드 각각) | `ci-quality-gates.yml`, optional 빌드는 `-p platforms/optional-build` | | `-p platforms/optional-build ci` | gRPC 플랫폼 빌드 | PR | `ci-quality-gates.yml` | | `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가(저장소 루트에서) | PR | `ci-quality-gates.yml` | +| `python3 scripts/check-repo-layout.py` | 저장소 루트와 `src/` 최상위에 허용 목록 밖의 항목이 없는가, registry 경로가 허용 폴더 안인가. 아무도 가리키지 않는 compose·스크립트 파일은 경고 | PR | `ci-quality-gates.yml` | | `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `integration-main.yml`: `./gradlew :mainCheck --continue --warning-mode=fail` | | `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `integration-main.yml`, optional 빌드도 | | `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | main·nightly | `integration-main.yml`, optional 빌드도. 5절 | @@ -81,7 +82,7 @@ python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':( | brief의 말 | 돌릴 것 | | --- | --- | -| pull request 단계 게이트 | (가)의 `# PR` 줄과 `verify-compose-profile-contracts.sh`, (나)에서 `pull_request`로 켜지는 것, (다) | +| pull request 단계 게이트 | (가)의 `# PR` 줄과 `verify-compose-profile-contracts.sh`·`check-repo-layout.py`, (나)에서 `pull_request`로 켜지는 것, (다) | | main 단계 | (가)의 `# main push` 줄과 `run-compose-runtime-smoke.sh`, (나)에서 main `push`로 켜지는 것 | | 라운드 끝 | 위 둘 전부와 (가)의 `# 태그` 두 줄 | @@ -112,6 +113,7 @@ cd src ./gradlew -p platforms/optional-build releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain cd .. bash scripts/verify-compose-profile-contracts.sh +python3 scripts/check-repo-layout.py bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json ``` diff --git a/scripts/check-repo-layout.py b/scripts/check-repo-layout.py new file mode 100755 index 00000000..805adb87 --- /dev/null +++ b/scripts/check-repo-layout.py @@ -0,0 +1,210 @@ +#!/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())