diff --git a/AGENTS.md b/AGENTS.md index 0509bd1b..e8451db0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,7 +99,8 @@ root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을 부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태 함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만 시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore` - 필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 세는 job이 + 필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches` + 없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이 부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job. (3) 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른 diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index be387166..9f230ba8 100644 --- a/docs/upgrade/2026-11-maturity-review.md +++ b/docs/upgrade/2026-11-maturity-review.md @@ -4,7 +4,7 @@ - 커밋: `34565130` High·P1 19건 · `1400dc15` 남은 발견·매뉴얼·생성 명령 · `5786126c` 남은 항목과 합친 뒤 결함 · `7ef8d0b4` 재리뷰 기록 · `bbe944bd` 재리뷰 결함 · `ecc74b7d` 2차 재리뷰 기록·이 안내 · `1885bf8d` 2차 재리뷰 결함 · `339cf8fd` 3차 확인 리뷰 기록 · `f40c03c6` 3차 확인 리뷰 Minor · `c2e55510` 마지막 확인 리뷰 기록 · - `2678955c` 테스트 코드 정적 분석(B-40) · `70fb80bf` 소유자가 다시 정한 기본값 3가지(늦은 멱등 완료 기록, `failure-retention` 기동 검사, workflow `cd`) · B4 성능 lane 단언 상시화(2026-11-06, B-43) · `paths` 필터 trigger를 단계 실행으로 세지 않음(2026-11-06 소유자 결정, B-36) — `docs(...)` 커밋은 문서만 바꾼다 + `2678955c` 테스트 코드 정적 분석(B-40) · `70fb80bf` 소유자가 다시 정한 기본값 3가지(늦은 멱등 완료 기록, `failure-retention` 기동 검사, workflow `cd`) · B4 성능 lane 단언 상시화(2026-11-06, B-43) · `paths` 필터 trigger를 단계 실행으로 세지 않음(2026-11-06 소유자 결정, B-36) · 태그 push·`release` workflow는 `releaseCheck`에만 셈(2026-11-07 소유자 결정, B-36) — `docs(...)` 커밋은 문서만 바꾼다 - 근거 문서: `docs/reviews/2026-11-01-maturity-review/README.md` 13~16절, `docs/reviews/2026-11-03-rereview/README.md` 4·6·8~13절, 각 커밋의 `BREAKING CHANGE:` 꼬리말 - 아래 표의 각 줄은 위 범위의 diff와 코드로 확인했다. 확인하지 못한 것은 그 자리에 "확인 못 함"으로 적었고 9절에 @@ -107,7 +107,7 @@ |---|---|---|---|---| | B-34 | 템플릿 패키지 규칙(ArchUnit): `FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`, `TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`. 템플릿 이름: application `usecase command query capability transaction security tenant observability secret messaging outbox idempotency operation lease lock cache realtime notification fileserver objectstorage`, domain `identifier stereotype` | 기능 패키지 이름이 이 목록과 겹치거나(예: `domain.lock`), 업무 코드를 템플릿 패키지(예: `application.usecase.*`)에 두고 기능 패키지를 import하면 `:app-bootstrap:architectureTest` 실패 | 기능 패키지 이름을 바꾸고, 업무 코드를 `dev.caskeleton.application.`로 옮긴다. 규칙 정본은 `src/application-core/CLAUDE.md` "Package ownership" | `5786126c`, r9 · `src/app-bootstrap/src/test/.../TemplatePackageOwnership.java`(표와 대조: `TemplatePackageOwnershipDocumentTest`) | | B-35 | JPA 규칙: 양방향 연관은 한쪽에서만 매핑(`mappedBy`), notification·fileserver 저장소 엔티티는 그 leaf 안에서만, `@Version` 엔티티의 bulk update는 version을 올려야 함 | 위반 엔티티·쿼리가 있으면 architectureTest 실패 | 매핑·쿼리를 고친다 | `34565130`, `1400dc15`, `bbe944bd` · `src/app-bootstrap/src/architectureTest/.../JpaProductionArchitectureTest.java` | -| B-36 | 빌드 검사 강화: `modules.json`에 없는 `build.gradle`이 있으면 `verifyCleanArchitectureDependencies` 실패. `verifyStrictLaneStages --dry-run`은 모든 strict lane이 workflow가 실행하는 단계(`:ci` `:sample-portfolio:check` `:mainCheck` `:integrationCheck` `:performanceCheck` `:releaseCheck`)에 속해야 하고 `.github/workflows`를 읽는다. 명령의 빌드는 `working-directory`(단계·job·workflow `defaults`)에서 시작해 같은 `run:` 셸이 그 앞에서 실행한 `cd <상대 경로>`(`cd src && ./gradlew …`, `cd src; ./gradlew …`, 앞 줄의 `cd src`)를 따라간 뒤 `-p`를 붙인 디렉터리로 정하고(`70fb80bf`(2026-11-04 소유자 결정)), `workflow_dispatch`로만 시작하는 workflow의 명령은 세지 않으며, 축약한 `-x`도 Gradle처럼 맞춰 본다(RR2-04-04). 붙여 쓴 `-x`·`-p`도 Gradle처럼 읽는다(RR3-04-02). `run:` 스크립트를 bash 문법으로 읽고(heredoc·여러 줄 문자열·함수 본문 안의 `cd`는 따라가지 않음), 세지 않는 명령은 이유를 셋으로 나눠 적는다(r10). (1) 실패해도 단계가 실패하지 않을 수 있음: `\|\| exit <0 아닌 값>` 밖의 `\|\|`(`\|\| true` 등), pipefail 없는 파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤, `exit 0` 하는 `EXIT`·`ERR` trap 뒤. (2) 돌지 않을 수 있음: `\|\|` 뒤, 마지막이 아닌 `&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec <명령>`·`set -n` 뒤, 조건부이거나 부른 함수 안의 `exit 0`·인자 없는 `exit`·값을 모르는 `exit`·`exec`·`set -n` 뒤, 요청으로만 시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment`·`types: [labeled]`인 `pull_request`·`workflow_run` 등; `push`·`pull_request`·`pull_request_target`·`merge_group`·`schedule`·`release`는 센다), change trigger가 모두 `paths`·`paths-ignore` 필터를 단 workflow(그 경로 밖 변경에는 돌지 않는다, 2026-11-06 소유자 결정. `branches`·`tags` 필터는 보지 않는다), 세는 job이 `uses: ./.github/workflows/<파일>`로 부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job(자기 `if:`가 `always()`·`!cancelled()`면 센다). (3) 실패하면 단계도 실패하지만 검사가 읽지 않음: `\|\| exit 1`·`\|\| { …; exit 1; }`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른 명령의 인자인 `gradlew`(`timeout 60 ./gradlew`), `bash`·`sh`가 아닌 `shell:`, `shell:` 없이 Windows일 수 있는 runner(Windows 라벨, `${{ matrix.os }}` 같은 식, `linux`·`macos` 라벨 없는 self-hosted)에서 도는 단계 — 기본 셸이 `pwsh`다(Linux·macOS runner의 기본은 `bash -e`, `container:` job은 `sh -e`이고 둘은 같게 읽는다). Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-m`·`-v`·`--version`·`-h`·`-?`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는 짧은 옵션 묶음(`-mx`)·값을 받지 않는 옵션에 붙인 값(`-m=yes`)도 세지 않는다. 판독기의 Gradle 옵션 표는 `GradleCommandLineTest`가 build-logic을 돌리는 Gradle의 `--help`와 대조하므로, Gradle을 올려 옵션이 늘면(9.2의 `--task-graph`) 그 테스트가 실패한다. 단계를 부르지만 세지 않은 명령은 다른 빌드로 읽힌 것까지 실패 메시지에 이유와 함께 적는다(r9). `verifyEnvKeys`: lane 계약 json의 `APP_` 밖 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_`이거나 `secret://…/`가 가리키는 변수여야 하고, 레지스트리 `property:` 행은 그 property가 설정 metadata에 있어야 읽히는 것으로 친다(`@ConditionalOnProperty`로만 읽는 스위치는 `META-INF/additional-spring-configuration-metadata.json`에 선언, RR2-04-05). SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다. `working-directory: src`도 `cd src`도 없이 `./gradlew`를 부르는 자기 workflow 단계는 실행으로 세지 않는다. 확실히 따라갈 수 없는 디렉터리 이동(`cd "$VAR"`, `cd -`, `cd ~`, 절대 경로, `pushd`, `if`/`for`/`case`·`{ }`·서브셸 안의 `cd`, `||`·`|`로 이은 `cd`, 다른 명령과 `&&`로 묶인 `cd` 다음 줄) 뒤의 명령도 세지 않고, 실패 메시지에 그 명령과 이유를 적는다. 단계를 `./gradlew ci \| tee log`(기본 셸), `./gradlew ci \|\| true`, `./gradlew ci \|\| exit 1`, `if ./gradlew ci; then` 같은 모양으로만 부르거나, 조건부 `exit 0` 뒤, `-v`·`--help`를 붙여, 요청형 trigger·`paths` 필터 trigger로만 시작하는 workflow·호출되지 않는 `workflow_call` workflow·조건부 job을 `needs`로 기다리는 job·`shell:` 없는 Windows runner에서만 부르는 자기 workflow도 실패한다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. 단계를 부르는 workflow 명령에 `working-directory`를 두거나 같은 셸에서 `cd <상대 경로>`로 옮긴 뒤 부른다. 단계 명령은 혼자 한 줄로 두고, 로그를 파이프로 남기려면 `shell: bash`나 앞 줄 `set -o pipefail`을 둔다. Windows runner에서는 `shell: bash`를 둔다. 단계는 매 push·pull request·schedule에 도는(`paths`·`paths-ignore` 필터 없는) workflow와 job에서, 재사용 workflow라면 그런 job이 조건 없이 부르게 한다. Gradle을 올려 `GradleCommandLineTest`가 실패하면 새 옵션을 값 옵션·플래그·작업 없이 끝나는 옵션 중 하나로 판독기 표에 넣는다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c`, `70fb80bf`(2026-11-04 소유자 결정), r9, r10(RR6-04-01~06), RR7-05-01(2026-11-06 소유자 결정) · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.java`, `.../strictlane/WorkflowGradleInvocations.java`, `.../strictlane/ShellScript.java`, `.../strictlane/GradleCommandLineTest.java`(test), `.../quality/QualityConventionsPlugin.java`, `src/build.gradle` | +| B-36 | 빌드 검사 강화: `modules.json`에 없는 `build.gradle`이 있으면 `verifyCleanArchitectureDependencies` 실패. `verifyStrictLaneStages --dry-run`은 모든 strict lane이 workflow가 실행하는 단계(`:ci` `:sample-portfolio:check` `:mainCheck` `:integrationCheck` `:performanceCheck` `:releaseCheck`)에 속해야 하고 `.github/workflows`를 읽는다. 명령의 빌드는 `working-directory`(단계·job·workflow `defaults`)에서 시작해 같은 `run:` 셸이 그 앞에서 실행한 `cd <상대 경로>`(`cd src && ./gradlew …`, `cd src; ./gradlew …`, 앞 줄의 `cd src`)를 따라간 뒤 `-p`를 붙인 디렉터리로 정하고(`70fb80bf`(2026-11-04 소유자 결정)), `workflow_dispatch`로만 시작하는 workflow의 명령은 세지 않으며, 축약한 `-x`도 Gradle처럼 맞춰 본다(RR2-04-04). 붙여 쓴 `-x`·`-p`도 Gradle처럼 읽는다(RR3-04-02). `run:` 스크립트를 bash 문법으로 읽고(heredoc·여러 줄 문자열·함수 본문 안의 `cd`는 따라가지 않음), 세지 않는 명령은 이유를 셋으로 나눠 적는다(r10). (1) 실패해도 단계가 실패하지 않을 수 있음: `\|\| exit <0 아닌 값>` 밖의 `\|\|`(`\|\| true` 등), pipefail 없는 파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤, `exit 0` 하는 `EXIT`·`ERR` trap 뒤. (2) 돌지 않을 수 있음: `\|\|` 뒤, 마지막이 아닌 `&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec <명령>`·`set -n` 뒤, 조건부이거나 부른 함수 안의 `exit 0`·인자 없는 `exit`·값을 모르는 `exit`·`exec`·`set -n` 뒤, 요청으로만 시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment`·`types: [labeled]`인 `pull_request`·`workflow_run` 등; `push`·`pull_request`·`pull_request_target`·`merge_group`·`schedule`·`release`는 센다), change trigger가 모두 `paths`·`paths-ignore` 필터를 단 workflow(그 경로 밖 변경에는 돌지 않는다, 2026-11-06 소유자 결정), `releaseCheck` 밖의 단계에서는 태그 push(`branches` 없는 `tags`·`tags-ignore`)나 `release`로만 시작하는 workflow(2026-11-07 소유자 결정), 세는 job이 `uses: ./.github/workflows/<파일>`로 부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job(자기 `if:`가 `always()`·`!cancelled()`면 센다). (3) 실패하면 단계도 실패하지만 검사가 읽지 않음: `\|\| exit 1`·`\|\| { …; exit 1; }`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른 명령의 인자인 `gradlew`(`timeout 60 ./gradlew`), `bash`·`sh`가 아닌 `shell:`, `shell:` 없이 Windows일 수 있는 runner(Windows 라벨, `${{ matrix.os }}` 같은 식, `linux`·`macos` 라벨 없는 self-hosted)에서 도는 단계 — 기본 셸이 `pwsh`다(Linux·macOS runner의 기본은 `bash -e`, `container:` job은 `sh -e`이고 둘은 같게 읽는다). Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-m`·`-v`·`--version`·`-h`·`-?`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는 짧은 옵션 묶음(`-mx`)·값을 받지 않는 옵션에 붙인 값(`-m=yes`)도 세지 않는다. 판독기의 Gradle 옵션 표는 `GradleCommandLineTest`가 build-logic을 돌리는 Gradle의 `--help`와 대조하므로, Gradle을 올려 옵션이 늘면(9.2의 `--task-graph`) 그 테스트가 실패한다. 단계를 부르지만 세지 않은 명령은 다른 빌드로 읽힌 것까지 실패 메시지에 이유와 함께 적는다(r9). `verifyEnvKeys`: lane 계약 json의 `APP_` 밖 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_`이거나 `secret://…/`가 가리키는 변수여야 하고, 레지스트리 `property:` 행은 그 property가 설정 metadata에 있어야 읽히는 것으로 친다(`@ConditionalOnProperty`로만 읽는 스위치는 `META-INF/additional-spring-configuration-metadata.json`에 선언, RR2-04-05). SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다. `working-directory: src`도 `cd src`도 없이 `./gradlew`를 부르는 자기 workflow 단계는 실행으로 세지 않는다. 확실히 따라갈 수 없는 디렉터리 이동(`cd "$VAR"`, `cd -`, `cd ~`, 절대 경로, `pushd`, `if`/`for`/`case`·`{ }`·서브셸 안의 `cd`, `||`·`|`로 이은 `cd`, 다른 명령과 `&&`로 묶인 `cd` 다음 줄) 뒤의 명령도 세지 않고, 실패 메시지에 그 명령과 이유를 적는다. 단계를 `./gradlew ci \| tee log`(기본 셸), `./gradlew ci \|\| true`, `./gradlew ci \|\| exit 1`, `if ./gradlew ci; then` 같은 모양으로만 부르거나, 조건부 `exit 0` 뒤, `-v`·`--help`를 붙여, 요청형 trigger·`paths` 필터 trigger로만 시작하는 workflow·`releaseCheck`가 아닌 단계를 태그 push·`release`로만 시작하는 workflow·호출되지 않는 `workflow_call` workflow·조건부 job을 `needs`로 기다리는 job·`shell:` 없는 Windows runner에서만 부르는 자기 workflow도 실패한다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. 단계를 부르는 workflow 명령에 `working-directory`를 두거나 같은 셸에서 `cd <상대 경로>`로 옮긴 뒤 부른다. 단계 명령은 혼자 한 줄로 두고, 로그를 파이프로 남기려면 `shell: bash`나 앞 줄 `set -o pipefail`을 둔다. Windows runner에서는 `shell: bash`를 둔다. 단계는 매 push·pull request·schedule에 도는(`paths`·`paths-ignore` 필터 없는) workflow와 job에서(`releaseCheck`만 태그 push·`release` workflow에서), 재사용 workflow라면 그런 job이 조건 없이 부르게 한다. Gradle을 올려 `GradleCommandLineTest`가 실패하면 새 옵션을 값 옵션·플래그·작업 없이 끝나는 옵션 중 하나로 판독기 표에 넣는다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c`, `70fb80bf`(2026-11-04 소유자 결정), r9, r10(RR6-04-01~06), RR7-05-01(2026-11-06 소유자 결정), 태그·릴리스 workflow(2026-11-07 소유자 결정) · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.java`, `.../strictlane/WorkflowGradleInvocations.java`, `.../strictlane/ShellScript.java`, `.../strictlane/GradleCommandLineTest.java`(test), `.../quality/QualityConventionsPlugin.java`, `src/build.gradle` | | B-37 | app-bootstrap 테스트 lane 분리: 저장소 파일을 읽는 테스트는 태그 `document-contract`(main 단계) 또는 `repository-contract`(`check`)여야 하고, 일반 `test` lane에는 `ca.repository.root`가 없다 | app-bootstrap에 둔 자기 테스트가 저장소 파일을 읽으면 `test`에서 실패 | 태그를 단다 | `1400dc15` · `src/app-bootstrap/build.gradle` | | B-40 | 테스트 코드 정적 분석 `testQualityCheck`: SpotBugs·FindSecBugs를 main 밖 모든 source set(test, testFixtures, integrationTest, systemTest 등)에 돌린다. 테스트용 제외 목록은 `config/spotbugs/exclude-test.xml`(보안 범주·내부 상태 노출·생성자 예외·반환값 null 역참조·아키텍처 위반 fixture). 분석 classpath가 그 source set의 runtime classpath로 넓어졌고, 분석이 불완전하면(빠진 클래스) 실패한다. main 빌드는 `mainCheck`(`qualificationCheck`), optional 빌드는 `ci` | 자기 테스트 코드의 SpotBugs 발견(예: `CountDownLatch.await` 반환값 무시, 공유 변수 비원자 쓰기, 닫지 않은 `Statement`)이 main 단계를 막는다. 테스트 classpath에 없는 타입을 참조하면 `SpotBugs analysis incomplete` | 고치거나, 클래스·메서드로 좁힌 Match를 이유와 함께 `exclude-test.xml`에 더한다. 빠진 타입은 그 테스트 suite 의존성에 넣는다 | `2678955c` · `src/build-logic/.../quality/QualityConventionsPlugin.java`, `src/config/spotbugs/exclude-test.xml`, `src/build.gradle` | | B-42 | shared-contract 패키지 규칙 `SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`가 실제로 검사한다. 대상은 `dev.caskeleton.shared..`뿐이고, 허용은 목록의 패키지(`concurrency digest error metrics observability ratelimit request response retry runtime security tracing`)와 그 아래, 뿌리 패키지에는 `package-info`만이다. 전에는 뿌리를 허용 목록에 넣고 접두어로 비교해서 모듈 안은 아무것도 잡지 못했고, 다른 leaf의 `..shared..` 패키지를 잡았다 | `dev.caskeleton.shared`에 목록에 없는 패키지나 뿌리 클래스를 둔 파생 서비스는 architectureTest 실패. 다른 leaf의 `shared` 패키지는 더는 걸리지 않는다 | 업무 개념이면 그것을 소유하는 모듈로 옮긴다. 운영 계약이면 `ForbiddenApiArchitectureTest.SHARED_CONTRACT_PACKAGES`와 shared-contract CLAUDE.md 「Responsibility」에 함께 더한다 | r10 · `src/app-bootstrap/src/architectureTest/.../ForbiddenApiArchitectureTest.java`, `SharedContractPackageRuleTest.java` | diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index d28c6a33..ad51da98 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -177,6 +177,7 @@ | 에이전트가 원칙에서 바로 정한 것 | Kafka 주소 키 하나, composition이 persistence-jpa를 함께 가져옴 등 7건 | 기본값 | `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」 끝 목록 | | 묶음별 기본값 | 각 라운드 처리 표의 「결정」 칸(예: SES replay 창 1h, Retry-After 30) | 기본값 | `1101` 13·14·16절, `1103` 6·10·12·15·16·17절 표 | | 경로 필터 workflow와 단계 검사 | `paths:`·`paths-ignore:` trigger만 있는 workflow는 strict lane 단계 실행으로 세지 않는다 | 소유자 | `1103` 18.4절(RR7-05-01), 2026-11-06 | +| 태그·릴리스 workflow와 단계 검사 | `push`에 `tags:`만 있거나(`branches`·`paths` 없이) `release` trigger만 있는 workflow는 `releaseCheck` 단계에서만 실행으로 센다. 다른 단계(pull request·main·nightly)로는 세지 않는다 | 소유자 | `1103` 18.4절(round7 05 Declined ①), 2026-11-07 | ## 3. 새 결정을 기록하는 법 diff --git a/src/README.md b/src/README.md index d6eeec83..77e93d41 100644 --- a/src/README.md +++ b/src/README.md @@ -28,7 +28,7 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇 | `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 | | `integrationCheck` | 선언된 strict integration lane(sample 포함)을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 | | `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(`-Pperformance.assertions.enabled`가 `true`가 아니면 실패, skip된 테스트가 있어도 실패). `integration-main.yml` `performance-check`가 main·nightly에 같은 명령으로 돌림 | -| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`:sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-v`·`--help` 등)과, 실패해도 단계가 실패하지 않을 수 있거나(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) 돌지 않을 수 있거나(조건부 `exit 0` 뒤, 요청으로만 시작하는 workflow, `paths` 필터로만 시작하는 workflow 등) 검사가 읽지 않는(`\|\| exit 1`, `{ }` 안 등) 명령은 실행으로 세지 않는다. 자세한 목록은 `build-logic/README.md`. PR 게이트가 돌림 | +| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`:sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-v`·`--help` 등)과, 실패해도 단계가 실패하지 않을 수 있거나(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) 돌지 않을 수 있거나(조건부 `exit 0` 뒤, 요청으로만 시작하는 workflow, `paths` 필터로만 시작하는 workflow, `releaseCheck` 밖의 단계를 태그 push·`release`로만 시작하는 workflow 등) 검사가 읽지 않는(`\|\| exit 1`, `{ }` 안 등) 명령은 실행으로 세지 않는다. 자세한 목록은 `build-logic/README.md`. PR 게이트가 돌림 | | `ci` | PR 게이트: 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` | | `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + sample web 계약 + sample 전체 기동(`:sample-portfolio:systemTest`) + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) | | `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) | diff --git a/src/build-logic/README.md b/src/build-logic/README.md index d6f54997..279ff8c3 100644 --- a/src/build-logic/README.md +++ b/src/build-logic/README.md @@ -16,7 +16,7 @@ capability, and the files it reads are declared as that test task's inputs. | `ca.java-library` / `ca.spring-library` / `ca.spring-config` | leaf-level composition of the Java/quality conventions for plain and Spring libraries | | `ca.platform-module` / `ca.grpc-platform-module` | what a vendored platform leaf (`messaging:*`, `grpc:*`, `grpc-advanced:*`) is: `java-library`, plus the gRPC BOM for the leaves that had it | | `ca.strict-test-lane` | the one "named tests ran, none skipped" mechanism: tagged / named / own-source-set `Test` lanes that fail when they execute nothing, miss a `requires` class, or (with `rejectSkipped`) skip anything. A `performance()` lane always rejects skips and runs with `performance.assertions.enabled=true`; a build (`-P`, `GRADLE_OPTS`) or lane that sets another value fails it before a test runs. `mainStage()` moves a tagged lane out of `test` into the leaf's `mainCheck`; `explicitOnly(reason)` keeps a lane that needs an outside input out of every aggregate, and the aggregate prints the reason. Extra test source sets are Gradle `jvm-test-suite` suites declared in the leaf (`testing { suites { … } }`); a lane named after its suite makes the suite's own `Test` task strict, and `ca.java-conventions` gives every suite the BOM's JUnit | -| `ca.strict-lane-stages` (root of each build with strict lanes: the main build and optional-platforms) | the other half of the lane mechanism: `verifyStrictLaneStages --dry-run` fails when a strict lane of that build that is not `explicitOnly` is in the task plan of no declared stage that a workflow executes, or when a declared stage is executed by no workflow. The workflows are read together (`WorkflowGradleInvocations.readAll`, so a reusable workflow is judged by its callers) and their `run:` scripts parsed as bash (`ShellScript`: quotes, comments, heredoc bodies, substitutions and compound commands are read as the shell reads them, so a `cd` in a heredoc or a string is data). A command does not count when Gradle runs no task with it — `--dry-run`/`-m` (also in a bundle such as `-qm`), `-v`/`--version`, `-h`/`-?`/`--help`, `--status`, `--stop`, `--foreground` (also in a bundle such as `-qv`) — or rejects it: a short-option bundle whose later letter takes a value (`-mx`: only the first letter of a bundle takes one), or a value given to an option that takes none (`-m=yes`). The reader follows Gradle 9.0's parser. `GradleCommandLineTest` holds its option tables to the `--help` of the Gradle that runs build-logic — an upgrade that adds an option, as 9.2 adds `--task-graph`, fails until the option is placed — and runs the launcher with each no-task option but `--stop` and `--foreground` (both return a daemon action, not a build, in Gradle's `BuildActionsFactory`); which options take a value was probed against 9.0.0 in round 9 and is not re-run. Nor does a command for another build count (the build a command starts is its step's `working-directory`, or the job's or workflow's `defaults.run.working-directory`, moved by each `cd ` the same `run:` shell surely ran before it — alone in its list, or before the command in the same `&&` list — then joined with `-p`; the plugin reads this build's own directory from where it sits under the repository that holds `.github/workflows`). Every other command that does not count gives one of three reasons. **Its failure may not fail its step**: `\|\| true`, `\|\| :` or any `\|\|` but `\|\| exit `, a pipe's left side without `pipefail` (on with `shell: bash` or a top-level `set -o pipefail`), `!`, `&`, an `if`/`while` condition, the part before `&&` of a list that is not the script's last command, after `set +e`, after a `trap` whose `EXIT` or `ERR` action may `exit` with status 0 (a bare `exit` keeps the status in an `EXIT` trap, not in an `ERR` one), and `continue-on-error`. **It may not run**: after `\|\|`, after `&&` in a list that is not the script's last command, inside `if`/`while`/`for`/`case` or a function body, after a top-level `exit`, `exec ` or `set -n`, after one elsewhere — in a compound command, an and-or list or a function the script calls — that may end the script with status 0 (`exit 0`, a bare `exit` other than right after `\|\|`, `exit "$code"`), replace it or stop it running commands (`set -o noexec`), under an `if:` other than `always()`/`success()`/`!cancelled()`, in a workflow that starts only on events someone or something asks for (`workflow_dispatch`, `repository_dispatch`, `issue_comment`, a pull request with `types: [labeled]`, `workflow_run`, …; `push`, `pull_request`, `pull_request_target`, `merge_group`, `schedule` and `release` count), in a workflow whose change-flow triggers all carry a `paths` or `paths-ignore` filter (a change outside those paths does not start it; owner decision 2026-11-06 — `branches` and `tags` filters are not read), in a reusable (`workflow_call`-only) workflow that no counted job calls with `uses: ./.github/workflows/`, and in a job that `needs`, directly or through other jobs, a job with such an `if:` or with `continue-on-error`, unless its own `if:` is `always()` or `!cancelled()`. **This check does not read it**, although its failure would fail the step (a false failure on purpose): `\|\| exit 1`, `\|\| { …; exit 1; }`, inside `{ }` or `( )`, `$( )`, `bash -c`, `gradlew` as another command's argument (`timeout 60 ./gradlew`), after a directory change the reader does not follow (`cd "$VAR"`, `cd -`, `cd ~`, an absolute path, `pushd`/`popd`, `builtin cd`, `eval`/`source`, a `cd` anywhere inside a compound command or a function body, one joined with `\|\|`, piped or in the background, and the lines after a `cd` that shares an `&&` list with other commands — not guessed), a step whose `shell:` is not `bash` or `sh`, and a step with no `shell:` in a job whose `runs-on` may be a Windows runner, whose default shell is `pwsh` (a Windows label, an expression such as `${{ matrix.os }}`, a self-hosted label set without `linux` or `macos`; Linux and macOS runners default to `bash -e` and a `container:` job to `sh -e`, which are read alike). An `exit` that fails the step — `exit 1`, or `cmd \|\| exit` — and one in an uncalled function, a `( )` subshell or `$( )` stop nothing after them from counting. The failure names every command that names the stage but does not execute it, with its reason or the other build it starts, and says to run the stage as `./gradlew` on a line of its own. A lane the command removes with `-x` is not covered — matched the way Gradle matches task and project names, abbreviations included (`TaskSelectors`, a copy of Gradle's internal `NameMatcher`). A `run:` input of a `uses:` step is not a command. The plan is Gradle's own; the workflows are read for their `run:` steps with YAML folding applied (review 2026-11-01 08-01, 2026-11-03 RR-06-03/04, 2026-11-04 RR2-04-04, owner decision 2026-11-04 on `cd`, RR5-02-01/02/03 in round 9, 2026-11-05 RR6-04-01..06, 2026-11-06 RR7-05-01) | +| `ca.strict-lane-stages` (root of each build with strict lanes: the main build and optional-platforms) | the other half of the lane mechanism: `verifyStrictLaneStages --dry-run` fails when a strict lane of that build that is not `explicitOnly` is in the task plan of no declared stage that a workflow executes, or when a declared stage is executed by no workflow. The workflows are read together (`WorkflowGradleInvocations.readAll`, so a reusable workflow is judged by its callers) and their `run:` scripts parsed as bash (`ShellScript`: quotes, comments, heredoc bodies, substitutions and compound commands are read as the shell reads them, so a `cd` in a heredoc or a string is data). A command does not count when Gradle runs no task with it — `--dry-run`/`-m` (also in a bundle such as `-qm`), `-v`/`--version`, `-h`/`-?`/`--help`, `--status`, `--stop`, `--foreground` (also in a bundle such as `-qv`) — or rejects it: a short-option bundle whose later letter takes a value (`-mx`: only the first letter of a bundle takes one), or a value given to an option that takes none (`-m=yes`). The reader follows Gradle 9.0's parser. `GradleCommandLineTest` holds its option tables to the `--help` of the Gradle that runs build-logic — an upgrade that adds an option, as 9.2 adds `--task-graph`, fails until the option is placed — and runs the launcher with each no-task option but `--stop` and `--foreground` (both return a daemon action, not a build, in Gradle's `BuildActionsFactory`); which options take a value was probed against 9.0.0 in round 9 and is not re-run. Nor does a command for another build count (the build a command starts is its step's `working-directory`, or the job's or workflow's `defaults.run.working-directory`, moved by each `cd ` the same `run:` shell surely ran before it — alone in its list, or before the command in the same `&&` list — then joined with `-p`; the plugin reads this build's own directory from where it sits under the repository that holds `.github/workflows`). Every other command that does not count gives one of three reasons. **Its failure may not fail its step**: `\|\| true`, `\|\| :` or any `\|\|` but `\|\| exit `, a pipe's left side without `pipefail` (on with `shell: bash` or a top-level `set -o pipefail`), `!`, `&`, an `if`/`while` condition, the part before `&&` of a list that is not the script's last command, after `set +e`, after a `trap` whose `EXIT` or `ERR` action may `exit` with status 0 (a bare `exit` keeps the status in an `EXIT` trap, not in an `ERR` one), and `continue-on-error`. **It may not run**: after `\|\|`, after `&&` in a list that is not the script's last command, inside `if`/`while`/`for`/`case` or a function body, after a top-level `exit`, `exec ` or `set -n`, after one elsewhere — in a compound command, an and-or list or a function the script calls — that may end the script with status 0 (`exit 0`, a bare `exit` other than right after `\|\|`, `exit "$code"`), replace it or stop it running commands (`set -o noexec`), under an `if:` other than `always()`/`success()`/`!cancelled()`, in a workflow that starts only on events someone or something asks for (`workflow_dispatch`, `repository_dispatch`, `issue_comment`, a pull request with `types: [labeled]`, `workflow_run`, …; `push`, `pull_request`, `pull_request_target`, `merge_group`, `schedule` and `release` count), in a workflow whose change-flow triggers all carry a `paths` or `paths-ignore` filter (a change outside those paths does not start it; owner decision 2026-11-06), for any stage but `:releaseCheck` in a workflow that starts without a request or a path filter only on the release flow — `release`, or a `push` with `tags`/`tags-ignore` and no `branches`/`branches-ignore`, which a branch push does not start (owner decision 2026-11-07; `:releaseCheck` is the tag-only stage) — in a reusable (`workflow_call`-only) workflow that no counted job calls with `uses: ./.github/workflows/`, and in a job that `needs`, directly or through other jobs, a job with such an `if:` or with `continue-on-error`, unless its own `if:` is `always()` or `!cancelled()`. **This check does not read it**, although its failure would fail the step (a false failure on purpose): `\|\| exit 1`, `\|\| { …; exit 1; }`, inside `{ }` or `( )`, `$( )`, `bash -c`, `gradlew` as another command's argument (`timeout 60 ./gradlew`), after a directory change the reader does not follow (`cd "$VAR"`, `cd -`, `cd ~`, an absolute path, `pushd`/`popd`, `builtin cd`, `eval`/`source`, a `cd` anywhere inside a compound command or a function body, one joined with `\|\|`, piped or in the background, and the lines after a `cd` that shares an `&&` list with other commands — not guessed), a step whose `shell:` is not `bash` or `sh`, and a step with no `shell:` in a job whose `runs-on` may be a Windows runner, whose default shell is `pwsh` (a Windows label, an expression such as `${{ matrix.os }}`, a self-hosted label set without `linux` or `macos`; Linux and macOS runners default to `bash -e` and a `container:` job to `sh -e`, which are read alike). An `exit` that fails the step — `exit 1`, or `cmd \|\| exit` — and one in an uncalled function, a `( )` subshell or `$( )` stop nothing after them from counting. The failure names every command that names the stage but does not execute it, with its reason or the other build it starts, and says to run the stage as `./gradlew` on a line of its own. A lane the command removes with `-x` is not covered — matched the way Gradle matches task and project names, abbreviations included (`TaskSelectors`, a copy of Gradle's internal `NameMatcher`). A `run:` input of a `uses:` step is not a command. The plan is Gradle's own; the workflows are read for their `run:` steps with YAML folding applied (review 2026-11-01 08-01, 2026-11-03 RR-06-03/04, 2026-11-04 RR2-04-04, owner decision 2026-11-04 on `cd`, RR5-02-01/02/03 in round 9, 2026-11-05 RR6-04-01..06, 2026-11-06 RR7-05-01, owner decision 2026-11-07 on the release flow) | | `ca.redis-topology-lane` | the Redis topology lane (mode selection, `-P` property validation, per-mode required classes) the redis-sdk-topology workflow drives | | `ca.api-surface` | read-only public API surface verification with a separate update task, wired into the leaf's `check` (owner decision 20); optionally holds other leaves' imports to a reviewed adopter subset (`adopterBaseline`) | | `ca.config-contract` | app-bootstrap's `verifyEnvKeys` (moved from the deleted build-tools included build; owner decision 4 keeps the task in app-bootstrap) | diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java index 419748ef..7d494a1d 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java @@ -34,7 +34,7 @@ import org.gradle.api.execution.TaskExecutionGraph; * the way Gradle matches it, abbreviations included ({@link TaskSelectors}); *
  • every declared stage is executed by a workflow. Not counted ({@code NOT_COUNTED}; review * 2026-11-03 RR-06-04, 2026-11-04 RR2-04-04, RR5-02-02, 2026-11-05 RR6-04-01..06, 2026-11-06 - * RR7-05-01): a command + * RR7-05-01, owner decision 2026-11-07 on the release flow): a command * after which Gradle runs no task ({@code --dry-run}, {@code -v}, {@code --help}, …) or that * Gradle rejects (a short-option bundle such as {@code -mx}), one for another build, and one * that does not gate for one of three reasons — its failure may not fail its step, it may not @@ -69,13 +69,15 @@ public final class StrictLaneStagesPlugin implements Plugin { + " exec or set -n, under an if: other than always()/success()/!cancelled(), in a" + " workflow that starts only on a request, or on changes only through a paths or" + " paths-ignore filter, or a reusable one no counted job calls, in a" - + " job that needs a job that may be skipped); and one this check does not read although" + + " job that needs a job that may be skipped, and for any stage but :releaseCheck in a" + + " workflow that starts only on a tag push or a release); and one this check does not" + + " read although" + " its failure" + " would fail the step (|| exit 1, inside { } or ( ), $( ), bash -c, gradlew as" + " another command's argument, after a cd it does not follow, a shell other than bash" + " or sh, a runner that may be Windows). Run the stage as ./gradlew on a line of its" + " own, in a step and job that run on every push, pull request or schedule, with no" - + " paths or paths-ignore filter"; + + " paths or paths-ignore filter (:releaseCheck may run on a tag push or a release)"; @Override public void apply(Project project) { @@ -231,7 +233,7 @@ public final class StrictLaneStagesPlugin implements Plugin { + ": gradlew " + String.join(" ", invocation.tasks()) + " — " - + invocation.whyNotExecuting(buildDirectory)))); + + invocation.whyNotExecuting(stage, buildDirectory)))); return lines.isEmpty() ? "" : "; commands that name it but do not count:\n " + String.join("\n ", lines); diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java index ef6c29bb..365d2f31 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java @@ -2,6 +2,7 @@ package dev.caskeleton.buildlogic.strictlane; import java.util.ArrayDeque; import java.util.ArrayList; +import java.util.Collection; import java.util.Deque; import java.util.HashSet; import java.util.LinkedHashMap; @@ -46,8 +47,11 @@ import java.util.regex.Pattern; * types} list, only when it holds {@code opened}, {@code synchronize} or {@code reopened}), {@code * merge_group}, {@code schedule}, {@code release} — and has no {@code paths} or {@code * paths-ignore} filter: a change that touches none of the listed paths, or only ignored ones, does - * not start it (owner decision 2026-11-06, review RR7-05-01). Its {@code branches} and {@code tags} - * filters are not read. One that starts only on other events — {@code + * not start it (owner decision 2026-11-06, review RR7-05-01). A workflow whose only such triggers + * are the release flow — {@code release}, or a {@code push} with {@code tags} or {@code + * tags-ignore} and no {@code branches} or {@code branches-ignore}, which a branch push does not + * start — counts only for {@code :releaseCheck}, the tag-only stage (owner decision 2026-11-07). + * One that starts only on other events — {@code * workflow_dispatch}, {@code repository_dispatch}, {@code issue_comment}, a {@code labeled} pull * request, {@code workflow_run} and the rest — runs only when someone or something asks (review * 2026-11-04 RR2-04-04, RR6-04-06). A workflow that starts only on {@code workflow_call} counts @@ -103,6 +107,13 @@ public final class WorkflowGradleInvocations { Set.of("opened", "synchronize", "reopened"); /** The trigger filters that start a workflow only for changes to some files. */ private static final List PATH_FILTERS = List.of("paths", "paths-ignore"); + /** The push filters that start it for tags; with no branch filter, a branch push does not. */ + private static final List TAG_FILTERS = List.of("tags", "tags-ignore"); + private static final List BRANCH_FILTERS = List.of("branches", "branches-ignore"); + private static final List FILTERS = + List.of("paths", "paths-ignore", "tags", "tags-ignore", "branches", "branches-ignore"); + /** The only stage a workflow of the release flow counts for: the tag-only one. */ + private static final String RELEASE_STAGE = ":releaseCheck"; private static final String REUSABLE_WORKFLOWS = "./.github/workflows/"; /** * Gradle 9.0's command-line options that take a value, by every name it accepts. Probed against @@ -176,6 +187,8 @@ public final class WorkflowGradleInvocations { * @param uncountedReason why the command gates nothing although it names tasks — it may not run, * its failure may not fail its step, this reader does not read it, or Gradle runs no task — * or {@code null} + * @param releaseFlowReason why the command gates only {@code :releaseCheck} — its workflow + * starts, of the triggers that need no request, only on the release flow — or {@code null} */ public record Invocation( String workingDirectory, @@ -183,12 +196,18 @@ public final class WorkflowGradleInvocations { List tasks, boolean dryRun, List excludedTasks, - String uncountedReason) { + String uncountedReason, + String releaseFlowReason) { public Invocation { tasks = List.copyOf(tasks); excludedTasks = List.copyOf(excludedTasks); } + private Invocation releaseFlowOnly(String reason) { + return new Invocation( + workingDirectory, projectDir, tasks, dryRun, excludedTasks, uncountedReason, reason); + } + /** * The directory of the build this command starts, from the repository root: the step's working * directory joined with {@code -p}. {@code .} is the repository root. @@ -206,11 +225,24 @@ public final class WorkflowGradleInvocations { * the repository root such as {@code src}. */ public boolean executes(String taskPath, String buildDirectory) { - return requests(taskPath) && whyNotExecuting(buildDirectory) == null; + return requests(taskPath) && whyNotExecuting(taskPath, buildDirectory) == null; } /** - * Why this command does not execute and gate on the tasks it names in the build in {@code + * Why this command does not execute and gate on the task at {@code taskPath} in the build in + * {@code buildDirectory}, or {@code null} when it does: a reason that holds for every task it + * names, or that its workflow is of the release flow and the task is not {@code :releaseCheck}. + */ + public String whyNotExecuting(String taskPath, String buildDirectory) { + String reason = whyNotExecuting(buildDirectory); + if (reason != null || releaseFlowReason == null) { + return reason; + } + return absolute(taskPath).equals(RELEASE_STAGE) ? null : releaseFlowReason; + } + + /** + * Why this command does not execute and gate on any task it names in the build in {@code * buildDirectory}, or {@code null} when it does: its uncounted reason, another build, or a dry * run. */ @@ -270,9 +302,39 @@ public final class WorkflowGradleInvocations { * * @param types its {@code types} list, or {@code null} when it has none * @param pathFilters which of {@code paths} and {@code paths-ignore} it has + * @param tagsOnly whether it filters tags and no branches, so that only a tag push starts it */ - private record Trigger(List types, List pathFilters) { - private static final Trigger UNFILTERED = new Trigger(null, List.of()); + private record Trigger(List types, List pathFilters, boolean tagsOnly) { + private static final Trigger UNFILTERED = new Trigger(null, List.of(), false); + + private static Trigger of(List types, Collection filters) { + return new Trigger( + types, + PATH_FILTERS.stream().filter(filters::contains).toList(), + TAG_FILTERS.stream().anyMatch(filters::contains) + && BRANCH_FILTERS.stream().noneMatch(filters::contains)); + } + } + + /** How a trigger takes part in the stages (owner decisions 2026-11-06 and 2026-11-07). */ + private enum Flow { + /** Starts on every change: counts for every stage. */ + CHANGE, + /** Starts on a release or a tag push: counts for {@code :releaseCheck} only. */ + RELEASE, + /** Starts on a change only when it touches some files: counts for no stage. */ + PATH_FILTERED, + /** Starts only when someone or something asks: counts for no stage. */ + REQUEST + } + + /** + * When a workflow starts, as the stages see it: on every change (both {@code null}), only on + * the release flow ({@code releaseFlow} says why it counts for {@code :releaseCheck} alone), or + * not without being asked ({@code notStarted} says why). + */ + private record Start(String notStarted, String releaseFlow) { + private static final Start EVERY_CHANGE = new Start(null, null); } /** A job: its id, the line of its key, and the column of its own keys (-1 when it has none). */ @@ -304,10 +366,13 @@ public final class WorkflowGradleInvocations { workflowsByFile.forEach((file, text) -> workflows.put(file, parse(file, text))); Map> invocations = new LinkedHashMap<>(); for (Workflow workflow : workflows.values()) { - String notStarted = startReason(workflow, workflows, new HashSet<>()); + Start start = start(workflow, workflows, new HashSet<>()); List commands = new ArrayList<>(); - for (RunStep step : runSteps(workflow, notStarted)) { - commands.addAll(stepInvocations(step)); + for (RunStep step : runSteps(workflow, start.notStarted())) { + for (Invocation command : stepInvocations(step)) { + commands.add( + start.releaseFlow() == null ? command : command.releaseFlowOnly(start.releaseFlow())); + } } invocations.put(workflow.file(), List.copyOf(commands)); } @@ -552,14 +617,13 @@ public final class WorkflowGradleInvocations { int detailIndent = childIndent(lines, next); if (detailIndent > childIndent) { int typesLine = mappingKey(lines, next + 1, detailIndent, "types"); - List pathFilters = new ArrayList<>(); - for (String filter : PATH_FILTERS) { + List filters = new ArrayList<>(); + for (String filter : FILTERS) { if (mappingKey(lines, next + 1, detailIndent, filter) >= 0) { - pathFilters.add(filter); + filters.add(filter); } } - trigger = - new Trigger(typesLine < 0 ? null : listValue(lines, typesLine), pathFilters); + trigger = Trigger.of(typesLine < 0 ? null : listValue(lines, typesLine), filters); } } triggers.put(stripScalarComment(colon < 0 ? key : key.substring(0, colon)), trigger); @@ -575,7 +639,7 @@ public final class WorkflowGradleInvocations { return Trigger.UNFILTERED; } List types = null; - List pathFilters = new ArrayList<>(); + List filters = new ArrayList<>(); for (String entry : flowItems(value.substring(1, value.length() - 1))) { int colon = entry.indexOf(':'); if (colon < 0) { @@ -588,48 +652,68 @@ public final class WorkflowGradleInvocations { detail.startsWith("[") && detail.endsWith("]") ? flowItems(detail.substring(1, detail.length() - 1)) : List.of(stripScalarComment(detail)); - } else if (PATH_FILTERS.contains(key)) { - pathFilters.add(key); + } else if (FILTERS.contains(key)) { + filters.add(key); } } - return new Trigger(types, pathFilters); + return Trigger.of(types, filters); } /** - * Why the workflow does not run on every change, or {@code null} when it does or writes no {@code - * on:}. A reusable workflow runs through its callers ({@code visiting} guards a cycle). + * When the workflow starts, as the stages see it; on every change when it writes no {@code on:}. + * A reusable workflow runs through its callers ({@code visiting} guards a cycle). */ - private static String startReason( + private static Start start( Workflow workflow, Map workflows, Set visiting) { Map triggers = workflow.triggers(); if (triggers.isEmpty()) { - return null; + return Start.EVERY_CHANGE; } Map pathFiltered = new LinkedHashMap<>(); + Map releaseFlow = new LinkedHashMap<>(); for (Map.Entry trigger : triggers.entrySet()) { - if (!runsOnChanges(trigger.getKey(), trigger.getValue().types())) { - continue; + switch (flow(trigger.getKey(), trigger.getValue())) { + case CHANGE -> { + return Start.EVERY_CHANGE; + } + case PATH_FILTERED -> pathFiltered.put(trigger.getKey(), trigger.getValue()); + case RELEASE -> releaseFlow.put(trigger.getKey(), trigger.getValue()); + case REQUEST -> { + // counted only through a caller, below, when it is workflow_call + } } - if (trigger.getValue().pathFilters().isEmpty()) { - return null; - } - pathFiltered.put(trigger.getKey(), trigger.getValue()); } + String release = + releaseFlow.isEmpty() + ? null + : "its workflow starts without a request or a path filter only on the release flow (" + + describe(releaseFlow) + + "), not on every push, pull request or schedule, so it counts only for " + + RELEASE_STAGE; String described = describe(triggers); - if (!triggers.containsKey("workflow_call") && !pathFiltered.isEmpty()) { - return "its workflow starts on changes only through " - + describe(pathFiltered) - + ", which a change that touches none of the listed paths, or only ignored ones, does" - + " not start, so it may not run"; - } if (!triggers.containsKey("workflow_call")) { - return "its workflow starts only on " - + described - + ", which happen only when someone or something asks, not on every push, pull request" - + " or schedule, so it may not run"; + if (release != null) { + return new Start(null, release); + } + if (!pathFiltered.isEmpty()) { + return new Start( + "its workflow starts on changes only through " + + describe(pathFiltered) + + ", which a change that touches none of the listed paths, or only ignored ones," + + " does not start, so it may not run", + null); + } + return new Start( + "its workflow starts only on " + + described + + ", which happen only when someone or something asks, not on every push, pull" + + " request or schedule, so it may not run", + null); } if (!visiting.add(workflow.file())) { - return "its workflow is called only through a cycle of workflow_call"; + return release != null + ? new Start(null, release) + : new Start("its workflow is called only through a cycle of workflow_call", null); } List callers = new ArrayList<>(); for (Workflow caller : workflows.values()) { @@ -643,30 +727,57 @@ public final class WorkflowGradleInvocations { reason = needsReason(caller, job); } if (reason == null) { - reason = startReason(caller, workflows, new HashSet<>(visiting)); - } - if (reason == null) { - return null; + Start callerStart = start(caller, workflows, new HashSet<>(visiting)); + if (callerStart.equals(Start.EVERY_CHANGE)) { + return Start.EVERY_CHANGE; + } + if (callerStart.notStarted() == null && release == null) { + release = + "its workflow is called by " + + caller.file() + + " job " + + job.id() + + ", and " + + callerStart.releaseFlow(); + } + reason = + callerStart.notStarted() == null + ? callerStart.releaseFlow() + : callerStart.notStarted(); } callers.add(caller.file() + " job " + job.id() + ": " + reason); } } - return "its workflow starts only on " - + described - + ", and no workflow that runs on every change calls it (" - + (callers.isEmpty() - ? "no workflow in this directory calls it" - : String.join("; ", callers)) - + "), so it may not run"; + if (release != null) { + return new Start(null, release); + } + return new Start( + "its workflow starts only on " + + described + + ", and no workflow that runs on every change calls it (" + + (callers.isEmpty() + ? "no workflow in this directory calls it" + : String.join("; ", callers)) + + "), so it may not run", + null); } - private static boolean runsOnChanges(String trigger, List types) { - if (!CHANGE_TRIGGERS.contains(trigger)) { - return false; + private static Flow flow(String name, Trigger trigger) { + if (!CHANGE_TRIGGERS.contains(name)) { + return Flow.REQUEST; } - return types == null - || !trigger.startsWith("pull_request") - || types.stream().anyMatch(PULL_REQUEST_CHANGE_TYPES::contains); + if (trigger.types() != null + && name.startsWith("pull_request") + && trigger.types().stream().noneMatch(PULL_REQUEST_CHANGE_TYPES::contains)) { + return Flow.REQUEST; + } + if (!trigger.pathFilters().isEmpty()) { + return Flow.PATH_FILTERED; + } + if (name.equals("release") || name.equals("push") && trigger.tagsOnly()) { + return Flow.RELEASE; + } + return Flow.CHANGE; } private static String describe(Map triggers) { @@ -678,6 +789,9 @@ public final class WorkflowGradleInvocations { filters.add("types: " + String.join(", ", trigger.types())); } filters.addAll(trigger.pathFilters()); + if (trigger.tagsOnly()) { + filters.add("tags only"); + } described.add(filters.isEmpty() ? name : name + " (" + String.join("; ", filters) + ")"); }); return String.join(", ", described); @@ -1268,7 +1382,7 @@ public final class WorkflowGradleInvocations { if (reason == null) { reason = rejected != null ? rejected : runsNoTask; } - return new Invocation(workingDirectory, projectDir, tasks, dryRun, excluded, reason); + return new Invocation(workingDirectory, projectDir, tasks, dryRun, excluded, reason, null); } private static boolean isFlag(String name) { diff --git a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java index 4c0a2a18..7a0b09ee 100644 --- a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java +++ b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java @@ -698,6 +698,63 @@ class StrictLaneStagesFunctionalTest { .doesNotContain("stage :ci is executed by no workflow"); } + @Test + @DisplayName("태그 push로만 도는 workflow의 단계 명령은 releaseCheck에만 세고, 다른 단계는 실행되지 않은 것으로 본다") + void aReleaseFlowWorkflowCountsOnlyForTheReleaseStage() throws Exception { + // given + Files.writeString( + gradleRoot.resolve("build.gradle"), + """ + plugins { id 'ca.strict-lane-stages' } + tasks.register('ci') { dependsOn ':leaf:check' } + tasks.register('integrationCheck') { dependsOn ':leaf:integrationTestLaneCheck' } + tasks.register('releaseCheck') + strictLaneStages { + stage ':ci', ':integrationCheck', ':releaseCheck' + workflowDirectory = layout.projectDirectory.dir('../.github/workflows') + } + """); + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + on: pull_request + jobs: + gate: + runs-on: ubuntu-latest + steps: + - working-directory: src + run: ./gradlew :ci --stacktrace + """); + Files.writeString( + repository.resolve(".github/workflows/release.yml"), + """ + on: + push: + tags: ['v*'] + jobs: + release: + runs-on: ubuntu-latest + steps: + - working-directory: src + run: ./gradlew :releaseCheck + - working-directory: src + run: ./gradlew :integrationCheck --continue + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .contains("release.yml: gradlew :integrationCheck") + .contains("counts only for :releaseCheck") + .doesNotContain("stage :releaseCheck is executed by no workflow"); + } + private void leafLanes(String lanes) throws Exception { Files.writeString( gradleRoot.resolve("leaf/build.gradle"), diff --git a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java index b8503153..ff933dcb 100644 --- a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java +++ b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java @@ -1218,8 +1218,8 @@ class WorkflowGradleInvocationsTest { } @Test - @DisplayName("push·pull_request·merge_group·schedule·release 중 하나로도 시작하는 workflow의 명령은 센다") - void aWorkflowThatAlsoStartsOnTheChangeOrReleaseFlowCounts() { + @DisplayName("push·pull_request·merge_group·schedule 중 하나로도 시작하는 workflow의 명령은 센다") + void aWorkflowThatAlsoStartsOnTheChangeFlowCounts() { // given List workflows = List.of( @@ -1252,16 +1252,6 @@ class WorkflowGradleInvocationsTest { run: ./gradlew :ci """, """ - on: - release: - types: [published] - jobs: - main: - steps: - - working-directory: src - run: ./gradlew :ci - """, - """ on: pull_request: types: [opened, synchronize, labeled] @@ -1279,7 +1269,7 @@ class WorkflowGradleInvocationsTest { // then assertThat(invocations) - .hasSize(5) + .hasSize(4) .allSatisfy(invocation -> assertThat(invocation.executes(":ci", "src")).isTrue()); } @@ -1364,6 +1354,82 @@ class WorkflowGradleInvocationsTest { invocation -> assertThat(invocation.executes(":ci", "src")).isTrue()); } + @Test + @DisplayName("태그 push나 release로만 시작하는 workflow의 명령은 releaseCheck에만 센다") + void aWorkflowThatStartsOnlyOnTheReleaseFlowCountsOnlyForReleaseCheck() { + // given + List workflows = + List.of( + """ + on: + push: + tags: ['v*'] + jobs: + release: + steps: + - working-directory: src + run: ./gradlew :releaseCheck :integrationCheck + """, + """ + on: + release: + types: [published] + workflow_dispatch: + jobs: + release: + steps: + - working-directory: src + run: ./gradlew :releaseCheck :integrationCheck + """, + """ + on: {push: {tags-ignore: ['nightly-*']}} + jobs: + release: + steps: + - working-directory: src + run: ./gradlew :releaseCheck :integrationCheck + """); + + // when + List invocations = + workflows.stream().flatMap(workflow -> WorkflowGradleInvocations.read(workflow).stream()) + .toList(); + + // then + assertThat(invocations) + .hasSize(3) + .allSatisfy( + invocation -> { + assertThat(invocation.executes(":releaseCheck", "src")).isTrue(); + assertThat(invocation.executes(":integrationCheck", "src")).isFalse(); + }); + } + + @Test + @DisplayName("태그와 함께 브랜치도 받는 push로 시작하는 workflow의 명령은 모든 단계에 센다") + void aPushWithBranchesBesidesTagsCountsForEveryStage() { + // given + String workflow = + """ + on: + push: + branches: [main] + tags: ['v*'] + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :integrationCheck + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).singleElement().satisfies( + invocation -> assertThat(invocation.executes(":integrationCheck", "src")).isTrue()); + } + @Test @DisplayName("workflow_call로만 시작하는 재사용 workflow의 명령은 매 변경에 도는 호출 job이 있을 때만 센다") void aReusableWorkflowCountsOnlyThroughACallerThatRunsOnEveryChange() {