build-logic/AGENTS.md는 「저장소 루트(`ca.repository.root`)는 이 두 레인에만 준다」고 적는다. 실제로 루트를 주는 것은 build-logic convention이 아니라 leaf `build.gradle`의 레인 선언(`systemProperty`)이다. 지금은 app-bootstrap의 `documentContractTest`·`repositoryContractTest` 둘이지만, 다른 leaf의 document-contract 레인도 같은 방식으로 받을 수 있다. 그러면 「두 레인」은 틀린 말이 된다. 태그 두 개로 범위를 적고, 주는 쪽이 그 leaf의 `build.gradle`이라고 적는다. 검증: scripts/verify.sh docs(노트북) rc=0. 이 문장을 읽는 시험은 없다 (git grep 'build-logic/AGENTS.md' -- '*.java': 0건). Refs: round9 리뷰 기록 5절 10번(r9-be 그룹 C)
5.7 KiB
5.7 KiB
build-logic — Gradle 정책 권위
registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 적는다. build-logic/, settings.gradle, build.gradle, gradle/modules.json을 고칠 때 읽는다. 루트 AGENTS.md HARD-STOP 5가 이 문서보다 먼저다. 게이트 고르기와 실행 위치는 docs/work/reference/gates.md다.
정본 넷
gradle/modules.json: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge, 그리고 별도 repo 라이브러리 edge(맨 위library_groups, 행마다allowed_libraries. 계층 leaf 행은 비워 둔다. 설명은gradle/README.md). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은allowed_dependencies가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(verifyDocumentedLeafCount)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와build.gradle을 정규식으로 훑는 파서였다.settings.gradle:ca.architecture-registry설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은verifyCleanArchitectureDependencies가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다.build-logic/: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(strictTestLanes). leaf는ca.java-library·ca.spring-library·ca.platform-module중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다.ca.architecture가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다.build.gradle: 루트 라이프사이클(ci,prCheck,mainCheck,integrationCheck,performanceCheck,releaseCheck,qualityCheck,configContractCheck)과 그것을 workflow job에 묶는strictLaneStages, 버전·리비전.
저장소 파일을 읽는 테스트
- 테스트가 저장소 파일을 읽으면 그 파일을 그 leaf의 test task
inputs로 선언한다. - 저장소 문서와 대조하는 테스트는
mainStage()레인(document-contract태그)으로 leafmainCheck에서 돈다. - 문서가 아닌 저장소 파일(빌드 스크립트, workflow, Compose, 다른 leaf 소스)을 읽어야 merge 전에 막을 수 있는 계약은 그 파일만 입력으로 둔 별도 레인(app-bootstrap
repository-contract)에 둔다. - 저장소 루트(
ca.repository.root)는document-contract·repository-contract태그 레인에만, 그 leaf의build.gradle이 레인 선언의systemProperty로 준다. convention은 주지 않는다. 그래서 태그 없이 저장소를 읽는 테스트는test에서 실패한다. - 문서를 파싱해 대조하는 Gradle 검사는 두지 않는다. 문서 검사는 Gradle 밖
scripts/check-docs.py·scripts/check-work-docs.py다.
lane 캐시와 성능 lane
TEST·ARCHITECTURElane은 입력이 같으면 up-to-date·build cache를 쓴다.INTEGRATION·SYSTEM·PERFORMANCElane과mainStage()lane은 이미지·네트워크·시간·문서처럼 입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을 입력으로 선언해야 캐시가 거짓 통과를 내지 않는다.PERFORMANCElane은 상한을 매번 단언한다. 끄는 스위치가 없다. convention이 테스트 JVM에performance.assertions.enabled=true를 넣고, 빌드(-P·GRADLE_OPTS)나 lane이 다른 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(rejectSkipped를 따로 쓰지 않아도). 사람이 손으로 돌리는./gradlew performanceCheck와 workflow가 같은 상한을 단언한다.verifyEnvKeys는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의ca.config-contract다.
단계 job의 모양
verifyStrictLaneStages --dry-run(PR)은explicitOnly가 아닌 strict lane마다build.gradle의strictLaneStages가 선언한 단계 태스크 하나의 계획에 들어 있는지 본다(그래프 검사).- 단계마다 선언한 workflow job은 step의
run: ./gradlew <단계> <옵션>줄을 가지고(같은 job을 쓰는 단계는 선언한line대로 한 줄을 나눠 쓸 수 있다:./gradlew :integrationCheck :mainCheck --continue), 다른 steprun:도 셸 문법 없는./gradlew한 줄이나bash scripts/<이름>.sh한 줄이며, 선언 밖의if:, 선언한 조건이!cancelled()·always()가 아닌데needs:,continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 이 빌드 밖의working-directory가 없다. workflow는 선언한 이벤트로, 선언한 필터 한 줄만 달고 시작하고, PR 단계 job 하나가 이 검사를 돌린다(형식 검사, 셸을 해석하지 않는다). - 단계를 더하거나 job을 바꾸면
strictLaneStages의stage줄과 workflow를 같은 커밋에서 고친다.
테스트
./gradlew -p build-logic test --console=plain(저장소 루트에서). build-logic은 Spotless 대상이 아니다. 편집 훅도 이 폴더의 Java를 포맷하지 않는다.