From 2e9298ec33afaf2a5820ccc598b782954b46c040 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 16:09:40 +0900 Subject: [PATCH] =?UTF-8?q?build:=20=ED=85=9C=ED=94=8C=EB=A6=BF=20?= =?UTF-8?q?=EB=B0=96=EC=97=90=EC=84=9C=20=ED=98=BC=EC=9E=90=20=EB=B9=8C?= =?UTF-8?q?=EB=93=9C=C2=B7=EB=B0=B0=ED=8F=AC=EB=90=98=EB=8A=94=20Gradle=20?= =?UTF-8?q?=EB=A3=A8=ED=8A=B8=EB=A5=BC=20=EB=A7=8C=EB=93=A0=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 옮겨 온 메시징 19개 모듈은 템플릿의 src/settings.gradle·build-logic· 카탈로그·registry에 기대고 있어 이 repo만으로는 빌드되지 않는다. repo 루트를 Gradle 루트로 하는 단독 빌드를 만든다. - build-logic/: grpc-library main 2e880c7의 줄인 사본(템플릿 22df3525에서 복사, 템플릿 2959eff0까지의 변경도 같은 내용)에서 gRPC BOM 규칙(ca.grpc-platform-module)만 뺐다. 배포 플러그인 ca.library-publishing과 서명 키 해석(SigningKeys)은 그대로다. 출처·뺀 것·고친 것은 build-logic/UPSTREAM.md. - settings.gradle·build.gradle·gradle.properties: group dev.cakit.messaging, 단계 태스크 ci·mainCheck·releaseCheck와 배포(release·releaseRehearsal·verifySigningKey)는 grpc-library와 같은 모양이다. 메시징만 다른 점: Buf가 없고, 성능 lane이 없고, mainCheck와 releaseCheck가 브로커 인증 증거 게이트 (verifyMessagingCertificationEvidence)를 부른다. 템플릿은 이 게이트를 따로 messaging-certification.yml로 돌렸다. 그 workflow는 지운다. - config/: registry 19행(source_path만 messaging/로), 메시징 클래스만 남긴 SpotBugs 제외 목록, 이미지 셋(postgres-16, kafka, toxiproxy, 모두 digest 고정), checkstyle 사본. - gradle/libs.versions.toml: 메시징이 쓰는 항목만(avro, cloudevents, protobuf 4.33.2, toxiproxy, jmh)과 kafka-clients가 끌고 오는 취약 버전을 덮는 pinned-lz4-java·pinned-snappy-java. - 저장소 계약 테스트: MessagingPublicSurfaceContractTest(템플릿 app-bootstrap에서 이력째 옮김)와 새 MessagingSettingsOwnerContractTest (app.messaging 주인은 starter 하나)를 messaging-testkit의 repositoryContractTest lane에 둔다. check에 들어가 PR 단계에서 돈다. - messaging-kafka: 인증 manifest 경로를 새 배치로 고친다. 버린 대안: 계약 테스트를 build-logic 테스트로 두는 안. 빌드 플러그인 시험과 모듈 계약이 섞이고, 소스·build.gradle을 입력으로 선언하는 기존 lane 장치를 쓸 수 없다. 위험: 이 커밋 단독으로는 lockfile을 다시 쓰지 않았다(뒤 커밋에서 desktop에서 쓴다). 패키지는 아직 dev.caskeleton.messaging이다. 검증: desktop ./gradlew projects rc=0(19개 모듈 포함). Refs: design-docs repo-structure/05-library-repos.md 4·10.3·13.1절 --- .gitea/pull_request_template.md | 23 + .github/workflows/messaging-certification.yml | 51 - .gitignore | 8 + .trivyignore.yaml | 15 + build-logic/AGENTS.md | 8 + build-logic/CLAUDE.md | 1 + build-logic/UPSTREAM.md | 39 + build-logic/build.gradle | 91 + build-logic/gradle.lockfile | 46 + build-logic/settings-gradle.lockfile | 4 + build-logic/settings.gradle | 26 + .../buildlogic/ApiSurfaceExtension.java | 45 + .../buildlogic/ApiSurfacePolicy.java | 197 ++ .../buildlogic/JavaPublicTypes.java | 131 ++ .../caskeleton/buildlogic/ModuleRegistry.java | 307 +++ .../ModuleRegistrySettingsInstaller.java | 63 + .../buildlogic/RequiredTestExecution.java | 40 + .../buildlogic/ResolvedComponents.java | 47 + .../apisurface/ApiSurfacePlugin.java | 111 ++ .../apisurface/UpdateApiSurfaceTask.java | 89 + .../apisurface/VerifyApiSurfaceTask.java | 92 + .../architecture/ArchitecturePlugin.java | 201 ++ ...rifyCleanArchitectureDependenciesTask.java | 96 + .../VerifyModuleDependencyDirectionTask.java | 89 + .../VerifyNoIgnoredSourcePackagesTask.java | 157 ++ .../JavaLibraryConventionPlugin.java | 13 + .../PlatformModuleConventionPlugin.java | 14 + .../SpringConfigConventionPlugin.java | 44 + .../java/JavaConventionsPlugin.java | 358 ++++ .../java/MockitoAgentArgumentProvider.java | 38 + .../java/ResolveConfigurationsTask.java | 39 + .../publishing/LibraryPublishingPlugin.java | 185 ++ .../buildlogic/publishing/SigningKeys.java | 42 + .../quality/QualityConventionsPlugin.java | 284 +++ .../quality/SpotBugsAnalysisReport.java | 63 + .../ArchitectureRegistrySettingsPlugin.java | 22 + .../ExclusiveRealServerLaneService.java | 24 + .../buildlogic/strictlane/ShellScript.java | 1659 +++++++++++++++++ .../StrictLaneExecutionTracker.java | 60 + .../strictlane/StrictLaneStagesExtension.java | 28 + .../strictlane/StrictLaneStagesPlugin.java | 322 ++++ .../strictlane/StrictTestLaneExtension.java | 28 + .../strictlane/StrictTestLanePlugin.java | 473 +++++ .../strictlane/StrictTestLaneSpec.java | 209 +++ .../buildlogic/strictlane/TaskSelectors.java | 214 +++ .../strictlane/TestLaneCategory.java | 9 + .../strictlane/WorkflowGradleInvocations.java | 1410 ++++++++++++++ .../buildlogic/ApiSurfacePolicyTest.java | 48 + .../buildlogic/ModuleRegistryTest.java | 191 ++ .../buildlogic/RequiredTestExecutionTest.java | 39 + .../apisurface/ApiSurfaceConventionTest.java | 199 ++ ...ectureResolvedClasspathFunctionalTest.java | 182 ++ ...NoIgnoredSourcePackagesFunctionalTest.java | 122 ++ .../PlatformModuleConventionTest.java | 158 ++ .../publishing/SigningKeysTest.java | 41 + .../strictlane/GradleCommandLineTest.java | 162 ++ .../StrictLaneStagesFunctionalTest.java | 783 ++++++++ .../StrictTestLaneConventionTest.java | 817 ++++++++ .../strictlane/TaskSelectorsTest.java | 71 + .../WorkflowGradleInvocationsTest.java | 1581 ++++++++++++++++ build.gradle | 315 ++++ config/architecture/modules.json | 190 ++ config/checkstyle/checkstyle-suppressions.xml | 28 + config/checkstyle/checkstyle.xml | 93 + config/spotbugs/exclude-test.xml | 84 + config/spotbugs/exclude.xml | 200 ++ config/testing/container-images.properties | 25 + gradle.properties | 13 + gradle/libs.versions.toml | 87 + gradle/wrapper/gradle-wrapper.jar | Bin 0 -> 45457 bytes gradle/wrapper/gradle-wrapper.properties | 8 + gradlew | 251 +++ gradlew.bat | 94 + messaging/messaging-kafka/build.gradle | 2 +- messaging/messaging-testkit/build.gradle | 28 + .../MessagingPublicSurfaceContractTest.java | 16 +- .../MessagingSettingsOwnerContractTest.java | 91 + .../testkit/contract/RepositoryRoot.java | 50 + scripts/release/check-signing-key.sh | 175 ++ scripts/release/check-staging.py | 85 + scripts/release/sbom.sh | 15 + scripts/release/verify-published.sh | 22 + scripts/release/vulnerability-scan.sh | 47 + scripts/tool.sh | 52 + scripts/verify.sh | 36 +- settings-gradle.lockfile | 4 + settings.gradle | 20 + 87 files changed, 13862 insertions(+), 78 deletions(-) create mode 100644 .gitea/pull_request_template.md delete mode 100644 .github/workflows/messaging-certification.yml create mode 100644 .trivyignore.yaml create mode 100644 build-logic/AGENTS.md create mode 100644 build-logic/CLAUDE.md create mode 100644 build-logic/UPSTREAM.md create mode 100644 build-logic/build.gradle create mode 100644 build-logic/gradle.lockfile create mode 100644 build-logic/settings-gradle.lockfile create mode 100644 build-logic/settings.gradle create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/ApiSurfaceExtension.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/ApiSurfacePolicy.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/JavaPublicTypes.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistrySettingsInstaller.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/RequiredTestExecution.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/ResolvedComponents.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/ApiSurfacePlugin.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/UpdateApiSurfaceTask.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/VerifyApiSurfaceTask.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyCleanArchitectureDependenciesTask.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyModuleDependencyDirectionTask.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesTask.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/convention/JavaLibraryConventionPlugin.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/convention/PlatformModuleConventionPlugin.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/convention/SpringConfigConventionPlugin.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/java/JavaConventionsPlugin.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/java/MockitoAgentArgumentProvider.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/java/ResolveConfigurationsTask.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/LibraryPublishingPlugin.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/SigningKeys.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/quality/QualityConventionsPlugin.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/quality/SpotBugsAnalysisReport.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/settings/ArchitectureRegistrySettingsPlugin.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ExclusiveRealServerLaneService.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ShellScript.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneExecutionTracker.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesExtension.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneExtension.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLanePlugin.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneSpec.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TaskSelectors.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TestLaneCategory.java create mode 100644 build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/ApiSurfacePolicyTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/ModuleRegistryTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/RequiredTestExecutionTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/apisurface/ApiSurfaceConventionTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/CleanArchitectureResolvedClasspathFunctionalTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesFunctionalTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/convention/PlatformModuleConventionTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/publishing/SigningKeysTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/GradleCommandLineTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneConventionTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/TaskSelectorsTest.java create mode 100644 build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java create mode 100644 build.gradle create mode 100644 config/architecture/modules.json create mode 100644 config/checkstyle/checkstyle-suppressions.xml create mode 100644 config/checkstyle/checkstyle.xml create mode 100644 config/spotbugs/exclude-test.xml create mode 100644 config/spotbugs/exclude.xml create mode 100644 config/testing/container-images.properties create mode 100644 gradle.properties create mode 100644 gradle/libs.versions.toml create mode 100644 gradle/wrapper/gradle-wrapper.jar create mode 100644 gradle/wrapper/gradle-wrapper.properties create mode 100755 gradlew create mode 100644 gradlew.bat create mode 100644 messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingSettingsOwnerContractTest.java create mode 100644 messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/RepositoryRoot.java create mode 100755 scripts/release/check-signing-key.sh create mode 100644 scripts/release/check-staging.py create mode 100755 scripts/release/sbom.sh create mode 100755 scripts/release/verify-published.sh create mode 100755 scripts/release/vulnerability-scan.sh create mode 100755 scripts/tool.sh create mode 100644 settings-gradle.lockfile create mode 100644 settings.gradle diff --git a/.gitea/pull_request_template.md b/.gitea/pull_request_template.md new file mode 100644 index 0000000..a546c3f --- /dev/null +++ b/.gitea/pull_request_template.md @@ -0,0 +1,23 @@ +## 무엇을, 왜 + + + +## 고른 방법과 버린 대안 + + + +## 위험과 영향 + + + +## 검증 + + + +## 리뷰어가 볼 곳 + + + +## 관련 + + diff --git a/.github/workflows/messaging-certification.yml b/.github/workflows/messaging-certification.yml deleted file mode 100644 index 726ba8e..0000000 --- a/.github/workflows/messaging-certification.yml +++ /dev/null @@ -1,51 +0,0 @@ -# The messaging platform's broker certification lane. -# -# Separate from ci-quality-gates.yml because it needs a container runtime and several minutes of it. -# The lane deliberately carries no Docker guard: every other container suite in the messaging tree -# skips with a stated reason when Docker is absent, and a certification lane that skipped would -# report success for a broker nobody started — which is the exact claim the evidence exists to rule -# out. -# -# The job runs the evidence gate rather than the lane, and the gate depends on the lane. What it -# proves is not only that the scenarios pass but that the committed manifest -# (messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl) is what this -# run produced, so "certified against a live broker" cannot be restored by editing a file. -name: messaging-certification - -on: - pull_request: - paths: - - "src/platforms/messaging/**" - - ".github/workflows/messaging-certification.yml" - # Every Gradle job here installs its toolchain through this composite action, so a change to - # it changes what this gate runs. - - ".github/actions/setup-gradle-java/action.yml" - schedule: - - cron: "41 4 * * 3" - workflow_dispatch: - -permissions: - contents: read - -env: - # Reuse would hand one scenario the broker another scenario had already faulted. - TESTCONTAINERS_REUSE_ENABLE: "false" - -jobs: - broker-certification: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Certify the Kafka adapter against a real broker - working-directory: src - # GITHUB_SHA is read by the lane and written into every evidence line, because "certified" - # is a claim about one source tree. - run: ./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --stacktrace - - name: Publish the certification evidence - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: messaging-broker-certification-evidence - path: src/platforms/messaging/messaging-kafka/build/messaging-certification/ - if-no-files-found: warn diff --git a/.gitignore b/.gitignore index 94f22da..85e7d7f 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,11 @@ .env.production __pycache__/ + +# Gradle and IDE output +.gradle/ +build/ +**/bin/ +.idea/ +*.iml +.vscode/ diff --git a/.trivyignore.yaml b/.trivyignore.yaml new file mode 100644 index 0000000..7ef712f --- /dev/null +++ b/.trivyignore.yaml @@ -0,0 +1,15 @@ +# Structured Trivy suppression baseline. +# +# This repository-root file is the only CI suppression source. Every Trivy invocation must name it +# with `--ignorefile .trivyignore.yaml`; ad-hoc ignore files and inline bypasses are not allowed. +# +# Every entry must carry: +# id: advisory, license, misconfiguration, or secret identifier +# statement: non-empty accepted-risk or false-positive rationale +# expired_at: future YYYY-MM-DD, no more than 90 days from review +# + +vulnerabilities: [] +licenses: [] +misconfigurations: [] +secrets: [] diff --git a/build-logic/AGENTS.md b/build-logic/AGENTS.md new file mode 100644 index 0000000..2d12922 --- /dev/null +++ b/build-logic/AGENTS.md @@ -0,0 +1,8 @@ +# build-logic — 이 repo의 Gradle convention 플러그인 + +백엔드 템플릿 `src/build-logic/`의 사본이다. 출처와 뺀 것·고친 것은 `UPSTREAM.md`가 정본이다. 루트 `AGENTS.md`가 먼저다. + +- 모듈은 `ca.platform-module`(Java 라이브러리 + 배포)을 쓴다. Spring 설정 메타데이터가 있는 모듈은 `ca.spring-config`를 더한다. +- `ca.architecture`는 registry(`config/architecture/modules.json`)의 허용 의존과 실제 project edge를 대조한다. registry에 없는 `build.gradle`이 있으면 실패한다. +- `ca.strict-test-lane`의 lane은 아무것도 실행하지 않거나 skip이 있으면 실패한다. lane마다 단계(`ci`·`mainCheck`·`releaseCheck`) 하나에 들어 있어야 한다(`verifyStrictLaneStages --dry-run`, `.gitea/workflows`를 읽는다). +- 이 폴더를 고치면 `./gradlew buildLogicTest`(루트 `ci`에 들어 있다). 템플릿 쪽 수정을 옮길 때는 `UPSTREAM.md` 「템플릿 수정을 옮기는 법」을 따른다. diff --git a/build-logic/CLAUDE.md b/build-logic/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/build-logic/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/build-logic/UPSTREAM.md b/build-logic/UPSTREAM.md new file mode 100644 index 0000000..963519e --- /dev/null +++ b/build-logic/UPSTREAM.md @@ -0,0 +1,39 @@ +# build-logic의 출처 — 백엔드 템플릿에서 복사해 줄였다 + +- 복사한 곳: `grpc-library` main `2e880c7`의 `build-logic/`(2026-11-08). 그 사본은 `clean-architecture-backend-template` main `22df3525`의 `src/build-logic/`을 줄인 것이다. 템플릿 main `2959eff0`까지의 `src/build-logic` 변경(`57988c2e` registry `build` 칸 거절, `5e204e6a` optional build 지원 삭제)은 그 사본에 이미 같은 내용으로 들어 있다(주석 문장만 다르다). +- 함께 복사: 템플릿 `src/gradle/libs.versions.toml`(이 repo가 쓰는 항목만), `src/gradle/wrapper/`, `src/gradlew*`, `src/config/checkstyle/`, `src/config/spotbugs/`(메시징 클래스와 일반 규칙만), `src/config/testing/container-images.properties`(`postgres-16`·`kafka`·`toxiproxy`만) +- 근거: design-docs `repo-structure/05-library-repos.md` 10.3절 L1(복사 후 줄이기). 다시 열 조건: 라이브러리 repo가 셋 이상이 되거나, 6개월 안에 템플릿에서 이 사본으로 옮긴 수정이 3번을 넘으면 공통 빌드 규칙 repo(L3)를 본다. 사본은 이제 셋이다(템플릿, grpc-library, 이 repo). 앞의 조건 「라이브러리 repo가 셋 이상」은 아직 아니다. + +## 뺀 것 + +| 무엇 | 이유 | +| --- | --- | +| `ca.bootrun-dotenv`, `ca.redis-topology-lane`, `ca.config-contract`, `ca.spring-library` | 이 repo 모듈이 쓰지 않는다(grpc-library 사본에서 이미 뺐다) | +| `ca.optional-architecture-registry`, `MainBuild` | 템플릿 안 두 번째 빌드(optional build)를 위한 것. 여기서는 repo 루트가 곧 Gradle 루트다 | +| `VerifyApplicationCoreDependencyPurityTask`(`ca.architecture` 안) | 템플릿 계층 이름(`domain-core`·`application-*`·`shared-contract`)에만 걸린다 | +| `ca.grpc-platform-module`과 그 테스트 | grpc-library 사본에만 있던 gRPC BOM 규칙. 이 repo에는 gRPC 모듈이 없다 | +| `README.md`, 템플릿 `AGENTS.md` | 템플릿 빌드 설명이다. 이 폴더 `AGENTS.md`로 바꿨다 | + +`ca.api-surface`는 남겼다. 설계 10.1절은 라이브러리 모듈에 켜기를 권하지만, 공개 타입 기준선 파일과 정책은 새 결정이라 아직 어느 모듈에도 켜지 않았다(grpc-library와 같다). + +## 고친 것(템플릿과 다른 점) + +| 파일 | 바뀐 점 | +| --- | --- | +| `settings/ArchitectureRegistrySettingsPlugin` | repo 루트 = Gradle 루트. registry의 `source_path`는 Gradle 루트 기준이다(템플릿은 `src/`의 부모 기준) | +| `architecture/ArchitecturePlugin` | 위와 같은 기준, optional build 분기와 purity 태스크를 뺐다 | +| `java/JavaConventionsPlugin` | `group`을 `gradle.properties`의 `libraryGroup`에서 읽는다(템플릿은 `dev.caskeleton` 고정). 버전은 `RELEASE_TAG`/`-PreleaseTag`(`vX.Y.Z`)에서도 읽는다. 이미지 목록·도구 설정은 루트의 `config/`만 본다 | +| `quality/QualityConventionsPlugin` | 도구 설정은 루트의 `config/`만 본다 | +| `convention/PlatformModuleConventionPlugin` | `ca.library-publishing`을 함께 켠다 | +| `strictlane/StrictLaneStagesPlugin` | 단계의 계획을 따라갈 때 included build 태스크(`ci`가 부르는 build-logic `test`)는 묻지 않는다 | +| 새 `publishing/LibraryPublishingPlugin`(`ca.library-publishing`) | 모듈마다 Maven publication(sources·javadoc jar, 해석된 버전), 저장소 `gitea`·`staging`, `SIGNING_KEY`가 있으면 PGP 서명. test fixtures는 배포하지 않는다 | +| 새 `publishing/SigningKeys` | base64로 감싼 armored 키를 푼다(grpc-library v1.0.0 서명 실패에서 나온 수정) | +| 테스트 fixture | `source_path`를 Gradle 루트 기준으로, `PlatformModuleConventionTest`에 `libraryGroup` | + +Java 패키지 `dev.caskeleton.buildlogic`은 그대로 두었다. 배포하지 않는 빌드 도구이고, 템플릿 파일과 나란히 비교하기 쉽게 하려는 것이다. + +## 템플릿 수정을 옮기는 법 + +1. 템플릿에서 `git log --oneline 2959eff0..main -- src/build-logic`으로 이후 변경을 본다. grpc-library의 `build-logic/`에 먼저 옮겨졌으면 그 커밋을 따라 해도 된다. +2. 위 「뺀 것」에 해당하지 않는 변경만 같은 파일에 옮긴다. 옮긴 커밋은 본문에 템플릿 커밋 SHA를 적는다. +3. 옮긴 뒤 이 파일의 「복사한 곳」 커밋을 그 템플릿 커밋으로 바꾸고, 옮긴 횟수를 세어 다시 열 조건과 비교한다. diff --git a/build-logic/build.gradle b/build-logic/build.gradle new file mode 100644 index 0000000..d1958e5 --- /dev/null +++ b/build-logic/build.gradle @@ -0,0 +1,91 @@ +plugins { + id 'java-gradle-plugin' +} + +// The plugins below come from the Gradle Plugin Portal, so their resolved graph is locked like every +// leaf's (gradle.lockfile beside this file). STRICT: a configuration with no lock state fails rather +// than resolving whatever the portal serves. Regenerate with +// `./gradlew -p build-logic dependencies --write-locks` after a catalog version change. +dependencyLocking { + lockAllConfigurations() + lockMode = LockMode.STRICT +} + +dependencies { + implementation libs.jackson3.databind + // The third-party Gradle plugins the convention plugins apply. + // + // The root build used to apply these to every leaf from `configure(subprojects)`, and the + // recorded reason for keeping them there (D8) was that build-logic would have to re-declare + // their versions, giving each one a second home that could drift. That objection no longer + // holds: build-logic/settings.gradle reads the main build's `gradle/libs.versions.toml`, so the + // versions below and the ones the root `plugins {}` block declares are the same table entries. + implementation "com.diffplug.spotless:spotless-plugin-gradle:${libs.versions.spotless.get()}" + implementation "com.github.spotbugs.snom:spotbugs-gradle-plugin:${libs.versions.spotbugsPlugin.get()}" + implementation "net.ltgt.gradle:gradle-errorprone-plugin:${libs.versions.errorpronePlugin.get()}" + implementation "io.spring.gradle:dependency-management-plugin:${libs.versions.springDependencyManagement.get()}" + + // TestKit verifies the binary plugins against the running Gradle distribution. + testImplementation gradleTestKit() + testImplementation libs.junit.jupiter + testImplementation libs.assertj.core + testRuntimeOnly 'org.junit.platform:junit-platform-launcher' +} + + +gradlePlugin { + plugins { + apiSurface { + id = 'ca.api-surface' + implementationClass = 'dev.caskeleton.buildlogic.apisurface.ApiSurfacePlugin' + } + architecture { + id = 'ca.architecture' + implementationClass = 'dev.caskeleton.buildlogic.architecture.ArchitecturePlugin' + } + javaConventions { + id = 'ca.java-conventions' + implementationClass = 'dev.caskeleton.buildlogic.java.JavaConventionsPlugin' + } + qualityConventions { + id = 'ca.quality-conventions' + implementationClass = 'dev.caskeleton.buildlogic.quality.QualityConventionsPlugin' + } + strictTestLane { + id = 'ca.strict-test-lane' + implementationClass = 'dev.caskeleton.buildlogic.strictlane.StrictTestLanePlugin' + } + strictLaneStages { + id = 'ca.strict-lane-stages' + implementationClass = 'dev.caskeleton.buildlogic.strictlane.StrictLaneStagesPlugin' + } + architectureRegistrySettings { + id = 'ca.architecture-registry' + implementationClass = 'dev.caskeleton.buildlogic.settings.ArchitectureRegistrySettingsPlugin' + } + javaLibraryConvention { + id = 'ca.java-library' + implementationClass = 'dev.caskeleton.buildlogic.convention.JavaLibraryConventionPlugin' + } + springConfigConvention { + id = 'ca.spring-config' + implementationClass = 'dev.caskeleton.buildlogic.convention.SpringConfigConventionPlugin' + } + platformModuleConvention { + id = 'ca.platform-module' + implementationClass = 'dev.caskeleton.buildlogic.convention.PlatformModuleConventionPlugin' + } + libraryPublishing { + id = 'ca.library-publishing' + implementationClass = 'dev.caskeleton.buildlogic.publishing.LibraryPublishingPlugin' + } + } +} + +tasks.named('test') { + useJUnitPlatform() + // GradleCommandLineTest runs the launcher of the Gradle that runs this build — the distribution + // the workflows' ./gradlew starts — and holds the workflow reader's copy of its command-line + // options to it (review 2026-11-05 RR6-04-02). + systemProperty 'ca.gradle.home', gradle.gradleHomeDir.absolutePath +} diff --git a/build-logic/gradle.lockfile b/build-logic/gradle.lockfile new file mode 100644 index 0000000..6de0fec --- /dev/null +++ b/build-logic/gradle.lockfile @@ -0,0 +1,46 @@ +# This is a Gradle generated file for dependency locking. +# Manual edits can break the build and are not advised. +# This file is expected to be part of source control. +com.diffplug.durian:durian-collect:1.2.0=runtimeClasspath,testRuntimeClasspath +com.diffplug.durian:durian-core:1.2.0=runtimeClasspath,testRuntimeClasspath +com.diffplug.durian:durian-io:1.2.0=runtimeClasspath,testRuntimeClasspath +com.diffplug.durian:durian-swt.os:4.3.0=runtimeClasspath,testRuntimeClasspath +com.diffplug.spotless:spotless-lib-extra:4.6.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +com.diffplug.spotless:spotless-lib:4.6.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +com.diffplug.spotless:spotless-plugin-gradle:8.6.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +com.fasterxml.jackson.core:jackson-annotations:2.21=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +com.github.spotbugs.snom:spotbugs-gradle-plugin:6.5.6=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +com.googlecode.concurrent-trees:concurrent-trees:2.6.1=runtimeClasspath,testRuntimeClasspath +com.googlecode.javaewah:JavaEWAH:1.2.3=runtimeClasspath,testRuntimeClasspath +com.squareup.okhttp3:okhttp:4.12.0=runtimeClasspath,testRuntimeClasspath +com.squareup.okio:okio-jvm:3.6.0=runtimeClasspath,testRuntimeClasspath +com.squareup.okio:okio:3.6.0=runtimeClasspath,testRuntimeClasspath +commons-codec:commons-codec:1.21.0=runtimeClasspath,testRuntimeClasspath +dev.equo.ide:solstice:1.8.1=runtimeClasspath,testRuntimeClasspath +io.spring.gradle:dependency-management-plugin:1.1.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +net.bytebuddy:byte-buddy:1.18.3=testCompileClasspath,testRuntimeClasspath +net.ltgt.gradle:gradle-errorprone-plugin:5.1.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath +org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath +org.eclipse.jgit:org.eclipse.jgit:7.6.0.202603022253-r=runtimeClasspath,testRuntimeClasspath +org.eclipse.platform:org.eclipse.osgi:3.24.100=runtimeClasspath,testRuntimeClasspath +org.jetbrains.kotlin:kotlin-stdlib-common:2.0.21=runtimeClasspath,testRuntimeClasspath +org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.9.10=runtimeClasspath,testRuntimeClasspath +org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.9.10=runtimeClasspath,testRuntimeClasspath +org.jetbrains.kotlin:kotlin-stdlib:2.0.21=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +org.jetbrains:annotations:13.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +org.junit.jupiter:junit-jupiter-api:5.11.3=testCompileClasspath,testRuntimeClasspath +org.junit.jupiter:junit-jupiter-engine:5.11.3=testRuntimeClasspath +org.junit.jupiter:junit-jupiter-params:5.11.3=testCompileClasspath,testRuntimeClasspath +org.junit.jupiter:junit-jupiter:5.11.3=testCompileClasspath,testRuntimeClasspath +org.junit.platform:junit-platform-commons:1.11.3=testCompileClasspath,testRuntimeClasspath +org.junit.platform:junit-platform-engine:1.11.3=testRuntimeClasspath +org.junit.platform:junit-platform-launcher:1.11.3=testRuntimeClasspath +org.junit:junit-bom:5.11.3=testCompileClasspath,testRuntimeClasspath +org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath +org.slf4j:slf4j-api:2.0.17=runtimeClasspath,testRuntimeClasspath +org.tukaani:xz:1.9=runtimeClasspath,testRuntimeClasspath +tools.jackson.core:jackson-core:3.1.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +tools.jackson.core:jackson-databind:3.1.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +tools.jackson:jackson-bom:3.1.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +empty=annotationProcessor,testAnnotationProcessor diff --git a/build-logic/settings-gradle.lockfile b/build-logic/settings-gradle.lockfile new file mode 100644 index 0000000..709a43f --- /dev/null +++ b/build-logic/settings-gradle.lockfile @@ -0,0 +1,4 @@ +# This is a Gradle generated file for dependency locking. +# Manual edits can break the build and are not advised. +# This file is expected to be part of source control. +empty=incomingCatalogForLibs0 diff --git a/build-logic/settings.gradle b/build-logic/settings.gradle new file mode 100644 index 0000000..7b7bb8e --- /dev/null +++ b/build-logic/settings.gradle @@ -0,0 +1,26 @@ +// The included build that holds this repository's convention plugins. +// +// Its own settings are deliberately tiny: an included build for build logic should not need the +// registry validation, toolchain resolution or plugin management the main build does, and giving it +// any of those would make the thing that validates the build depend on the build it validates. +dependencyResolutionManagement { + repositories { + mavenCentral() + gradlePluginPortal() + } + + // The main build's version catalog, read as a file rather than inherited — an included build + // does not see its parent's catalog. + // + // This is not the dependency the note above warns against. It reads a table of versions, not the + // build those versions configure: nothing here is evaluated and no project is resolved. + // Keeping Java/JUnit/plugin coordinates in the shared catalog prevents included-build versions + // from drifting away from the leaf modules they configure. + versionCatalogs { + libs { + from(files('../gradle/libs.versions.toml')) + } + } +} + +rootProject.name = 'build-logic' diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/ApiSurfaceExtension.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/ApiSurfaceExtension.java new file mode 100644 index 0000000..017683c --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/ApiSurfaceExtension.java @@ -0,0 +1,45 @@ +package dev.caskeleton.buildlogic; + +import java.io.File; +import java.util.ArrayList; +import java.util.List; + +/** Declarative configuration for one committed public API surface. */ +public class ApiSurfaceExtension { + private String label; + private File baseline; + private String description; + private List rationale = new ArrayList<>(); + private String sourceRoot = "src/main/java"; + private List additionalSourceRoots = new ArrayList<>(); + private File adopterBaseline; + private Object adopterSources; + + public String getLabel() { return label; } + public void setLabel(String label) { this.label = label; } + public File getBaseline() { return baseline; } + public void setBaseline(File baseline) { this.baseline = baseline; } + public String getDescription() { return description; } + public void setDescription(String description) { this.description = description; } + public List getRationale() { return rationale; } + public void setRationale(List rationale) { + this.rationale = rationale == null ? new ArrayList<>() : new ArrayList<>(rationale); + } + public String getSourceRoot() { return sourceRoot; } + public void setSourceRoot(String sourceRoot) { this.sourceRoot = sourceRoot; } + public List getAdditionalSourceRoots() { return additionalSourceRoots; } + public void setAdditionalSourceRoots(List additionalSourceRoots) { + this.additionalSourceRoots = + additionalSourceRoots == null ? new ArrayList<>() : new ArrayList<>(additionalSourceRoots); + } + + /** + * The reviewed subset of the surface other leaves' production code may import. Optional: without + * it, every public type is fair game to an adopter, which is what the surface alone says. + */ + public File getAdopterBaseline() { return adopterBaseline; } + public void setAdopterBaseline(File adopterBaseline) { this.adopterBaseline = adopterBaseline; } + /** The adopter sources whose imports are held to {@link #getAdopterBaseline()}; any {@code files()} notation. */ + public Object getAdopterSources() { return adopterSources; } + public void setAdopterSources(Object adopterSources) { this.adopterSources = adopterSources; } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/ApiSurfacePolicy.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/ApiSurfacePolicy.java new file mode 100644 index 0000000..fa1ac8e --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/ApiSurfacePolicy.java @@ -0,0 +1,197 @@ +package dev.caskeleton.buildlogic; + +import java.io.File; +import java.io.IOException; +import java.io.UncheckedIOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.util.ArrayList; +import java.util.Collection; +import java.util.List; + +/** Policy and rendering semantics for committed public Java API surfaces. */ +public final class ApiSurfacePolicy { + private ApiSurfacePolicy() {} + + public static String render( + Collection roots, + String label, + String description, + Collection rationale, + String owningProjectPath, + String updateTaskName, + String approvalProperty) { + List types; + try { + types = JavaPublicTypes.render(roots); + } catch (IllegalStateException unparseable) { + throw new IllegalStateException( + owningProjectPath + " " + label + " API surface: " + unparseable.getMessage(), + unparseable); + } + if (types.isEmpty()) { + throw new IllegalStateException( + owningProjectPath + + ": found no public types under " + + String.join(", ", roots.stream().map(File::toString).toList()) + + ". The source roots moved; fix the paths rather than accepting an empty surface."); + } + StringBuilder header = new StringBuilder(); + header.append("# ").append(description).append('\n'); + if (rationale != null) { + rationale.forEach(line -> header.append("# ").append(line).append('\n')); + } + header.append("# Update only after review with:\n"); + header + .append("# ./gradlew ") + .append(owningProjectPath) + .append(':') + .append(updateTaskName) + .append(" -P") + .append(approvalProperty) + .append('\n'); + header.append("# types: ").append(types.size()).append('\n'); + return header + String.join("\n", types) + "\n"; + } + + public static void verify( + String verifyTaskName, + String updateTaskName, + String owningProjectPath, + String approvalProperty, + File baseline, + String rendered) { + if (!baseline.isFile()) { + throw new IllegalStateException( + verifyTaskName + ": missing committed baseline " + baseline); + } + String committed = read(baseline); + if (committed.equals(rendered)) { + return; + } + List committedTypes = surfaceLines(committed); + List renderedTypes = surfaceLines(rendered); + List added = difference(renderedTypes, committedTypes); + List removed = difference(committedTypes, renderedTypes); + throw new IllegalStateException( + verifyTaskName + + ": the public API surface changed.\n" + + (added.isEmpty() ? "" : " added:\n " + String.join("\n ", added) + "\n") + + (removed.isEmpty() ? "" : " removed:\n " + String.join("\n ", removed) + "\n") + + "Review the change, then record it with:\n" + + " ./gradlew " + + owningProjectPath + + ":" + + updateTaskName + + " -P" + + approvalProperty); + } + + /** + * Holds other leaves' imports of this surface to the reviewed adopter subset. + * + *

The surface says what is public; the adopter baseline says which of those public types other + * leaves' production code may depend on. An import of a surface type the adopter baseline does not + * list fails, and so does an adopter entry the surface no longer has. + */ + public static void verifyAdopters( + String verifyTaskName, String rendered, File adopterBaseline, List adopterImports) { + if (!adopterBaseline.isFile()) { + throw new IllegalStateException( + verifyTaskName + ": missing committed adopter baseline " + adopterBaseline); + } + java.util.Set surface = new java.util.HashSet<>(surfaceLines(rendered)); + java.util.Set allowed = new java.util.TreeSet<>(); + for (String line : read(adopterBaseline).lines().toList()) { + if (!line.isBlank() && !line.startsWith("#")) { + allowed.add(line.trim()); + } + } + List stale = allowed.stream().filter(type -> !surface.contains(type)).toList(); + List unreviewed = + adopterImports.stream() + .filter(entry -> { + String type = entry.substring(entry.indexOf(": ") + 2); + return surface.contains(type) && !allowed.contains(type); + }) + .toList(); + if (stale.isEmpty() && unreviewed.isEmpty()) { + return; + } + throw new IllegalStateException( + verifyTaskName + + ": the adopter surface (" + + adopterBaseline.getName() + + ") does not match what other leaves import.\n" + + (unreviewed.isEmpty() + ? "" + : " imported but not in the adopter baseline:\n " + + String.join("\n ", unreviewed) + + "\n") + + (stale.isEmpty() + ? "" + : " in the adopter baseline but not in the public surface:\n " + + String.join("\n ", stale) + + "\n") + + "Add a reviewed type to the adopter baseline, or stop importing it."); + } + + public static void requireNoUnapprovedGrowth( + String updateTaskName, + String owningProjectPath, + String approvalProperty, + String ceilingProperty, + int committedCount, + String rendered, + boolean ceilingRaiseApproved) { + if (ceilingRaiseApproved) { + return; + } + int renderedCount = countTypes(rendered); + if (renderedCount > committedCount) { + throw new IllegalStateException( + updateTaskName + + ": the public surface would grow from " + + committedCount + + " to " + + renderedCount + + " types.\n" + + "Approving additions one at a time is how this leaf got too big to split without anybody deciding to make it so.\n" + + "Either land the addition together with a removal that pays for it, or raise the ceiling deliberately:\n" + + " ./gradlew " + + owningProjectPath + + ":" + + updateTaskName + + " -P" + + approvalProperty + + " -P" + + ceilingProperty); + } + } + + public static int countTypes(String surface) { + return (int) + surface.lines() + .filter(line -> !line.startsWith("#") && !line.trim().isEmpty()) + .count(); + } + + private static List surfaceLines(String surface) { + return surface.lines().filter(line -> !line.startsWith("#")).toList(); + } + + private static List difference(List left, List right) { + ArrayList result = new ArrayList<>(left); + result.removeAll(right); + result.sort(String::compareTo); + return List.copyOf(result); + } + + private static String read(File file) { + try { + return Files.readString(file.toPath(), StandardCharsets.UTF_8); + } catch (IOException exception) { + throw new UncheckedIOException("failed to read " + file, exception); + } + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/JavaPublicTypes.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/JavaPublicTypes.java new file mode 100644 index 0000000..1413753 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/JavaPublicTypes.java @@ -0,0 +1,131 @@ +package dev.caskeleton.buildlogic; + +import com.sun.source.tree.ClassTree; +import com.sun.source.tree.CompilationUnitTree; +import com.sun.source.tree.ImportTree; +import com.sun.source.tree.Tree; +import com.sun.source.util.JavacTask; +import java.io.File; +import java.io.IOException; +import java.io.StringWriter; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.util.ArrayList; +import java.util.Collection; +import java.util.Comparator; +import java.util.List; +import java.util.Set; +import java.util.TreeSet; +import javax.lang.model.element.Modifier; +import javax.tools.Diagnostic; +import javax.tools.DiagnosticCollector; +import javax.tools.JavaCompiler; +import javax.tools.JavaFileObject; +import javax.tools.StandardJavaFileManager; +import javax.tools.ToolProvider; + +/** Public top-level Java types parsed with javac rather than regular expressions. */ +public final class JavaPublicTypes { + private JavaPublicTypes() {} + + public static List render(Collection sourceRoots) { + List sources = new ArrayList<>(); + if (sourceRoots != null) { + for (File root : sourceRoots) { + if (root == null || !root.isDirectory()) { + continue; + } + try (var paths = Files.walk(root.toPath())) { + paths.filter(Files::isRegularFile) + .filter(path -> path.getFileName().toString().endsWith(".java")) + .map(java.nio.file.Path::toFile) + .forEach(sources::add); + } catch (IOException exception) { + throw new IllegalStateException("Could not walk Java source root " + root, exception); + } + } + } + Set types = new TreeSet<>(); + for (CompilationUnitTree unit : parse(sources, "The public API surface")) { + if (unit.getPackageName() == null) { + continue; + } + String packageName = unit.getPackageName().toString(); + for (Tree declaration : unit.getTypeDecls()) { + if (declaration instanceof ClassTree type + && type.getModifiers().getFlags().contains(Modifier.PUBLIC)) { + types.add(packageName + "." + type.getSimpleName()); + } + } + } + return List.copyOf(types); + } + + /** + * Every single-type, non-static import in {@code sources}, as {@code ": "}. + * Wildcard and static imports are not listed; a leaf whose adopters need them is declaring a + * surface this check does not model. + */ + public static List imports(Collection sources) { + List files = + sources == null + ? List.of() + : sources.stream().filter(file -> file.getName().endsWith(".java")).toList(); + Set imports = new TreeSet<>(); + for (CompilationUnitTree unit : parse(files, "The adopter sources")) { + String file = new File(unit.getSourceFile().toUri()).getName(); + for (ImportTree declaration : unit.getImports()) { + String name = declaration.getQualifiedIdentifier().toString(); + if (!declaration.isStatic() && !name.endsWith(".*")) { + imports.add(file + ": " + name); + } + } + } + return List.copyOf(imports); + } + + private static List parse(Collection files, String subject) { + List sources = new ArrayList<>(files); + if (sources.isEmpty()) { + return List.of(); + } + sources.sort(Comparator.comparing(File::getPath)); + + JavaCompiler compiler = ToolProvider.getSystemJavaCompiler(); + if (compiler == null) { + throw new IllegalStateException( + "No Java compiler on this JVM, so the public API surface cannot be parsed. " + + "Run the build on a JDK rather than a JRE — rendering an empty surface " + + "instead would report every public type as removed."); + } + + DiagnosticCollector diagnostics = new DiagnosticCollector<>(); + try (StandardJavaFileManager fileManager = + compiler.getStandardFileManager(diagnostics, null, StandardCharsets.UTF_8)) { + JavacTask task = + (JavacTask) + compiler.getTask( + new StringWriter(), + fileManager, + diagnostics, + List.of("-proc:none"), + null, + fileManager.getJavaFileObjectsFromFiles(sources)); + List units = new ArrayList<>(); + task.parse().forEach(units::add); + List> errors = + diagnostics.getDiagnostics().stream() + .filter(diagnostic -> diagnostic.getKind() == Diagnostic.Kind.ERROR) + .toList(); + if (!errors.isEmpty()) { + String first = + errors.stream().limit(5).map(Object::toString).reduce((a, b) -> a + "\n " + b).orElse(""); + String more = errors.size() > 5 ? "\n (" + (errors.size() - 5) + " more)" : ""; + throw new IllegalStateException(subject + " could not be parsed:\n " + first + more); + } + return units; + } catch (IOException exception) { + throw new IllegalStateException("Could not parse Java source files", exception); + } + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java new file mode 100644 index 0000000..4c292bf --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java @@ -0,0 +1,307 @@ +package dev.caskeleton.buildlogic; + +import java.io.File; +import java.io.IOException; +import java.io.UncheckedIOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.FileVisitResult; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.SimpleFileVisitor; +import java.nio.file.attribute.BasicFileAttributes; +import java.util.ArrayList; +import java.util.HashSet; +import java.util.LinkedHashSet; +import java.util.List; +import java.util.Objects; +import java.util.Set; +import java.util.TreeSet; +import tools.jackson.databind.JsonNode; +import tools.jackson.databind.ObjectMapper; +import tools.jackson.databind.json.JsonMapper; + +/** Typed representation of config/architecture/modules.json. */ +public record ModuleRegistry(List modules, File source) { + private static final ObjectMapper JSON = JsonMapper.builder().build(); + private static final Set REQUIRED_MODULE_FIELDS = + Set.of("id", "gradle_path", "source_path", "allowed_dependencies"); + private static final Set REQUIRED_ROOT_FIELDS = Set.of("modules"); + + public ModuleRegistry { + modules = List.copyOf(modules); + Objects.requireNonNull(source, "source"); + } + + public record Module( + String id, + String gradlePath, + String sourcePath, + File sourceDirectory, + String buildName, + List allowedDependencies) { + public Module { + Objects.requireNonNull(id, "id"); + Objects.requireNonNull(gradlePath, "gradlePath"); + Objects.requireNonNull(sourcePath, "sourcePath"); + Objects.requireNonNull(sourceDirectory, "sourceDirectory"); + Objects.requireNonNull(buildName, "buildName"); + allowedDependencies = List.copyOf(allowedDependencies); + } + } + + public static ModuleRegistry read(File registryFile, File repositoryRoot) { + if (!registryFile.isFile()) { + throw new IllegalStateException("Missing module registry: " + registryFile); + } + JsonNode root; + try { + root = JSON.readTree(Files.readString(registryFile.toPath(), StandardCharsets.UTF_8)); + } catch (IOException exception) { + throw new UncheckedIOException("failed to read " + registryFile, exception); + } + if (root == null || !root.isObject()) { + throw new IllegalStateException("Module registry root must be a JSON object: " + registryFile); + } + Set rootKeys = keys(root); + Set missingRootFields = new TreeSet<>(REQUIRED_ROOT_FIELDS); + missingRootFields.removeAll(rootKeys); + if (!missingRootFields.isEmpty()) { + throw new IllegalStateException( + "Module registry root is missing " + missingRootFields + ": " + registryFile); + } + + JsonNode modulesNode = root.get("modules"); + if (modulesNode == null || !modulesNode.isArray() || modulesNode.isEmpty()) { + throw new IllegalStateException("Module registry has no modules: " + registryFile); + } + + File canonicalRoot; + try { + canonicalRoot = repositoryRoot.getCanonicalFile(); + } catch (IOException exception) { + throw new UncheckedIOException("failed to canonicalize " + repositoryRoot, exception); + } + String rootPrefix = canonicalRoot.getPath() + File.separator; + Set ids = new LinkedHashSet<>(); + Set gradlePaths = new LinkedHashSet<>(); + Set sourceDirectories = new LinkedHashSet<>(); + List modules = new ArrayList<>(); + + for (int index = 0; index < modulesNode.size(); index++) { + JsonNode module = modulesNode.get(index); + if (module == null || !module.isObject()) { + throw new IllegalStateException( + "Module registry entry " + index + " must be a JSON object."); + } + Set missingFields = new TreeSet<>(REQUIRED_MODULE_FIELDS); + missingFields.removeAll(keys(module)); + if (!missingFields.isEmpty()) { + JsonNode rawId = module.get("id"); + String named = + rawId != null && rawId.isString() && !rawId.asText().isBlank() + ? "'" + rawId.asText() + "'" + : "at index " + index; + throw new IllegalStateException( + "Module registry entry " + named + " is missing " + missingFields); + } + + String id = requireNonBlankText(module, "id", index); + String gradlePath = requireNonBlankText(module, "gradle_path", index); + String sourcePath = requireNonBlankText(module, "source_path", index); + // Every module belongs to the one build. A row naming any other build (a typo included) would + // be included by no settings and checked by no direction gate while ci stays green, so the + // field is refused rather than read (the template's optional build, which used it, is gone). + if (module.has("build")) { + throw new IllegalStateException( + "Module registry entry '" + + id + + "' has a 'build' field; every module belongs to the main build, so remove it."); + } + String buildName = "main"; + List allowedDependencies = + requireStringList(module.get("allowed_dependencies"), id, "allowed_dependencies"); + + if (new HashSet<>(allowedDependencies).size() != allowedDependencies.size()) { + throw new IllegalStateException( + "Module registry entry '" + id + "' contains duplicate allowed dependencies."); + } + if (!ids.add(id)) { + throw new IllegalStateException( + "Module registry contains duplicate module id '" + id + "'."); + } + if (!gradlePath.startsWith(":")) { + throw new IllegalStateException( + "Module registry entry '" + + id + + "' has Gradle path '" + + gradlePath + + "' that does not start with ':'."); + } + if (!gradlePaths.add(gradlePath)) { + throw new IllegalStateException( + "Module registry contains duplicate Gradle path '" + gradlePath + "'."); + } + if (new File(sourcePath).isAbsolute()) { + throw new IllegalStateException( + "Module registry entry '" + + id + + "' source path must be repository-root-relative: '" + + sourcePath + + "'."); + } + + File sourceDirectory; + try { + sourceDirectory = new File(canonicalRoot, sourcePath).getCanonicalFile(); + } catch (IOException exception) { + throw new UncheckedIOException("failed to canonicalize " + sourcePath, exception); + } + if (!sourceDirectory.getPath().startsWith(rootPrefix)) { + throw new IllegalStateException( + "Module registry entry '" + + id + + "' source path escapes the repository root: '" + + sourcePath + + "'."); + } + if (!sourceDirectory.isDirectory()) { + throw new IllegalStateException( + "Module registry entry '" + + id + + "' source path is not an existing directory: " + + sourceDirectory); + } + if (!sourceDirectories.add(sourceDirectory.getPath())) { + throw new IllegalStateException( + "Module registry entry '" + + id + + "' resolves to duplicate or aliased canonical source directory: " + + sourceDirectory); + } + modules.add( + new Module( + id, + gradlePath, + sourcePath, + sourceDirectory, + buildName, + allowedDependencies)); + } + + return new ModuleRegistry(modules, registryFile); + } + + public Module byId(String id) { + return modules.stream().filter(module -> module.id().equals(id)).findFirst().orElse(null); + } + + /** + * Build scripts under {@code gradleRoot} that no registered module owns, relative to it. + * + *

The settings plugin includes only registered modules, so a leaf directory nobody registered + * is not compiled, not tested and not compared by any gate, while {@code ci} stays green (review + * 2026-11-01 08-05). The walk skips the root's own script, every directory with its own settings + * script (a separate build, such as build-logic or optional-platforms), build output, and the + * inside of a module's {@code src} tree, where a build script is a test fixture. + */ + public List unregisteredBuildScripts(File gradleRoot) { + Path root = canonical(gradleRoot).toPath(); + Set owned = new HashSet<>(); + for (Module module : modules) { + owned.add(canonical(module.sourceDirectory()).toPath()); + } + List unregistered = new ArrayList<>(); + try { + Files.walkFileTree( + root, + new SimpleFileVisitor<>() { + @Override + public FileVisitResult preVisitDirectory(Path directory, BasicFileAttributes attributes) { + String name = directory.getFileName().toString(); + boolean otherBuild = + !directory.equals(root) + && (Files.isRegularFile(directory.resolve("settings.gradle")) + || Files.isRegularFile(directory.resolve("settings.gradle.kts"))); + boolean moduleSources = + name.equals("src") && owned.contains(directory.getParent()); + if (otherBuild + || moduleSources + || name.equals("build") + // IDE compiler output (Eclipse/VS Code `bin/`, git-ignored as `src/**/bin/`) copies + // resource build scripts such as grpc-codegen's consumer fixtures; it is not source. + || name.equals("bin") + || name.startsWith(".")) { + return FileVisitResult.SKIP_SUBTREE; + } + if (!directory.equals(root) + && !owned.contains(directory) + && (Files.isRegularFile(directory.resolve("build.gradle")) + || Files.isRegularFile(directory.resolve("build.gradle.kts")))) { + String script = + Files.isRegularFile(directory.resolve("build.gradle")) + ? "build.gradle" + : "build.gradle.kts"; + unregistered.add( + root.relativize(directory.resolve(script)).toString().replace(File.separatorChar, '/')); + } + return FileVisitResult.CONTINUE; + } + }); + } catch (IOException exception) { + throw new UncheckedIOException("failed to walk " + root, exception); + } + unregistered.sort(null); + return List.copyOf(unregistered); + } + + private static File canonical(File file) { + try { + return file.getCanonicalFile(); + } catch (IOException exception) { + throw new UncheckedIOException("failed to canonicalize " + file, exception); + } + } + + public List modulesForBuild(String buildName) { + return modules.stream().filter(module -> module.buildName().equals(buildName)).toList(); + } + + private static Set keys(JsonNode node) { + Set result = new LinkedHashSet<>(); + node.properties().forEach(entry -> result.add(entry.getKey())); + return result; + } + + private static String requireNonBlankText(JsonNode node, String field, Object entry) { + JsonNode value = node.get(field); + if (value == null || !value.isString() || value.asText().isBlank()) { + String prefix = entry instanceof Integer ? "entry " + entry : "entry '" + entry + "'"; + throw new IllegalStateException( + "Module registry " + prefix + " needs a nonblank string '" + field + "'."); + } + return value.asText(); + } + + private static List requireStringList(JsonNode raw, String id, String field) { + if (raw == null || !raw.isArray()) { + throw new IllegalStateException( + "Module registry entry '" + id + "' needs a '" + field + "' list."); + } + List result = new ArrayList<>(); + for (int index = 0; index < raw.size(); index++) { + JsonNode value = raw.get(index); + if (value == null || !value.isString() || value.asText().isBlank()) { + throw new IllegalStateException( + "Module registry entry '" + + id + + "' has a non-string or blank " + + field + + " entry at index " + + index + + "."); + } + result.add(value.asText()); + } + return List.copyOf(result); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistrySettingsInstaller.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistrySettingsInstaller.java new file mode 100644 index 0000000..075b5cc --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistrySettingsInstaller.java @@ -0,0 +1,63 @@ +package dev.caskeleton.buildlogic; + +import java.io.File; +import java.io.IOException; +import java.io.UncheckedIOException; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import org.gradle.api.GradleException; +import org.gradle.api.initialization.Settings; + +/** Settings-time adapter mapping one logical build from the shared module registry into Gradle. */ +public final class ModuleRegistrySettingsInstaller { + private ModuleRegistrySettingsInstaller() {} + + public static ModuleRegistry install( + Settings settings, File registryFile, File repositoryRoot, String buildName) { + ModuleRegistry registry; + try { + registry = ModuleRegistry.read(registryFile, repositoryRoot); + } catch (IllegalStateException invalid) { + throw new GradleException(invalid.getMessage(), invalid); + } + + List selected = registry.modulesForBuild(buildName); + if (selected.isEmpty()) { + throw new GradleException( + "Module registry declares no modules for build '" + buildName + "': " + registryFile); + } + + Map namespaceDirectories = new HashMap<>(); + for (ModuleRegistry.Module module : selected) { + settings.include(module.gradlePath()); + settings.project(module.gradlePath()).setProjectDir(module.sourceDirectory()); + + String[] segments = module.gradlePath().substring(1).split(":"); + File directory = module.sourceDirectory(); + for (int size = segments.length - 1; size >= 1; size--) { + directory = directory.getParentFile(); + String parentPath = ":" + String.join(":", java.util.Arrays.copyOf(segments, size)); + File canonical; + try { + canonical = directory.getCanonicalFile(); + } catch (IOException exception) { + throw new UncheckedIOException("failed to canonicalize " + directory, exception); + } + File existing = namespaceDirectories.putIfAbsent(parentPath, canonical); + if (existing != null && !existing.equals(canonical)) { + throw new GradleException( + "Module registry maps namespace '" + + parentPath + + "' to both " + + existing + + " and " + + canonical + + "."); + } + settings.project(parentPath).setProjectDir(canonical); + } + } + return registry; + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/RequiredTestExecution.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/RequiredTestExecution.java new file mode 100644 index 0000000..f46104b --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/RequiredTestExecution.java @@ -0,0 +1,40 @@ +package dev.caskeleton.buildlogic; + +import java.util.ArrayList; +import java.util.Collection; +import java.util.List; + +/** One rule for proving that a named test selector actually executed. */ +public final class RequiredTestExecution { + private static final List SUB_IDENTITY_SEPARATORS = List.of("$", "(", "["); + + private RequiredTestExecution() {} + + public static boolean satisfies(String executed, String required) { + if (executed == null || required == null) { + return false; + } + if (executed.equals(required)) { + return true; + } + return SUB_IDENTITY_SEPARATORS.stream() + .anyMatch(separator -> executed.startsWith(required + separator)); + } + + public static List absent( + Collection required, Collection executed) { + if (required == null || required.isEmpty()) { + return List.of(); + } + Collection observed = executed == null ? List.of() : executed; + List absent = new ArrayList<>(); + for (String requiredSelector : required) { + boolean satisfied = + observed.stream().anyMatch(executedSelector -> satisfies(executedSelector, requiredSelector)); + if (!satisfied) { + absent.add(requiredSelector); + } + } + return List.copyOf(absent); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/ResolvedComponents.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/ResolvedComponents.java new file mode 100644 index 0000000..f1fc2b0 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/ResolvedComponents.java @@ -0,0 +1,47 @@ +package dev.caskeleton.buildlogic; + +import java.util.ArrayDeque; +import java.util.Deque; +import java.util.LinkedHashSet; +import java.util.Set; +import org.gradle.api.artifacts.result.ResolvedComponentResult; +import org.gradle.api.artifacts.result.ResolvedDependencyResult; + +/** + * Walks a resolution result from its root component. + * + *

The architecture tasks used to hold a {@link org.gradle.api.artifacts.Configuration} and call + * {@code getIncoming().getResolutionResult().getAllComponents()} inside the task action. That is + * live build state: Gradle cannot serialise it, so the configuration cache refused to store the + * task, and it resolves a configuration at execution time from whatever project happens to run the + * action. A {@code Provider} taken from {@code getRootComponent()} is the + * supported carrier — it is resolved while the owning project is still configuring, and what the + * task keeps is a value. + * + *

This walk therefore replaces {@code getAllComponents()}, which has no equivalent on the root + * component. The visited set is not an optimisation: a dependency graph is a DAG only in intent, + * and a cycle here would be an infinite loop rather than a diagnosis. + */ +public final class ResolvedComponents { + + private ResolvedComponents() {} + + /** Every component reachable from {@code root}, including {@code root} itself. */ + public static Set reachableFrom(ResolvedComponentResult root) { + Set visited = new LinkedHashSet<>(); + Deque pending = new ArrayDeque<>(); + pending.add(root); + while (!pending.isEmpty()) { + ResolvedComponentResult component = pending.removeFirst(); + if (!visited.add(component)) { + continue; + } + for (var dependency : component.getDependencies()) { + if (dependency instanceof ResolvedDependencyResult resolved) { + pending.add(resolved.getSelected()); + } + } + } + return visited; + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/ApiSurfacePlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/ApiSurfacePlugin.java new file mode 100644 index 0000000..a022dea --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/ApiSurfacePlugin.java @@ -0,0 +1,111 @@ +package dev.caskeleton.buildlogic.apisurface; + +import dev.caskeleton.buildlogic.ApiSurfaceExtension; +import java.io.File; +import java.util.ArrayList; +import java.util.List; +import org.gradle.api.GradleException; +import org.gradle.api.Plugin; +import org.gradle.api.Project; + +public final class ApiSurfacePlugin implements Plugin { + @Override + public void apply(Project project) { + ApiSurfaceExtension extension = + project.getExtensions().create("apiSurface", ApiSurfaceExtension.class); + + project.afterEvaluate( + ignored -> { + String label = extension.getLabel(); + File baseline = extension.getBaseline(); + if ((label == null || label.isBlank()) && baseline == null) { + return; + } + if (label == null || label.isBlank()) { + throw new GradleException( + project.getPath() + " declares an apiSurface baseline without a label"); + } + if (baseline == null) { + throw new GradleException( + project.getPath() + " declares an apiSurface label without a baseline"); + } + + List sourcePaths = new ArrayList<>(); + if (extension.getSourceRoot() != null && !extension.getSourceRoot().isBlank()) { + sourcePaths.add(extension.getSourceRoot()); + } + extension.getAdditionalSourceRoots().stream() + .filter(path -> path != null && !path.isBlank()) + .forEach(sourcePaths::add); + List roots = sourcePaths.stream().map(project::file).toList(); + String verifyTaskName = "verify" + label + "ApiSurface"; + String updateTaskName = "update" + label + "ApiSurface"; + String approvalProperty = "approve" + label + "ApiSurfaceChange"; + String ceilingProperty = "raise" + label + "ApiSurfaceCeiling"; + boolean approved = project.hasProperty(approvalProperty); + boolean ceilingApproved = project.hasProperty(ceilingProperty); + + var verify = + project + .getTasks() + .register( + verifyTaskName, + VerifyApiSurfaceTask.class, + task -> { + task.setGroup("verification"); + task.setDescription( + "Fails without mutation when the committed " + + label + + " public API surface drifts."); + task.getSourceRoots().from(roots); + task.getBaseline().fileValue(baseline); + task.getLabel().set(label); + task.getSurfaceDescription() + .set(extension.getDescription() == null ? "" : extension.getDescription()); + task.getRationale().set(extension.getRationale()); + task.getOwningProjectPath().set(project.getPath()); + task.getUpdateTaskName().set(updateTaskName); + task.getApprovalProperty().set(approvalProperty); + task.getUpdateApproved().set(approved); + if (extension.getAdopterBaseline() != null) { + task.getAdopterBaseline().fileValue(extension.getAdopterBaseline()); + if (extension.getAdopterSources() != null) { + task.getAdopterSources().from(extension.getAdopterSources()); + } + } + }); + + project + .getTasks() + .register( + updateTaskName, + UpdateApiSurfaceTask.class, + task -> { + task.setGroup("verification"); + task.setDescription( + "Rewrites the committed " + + label + + " public API surface baseline after review."); + task.getSourceRoots().from(roots); + task.getBaseline().fileValue(baseline); + task.getLabel().set(label); + task.getSurfaceDescription() + .set(extension.getDescription() == null ? "" : extension.getDescription()); + task.getRationale().set(extension.getRationale()); + task.getOwningProjectPath().set(project.getPath()); + task.getApprovalProperty().set(approvalProperty); + task.getCeilingProperty().set(ceilingProperty); + task.getApproved().set(approved); + task.getCeilingRaiseApproved().set(ceilingApproved); + }); + + // The leaf's `check`, so a pull request that changes a public type fails there (owner + // decision 20, 2026-09-25). It used to run only in `mainCheck`, which reported the change + // after it had merged. + project + .getTasks() + .matching(task -> task.getName().equals("check")) + .configureEach(task -> task.dependsOn(verify)); + }); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/UpdateApiSurfaceTask.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/UpdateApiSurfaceTask.java new file mode 100644 index 0000000..34513dc --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/UpdateApiSurfaceTask.java @@ -0,0 +1,89 @@ +package dev.caskeleton.buildlogic.apisurface; + +import dev.caskeleton.buildlogic.ApiSurfacePolicy; +import java.io.File; +import java.io.IOException; +import java.io.UncheckedIOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.util.List; +import org.gradle.api.DefaultTask; +import org.gradle.api.GradleException; +import org.gradle.api.file.ConfigurableFileCollection; +import org.gradle.api.file.RegularFileProperty; +import org.gradle.api.provider.ListProperty; +import org.gradle.api.provider.Property; +import org.gradle.api.tasks.Input; +import org.gradle.api.tasks.InputFiles; +import org.gradle.api.tasks.OutputFile; +import org.gradle.api.tasks.TaskAction; +import org.gradle.work.DisableCachingByDefault; + +@DisableCachingByDefault(because = "This task intentionally updates a committed review baseline") +public abstract class UpdateApiSurfaceTask extends DefaultTask { + @InputFiles + public abstract ConfigurableFileCollection getSourceRoots(); + + @OutputFile + public abstract RegularFileProperty getBaseline(); + + @Input public abstract Property getLabel(); + @Input public abstract Property getSurfaceDescription(); + @Input public abstract ListProperty getRationale(); + @Input public abstract Property getOwningProjectPath(); + @Input public abstract Property getApprovalProperty(); + @Input public abstract Property getCeilingProperty(); + @Input public abstract Property getApproved(); + @Input public abstract Property getCeilingRaiseApproved(); + + @TaskAction + public void updateSurface() { + if (!getApproved().get()) { + throw new GradleException( + getName() + + " requires -P" + + getApprovalProperty().get() + + ": growing the public surface is a review decision, not a build step."); + } + List roots = getSourceRoots().getFiles().stream().sorted().toList(); + String rendered; + File baseline = getBaseline().get().getAsFile(); + try { + rendered = + ApiSurfacePolicy.render( + roots, + getLabel().get(), + getSurfaceDescription().get(), + getRationale().get(), + getOwningProjectPath().get(), + getName(), + getApprovalProperty().get()); + if (baseline.isFile()) { + ApiSurfacePolicy.requireNoUnapprovedGrowth( + getName(), + getOwningProjectPath().get(), + getApprovalProperty().get(), + getCeilingProperty().get(), + ApiSurfacePolicy.countTypes( + Files.readString(baseline.toPath(), StandardCharsets.UTF_8)), + rendered, + getCeilingRaiseApproved().get()); + } + } catch (IOException exception) { + throw new UncheckedIOException("failed to read " + baseline, exception); + } catch (IllegalStateException invalidSurface) { + throw new GradleException(invalidSurface.getMessage(), invalidSurface); + } + + File parent = baseline.getParentFile(); + if (!parent.isDirectory() && !parent.mkdirs()) { + throw new GradleException("Could not create API surface baseline directory " + parent); + } + try { + Files.writeString(baseline.toPath(), rendered, StandardCharsets.UTF_8); + } catch (IOException exception) { + throw new UncheckedIOException("failed to write " + baseline, exception); + } + getLogger().lifecycle("{}: wrote {}", getName(), baseline); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/VerifyApiSurfaceTask.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/VerifyApiSurfaceTask.java new file mode 100644 index 0000000..14c4dc4 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/VerifyApiSurfaceTask.java @@ -0,0 +1,92 @@ +package dev.caskeleton.buildlogic.apisurface; + +import dev.caskeleton.buildlogic.ApiSurfacePolicy; +import dev.caskeleton.buildlogic.JavaPublicTypes; +import java.io.File; +import java.util.List; +import org.gradle.api.DefaultTask; +import org.gradle.api.GradleException; +import org.gradle.api.file.ConfigurableFileCollection; +import org.gradle.api.file.RegularFileProperty; +import org.gradle.api.provider.ListProperty; +import org.gradle.api.provider.Property; +import org.gradle.api.tasks.Input; +import org.gradle.api.tasks.InputFile; +import org.gradle.api.tasks.InputFiles; +import org.gradle.api.tasks.Internal; +import org.gradle.api.tasks.Optional; +import org.gradle.api.tasks.PathSensitive; +import org.gradle.api.tasks.PathSensitivity; +import org.gradle.api.tasks.TaskAction; +import org.gradle.work.DisableCachingByDefault; + +@DisableCachingByDefault(because = "Verification task has no reusable outputs") +public abstract class VerifyApiSurfaceTask extends DefaultTask { + @InputFiles + public abstract ConfigurableFileCollection getSourceRoots(); + + @Internal + public abstract RegularFileProperty getBaseline(); + + @Input + public String getBaselinePath() { + return getBaseline().get().getAsFile().getAbsolutePath(); + } + + @Input public abstract Property getLabel(); + @Input public abstract Property getSurfaceDescription(); + @Input public abstract ListProperty getRationale(); + @Input public abstract Property getOwningProjectPath(); + @Input public abstract Property getUpdateTaskName(); + @Input public abstract Property getApprovalProperty(); + @Input public abstract Property getUpdateApproved(); + + /** Other leaves' production sources, held to the adopter baseline when one is declared. */ + @InputFiles + @PathSensitive(PathSensitivity.RELATIVE) + public abstract ConfigurableFileCollection getAdopterSources(); + + @Optional + @InputFile + public abstract RegularFileProperty getAdopterBaseline(); + + @TaskAction + public void verifySurface() { + if (getUpdateApproved().get()) { + throw new GradleException( + getName() + + " is read-only; use " + + getUpdateTaskName().get() + + " to record an approved change."); + } + List roots = getSourceRoots().getFiles().stream().sorted().toList(); + try { + String rendered = + ApiSurfacePolicy.render( + roots, + getLabel().get(), + getSurfaceDescription().get(), + getRationale().get(), + getOwningProjectPath().get(), + getUpdateTaskName().get(), + getApprovalProperty().get()); + ApiSurfacePolicy.verify( + getName(), + getUpdateTaskName().get(), + getOwningProjectPath().get(), + getApprovalProperty().get(), + getBaseline().get().getAsFile(), + rendered); + if (getAdopterBaseline().isPresent()) { + ApiSurfacePolicy.verifyAdopters( + getName(), + rendered, + getAdopterBaseline().get().getAsFile(), + JavaPublicTypes.imports(getAdopterSources().getFiles())); + } + } catch (IllegalStateException invalidSurface) { + throw new GradleException(invalidSurface.getMessage(), invalidSurface); + } + getLogger().lifecycle("{}: OK — the committed public API surface is unchanged.", getName()); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java new file mode 100644 index 0000000..cff53c6 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java @@ -0,0 +1,201 @@ +package dev.caskeleton.buildlogic.architecture; + +import dev.caskeleton.buildlogic.ModuleRegistry; +import java.io.File; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.HashSet; +import java.util.List; +import java.util.Set; +import java.util.TreeSet; +import org.gradle.api.Plugin; +import org.gradle.api.Project; +import org.gradle.api.artifacts.Configuration; +import org.gradle.api.artifacts.ProjectDependency; +import org.gradle.api.artifacts.result.ResolvedComponentResult; +import org.gradle.api.provider.Provider; +import org.gradle.api.tasks.SourceSet; +import org.gradle.api.tasks.SourceSetContainer; + +public final class ArchitecturePlugin implements Plugin { + private static final List PRODUCTION_DECLARATIONS = + List.of("api", "implementation", "compileOnly", "runtimeOnly"); + /** The registry, relative to the repository root. */ + public static final String REGISTRY = "config/architecture/modules.json"; + + @Override + public void apply(Project project) { + // One build, rooted at the repository root: the registry is the root's, and every source_path + // is relative to it (the template's main build sits in src/, which is why its copy reads the + // registry relative to the parent). + Project root = project.getRootProject(); + File repositoryRoot = root.getProjectDir(); + File registryFile = new File(repositoryRoot, REGISTRY); + ModuleRegistry registry = ModuleRegistry.read(registryFile, repositoryRoot); + List modules = registry.modulesForBuild("main"); + List registryViolations = registryViolations(registry, modules); + + var clean = + project + .getTasks() + .register( + "verifyCleanArchitectureDependencies", + VerifyCleanArchitectureDependenciesTask.class, + task -> { + task.setGroup("verification"); + task.setDescription("Verifies Clean Architecture project dependency direction."); + task.getRegistryFile().fileValue(registryFile); + task.getRegistryViolations().set(registryViolations); + task.getUnregisteredBuildScripts() + .set(registry.unregisteredBuildScripts(root.getProjectDir())); + }); + var ignoredSources = + project + .getTasks() + .register( + "verifyNoIgnoredSourcePackages", + VerifyNoIgnoredSourcePackagesTask.class, + task -> { + task.setGroup("verification"); + task.setDescription( + "Fails when a Java source file lives in a package that Git ignores or would" + + " ignore."); + task.getBuildRoot().set(root.getLayout().getProjectDirectory()); + }); + + project + .getGradle() + .projectsEvaluated( + ignored -> { + Set declaredModules = new HashSet<>(); + root.getSubprojects().stream() + .filter(sub -> sub.getChildProjects().isEmpty()) + .forEach(sub -> declaredModules.add(sub.getPath().replaceFirst("^:", ""))); + // One task per module, registered in the project that owns the configurations. The + // root task used to walk every other project and resolve its `compileClasspath`, + // which asks Gradle for state another project holds the lock on — with + // `org.gradle.parallel=true` that is a hard failure, and it is why the flag was + // turned off instead of the verification moved. + List moduleTaskPaths = new ArrayList<>(); + for (ModuleRegistry.Module module : modules) { + Project owner = root.project(module.gradlePath()); + Set allowed = new HashSet<>(); + for (String dependencyId : module.allowedDependencies()) { + ModuleRegistry.Module dependency = registry.byId(dependencyId); + if (dependency != null) { + allowed.add(dependency.gradlePath().replaceFirst("^:", "")); + } + } + Set declaredEdges = declaredProjectEdges(owner); + Provider compileClasspathRoot = + owner + .getConfigurations() + .getByName("compileClasspath") + .getIncoming() + .getResolutionResult() + .getRootComponent(); + String moduleName = module.gradlePath().replaceFirst("^:", ""); + owner + .getTasks() + .register( + "verifyModuleDependencyDirection", + VerifyModuleDependencyDirectionTask.class, + task -> { + task.setGroup("verification"); + task.setDescription( + "Verifies this module's declared and compile-visible project edges" + + " against the architecture registry."); + task.getModuleName().set(moduleName); + task.getAllowedDependencies().set(allowed); + task.getDeclaredProjectEdges().set(declaredEdges); + task.getCompileClasspathRoot().set(compileClasspathRoot); + }); + moduleTaskPaths.add(module.gradlePath() + ":verifyModuleDependencyDirection"); + } + clean.configure( + task -> { + task.getDeclaredModules().set(declaredModules); + task.getGovernedModules() + .set( + modules.stream() + .map(module -> module.gradlePath().replaceFirst("^:", "")) + .toList()); + task.dependsOn(moduleTaskPaths); + }); + + // Every source set of every project — testFixtures, integrationTest, systemTest and + // the sample included — because a file Git drops is lost whichever lane owns it. + // Directories under a build directory are generated and never committed. + List sourceRoots = new ArrayList<>(); + for (Project sub : root.getSubprojects()) { + SourceSetContainer sourceSets = + sub.getExtensions().findByType(SourceSetContainer.class); + if (sourceSets == null) { + continue; + } + Path buildDirectory = sub.getLayout().getBuildDirectory().get().getAsFile().toPath(); + for (SourceSet sourceSet : sourceSets) { + for (File sourceRoot : sourceSet.getJava().getSrcDirs()) { + if (!sourceRoot.toPath().startsWith(buildDirectory)) { + sourceRoots.add(sourceRoot); + } + } + } + } + ignoredSources.configure(task -> task.getSourceRoots().from(sourceRoots)); + }); + + project + .getTasks() + .register( + "architectureCheck", + task -> { + task.setGroup("verification"); + task.setDescription("Runs the build's architecture invariants."); + task.dependsOn(clean, ignoredSources); + }); + } + + /** + * This module's declared {@code project(...)} edges, read while the owning project is configured. + * + *

Read here rather than in the task action: a {@link Configuration} cannot be stored in the + * configuration cache, and every declaration this reads is final by {@code projectsEvaluated}. + */ + private static Set declaredProjectEdges(Project owner) { + Set edges = new TreeSet<>(); + for (String name : PRODUCTION_DECLARATIONS) { + Configuration configuration = owner.getConfigurations().findByName(name); + if (configuration == null) { + continue; + } + configuration + .getDependencies() + .withType(ProjectDependency.class) + .forEach(dependency -> edges.add(dependency.getPath().replaceFirst("^:", ""))); + } + return edges; + } + + private static List registryViolations( + ModuleRegistry registry, List modules) { + List violations = new ArrayList<>(); + for (ModuleRegistry.Module module : modules) { + for (String dependencyId : module.allowedDependencies()) { + if (dependencyId.equals(module.id())) { + violations.add("'" + module.id() + "' declares itself as an allowed dependency"); + continue; + } + ModuleRegistry.Module dependency = registry.byId(dependencyId); + if (dependency == null) { + violations.add( + "'" + module.id() + "' allows unknown dependency id '" + dependencyId + "'"); + } else if (!dependency.buildName().equals(module.buildName())) { + violations.add( + "'" + module.id() + "' allows cross-build dependency id '" + dependencyId + "'"); + } + } + } + return List.copyOf(violations); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyCleanArchitectureDependenciesTask.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyCleanArchitectureDependenciesTask.java new file mode 100644 index 0000000..5535631 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyCleanArchitectureDependenciesTask.java @@ -0,0 +1,96 @@ +package dev.caskeleton.buildlogic.architecture; + +import java.util.HashSet; +import java.util.List; +import java.util.Set; +import java.util.TreeSet; +import org.gradle.api.DefaultTask; +import org.gradle.api.GradleException; +import org.gradle.api.file.RegularFileProperty; +import org.gradle.api.provider.ListProperty; +import org.gradle.api.provider.SetProperty; +import org.gradle.api.tasks.Input; +import org.gradle.api.tasks.InputFile; +import org.gradle.api.tasks.TaskAction; +import org.gradle.work.DisableCachingByDefault; + +/** + * The repository-wide half of the dependency contract. + * + *

Two questions only, and both are answered from the registry rather than from any project's + * configurations: is the registry internally consistent, and does the set of modules it governs + * match the set of leaves the build actually declares. A leaf that exists and is ungoverned is the + * failure this catches — a new module cannot be added and quietly escape the direction rules. + * + *

Whether a given module's edges are allowed is {@link VerifyModuleDependencyDirectionTask}'s + * job, one task per module, in the project that owns the configurations. That split is the whole + * point: this task used to resolve every other project's {@code compileClasspath} itself, which + * needs a lock it does not hold, and made {@code org.gradle.parallel=true} fail rather than merely + * be unused. + */ +@DisableCachingByDefault(because = "Verification of live build structure emits no reusable output") +public abstract class VerifyCleanArchitectureDependenciesTask extends DefaultTask { + + @InputFile + public abstract RegularFileProperty getRegistryFile(); + + @Input + public abstract ListProperty getRegistryViolations(); + + /** Every leaf the build declares. */ + @Input + public abstract SetProperty getDeclaredModules(); + + /** Every module the registry governs. */ + @Input + public abstract ListProperty getGovernedModules(); + + /** + * Build scripts under the Gradle root that no registry entry owns. The settings plugin includes + * registered modules only, so such a leaf never reaches {@link #getDeclaredModules()} and the + * comparison below cannot see it (review 2026-11-01 08-05). + */ + @Input + public abstract ListProperty getUnregisteredBuildScripts(); + + @TaskAction + public void verifyDependencies() { + List registryViolations = getRegistryViolations().get(); + if (!registryViolations.isEmpty()) { + throw new GradleException( + "config/architecture/modules.json declares impossible edges:\n " + + String.join("\n ", registryViolations)); + } + + List unregistered = getUnregisteredBuildScripts().get(); + if (!unregistered.isEmpty()) { + throw new GradleException( + "These build scripts have no registry entry, so the build does not include them and no" + + " gate compiles or tests them. Register each in config/architecture/modules.json" + + " or delete it:\n " + + String.join("\n ", unregistered)); + } + + Set declared = getDeclaredModules().get(); + Set governed = new HashSet<>(getGovernedModules().get()); + Set missingFromBuild = new TreeSet<>(governed); + missingFromBuild.removeAll(declared); + Set missingFromPolicy = new TreeSet<>(declared); + missingFromPolicy.removeAll(governed); + if (!missingFromBuild.isEmpty()) { + throw new GradleException( + "Clean Architecture dependency policy references missing Gradle modules " + + missingFromBuild + + ". Declared modules are " + + new TreeSet<>(declared) + + "."); + } + if (!missingFromPolicy.isEmpty()) { + throw new GradleException( + "Gradle modules " + + missingFromPolicy + + " are not covered by verifyCleanArchitectureDependencies. Add an explicit dependency" + + " policy before using them."); + } + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyModuleDependencyDirectionTask.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyModuleDependencyDirectionTask.java new file mode 100644 index 0000000..f22bbf9 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyModuleDependencyDirectionTask.java @@ -0,0 +1,89 @@ +package dev.caskeleton.buildlogic.architecture; + +import dev.caskeleton.buildlogic.ResolvedComponents; +import java.util.HashSet; +import java.util.Set; +import java.util.TreeSet; +import org.gradle.api.DefaultTask; +import org.gradle.api.GradleException; +import org.gradle.api.artifacts.component.ProjectComponentIdentifier; +import org.gradle.api.artifacts.result.ResolvedComponentResult; +import org.gradle.api.provider.Property; +import org.gradle.api.provider.SetProperty; +import org.gradle.api.tasks.Input; +import org.gradle.api.tasks.Internal; +import org.gradle.api.tasks.TaskAction; +import org.gradle.work.DisableCachingByDefault; + +/** + * One module's own dependency-direction check, run by the project that owns the configurations. + * + *

This used to be a loop inside the root task, which reached into every other project and + * resolved its {@code compileClasspath}. That is the one thing a task must not do: a configuration + * belongs to its project, and resolving it from somewhere else asks Gradle for state it holds under + * another project's lock. With {@code org.gradle.parallel=true} that is not a style objection — the + * root task failed outright, which is why the flag was turned back off rather than the verification + * moved. Here the task and the configurations are in the same project, so the check costs the build + * nothing to parallelise. + * + *

The task keeps no {@code Configuration}. It keeps the declared project edges as strings and the + * compile classpath's resolved root component, both established while the owning project is + * configuring. Holding the configurations themselves is what made this task unstorable in the + * configuration cache. + * + *

The root task keeps what is genuinely repository-wide — the registry's own consistency, and + * whether the set of governed modules matches the set of declared ones — and depends on every one of + * these. + */ +@DisableCachingByDefault(because = "Verification inspects live declarations and a resolved classpath") +public abstract class VerifyModuleDependencyDirectionTask extends DefaultTask { + + /** The registry name of the module this task governs. */ + @Input + public abstract Property getModuleName(); + + /** The module ids this module's registry entry permits. */ + @Input + public abstract SetProperty getAllowedDependencies(); + + /** Project paths this module declares in {@code api/implementation/compileOnly/runtimeOnly}. */ + @Input + public abstract SetProperty getDeclaredProjectEdges(); + + /** Root of this module's resolved {@code compileClasspath}. */ + @Internal + public abstract Property getCompileClasspathRoot(); + + @TaskAction + public void verify() { + String moduleName = getModuleName().get(); + Set allowed = getAllowedDependencies().get(); + + Set actual = new HashSet<>(getDeclaredProjectEdges().get()); + // Declared edges are not the whole story: an `api(project(...))` two leaves away is visible to + // this module's compiler and is therefore a real edge, whatever this build file says. + for (ResolvedComponentResult component : + ResolvedComponents.reachableFrom(getCompileClasspathRoot().get())) { + if (component.getId() instanceof ProjectComponentIdentifier project) { + String projectPath = project.getProjectPath().replaceFirst("^:", ""); + if (!projectPath.equals(moduleName)) { + actual.add(projectPath); + } + } + } + + Set forbidden = new TreeSet<>(actual); + forbidden.removeAll(allowed); + if (!forbidden.isEmpty()) { + throw new GradleException( + "Module ':" + + moduleName + + "' has forbidden project dependencies " + + forbidden + + ". Allowed dependencies are " + + new TreeSet<>(allowed) + + ".\nDirect and compile-visible production project edges must be explicitly" + + " registered."); + } + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesTask.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesTask.java new file mode 100644 index 0000000..ecbc1a4 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesTask.java @@ -0,0 +1,157 @@ +package dev.caskeleton.buildlogic.architecture; + +import java.io.File; +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.util.ArrayList; +import java.util.List; +import java.util.Set; +import org.gradle.api.DefaultTask; +import org.gradle.api.GradleException; +import org.gradle.api.file.ConfigurableFileCollection; +import org.gradle.api.file.DirectoryProperty; +import org.gradle.api.tasks.InputFiles; +import org.gradle.api.tasks.Internal; +import org.gradle.api.tasks.PathSensitive; +import org.gradle.api.tasks.PathSensitivity; +import org.gradle.api.tasks.TaskAction; +import org.gradle.work.DisableCachingByDefault; + +@DisableCachingByDefault(because = "Verification consults Git ignore rules") +public abstract class VerifyNoIgnoredSourcePackagesTask extends DefaultTask { + private static final Set OUTPUT_DIRECTORY_NAMES = + Set.of("build", "out", "target", "bin", "classes"); + + @InputFiles + @PathSensitive(PathSensitivity.RELATIVE) + public abstract ConfigurableFileCollection getSourceRoots(); + + @Internal + public abstract DirectoryProperty getBuildRoot(); + + @TaskAction + public void verifySourcePackages() { + List violations = new ArrayList<>(); + List sourceFiles = new ArrayList<>(); + for (File sourceRoot : getSourceRoots().getFiles()) { + if (!sourceRoot.isDirectory()) { + continue; + } + try (var paths = Files.walk(sourceRoot.toPath())) { + paths + .filter(Files::isRegularFile) + .filter(path -> path.getFileName().toString().endsWith(".java")) + .forEach( + path -> { + File candidate = path.toFile(); + sourceFiles.add(candidate); + var relative = sourceRoot.toPath().relativize(path); + for (int index = 0; index < relative.getNameCount() - 1; index++) { + String segment = relative.getName(index).toString(); + if (OUTPUT_DIRECTORY_NAMES.contains(segment)) { + violations.add( + candidate + + ": package segment '" + + segment + + "' collides with a build output directory name"); + } + } + }); + } catch (IOException exception) { + throw new GradleException("verifyNoIgnoredSourcePackages: cannot scan " + sourceRoot, exception); + } + } + if (sourceFiles.isEmpty()) { + throw new GradleException( + "verifyNoIgnoredSourcePackages: found no Java sources at all; the gate would pass vacuously."); + } + + File repositoryRoot = checkoutRoot(getBuildRoot().get().getAsFile()); + if (repositoryRoot == null) { + getLogger().lifecycle("verifyNoIgnoredSourcePackages: not a Git checkout; naming rule only."); + } else { + String stdin = sourceFiles.stream().map(File::getPath).collect(java.util.stream.Collectors.joining("\n")); + String output = checkIgnore(repositoryRoot, stdin); + for (String line : output.lines().filter(value -> !value.isBlank()).toList()) { + String[] parts = line.split("\\t", -1); + String rule = parts.length > 1 ? parts[0] : "(unknown rule)"; + String path = parts.length > 1 ? String.join("\t", java.util.Arrays.copyOfRange(parts, 1, parts.length)) : line; + violations.add(path + ": ignored by " + rule + "; it will not survive a fresh checkout"); + } + } + + if (!violations.isEmpty()) { + throw new GradleException( + "verifyNoIgnoredSourcePackages: " + + violations.size() + + " source file(s) Git cannot carry:\n " + + String.join("\n ", violations)); + } + getLogger() + .lifecycle( + "verifyNoIgnoredSourcePackages: OK — {} Java sources are all committable.", + sourceFiles.size()); + } + + /** + * The nearest directory at or above {@code start} holding {@code .git} (a directory, or the file + * a worktree has), or {@code null} for an exported source tree. Decided on the file system rather + * than by asking Git, so that Git failing inside a checkout cannot read as "not a checkout". + */ + private static File checkoutRoot(File start) { + for (File directory = start.getAbsoluteFile(); directory != null; directory = directory.getParentFile()) { + if (new File(directory, ".git").exists()) { + return directory; + } + } + return null; + } + + /** + * Git's ignore verdicts for the paths on {@code stdin}. Fails closed: inside a checkout, a git that + * cannot run or exits with anything but 0 (some path ignored) or 1 (none ignored) is an error, not + * an empty answer — an empty answer is how the gate used to pass without asking. + */ + private String checkIgnore(File repositoryRoot, String stdin) { + List command = + List.of("git", "-C", repositoryRoot.getPath(), "check-ignore", "--no-index", "-v", "--stdin"); + Process process; + try { + process = new ProcessBuilder(command).start(); + } catch (IOException unavailable) { + throw new GradleException( + "verifyNoIgnoredSourcePackages: " + + repositoryRoot + + " is a Git checkout but git could not run: " + + unavailable.getMessage(), + unavailable); + } + try { + try (var input = process.getOutputStream()) { + input.write(stdin.getBytes(StandardCharsets.UTF_8)); + } catch (IOException exitedEarly) { + // git stopped reading, which it does when it fails; its exit code below says why. + } + String output = new String(process.getInputStream().readAllBytes(), StandardCharsets.UTF_8); + String error = new String(process.getErrorStream().readAllBytes(), StandardCharsets.UTF_8); + int exitCode = process.waitFor(); + if (exitCode != 0 && exitCode != 1) { + throw new GradleException( + "verifyNoIgnoredSourcePackages: `git check-ignore` exited " + + exitCode + + " inside the Git checkout at " + + repositoryRoot + + ": " + + error.strip()); + } + return output; + } catch (IOException unreadable) { + throw new GradleException( + "verifyNoIgnoredSourcePackages: could not read `git check-ignore` output", unreadable); + } catch (InterruptedException interrupted) { + Thread.currentThread().interrupt(); + throw new GradleException("verifyNoIgnoredSourcePackages: git command interrupted", interrupted); + } + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/convention/JavaLibraryConventionPlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/convention/JavaLibraryConventionPlugin.java new file mode 100644 index 0000000..23d745b --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/convention/JavaLibraryConventionPlugin.java @@ -0,0 +1,13 @@ +package dev.caskeleton.buildlogic.convention; + +import org.gradle.api.Plugin; +import org.gradle.api.Project; + +public final class JavaLibraryConventionPlugin implements Plugin { + @Override + public void apply(Project project) { + project.getPluginManager().apply("ca.quality-conventions"); + project.getDependencies().add("testImplementation", "org.junit.jupiter:junit-jupiter"); + project.getDependencies().add("testImplementation", "org.assertj:assertj-core"); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/convention/PlatformModuleConventionPlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/convention/PlatformModuleConventionPlugin.java new file mode 100644 index 0000000..57156ac --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/convention/PlatformModuleConventionPlugin.java @@ -0,0 +1,14 @@ +package dev.caskeleton.buildlogic.convention; + +import org.gradle.api.Plugin; +import org.gradle.api.Project; + +public final class PlatformModuleConventionPlugin implements Plugin { + @Override + public void apply(Project project) { + project.getPluginManager().apply("ca.java-library"); + project.getPluginManager().apply("java-library"); + // Every module of this repository is a published library artifact. + project.getPluginManager().apply("ca.library-publishing"); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/convention/SpringConfigConventionPlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/convention/SpringConfigConventionPlugin.java new file mode 100644 index 0000000..40a641e --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/convention/SpringConfigConventionPlugin.java @@ -0,0 +1,44 @@ +package dev.caskeleton.buildlogic.convention; + +import org.gradle.api.Plugin; +import org.gradle.api.Project; +import org.gradle.api.tasks.PathSensitivity; + +public final class SpringConfigConventionPlugin implements Plugin { + /** + * How a module declares a property the processor cannot see — a switch read only by + * {@code @ConditionalOnProperty} — so the environment contract finds it in the metadata. + */ + private static final String ADDITIONAL_METADATA = + "src/main/resources/META-INF/additional-spring-configuration-metadata.json"; + + @Override + public void apply(Project project) { + project + .getDependencies() + .add("annotationProcessor", "org.springframework.boot:spring-boot-configuration-processor"); + // The processor merges the additional metadata from the processed resources, so compileJava + // runs after processResources and reruns when that one file changes. Without this it could run + // first, or stay up to date when only that file changed, and the declared switch was missing + // from the metadata verifyEnvKeys reads (review 2026-11-04 RR2-04-05). Only that file is an + // input: every other resource leaves compileJava's cache key alone. + project + .getPluginManager() + .withPlugin( + "java", + ignored -> + project + .getTasks() + .named( + "compileJava", + compile -> { + compile.dependsOn(project.getTasks().named("processResources")); + // files(), not file(): most modules have no such file. + compile + .getInputs() + .files(project.file(ADDITIONAL_METADATA)) + .withPropertyName("additionalConfigurationMetadata") + .withPathSensitivity(PathSensitivity.RELATIVE); + })); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/java/JavaConventionsPlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/java/JavaConventionsPlugin.java new file mode 100644 index 0000000..9a62f73 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/java/JavaConventionsPlugin.java @@ -0,0 +1,358 @@ +package dev.caskeleton.buildlogic.java; + +import io.spring.gradle.dependencymanagement.dsl.DependencyManagementExtension; +import java.io.File; +import java.io.IOException; +import java.io.UncheckedIOException; +import java.nio.file.Files; +import java.util.ArrayList; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.Properties; +import java.util.TreeMap; +import org.gradle.api.GradleException; +import org.gradle.api.Plugin; +import org.gradle.api.Project; +import org.gradle.api.artifacts.Configuration; +import org.gradle.api.artifacts.VersionCatalogsExtension; +import org.gradle.api.artifacts.dsl.LockMode; +import org.gradle.api.plugins.JavaPluginExtension; +import org.gradle.api.plugins.jvm.JvmTestSuite; +import org.gradle.api.provider.ProviderFactory; +import org.gradle.api.tasks.PathSensitivity; +import org.gradle.api.tasks.bundling.AbstractArchiveTask; +import org.gradle.api.tasks.bundling.Jar; +import org.gradle.api.tasks.compile.JavaCompile; +import org.gradle.api.tasks.testing.Test; +import org.gradle.jvm.toolchain.JavaLanguageVersion; +import org.gradle.testing.base.TestingExtension; + +public final class JavaConventionsPlugin implements Plugin { + private static final List COMPILER_ARGS = + List.of("-parameters", "-Werror", "-Xlint:deprecation", "-Xlint:unchecked"); + + /** What {@link #sourceRevision} returns when the build was given no commit id. */ + public static final String UNKNOWN_REVISION = "unknown"; + + /** + * The commit this build names: {@code -PgitRevision}, {@code GIT_SHA} or {@code GITHUB_SHA}, cut + * to twelve lowercase hex characters, or {@link #UNKNOWN_REVISION} when none of them is a commit + * id. The root {@code verifyReleaseProvenance} fails on the latter. + */ + public static String sourceRevision(ProviderFactory providers) { + String declared = + providers + .gradleProperty("gitRevision") + .orElse(providers.environmentVariable("GIT_SHA")) + .orElse(providers.environmentVariable("GITHUB_SHA")) + .getOrElse(""); + return declared.matches("(?i)[0-9a-f]{7,40}") + ? declared.toLowerCase(Locale.ROOT).substring(0, Math.min(12, declared.length())) + : UNKNOWN_REVISION; + } + + /** + * The version this build names: the release tag ({@code -PreleaseTag} or {@code RELEASE_TAG}, + * {@code vMAJOR.MINOR.PATCH}) without its {@code v}, else {@code -PreleaseVersion} or {@code + * RELEASE_VERSION}, else {@code 0.0.1}. A tag is how release.yml says which version it publishes, + * so a tag of any other shape fails here, before a single module is built. + */ + public static String releaseVersion(ProviderFactory providers) { + String declared = + providers + .gradleProperty("releaseVersion") + .orElse(providers.environmentVariable("RELEASE_VERSION")) + .getOrElse(""); + String tag = + providers + .gradleProperty("releaseTag") + .orElse(providers.environmentVariable("RELEASE_TAG")) + .getOrElse(""); + if (tag.isEmpty()) { + return declared.isEmpty() ? "0.0.1" : declared; + } + if (!tag.matches("v\\d+\\.\\d+\\.\\d+")) { + throw new GradleException( + "release tag must be vMAJOR.MINOR.PATCH with no suffix; got '" + tag + "'."); + } + String fromTag = tag.substring(1); + if (!declared.isEmpty() && !declared.equals(fromTag)) { + throw new GradleException( + "release tag " + tag + " and releaseVersion " + declared + " name different versions."); + } + return fromTag; + } + + @Override + public void apply(Project project) { + project.getPluginManager().apply("java"); + project.getPluginManager().apply("io.spring.dependency-management"); + // `ca.strict-test-lane` supplies the per-leaf `*TestLaneCheck` aggregates that the root's + // repository-wide tasks depend on by path, so every Java leaf has to have them or the root task + // graph cannot be built. `ca.api-surface` is opt-in: a leaf that wants it says so. + project.getPluginManager().apply("ca.strict-test-lane"); + + var catalog = project.getExtensions().getByType(VersionCatalogsExtension.class).named("libs"); + String springBootVersion = catalog.findVersion("springBoot").orElseThrow().getRequiredVersion(); + + ProviderFactory providers = project.getProviders(); + // The Maven group every module publishes under. A property, not a constant, so this copy of the + // template's convention reads the same in every library repository (gradle.properties). + String libraryGroup = providers.gradleProperty("libraryGroup").getOrElse(""); + if (libraryGroup.isBlank()) { + throw new GradleException("gradle.properties must set libraryGroup (the Maven group)."); + } + project.setGroup(libraryGroup); + String releaseVersion = releaseVersion(providers); + if (!releaseVersion.matches("\\d+\\.\\d+\\.\\d+")) { + throw new GradleException( + "releaseVersion must be MAJOR.MINOR.PATCH without a leading 'v', pre-release or build" + + " metadata; got '" + + releaseVersion + + "'."); + } + // The release version alone, never the revision: a revision in the version put a new jar name in + // every leaf's build/libs on every commit, which is what the deleted archive-hygiene plugin + // existed to clean up (review BUILD-O3-5). The revision stays in each jar's manifest + // (Build-Revision) and in app-bootstrap's build-info.properties, which reads the `sourceRevision` + // extra property set here. This replaced the root `ca.release-provenance` plugin. + String buildRevision = sourceRevision(providers); + project.setVersion(releaseVersion + (buildRevision.equals(UNKNOWN_REVISION) ? "-SNAPSHOT" : "")); + project.getExtensions().getExtraProperties().set("sourceRevision", buildRevision); + + JavaPluginExtension javaExtension = project.getExtensions().getByType(JavaPluginExtension.class); + javaExtension.getToolchain().getLanguageVersion().set(JavaLanguageVersion.of(21)); + + project.getDependencyLocking().lockAllConfigurations(); + project.getDependencyLocking().getLockMode().set(LockMode.STRICT); + + project + .getTasks() + .withType(AbstractArchiveTask.class) + .configureEach( + archive -> { + archive.setPreserveFileTimestamps(false); + archive.setReproducibleFileOrder(true); + archive.dirPermissions(permissions -> permissions.unix("755")); + archive.filePermissions(permissions -> permissions.unix("644")); + }); + project + .getTasks() + .withType(Jar.class) + .configureEach( + jar -> + jar.getManifest() + .attributes( + java.util.Map.of( + "Implementation-Version", project.getVersion().toString(), + "Build-Revision", buildRevision))); + + // Both attributes change on every commit, and every test and SpotBugs task has this jar on its + // runtime classpath: without the normalization a CI build never reuses a cached test result + // (review O-4c). They describe the build, not the classes, so a runtime classpath ignores them. + project + .getNormalization() + .getRuntimeClasspath() + .metaInf( + metaInf -> { + metaInf.ignoreAttribute("Implementation-Version"); + metaInf.ignoreAttribute("Build-Revision"); + }); + + project + .getTasks() + .withType(JavaCompile.class) + .configureEach( + compile -> { + compile.getOptions().setEncoding("UTF-8"); + for (String argument : COMPILER_ARGS) { + if (!compile.getOptions().getCompilerArgs().contains(argument)) { + compile.getOptions().getCompilerArgs().add(argument); + } + } + }); + + // Spring dependency-management reads Maven BOM property overrides from project extra properties. + // commons-lang3: the Boot BOM manages 3.19.0, and the SpotBugs worker (which shares the + // buildscript's commons-lang3) fails with NoClassDefFoundError on it; 3.20.0 is what it needs. + // Delete the override once the BOM manages 3.20.0 or later. (A `netty.version` override sat + // here too and was removed: it pinned the version the BOM already manages, review 2026-11-01 + // O-11c.) + project.getExtensions().getExtraProperties().set("commons-lang3.version", "3.20.0"); + // httpcore5: the Boot BOM manages 5.3.6, and the 5.3 line has no fix for two High advisories + // (CVE-2026-54399, unbounded HTTP/1 header parsing; CVE-2026-54428, unbounded HPACK header + // list). 5.4.3 is the first fixed core. httpclient5 moves with it because each client release + // is built against one core line (5.5 on 5.3, 5.6 on 5.4); 5.6.3 declares 5.4.3 and also + // carries the Content-Encoding connection-leak fix 5.5.2 lacks. Delete both once the BOM + // manages httpcore5 5.4.3 or later. + project.getExtensions().getExtraProperties().set("httpcore5.version", "5.4.3"); + project.getExtensions().getExtraProperties().set("httpclient5.version", "5.6.3"); + DependencyManagementExtension dependencyManagement = + project.getExtensions().getByType(DependencyManagementExtension.class); + dependencyManagement.imports( + imports -> + imports.mavenBom( + "org.springframework.boot:spring-boot-dependencies:" + springBootVersion)); + // The catalog's `pinned-*` libraries: no leaf declares them, and their upstream still brings a + // version with a High or Critical advisory (the catalog says which and from where). Dependency + // management rather than a Gradle constraint because it reaches every configuration, so the + // Checkstyle and Error Prone classpaths get the fixed version too. A leaf that declares one of + // these itself, with a version, still wins. + for (String alias : catalog.getLibraryAliases()) { + if (alias.startsWith("pinned.")) { + var library = catalog.findLibrary(alias).orElseThrow().get(); + String coordinates = + library.getModule() + ":" + library.getVersionConstraint().getRequiredVersion(); + dependencyManagement.dependencies(dependencies -> dependencies.dependency(coordinates)); + } + } + + project + .getDependencies() + .add("testRuntimeOnly", "org.junit.platform:junit-platform-launcher"); + + project.getTasks().named("test", Test.class).configure(Test::useJUnitPlatform); + + // A leaf's extra test source sets are JVM test suites (review BUILD-O3-5 replaced the + // ca.auxiliary-source-set plugin). A suite adds its framework dependency with Gradle's default + // JUnit version, and a version written into a dependency outranks the Spring Boot BOM — so the + // suites would run a different JUnit from `test`. They get the BOM's version instead. + project + .getExtensions() + .getByType(TestingExtension.class) + .getSuites() + .withType(JvmTestSuite.class) + .matching(suite -> !suite.getName().equals("test")) + .configureEach( + suite -> + suite.useJUnitJupiter( + project.provider( + () -> + dependencyManagement + .getManagedVersions() + .get("org.junit.jupiter:junit-jupiter")))); + + // The main-branch stage of this leaf (the root `mainCheck` aggregates every leaf's). Empty unless + // a convention or the leaf attaches a gate that is not worth a pull request's wait. + project + .getTasks() + .register( + "mainCheck", + task -> { + task.setGroup("verification"); + task.setDescription("Runs this leaf's main-branch-stage gates."); + }); + + boolean writeLocksRequested = project.getGradle().getStartParameter().isWriteDependencyLocks(); + var resolveAndLockAll = + project + .getTasks() + .register( + "resolveAndLockAll", + ResolveConfigurationsTask.class, + task -> { + task.setGroup("build setup"); + task.setDescription( + "Resolves every configuration and writes this project's dependency lock state."); + task.getRequireWriteLocks().set(true); + task.getWriteLocksRequested().set(writeLocksRequested); + task.notCompatibleWithConfigurationCache( + "Resolves configurations captured from the owning project"); + }); + var verifyDependencyLocks = + project + .getTasks() + .register( + "verifyDependencyLocks", + ResolveConfigurationsTask.class, + task -> { + task.setGroup("verification"); + task.setDescription( + "Resolves every configuration and fails when strict dependency locks drift."); + task.getRequireWriteLocks().set(false); + task.getWriteLocksRequested().set(writeLocksRequested); + task.notCompatibleWithConfigurationCache( + "Resolves configurations captured from the owning project"); + }); + project.afterEvaluate( + ignored -> { + List resolvable = + project.getConfigurations().stream().filter(Configuration::isCanBeResolved).toList(); + resolveAndLockAll.configure(task -> task.setConfigurationsToResolve(resolvable)); + verifyDependencyLocks.configure(task -> task.setConfigurationsToResolve(resolvable)); + }); + + // The Mockito agent on every Test JVM, attached at startup rather than self-attached. The agent + // is the mockito-core jar alone, hence non-transitive. + Configuration agentDependencies = + project.getConfigurations().dependencyScope("mockitoAgentDependencies").get(); + Configuration agent = + project + .getConfigurations() + .resolvable( + "mockitoAgent", + configuration -> { + configuration.extendsFrom(agentDependencies); + configuration.setTransitive(false); + }) + .get(); + project.getDependencies().add(agentDependencies.getName(), "org.mockito:mockito-core"); + // Every Test JVM runs in UTC, so a timestamp test does not depend on the host's zone. A system + // property rather than a JVM argument: a strict lane's own `jvmArgs` replace the argument list, + // and this used to be repeated in 28 lanes for that reason (review 2026-11-01 O-10b). + // + // The container images the lanes start come from config/testing/container-images.properties, + // each as `ca.test.image.`, with the file as an input (review 2026-11-01 08-04). + File images = containerImageCatalog(project); + Map containerImages = containerImages(images); + project.getExtensions().getExtraProperties().set("testContainerImages", containerImages); + project + .getTasks() + .withType(Test.class) + .configureEach( + test -> { + test.systemProperty("user.timezone", "UTC"); + containerImages.forEach( + (key, image) -> test.systemProperty(CONTAINER_IMAGE_PROPERTY_PREFIX + key, image)); + test.getInputs() + .file(images) + .withPathSensitivity(PathSensitivity.NONE) + .withPropertyName("containerImageCatalog"); + }); + project + .getTasks() + .withType(Test.class) + .configureEach( + test -> { + MockitoAgentArgumentProvider provider = + project.getObjects().newInstance(MockitoAgentArgumentProvider.class); + provider.getMockitoCoreClasspath().from(agent); + provider.getOwner().set(project.getPath() + ":" + test.getName()); + test.getJvmArgumentProviders().add(provider); + }); + } + + /** The system property prefix under which every Test JVM receives the catalog's images. */ + public static final String CONTAINER_IMAGE_PROPERTY_PREFIX = "ca.test.image."; + + private static File containerImageCatalog(Project project) { + File catalog = project.getRootProject().file("config/testing/container-images.properties"); + if (!catalog.isFile()) { + throw new GradleException("Missing test container image catalog: " + catalog); + } + return catalog; + } + + private static Map containerImages(File catalog) { + Properties properties = new Properties(); + try (var in = Files.newInputStream(catalog.toPath())) { + properties.load(in); + } catch (IOException exception) { + throw new UncheckedIOException("failed to read " + catalog, exception); + } + Map images = new TreeMap<>(); + properties.stringPropertyNames().forEach(key -> images.put(key, properties.getProperty(key))); + return Map.copyOf(images); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/java/MockitoAgentArgumentProvider.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/java/MockitoAgentArgumentProvider.java new file mode 100644 index 0000000..9ba5bf9 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/java/MockitoAgentArgumentProvider.java @@ -0,0 +1,38 @@ +package dev.caskeleton.buildlogic.java; + +import java.io.File; +import java.util.Comparator; +import java.util.List; +import org.gradle.api.GradleException; +import org.gradle.api.file.ConfigurableFileCollection; +import org.gradle.api.provider.Property; +import org.gradle.api.tasks.Classpath; +import org.gradle.api.tasks.Input; +import org.gradle.process.CommandLineArgumentProvider; + +public abstract class MockitoAgentArgumentProvider implements CommandLineArgumentProvider { + @Classpath + public abstract ConfigurableFileCollection getMockitoCoreClasspath(); + + @Input + public abstract Property getOwner(); + + @Override + public Iterable asArguments() { + List candidates = + getMockitoCoreClasspath().getFiles().stream() + .filter(File::isFile) + .filter(file -> file.getName().matches("mockito-core-[^/]+\\.jar")) + .sorted(Comparator.comparing(File::getAbsolutePath)) + .toList(); + if (candidates.size() != 1) { + throw new GradleException( + getOwner().get() + + ": expected exactly one mockito-core JAR for the test JVM, found " + + candidates.size() + + ": " + + candidates.stream().map(File::getAbsolutePath).toList()); + } + return List.of("-javaagent:" + candidates.getFirst().getAbsolutePath(), "-Xshare:off"); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/java/ResolveConfigurationsTask.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/java/ResolveConfigurationsTask.java new file mode 100644 index 0000000..bcf9377 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/java/ResolveConfigurationsTask.java @@ -0,0 +1,39 @@ +package dev.caskeleton.buildlogic.java; + +import java.util.List; +import org.gradle.api.DefaultTask; +import org.gradle.api.GradleException; +import org.gradle.api.artifacts.Configuration; +import org.gradle.api.provider.Property; +import org.gradle.api.tasks.Input; +import org.gradle.api.tasks.Internal; +import org.gradle.api.tasks.TaskAction; +import org.gradle.work.DisableCachingByDefault; + +@DisableCachingByDefault(because = "Dependency resolution verifies or writes external lock state") +public abstract class ResolveConfigurationsTask extends DefaultTask { + private List configurations = List.of(); + + @Internal + public List getConfigurationsToResolve() { + return configurations; + } + + public void setConfigurationsToResolve(List configurations) { + this.configurations = List.copyOf(configurations); + } + + @Input + public abstract Property getRequireWriteLocks(); + + @Input + public abstract Property getWriteLocksRequested(); + + @TaskAction + public void resolveConfigurations() { + if (getRequireWriteLocks().get() && !getWriteLocksRequested().get()) { + throw new GradleException(getPath() + " requires the --write-locks command-line flag."); + } + configurations.forEach(Configuration::resolve); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/LibraryPublishingPlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/LibraryPublishingPlugin.java new file mode 100644 index 0000000..88112b7 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/LibraryPublishingPlugin.java @@ -0,0 +1,185 @@ +package dev.caskeleton.buildlogic.publishing; + +import io.spring.gradle.dependencymanagement.dsl.DependencyManagementExtension; +import java.util.List; +import org.gradle.api.GradleException; +import org.gradle.api.Plugin; +import org.gradle.api.Project; +import org.gradle.api.component.AdhocComponentWithVariants; +import org.gradle.api.credentials.HttpHeaderCredentials; +import org.gradle.api.plugins.JavaPluginExtension; +import org.gradle.api.provider.Provider; +import org.gradle.api.publish.PublishingExtension; +import org.gradle.api.publish.maven.MavenPublication; +import org.gradle.api.publish.maven.tasks.PublishToMavenRepository; +import org.gradle.authentication.http.HttpHeaderAuthentication; +import org.gradle.plugins.signing.Sign; +import org.gradle.plugins.signing.SigningExtension; + +/** + * Publishes one library module to the owner's Gitea Maven registry, or to a staging directory. + * + *

Every module publishes one Maven publication, {@code maven}, built from the {@code java} + * component with its sources and javadoc jars. Two repositories: + * + *

    + *
  • {@code gitea}: {@code packagesUrl} from gradle.properties, authenticated with the {@code + * Authorization: token } header. Gitea's job token cannot publish packages, + * so the token is a package-scoped personal access token in a repository secret; it is read + * from the environment and never written to a file. + *
  • {@code staging}: {@code build/staging-repository} under the root project. {@code + * releaseRehearsal} publishes there, so everything up to the upload runs without a secret. + *
+ * + *

Versions: the leaves declare most dependencies without a version and let Spring dependency + * management fill it from a BOM. A published POM or Gradle module file written from the + * declarations would carry no version, so the publication maps every variant's dependencies to + * the versions its own resolution chose ({@code versionMapping}), and the plugin's POM + * customization, which would add the BOM imports a consumer never inherits, is off. + * + *

Signing: with {@code SIGNING_KEY} (an ASCII-armoured PGP secret key, or the base64 of one; + * {@link SigningKeys}) and {@code + * SIGNING_PASSWORD} in the environment, every published file gets an {@code .asc}. Without them + * nothing is signed, and a task that uploads to {@code gitea} fails before it starts: an unsigned + * release is not a release. + */ +public final class LibraryPublishingPlugin implements Plugin { + public static final String PUBLICATION = "maven"; + public static final String GITEA_REPOSITORY = "gitea"; + public static final String STAGING_REPOSITORY = "staging"; + + @Override + public void apply(Project project) { + project.getPluginManager().apply("maven-publish"); + project.getPluginManager().apply("signing"); + + JavaPluginExtension java = project.getExtensions().getByType(JavaPluginExtension.class); + java.withSourcesJar(); + java.withJavadocJar(); + + project + .getExtensions() + .getByType(DependencyManagementExtension.class) + .generatedPomCustomization(customization -> customization.setEnabled(false)); + + // Test fixtures are this repository's own test support (messaging-kafka's, shared by its + // integration lanes); the published testkit is messaging-testkit. They stay out of the + // publication, which also keeps a capability Maven cannot express out of the POM. + project + .getPlugins() + .withId( + "java-test-fixtures", + ignored -> { + AdhocComponentWithVariants component = + (AdhocComponentWithVariants) project.getComponents().getByName("java"); + for (String variant : List.of("testFixturesApiElements", "testFixturesRuntimeElements")) { + component.withVariantsFromConfiguration( + project.getConfigurations().getByName(variant), details -> details.skip()); + } + }); + + Provider packagesUrl = project.getProviders().gradleProperty("packagesUrl"); + Provider repositoryUrl = project.getProviders().gradleProperty("repositoryUrl"); + Provider token = project.getProviders().environmentVariable("PACKAGE_TOKEN"); + + PublishingExtension publishing = project.getExtensions().getByType(PublishingExtension.class); + MavenPublication publication = + publishing + .getPublications() + .create( + PUBLICATION, + MavenPublication.class, + maven -> { + maven.from(project.getComponents().getByName("java")); + maven.versionMapping( + mapping -> mapping.allVariants(variant -> variant.fromResolutionResult())); + maven.pom( + pom -> { + pom.getName().set(project.getName()); + pom.getDescription() + .set( + project.provider( + () -> + project.getDescription() == null + ? project.getName() + : project.getDescription())); + pom.getUrl().set(repositoryUrl); + pom.scm( + scm -> { + scm.getUrl().set(repositoryUrl); + scm.getConnection().set(repositoryUrl.map(url -> "scm:git:" + url + ".git")); + }); + }); + }); + + publishing + .getRepositories() + .maven( + repository -> { + repository.setName(GITEA_REPOSITORY); + repository.setUrl(packagesUrl); + repository.credentials( + HttpHeaderCredentials.class, + credentials -> { + credentials.setName("Authorization"); + credentials.setValue("token " + token.getOrElse("")); + }); + repository.getAuthentication().create("header", HttpHeaderAuthentication.class); + }); + publishing + .getRepositories() + .maven( + repository -> { + repository.setName(STAGING_REPOSITORY); + repository.setUrl( + project + .getRootProject() + .getLayout() + .getBuildDirectory() + .dir("staging-repository")); + }); + + String signingKey = + SigningKeys.armoured(project.getProviders().environmentVariable("SIGNING_KEY").getOrElse("")); + String signingPassword = + project.getProviders().environmentVariable("SIGNING_PASSWORD").getOrElse(""); + boolean signed = !signingKey.isBlank(); + if (signed) { + SigningExtension signing = project.getExtensions().getByType(SigningExtension.class); + signing.useInMemoryPgpKeys(signingKey, signingPassword); + signing.sign(publication); + // The root's verifySigningKey says what is wrong with a key before Gradle's signing reports + // it only as "Could not read PGP secret key". + project.getTasks().withType(Sign.class).configureEach(task -> task.mustRunAfter(":verifySigningKey")); + } + + // Nothing leaves the machine before the release checks have passed, and nothing reaches Gitea + // unsigned or without a token. Gitea refuses a second upload of a version, so a half-published + // version cannot be repaired by publishing it again; the checks run first (design 05, 7.2). + project + .getTasks() + .withType(PublishToMavenRepository.class) + .configureEach( + task -> { + task.mustRunAfter(":releaseCheck"); + if (task.getName().endsWith("To" + capitalized(GITEA_REPOSITORY) + "Repository")) { + task.doFirst( + "requireReleaseCredentials", + ignored -> { + if (!signed) { + throw new GradleException( + "SIGNING_KEY is not set; refusing to publish unsigned files to Gitea."); + } + if (token.getOrElse("").isBlank()) { + throw new GradleException( + "PACKAGE_TOKEN is not set; Gitea's job token cannot publish packages."); + } + }); + } + }); + } + + private static String capitalized(String name) { + return Character.toUpperCase(name.charAt(0)) + name.substring(1); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/SigningKeys.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/SigningKeys.java new file mode 100644 index 0000000..2996b87 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/SigningKeys.java @@ -0,0 +1,42 @@ +package dev.caskeleton.buildlogic.publishing; + +import java.nio.charset.StandardCharsets; +import java.util.Base64; + +/** + * The ASCII-armoured key Gradle's in-memory signatory reads, from what a CI secret holds. + * + *

A secret store keeps a multi-line value badly or not at all, so the common practice is to put + * the armoured key file in base64 on one line ({@code base64 -w0 signing-key.asc}). Gradle's {@code + * useInMemoryPgpKeys} reads only the armoured text and reports the base64 form as "Could not read + * PGP secret key" (v1.0.0 release run 9 and the secret put in after it). Both forms are accepted: + * a value that decodes to an armoured private key block is unwrapped, anything else is passed on + * unchanged, so a wrong value still fails, and {@code verifySigningKey} says why. + */ +public final class SigningKeys { + private static final String BEGIN = "-----BEGIN PGP PRIVATE KEY BLOCK-----"; + + private SigningKeys() {} + + /** + * The armoured key: {@code value} itself, or the armoured block it is the base64 of. + * + * @param value the secret as given (armoured, base64 of the armoured file, or anything else) + * @return the armoured key, or {@code value} unchanged when it is neither form + */ + public static String armoured(String value) { + if (value == null || value.isBlank() || value.contains(BEGIN)) { + return value; + } + String compact = value.replaceAll("\\s", ""); + if (!compact.matches("[A-Za-z0-9+/]+={0,2}")) { + return value; + } + try { + String decoded = new String(Base64.getDecoder().decode(compact), StandardCharsets.UTF_8); + return decoded.strip().startsWith(BEGIN) ? decoded : value; + } catch (IllegalArgumentException notBase64) { + return value; + } + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/QualityConventionsPlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/QualityConventionsPlugin.java new file mode 100644 index 0000000..e5f15fd --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/QualityConventionsPlugin.java @@ -0,0 +1,284 @@ +package dev.caskeleton.buildlogic.quality; + +import com.diffplug.gradle.spotless.SpotlessExtension; +import com.github.spotbugs.snom.Confidence; +import com.github.spotbugs.snom.SpotBugsExtension; +import com.github.spotbugs.snom.SpotBugsReport; +import com.github.spotbugs.snom.SpotBugsTask; +import java.io.File; +import java.util.List; +import net.ltgt.gradle.errorprone.ErrorProneOptions; +import net.ltgt.gradle.errorprone.ErrorProneOptionsKt; +import org.gradle.api.GradleException; +import org.gradle.api.Plugin; +import org.gradle.api.Project; +import org.gradle.api.artifacts.VersionCatalog; +import org.gradle.api.artifacts.VersionCatalogsExtension; +import org.gradle.api.plugins.JavaPluginExtension; +import org.gradle.api.plugins.quality.Checkstyle; +import org.gradle.api.plugins.quality.CheckstyleExtension; +import org.gradle.api.tasks.SourceSet; +import org.gradle.api.tasks.compile.JavaCompile; + +public final class QualityConventionsPlugin implements Plugin { + @Override + public void apply(Project project) { + project.getPluginManager().apply("ca.java-conventions"); + project.getPluginManager().apply("com.diffplug.spotless"); + project.getPluginManager().apply("checkstyle"); + project.getPluginManager().apply("com.github.spotbugs"); + project.getPluginManager().apply("net.ltgt.errorprone"); + + VersionCatalog catalog = + project.getExtensions().getByType(VersionCatalogsExtension.class).named("libs"); + JavaPluginExtension javaExtension = + project.getExtensions().getByType(JavaPluginExtension.class); + SourceSet main = javaExtension.getSourceSets().getByName(SourceSet.MAIN_SOURCE_SET_NAME); + SourceSet test = javaExtension.getSourceSets().getByName(SourceSet.TEST_SOURCE_SET_NAME); + + File repositoryConfigDirectory = project.getRootProject().file("config"); + + SpotlessExtension spotless = project.getExtensions().getByType(SpotlessExtension.class); + spotless.java( + java -> { + java.googleJavaFormat(version(catalog, "googleJavaFormat")); + java.importOrder(); + java.removeUnusedImports(); + }); + + CheckstyleExtension checkstyle = + project.getExtensions().getByType(CheckstyleExtension.class); + checkstyle.setToolVersion(version(catalog, "checkstyle")); + checkstyle.setConfigFile(new File(repositoryConfigDirectory, "checkstyle/checkstyle.xml")); + checkstyle.getConfigDirectory().set(new File(repositoryConfigDirectory, "checkstyle")); + checkstyle.setIgnoreFailures(false); + checkstyle.setMaxWarnings(Integer.MAX_VALUE); + checkstyle.setSourceSets(List.of(main, test)); + + SpotBugsExtension spotBugs = project.getExtensions().getByType(SpotBugsExtension.class); + spotBugs.getToolVersion().set(version(catalog, "spotbugs")); + // MEDIUM (review 2026-11-01 08-07, decided 2026-11-03). HIGH reported 0 findings and left out + // FindSecBugs' injection, ReDoS and weak-crypto rules, which report at MEDIUM. The first MEDIUM + // run over every analysed leaf reported 307 findings, all priority 2, and each was judged + // against the code it names: "fixed" changed the code, "excluded" is a Match in + // config/spotbugs/exclude.xml that carries its reason. + // + // pattern / group found fixed excluded + // EI_EXPOSE_REP, EI_EXPOSE_REP2 196 11 185 + // non-collection references (collaborators) 97 - 97 pattern + // settings binding carriers 43 - 43 by class + // transport DTOs under adapter.inbound 23 - 23 pattern + // collection already copied at construction 20 - 20 class+field + // value type exposing mutable state 13 11 2 per site + // CT_CONSTRUCTOR_THROW 63 24 39 + // made final (21 classes) 24 24 - + // CGLIB-proxied (@RequiresPermission, @Configuration) 30 - 30 annotation + // designed for extension (exception roots, bases) 9 - 9 by class + // SECURITY: REDOS 11, UNSAFE_HASH_EQUALS 7, 25 0 25 per site + // SQL_INJECTION_* 3, PREDICTABLE_RANDOM 2, XSS 1, WEAK_MESSAGE_DIGEST_SHA1 1 + // others 23 11 12 per site + // NP_NULL_ON_SOME_PATH_FROM_RETURN_VALUE 13 (6 fixed), AT_NONATOMIC 2 (fixed), + // NP_NULL_ON_SOME_PATH 1 (fixed), BC_IMPOSSIBLE_INSTANCEOF 1 (fixed), BX_UNBOXING 1 + // (fixed), RV_RETURN_VALUE_IGNORED 2, MS_EXPOSE_REP 2, DLS_DEAD_LOCAL_STORE 1 + // total 307 46 261 + // + // Found afterwards and judged the same way (review 15절, r3-L): the optional-platforms (gRPC) + // build reads this same exclude file and had not been analysed at MEDIUM (13), and the + // httpclient retry jitter source r3-J added (1). + // USO_UNSAFE_METHOD_SYNCHRONIZATION 6 6 - + // GrpcAdmissionController: private lock object + // SECURITY: REDOS 4, UNSAFE_HASH_EQUALS 1, 7 0 7 per site + // COMMAND_INJECTION 1, PREDICTABLE_RANDOM 1 + // CT_CONSTRUCTOR_THROW (GrpcPlatformException root) 1 0 1 by class + // total 14 6 8 + // + // A new finding fails qualityCheck. Fix it, or add a Match scoped to the class and method (or + // field) with the reason it is not a defect. A pattern-wide Match needs a reason that holds for + // every class it can ever match, as the EI reference and DTO patterns state theirs. + spotBugs.getReportLevel().set(Confidence.MEDIUM); + spotBugs.getExcludeFilter().set(new File(repositoryConfigDirectory, "spotbugs/exclude.xml")); + // Keep local check fast; qualityCheck is the explicit bytecode-analysis lane. + spotBugs.getRunOnCheck().set(false); + + // Test code (every source set but main) is analysed too, by testQualityCheck, against its own + // filter: config/spotbugs/exclude-test.xml says which rules do not apply to code that never + // runs in production, and why. Until 2026-11-04 these tasks existed, ran in no gate, and 53 of + // them failed (300 findings) without anyone seeing it. + File testExcludeFilter = new File(repositoryConfigDirectory, "spotbugs/exclude-test.xml"); + // Registered after evaluation on purpose. The SpotBugs plugin registers a task per source set + // and, in that registration, sets the task's auxiliary classpath to the compile classpath. A + // configureEach added before a task is registered runs before that registration action, so + // for every source set created after this plugin (testFixtures, the test suites) an earlier + // configureEach was overwritten and the runtime classpath below never arrived. + project.afterEvaluate( + evaluated -> + evaluated + .getTasks() + .withType(SpotBugsTask.class) + .configureEach( + task -> { + SourceSet analysed = analysedSourceSet(javaExtension, task); + if (analysed == null) { + return; + } + if (!analysed.getName().equals(SourceSet.MAIN_SOURCE_SET_NAME)) { + task.getExcludeFilter().set(testExcludeFilter); + } + // The compile classpath alone leaves out runtime-only types a class still + // links against (org.jboss.logging.BasicLogger, a Resilience4j supertype a + // fixture implements), and the analysis of everything that touches them is + // then incomplete. + task.getAuxClassPaths() + .from(analysed.getRuntimeClasspath().minus(analysed.getOutput())); + })); + project + .getTasks() + .withType(SpotBugsTask.class) + .configureEach( + task -> { + if (analysedSourceSet(javaExtension, task) == null) { + return; + } + // The SpotBugs Gradle plugin rewrites this file without truncating it. A classpath + // shorter than the previous run's (the version drops from `0.0.1+` to + // `0.0.1-SNAPSHOT` once the tree is dirty) keeps the old tail, the last entry reads + // `...-SNAPSHOT.jar.jar`, and SpotBugs reports its classes as missing. + File auxClasspathFile = + project + .getLayout() + .getBuildDirectory() + .file("spotbugs/auxclasspath/" + task.getName()) + .get() + .getAsFile(); + task.doFirst(ignored -> auxClasspathFile.delete()); + SpotBugsReport xml = task.getReports().maybeCreate("xml"); + xml.getRequired().set(true); + task.doLast( + ignored -> { + List failures = + SpotBugsAnalysisReport.failures(xml.getOutputLocation().get().getAsFile()); + if (!failures.isEmpty()) { + throw new GradleException( + task.getPath() + + ": SpotBugs analysis incomplete:\n " + + String.join("\n ", failures)); + } + }); + }); + + project + .getTasks() + .withType(JavaCompile.class) + .configureEach( + compile -> { + ErrorProneOptions options = + ErrorProneOptionsKt.getErrorprone(compile.getOptions()); + options.getDisableWarningsInGeneratedCode().set(true); + }); + + // JMH (me.champeau.jmh) compiles benchmarks and the code it generates from them; neither is + // shipped, and generated code does not answer to the repository's lint or bug patterns. + project + .getPluginManager() + .withPlugin( + "me.champeau.jmh", + ignored -> { + project + .getTasks() + .withType(JavaCompile.class) + .matching( + compile -> + compile.getName().equals("compileJmhJava") + || compile.getName().equals("jmhCompileGeneratedClasses")) + .configureEach( + compile -> { + ErrorProneOptionsKt.getErrorprone(compile.getOptions()) + .getEnabled() + .set(false); + compile.getOptions().getCompilerArgs().removeIf("-Werror"::equals); + }); + project + .getTasks() + .matching( + task -> + task.getName().equals("spotbugsJmh") + || task.getName().equals("checkstyleJmh")) + .configureEach(task -> task.setEnabled(false)); + }); + + project + .getDependencies() + .add( + "spotbugsPlugins", + "com.h3xstream.findsecbugs:findsecbugs-plugin:" + version(catalog, "findsecbugs")); + project + .getDependencies() + .add( + "errorprone", + "com.google.errorprone:error_prone_core:" + version(catalog, "errorprone")); + + project + .getTasks() + .register( + "auxiliaryStyleCheck", + task -> { + task.setGroup("verification"); + task.setDescription( + "Runs Checkstyle for non-default source sets outside the fast local check lane."); + task.dependsOn( + project + .getTasks() + .withType(Checkstyle.class) + .matching( + check -> + !check.getName().equals("checkstyleMain") + && !check.getName().equals("checkstyleTest"))); + }); + project + .getTasks() + .register( + "qualityCheck", + task -> { + task.setGroup("verification"); + task.setDescription("Runs this leaf's SpotBugs and FindSecBugs bytecode analysis."); + task.dependsOn(project.getTasks().named("spotbugsMain")); + }); + project + .getTasks() + .register( + "testQualityCheck", + task -> { + task.setGroup("verification"); + task.setDescription( + "Runs SpotBugs and FindSecBugs over this leaf's test source sets" + + " (config/spotbugs/exclude-test.xml)."); + task.dependsOn( + project + .getTasks() + .withType(SpotBugsTask.class) + .matching( + spotbugs -> + !spotbugs.getName().equals("spotbugsMain") + && !spotbugs.getName().equals("spotbugsJmh"))); + }); + } + + /** The source set a {@code spotbugs} task analyses, or null for any other name. */ + private static SourceSet analysedSourceSet(JavaPluginExtension javaExtension, SpotBugsTask task) { + String suffix = task.getName().substring("spotbugs".length()); + if (suffix.isEmpty()) { + return null; + } + return javaExtension + .getSourceSets() + .findByName(Character.toLowerCase(suffix.charAt(0)) + suffix.substring(1)); + } + + private static String version(VersionCatalog catalog, String alias) { + return catalog + .findVersion(alias) + .orElseThrow( + () -> new GradleException("Version catalog 'libs' must define version '" + alias + "'")) + .getRequiredVersion(); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/SpotBugsAnalysisReport.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/SpotBugsAnalysisReport.java new file mode 100644 index 0000000..17d3d75 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/SpotBugsAnalysisReport.java @@ -0,0 +1,63 @@ +package dev.caskeleton.buildlogic.quality; + +import java.io.File; +import java.util.ArrayList; +import java.util.List; +import javax.xml.parsers.DocumentBuilderFactory; +import org.w3c.dom.Element; +import org.w3c.dom.NodeList; + +final class SpotBugsAnalysisReport { + private SpotBugsAnalysisReport() {} + + static List failures(File reportFile) { + List failures = new ArrayList<>(); + if (!reportFile.isFile()) { + return List.of("missing XML report " + reportFile); + } + try { + DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance(); + factory.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true); + factory.setFeature("http://xml.org/sax/features/external-general-entities", false); + factory.setFeature("http://xml.org/sax/features/external-parameter-entities", false); + factory.setExpandEntityReferences(false); + factory.setXIncludeAware(false); + var document = factory.newDocumentBuilder().parse(reportFile); + NodeList errorsNodes = document.getElementsByTagName("Errors"); + if (errorsNodes.getLength() != 1) { + return List.of("expected one Errors element in " + reportFile.getName()); + } + Element errors = (Element) errorsNodes.item(0); + NodeList missingClasses = errors.getElementsByTagName("MissingClass"); + for (int index = 0; index < missingClasses.getLength(); index++) { + String className = missingClasses.item(index).getTextContent().trim(); + failures.add("missing analysis class " + (className.isBlank() ? "" : className)); + } + NodeList errorNodes = errors.getElementsByTagName("Error"); + for (int index = 0; index < errorNodes.getLength(); index++) { + Element error = (Element) errorNodes.item(index); + NodeList messages = error.getElementsByTagName("ErrorMessage"); + String message = + messages.getLength() == 0 ? "" : messages.item(0).getTextContent().trim(); + failures.add("analysis error " + (message.isBlank() ? "" : message)); + } + validateDeclaredCount(failures, errors, "missingClasses", missingClasses.getLength()); + validateDeclaredCount(failures, errors, "errors", errorNodes.getLength()); + return List.copyOf(failures); + } catch (Exception exception) { + return List.of("unreadable XML report: " + exception.getMessage()); + } + } + + private static void validateDeclaredCount( + List failures, Element errors, String attribute, int observed) { + String declared = errors.getAttribute(attribute); + if (!declared.matches("\\d+")) { + failures.add("invalid " + attribute + " count '" + declared + "'"); + return; + } + if (Integer.parseInt(declared) > observed) { + failures.add(declared + " " + attribute + " reported but only " + observed + " detailed"); + } + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/settings/ArchitectureRegistrySettingsPlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/settings/ArchitectureRegistrySettingsPlugin.java new file mode 100644 index 0000000..8bc01de --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/settings/ArchitectureRegistrySettingsPlugin.java @@ -0,0 +1,22 @@ +package dev.caskeleton.buildlogic.settings; + +import dev.caskeleton.buildlogic.ModuleRegistrySettingsInstaller; +import java.io.File; +import java.io.IOException; +import java.io.UncheckedIOException; +import org.gradle.api.Plugin; +import org.gradle.api.initialization.Settings; + +public final class ArchitectureRegistrySettingsPlugin implements Plugin { + @Override + public void apply(Settings settings) { + try { + // The Gradle root is the repository root here; source_path in the registry is relative to it. + File repositoryRoot = settings.getSettingsDir().getCanonicalFile(); + File registryFile = new File(settings.getSettingsDir(), "config/architecture/modules.json"); + ModuleRegistrySettingsInstaller.install(settings, registryFile, repositoryRoot, "main"); + } catch (IOException exception) { + throw new UncheckedIOException("failed to resolve architecture registry paths", exception); + } + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ExclusiveRealServerLaneService.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ExclusiveRealServerLaneService.java new file mode 100644 index 0000000..add5c0c --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ExclusiveRealServerLaneService.java @@ -0,0 +1,24 @@ +package dev.caskeleton.buildlogic.strictlane; + +import org.gradle.api.services.BuildService; +import org.gradle.api.services.BuildServiceParameters; + +/** + * One slot, shared by every lane that starts a real server or container. + * + *

Turning on {@code org.gradle.parallel} made three web throttle IT cases and a WebSocket + * shutdown contract fail on socket timeouts, and pass when run alone. Those lanes start an embedded + * server and then assert on timing — a permit released at the wrong + * moment, a capacity refusal that has to arrive inside a five-second read timeout, connections + * closed rather than dropped during shutdown. Several of them at once means the machine decides the + * result, not the code, and a gate whose result depends on the machine is the kind this repository's + * own review says gets switched off within a quarter. + * + *

Ordering them inside one leaf was not enough: the contention is across leaves. A build service + * with {@code maxParallelUsages = 1} is Gradle's answer to "these tasks must not overlap", and it + * scopes to exactly the lanes that need it — every strict lane whose category is not {@code TEST}. + * The hermetic unit lanes, which are the bulk of the build and the reason to run in parallel at all, + * are untouched. + */ +public abstract class ExclusiveRealServerLaneService + implements BuildService {} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ShellScript.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ShellScript.java new file mode 100644 index 0000000..4f93013 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ShellScript.java @@ -0,0 +1,1659 @@ +package dev.caskeleton.buildlogic.strictlane; + +import java.util.ArrayDeque; +import java.util.ArrayList; +import java.util.Deque; +import java.util.HashMap; +import java.util.HashSet; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.Set; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +/** + * The simple commands of one {@code run:} script, read as bash reads it, each with the directory + * the shell is in when it runs and why its failure would not fail the step, if it would not. + * + *

It parses the script instead of splitting lines (review 2026-11-04 RR5-02-01): quotes, escapes, + * comments, heredoc bodies, {@code $( )} and backquotes, and the compound commands ({@code if}, + * {@code while}, {@code until}, {@code for}, {@code case}, {@code { }}, {@code ( )}, function + * definitions) are read as the shell reads them, so a {@code cd} inside a heredoc or a multi-line + * string is data, not a directory change. + * + *

A command counts only when it certainly runs and the step certainly fails if it fails (README + * 15, RR5-02-02). Under {@code bash -e} — the default shell of a Linux or macOS runner — that is a + * command whose failure ends the shell, or that is the script's last command. Every other shape is + * returned with the reason it does not count, which is one of three (review 2026-11-05 RR6-04-05): + * + *

    + *
  1. its failure may not fail the step: joined with an {@code ||} other than {@code || exit + * } ({@code || true}, {@code || :}); a pipe's left side without {@code pipefail}; + * {@code !}; a background {@code &}; the condition of {@code if}/{@code while}/{@code until}; + * the part before {@code &&} of a list that is not the script's last command; anything after + * {@code set +e}, or after a {@code trap} whose {@code EXIT} or {@code ERR} action may {@code + * exit} with status 0; + *
  2. it may not run: after {@code ||}; after an {@code &&} of a list that is not the script's + * last command; inside {@code if}/{@code while}/{@code until}/{@code for}/{@code case} or a + * function body; after a top-level {@code exit}, {@code exec } or {@code set -n} + * (it never runs), or 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 ({@code exit 0}, a bare + * {@code exit}, an {@code exit} whose value is not a literal), replace it ({@code exec}) or + * stop it running commands ({@code set -n}, {@code set -o noexec}) first (RR6-04-03); + *
  3. this reader does not read it, although its failure would fail the step: {@code || exit + * } or {@code || { …; exit ; }}, inside {@code { }} or {@code ( )}, a + * command substitution or {@code bash -c}. That is a false failure on purpose (README 16); + * the message says to put the command on a line of its own. + *
+ * + *

An {@code exit} that fails the step — a literal non-zero value, or a bare {@code exit} right + * after {@code ||}, which keeps the failed status — does not stop the commands after it from + * counting: if the script goes on, they run, and if it ends there, the step fails. Neither does one + * in a function no command calls, in a {@code ( )} subshell or a command substitution, which ends + * only that subshell. A bare {@code exit} in an {@code EXIT} trap keeps the status the script was + * ending with, so it does not swallow a failure; in an {@code ERR} trap it returns the status of + * the trap's last command, so it may. + * + *

{@code pipefail} is on when the step's shell is {@code bash} (GitHub runs it as {@code -eo + * pipefail}) or after a top-level {@code set -o pipefail}. A script that does not parse is not + * guessed: its Gradle commands are returned with that reason. + * + *

Which directory a command runs in follows {@code cd } at the top level + * only when it is certain to have run: alone in its list under {@code -e} (a failed {@code cd} ends + * the step), or before the command in the same {@code &&} list. Any other directory change — a + * variable, {@code -}, {@code ~} or an absolute path, {@code pushd}/{@code popd}, {@code builtin + * cd}, {@code eval}/{@code source}, one joined with {@code ||}, piped or in the background, one in + * an {@code &&} list with other commands (for the lines after it), and one anywhere inside a + * compound command or a function body, which may run later or not at all — makes the directory of + * everything after it unread, with the reason. A {@code ( )} subshell is read like the other + * compound commands rather than relied on to keep its {@code cd} to itself: one rule for every + * compound command, and only a false failure if that is too strict. + */ +final class ShellScript { + /** What a message tells a workflow author to do with a stage command this reader does not read. */ + static final String PUT_IT_ON_ITS_OWN_LINE = "put the stage command on a line of its own"; + + private static final String GROUP = "{ … }"; + private static final String SUBSHELL = "a subshell ( … )"; + private static final Pattern INTEGER = Pattern.compile("[+-]?[0-9]+"); + + /** A {@code cd} argument this reader follows: relative, with no variable, glob or {@code ~}. */ + private static final Pattern LITERAL_RELATIVE_PATH = + Pattern.compile("[A-Za-z0-9._][A-Za-z0-9._/-]*"); + + private static final Pattern ASSIGNMENT = Pattern.compile("[A-Za-z_][A-Za-z0-9_]*\\+?=.*"); + private static final Pattern GITHUB_EXPRESSION = Pattern.compile("\\$\\{\\{(.*?)}}"); + private static final Set DIRECTORY_COMMANDS = Set.of("cd", "pushd", "popd"); + /** Commands that may change the directory in a way this reader cannot see. */ + private static final Set OPAQUE_COMMANDS = Set.of("eval", "source", "."); + private static final Set SHELLS = Set.of("bash", "sh"); + private static final Set REDIRECTIONS = + Set.of("<", ">", ">>", ">|", "<>", "<&", ">&", "&>", "&>>", "<<<", "<<", "<<-"); + + /** How the step's shell starts. */ + record Options(boolean errexit, boolean pipefail) {} + + /** + * One simple command. + * + * @param words its words without quotes, from the command word on (leading assignments dropped) + * @param directory where the shell is when it runs, from the repository root; {@code null} for + * the root + * @param unreadDirectory why where it runs is not read, or {@code null} + * @param uncountedReason why its failure would not fail the step, or {@code null} + */ + record Command( + List words, String directory, String unreadDirectory, String uncountedReason) { + Command { + words = List.copyOf(words); + } + } + + private ShellScript() {} + + /** The simple commands of {@code script}, in order, as a shell started with {@code options}. */ + static List commands(String script, String startDirectory, Options options) { + String text = withoutExpressions(script); + Sequence parsed; + try { + parsed = new Parser(text).script(); + } catch (IllegalStateException unreadable) { + return unparsed(text, startDirectory, unreadable.getMessage()); + } + Evaluator evaluator = new Evaluator(ShellDirectory.at(startDirectory), options); + evaluator.top(parsed); + return List.copyOf(evaluator.commands); + } + + /** + * The index of the word the shell runs: past {@code command}, {@code builtin}, {@code exec} and + * {@code env NAME=value…}; -1 when an option of one of them makes it a different action. + */ + static int commandWord(List words) { + int index = 0; + while (index < words.size()) { + String word = words.get(index); + if (word.equals("command") || word.equals("builtin") || word.equals("exec")) { + index++; + } else if (word.equals("env")) { + index++; + while (index < words.size() && ASSIGNMENT.matcher(words.get(index)).matches()) { + index++; + } + } else { + return index; + } + if (index < words.size() && words.get(index).startsWith("-")) { + return -1; + } + } + return index; + } + + /** + * GitHub substitutes {@code ${{ }}} before the shell runs. Its value is unknown here, so the + * expression is kept as one word instead of being split at the spaces inside it. + */ + private static String withoutExpressions(String script) { + return GITHUB_EXPRESSION + .matcher(script) + .replaceAll( + match -> + Matcher.quoteReplacement("${{" + match.group(1).replaceAll("\\s+", "") + "}}")); + } + + /** A script that does not parse: its lines that name gradlew, none of them counted. */ + private static List unparsed(String script, String startDirectory, String problem) { + List commands = new ArrayList<>(); + for (String line : script.split("\n", -1)) { + List words = List.of(line.trim().split("\\s+")); + for (int index = 0; index < words.size(); index++) { + if (words.get(index).endsWith("gradlew")) { + commands.add( + new Command( + words.subList(index, words.size()), + startDirectory, + null, + "its run: script does not parse as a shell script (" + problem + + "), so this check does not read it")); + break; + } + } + } + return commands; + } + + // --------------------------------------------------------------------------------------------- + // Syntax tree + + /** A word: its value without quotes (expansions kept as written) and what it holds. */ + private record Word(String value, boolean quoted, boolean expands, List substitutions) { + boolean isReserved(String reserved) { + return !quoted && value.equals(reserved); + } + } + + private sealed interface Node permits Simple, Compound, FunctionDefinition {} + + private record Simple(List words, List others) implements Node {} + + /** A part of a compound command: a condition, which runs to choose, or a body. */ + private record Part(boolean condition, Sequence body) {} + + private record Compound(String kind, List parts, List others) implements Node {} + + private record FunctionDefinition(String name, Node body) implements Node {} + + private record Pipeline(boolean negated, List commands, String text) {} + + /** Pipelines joined by {@code &&} and {@code ||}, run in the background when {@code async}. */ + private record AndOr(List pipelines, List operators, boolean async) {} + + private record Sequence(List items) {} + + // --------------------------------------------------------------------------------------------- + // Lexer + + private enum Kind { + WORD, + OPERATOR, + NEWLINE, + END + } + + /** A token and where it sits in the script, so a message can quote the script as written. */ + private record Token(Kind kind, String text, Word word, int start, int end) { + boolean is(String operator) { + return kind == Kind.OPERATOR && text.equals(operator); + } + + boolean isWord(String reserved) { + return kind == Kind.WORD && word.isReserved(reserved); + } + } + + private record Heredoc(String delimiter, boolean stripTabs) {} + + private static final class Lexer { + private static final List OPERATORS = + List.of( + ";;&", "&>>", "<<<", "<<-", "&&", "||", ";;", ";&", "|&", "&>", "<<", "<&", "<>", ">>", + ">&", ">|", "&", "|", ";", "(", ")", "<", ">"); + private final String text; + private int position; + private final Deque heredocs = new ArrayDeque<>(); + + Lexer(String text) { + this.text = text; + } + + char at(int index) { + return index < text.length() ? text.charAt(index) : '\0'; + } + + void heredoc(Heredoc heredoc) { + heredocs.add(heredoc); + } + + Token next() { + skipBlanks(); + if (position >= text.length()) { + return new Token(Kind.END, "", null, position, position); + } + char current = text.charAt(position); + if (current == '\n') { + int start = position++; + readHeredocBodies(); + return new Token(Kind.NEWLINE, "\n", null, start, start + 1); + } + if ((current == '<' || current == '>') && at(position + 1) == '(') { + return word(); + } + if (Character.isDigit(current)) { + int end = position; + while (Character.isDigit(at(end))) { + end++; + } + if (at(end) == '<' || at(end) == '>') { + position = end; // a file descriptor number belongs to the redirection after it + return next(); + } + } + for (String operator : OPERATORS) { + if (text.startsWith(operator, position)) { + position += operator.length(); + return new Token(Kind.OPERATOR, operator, null, position - operator.length(), position); + } + } + return word(); + } + + /** Reads {@code (( … ))} once the first {@code (} has been read. */ + void arithmetic() { + position++; // the second ( + int depth = 2; + while (position < text.length() && depth > 0) { + char current = text.charAt(position++); + if (current == '(') { + depth++; + } else if (current == ')') { + depth--; + } + } + if (depth > 0) { + throw new IllegalStateException("an arithmetic (( )) is not closed"); + } + } + + private void skipBlanks() { + while (position < text.length()) { + char current = text.charAt(position); + if (current == ' ' || current == '\t' || current == '\r') { + position++; + } else if (current == '\\' && at(position + 1) == '\n') { + position += 2; + } else if (current == '#') { + while (position < text.length() && text.charAt(position) != '\n') { + position++; + } + } else { + return; + } + } + } + + private void readHeredocBodies() { + while (!heredocs.isEmpty()) { + Heredoc heredoc = heredocs.poll(); + while (position < text.length()) { + int end = text.indexOf('\n', position); + String line = end < 0 ? text.substring(position) : text.substring(position, end); + position = end < 0 ? text.length() : end + 1; + String compared = heredoc.stripTabs() ? line.replaceFirst("^\t+", "") : line; + if (compared.equals(heredoc.delimiter())) { + break; + } + } + } + } + + private Token word() { + int start = position; + StringBuilder value = new StringBuilder(); + boolean quoted = false; + boolean expands = false; + List substitutions = new ArrayList<>(); + while (position < text.length()) { + char current = text.charAt(position); + if (" \t\r\n;&|".indexOf(current) >= 0 + || (current == '(' || current == ')') + || ((current == '<' || current == '>') && at(position + 1) != '(')) { + break; + } + if (current == '\\') { + if (at(position + 1) != '\n') { + value.append(at(position + 1)); + quoted = true; + } + position += 2; + } else if (current == '\'') { + int end = text.indexOf('\'', position + 1); + if (end < 0) { + throw new IllegalStateException("a ' quote is not closed"); + } + value.append(text, position + 1, end); + quoted = true; + position = end + 1; + } else if (current == '"') { + quoted = true; + expands |= doubleQuoted(value, substitutions); + } else if (current == '$' || current == '`') { + expands = true; + dollar(value, substitutions, true); + } else if ((current == '<' || current == '>') && at(position + 1) == '(') { + expands = true; + position++; + substitutions.add(balanced(value.append(current))); + } else { + if (current == '*' || current == '?' || current == '[' || (current == '~' && value.isEmpty())) { + expands = true; + } + value.append(current); + position++; + } + } + return new Token( + Kind.WORD, + value.toString(), + new Word(value.toString(), quoted, expands, substitutions), + start, + position); + } + + /** Reads a {@code "…"} string at the position; whether it holds an expansion. */ + private boolean doubleQuoted(StringBuilder value, List substitutions) { + position++; + boolean expands = false; + while (true) { + if (position >= text.length()) { + throw new IllegalStateException("a \" quote is not closed"); + } + char current = text.charAt(position); + if (current == '"') { + position++; + return expands; + } + if (current == '\\') { + char escaped = at(position + 1); + if ("$`\"\\".indexOf(escaped) >= 0) { + value.append(escaped); + } else if (escaped != '\n') { + value.append(current).append(escaped); + } + position += 2; + } else if (current == '$' || current == '`') { + expands = true; + dollar(value, substitutions, false); + } else { + value.append(current); + position++; + } + } + } + + /** Reads an expansion starting with {@code $} or a backquote, keeping it as written. */ + private void dollar(StringBuilder value, List substitutions, boolean unquoted) { + char current = text.charAt(position); + if (current == '`') { + int end = position + 1; + while (end < text.length() && text.charAt(end) != '`') { + end += text.charAt(end) == '\\' ? 2 : 1; + } + if (end >= text.length()) { + throw new IllegalStateException("a ` substitution is not closed"); + } + substitutions.add(text.substring(position + 1, end)); + value.append(text, position, end + 1); + position = end + 1; + return; + } + char next = at(position + 1); + if (next == '(' && at(position + 2) == '(') { + int start = position; + position++; // balanced() reads (( … )) from the first ( + balanced(new StringBuilder()); + value.append(text, start, position); + } else if (next == '(') { + value.append('$'); + position++; + substitutions.add(balanced(value)); + } else if (next == '{') { + int start = position; + int depth = 0; + do { + char inside = at(position); + if (inside == '\0') { + throw new IllegalStateException("a ${ expansion is not closed"); + } + depth += inside == '{' ? 1 : inside == '}' ? -1 : 0; + position++; + } while (depth > 0); + value.append(text, start, position); + } else if (next == '\'' && unquoted) { + int end = position + 2; + while (end < text.length() && text.charAt(end) != '\'') { + end += text.charAt(end) == '\\' ? 2 : 1; + } + if (end >= text.length()) { + throw new IllegalStateException("a $' quote is not closed"); + } + value.append(text, position + 2, end); + position = end + 1; + } else { + int end = position + 1; + if (Character.isLetter(next) || next == '_') { + while (Character.isLetterOrDigit(at(end)) || at(end) == '_') { + end++; + } + } else if ("0123456789@*#?$!-".indexOf(next) >= 0 && next != '\0') { + end++; + } + value.append(text, position, end); + position = end; + } + } + + /** + * Reads from an opening {@code (} at the position to its match, appending it to {@code value}; + * the text between them. + */ + private String balanced(StringBuilder value) { + int start = position; + int depth = 0; + while (position < text.length()) { + char current = text.charAt(position); + if (current == '\\') { + position += 2; + continue; + } + if (current == '\'') { + int end = text.indexOf('\'', position + 1); + position = end < 0 ? text.length() : end + 1; + continue; + } + if (current == '"') { + doubleQuoted(new StringBuilder(), new ArrayList<>()); + continue; + } + if (current == '(') { + depth++; + } else if (current == ')') { + depth--; + if (depth == 0) { + position++; + value.append(text, start, position); + return text.substring(start + 1, position - 1); + } + } + position++; + } + throw new IllegalStateException("a ( is not closed"); + } + } + + // --------------------------------------------------------------------------------------------- + // Parser + + private static final class Parser { + private final String source; + private final Lexer lexer; + private Token peeked; + private int lastEnd; + + Parser(String text) { + source = text; + lexer = new Lexer(text); + } + + Sequence script() { + Sequence sequence = sequence(Set.of()); + if (peek().kind() != Kind.END) { + throw new IllegalStateException("unexpected '" + peek().text() + "'"); + } + return sequence; + } + + private Token peek() { + if (peeked == null) { + peeked = lexer.next(); + } + return peeked; + } + + private Token next() { + Token token = peek(); + peeked = null; + lastEnd = Math.max(lastEnd, token.end()); + return token; + } + + private void skipNewlines() { + while (peek().kind() == Kind.NEWLINE) { + next(); + } + } + + private void expectWord(String reserved) { + skipNewlines(); + Token token = next(); + if (!token.isWord(reserved)) { + throw new IllegalStateException("expected '" + reserved + "' but found '" + token.text() + "'"); + } + } + + private boolean ends(Token token, Set terminators) { + return token.kind() == Kind.END + || token.is(")") + || token.is(";;") + || token.is(";&") + || token.is(";;&") + || (token.kind() == Kind.WORD && !token.word().quoted() && terminators.contains(token.text())); + } + + /** And-or lists until one of {@code terminators} stands where a command would. */ + private Sequence sequence(Set terminators) { + List items = new ArrayList<>(); + while (true) { + while (peek().kind() == Kind.NEWLINE || peek().is(";")) { + next(); + } + if (ends(peek(), terminators)) { + return new Sequence(items); + } + List pipelines = new ArrayList<>(); + List operators = new ArrayList<>(); + pipelines.add(pipeline()); + while (peek().is("&&") || peek().is("||")) { + operators.add(next().text()); + skipNewlines(); + pipelines.add(pipeline()); + } + boolean async = peek().is("&"); + if (async) { + next(); + } + items.add(new AndOr(pipelines, operators, async)); + } + } + + private Pipeline pipeline() { + int start = peek().start(); + boolean negated = false; + while (peek().isWord("!") || peek().isWord("time")) { + Token prefix = next(); + negated |= prefix.text().equals("!"); + if (prefix.text().equals("time") && peek().isWord("-p")) { + next(); + } + } + List commands = new ArrayList<>(); + commands.add(command()); + while (peek().is("|") || peek().is("|&")) { + next(); + skipNewlines(); + commands.add(command()); + } + return new Pipeline(negated, commands, asWritten(source.substring(start, lastEnd))); + } + + /** The pipeline as written, on one line and cut short: what a message quotes. */ + private static String asWritten(String text) { + String line = text.strip().replaceAll("\\s*\n\\s*", " "); + return line.length() <= 100 ? line : line.substring(0, 97) + "..."; + } + + private Node command() { + Token token = peek(); + if (token.is("(")) { + next(); + if (lexer.at(lexer.position) == '(') { + lexer.arithmetic(); + return new Compound("(( ))", List.of(), redirections(new ArrayList<>())); + } + Sequence body = sequence(Set.of()); + if (!next().is(")")) { + throw new IllegalStateException("a ( subshell is not closed"); + } + return new Compound( + SUBSHELL, List.of(new Part(false, body)), redirections(new ArrayList<>())); + } + if (token.kind() != Kind.WORD) { + throw new IllegalStateException("unexpected '" + token.text() + "'"); + } + Word word = token.word(); + if (!word.quoted()) { + switch (word.value()) { + case "if" -> { + return ifCommand(); + } + case "while", "until" -> { + next(); + Sequence condition = sequence(Set.of("do")); + expectWord("do"); + Sequence body = sequence(Set.of("done")); + expectWord("done"); + return new Compound( + word.value() + " … done", + List.of(new Part(true, condition), new Part(false, body)), + redirections(new ArrayList<>())); + } + case "for", "select" -> { + return forCommand(word.value()); + } + case "case" -> { + return caseCommand(); + } + case "{" -> { + next(); + Sequence body = sequence(Set.of("}")); + expectWord("}"); + return new Compound( + GROUP, List.of(new Part(false, body)), redirections(new ArrayList<>())); + } + case "[[" -> { + next(); + List others = new ArrayList<>(); + while (!peek().isWord("]]")) { + Token inside = next(); + if (inside.kind() == Kind.END || inside.kind() == Kind.NEWLINE) { + throw new IllegalStateException("a [[ is not closed"); + } + if (inside.kind() == Kind.WORD) { + others.add(inside.word()); + } + } + next(); + return new Compound("[[ ]]", List.of(), redirections(others)); + } + case "function" -> { + next(); + Token name = next(); + if (peek().is("(")) { + next(); + if (!next().is(")")) { + throw new IllegalStateException("expected ) after function " + name.text() + "("); + } + } + skipNewlines(); + return new FunctionDefinition(name.text(), command()); + } + default -> { + // a simple command or a name() definition + } + } + } + return simple(); + } + + private Node ifCommand() { + next(); + List parts = new ArrayList<>(); + parts.add(new Part(true, sequence(Set.of("then")))); + expectWord("then"); + parts.add(new Part(false, sequence(Set.of("elif", "else", "fi")))); + while (true) { + skipNewlines(); + Token token = next(); + if (token.isWord("elif")) { + parts.add(new Part(true, sequence(Set.of("then")))); + expectWord("then"); + parts.add(new Part(false, sequence(Set.of("elif", "else", "fi")))); + } else if (token.isWord("else")) { + parts.add(new Part(false, sequence(Set.of("fi")))); + expectWord("fi"); + break; + } else if (token.isWord("fi")) { + break; + } else { + throw new IllegalStateException("an if is not closed by fi"); + } + } + return new Compound("if … fi", parts, redirections(new ArrayList<>())); + } + + private Node forCommand(String keyword) { + next(); + List header = new ArrayList<>(); + if (peek().is("(") && lexer.at(lexer.position) == '(') { + next(); + lexer.arithmetic(); + } else { + Token name = next(); + if (name.kind() != Kind.WORD) { + throw new IllegalStateException("expected a name after " + keyword); + } + skipNewlines(); + if (peek().isWord("in")) { + next(); + while (peek().kind() == Kind.WORD) { + header.add(next().word()); + } + } + } + while (peek().is(";") || peek().kind() == Kind.NEWLINE) { + next(); + } + expectWord("do"); + Sequence body = sequence(Set.of("done")); + expectWord("done"); + return new Compound(keyword + " … done", List.of(new Part(false, body)), redirections(header)); + } + + private Node caseCommand() { + next(); + List header = new ArrayList<>(); + Token subject = next(); + if (subject.kind() != Kind.WORD) { + throw new IllegalStateException("expected a word after case"); + } + header.add(subject.word()); + expectWord("in"); + List parts = new ArrayList<>(); + while (true) { + skipNewlines(); + if (peek().isWord("esac")) { + next(); + break; + } + if (peek().is("(")) { + next(); + } + while (!peek().is(")")) { + Token pattern = next(); + if (pattern.kind() == Kind.END || pattern.kind() == Kind.NEWLINE) { + throw new IllegalStateException("a case pattern is not closed by )"); + } + } + next(); + parts.add(new Part(false, sequence(Set.of("esac")))); + if (peek().is(";;") || peek().is(";&") || peek().is(";;&")) { + next(); + } + } + return new Compound("case … esac", parts, redirections(header)); + } + + private Node simple() { + List words = new ArrayList<>(); + List others = new ArrayList<>(); + while (true) { + Token token = peek(); + if (token.kind() == Kind.WORD) { + next(); + if (words.isEmpty() && !token.word().quoted() + && ASSIGNMENT.matcher(token.word().value()).matches()) { + others.add(token.word()); + } else { + words.add(token.word()); + } + if (words.size() == 1 && others.isEmpty() && peek().is("(")) { + next(); + if (!next().is(")")) { + throw new IllegalStateException("expected ) in " + token.text() + "()"); + } + skipNewlines(); + return new FunctionDefinition(token.text(), command()); + } + } else if (token.kind() == Kind.OPERATOR && REDIRECTIONS.contains(token.text())) { + redirection(others); + } else { + break; + } + } + if (words.isEmpty() && others.isEmpty()) { + throw new IllegalStateException("unexpected '" + peek().text() + "'"); + } + return new Simple(words, others); + } + + private List redirections(List others) { + while (peek().kind() == Kind.OPERATOR && REDIRECTIONS.contains(peek().text())) { + redirection(others); + } + return others; + } + + private void redirection(List others) { + String operator = next().text(); + Token target = next(); + if (target.kind() != Kind.WORD) { + throw new IllegalStateException("a " + operator + " has no target"); + } + if (operator.equals("<<") || operator.equals("<<-")) { + lexer.heredoc(new Heredoc(target.word().value(), operator.equals("<<-"))); + } else { + others.add(target.word()); + } + } + } + + // --------------------------------------------------------------------------------------------- + // Evaluation + + /** + * Where the shell is: a path from the repository root ({@code null} for the root), or, once a + * directory change is not followed, why — the first such reason is kept. + */ + private record ShellDirectory(String path, String unread) { + static ShellDirectory at(String path) { + return new ShellDirectory(path, null); + } + + ShellDirectory cd(String target) { + return unread != null + ? this + : at( + WorkflowGradleInvocations.Invocation.normalized( + (path == null ? "." : path) + "/" + target)); + } + + ShellDirectory unreadBecause(String reason) { + return unread != null ? this : new ShellDirectory(path, reason); + } + } + + /** What a {@code set} command does to the options this reader follows. */ + private record SetEffect(Boolean errexit, Boolean pipefail, Boolean noexec, boolean unknown) {} + + /** A function an {@code EXIT} or {@code ERR} trap calls that was not defined when it was set. */ + private record TrapCall(String trap, boolean bareExitKeepsStatus) {} + + /** A simple command the shell runs, with whether it runs in this shell and right after {@code ||}. */ + private interface CommandVisitor { + void visit(Simple simple, boolean mainShell, boolean afterOr); + } + + private static final class Evaluator { + private final List commands = new ArrayList<>(); + private ShellDirectory directory; + /** Why a failed command no longer ends the shell, or {@code null} while {@code -e} is on. */ + private String errexitOff; + private boolean pipefail; + /** Why nothing after this point runs, or {@code null}. */ + private String terminated; + /** Why the script may have ended before this point, or {@code null}. */ + private String mayHaveEnded; + /** Why a failure after this point may still end the script with status 0, or {@code null}. */ + private String exitTrap; + /** The functions defined so far, by name. */ + private final Map functions = new HashMap<>(); + /** Commands an {@code EXIT}/{@code ERR} trap runs, by name, in case a function defines them. */ + private final Map trapCalls = new HashMap<>(); + /** How deep the reader is in function bodies it reads where they are defined, not called. */ + private int definingFunction; + + Evaluator(ShellDirectory start, Options options) { + directory = start; + errexitOff = options.errexit() ? null : "its shell does not stop at a failed command"; + pipefail = options.pipefail(); + } + + void top(Sequence script) { + for (int index = 0; index < script.items().size(); index++) { + topList(script.items().get(index), index == script.items().size() - 1); + } + } + + /** One and-or list at the top level of the script. */ + private void topList(AndOr list, boolean last) { + List pipelines = list.pipelines(); + List operators = list.operators(); + ShellDirectory current = directory; + String followedCd = null; + boolean directoryChanged = false; + boolean alone = + pipelines.size() == 1 && !list.async() && !pipelines.get(0).negated() + && pipelines.get(0).commands().size() == 1; + for (int index = 0; index < pipelines.size(); index++) { + Pipeline pipeline = pipelines.get(index); + String text = "`" + pipeline.text() + "`"; + String previous = index > 0 ? operators.get(index - 1) : null; + String next = index < operators.size() ? operators.get(index) : null; + if (followedCd != null && !"&&".equals(previous)) { + current = + current.unreadBecause( + text + " follows " + followedCd + " through " + previous + + ", so it may run where that cd did not take the shell"); + } + Simple directoryCommand = directoryCommand(pipeline); + if (directoryCommand != null) { + directoryChanged = true; + String target = followableTarget(directoryCommand); + if (target == null) { + current = + current.unreadBecause( + text + " is not a cd to a literal relative path (a variable, -, ~, an absolute" + + " path, pushd, popd, builtin cd, eval and source are not followed)"); + } else if (pipeline.commands().size() > 1 || pipeline.negated() || list.async()) { + current = + current.unreadBecause( + text + " is piped, negated or in the background, so it ran in a subshell"); + } else if ("||".equals(next) || operators.subList(0, index).contains("||")) { + current = + current.unreadBecause( + text + " is joined with ||, so it may not have run, or ran in a subshell"); + } else if (terminated == null) { + current = current.cd(target); + followedCd = text; + } + } + pipeline( + pipeline, + current, + listReason(list, index, last), + alone, + pipeline.commands().size() == 1 && !list.async(), + "||".equals(previous)); + } + if (directoryChanged) { + if (pipelines.size() > 1 && followedCd != null) { + current = + current.unreadBecause( + followedCd + " shares an && list with other commands, and if it failed the shell" + + " went on to the next line in the old directory"); + } else if (followedCd != null && errexitOff != null) { + current = + current.unreadBecause( + followedCd + " may fail and the shell go on in the old directory, because " + + errexitOff); + } + directory = current; + } + } + + /** + * Why a command in pipeline {@code index} of {@code list} may not run or may not fail the step, + * or null. + */ + private String listReason(AndOr list, int index, boolean last) { + List operators = list.operators(); + if (terminated != null) { + return terminated; + } + if (mayHaveEnded != null) { + return mayHaveEnded; + } + if (exitTrap != null) { + return exitTrap; + } + if (list.async()) { + return "it runs in the background (&), so the step does not wait for it and its failure" + + " cannot fail the step"; + } + int orBefore = operators.subList(0, index).lastIndexOf("||"); + if (orBefore >= 0) { + return "it follows `" + list.pipelines().get(orBefore).text() + + "` through ||, so it may not run: it runs only when that fails"; + } + int orAfter = operators.subList(index, operators.size()).indexOf("||"); + if (orAfter >= 0) { + Pipeline handler = list.pipelines().get(index + orAfter + 1); + if (orAfter == 0 && failsTheStep(handler)) { + return "its failure runs the `|| " + handler.text() + "` after it, which fails the step" + + " too, but this check does not read that shape; " + PUT_IT_ON_ITS_OWN_LINE; + } + return "its failure goes to the `|| " + handler.text() + "` after it, so it cannot fail" + + " the step unless that fails too"; + } + if (index > 0 && !last) { + return "it runs only if `" + list.pipelines().get(index - 1).text() + + "` succeeds (&&), and when that fails the script goes on without it, because this" + + " && list is not the script's last command, so it may not run"; + } + if (index < operators.size() && !last) { + return "a failure only skips the rest of its && list and the script goes on, because" + + " this && list is not the script's last command, so its failure cannot fail the step"; + } + if (errexitOff != null && !last) { + return errexitOff; + } + return null; + } + + /** + * The commands of one top-level pipeline, each with {@code reason} or the pipe's own, and what + * its simple commands do to the shell. + */ + private void pipeline( + Pipeline pipeline, + ShellDirectory current, + String reason, + boolean alone, + boolean mainShell, + boolean afterOr) { + int count = pipeline.commands().size(); + for (int index = 0; index < count; index++) { + String own = reason; + if (own == null && pipeline.negated()) { + own = "! inverts its status, so its failure cannot fail the step"; + } + if (own == null && index < count - 1 && !pipefail) { + own = "it is piped into the next command and the shell has no pipefail, so the pipe's" + + " status is the last command's and its failure cannot fail the step"; + } + Node node = pipeline.commands().get(index); + if (node instanceof Simple simple) { + report(simple, current, own); + effects(simple, alone, mainShell, afterOr); + continue; + } + // A compound command or a function definition: nothing inside counts, and a directory + // change or a set inside may or may not have run when the script goes on. + ShellDirectory[] inside = {current}; + enclosed(node, inside, own, true, mainShell, false); + if (inside[0].unread() != null && current.unread() == null) { + directory = directory.unreadBecause(inside[0].unread()); + } + } + } + + /** + * The commands inside {@code node}, a compound command or a function definition, none of them + * counted: each gets {@code reason}, or the construct's own. A directory change anywhere inside + * makes {@code inside} unread from there on; what a command does to the shell — a {@code set}, + * an {@code exit}, an {@code exec}, a {@code trap}, a call — is kept when the commands run in + * this shell ({@code sameShell}), as something that may have happened. + */ + private void enclosed( + Node node, + ShellDirectory[] inside, + String reason, + boolean sameShell, + boolean mainShell, + boolean afterOr) { + switch (node) { + case Simple simple -> { + List words = values(simple.words()); + if (directoryCommand(simple) != null) { + inside[0] = + inside[0].unreadBecause( + "`" + String.join(" ", words) + "` runs inside a compound command, a function" + + " body or a substitution, so whether it ran before the command is not" + + " read"); + } + report(simple, inside[0], reason); + if (sameShell) { + effects(simple, false, mainShell, afterOr); + } + } + case Compound compound -> { + substitutions(compound.others(), inside[0]); + boolean bodyShell = sameShell && mainShell && !compound.kind().equals(SUBSHELL); + for (Part part : compound.parts()) { + enclosed(part.body(), inside, reason != null ? reason : partReason(compound, part), + bodyShell); + } + } + case FunctionDefinition function -> { + if (sameShell) { + defined(function); + } + definingFunction++; + try { + enclosed( + function.body(), + inside, + reason != null + ? reason + : "it is in the body of function " + function.name() + + ", so it may not run: it runs only where the function is called", + sameShell, + true, + false); + } finally { + definingFunction--; + } + } + } + } + + private void enclosed(Sequence body, ShellDirectory[] inside, String reason, boolean sameShell) { + for (AndOr list : body.items()) { + for (int index = 0; index < list.pipelines().size(); index++) { + Pipeline pipeline = list.pipelines().get(index); + boolean mainShell = pipeline.commands().size() == 1 && !list.async(); + boolean afterOr = index > 0 && list.operators().get(index - 1).equals("||"); + for (Node node : pipeline.commands()) { + enclosed(node, inside, reason, sameShell, mainShell, afterOr); + } + } + } + } + + /** Why a command in {@code part} of {@code compound} does not count. */ + private static String partReason(Compound compound, Part part) { + if (part.condition()) { + return "it is the condition of " + compound.kind() + + ", where a failure only picks the branch, so it cannot fail the step"; + } + if (compound.kind().equals(GROUP) || compound.kind().equals(SUBSHELL)) { + return "it runs inside " + compound.kind() + ", which this check does not read (its" + + " failure would fail the step); " + PUT_IT_ON_ITS_OWN_LINE; + } + return "it runs inside " + compound.kind() + + ", so it may not run: it runs only when and as often as that runs it"; + } + + /** Records a simple command and reads the commands its substitutions and bash -c run. */ + private void report(Simple simple, ShellDirectory current, String reason) { + List words = values(simple.words()); + commands.add(new Command(words, current.path(), current.unread(), reason)); + substitutions(simple.words(), current); + substitutions(simple.others(), current); + int at = commandWord(words); + if (at < 0 || at >= words.size() || !SHELLS.contains(words.get(at))) { + return; + } + for (int index = at + 1; index + 1 < words.size(); index++) { + String option = words.get(index); + if (option.startsWith("-") && !option.startsWith("--") && option.contains("c")) { + child( + words.get(index + 1), + current, + "it runs in a child shell started by " + words.get(at) + " -c, which this check" + + " does not read; " + PUT_IT_ON_ITS_OWN_LINE); + return; + } + } + } + + private void substitutions(List words, ShellDirectory current) { + for (Word word : words) { + for (String substitution : word.substitutions()) { + child( + substitution, + current, + "it runs inside a command substitution, where whether its failure fails the step" + + " depends on the command around it, which this check does not read; " + + PUT_IT_ON_ITS_OWN_LINE); + } + } + } + + /** The commands of a script another shell runs: none counted, nothing kept in this one. */ + private void child(String script, ShellDirectory current, String reason) { + Sequence parsed; + try { + parsed = new Parser(script).script(); + } catch (IllegalStateException unreadable) { + for (Command command : unparsed(script, current.path(), unreadable.getMessage())) { + commands.add(new Command(command.words(), command.directory(), current.unread(), reason)); + } + return; + } + enclosed(parsed, new ShellDirectory[] {current}, reason, false); + } + + /** + * What {@code simple} does to this shell: a {@code set}; an {@code exit}, an {@code exec + * } or a {@code set -n} that ends the script — certainly, when the command stands + * alone at the top level ({@code certain}), or perhaps; a {@code trap} on {@code EXIT} or + * {@code ERR}; a call of a function that does one of these. Only {@code set} is read in a body + * read where its function is defined; the rest happen where the function is called. + */ + private void effects(Simple simple, boolean certain, boolean mainShell, boolean afterOr) { + if (terminated != null) { + return; + } + List words = values(simple.words()); + int at = commandWord(words); + String text = "`" + String.join(" ", words) + "`"; + if (!words.isEmpty() && at == 0 && words.get(0).equals("set")) { + // A set that may not have run keeps only its turning an option off. + applySet(setEffect(words), text, certain); + return; + } + if (!mainShell || definingFunction > 0) { + return; + } + if (replacesShell(words)) { + if (certain) { + terminated = + "it comes after " + text + " at the top level, which replaces the shell, so it never" + + " runs"; + } else { + mayEnd(text + " before it may replace the shell"); + } + return; + } + if (at < 0 || at >= words.size()) { + return; + } + String command = words.get(at); + if (command.equals("exit")) { + if (certain) { + terminated = "it comes after " + text + " at the top level, so it never runs"; + } else if (exitsWithSuccess(words, at, afterOr)) { + mayEnd(text + " before it may end the script first, with status 0"); + } + } else if (command.equals("trap")) { + trap(simple.words().subList(at + 1, simple.words().size()), text); + } else if (functions.containsKey(command)) { + called(functions.get(command), text); + } + } + + private void mayEnd(String what) { + if (mayHaveEnded == null) { + mayHaveEnded = what + ", so it may not run"; + } + } + + private void endsWithStatusZero(String trap, String ending) { + if (exitTrap == null) { + exitTrap = + trap + " before it runs " + ending + " when the script ends or a command fails, which" + + " can end the script with status 0, so its failure may not fail the step"; + } + } + + /** A function definition: kept for the calls after it, and checked for a trap that calls it. */ + private void defined(FunctionDefinition function) { + functions.put(function.name(), function); + TrapCall trap = trapCalls.remove(function.name()); + if (trap == null || definingFunction > 0 || terminated != null) { + return; + } + String ending = + endingIn( + function.body(), + trap.bareExitKeepsStatus(), + true, + new HashSet<>(Set.of(function.name())), + new ArrayList<>()); + if (ending != null) { + endsWithStatusZero(trap.trap(), "`" + function.name() + "`, which runs " + ending); + } + } + + /** A call of {@code function}: what its body does to the shell happens here. */ + private void called(FunctionDefinition function, String call) { + List> traps = new ArrayList<>(); + String ending = + endingIn(function.body(), false, false, new HashSet<>(Set.of(function.name())), traps); + for (List trap : traps) { + trap(trap, call + "'s `trap " + String.join(" ", values(trap)) + "`"); + } + if (ending != null) { + mayEnd(call + " before it may end the script first (it runs " + ending + ")"); + } + } + + /** + * A {@code trap} with {@code arguments}. An action on {@code EXIT} or {@code ERR} that may + * {@code exit} with status 0 — directly, through a function it calls, or through a command this + * reader cannot see ({@code "$handler"}) — ends a failing script with status 0, so no command + * after it can fail the step. A function the action calls that is not defined yet is checked + * where it is. + */ + private void trap(List arguments, String text) { + int index = 0; + while (index < arguments.size()) { + String option = arguments.get(index).value(); + if (option.equals("--")) { + index++; + break; + } + if (!option.startsWith("-") || option.equals("-")) { + break; + } + if (option.contains("p") || option.contains("l")) { + return; // it prints traps and sets none + } + index++; + } + List rest = arguments.subList(index, arguments.size()); + if (rest.size() < 2 + || rest.get(0).value().equals("-") + || INTEGER.matcher(rest.get(0).value()).matches()) { + return; // it resets the conditions it names + } + Set conditions = new HashSet<>(); + for (Word condition : rest.subList(1, rest.size())) { + String name = condition.value().toUpperCase(Locale.ROOT); + conditions.add(name.startsWith("SIG") ? name.substring(3) : name); + } + boolean onError = conditions.contains("ERR"); + if (!onError && !conditions.contains("EXIT") && !conditions.contains("0")) { + return; + } + // A bare exit in an EXIT trap keeps the status the script was ending with; in an ERR trap it + // returns the status of the trap's last command. + boolean bareExitKeepsStatus = !onError; + Sequence action; + try { + action = new Parser(rest.get(0).value()).script(); + } catch (IllegalStateException unreadable) { + endsWithStatusZero(text, "an action this check cannot read"); + return; + } + Compound body = new Compound(GROUP, List.of(new Part(false, action)), List.of()); + walk( + body, + (simple, mainShell, afterOr) -> { + List words = values(simple.words()); + int at = commandWord(words); + if (at >= 0 && at < words.size() && !functions.containsKey(words.get(at))) { + trapCalls.put(words.get(at), new TrapCall(text, bareExitKeepsStatus)); + } + }); + String ending = endingIn(body, bareExitKeepsStatus, true, new HashSet<>(), new ArrayList<>()); + if (ending != null) { + endsWithStatusZero(text, ending); + } + } + + /** + * The first command {@code node} runs in this shell that may end the script with status 0 — an + * {@code exit} that is not a literal non-zero value, {@code exec }, a {@code set -n} + * — following the functions it calls, or, with {@code unknownEnds}, a command whose name is an + * expansion; {@code null} when there is none. Each {@code trap} it runs is added to {@code + * traps}. + */ + private String endingIn( + Node node, + boolean bareExitKeepsStatus, + boolean unknownEnds, + Set visiting, + List> traps) { + String[] found = {null}; + walk( + node, + (simple, mainShell, afterOr) -> { + if (found[0] != null || !mainShell) { + return; + } + List words = values(simple.words()); + int at = commandWord(words); + String text = "`" + String.join(" ", words) + "`"; + if (replacesShell(words)) { + found[0] = text; + return; + } + if (at < 0 || at >= words.size()) { + return; + } + String command = words.get(at); + if (command.equals("exit")) { + if (exitsWithSuccess(words, at, afterOr || bareExitKeepsStatus)) { + found[0] = text; + } + } else if (command.equals("set")) { + SetEffect effect = setEffect(words); + if (effect.unknown() || Boolean.TRUE.equals(effect.noexec())) { + found[0] = text; + } + } else if (command.equals("trap")) { + traps.add(simple.words().subList(at + 1, simple.words().size())); + } else if (functions.containsKey(command)) { + if (visiting.add(command)) { + String inner = + endingIn( + functions.get(command).body(), + bareExitKeepsStatus, + unknownEnds, + visiting, + traps); + if (inner != null) { + found[0] = text + ", which runs " + inner; + } + } + } else if (unknownEnds && (command.contains("$") || command.contains("`"))) { + found[0] = text; + } + }); + return found[0]; + } + + /** + * Each simple command {@code node} runs, without running it: the bodies of compound commands, + * but not a subshell's, a piped compound's or a function definition's. + */ + private static void walk(Node node, CommandVisitor visitor) { + walk(node, visitor, true, false); + } + + private static void walk(Node node, CommandVisitor visitor, boolean mainShell, boolean afterOr) { + switch (node) { + case Simple simple -> visitor.visit(simple, mainShell, afterOr); + case Compound compound -> { + if (mainShell && !compound.kind().equals(SUBSHELL)) { + for (Part part : compound.parts()) { + for (AndOr list : part.body().items()) { + for (int index = 0; index < list.pipelines().size(); index++) { + Pipeline pipeline = list.pipelines().get(index); + boolean single = pipeline.commands().size() == 1 && !list.async(); + boolean or = index > 0 && list.operators().get(index - 1).equals("||"); + for (Node inner : pipeline.commands()) { + walk(inner, visitor, single, or); + } + } + } + } + } + } + case FunctionDefinition ignored -> { + // defining a function runs nothing + } + } + } + + /** Whether {@code words} is {@code exec }, which replaces the shell with the command. */ + private static boolean replacesShell(List words) { + int index = 0; + while (index < words.size() + && (words.get(index).equals("command") || words.get(index).equals("builtin"))) { + index++; + } + if (index >= words.size() || !words.get(index).equals("exec")) { + return false; + } + index++; + while (index < words.size() && words.get(index).startsWith("-")) { + String option = words.get(index); + index += option.equals("-a") ? 2 : 1; + if (option.equals("--")) { + break; + } + } + return index < words.size(); + } + + /** + * Whether {@code exit} at {@code at} may end the shell with status 0: a value that is not a + * literal number, or one that is 0 modulo 256, or no value unless {@code bareKeepsFailure}. + */ + private static boolean exitsWithSuccess(List words, int at, boolean bareKeepsFailure) { + if (at + 1 >= words.size()) { + return !bareKeepsFailure; + } + String value = words.get(at + 1); + if (!INTEGER.matcher(value).matches()) { + return true; + } + try { + return Long.parseLong(value) % 256 == 0; + } catch (NumberFormatException tooLong) { + return true; + } + } + + /** + * Whether {@code handler}, which runs on a failure through {@code ||}, certainly fails the step: + * {@code exit} with a literal non-zero value or none (it keeps the failed status), or a group + * whose last command is {@code exit} with a literal non-zero value. + */ + private static boolean failsTheStep(Pipeline handler) { + if (handler.negated() || handler.commands().size() != 1) { + return false; + } + Node node = handler.commands().get(0); + if (node instanceof Simple simple) { + return failingExit(simple, true); + } + if (node instanceof Compound compound + && (compound.kind().equals(GROUP) || compound.kind().equals(SUBSHELL))) { + List items = compound.parts().get(0).body().items(); + if (items.isEmpty()) { + return false; + } + AndOr last = items.get(items.size() - 1); + return last.pipelines().size() == 1 + && !last.async() + && !last.pipelines().get(0).negated() + && last.pipelines().get(0).commands().size() == 1 + && last.pipelines().get(0).commands().get(0) instanceof Simple simple + && failingExit(simple, false); + } + return false; + } + + private static boolean failingExit(Simple simple, boolean bareKeepsFailure) { + List words = values(simple.words()); + int at = commandWord(words); + return at >= 0 + && at < words.size() + && words.get(at).equals("exit") + && !exitsWithSuccess(words, at, bareKeepsFailure); + } + + private void applySet(SetEffect effect, String text, boolean certain) { + if (effect.unknown()) { + if (errexitOff == null) { + errexitOff = + text + " may have turned off exit-on-error, so its failure may not fail the step"; + } + pipefail = false; + if (definingFunction == 0) { + mayEnd(text + " before it may have stopped the shell from running commands (set -n)"); + } + return; + } + if (Boolean.FALSE.equals(effect.errexit()) && errexitOff == null) { + errexitOff = + text + " turned off exit-on-error before it, so its failure cannot fail the step"; + } else if (Boolean.TRUE.equals(effect.errexit()) && certain) { + errexitOff = null; + } + if (Boolean.FALSE.equals(effect.pipefail())) { + pipefail = false; + } else if (Boolean.TRUE.equals(effect.pipefail()) && certain) { + pipefail = true; + } + if (Boolean.TRUE.equals(effect.noexec()) && definingFunction == 0) { + if (certain) { + terminated = + "it comes after " + text + ", after which the shell reads commands without running" + + " them, so it never runs"; + } else { + mayEnd(text + " before it may stop the shell from running commands"); + } + } + } + + /** What {@code set } does to {@code -e}, {@code pipefail} and {@code -n}. */ + private static SetEffect setEffect(List words) { + Boolean errexit = null; + Boolean pipefailValue = null; + Boolean noexec = null; + for (int index = 1; index < words.size(); index++) { + String word = words.get(index); + if (word.contains("$") || word.contains("`")) { + return new SetEffect(null, null, null, true); + } + if (word.equals("--") || word.equals("-") + || !(word.startsWith("-") || word.startsWith("+"))) { + break; + } + boolean on = word.startsWith("-"); + for (char letter : word.substring(1).toCharArray()) { + if (letter == 'e') { + errexit = on; + } else if (letter == 'n') { + noexec = on; + } else if (letter == 'o' && index + 1 < words.size()) { + String option = words.get(++index); + if (option.contains("$") || option.contains("`")) { + return new SetEffect(null, null, null, true); + } else if (option.equals("errexit")) { + errexit = on; + } else if (option.equals("pipefail")) { + pipefailValue = on; + } else if (option.equals("noexec")) { + noexec = on; + } + } + } + } + return new SetEffect(errexit, pipefailValue, noexec, false); + } + + /** The command of {@code pipeline} that changes directory, or null. */ + private static Simple directoryCommand(Pipeline pipeline) { + for (Node node : pipeline.commands()) { + if (node instanceof Simple simple && directoryCommand(simple) != null) { + return simple; + } + } + return null; + } + + /** {@code cd}, {@code pushd}, {@code popd}, or a command that may change directory unseen. */ + private static String directoryCommand(Simple simple) { + List words = values(simple.words()); + int at = commandWord(words); + if (at < 0 || at >= words.size()) { + return null; + } + String word = words.get(at); + return DIRECTORY_COMMANDS.contains(word) || OPAQUE_COMMANDS.contains(word) ? word : null; + } + + /** The directory a plain {@code cd } goes to, or null. */ + private static String followableTarget(Simple simple) { + List words = simple.words(); + if (words.size() != 2 || !words.get(0).isReserved("cd")) { + return null; + } + Word target = words.get(1); + return !target.expands() && LITERAL_RELATIVE_PATH.matcher(target.value()).matches() + ? target.value() + : null; + } + + private static List values(List words) { + return words.stream().map(Word::value).toList(); + } + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneExecutionTracker.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneExecutionTracker.java new file mode 100644 index 0000000..d11b526 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneExecutionTracker.java @@ -0,0 +1,60 @@ +package dev.caskeleton.buildlogic.strictlane; + +import java.util.Collections; +import java.util.LinkedHashSet; +import java.util.Set; +import java.util.concurrent.atomic.AtomicLong; +import org.gradle.api.tasks.testing.TestDescriptor; +import org.gradle.api.tasks.testing.TestListener; +import org.gradle.api.tasks.testing.TestResult; + +final class StrictLaneExecutionTracker implements TestListener { + private final boolean collectSelectors; + private final AtomicLong executed = new AtomicLong(); + private final AtomicLong skipped = new AtomicLong(); + private final Set executedSelectors = + Collections.synchronizedSet(new LinkedHashSet<>()); + + StrictLaneExecutionTracker(boolean collectSelectors) { + this.collectSelectors = collectSelectors; + } + + long executedCount() { + return executed.get(); + } + + long skippedCount() { + return skipped.get(); + } + + Set executedSelectors() { + synchronized (executedSelectors) { + return Set.copyOf(executedSelectors); + } + } + + @Override + public void beforeSuite(TestDescriptor suite) {} + + @Override + public void afterSuite(TestDescriptor suite, TestResult result) {} + + @Override + public void beforeTest(TestDescriptor testDescriptor) {} + + @Override + public void afterTest(TestDescriptor descriptor, TestResult result) { + if (result.getResultType() == TestResult.ResultType.SKIPPED) { + skipped.incrementAndGet(); + return; + } + executed.incrementAndGet(); + if (collectSelectors) { + String className = descriptor.getClassName(); + if (className != null) { + executedSelectors.add(className); + executedSelectors.add(className + "." + descriptor.getName()); + } + } + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesExtension.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesExtension.java new file mode 100644 index 0000000..03d1dd5 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesExtension.java @@ -0,0 +1,28 @@ +package dev.caskeleton.buildlogic.strictlane; + +import org.gradle.api.file.DirectoryProperty; +import org.gradle.api.provider.ListProperty; + +/** + * The stages a strict lane may belong to, and where the workflows that run them live. + * + *

A stage is a task path a workflow executes ({@code :ci}, {@code :mainCheck}, ...). Every strict + * lane that is not {@code explicitOnly} must be in the plan of at least one stage, and every stage + * must be executed — not merely planned with {@code --dry-run} — by at least one workflow. + */ +public abstract class StrictLaneStagesExtension { + public abstract ListProperty getStages(); + + /** + * The repository's {@code .github/workflows}. Its grandparent is the repository root, and a + * command executes this build's stages only when it starts in this build's directory from there + * — its step's {@code working-directory} joined with its {@code -p}. The directory is read from + * where the build is, so no build states it (review 2026-11-04 RR2-04-04: a {@code -p} value + * alone missed {@code working-directory: src/platforms/optional-build} with {@code ../gradlew}). + */ + public abstract DirectoryProperty getWorkflowDirectory(); + + public void stage(String... taskPaths) { + getStages().addAll(taskPaths); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java new file mode 100644 index 0000000..beed912 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java @@ -0,0 +1,322 @@ +package dev.caskeleton.buildlogic.strictlane; + +import java.io.File; +import java.io.IOException; +import java.io.UncheckedIOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.util.ArrayDeque; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Comparator; +import java.util.Deque; +import java.util.HashSet; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.Set; +import org.gradle.api.GradleException; +import org.gradle.api.Plugin; +import org.gradle.api.Project; +import org.gradle.api.Task; +import org.gradle.api.execution.TaskExecutionGraph; + +/** + * Fails when a strict lane belongs to no stage a workflow executes. + * + *

A strict lane fails closed when it runs, but nothing makes it run: a lane that no workflow + * reaches is a file that looks like coverage (review 2026-11-01 08-01 found fourteen). The rule is + * stated once, here, instead of as one workflow line per lane: + * + *

    + *
  1. every strict lane that is not {@code explicitOnly} is in the task plan of a declared stage + * as a workflow runs it — a lane the command removes with {@code -x} is not covered, matched + * the way Gradle matches it, abbreviations included ({@link TaskSelectors}); + *
  2. 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, 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 + * run, or this check does not read it although its failure would fail the step ({@code + * WorkflowGradleInvocations} and {@code ShellScript} name the shapes). + *
+ * + *

Each build that holds strict lanes applies it at its own root: the main build, and the + * optional-platforms build. A command executes this build when it starts in this build's directory + * — its step's {@code working-directory}, moved by the {@code cd} commands the same shell surely + * ran before it, joined with its {@code -p}, from the repository root, which is where GitHub keeps + * {@code .github/workflows} ({@code ShellScript} says which {@code cd} it follows). + * A stage named only by commands that do not count is reported with each command's reason. Applied + * to the main build only, it said "every strict lane" while the optional build's performance lane + * ran nowhere (RR-06-03).

+ * + *

The task plan is Gradle's own: {@code verifyStrictLaneStages} depends on the stages, so a + * {@code --dry-run} of it builds the real plan, and the check reads it when the graph is ready. It + * refuses to run without {@code --dry-run}, which would execute every stage. + */ +public final class StrictLaneStagesPlugin implements Plugin { + public static final String TASK_NAME = "verifyStrictLaneStages"; + + /** What a failure names as not counted, in the three reasons the readers give, and what to do. */ + static final String NOT_COUNTED = + "Not counted: a command after which Gradle runs no task (--dry-run, -m, -v, --help," + + " --status, ...) or that Gradle rejects (a short-option bundle such as -mx), and one" + + " for another build; one whose failure may not fail its step (|| true, a pipe without" + + " pipefail, !, &, an if/while condition, the part before && of a list that is not the" + + " script's last command, after set +e or a trap that exits 0, continue-on-error); one" + + " that may not run (after ||, inside if/while/for/case or a function, after an exit 0," + + " 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 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 (:releaseCheck may run on a tag push or a release)"; + + @Override + public void apply(Project project) { + if (project != project.getRootProject()) { + throw new GradleException("ca.strict-lane-stages is applied to the root project only."); + } + StrictLaneStagesExtension extension = + project.getExtensions().create("strictLaneStages", StrictLaneStagesExtension.class); + var verify = + project + .getTasks() + .register( + TASK_NAME, + task -> { + task.setGroup("verification"); + task.setDescription( + "Fails when a strict lane is in no stage a workflow executes. Run with --dry-run."); + task.notCompatibleWithConfigurationCache( + "the check reads the task graph itself, which a cached entry does not rebuild"); + }); + project.afterEvaluate( + ignored -> verify.configure(task -> task.dependsOn(extension.getStages().get().toArray()))); + project + .getGradle() + .getTaskGraph() + .whenReady( + graph -> { + Task task = verify.get(); + if (!graph.hasTask(task)) { + return; + } + if (!project.getGradle().getStartParameter().isDryRun()) { + throw new GradleException( + TASK_NAME + + " checks the plan of " + + extension.getStages().get() + + " and would execute all of them; run it with --dry-run."); + } + File workflowDirectory = extension.getWorkflowDirectory().get().getAsFile(); + List problems = + problems( + project, + graph, + extension.getStages().get(), + workflowDirectory, + buildDirectory(project, workflowDirectory)); + if (!problems.isEmpty()) { + throw new GradleException( + TASK_NAME + + ": " + + problems.size() + + " problem(s). A lane no executed stage reaches runs nowhere; put it in a" + + " stage, or declare explicitOnly(\"reason\") if it needs an input no stage" + + " has.\n - " + + String.join("\n - ", problems)); + } + project + .getLogger() + .lifecycle( + TASK_NAME + ": every strict lane is in an executed stage."); + }); + } + + private static List problems( + Project root, + TaskExecutionGraph graph, + List stages, + File workflowDirectory, + String buildDirectory) { + List problems = new ArrayList<>(foldedCommandBreaks(workflowDirectory)); + Map> invocationsByWorkflow = + invocations(workflowDirectory); + List invocations = + invocationsByWorkflow.values().stream().flatMap(List::stream).toList(); + // Only an executed stage covers a lane — a stage no workflow runs is the same gap one level + // up — and only as the command runs it: what its -x removes is not covered. + Map> tasksByProject = new LinkedHashMap<>(); + root.getAllprojects() + .forEach( + project -> tasksByProject.put(project.getPath(), Set.copyOf(project.getTasks().getNames()))); + Map> plans = new LinkedHashMap<>(); + for (String stage : stages) { + List executions = + invocations.stream() + .filter(invocation -> invocation.executes(stage, buildDirectory)) + .toList(); + if (executions.isEmpty()) { + problems.add( + "stage " + + stage + + " is executed by no workflow in " + + workflowDirectory.getName() + + " for the build in " + + buildDirectory + + ". " + + NOT_COUNTED + + notCounted(invocationsByWorkflow, stage, buildDirectory)); + continue; + } + Task stageTask = root.getTasks().findByPath(stage); + int run = 0; + for (WorkflowGradleInvocations.Invocation execution : executions) { + Set excluded = + TaskSelectors.excludedPaths(execution.excludedTasks(), tasksByProject); + plans.put( + stage + "#" + run++, stageTask == null ? Set.of() : plan(graph, stageTask, excluded)); + } + } + List lanes = new ArrayList<>(); + root.getAllprojects().stream() + .sorted(Comparator.comparing(Project::getPath)) + .forEach( + project -> { + StrictTestLaneExtension lanesOf = + project.getExtensions().findByType(StrictTestLaneExtension.class); + if (lanesOf == null) { + return; + } + lanesOf.getLanes().stream() + .filter(lane -> lane.getExplicitOnlyReason() == null) + .map(lane -> taskPath(project, lane.getName())) + .sorted() + .forEach(lanes::add); + }); + for (String lane : lanes) { + if (plans.values().stream().noneMatch(plan -> plan.contains(lane))) { + problems.add("strict lane " + lane + " is in no executed stage of " + stages); + } + } + return problems; + } + + /** + * The commands that name {@code stage} but do not execute it for this build, each with why — its + * uncounted reason, the other build it starts (review 2026-11-04 RR5-02-03: a typo in a {@code cd} + * or a {@code cd src} under {@code working-directory: src} is named, not hidden), or a dry run: a + * workflow that calls the stage in a way this check does not count is told so, instead of failing + * as if it never did. + */ + private static String notCounted( + Map> invocationsByWorkflow, + String stage, + String buildDirectory) { + List lines = new ArrayList<>(); + invocationsByWorkflow.forEach( + (workflow, invocations) -> + invocations.stream() + .filter(invocation -> invocation.requests(stage)) + .forEach( + invocation -> + lines.add( + workflow + + ": gradlew " + + String.join(" ", invocation.tasks()) + + " — " + + invocation.whyNotExecuting(stage, buildDirectory)))); + return lines.isEmpty() + ? "" + : "; commands that name it but do not count:\n " + String.join("\n ", lines); + } + + /** + * The tasks {@code stage} reaches as a command runs it: what its -x removes is cut off. A task of + * an included build (a stage that runs build-logic's tests) is not in this build's plan and holds + * none of its lanes, so the walk does not ask the graph about it — the graph would refuse. + */ + private static Set plan(TaskExecutionGraph graph, Task stage, Set excluded) { + Set seen = new HashSet<>(); + Deque pending = new ArrayDeque<>(List.of(stage)); + while (!pending.isEmpty()) { + Task task = pending.pop(); + if (!excluded.contains(task.getPath()) && seen.add(task.getPath()) && graph.hasTask(task)) { + pending.addAll(graph.getDependencies(task)); + } + } + return seen; + } + + /** A folded run block broken by a blank line runs its options as commands; see the reader. */ + private static List foldedCommandBreaks(File workflowDirectory) { + List problems = new ArrayList<>(); + for (File file : workflowFiles(workflowDirectory)) { + try { + WorkflowGradleInvocations.foldedCommandBreaks( + Files.readString(file.toPath(), StandardCharsets.UTF_8)) + .forEach(problem -> problems.add(file.getName() + " " + problem)); + } catch (IOException exception) { + throw new UncheckedIOException("failed to read " + file, exception); + } + } + return problems; + } + + private static File[] workflowFiles(File workflowDirectory) { + File[] files = + workflowDirectory.listFiles( + file -> file.getName().endsWith(".yml") || file.getName().endsWith(".yaml")); + if (files == null || files.length == 0) { + throw new GradleException( + TASK_NAME + ": no workflow files in " + workflowDirectory + "; nothing could run a stage."); + } + Arrays.sort(files); + return files; + } + + /** + * Each workflow file's Gradle commands, by file name, in file order — read together, because a + * reusable workflow runs only through the workflows that call it (RR6-04-06). + */ + private static Map> invocations( + File workflowDirectory) { + Map workflows = new LinkedHashMap<>(); + for (File file : workflowFiles(workflowDirectory)) { + try { + workflows.put(file.getName(), Files.readString(file.toPath(), StandardCharsets.UTF_8)); + } catch (IOException exception) { + throw new UncheckedIOException("failed to read " + file, exception); + } + } + return WorkflowGradleInvocations.readAll(workflows); + } + + /** + * This build's directory from the repository root, which holds {@code .github/workflows}: {@code + * src} for the main build, {@code src/platforms/optional-build} for the optional one. + */ + private static String buildDirectory(Project root, File workflowDirectory) { + File repository = workflowDirectory.getAbsoluteFile().getParentFile().getParentFile(); + String relative = + repository + .toPath() + .normalize() + .relativize(root.getRootDir().getAbsoluteFile().toPath().normalize()) + .toString() + .replace(File.separatorChar, '/'); + return WorkflowGradleInvocations.Invocation.normalized(relative); + } + + private static String taskPath(Project project, String name) { + return project == project.getRootProject() ? ":" + name : project.getPath() + ":" + name; + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneExtension.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneExtension.java new file mode 100644 index 0000000..f0cfd64 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneExtension.java @@ -0,0 +1,28 @@ +package dev.caskeleton.buildlogic.strictlane; + +import org.gradle.api.Action; +import org.gradle.api.GradleException; +import org.gradle.api.NamedDomainObjectContainer; + +public class StrictTestLaneExtension { + private final NamedDomainObjectContainer lanes; + + public StrictTestLaneExtension(NamedDomainObjectContainer lanes) { + this.lanes = lanes; + } + + public NamedDomainObjectContainer getLanes() { + return lanes; + } + + public void lane(String name, Action configuration) { + // Configured before it is added, so the plugin's `lanes.all` action sees the declared source + // set (it decides whether the lane is its JVM test suite's own task). + if (lanes.findByName(name) != null) { + throw new GradleException("strict test lane '" + name + "' is declared twice"); + } + StrictTestLaneSpec lane = new StrictTestLaneSpec(name); + configuration.execute(lane); + lanes.add(lane); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLanePlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLanePlugin.java new file mode 100644 index 0000000..628cea8 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLanePlugin.java @@ -0,0 +1,473 @@ +package dev.caskeleton.buildlogic.strictlane; + +import dev.caskeleton.buildlogic.RequiredTestExecution; +import java.io.File; +import java.util.List; +import java.util.function.Predicate; +import org.gradle.api.tasks.PathSensitivity; +import org.gradle.api.GradleException; +import org.gradle.api.NamedDomainObjectContainer; +import org.gradle.api.Plugin; +import org.gradle.api.Project; +import org.gradle.api.plugins.JavaPluginExtension; +import org.gradle.api.provider.Provider; +import org.gradle.api.tasks.SourceSet; +import org.gradle.api.tasks.TaskProvider; +import org.gradle.api.tasks.testing.Test; +import org.gradle.testing.base.TestingExtension; + +public final class StrictTestLanePlugin implements Plugin { + /** + * The switch a performance lane's machine-dependent bounds used to sit behind, now always on. + * + *

Each leaf declared it with its own default — {@code false} for the httpclient lane, {@code + * true} for the Mongo lane — and only the workflows set it. {@code ./gradlew :performanceCheck} + * typed by hand therefore passed with the httpclient heap bound compared to nothing (the + * 2026-11-05 desktop gate). The convention owns it now: every performance lane's test JVM gets + * {@code true}, so a test that still reads the switch asserts, and a build that sets it to + * anything else fails before the lane runs. Nothing in this repository reads it any more; the + * value is for tests written against the old switch, such as a derived service's. + */ + static final String PERFORMANCE_ASSERTIONS = "performance.assertions.enabled"; + + @Override + public void apply(Project project) { + project.getPluginManager().withPlugin("java", ignored -> configure(project)); + } + + private static void configure(Project project) { + NamedDomainObjectContainer lanes = + project.container(StrictTestLaneSpec.class, StrictTestLaneSpec::new); + StrictTestLaneExtension extension = + project + .getExtensions() + .create("strictTestLanes", StrictTestLaneExtension.class, lanes); + String ownerPath = project.getPath(); + JavaPluginExtension java = project.getExtensions().getByType(JavaPluginExtension.class); + + lanes.all( + lane -> { + // A lane named after the JVM test suite it runs is that suite's own Test task: the suite + // (jvm-test-suite, which replaced ca.auxiliary-source-set) registers it, the lane makes it + // strict. Any other name collision still fails in register(). + TaskProvider laneTask = + isOwnSuiteTask(project, lane) + ? project.getTasks().named(lane.getName(), Test.class) + : project.getTasks().register(lane.getName(), Test.class); + laneTask.configure(test -> configureLane(project, java, ownerPath, lane, test)); + + project + .getGradle() + .getTaskGraph() + .whenReady( + graph -> { + boolean selected = + graph.getAllTasks().stream().anyMatch(task -> task == laneTask.get()); + if (!selected) { + return; + } + SourceSet sourceSet = java.getSourceSets().getByName(lane.getSourceSet()); + if (sourceSet.getAllSource().getFiles().isEmpty()) { + throw new GradleException( + "strict test lane '" + + lane.getName() + + "' in " + + ownerPath + + " has no sources in source set '" + + lane.getSourceSet() + + "'. Gradle would skip it as NO-SOURCE and report success for a lane that ran nothing."); + } + }); + }); + + project.afterEvaluate( + ignored -> lanes.forEach(lane -> validateLane(project, lane))); + + lanes.all( + lane -> + project.afterEvaluate( + ignored -> { + if (!lane.isMainStage()) { + return; + } + String tag = lane.getTag(); + if (tag == null || tag.isBlank()) { + throw new GradleException( + "strict test lane '" + + lane.getName() + + "' in " + + ownerPath + + " is a main-stage lane without a tag; the tag is what keeps its tests out of `test`."); + } + project + .getTasks() + .named("test", Test.class) + .configure(test -> test.useJUnitPlatform(options -> options.excludeTags(tag))); + project + .getTasks() + .matching(task -> task.getName().equals("mainCheck")) + .configureEach(task -> task.dependsOn(lane.getName())); + })); + + registerAggregate( + project, + extension, + "strictTestLaneCheck", + "Runs every strict test lane this leaf declares.", + lane -> true); + registerAggregate( + project, + extension, + "testLaneCheck", + "Runs this leaf's hermetic test lanes.", + lane -> lane.getCategory() == TestLaneCategory.TEST); + registerAggregate( + project, + extension, + "integrationTestLaneCheck", + "Runs this leaf's external-infrastructure integration test lanes.", + lane -> lane.getCategory() == TestLaneCategory.INTEGRATION); + registerAggregate( + project, + extension, + "systemTestLaneCheck", + "Runs this leaf's full application/system test lanes.", + lane -> lane.getCategory() == TestLaneCategory.SYSTEM); + registerAggregate( + project, + extension, + "architectureTestLaneCheck", + "Runs this leaf's architecture test lanes.", + lane -> lane.getCategory() == TestLaneCategory.ARCHITECTURE); + registerAggregate( + project, + extension, + "performanceTestLaneCheck", + "Runs this leaf's performance test lanes.", + lane -> lane.getCategory() == TestLaneCategory.PERFORMANCE); + } + + private static void registerAggregate( + Project project, + StrictTestLaneExtension extension, + String taskName, + String description, + Predicate selection) { + project + .getTasks() + .register( + taskName, + task -> { + task.setGroup("verification"); + task.setDescription(description); + task.dependsOn( + project.provider( + () -> + extension.getLanes().stream() + .filter(lane -> lane.getExplicitOnlyReason() == null) + .filter(selection) + .map(lane -> project.getTasks().named(lane.getName())) + .toList())); + // An explicit-only lane is left out, and the aggregate says so when it runs, so a + // green aggregate is never read as covering it. + var leftOut = + project.provider( + () -> + extension.getLanes().stream() + .filter(lane -> lane.getExplicitOnlyReason() != null) + .filter(selection) + .map( + lane -> + "strict test lane '" + + lane.getName() + + "' in " + + project.getPath() + + " runs only when named: " + + lane.getExplicitOnlyReason() + + ".") + .toList()); + task.doLast( + running -> leftOut.get().forEach(note -> running.getLogger().lifecycle(note))); + }); + } + + private static void configureLane( + Project project, + JavaPluginExtension java, + String ownerPath, + StrictTestLaneSpec lane, + Test test) { + SourceSet sourceSet = java.getSourceSets().getByName(lane.getSourceSet()); + if (startsARealServer(lane)) { + // INTEGRATION, SYSTEM and PERFORMANCE lanes start a server, a container or both, and + // several of those at once under `org.gradle.parallel` makes the machine decide the result. + // One slot for all of them, build-wide — ordering them inside a leaf was not enough, because + // the web and websocket lanes contend with each other across leaves. An ARCHITECTURE lane + // imports classes and starts nothing, so it does not wait for that slot (review 2026-11-01 + // 08-06). + test.usesService( + project + .getGradle() + .getSharedServices() + .registerIfAbsent( + "exclusiveRealServerLane", + ExclusiveRealServerLaneService.class, + specification -> specification.getMaxParallelUsages().set(1))); + } + test.setGroup( + lane.getGroup() == null || lane.getGroup().isBlank() ? "verification" : lane.getGroup()); + test.setDescription(lane.getDescription()); + test.setTestClassesDirs(sourceSet.getOutput().getClassesDirs()); + test.setClasspath(sourceSet.getRuntimeClasspath()); + String tag = lane.getTag(); + if (tag != null && !tag.trim().isEmpty()) { + test.useJUnitPlatform(options -> options.includeTags(tag)); + } else { + test.useJUnitPlatform(); + } + List required = lane.getRequiredTests(); + if (!required.isEmpty()) { + test.filter( + filter -> { + required.forEach(filter::includeTestsMatching); + filter.setFailOnNoMatchingTests(true); + }); + } + test.getFailOnNoDiscoveredTests().set(true); + // A lane whose result follows from its declared inputs may be up to date or come from the + // build cache: the result it reuses was produced by a run that passed the checks below (no test + // ran, a skip, a required test missing), with the same classes, filter and properties. A lane + // whose result depends on what Gradle cannot see runs every time (review 2026-11-01 08-02). + // The verdict below reads the lane's policy, not only its test results, so the policy is an + // input: tightening it (rejectSkipped = true, another required test, another category) must + // judge the lane again rather than reuse a result produced under the looser policy. Without + // this a lane that skipped a test stayed green, up to date and from the build cache, after + // rejectSkipped was switched on (review 2026-11-03 RR-06-02). + test.getInputs() + .property("strictLane.rejectSkipped", project.provider(() -> rejectsSkipped(lane))); + test.getInputs() + .property("strictLane.requiredTests", project.provider(lane::getRequiredTests)); + test.getInputs() + .property( + "strictLane.tag", project.provider(() -> lane.getTag() == null ? "" : lane.getTag())); + test.getInputs() + .property("strictLane.category", project.provider(() -> lane.getCategory().name())); + test.getInputs().property("strictLane.mainStage", project.provider(lane::isMainStage)); + String rerunReason = rerunReason(lane); + if (rerunReason != null) { + test.getOutputs().upToDateWhen(ignored -> false); + test.getOutputs().doNotCacheIf(rerunReason, ignored -> true); + } + boolean performance = lane.getCategory() == TestLaneCategory.PERFORMANCE; + if (performance) { + // Set before the lane's own JVM arguments and system properties — Gradle turns a -D in + // jvmArgs into a system property — so a lane that still declares the switch replaces this + // value and the check below sees the override, instead of the override disappearing silently. + test.systemProperty(PERFORMANCE_ASSERTIONS, "true"); + Provider requested = project.getProviders().gradleProperty(PERFORMANCE_ASSERTIONS); + String laneName = lane.getName(); + test.doFirst( + running -> requireAssertionsOn(laneName, ownerPath, requested.getOrNull(), (Test) running)); + } + if (lane.getMaxHeapSize() != null && !lane.getMaxHeapSize().isBlank()) { + test.setMaxHeapSize(lane.getMaxHeapSize()); + } + if (!lane.getJvmArgs().isEmpty()) { + test.setJvmArgs(lane.getJvmArgs()); + } + lane.getShouldRunAfter().forEach(test::shouldRunAfter); + lane.getDependsOn().forEach(test::dependsOn); + lane.getSystemProperties().forEach(test::systemProperty); + for (File directory : lane.getInputDirectories()) { + test.getInputs().dir(directory).withPathSensitivity(PathSensitivity.RELATIVE); + } + + StrictLaneExecutionTracker tracker = new StrictLaneExecutionTracker(!required.isEmpty()); + test.addTestListener(tracker); + test.doLast( + ignored -> { + if (tracker.executedCount() == 0L) { + String detail; + if (tracker.skippedCount() > 0L) { + detail = + "; all " + + tracker.skippedCount() + + " test(s) it selected were skipped (@Disabled or an unmet assumption), and a skip is not a result"; + } else if (tag != null && !tag.trim().isEmpty()) { + detail = + "; its tag '" + + tag + + "' matches nothing in source set '" + + lane.getSourceSet() + + "'"; + } else if (required.isEmpty()) { + detail = " in source set '" + lane.getSourceSet() + "'"; + } else { + detail = "; its required tests " + required + " matched no executable test"; + } + throw new GradleException( + "strict test lane '" + + lane.getName() + + "' in " + + ownerPath + + " executed no test" + + detail + + " — a lane that runs nothing reports success for whatever it was meant to prove."); + } + if (rejectsSkipped(lane) && tracker.skippedCount() > 0L) { + throw new GradleException( + "strict test lane '" + + lane.getName() + + "' in " + + ownerPath + + " forbids skipped tests but observed " + + tracker.skippedCount() + + " skipped test(s)." + + (performance + ? " A performance lane always does: a skipped test is a bound nobody measured." + : "")); + } + if (!required.isEmpty()) { + List absent = + RequiredTestExecution.absent(required, tracker.executedSelectors()); + if (!absent.isEmpty()) { + throw new GradleException( + "strict test lane '" + + lane.getName() + + "' in " + + ownerPath + + " required " + + absent + + " and executed neither. A lane that named a test it no longer runs proves less than it claims."); + } + } + }); + if (lane.getCustomize() != null) { + lane.getCustomize().execute(test); + } + } + + /** + * A performance lane rejects skipped tests whatever it declares: its tests are its bounds, and a + * skip is a bound the run reports as passed without comparing it to anything. + */ + private static boolean rejectsSkipped(StrictTestLaneSpec lane) { + return lane.isRejectSkipped() || lane.getCategory() == TestLaneCategory.PERFORMANCE; + } + + /** + * Fails a performance lane, before any test runs, when the build or the lane turns its bounds off. + * {@code true} from the build is accepted, so a command that still passes it keeps working. + */ + private static void requireAssertionsOn( + String laneName, String ownerPath, String requestedByBuild, Test test) { + if (requestedByBuild != null && !Boolean.parseBoolean(requestedByBuild.trim())) { + throw new GradleException( + "strict test lane '" + + laneName + + "' in " + + ownerPath + + " is a performance lane, and this build sets " + + PERFORMANCE_ASSERTIONS + + "=" + + requestedByBuild + + " (-P" + + PERFORMANCE_ASSERTIONS + + ", or -Dorg.gradle.project." + + PERFORMANCE_ASSERTIONS + + " in GRADLE_OPTS). A performance lane asserts its bounds in every run: one without" + + " them measures nothing it can fail on and still reports success. Remove the" + + " property or set it to true."); + } + Object effective = test.getSystemProperties().get(PERFORMANCE_ASSERTIONS); + if (effective == null || !Boolean.parseBoolean(String.valueOf(effective).trim())) { + throw new GradleException( + "strict test lane '" + + laneName + + "' in " + + ownerPath + + " is a performance lane, but its test JVM would get " + + PERFORMANCE_ASSERTIONS + + "=" + + effective + + " from this project's build (a lane systemProperty or jvmArgs, or a block that" + + " configures the task). The strict-lane convention sets it to true for every" + + " performance lane; delete the override."); + } + } + + private static boolean startsARealServer(StrictTestLaneSpec lane) { + return lane.getCategory() != TestLaneCategory.TEST + && lane.getCategory() != TestLaneCategory.ARCHITECTURE; + } + + /** + * Why this lane's earlier result may not stand for this run, or {@code null} when it may. + * + *

    + *
  • INTEGRATION, SYSTEM, PERFORMANCE: a container image pulled by tag, the network, the clock + * and the machine's load are not task inputs, so the same inputs prove nothing about the + * same result. + *
  • A main-stage lane: it compares the leaf with repository documents it does not declare as + * inputs, and it is the stage whose run is the evidence. + *
+ */ + private static String rerunReason(StrictTestLaneSpec lane) { + if (startsARealServer(lane)) { + return "a " + + lane.getCategory() + + " lane depends on images, network and time that are not task inputs"; + } + if (lane.isMainStage()) { + return "a main-stage lane reads repository documents that are not task inputs"; + } + return null; + } + + private static boolean isOwnSuiteTask(Project project, StrictTestLaneSpec lane) { + TestingExtension testing = project.getExtensions().findByType(TestingExtension.class); + return testing != null + && lane.getName().equals(lane.getSourceSet()) + && testing.getSuites().getNames().contains(lane.getName()) + && project.getTasks().getNames().contains(lane.getName()); + } + + private static void validateLane(Project project, StrictTestLaneSpec lane) { + boolean hasTag = lane.getTag() != null && !lane.getTag().trim().isEmpty(); + boolean hasRequired = !lane.getRequiredTests().isEmpty(); + if (!hasTag && !hasRequired && lane.getSourceSet().equals("test")) { + throw new GradleException( + "strict test lane '" + + lane.getName() + + "' in " + + project.getPath() + + " selects nothing while running over the shared 'test' source set; it would run the entire suite under a name that claims it ran one thing. Give it a tag, a set of required tests, or a source set of its own."); + } + if (hasTag && hasRequired) { + throw new GradleException( + "strict test lane '" + + lane.getName() + + "' in " + + project.getPath() + + " declares both a tag and required tests; pick one selection."); + } + if (lane.getDescription() == null || lane.getDescription().trim().isEmpty()) { + throw new GradleException( + "strict test lane '" + + lane.getName() + + "' in " + + project.getPath() + + " declares no description"); + } + if (project.getExtensions().getByType(JavaPluginExtension.class).getSourceSets().findByName(lane.getSourceSet()) == null) { + throw new GradleException( + "strict test lane '" + + lane.getName() + + "' in " + + project.getPath() + + " references unknown source set '" + + lane.getSourceSet() + + "'."); + } + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneSpec.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneSpec.java new file mode 100644 index 0000000..197d102 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneSpec.java @@ -0,0 +1,209 @@ +package dev.caskeleton.buildlogic.strictlane; + +import java.io.File; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.Objects; +import org.gradle.api.Action; +import org.gradle.api.Named; +import org.gradle.api.tasks.testing.Test; + +public class StrictTestLaneSpec implements Named { + private final String name; + private String tag; + private String description; + private String group; + private String sourceSet = "test"; + private String maxHeapSize; + private boolean rejectSkipped; + private boolean mainStage; + private String explicitOnlyReason; + private TestLaneCategory category = TestLaneCategory.TEST; + private final List requiredTests = new ArrayList<>(); + private final List jvmArgs = new ArrayList<>(); + private final List shouldRunAfter = new ArrayList<>(); + private final List dependsOn = new ArrayList<>(); + private final List inputDirectories = new ArrayList<>(); + private final Map systemProperties = new LinkedHashMap<>(); + private Action customize; + + public StrictTestLaneSpec(String name) { + this.name = Objects.requireNonNull(name, "name"); + } + + @Override + public String getName() { + return name; + } + + public String getTag() { + return tag; + } + + public void setTag(String tag) { + this.tag = tag; + } + + public String getDescription() { + return description; + } + + public void setDescription(String description) { + this.description = description; + } + + public String getGroup() { + return group; + } + + public void setGroup(String group) { + this.group = group; + } + + public String getSourceSet() { + return sourceSet; + } + + public void setSourceSet(String sourceSet) { + this.sourceSet = sourceSet; + } + + public String getMaxHeapSize() { + return maxHeapSize; + } + + public void setMaxHeapSize(String maxHeapSize) { + this.maxHeapSize = maxHeapSize; + } + + public boolean isRejectSkipped() { + return rejectSkipped; + } + + public void setRejectSkipped(boolean rejectSkipped) { + this.rejectSkipped = rejectSkipped; + } + + public boolean isMainStage() { + return mainStage; + } + + /** + * Runs this lane in the leaf's {@code mainCheck} instead of its {@code test}: the lane's tag is + * excluded from {@code test}. For checks that compare a leaf with documents or registries, which + * are not worth a pull request's wait (review 2026-09-24 BUILD-계획-B4-27). + */ + public void mainStage() { + mainStage = true; + } + + public String getExplicitOnlyReason() { + return explicitOnlyReason; + } + + /** + * Keeps this lane out of every aggregate ({@code strictTestLaneCheck}, {@code + * integrationTestLaneCheck}, ...): it runs only when named. For a lane that cannot pass without + * an input the aggregate's caller does not have — protected credentials, an external topology — + * so that the aggregate states the gap instead of failing on it (review NEW-16). + */ + public void explicitOnly(String reason) { + explicitOnlyReason = Objects.requireNonNull(reason, "reason"); + } + + public TestLaneCategory getCategory() { + return category; + } + + public void setCategory(TestLaneCategory category) { + this.category = Objects.requireNonNull(category, "category"); + } + + public void test() { + category = TestLaneCategory.TEST; + } + + public void integration() { + category = TestLaneCategory.INTEGRATION; + } + + public void system() { + category = TestLaneCategory.SYSTEM; + } + + public void architecture() { + category = TestLaneCategory.ARCHITECTURE; + } + + /** + * A lane whose tests are resource or latency bounds. Besides rerunning every time and taking the + * build-wide real-server slot, it rejects skipped tests and always runs with its bounds asserted: + * the convention sets {@code performance.assertions.enabled=true}, and a build or lane that sets + * it to anything else fails before a test runs. + */ + public void performance() { + category = TestLaneCategory.PERFORMANCE; + } + + public List getRequiredTests() { + return List.copyOf(requiredTests); + } + + public void requires(String... selectors) { + requiredTests.addAll(List.of(selectors)); + } + + public List getJvmArgs() { + return List.copyOf(jvmArgs); + } + + public void jvmArgs(String... arguments) { + jvmArgs.addAll(List.of(arguments)); + } + + public List getShouldRunAfter() { + return List.copyOf(shouldRunAfter); + } + + public void shouldRunAfter(String... taskNames) { + shouldRunAfter.addAll(List.of(taskNames)); + } + + public List getDependsOn() { + return List.copyOf(dependsOn); + } + + public void dependsOn(String... taskNames) { + dependsOn.addAll(List.of(taskNames)); + } + + public Map getSystemProperties() { + return Map.copyOf(systemProperties); + } + + public void systemProperty(String name, String value) { + systemProperties.put(Objects.requireNonNull(name, "name"), Objects.requireNonNull(value, "value")); + } + + public List getInputDirectories() { + return List.copyOf(inputDirectories); + } + + public void inputDirectory(File directory) { + inputDirectories.add(Objects.requireNonNull(directory, "directory")); + } + + public Action getCustomize() { + return customize; + } + + public void setCustomize(Action customize) { + this.customize = customize; + } + + public void customize(Action customize) { + this.customize = customize; + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TaskSelectors.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TaskSelectors.java new file mode 100644 index 0000000..6dad58e --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TaskSelectors.java @@ -0,0 +1,214 @@ +package dev.caskeleton.buildlogic.strictlane; + +import java.util.Collection; +import java.util.LinkedHashSet; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.Set; +import java.util.TreeSet; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +/** + * Which tasks a command line's {@code -x} selectors remove, matched the way Gradle matches them. + * + *

Gradle accepts an abbreviation wherever it accepts a task or project name: {@code -x + * grpcPerformanceT} removes {@code grpcPerformanceTest}, and {@code :g-t:gPT} a task of {@code + * :grpc-testkit}. The workflow reader compared names exactly, so an abbreviated {@code -x} — the + * form people type in a terminal and paste into a workflow — removed a lane from Gradle's plan while + * the stage check still counted it (review 2026-11-04 RR2-04-04). + * + *

The matching is a copy of Gradle's {@code org.gradle.util.internal.NameMatcher} (9.0): exact, + * then case-insensitive, then camel-case, then kebab-case abbreviation. It is copied rather than + * called because that class is internal API. Where Gradle would refuse the selector as ambiguous, + * every candidate counts as removed: the command cannot run, so it covers none of them. + */ +final class TaskSelectors { + private static final Pattern CAMEL_CASE_BOUNDARY = + Pattern.compile( + "((^|\\p{Punct})\\p{javaLowerCase}+)|((\\p{javaUpperCase}|\\p{Digit})\\p{javaLowerCase}*)"); + private static final Pattern KEBAB_BOUNDARY = + Pattern.compile("((^|\\p{Punct})\\p{javaLowerCase}+)|(\\p{javaUpperCase}\\p{javaLowerCase}*)"); + + private TaskSelectors() {} + + /** + * The paths of the tasks the selectors remove from a command started at the root project. + * + * @param selectors the {@code -x} values, as written + * @param tasksByProject each project's path ({@code :} for the root) and its task names + * @return the removed task paths + */ + static Set excludedPaths( + List selectors, Map> tasksByProject) { + Set excluded = new LinkedHashSet<>(); + for (String selector : selectors) { + excluded.addAll(selected(selector, tasksByProject)); + } + return excluded; + } + + private static Set selected( + String selector, Map> tasksByProject) { + Set paths = new LinkedHashSet<>(); + if (!selector.contains(":")) { + // A bare name is matched against every task name in the build and removes the task of that + // name in every project. + Set names = new TreeSet<>(); + tasksByProject.values().forEach(names::addAll); + for (String name : matches(selector, names)) { + tasksByProject.forEach( + (project, tasks) -> { + if (tasks.contains(name)) { + paths.add(taskPath(project, name)); + } + }); + } + return paths; + } + String relative = selector.startsWith(":") ? selector.substring(1) : selector; + String[] segments = relative.split(":", -1); + Set projects = Set.of(":"); + for (int index = 0; index < segments.length - 1; index++) { + Set next = new LinkedHashSet<>(); + for (String project : projects) { + for (String child : matches(segments[index], children(project, tasksByProject.keySet()))) { + next.add(project.equals(":") ? ":" + child : project + ":" + child); + } + } + projects = next; + } + String taskName = segments[segments.length - 1]; + for (String project : projects) { + Collection tasks = tasksByProject.get(project); + for (String name : matches(taskName, tasks == null ? List.of() : tasks)) { + paths.add(taskPath(project, name)); + } + } + return paths; + } + + private static Set children(String project, Set projects) { + String prefix = project.equals(":") ? ":" : project + ":"; + Set children = new TreeSet<>(); + for (String candidate : projects) { + if (candidate.startsWith(prefix) && candidate.length() > prefix.length()) { + String rest = candidate.substring(prefix.length()); + if (!rest.contains(":")) { + children.add(rest); + } + } + } + return children; + } + + private static String taskPath(String project, String name) { + return project.equals(":") ? ":" + name : project + ":" + name; + } + + /** + * The names {@code pattern} selects among {@code items}: one when Gradle would accept it, several + * when Gradle would refuse it as ambiguous, none when nothing matches. + */ + static Set matches(String pattern, Collection items) { + if (items.contains(pattern)) { + return Set.of(pattern); + } + if (pattern.isEmpty()) { + return Set.of(); + } + Pattern camelCase = Pattern.compile(camelCasePattern(pattern)); + Pattern camelCaseIgnoringCase = + Pattern.compile(camelCasePattern(pattern), Pattern.CASE_INSENSITIVE | Pattern.UNICODE_CASE); + String kebabCasePattern = kebabCasePattern(pattern); + Pattern kebabCase = Pattern.compile(kebabCasePattern); + Pattern kebabCasePrefix = Pattern.compile(kebabCasePattern + "[\\p{javaLowerCase}\\p{Digit}-]*"); + Set ignoringCase = new TreeSet<>(); + Set camelCaseWhole = new TreeSet<>(); + Set camelCaseStart = new TreeSet<>(); + Set camelCaseStartIgnoringCase = new TreeSet<>(); + Set kebabCaseWhole = new TreeSet<>(); + Set kebabCaseStart = new TreeSet<>(); + for (String candidate : items) { + if (candidate.equalsIgnoreCase(pattern)) { + ignoringCase.add(candidate); + } + if (camelCase.matcher(candidate).matches()) { + camelCaseWhole.add(candidate); + } + if (camelCase.matcher(candidate).lookingAt()) { + camelCaseStart.add(candidate); + } + if (camelCaseIgnoringCase.matcher(candidate).lookingAt()) { + camelCaseStartIgnoringCase.add(candidate); + } + if (kebabCase.matcher(candidate).matches()) { + kebabCaseWhole.add(candidate); + } + if (kebabCasePrefix.matcher(candidate).matches()) { + kebabCaseStart.add(candidate); + } + } + Set matches = new TreeSet<>(); + if (!ignoringCase.isEmpty()) { + matches.addAll(ignoringCase); + } else if (!camelCaseWhole.isEmpty()) { + matches.addAll(camelCaseWhole); + } else if (!camelCaseStart.isEmpty()) { + matches.addAll(camelCaseStart); + } else if (kebabCaseWhole.isEmpty() && kebabCaseStart.isEmpty()) { + matches.addAll(camelCaseStartIgnoringCase); + } + if (!kebabCaseWhole.isEmpty()) { + matches.addAll(kebabCaseWhole); + } else if (!kebabCaseStart.isEmpty()) { + matches.addAll(kebabCaseStart); + } + return matches; + } + + private static String camelCasePattern(String name) { + return pattern( + name, + CAMEL_CASE_BOUNDARY, + (builder, position, part) -> + builder.append(Pattern.quote(part)).append("[\\p{javaLowerCase}]*")); + } + + private static String kebabCasePattern(String name) { + return pattern( + name, + KEBAB_BOUNDARY, + (builder, position, part) -> { + if (position > 0) { + builder.append('-'); + } + builder + .append(Pattern.quote(part.toLowerCase(Locale.ROOT))) + .append("[\\p{javaLowerCase}\\p{Digit}]*"); + }); + } + + private interface PartWriter { + void write(StringBuilder builder, int position, String part); + } + + private static String pattern(String name, Pattern boundary, PartWriter writer) { + Matcher matcher = boundary.matcher(name); + int position = 0; + StringBuilder builder = new StringBuilder(); + while (matcher.find()) { + String prefix = name.substring(position, matcher.start()); + if (!prefix.isEmpty()) { + builder.append(Pattern.quote(prefix)); + } + writer.write(builder, position, matcher.group()); + position = matcher.end(); + } + if (position < name.length()) { + builder.append(Pattern.quote(name.substring(position))); + } + return builder.toString(); + } +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TestLaneCategory.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TestLaneCategory.java new file mode 100644 index 0000000..84eee1c --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TestLaneCategory.java @@ -0,0 +1,9 @@ +package dev.caskeleton.buildlogic.strictlane; + +public enum TestLaneCategory { + TEST, + INTEGRATION, + SYSTEM, + ARCHITECTURE, + PERFORMANCE +} diff --git a/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java new file mode 100644 index 0000000..365d2f3 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java @@ -0,0 +1,1410 @@ +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; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.Set; +import java.util.TreeSet; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +/** + * The {@code ./gradlew} commands GitHub Actions workflow files run, read from their {@code run:} + * steps. + * + *

Not a YAML parser: it reads the two shapes the workflows use — a one-line {@code run:} and a + * {@code |} or {@code >} block — and applies YAML's folding rule to the second, because a blank line + * inside a folded block ends the command (the rest becomes a separate shell command). Comments are + * dropped before anything is matched, so a task named only in a comment is not "run". + * + *

A command is read with what decides whether it gates anything (review 2026-11-03 RR-06-04): + * its {@code -x} exclusions, its {@code -m}, the options after which Gradle runs no task ({@code + * -v}, {@code --help}, {@code --status}, …), all read the way Gradle 9.0's command-line parser + * reads them (see {@code gradleInvocation}); and whether the workflow, the job and the shell + * certainly run it and certainly fail when it fails. A command that does not count is still + * returned, with its reason, which is one of three kinds (review 2026-11-05 RR6-04-05): + * + *

    + *
  1. its failure may not fail the step: {@code continue-on-error}, and the shapes {@code + * ShellScript} names ({@code || true}, a pipe without {@code pipefail}, …); + *
  2. it may not run: an {@code if:} other than a status function on its step or job, a workflow + * only a request starts, a reusable workflow no counted caller calls, a job that needs a job + * that may be skipped, and the shapes {@code ShellScript} names; + *
  3. this reader does not read it, although its failure would fail the step: a {@code shell:} + * other than {@code bash} or {@code sh}, the default shell of a runner that may be Windows, a + * directory change it does not follow, {@code gradlew} as another command's argument, and the + * shapes {@code ShellScript} names. That is a false failure on purpose (README 16). + *
+ * + *

When a workflow runs. A workflow counts when one of its triggers is part of the change + * or release flow: {@code push}, {@code pull_request} or {@code pull_request_target} (with a {@code + * 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). 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 + * through the jobs that call it ({@code uses: ./.github/workflows/}): through one whose own + * workflow counts and whose {@code if:}, {@code continue-on-error} and {@code needs:} pass. A + * workflow with no {@code on:} is not judged here; GitHub refuses it as invalid on every event. + * + *

{@code needs:}. A job runs only when every job it needs succeeded, unless its {@code + * if:} is {@code always()} or {@code !cancelled()}. So a job that needs — directly or through the + * jobs it needs — a job with an {@code if:} other than a status function (skipped while the run + * passes) or with {@code continue-on-error} may not run. + * + *

The shell. The script is read by {@code ShellScript}, in the shell the step runs: + * {@code shell: bash} ({@code bash -eo pipefail}) or {@code shell: sh} ({@code sh -e}), from the + * step, the job's or the workflow's {@code defaults.run.shell}. With none, it is the runner's + * default: {@code bash -e} on Linux and macOS, {@code sh -e} in a job's {@code container:} — both + * read the same way — and {@code pwsh} on Windows, which this reader does not read. So a step with no + * shell counts only in a job with a {@code container:}, or whose {@code runs-on} names an {@code + * ubuntu-*} or {@code macos-*} runner or a {@code linux} or {@code macos} label; a Windows label, an + * expression such as {@code ${{ matrix.os }}} or a self-hosted label set without one may be + * Windows (RR6-04-04). A job with no {@code runs-on} is not judged here; GitHub refuses it as + * invalid. A step in any other shell is returned with that reason (round 9). Inside the script, + * {@code gradlew} has to be the command the shell runs, not an argument of {@code echo} or {@code + * timeout}. + * + *

Which build a command starts is where it starts: the step's {@code working-directory} (or the + * job's or the workflow's {@code defaults.run.working-directory}), then each {@code cd} the same + * shell surely ran before it ({@code ShellScript} says which it follows), then its {@code -p}, as a + * path from the repository root (owner decision 2026-11-04). A command after a directory change + * that is not followed gets an uncounted reason naming it, so it counts for no build. A {@code + * run:} that is an input of a {@code uses:} step ({@code with: run:}) is not a shell command and is + * not read. + */ +public final class WorkflowGradleInvocations { + private static final Pattern RUN_KEY = Pattern.compile("^(\\s*)(?:-\\s+)?run:(.*)$"); + private static final Pattern BLOCK_HEADER = Pattern.compile("^([|>])[-+]?\\d*\\s*(#.*)?$"); + private static final Pattern MAPPING_KEY = + Pattern.compile("^(\\s*)(?:-\\s+)?([A-Za-z0-9_-]+):(?:\\s+(.*?))?\\s*$"); + private static final Pattern JOB_KEY = Pattern.compile("^(\\s*)([A-Za-z0-9_-]+):\\s*(#.*)?$"); + private static final Pattern JOBS_KEY = Pattern.compile("^jobs:\\s*(#.*)?$"); + /** The top-level {@code on:} key, which YAML 1.1 readers want quoted. */ + private static final Pattern TRIGGER_KEY = Pattern.compile("^(?:on|\"on\"|'on'):(?:\\s+(.*?))?\\s*$"); + /** Conditions under which a step still runs on every run whose earlier steps passed. */ + private static final Set STATUS_CONDITIONS = + Set.of("always()", "success()", "!cancelled()", "true"); + /** Conditions under which a job runs even when a job it needs was skipped or failed. */ + private static final Set RUNS_AFTER_ANY_NEEDED_JOB = Set.of("always()", "!cancelled()"); + /** The triggers of the change and release flow: a workflow with one runs without being asked. */ + private static final Set CHANGE_TRIGGERS = + Set.of("push", "pull_request", "pull_request_target", "merge_group", "schedule", "release"); + /** The pull-request activity types that come with every new change. */ + private static final Set PULL_REQUEST_CHANGE_TYPES = + 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 + * the 9.0.0 distribution (round 9): {@code gradle -q --unknown} answers "No argument was + * provided" for these, and so does {@code --} at the end of a command line. + */ + private static final Set GRADLE_VALUE_OPTIONS = + Set.of( + "D", "F", "I", "M", "P", "g", "p", "x", + "system-prop", "dependency-verification", "init-script", "write-verification-metadata", + "project-prop", "gradle-user-home", "project-dir", "exclude-task", + "configuration-cache-problems", "console", "include-build", "max-workers", "priority", + "project-cache-dir", "update-locks", "warning-mode"); + /** Gradle 9.0's command-line options that take no value and leave the build to run its tasks. */ + private static final Set GRADLE_FLAGS = + Set.of( + "a", "d", "i", "m", "q", "s", "t", "w", "S", "U", "V", + "no-rebuild", "build-cache", "no-build-cache", "configuration-cache", + "no-configuration-cache", "configure-on-demand", "no-configure-on-demand", "continue", + "no-continue", "debug", "daemon", "no-daemon", "export-keys", "info", + "dry-run", "offline", "parallel", "no-parallel", "problems-report", "no-problems-report", + "profile", "property-upgrade-report", "quiet", "refresh-keys", "rerun-tasks", + "full-stacktrace", "stacktrace", "scan", "no-scan", "continuous", + "refresh-dependencies", "show-version", "warn", "watch-fs", "no-watch-fs", + "write-locks"); + /** + * Gradle 9.0's command-line options that take no value and after which it runs no task, with what + * it does instead (review 2026-11-05 RR6-04-01). The launcher answers {@code --help} and {@code + * --version} itself; its {@code BuildActionsFactory} returns a daemon action, not a build, for + * {@code --stop}, {@code --status} and {@code --foreground}. {@code GradleCommandLineTest} holds + * all of these tables to the running Gradle's {@code --help}, and runs the launcher with each of + * these options but {@code --stop} and {@code --foreground}. + */ + private static final Map GRADLE_OPTIONS_THAT_RUN_NO_TASK = + Map.of( + "?", "prints its help and ends", + "h", "prints its help and ends", + "help", "prints its help and ends", + "v", "prints its version and ends", + "version", "prints its version and ends", + "status", "shows its daemons' status and ends", + "stop", "stops its daemons and ends", + "foreground", "runs a daemon in the foreground instead of a build"); + /** + * Options of Gradle's built-in tasks that take a value. Gradle hands an option it does not know to + * the task before it; these are read with their value so that {@code help --task ci} does not + * read as running {@code ci}. + */ + private static final Set TASK_OPTIONS_WITH_VALUE = + Set.of( + "tests", "task", "group", "configuration", "dependency", "type", "dsl", "project-name", + "package", "test-framework", "gradle-version", "distribution-type", + "gradle-distribution-url", "gradle-distribution-sha256-sum", "network-timeout"); + /** The shells whose failure handling the reader follows, as GitHub starts them. */ + private static final Map SHELLS = + Map.of( + "", new ShellScript.Options(true, false), + "bash", new ShellScript.Options(true, true), + "sh", new ShellScript.Options(true, false)); + + /** + * One Gradle command. + * + * @param workingDirectory the directory the step runs in, from the repository root, or {@code + * null} for the repository root itself + * @param projectDir the {@code -p} directory, or {@code null} for the build in the step's working + * directory + * @param tasks the task selectors it requests, in order + * @param dryRun whether it only plans ({@code --dry-run} or {@code -m}) instead of executing + * @param excludedTasks the {@code -x} / {@code --exclude-task} selectors, in order + * @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, + String projectDir, + List tasks, + boolean dryRun, + List excludedTasks, + 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. + */ + public String buildDirectory() { + return normalized( + (workingDirectory == null ? "." : workingDirectory) + + "/" + + (projectDir == null ? "." : projectDir)); + } + + /** + * Whether this command executes, and gates on, the task at {@code taskPath} (for example {@code + * :ci}; {@code ci} names the same root task) of the build in {@code buildDirectory}, a path from + * the repository root such as {@code src}. + */ + public boolean executes(String taskPath, String buildDirectory) { + return requests(taskPath) && whyNotExecuting(taskPath, buildDirectory) == null; + } + + /** + * 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. + */ + public String whyNotExecuting(String buildDirectory) { + if (uncountedReason != null) { + return uncountedReason; + } + if (!buildDirectory().equals(normalized(buildDirectory))) { + return "it starts the build in " + buildDirectory() + ", not " + normalized(buildDirectory); + } + return dryRun ? "it only plans the tasks (--dry-run), so Gradle runs no task" : null; + } + + /** Whether the command names the task at {@code taskPath}, whatever build it starts. */ + public boolean requests(String taskPath) { + String wanted = absolute(taskPath); + return tasks.stream().map(Invocation::absolute).anyMatch(wanted::equals); + } + + /** A relative path with {@code .} and {@code ..} resolved; {@code .} for the root itself. */ + static String normalized(String directory) { + Deque parts = new ArrayDeque<>(); + for (String part : directory.split("/")) { + if (part.isEmpty() || part.equals(".")) { + continue; + } + if (part.equals("..") && !parts.isEmpty() && !parts.peekLast().equals("..")) { + parts.removeLast(); + } else { + parts.addLast(part); + } + } + return parts.isEmpty() ? "." : String.join("/", parts); + } + + private static String absolute(String selector) { + return selector.startsWith(":") ? selector : ":" + selector; + } + } + + /** + * The script of one {@code run:} step, the directory it runs in, and why its commands gate + * nothing, if they do not. + */ + private record RunStep( + String script, + String workingDirectory, + ShellScript.Options shell, + String uncountedReason) {} + + /** One workflow file: its name, its lines, its triggers by event name, its jobs. */ + private record Workflow( + String file, List lines, Map triggers, Map jobs) {} + + /** + * One trigger's filters that decide whether it runs on every change. + * + * @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, 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). */ + private record Job(String id, int header, int keyIndent) {} + + private WorkflowGradleInvocations() {} + + /** + * The Gradle commands of one workflow, read on its own: a reusable workflow ({@code + * workflow_call}) has no caller here, so its commands do not count. + * + * @param workflow the workflow file's text + * @return its Gradle commands, in file order + */ + public static List read(String workflow) { + return readAll(Map.of("workflow.yml", workflow)).get("workflow.yml"); + } + + /** + * The Gradle commands of each workflow of one directory: read together, because a reusable + * workflow runs when, and only when, a workflow that calls it does. + * + * @param workflowsByFile each workflow file's text by its file name, as a {@code uses: + * ./.github/workflows/} names it + * @return each file's Gradle commands, in file order, by file name in the order given + */ + public static Map> readAll(Map workflowsByFile) { + Map workflows = new LinkedHashMap<>(); + workflowsByFile.forEach((file, text) -> workflows.put(file, parse(file, text))); + Map> invocations = new LinkedHashMap<>(); + for (Workflow workflow : workflows.values()) { + Start start = start(workflow, workflows, new HashSet<>()); + List commands = new ArrayList<>(); + 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)); + } + return invocations; + } + + /** Every option name Gradle 9.0's {@code --help} lists, without dashes. */ + static Set gradleOptionNames() { + Set names = new TreeSet<>(GRADLE_VALUE_OPTIONS); + names.addAll(GRADLE_FLAGS); + names.addAll(GRADLE_OPTIONS_THAT_RUN_NO_TASK.keySet()); + return names; + } + + /** The option names after which Gradle 9.0 runs no task. */ + static Set optionsThatRunNoTask() { + return new TreeSet<>(GRADLE_OPTIONS_THAT_RUN_NO_TASK.keySet()); + } + + /** + * The Gradle commands of one step, each with where its shell is when it runs and why it does not + * count, if it does not: the step's reason first, then an unread directory, then the shell's. + */ + private static List stepInvocations(RunStep step) { + List invocations = new ArrayList<>(); + for (ShellScript.Command command : + ShellScript.commands(step.script(), step.workingDirectory(), step.shell())) { + String reason = step.uncountedReason(); + if (reason == null && command.unreadDirectory() != null) { + reason = + "the directory it starts in is not read: " + command.unreadDirectory() + + "; start the stage command from the step's working-directory, or after a cd to" + + " a literal relative path on a line of its own"; + } + if (reason == null) { + reason = command.uncountedReason(); + } + Invocation invocation = gradleInvocation(command.words(), command.directory(), reason); + if (invocation != null) { + invocations.add(invocation); + } + } + return invocations; + } + + /** + * Lines of a folded ({@code >}) {@code run:} block that start with an option right after a blank + * line. YAML turns the blank line into a line break, so the option becomes a shell command of its + * own — {@code --stacktrace: command not found} — and the step fails before or after the Gradle + * command it was meant for. Twenty-two such steps were found across five workflows (review + * 2026-11-01, round 1 follow-up). + * + * @return one description per broken line, with its 1-based line number in the workflow + */ + public static List foldedCommandBreaks(String workflow) { + List lines = workflow.lines().toList(); + List problems = new ArrayList<>(); + for (int index = 0; index < lines.size(); index++) { + Matcher run = RUN_KEY.matcher(lines.get(index)); + if (!run.matches() || !isStepRun(lines, index)) { + continue; + } + Matcher header = BLOCK_HEADER.matcher(run.group(2).trim()); + if (!header.matches() || !header.group(1).equals(">")) { + continue; + } + int keyIndent = run.group(1).length(); + boolean afterBlank = false; + for (int next = index + 1; + next < lines.size() + && (lines.get(next).isBlank() || indentOf(lines.get(next)) > keyIndent); + next++) { + String line = lines.get(next).trim(); + if (line.isEmpty()) { + afterBlank = true; + continue; + } + if (afterBlank && line.startsWith("-")) { + problems.add( + "line " + + (next + 1) + + ": '" + + line + + "' follows a blank line inside a folded run block, so it runs as a separate" + + " shell command instead of an argument of the command above"); + } + afterBlank = false; + } + } + return List.copyOf(problems); + } + + private static Workflow parse(String file, String text) { + List lines = text.lines().toList(); + return new Workflow(file, lines, triggers(lines), jobs(lines)); + } + + private static List runSteps(Workflow workflow, String notStarted) { + List lines = workflow.lines(); + List scripts = new ArrayList<>(); + for (int index = 0; index < lines.size(); index++) { + Matcher run = RUN_KEY.matcher(lines.get(index)); + if (!run.matches() || !isStepRun(lines, index)) { + continue; + } + int keyIndent = run.group(1).length(); + String value = run.group(2).trim(); + Job job = jobAt(workflow, index); + String uncounted = uncountedReason(lines, index); + if (uncounted == null && job != null) { + uncounted = needsReason(workflow, job); + } + if (uncounted == null) { + uncounted = notStarted; + } + String directory = runSetting(lines, index, "working-directory"); + String shellName = runSetting(lines, index, "shell"); + ShellScript.Options shell = SHELLS.get(shellName == null ? "" : shellName); + if (uncounted == null && shell == null) { + uncounted = + "its step runs in shell: " + + shellName + + ", whose failure handling this check does not read (only bash and sh are" + + " read); run the stage command with shell: bash"; + } + if (uncounted == null && shellName == null) { + uncounted = defaultShellReason(workflow, job); + } + if (shell == null) { + shell = SHELLS.get(""); + } + Matcher header = BLOCK_HEADER.matcher(value); + if (!header.matches()) { + scripts.add(new RunStep(stripScalarComment(value), directory, shell, uncounted)); + continue; + } + List block = new ArrayList<>(); + int next = index + 1; + while (next < lines.size() + && (lines.get(next).isBlank() || indentOf(lines.get(next)) > keyIndent)) { + block.add(lines.get(next)); + next++; + } + index = next - 1; + int blockIndent = + block.stream().filter(line -> !line.isBlank()).mapToInt(WorkflowGradleInvocations::indentOf).min().orElse(0); + List content = + block.stream().map(line -> line.isBlank() ? "" : line.substring(blockIndent)).toList(); + scripts.add( + new RunStep( + header.group(1).equals("|") ? String.join("\n", content) : fold(content), + directory, + shell, + uncounted)); + } + return scripts; + } + + /** + * Whether the {@code run:} key at {@code index} is a step's: a key of a {@code steps:} item, not + * an input under a {@code uses:} step's {@code with:} or a {@code defaults.run} mapping. + */ + private static boolean isStepRun(List lines, int index) { + String line = lines.get(index); + if (line.trim().startsWith("-")) { + return true; + } + int keyIndent = indentOf(line); + for (int previous = index - 1; previous >= 0; previous--) { + String candidate = lines.get(previous); + if (candidate.isBlank() || candidate.trim().startsWith("#")) { + continue; + } + if (indentOf(candidate) < keyIndent) { + return candidate.trim().startsWith("-") && keyColumn(candidate) == keyIndent; + } + } + return false; + } + + // --------------------------------------------------------------------------------------------- + // When the workflow runs + + /** The workflow's triggers with their filters; empty when no {@code on:} is written. */ + private static Map triggers(List lines) { + Map triggers = new LinkedHashMap<>(); + for (int index = 0; index < lines.size(); index++) { + Matcher on = TRIGGER_KEY.matcher(lines.get(index)); + if (!on.matches()) { + continue; + } + String inline = + on.group(1) == null || on.group(1).startsWith("#") ? "" : stripScalarComment(on.group(1)); + if (inline.startsWith("{") && inline.endsWith("}")) { + for (String entry : flowItems(inline.substring(1, inline.length() - 1))) { + int colon = entry.indexOf(':'); + triggers.put( + stripScalarComment(colon < 0 ? entry : entry.substring(0, colon)), + colon < 0 ? Trigger.UNFILTERED : flowTrigger(entry.substring(colon + 1).trim())); + } + } else if (!inline.isEmpty()) { + String list = + inline.startsWith("[") && inline.endsWith("]") + ? inline.substring(1, inline.length() - 1) + : inline; + for (String trigger : flowItems(list)) { + triggers.put(trigger, Trigger.UNFILTERED); + } + } else { + blockTriggers(lines, index, triggers); + } + break; + } + return triggers; + } + + /** The triggers of a block {@code on:} at {@code onLine}: a mapping or a list. */ + private static void blockTriggers( + List lines, int onLine, Map triggers) { + int childIndent = childIndent(lines, onLine); + for (int next = onLine + 1; next < lines.size(); next++) { + String line = lines.get(next); + if (line.isBlank() || line.trim().startsWith("#")) { + continue; + } + int indent = indentOf(line); + if (indent == 0) { + break; + } + if (indent != childIndent) { + continue; + } + String key = line.trim(); + boolean item = key.startsWith("-"); + key = item ? key.substring(1).trim() : key; + int colon = key.indexOf(':'); + Trigger trigger = Trigger.UNFILTERED; + String inlineDetail = colon < 0 ? "" : key.substring(colon + 1).trim(); + if (!item && inlineDetail.startsWith("{")) { + trigger = flowTrigger(stripScalarComment(inlineDetail)); + } else if (!item && colon >= 0) { + int detailIndent = childIndent(lines, next); + if (detailIndent > childIndent) { + int typesLine = mappingKey(lines, next + 1, detailIndent, "types"); + List filters = new ArrayList<>(); + for (String filter : FILTERS) { + if (mappingKey(lines, next + 1, detailIndent, filter) >= 0) { + filters.add(filter); + } + } + trigger = Trigger.of(typesLine < 0 ? null : listValue(lines, typesLine), filters); + } + } + triggers.put(stripScalarComment(colon < 0 ? key : key.substring(0, colon)), trigger); + } + } + + /** + * The filters of a flow-mapping trigger value such as {@code {types: [created]}} or {@code + * {paths: [docs/**]}}. + */ + private static Trigger flowTrigger(String value) { + if (!value.startsWith("{") || !value.endsWith("}")) { + return Trigger.UNFILTERED; + } + List types = null; + List filters = new ArrayList<>(); + for (String entry : flowItems(value.substring(1, value.length() - 1))) { + int colon = entry.indexOf(':'); + if (colon < 0) { + continue; + } + String key = stripScalarComment(entry.substring(0, colon)); + String detail = entry.substring(colon + 1).trim(); + if (key.equals("types")) { + types = + detail.startsWith("[") && detail.endsWith("]") + ? flowItems(detail.substring(1, detail.length() - 1)) + : List.of(stripScalarComment(detail)); + } else if (FILTERS.contains(key)) { + filters.add(key); + } + } + return Trigger.of(types, filters); + } + + /** + * 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 Start start( + Workflow workflow, Map workflows, Set visiting) { + Map triggers = workflow.triggers(); + if (triggers.isEmpty()) { + return Start.EVERY_CHANGE; + } + Map pathFiltered = new LinkedHashMap<>(); + Map releaseFlow = new LinkedHashMap<>(); + for (Map.Entry trigger : triggers.entrySet()) { + 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 + } + } + } + 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")) { + 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 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()) { + for (Job job : caller.jobs().values()) { + String uses = jobValue(caller, job, "uses"); + if (uses == null || !calls(uses, workflow.file())) { + continue; + } + String reason = gatingProblem(caller.lines(), job.header() + 1, job.keyIndent(), "job"); + if (reason == null) { + reason = needsReason(caller, job); + } + if (reason == 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); + } + } + 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 Flow flow(String name, Trigger trigger) { + if (!CHANGE_TRIGGERS.contains(name)) { + return Flow.REQUEST; + } + 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) { + List described = new ArrayList<>(); + triggers.forEach( + (name, trigger) -> { + List filters = new ArrayList<>(); + if (trigger.types() != null) { + 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); + } + + /** Whether a job's {@code uses:} calls the workflow {@code file} of this directory. */ + private static boolean calls(String uses, String file) { + String target = stripScalarComment(uses); + int ref = target.indexOf('@'); + return (ref < 0 ? target : target.substring(0, ref)).equals(REUSABLE_WORKFLOWS + file); + } + + // --------------------------------------------------------------------------------------------- + // Jobs + + /** The jobs under the top-level {@code jobs:}, by id, in file order. */ + private static Map jobs(List lines) { + Map jobs = new LinkedHashMap<>(); + int jobsLine = -1; + for (int index = 0; index < lines.size() && jobsLine < 0; index++) { + if (JOBS_KEY.matcher(lines.get(index)).matches()) { + jobsLine = index; + } + } + int jobIndent = jobsLine < 0 ? -1 : childIndent(lines, jobsLine); + if (jobIndent <= 0) { + return jobs; + } + for (int index = jobsLine + 1; index < lines.size(); index++) { + String line = lines.get(index); + if (line.isBlank() || line.trim().startsWith("#")) { + continue; + } + if (indentOf(line) == 0) { + break; + } + Matcher job = JOB_KEY.matcher(line); + if (indentOf(line) == jobIndent && job.matches()) { + int keyIndent = childIndent(lines, index); + jobs.put( + job.group(2), new Job(job.group(2), index, keyIndent > jobIndent ? keyIndent : -1)); + } + } + return jobs; + } + + /** The job holding the line at {@code index}, or {@code null}. */ + private static Job jobAt(Workflow workflow, int index) { + int header = jobHeader(workflow.lines(), index); + for (Job job : workflow.jobs().values()) { + if (job.header() == header) { + return job; + } + } + return null; + } + + private static String jobValue(Workflow workflow, Job job, String key) { + return job.keyIndent() < 0 + ? null + : mappingValue(workflow.lines(), job.header() + 1, job.keyIndent(), key); + } + + private static int jobKey(Workflow workflow, Job job, String key) { + return job.keyIndent() < 0 + ? -1 + : mappingKey(workflow.lines(), job.header() + 1, job.keyIndent(), key); + } + + /** + * Why {@code job} may not run although its own conditions pass: a job it needs, directly or + * through the jobs that one needs, may be skipped or fail while the run passes; {@code null} when + * none may, or when its {@code if:} runs it after any needed job. + */ + private static String needsReason(Workflow workflow, Job job) { + String chain = needsChain(workflow, job, new HashSet<>(Set.of(job.id()))); + return chain == null + ? null + : "its job needs " + + chain + + "; a job whose needed job is skipped or fails is skipped too while the run can pass," + + " so it may not run"; + } + + private static String needsChain(Workflow workflow, Job job, Set visiting) { + String condition = jobValue(workflow, job, "if"); + if (condition != null && RUNS_AFTER_ANY_NEEDED_JOB.contains(expression(condition))) { + return null; + } + int needs = jobKey(workflow, job, "needs"); + if (needs < 0) { + return null; + } + for (String need : listValue(workflow.lines(), needs)) { + Job needed = workflow.jobs().get(need); + if (needed == null || !visiting.add(need)) { + continue; + } + String neededCondition = jobValue(workflow, needed, "if"); + if (neededCondition != null && !STATUS_CONDITIONS.contains(expression(neededCondition))) { + return need + ", which runs only if: " + neededCondition; + } + String continueOnError = jobValue(workflow, needed, "continue-on-error"); + if (continueOnError != null && !continueOnError.equals("false")) { + return need + ", which has continue-on-error: " + continueOnError; + } + String deeper = needsChain(workflow, needed, visiting); + if (deeper != null) { + return need + ", which needs " + deeper; + } + } + return null; + } + + /** + * Why a step with no {@code shell:} may run in a shell this reader does not read: its job's + * {@code runs-on} may be a Windows runner, whose default is {@code pwsh}. {@code null} for a job + * with a {@code container:} (default {@code sh -e}), a Linux or macOS runner, or no {@code + * runs-on}. + */ + private static String defaultShellReason(Workflow workflow, Job job) { + if (job == null || jobKey(workflow, job, "container") >= 0) { + return null; + } + int runsOn = jobKey(workflow, job, "runs-on"); + if (runsOn < 0) { + return null; + } + List labels = runnerLabels(workflow.lines(), runsOn); + for (String label : labels) { + String plain = label.toLowerCase(Locale.ROOT); + if (plain.startsWith("ubuntu-") + || plain.startsWith("macos-") + || plain.equals("linux") + || plain.equals("macos")) { + return null; + } + } + return "its job runs on " + + (labels.isEmpty() ? "a runner group with no labels" : String.join(", ", labels)) + + ", which may be a Windows runner, whose default shell is pwsh, and this check does not" + + " read pwsh; give the step shell: bash, or the job defaults.run.shell: bash"; + } + + /** The labels of {@code runs-on}: a scalar, a list, or the {@code labels} of a mapping. */ + private static List runnerLabels(List lines, int runsOn) { + List labels = listValue(lines, runsOn); + if (!labels.isEmpty()) { + return labels; + } + int detailIndent = childIndent(lines, runsOn); + int labelsLine = + detailIndent > keyColumn(lines.get(runsOn)) + ? mappingKey(lines, runsOn + 1, detailIndent, "labels") + : -1; + return labelsLine < 0 ? List.of() : listValue(lines, labelsLine); + } + + // --------------------------------------------------------------------------------------------- + // Steps + + /** + * The {@code run:} setting {@code key} ({@code working-directory} or {@code shell}) of the step + * at {@code runIndex}: its step's, else its job's {@code defaults.run}, else the workflow's; + * {@code null} when none is written. + */ + private static String runSetting(List lines, int runIndex, String key) { + StepScope step = stepScope(lines, runIndex); + String value = mappingValue(lines, step.start(), step.keyIndent(), key); + if (value != null) { + return value; + } + int jobHeader = jobHeader(lines, runIndex); + if (jobHeader >= 0) { + int jobKeyIndent = childIndent(lines, jobHeader); + if (jobKeyIndent > indentOf(lines.get(jobHeader))) { + value = defaultsRunSetting(lines, jobHeader + 1, jobKeyIndent, key); + if (value != null) { + return value; + } + } + } + return defaultsRunSetting(lines, 0, 0, key); + } + + /** {@code defaults.run.} of the mapping whose keys sit at {@code keyIndent}. */ + private static String defaultsRunSetting( + List lines, int start, int keyIndent, String key) { + int defaults = mappingKey(lines, start, keyIndent, "defaults"); + if (defaults < 0) { + return null; + } + int runIndent = childIndent(lines, defaults); + int run = runIndent > keyIndent ? mappingKey(lines, defaults + 1, runIndent, "run") : -1; + if (run < 0) { + return null; + } + int directoryIndent = childIndent(lines, run); + return directoryIndent > runIndent + ? mappingValue(lines, run + 1, directoryIndent, key) + : null; + } + + /** The value of {@code key} in the mapping at {@code keyIndent} starting at {@code start}. */ + private static String mappingValue(List lines, int start, int keyIndent, String key) { + int index = mappingKey(lines, start, keyIndent, key); + if (index < 0) { + return null; + } + Matcher matcher = MAPPING_KEY.matcher(lines.get(index)); + return matcher.matches() && matcher.group(3) != null + ? stripScalarComment(matcher.group(3)) + : null; + } + + /** The line of {@code key} in the mapping at {@code keyIndent} starting at {@code start}, or -1. */ + private static int mappingKey(List lines, int start, int keyIndent, String key) { + for (int index = start; index < lines.size(); index++) { + String line = lines.get(index); + if (line.isBlank() || line.trim().startsWith("#")) { + continue; + } + if (index > start && indentOf(line) < keyIndent) { + break; + } + if (index > start && keyColumn(line) == keyIndent && line.trim().startsWith("-")) { + break; + } + Matcher matcher = MAPPING_KEY.matcher(line); + if (matcher.matches() && keyColumn(line) == keyIndent && matcher.group(2).equals(key)) { + return index; + } + } + return -1; + } + + /** + * The items of the list at the key on {@code keyLine}: a flow list {@code [a, b]}, a single + * scalar, or the {@code - item} lines under it; empty when it holds a mapping or nothing. + */ + private static List listValue(List lines, int keyLine) { + Matcher key = MAPPING_KEY.matcher(lines.get(keyLine)); + String inline = key.matches() && key.group(3) != null ? stripScalarComment(key.group(3)) : ""; + if (inline.startsWith("[") && inline.endsWith("]")) { + return flowItems(inline.substring(1, inline.length() - 1)); + } + if (!inline.isEmpty()) { + return List.of(inline); + } + List items = new ArrayList<>(); + int keyIndent = keyColumn(lines.get(keyLine)); + for (int index = keyLine + 1; index < lines.size(); index++) { + String line = lines.get(index); + if (line.isBlank() || line.trim().startsWith("#")) { + continue; + } + if (indentOf(line) < keyIndent || !line.trim().startsWith("-")) { + break; + } + items.add(stripScalarComment(line.trim().substring(1).trim())); + } + return items; + } + + /** The items of a flow collection's inside, split at its top-level commas, quotes removed. */ + private static List flowItems(String inside) { + List items = new ArrayList<>(); + int depth = 0; + char quote = 0; + int start = 0; + for (int index = 0; index <= inside.length(); index++) { + char current = index < inside.length() ? inside.charAt(index) : ','; + if (quote != 0) { + quote = current == quote ? 0 : quote; + } else if (current == '\'' || current == '"') { + quote = current; + } else if (current == '[' || current == '{') { + depth++; + } else if (current == ']' || current == '}') { + depth--; + } else if (current == ',' && depth == 0) { + String item = inside.substring(start, Math.min(index, inside.length())).trim(); + if (!item.isEmpty()) { + items.add(item.contains(":") ? item : stripScalarComment(item)); + } + start = index + 1; + } + } + return items; + } + + /** The indentation of the first content line after {@code index}. */ + private static int childIndent(List lines, int index) { + for (int next = index + 1; next < lines.size(); next++) { + String line = lines.get(next); + if (!line.isBlank() && !line.trim().startsWith("#")) { + return indentOf(line); + } + } + return -1; + } + + /** Where the step holding the {@code run:} at {@code runIndex} starts, and its key column. */ + private record StepScope(int start, int keyIndent) {} + + private static StepScope stepScope(List lines, int runIndex) { + Matcher run = RUN_KEY.matcher(lines.get(runIndex)); + boolean itemLine = lines.get(runIndex).trim().startsWith("-"); + int stepKeyIndent = + itemLine + ? lines.get(runIndex).indexOf("run:") + : run.matches() ? run.group(1).length() : indentOf(lines.get(runIndex)); + int stepStart = runIndex; + if (!itemLine) { + while (stepStart > 0) { + stepStart--; + String line = lines.get(stepStart); + if (line.isBlank() || line.trim().startsWith("#")) { + continue; + } + if (indentOf(line) < stepKeyIndent) { + break; + } + } + } + return new StepScope(stepStart, stepKeyIndent); + } + + /** + * Why the {@code run:} key at {@code runIndex} gates nothing: a {@code continue-on-error} other + * than {@code false}, or an {@code if:} other than a status function, on its step or its job. + */ + private static String uncountedReason(List lines, int runIndex) { + StepScope scope = stepScope(lines, runIndex); + String step = gatingProblem(lines, scope.start(), scope.keyIndent(), "step"); + if (step != null) { + return step; + } + int jobHeader = jobHeader(lines, runIndex); + if (jobHeader < 0) { + return null; + } + int jobKeyIndent = childIndent(lines, jobHeader); + return jobKeyIndent <= indentOf(lines.get(jobHeader)) + ? null + : gatingProblem(lines, jobHeader + 1, jobKeyIndent, "job"); + } + + /** The first {@code continue-on-error} or {@code if:} at {@code keyIndent} in the mapping. */ + private static String gatingProblem(List lines, int start, int keyIndent, String scope) { + if (keyIndent < 0) { + return null; + } + for (int index = start; index < lines.size(); index++) { + String line = lines.get(index); + if (line.isBlank() || line.trim().startsWith("#")) { + continue; + } + if (index > start && indentOf(line) < keyIndent) { + break; + } + Matcher key = MAPPING_KEY.matcher(line); + if (!key.matches() || keyColumn(line) != keyIndent) { + continue; + } + String value = stripScalarComment(key.group(3) == null ? "" : key.group(3)); + if (key.group(2).equals("continue-on-error") && !value.equals("false")) { + return "its " + scope + " has continue-on-error: " + value + + ", so its failure fails nothing"; + } + if (key.group(2).equals("if") && !STATUS_CONDITIONS.contains(expression(value))) { + return "its " + + scope + + " runs only if: " + + value + + ", not on every run (only always(), success() and !cancelled() count), so it may not" + + " run"; + } + } + return null; + } + + /** The column a mapping key starts at, after a list item's {@code - }. */ + private static int keyColumn(String line) { + int column = indentOf(line); + if (line.startsWith("-", column)) { + column++; + while (column < line.length() && line.charAt(column) == ' ') { + column++; + } + } + return column; + } + + private static String expression(String condition) { + String plain = condition.trim(); + if (plain.startsWith("${{") && plain.endsWith("}}")) { + plain = plain.substring(3, plain.length() - 2).trim(); + } + return plain.replace(" ", "").toLowerCase(Locale.ROOT); + } + + /** The line of the job containing {@code index}: the last key at the indentation under {@code jobs:}. */ + private static int jobHeader(List lines, int index) { + int jobs = -1; + for (int line = 0; line < index; line++) { + if (JOBS_KEY.matcher(lines.get(line)).matches()) { + jobs = line; + } + } + if (jobs < 0) { + return -1; + } + int jobIndent = -1; + for (int line = jobs + 1; line < index; line++) { + String text = lines.get(line); + if (!text.isBlank() && !text.trim().startsWith("#")) { + jobIndent = indentOf(text); + break; + } + } + int header = -1; + for (int line = jobs + 1; line < index; line++) { + Matcher job = JOB_KEY.matcher(lines.get(line)); + if (job.matches() && job.group(1).length() == jobIndent) { + header = line; + } + } + return header; + } + + /** YAML folding: adjacent lines join with a space, and each blank line is a line break. */ + private static String fold(List content) { + StringBuilder folded = new StringBuilder(); + boolean previousWasText = false; + for (String line : content) { + if (line.isEmpty()) { + folded.append('\n'); + previousWasText = false; + } else { + if (previousWasText) { + folded.append(' '); + } + folded.append(line); + previousWasText = true; + } + } + return folded.toString(); + } + + private static String stripScalarComment(String value) { + int comment = value.indexOf(" #"); + String plain = comment < 0 ? value : value.substring(0, comment); + plain = plain.trim(); + if (plain.length() >= 2 + && (plain.startsWith("'") && plain.endsWith("'") + || plain.startsWith("\"") && plain.endsWith("\""))) { + plain = plain.substring(1, plain.length() - 1); + } + return plain; + } + + // --------------------------------------------------------------------------------------------- + // The Gradle command line + + /** + * The Gradle command a simple command runs, or {@code null} when it names no {@code gradlew}. A + * {@code gradlew} that is not the command the shell runs ({@code echo ./gradlew ci}, {@code + * timeout 60 ./gradlew ci}) is returned with that reason. + * + *

The arguments are read the way Gradle 9.0's {@code CommandLineParser} reads them (checked + * against the 9.0.0 distribution in round 9): after {@code --} every word is a task; {@code + * --name} and {@code --name=value} are long options, and Gradle also takes a short name there + * ({@code --m}); {@code -c=value} gives a one-letter option a value; a word that is a whole option + * name after one dash is that option ({@code -dry-run}); otherwise the letters are a bundle in + * which only the first may take a value, as the rest of the word ({@code -xtask}, {@code -pdir}) + * — {@code -qm} is a dry run, {@code -qv} prints the version and ends, and {@code -mx} is a + * command line Gradle rejects, because {@code -x} needs a value it is not given there. Gradle + * also rejects a value given to an option that takes none ({@code -m=yes}, {@code + * --offline=true}). A rejected command runs nothing, and neither does one with an option after + * which Gradle runs no task, so neither counts. {@code StrictLaneStagesFunctionalTest} runs + * {@code -qm} and {@code -mx} through TestKit; {@code GradleCommandLineTest} compares the option + * tables with the running Gradle's {@code --help} and runs the options that run no task. + * Whether each option takes a value was probed against 9.0.0 and is not re-run by a test: an + * upgrade that adds an option fails that test until the option is placed in a table. + */ + private static Invocation gradleInvocation( + List words, String workingDirectory, String uncountedReason) { + int at = ShellScript.commandWord(words); + int start = at >= 0 && at < words.size() && isGradlew(words.get(at)) ? at : -1; + String reason = uncountedReason; + if (start < 0) { + for (int index = 0; index < words.size(); index++) { + if (isGradlew(words.get(index))) { + start = index; + break; + } + } + if (start < 0) { + return null; + } + if (reason == null) { + reason = + "it is an argument of `" + + String.join(" ", words.subList(0, start)) + + "`, and this check does not read what another command does with its arguments; " + + ShellScript.PUT_IT_ON_ITS_OWN_LINE + + ", with gradlew as the command"; + } + } + String projectDir = null; + boolean dryRun = false; + String rejected = null; + String runsNoTask = null; + List tasks = new ArrayList<>(); + List excluded = new ArrayList<>(); + boolean onlyTasks = false; + for (int index = start + 1; index < words.size(); index++) { + String word = words.get(index); + String name = null; + String value = null; + if (onlyTasks || !word.startsWith("-") || word.equals("-")) { + tasks.add(word); + continue; + } else if (word.equals("--")) { + onlyTasks = true; + continue; + } else if (word.startsWith("--")) { + int equals = word.indexOf('='); + name = equals < 0 ? word.substring(2) : word.substring(2, equals); + value = equals < 0 ? null : word.substring(equals + 1); + if (value != null && isFlag(name) && rejected == null) { + rejected = "Gradle rejects " + word + ": --" + name + " takes no value"; + } + } else if (word.length() > 2 && word.charAt(2) == '=') { + name = word.substring(1, 2); + value = word.substring(3); + if (isFlag(name) && rejected == null) { + rejected = "Gradle rejects " + word + ": -" + name + " takes no value"; + } + } else if (GRADLE_VALUE_OPTIONS.contains(word.substring(1)) || isFlag(word.substring(1))) { + name = word.substring(1); + } else { + String first = word.substring(1, 2); + if (GRADLE_VALUE_OPTIONS.contains(first)) { + name = first; + value = word.substring(2); + } else { + for (int letter = 1; letter < word.length(); letter++) { + String option = word.substring(letter, letter + 1); + if (!isFlag(option)) { + if (rejected == null) { + rejected = + "Gradle rejects " + + word + + ": -" + + option + + (GRADLE_VALUE_OPTIONS.contains(option) + ? " takes a value, and only the first letter of a bundle can have one" + : " is not a Gradle option"); + } + break; + } + dryRun |= option.equals("m"); + if (runsNoTask == null && GRADLE_OPTIONS_THAT_RUN_NO_TASK.containsKey(option)) { + runsNoTask = noTask(word, option); + } + } + continue; + } + } + if (value == null + && (GRADLE_VALUE_OPTIONS.contains(name) || TASK_OPTIONS_WITH_VALUE.contains(name))) { + value = index + 1 < words.size() ? words.get(++index) : ""; + } + if (runsNoTask == null && GRADLE_OPTIONS_THAT_RUN_NO_TASK.containsKey(name)) { + runsNoTask = noTask(word, name); + } + switch (name) { + case "m", "dry-run" -> dryRun = true; + case "x", "exclude-task" -> excluded.add(value); + case "p", "project-dir" -> projectDir = value; + default -> { + // an option that does not decide which tasks run, or where + } + } + } + if (reason == null) { + reason = rejected != null ? rejected : runsNoTask; + } + return new Invocation(workingDirectory, projectDir, tasks, dryRun, excluded, reason, null); + } + + private static boolean isFlag(String name) { + return GRADLE_FLAGS.contains(name) || GRADLE_OPTIONS_THAT_RUN_NO_TASK.containsKey(name); + } + + private static String noTask(String word, String option) { + return "Gradle runs no task when given " + + word + + ": it " + + GRADLE_OPTIONS_THAT_RUN_NO_TASK.get(option); + } + + private static boolean isGradlew(String word) { + return word.equals("gradlew") || word.endsWith("/gradlew"); + } + + private static int indentOf(String line) { + int indent = 0; + while (indent < line.length() && line.charAt(indent) == ' ') { + indent++; + } + return indent; + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/ApiSurfacePolicyTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/ApiSurfacePolicyTest.java new file mode 100644 index 0000000..9ee6490 --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/ApiSurfacePolicyTest.java @@ -0,0 +1,48 @@ +package dev.caskeleton.buildlogic; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.io.File; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +class ApiSurfacePolicyTest { + @Test void renderUsesJavacTypesAndStableHeader(@TempDir Path temp) throws Exception { + Path root = temp.resolve("src/main/java/app"); + Files.createDirectories(root); + Files.writeString(root.resolve("Visible.java"), "package app; public strictfp class Visible {}\n"); + String rendered = ApiSurfacePolicy.render( + List.of(temp.resolve("src/main/java").toFile()), + "Fixture", "Fixture public surface", List.of("Reviewed API only"), + ":fixture", "updateFixtureApiSurface", "approveFixtureApiSurfaceChange"); + assertTrue(rendered.contains("# Fixture public surface")); + assertTrue(rendered.contains("# Reviewed API only")); + assertTrue(rendered.contains("app.Visible")); + assertEquals(1, ApiSurfacePolicy.countTypes(rendered)); + } + + @Test void verifyReportsAddedAndRemovedTypes(@TempDir Path temp) throws Exception { + File baseline = temp.resolve("surface.txt").toFile(); + Files.writeString(baseline.toPath(), "# baseline\napp.Old\n"); + IllegalStateException failure = assertThrows(IllegalStateException.class, () -> + ApiSurfacePolicy.verify("verifyFixtureApiSurface", "updateFixtureApiSurface", ":fixture", + "approveFixtureApiSurfaceChange", baseline, "# rendered\napp.New\n")); + assertTrue(failure.getMessage().contains("added:")); + assertTrue(failure.getMessage().contains("app.New")); + assertTrue(failure.getMessage().contains("removed:")); + assertTrue(failure.getMessage().contains("app.Old")); + } + + @Test void growthRequiresSeparateCeilingApproval() { + IllegalStateException failure = assertThrows(IllegalStateException.class, () -> + ApiSurfacePolicy.requireNoUnapprovedGrowth( + "updateFixtureApiSurface", ":fixture", "approveFixtureApiSurfaceChange", + "raiseFixtureApiSurfaceCeiling", 1, "# rendered\napp.One\napp.Two\n", false)); + assertTrue(failure.getMessage().contains("grow from 1 to 2 types")); + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/ModuleRegistryTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/ModuleRegistryTest.java new file mode 100644 index 0000000..861152d --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/ModuleRegistryTest.java @@ -0,0 +1,191 @@ +package dev.caskeleton.buildlogic; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.io.File; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +class ModuleRegistryTest { + @TempDir Path root; + + @BeforeEach + void setUp() throws Exception { + Files.createDirectories(root.resolve("src/alpha")); + Files.createDirectories(root.resolve("src/beta")); + } + + @Test + void wellFormedRegistryParses() { + ModuleRegistry parsed = read(valid()); + assertEquals(2, parsed.modules().size()); + assertTrue(parsed.byId("app-bootstrap").sourceDirectory().isDirectory()); + } + + @Test + void duplicateIdIsRefused() { + IllegalStateException failure = + assertThrows( + IllegalStateException.class, + () -> + read( + registry( + entry("app-bootstrap", ":app-bootstrap", "src/alpha"), + entry("example-app", ":example-app", "src/beta"), + entry("app-bootstrap", ":other", "src/alpha")))); + assertTrue(failure.getMessage().contains("duplicate module id"), failure.getMessage()); + } + + @Test + void aliasedSourceDirectoryIsRefused() { + IllegalStateException failure = + assertThrows( + IllegalStateException.class, + () -> + read( + registry( + entry("app-bootstrap", ":app-bootstrap", "src/alpha"), + entry("example-app", ":example-app", "src/beta"), + entry("aliased", ":aliased", "src/beta/../alpha")))); + assertTrue(failure.getMessage().contains("duplicate or aliased"), failure.getMessage()); + } + + @Test + void architectureEdgesRemainData() { + ModuleRegistry parsed = + read( + registry( + entry( + "app-bootstrap", + ":app-bootstrap", + "src/alpha", + "[\"example-app\",\"unknown\",\"app-bootstrap\"]"), + entry("example-app", ":example-app", "src/beta"))); + assertEquals( + List.of("example-app", "unknown", "app-bootstrap"), + parsed.byId("app-bootstrap").allowedDependencies()); + } + + @Test + void missingRequiredFieldIsRefused() { + String json = + """ + {"modules":[ + {"id":"app-bootstrap","gradle_path":":app-bootstrap","source_path":"src/alpha"}, + %s]} + """ + .formatted(entry("example-app", ":example-app", "src/beta")); + IllegalStateException failure = assertThrows(IllegalStateException.class, () -> read(json)); + assertTrue(failure.getMessage().contains("allowed_dependencies"), failure.getMessage()); + } + + @Test + void everyModuleBelongsToTheMainBuild() throws Exception { + ModuleRegistry parsed = read(registry(entry("app-bootstrap", ":app-bootstrap", "src/alpha"))); + assertEquals("main", parsed.byId("app-bootstrap").buildName()); + assertEquals(List.of("app-bootstrap"), parsed.modulesForBuild("main").stream().map(ModuleRegistry.Module::id).toList()); + } + + @Test + void aBuildFieldIsRejectedBecauseNoOtherBuildIncludesOrChecksTheModule() throws Exception { + // The optional gRPC build was the only other build; it moved to its own repository on + // 2026-11-08. A row naming any other build (a typo included) would be included by no settings + // and checked by no direction gate, while ci stays green. + Files.createDirectories(root.resolve("src/grpc/grpc-client")); + String json = + registry( + entry("app-bootstrap", ":app-bootstrap", "src/alpha"), + """ + {"id":"grpc-client","gradle_path":":grpc:grpc-client","source_path":"src/grpc/grpc-client", + "allowed_dependencies":[],"build":"optional-grpc"} + """); + IllegalStateException failure = assertThrows(IllegalStateException.class, () -> read(json)); + assertTrue(failure.getMessage().contains("'grpc-client'"), failure.getMessage()); + assertTrue(failure.getMessage().contains("'build'"), failure.getMessage()); + } + + @Test + void aBlankBuildFieldIsRefusedToo() { + String json = + """ + {"modules":[ + {"id":"app-bootstrap","gradle_path":":app-bootstrap","source_path":"src/alpha", + "allowed_dependencies":[],"build":" "}]} + """; + IllegalStateException failure = assertThrows(IllegalStateException.class, () -> read(json)); + assertTrue(failure.getMessage().contains("'build' field"), failure.getMessage()); + } + + @Test + @DisplayName("registry에 없는 디렉터리의 build 스크립트는 찾아내고, 등록된 leaf·루트·다른 빌드·build 산출물은 무시한다") + void buildScriptsOutsideTheRegistryAreReported() throws Exception { + // given + Path gradleRoot = root.resolve("src"); + Files.writeString(gradleRoot.resolve("build.gradle"), ""); + Files.writeString(gradleRoot.resolve("alpha/build.gradle"), ""); + Files.writeString(gradleRoot.resolve("beta/build.gradle"), ""); + Files.createDirectories(gradleRoot.resolve("adapter/gamma")); + Files.writeString(gradleRoot.resolve("adapter/gamma/build.gradle"), ""); + Files.createDirectories(gradleRoot.resolve("other-build")); + Files.writeString(gradleRoot.resolve("other-build/settings.gradle"), ""); + Files.writeString(gradleRoot.resolve("other-build/build.gradle"), ""); + Files.createDirectories(gradleRoot.resolve("alpha/build/tmp/fixture")); + Files.writeString(gradleRoot.resolve("alpha/build/tmp/fixture/build.gradle"), ""); + Files.createDirectories(gradleRoot.resolve("alpha/src/test/resources/fixture")); + Files.writeString(gradleRoot.resolve("alpha/src/test/resources/fixture/build.gradle"), ""); + ModuleRegistry registry = read(valid()); + + // when + List unregistered = registry.unregisteredBuildScripts(gradleRoot.toFile()); + + // then + assertEquals(List.of("adapter/gamma/build.gradle"), unregistered); + } + + private File write(String json) { + try { + Path file = root.resolve("modules.json"); + Files.writeString(file, json); + return file.toFile(); + } catch (Exception exception) { + throw new RuntimeException(exception); + } + } + + private ModuleRegistry read(String json) { + return ModuleRegistry.read(write(json), root.toFile()); + } + + private String valid() { + return registry( + entry("app-bootstrap", ":app-bootstrap", "src/alpha"), + entry("example-app", ":example-app", "src/beta")); + } + + private static String entry(String id, String path, String source) { + return entry(id, path, source, "[]"); + } + + private static String entry(String id, String path, String source, String deps) { + return "{\"id\":\"" + + id + + "\",\"gradle_path\":\"" + + path + + "\",\"source_path\":\"" + + source + + "\",\"allowed_dependencies\":" + + deps + + "}"; + } + + private static String registry(String... entries) { + return "{\"modules\":[" + String.join(",", entries) + "]}"; + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/RequiredTestExecutionTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/RequiredTestExecutionTest.java new file mode 100644 index 0000000..399159d --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/RequiredTestExecutionTest.java @@ -0,0 +1,39 @@ +package dev.caskeleton.buildlogic; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.List; +import org.junit.jupiter.api.Test; + +class RequiredTestExecutionTest { + @Test void exactMatchCounts() { + assertEquals(List.of(), RequiredTestExecution.absent(List.of("com.example.FooTest"), List.of("com.example.FooTest"))); + } + @Test void nestedClassCountsForOuterClass() { + assertEquals(List.of(), RequiredTestExecution.absent(List.of("com.example.FooTest"), List.of("com.example.FooTest$WhenEmpty"))); + } + @Test void parameterizedInvocationCountsForMethod() { + assertEquals(List.of(), RequiredTestExecution.absent(List.of("com.example.FooTest.rejects"), List.of("com.example.FooTest.rejects(String)[1]"))); + assertEquals(List.of(), RequiredTestExecution.absent(List.of("com.example.FooTest.rejects"), List.of("com.example.FooTest.rejects[2]"))); + } + @Test void differentPrefixNameIsNotMatch() { + assertEquals(List.of("com.example.FooTest"), RequiredTestExecution.absent(List.of("com.example.FooTest"), List.of("com.example.FooTestHelper"))); + } + @Test void reportsEveryAbsentSelector() { + assertEquals(List.of("com.example.A", "com.example.C"), RequiredTestExecution.absent(List.of("com.example.A", "com.example.B", "com.example.C"), List.of("com.example.B"))); + } + @Test void handlesEmptyInputs() { + assertEquals(List.of(), RequiredTestExecution.absent(List.of(), List.of("com.example.A"))); + assertEquals(List.of(), RequiredTestExecution.absent(null, List.of("com.example.A"))); + assertEquals(List.of("com.example.A"), RequiredTestExecution.absent(List.of("com.example.A"), List.of())); + assertEquals(List.of("com.example.A"), RequiredTestExecution.absent(List.of("com.example.A"), null)); + } + @Test void satisfiesIsSinglePredicate() { + assertTrue(RequiredTestExecution.satisfies("com.example.FooTest$Inner", "com.example.FooTest")); + assertTrue(RequiredTestExecution.satisfies("com.example.FooTest.bar(int)", "com.example.FooTest.bar")); + assertFalse(RequiredTestExecution.satisfies(null, "com.example.FooTest")); + assertFalse(RequiredTestExecution.satisfies("com.example.FooTest", null)); + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/apisurface/ApiSurfaceConventionTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/apisurface/ApiSurfaceConventionTest.java new file mode 100644 index 0000000..06869bc --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/apisurface/ApiSurfaceConventionTest.java @@ -0,0 +1,199 @@ +package dev.caskeleton.buildlogic.apisurface; + +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.file.Files; +import java.nio.file.Path; +import org.gradle.testkit.runner.BuildResult; +import org.gradle.testkit.runner.GradleRunner; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +class ApiSurfaceConventionTest { + @TempDir Path projectDir; + + @BeforeEach + void setUp() throws Exception { + Files.writeString(projectDir.resolve("settings.gradle"), "rootProject.name='fixture'\n"); + Path source = projectDir.resolve("src/main/java/app"); + Files.createDirectories(source); + Files.writeString(source.resolve("Visible.java"), "package app;\npublic final class Visible {}\n"); + writeConfiguredBuild("src/main/java"); + } + + @Test + void documentedFlagApprovesUpdateAndVerifyIsReadOnly() throws Exception { + BuildResult updated = + runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").build(); + assertTrue(updated.getOutput().contains("wrote"), updated.getOutput()); + assertTrue(Files.readString(projectDir.resolve("surface.txt")).contains("app.Visible")); + + BuildResult verify = + runner("verifyFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").buildAndFail(); + assertTrue(verify.getOutput().contains("read-only"), verify.getOutput()); + } + + @Test + void unapprovedAndMisnamedApprovalFlagsAreRefused() { + BuildResult noFlag = runner("updateFixtureApiSurface").buildAndFail(); + assertTrue(noFlag.getOutput().contains("requires -PapproveFixtureApiSurfaceChange")); + + BuildResult wrongFlag = + runner("updateFixtureApiSurface", "-PapprovenullApiSurfaceChange").buildAndFail(); + assertTrue(wrongFlag.getOutput().contains("requires -PapproveFixtureApiSurfaceChange")); + } + + @Test + void grownSurfaceFailsAndNamesAddedType() throws Exception { + runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").build(); + Files.writeString( + projectDir.resolve("src/main/java/app/Added.java"), + "package app;\npublic interface Added {}\n"); + BuildResult result = runner("verifyFixtureApiSurface").buildAndFail(); + assertTrue(result.getOutput().contains("app.Added"), result.getOutput()); + } + + @Test + void parserHandlesStrictfpAndIgnoresCommentedType() throws Exception { + Files.writeString( + projectDir.resolve("src/main/java/app/Strict.java"), + "package app;\npublic strictfp class Strict {}\n"); + Files.writeString( + projectDir.resolve("src/main/java/app/Commented.java"), + "package app;\n/*\npublic class Ghost {}\n*/\npublic final class Commented {}\n"); + runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").build(); + String surface = Files.readString(projectDir.resolve("surface.txt")); + assertTrue(surface.contains("app.Strict")); + assertTrue(surface.contains("app.Commented")); + assertFalse(surface.contains("app.Ghost")); + } + + @Test + void emptyOrUnparseableSurfaceFailsClosed() throws Exception { + writeConfiguredBuild("src/main/moved-away"); + BuildResult empty = runner("verifyFixtureApiSurface").buildAndFail(); + assertTrue(empty.getOutput().contains("found no public types"), empty.getOutput()); + + writeConfiguredBuild("src/main/java"); + Files.writeString( + projectDir.resolve("src/main/java/app/Broken.java"), + "package app;\npublic class Broken {\n"); + BuildResult broken = runner("verifyFixtureApiSurface").buildAndFail(); + assertTrue(broken.getOutput().contains("could not be parsed"), broken.getOutput()); + } + + @Test + void undeclaredSurfaceRegistersNoApiSurfaceTasks() throws Exception { + Files.writeString( + projectDir.resolve("build.gradle"), + """ + plugins { + id 'java' + id 'ca.api-surface' + } + """); + BuildResult result = runner("tasks", "--group=verification").build(); + assertFalse(result.getOutput().contains("ApiSurface"), result.getOutput()); + } + + @Test + void theLeafCheckRunsTheSurfaceVerification() throws Exception { + // given + runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").build(); + + // when + BuildResult result = runner("check", "--dry-run").build(); + + // then + assertTrue(result.getOutput().contains(":verifyFixtureApiSurface"), result.getOutput()); + } + + @Test + void anAdopterImportOutsideTheAdopterBaselineFailsTheVerification() throws Exception { + // given + runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").build(); + writeAdopter("package consumer;\nimport app.Visible;\npublic final class Consumer {}\n"); + Files.writeString(projectDir.resolve("adopters.txt"), "# reviewed adopter surface\n"); + + // when + BuildResult result = runner("verifyFixtureApiSurface").buildAndFail(); + + // then + assertTrue(result.getOutput().contains("Consumer.java: app.Visible"), result.getOutput()); + } + + @Test + void anAdopterImportTheAdopterBaselineListsPasses() throws Exception { + // given + runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").build(); + writeAdopter("package consumer;\nimport app.Visible;\npublic final class Consumer {}\n"); + Files.writeString(projectDir.resolve("adopters.txt"), "app.Visible\n"); + + // when + BuildResult result = runner("verifyFixtureApiSurface").build(); + + // then + assertTrue(result.getOutput().contains("OK"), result.getOutput()); + } + + @Test + void anAdopterBaselineEntryTheSurfaceNoLongerHasFailsTheVerification() throws Exception { + // given + runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").build(); + writeAdopter("package consumer;\npublic final class Consumer {}\n"); + Files.writeString(projectDir.resolve("adopters.txt"), "app.Gone\n"); + + // when + BuildResult result = runner("verifyFixtureApiSurface").buildAndFail(); + + // then + assertTrue(result.getOutput().contains("app.Gone"), result.getOutput()); + } + + private void writeAdopter(String source) throws Exception { + Path adopter = projectDir.resolve("adopter/src/consumer"); + Files.createDirectories(adopter); + Files.writeString(adopter.resolve("Consumer.java"), source); + Files.writeString( + projectDir.resolve("build.gradle"), + """ + plugins { + id 'java' + id 'ca.api-surface' + } + apiSurface { + label = 'Fixture' + baseline = file('surface.txt') + description = 'The fixture leaf public surface.' + adopterBaseline = file('adopters.txt') + adopterSources = fileTree('adopter/src') { include '**/*.java' } + } + """); + } + + private void writeConfiguredBuild(String sourceRoot) throws Exception { + Files.writeString( + projectDir.resolve("build.gradle"), + """ + plugins { + id 'java' + id 'ca.api-surface' + } + apiSurface { + label = 'Fixture' + sourceRoot = '%s' + baseline = file('surface.txt') + description = 'The fixture leaf public surface.' + } + """.formatted(sourceRoot)); + } + + private GradleRunner runner(String... args) { + return GradleRunner.create() + .withProjectDir(projectDir.toFile()) + .withPluginClasspath() + .withArguments(args); + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/CleanArchitectureResolvedClasspathFunctionalTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/CleanArchitectureResolvedClasspathFunctionalTest.java new file mode 100644 index 0000000..f3c0095 --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/CleanArchitectureResolvedClasspathFunctionalTest.java @@ -0,0 +1,182 @@ +package dev.caskeleton.buildlogic.architecture; + +import static java.nio.charset.StandardCharsets.UTF_8; +import static org.assertj.core.api.Assertions.assertThat; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import org.gradle.testkit.runner.BuildResult; +import org.gradle.testkit.runner.GradleRunner; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +class CleanArchitectureResolvedClasspathFunctionalTest { + + @Test + void transitiveApiProjectMustBeRegisteredForTheCompileVisibleConsumer(@TempDir Path temporaryRoot) + throws IOException { + Path project = fixture(temporaryRoot, false); + + BuildResult result = runner(project, "verifyCleanArchitectureDependencies").buildAndFail(); + + assertThat(result.getOutput()) + .contains("Module ':c' has forbidden project dependencies [a]") + .contains( + "Direct and compile-visible production project edges must be explicitly registered"); + } + + @Test + void aSecondCompositionRootIsGovernedByTheSameDependencyPolicy( + @TempDir Path temporaryRoot) throws IOException { + Path repository = temporaryRoot.resolve("repository"); + Path project = repository.resolve("src"); + Files.createDirectories(project.resolve("config/architecture")); + Files.createDirectories(project.resolve("a")); + Files.createDirectories(project.resolve("example-app")); + + Files.writeString( + project.resolve("settings.gradle"), + """ + rootProject.name = 'main' + include 'a', 'example-app' + """, + UTF_8); + Files.writeString( + project.resolve("build.gradle"), + """ + plugins { id 'ca.architecture' } + subprojects { apply plugin: 'java-library' } + project(':example-app') { + dependencies { implementation project(':a') } + } + """, + UTF_8); + Files.writeString( + project.resolve("config/architecture/modules.json"), + """ + { + "modules": [ + { + "id": "a", + "gradle_path": ":a", + "source_path": "a", + "allowed_dependencies": [] + }, + { + "id": "example-app", + "gradle_path": ":example-app", + "source_path": "example-app", + "allowed_dependencies": [] + } + ] + } + """, + UTF_8); + + BuildResult result = runner(project, "verifyCleanArchitectureDependencies").buildAndFail(); + + assertThat(result.getOutput()) + .contains("Module ':example-app' has forbidden project dependencies [a]"); + } + + @Test + void explicitlyRegisteredCompileVisibleTransitiveProjectPasses(@TempDir Path temporaryRoot) + throws IOException { + Path project = fixture(temporaryRoot, true); + + BuildResult result = runner(project, "verifyCleanArchitectureDependencies").build(); + + assertThat(result.getOutput()).contains("BUILD SUCCESSFUL"); + } + + @Test + @DisplayName("registry에 등록하지 않은 leaf 디렉터리에 build 스크립트가 있으면 방향 게이트가 그 경로로 실패한다") + void aLeafDirectoryMissingFromTheRegistryFailsTheGate(@TempDir Path temporaryRoot) + throws IOException { + // given + Path project = fixture(temporaryRoot, true); + Files.createDirectories(project.resolve("d")); + Files.writeString(project.resolve("d/build.gradle"), "plugins { id 'java' }\n", UTF_8); + + // when + BuildResult result = runner(project, "verifyCleanArchitectureDependencies").buildAndFail(); + + // then + assertThat(result.getOutput()).contains("d/build.gradle").contains("no registry entry"); + } + + private static Path fixture(Path temporaryRoot, boolean allowTransitiveA) throws IOException { + Path repository = temporaryRoot.resolve("repository"); + Path project = repository.resolve("src"); + Files.createDirectories(project.resolve("config/architecture")); + for (String module : new String[] {"a", "b", "c"}) { + Files.createDirectories(project.resolve(module)); + } + + Files.writeString( + project.resolve("settings.gradle"), + """ + rootProject.name = 'main' + include 'a', 'b', 'c' + """, + UTF_8); + + Files.writeString( + project.resolve("build.gradle"), + """ + plugins { id 'ca.architecture' } + subprojects { apply plugin: 'java-library' } + project(':b') { + dependencies { api project(':a') } + } + project(':c') { + dependencies { implementation project(':b') } + } + """, + UTF_8); + + String cAllowed = allowTransitiveA ? "[\"b\", \"a\"]" : "[\"b\"]"; + Files.writeString( + project.resolve("config/architecture/modules.json"), + """ + { + "modules": [ + { + "id": "a", + "gradle_path": ":a", + "source_path": "a", + "allowed_dependencies": [] + }, + { + "id": "b", + "gradle_path": ":b", + "source_path": "b", + "allowed_dependencies": ["a"] + }, + { + "id": "c", + "gradle_path": ":c", + "source_path": "c", + "allowed_dependencies": %s + } + ] + } + """ + .formatted(cAllowed), + UTF_8); + return project; + } + + private static GradleRunner runner(Path project, String... arguments) { + String[] fullArguments = new String[arguments.length + 2]; + fullArguments[0] = "--console=plain"; + fullArguments[1] = "--stacktrace"; + System.arraycopy(arguments, 0, fullArguments, 2, arguments.length); + return GradleRunner.create() + .withProjectDir(project.toFile()) + .withPluginClasspath() + .withArguments(fullArguments); + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesFunctionalTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesFunctionalTest.java new file mode 100644 index 0000000..f359db9 --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesFunctionalTest.java @@ -0,0 +1,122 @@ +package dev.caskeleton.buildlogic.architecture; + +import static java.nio.charset.StandardCharsets.UTF_8; +import static org.assertj.core.api.Assertions.assertThat; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import org.gradle.testkit.runner.BuildResult; +import org.gradle.testkit.runner.GradleRunner; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +class VerifyNoIgnoredSourcePackagesFunctionalTest { + + @Test + void sourceInAnIgnoredPackageOfAnAuxiliarySourceSetFailsTheGate(@TempDir Path temporaryRoot) + throws IOException { + // given + Path project = fixture(temporaryRoot, "a"); + source(project, "a/src/main/java/example/Ok.java"); + source(project, "a/src/integrationTest/java/example/bin/Ignored.java"); + + // when + BuildResult result = runner(project).buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("Ignored.java: package segment 'bin' collides with a build output directory name"); + } + + @Test + void sourceInAnIgnoredPackageOfAnyLeafFailsTheGate(@TempDir Path temporaryRoot) + throws IOException { + // given + Path project = fixture(temporaryRoot, "example-app"); + source(project, "example-app/src/main/java/example/Ok.java"); + source(project, "example-app/src/main/java/example/build/Ignored.java"); + + // when + BuildResult result = runner(project).buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains( + "Ignored.java: package segment 'build' collides with a build output directory name"); + } + + @Test + void gitFailingInsideACheckoutFailsTheGateInsteadOfPassing(@TempDir Path temporaryRoot) + throws IOException { + // given + Path project = fixture(temporaryRoot, "a"); + source(project, "a/src/main/java/example/Ok.java"); + Files.writeString( + project.getParent().resolve(".git"), + "gitdir: " + temporaryRoot.resolve("missing-git-dir") + "\n", + UTF_8); + + // when + BuildResult result = runner(project).buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("verifyNoIgnoredSourcePackages: `git check-ignore` exited 128"); + } + + /** One registered leaf with an extra {@code integrationTest} source set, under {@code src/}. */ + private static Path fixture(Path temporaryRoot, String leaf) throws IOException { + Path project = temporaryRoot.resolve("repository").resolve("src"); + Files.createDirectories(project.resolve("config/architecture")); + Files.createDirectories(project.resolve(leaf)); + Files.writeString( + project.resolve("settings.gradle"), + """ + rootProject.name = 'main' + include '%s' + """ + .formatted(leaf), + UTF_8); + Files.writeString( + project.resolve("build.gradle"), + """ + plugins { id 'ca.architecture' } + subprojects { + apply plugin: 'java-library' + sourceSets { integrationTest } + } + """, + UTF_8); + Files.writeString( + project.resolve("config/architecture/modules.json"), + """ + { + "modules": [ + { + "id": "%1$s", + "gradle_path": ":%1$s", + "source_path": "%1$s", + "allowed_dependencies": [] + } + ] + } + """ + .formatted(leaf), + UTF_8); + return project; + } + + private static void source(Path project, String relativePath) throws IOException { + Path file = project.resolve(relativePath); + Files.createDirectories(file.getParent()); + Files.writeString(file, "package example;\n", UTF_8); + } + + private static GradleRunner runner(Path project) { + return GradleRunner.create() + .withProjectDir(project.toFile()) + .withPluginClasspath() + .withArguments("--console=plain", "--stacktrace", "verifyNoIgnoredSourcePackages"); + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/convention/PlatformModuleConventionTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/convention/PlatformModuleConventionTest.java new file mode 100644 index 0000000..81d0db7 --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/convention/PlatformModuleConventionTest.java @@ -0,0 +1,158 @@ +package dev.caskeleton.buildlogic.convention; + +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.file.Files; +import java.nio.file.Path; +import org.gradle.testkit.runner.BuildResult; +import org.gradle.testkit.runner.GradleRunner; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +class PlatformModuleConventionTest { + @TempDir Path projectDir; + + @BeforeEach + void setUp() throws Exception { + Files.createDirectories(projectDir.resolve("gradle")); + writeCatalog(); + // java-conventions refuses a build without the container image catalog (review 2026-11-01 + // 08-04); a fixture build that starts no container still has to carry one, even empty. + Files.createDirectories(projectDir.resolve("config/testing")); + Files.writeString(projectDir.resolve("config/testing/container-images.properties"), ""); + // java-conventions takes the Maven group from this property and refuses a build without it. + Files.writeString(projectDir.resolve("gradle.properties"), "libraryGroup=org.example.fixture\n"); + Files.writeString( + projectDir.resolve("settings.gradle"), + """ + dependencyResolutionManagement { repositories { mavenCentral() } } + rootProject.name = 'fixture' + """); + } + + @Test + void platformModuleProvidesJavaLibrary() throws Exception { + buildFile( + """ + plugins { id 'ca.platform-module' } + tasks.register('reportApiConfiguration') { + boolean present = configurations.findByName('api') != null + doLast { logger.lifecycle('api-configuration-present=' + present) } + } + """); + BuildResult result = runner("reportApiConfiguration").build(); + assertTrue(result.getOutput().contains("api-configuration-present=true"), result.getOutput()); + } + + @Test + void aLeafCarriesTheReleaseVersionAndNamesTheRevisionSeparately() throws Exception { + // given + buildFile( + """ + plugins { id 'ca.platform-module' } + tasks.register('reportRelease') { + String version = project.version.toString() + String revision = project.sourceRevision + doLast { logger.lifecycle("version=" + version + " revision=" + revision) } + } + """); + + // when + BuildResult result = + runner( + "reportRelease", + "-PreleaseVersion=1.2.3", + "-PgitRevision=0123456789ABCDEF0123456789abcdef01234567") + .build(); + + // then + assertTrue( + result.getOutput().contains("version=1.2.3 revision=0123456789ab"), result.getOutput()); + } + + @Test + void aLeafWithoutACommitIdIsASnapshotOfAnUnknownRevision() throws Exception { + // given + buildFile( + """ + plugins { id 'ca.platform-module' } + tasks.register('reportRelease') { + String version = project.version.toString() + String revision = project.sourceRevision + doLast { logger.lifecycle("version=" + version + " revision=" + revision) } + } + """); + + // when + BuildResult result = runner("reportRelease", "-PgitRevision=not-a-commit").build(); + + // then + assertTrue( + result.getOutput().contains("version=0.0.1-SNAPSHOT revision=unknown"), result.getOutput()); + } + + @Test + void aReleaseVersionWithASuffixIsRefused() throws Exception { + // given + buildFile("plugins { id 'ca.platform-module' }\n"); + + // when + BuildResult result = runner("tasks", "-PreleaseVersion=v1.2.3-rc1").buildAndFail(); + + // then + assertTrue( + result.getOutput().contains("releaseVersion must be MAJOR.MINOR.PATCH"), result.getOutput()); + } + + @Test + void pinnedCatalogLibrariesAreManagedAndOthersAreNot() throws Exception { + // given: the fixture catalog carries `pinned-fixture` and `unpinned-fixture`. The project-wide + // managed versions are the ones Spring dependency management applies to every configuration, + // Checkstyle's and Error Prone's included. + buildFile( + """ + plugins { id 'ca.platform-module' } + tasks.register('reportPinned') { + String pinned = dependencyManagement.managedVersions['org.example:pinned-fixture'] + String unpinned = dependencyManagement.managedVersions['org.example:unpinned-fixture'] + doLast { logger.lifecycle('pinned=' + pinned + ' unpinned=' + unpinned) } + } + """); + + // when + BuildResult result = runner("reportPinned").build(); + + // then + assertTrue(result.getOutput().contains("pinned=2.0.1 unpinned=null"), result.getOutput()); + } + + private void writeCatalog() throws Exception { + Files.writeString( + projectDir.resolve("gradle/libs.versions.toml"), + """ + [versions] + springBoot = "4.0.8" + googleJavaFormat = "1.35.0" + checkstyle = "13.5.0" + spotbugs = "4.10.2" + findsecbugs = "1.14.0" + errorprone = "2.49.0" + + [libraries] + pinned-fixture = { module = "org.example:pinned-fixture", version = "2.0.1" } + unpinned-fixture = { module = "org.example:unpinned-fixture", version = "1.0.0" } + """); + } + + private void buildFile(String body) throws Exception { + Files.writeString(projectDir.resolve("build.gradle"), body); + } + + private GradleRunner runner(String... args) { + return GradleRunner.create() + .withProjectDir(projectDir.toFile()) + .withPluginClasspath() + .withArguments(args); + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/publishing/SigningKeysTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/publishing/SigningKeysTest.java new file mode 100644 index 0000000..9be7ffd --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/publishing/SigningKeysTest.java @@ -0,0 +1,41 @@ +package dev.caskeleton.buildlogic.publishing; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.nio.charset.StandardCharsets; +import java.util.Base64; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +class SigningKeysTest { + private static final String ARMOURED = + "-----BEGIN PGP PRIVATE KEY BLOCK-----\n\nlQdGBGrv1SYBEADGgq8C\n=abcd\n" + + "-----END PGP PRIVATE KEY BLOCK-----\n"; + + @Test + @DisplayName("armour 그대로인 키는 바꾸지 않는다") + void anArmouredKeyIsUsedAsItIs() { + assertThat(SigningKeys.armoured(ARMOURED)).isEqualTo(ARMOURED); + } + + @Test + @DisplayName("armour 파일을 base64로 감싼 값은 풀어서 armour로 쓴다") + void aBase64WrappedArmouredKeyIsUnwrapped() { + String wrapped = Base64.getEncoder().encodeToString(ARMOURED.getBytes(StandardCharsets.UTF_8)); + + assertThat(SigningKeys.armoured(wrapped)).isEqualTo(ARMOURED); + assertThat(SigningKeys.armoured(wrapped.substring(0, 40) + "\n" + wrapped.substring(40))) + .isEqualTo(ARMOURED); + } + + @Test + @DisplayName("지문이나 armour가 아닌 base64는 그대로 두어 서명이 원래 오류로 실패하게 한다") + void anythingElseIsLeftAlone() { + String fingerprint = "92646CEAFE816CF8B9C249F0A1C936D7F791F8AB"; + String otherBase64 = Base64.getEncoder().encodeToString("not a key".getBytes(StandardCharsets.UTF_8)); + + assertThat(SigningKeys.armoured(fingerprint)).isEqualTo(fingerprint); + assertThat(SigningKeys.armoured(otherBase64)).isEqualTo(otherBase64); + assertThat(SigningKeys.armoured("")).isEmpty(); + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/GradleCommandLineTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/GradleCommandLineTest.java new file mode 100644 index 0000000..e33291e --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/GradleCommandLineTest.java @@ -0,0 +1,162 @@ +package dev.caskeleton.buildlogic.strictlane; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.LinkedHashSet; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.concurrent.TimeUnit; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +/** + * Holds the workflow reader's copy of Gradle's command-line options to the Gradle that runs this + * build — the distribution the workflows' {@code ./gradlew} starts (review 2026-11-05 RR6-04-01/02). + * + *

It runs that distribution's own launcher ({@code bin/gradle}) rather than TestKit: {@code + * --help}, {@code --version}, {@code --status} and {@code --stop} are the launcher's options, and a + * workflow step runs the launcher. An upgrade that adds an option (9.2's {@code --task-graph}) fails + * the first test until the reader is told whether the option takes a value and whether Gradle then + * runs any task. + */ +class GradleCommandLineTest { + /** + * Options the reader reads as ending without a task that this test does not run: {@code --stop} + * stops every daemon of this Gradle version in the user home it is given, and {@code --foreground} + * runs a daemon until it is idle. Gradle's {@code BuildActionsFactory} returns a daemon action, not + * a build, for both. + */ + private static final Set NOT_RUN_HERE = Set.of("stop", "foreground"); + + @TempDir Path temp; + private Path project; + + @BeforeEach + void setUp() throws IOException { + project = temp.resolve("project"); + Files.createDirectories(project); + Files.writeString(project.resolve("settings.gradle"), "rootProject.name = 'probe'\n"); + Files.writeString( + project.resolve("build.gradle"), + """ + tasks.register('ci') { + def marker = file('ci-ran') + doLast { marker.text = 'ran' } + } + """); + } + + @Test + @DisplayName("판독기의 Gradle 옵션 표는 이 빌드를 돌리는 Gradle의 --help가 보이는 옵션과 정확히 같다") + void theReadersOptionTableNamesExactlyTheOptionsTheRunningGradleLists() throws Exception { + // when + Run help = gradle("--help"); + + // then + assertThat(help.exitCode()).as(help.output()).isZero(); + assertThat(optionNames(help.output())) + .as("the options of the Gradle in %s", gradleHome()) + .containsExactlyInAnyOrderElementsOf(WorkflowGradleInvocations.gradleOptionNames()); + } + + @Test + @DisplayName("판독기가 작업 없이 끝난다고 읽는 옵션을 붙이면 Gradle은 성공으로 끝나고 작업을 실행하지 않는다") + void gradleEndsWithoutRunningTheTaskWhenGivenAnOptionTheReaderReadsAsRunningNoTask() + throws Exception { + // given + List options = new ArrayList<>(); + for (String name : WorkflowGradleInvocations.optionsThatRunNoTask()) { + if (!NOT_RUN_HERE.contains(name)) { + options.add(name.length() == 1 ? "-" + name : "--" + name); + } + } + options.add("-qv"); + + // when + Map runs = new LinkedHashMap<>(); + for (String option : options) { + runs.put(option, gradle(":ci", option)); + } + + // then + assertThat(options).contains("-v", "--version", "-h", "-?", "--help", "--status"); + runs.forEach( + (option, run) -> { + assertThat(run.exitCode()).as(option + "\n" + run.output()).isZero(); + assertThat(project.resolve("ci-ran")).as(option).doesNotExist(); + }); + } + + @Test + @DisplayName("버전을 찍고 계속하는 -V를 붙이면 Gradle은 작업을 실행하므로, 위 검사는 실행을 알아볼 수 있다") + void gradleRunsTheTaskWhenGivenShowVersionWhichContinues() throws Exception { + // when + Run run = gradle(":ci", "-V"); + + // then + assertThat(run.exitCode()).as(run.output()).isZero(); + assertThat(project.resolve("ci-ran")).exists(); + } + + /** The option names a {@code --help} lists, without dashes; {@code --} itself is not an option. */ + private static Set optionNames(String help) { + Set names = new LinkedHashSet<>(); + for (String line : help.lines().toList()) { + if (!line.startsWith("-")) { + continue; + } + for (String spelling : line.split("\\s{2,}", 2)[0].split(",\\s*")) { + String name = spelling.strip().replaceFirst("^-+", ""); + if (!name.isEmpty()) { + names.add(name); + } + } + } + return names; + } + + private record Run(int exitCode, String output) {} + + /** Runs the launcher of this build's Gradle on the probe project, isolated from every daemon. */ + private Run gradle(String... arguments) throws IOException, InterruptedException { + List command = new ArrayList<>(); + boolean windows = System.getProperty("os.name").startsWith("Windows"); + command.add(gradleHome().resolve(windows ? "bin/gradle.bat" : "bin/gradle").toString()); + command.addAll( + List.of( + "--no-daemon", + "--gradle-user-home", + temp.resolve("gradle-user-home").toString(), + "--project-dir", + project.toString())); + command.addAll(List.of(arguments)); + Path output = Files.createTempFile(temp, "gradle", ".log"); + ProcessBuilder builder = + new ProcessBuilder(command).redirectErrorStream(true).redirectOutput(output.toFile()); + builder.environment().put("JAVA_HOME", System.getProperty("java.home")); + builder.environment().remove("GRADLE_OPTS"); + Process process = builder.start(); + if (!process.waitFor(5, TimeUnit.MINUTES)) { + process.destroyForcibly(); + throw new IllegalStateException("gradle " + String.join(" ", arguments) + " did not end"); + } + return new Run(process.exitValue(), Files.readString(output, StandardCharsets.UTF_8)); + } + + private static Path gradleHome() { + String home = System.getProperty("ca.gradle.home"); + assertThat(home) + .as("build-logic's test task passes the running Gradle's home as ca.gradle.home") + .isNotBlank(); + return Path.of(home); + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java new file mode 100644 index 0000000..7a0b09e --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java @@ -0,0 +1,783 @@ +package dev.caskeleton.buildlogic.strictlane; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; + +import java.nio.file.Files; +import java.nio.file.Path; +import org.gradle.testkit.runner.BuildResult; +import org.gradle.testkit.runner.GradleRunner; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +/** + * A two-project build: a root that declares stages, and a leaf with strict lanes. The workflows + * live where the real repository keeps them, one directory above the Gradle root. + */ +class StrictLaneStagesFunctionalTest { + private static final String EXECUTING_WORKFLOW = + """ + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci --stacktrace + - working-directory: src + run: ./gradlew :integrationCheck --continue --stacktrace + """; + + @TempDir Path repository; + private Path gradleRoot; + + @BeforeEach + void setUp() throws Exception { + gradleRoot = repository.resolve("src"); + Files.createDirectories(gradleRoot.resolve("leaf/src/test/java")); + Files.createDirectories(repository.resolve(".github/workflows")); + Files.writeString( + gradleRoot.resolve("settings.gradle"), "rootProject.name = 'fixture'\ninclude 'leaf'\n"); + Files.writeString( + gradleRoot.resolve("build.gradle"), + """ + plugins { id 'ca.strict-lane-stages' } + tasks.register('ci') { dependsOn ':leaf:check' } + tasks.register('integrationCheck') { dependsOn ':leaf:integrationTestLaneCheck' } + strictLaneStages { + stage ':ci', ':integrationCheck' + workflowDirectory = layout.projectDirectory.dir('../.github/workflows') + } + """); + Files.writeString( + gradleRoot.resolve("leaf/src/test/java/LaneTest.java"), + """ + class LaneTest {} + """); + } + + @Test + @DisplayName("모든 lane이 workflow가 실행하는 단계에 들어 있으면 통과한다") + void passesWhenEveryLaneIsInAnExecutedStage() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow(EXECUTING_WORKFLOW); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").build(); + + // then + assertThat(result.getOutput()).contains("every strict lane is in an executed stage"); + } + + @Test + @DisplayName("어느 단계 집계에도 들지 않는 lane이 있으면 그 lane 이름으로 실패한다") + void failsNamingALaneThatNoStageReaches() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + lane('loadLane') { performance(); tag = 'load'; description = 'Load and shutdown.' } + """); + workflow(EXECUTING_WORKFLOW); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("strict lane :leaf:loadLane is in no executed stage") + .doesNotContain("strict lane :leaf:databaseLane"); + } + + @Test + @DisplayName("단계를 workflow가 --dry-run으로만 부르면 그 단계와 그 단계에만 있는 lane을 함께 보고하고 실패한다") + void failsWhenAStageIsOnlyDryRun() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: ./gradlew :ci --stacktrace + - run: | + for gate in ci integrationCheck; do + ./gradlew "${gate}" --dry-run + done + ./gradlew integrationCheck --dry-run + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .contains("strict lane :leaf:databaseLane is in no executed stage"); + } + + @Test + @DisplayName("explicitOnly lane은 이유가 코드에 있으므로 단계 밖에 있어도 통과한다") + void explicitOnlyLaneIsExempt() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + lane('sandboxLane') { + integration(); tag = 'sandbox'; description = 'Protected sandbox.' + explicitOnly 'it needs the protected sandbox credentials' + } + """); + workflow(EXECUTING_WORKFLOW); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").build(); + + // then + assertThat(result.getOutput()).contains("every strict lane is in an executed stage"); + } + + @Test + @DisplayName("--dry-run 없이 부르면 모든 단계를 실행하게 되므로 시작 전에 거절한다") + void refusesToRunWithoutDryRun() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow(EXECUTING_WORKFLOW); + + // when + BuildResult result = runner(":verifyStrictLaneStages").buildAndFail(); + + // then + assertThat(result.getOutput()).contains("run it with --dry-run"); + } + + @Test + @DisplayName("접힌 run 블록이 빈 줄 때문에 옵션을 별개 명령으로 떼어 내면 그 workflow와 줄을 보고하고 실패한다") + void failsOnAFoldedRunBlockThatABlankLineSplits() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + EXECUTING_WORKFLOW + + """ + - name: Broken + run: >- + ./gradlew + :leaf:check + + --stacktrace + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()).contains("main.yml line 13: '--stacktrace' follows a blank line"); + } + + @Test + @DisplayName("단계를 실행해도 -x로 뺀 lane은 덮이지 않으므로 그 lane 이름으로 실패한다") + void aLaneExcludedWithDashXIsNotCoveredByTheStageThatRuns() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + lane('cacheLane') { integration(); tag = 'cache'; description = 'Real cache.' } + """); + workflow( + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: ./gradlew :ci --stacktrace + - run: ./gradlew :integrationCheck -x :leaf:databaseLane --continue + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("strict lane :leaf:databaseLane is in no executed stage") + .doesNotContain("strict lane :leaf:cacheLane"); + } + + @Test + @DisplayName("continue-on-error job이나 단계가 부르는 단계는 실패해도 막지 못하므로 실행으로 세지 않는다") + void aStageRunUnderContinueOnErrorIsNotAnExecution() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + defaults: + run: + working-directory: src + jobs: + gate: + steps: + - run: ./gradlew :ci --stacktrace + advisory: + runs-on: ubuntu-latest + continue-on-error: true + steps: + - run: ./gradlew :integrationCheck + other: + steps: + - name: Advisory step + continue-on-error: true + run: ./gradlew :integrationCheck + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .contains("strict lane :leaf:databaseLane is in no executed stage"); + } + + @Test + @DisplayName("상태 함수가 아닌 if 조건 아래의 단계 실행은 매번 돈다고 볼 수 없으므로 세지 않는다") + void aStageRunUnderAConditionIsNotAnExecution() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + defaults: + run: + working-directory: src + jobs: + gate: + steps: + - run: ./gradlew :ci --stacktrace + disabled: + if: ${{ false }} + steps: + - run: ./gradlew :integrationCheck + manual: + steps: + - if: github.event_name == 'workflow_dispatch' + run: ./gradlew :integrationCheck + reported: + steps: + - if: always() + run: ./gradlew :integrationCheck --dry-run + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()).contains("stage :integrationCheck is executed by no workflow"); + } + + @Test + @DisplayName("다른 빌드로 실행되는 빌드는 workflow가 그 디렉터리에서 시작한 단계만 실행으로 센다") + void aBuildStartedWithDashPCountsOnlyCommandsThatStartInItsDirectory() throws Exception { + // given + Path optional = gradleRoot.resolve("optional"); + Files.createDirectories(optional.resolve("leaf/src/test/java")); + Files.writeString( + optional.resolve("settings.gradle"), "rootProject.name = 'optional'\ninclude 'leaf'\n"); + Files.writeString( + optional.resolve("build.gradle"), + """ + plugins { id 'ca.strict-lane-stages' } + tasks.register('ci') { dependsOn ':leaf:check' } + tasks.register('integrationCheck') { dependsOn ':leaf:integrationTestLaneCheck' } + tasks.register('performanceCheck') { dependsOn ':leaf:check' } + strictLaneStages { + stage ':ci', ':integrationCheck', ':performanceCheck' + workflowDirectory = layout.projectDirectory.dir('../../.github/workflows') + } + """); + Files.writeString( + optional.resolve("leaf/build.gradle"), + """ + plugins { + id 'java' + id 'ca.strict-test-lane' + } + strictTestLanes { + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + } + """); + Files.writeString(optional.resolve("leaf/src/test/java/LaneTest.java"), "class LaneTest {}\n"); + workflow( + """ + jobs: + main: + steps: + - working-directory: src + run: ./gradlew -p optional ci --stacktrace + - working-directory: src/optional + run: ../gradlew performanceCheck + - working-directory: src + run: ./gradlew :integrationCheck + """); + + // when + BuildResult result = + GradleRunner.create() + .withProjectDir(optional.toFile()) + .withPluginClasspath() + .withArguments(":verifyStrictLaneStages", "--dry-run") + .buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .doesNotContain("stage :ci is executed by no workflow") + .doesNotContain("stage :performanceCheck is executed by no workflow"); + } + + @Test + @DisplayName("축약한 -x로 뺀 lane도 Gradle처럼 맞춰 보아 덮이지 않은 것으로 실패한다") + void aLaneExcludedWithAnAbbreviatedDashXIsNotCovered() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + lane('cacheLane') { integration(); tag = 'cache'; description = 'Real cache.' } + """); + workflow( + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: ./gradlew :ci --stacktrace + - run: ./gradlew :integrationCheck -x databaseL --continue + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("strict lane :leaf:databaseLane is in no executed stage") + .doesNotContain("strict lane :leaf:cacheLane"); + } + + @Test + @DisplayName("workflow_dispatch로만 시작하는 workflow가 부르는 단계는 실행으로 세지 않는다") + void aStageRunOnlyByADispatchOnlyWorkflowIsNotAnExecution() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow(EXECUTING_WORKFLOW.replace("./gradlew :integrationCheck", "./gradlew :ci")); + Files.writeString( + repository.resolve(".github/workflows/manual.yml"), + """ + on: + workflow_dispatch: + jobs: + manual: + steps: + - working-directory: src + run: ./gradlew :integrationCheck + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .contains("strict lane :leaf:databaseLane is in no executed stage"); + } + + @Test + @DisplayName("다른 빌드의 디렉터리를 working-directory로 둔 gradlew는 이 빌드의 단계 실행으로 세지 않는다") + void aCommandStartedInAnotherBuildsDirectoryIsNotThisBuildsExecution() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci --stacktrace + - working-directory: src/optional + run: ../gradlew :integrationCheck + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()).contains("stage :integrationCheck is executed by no workflow"); + } + + @Test + @DisplayName("working-directory 없이 cd src로 옮긴 뒤 단계를 부르는 workflow도 실행으로 세어 통과한다") + void passesWhenTheWorkflowCdsIntoTheBuildBeforeCallingGradlew() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + jobs: + main: + steps: + - run: cd src && ./gradlew ci --stacktrace + - run: | + cd src + ./gradlew integrationCheck --continue + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").build(); + + // then + assertThat(result.getOutput()).contains("every strict lane is in an executed stage"); + } + + @Test + @DisplayName("따라갈 수 없는 cd 뒤에 부른 단계는 세지 않고, 실패 메시지에 그 명령과 세지 않은 이유를 적는다") + void aStageCalledAfterACdThatCannotBeFollowedFailsNamingWhy() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + jobs: + main: + steps: + - run: cd src && ./gradlew ci --stacktrace + - run: cd "$GITHUB_WORKSPACE/src" && ./gradlew integrationCheck + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .contains("main.yml: gradlew integrationCheck") + .contains("cd \"$GITHUB_WORKSPACE/src\""); + } + + @Test + @DisplayName("단계를 부르지만 다른 빌드로 읽힌 명령도 실패 메시지에 그 빌드 디렉터리와 함께 적는다") + void aStageCalledForAnotherBuildIsNamedWithThatBuildInTheFailure() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + jobs: + main: + steps: + - run: cd src && ./gradlew ci --stacktrace + - run: cd scr && ./gradlew integrationCheck + - working-directory: src + run: cd src && ./gradlew integrationCheck + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .contains("main.yml: gradlew integrationCheck — it starts the build in scr, not src") + .contains("main.yml: gradlew integrationCheck — it starts the build in src/src, not src"); + } + + @Test + @DisplayName("실패를 막지 못하는 모양으로만 부른 단계는 실행으로 세지 않고, 실패 메시지에 그 이유를 적는다") + void aStageCalledOnlyInShapesThatCannotFailTheStepFailsNamingWhy() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: ./gradlew :ci --stacktrace + - run: ./gradlew :integrationCheck || true + - run: ./gradlew :integrationCheck | tee integration.log + - run: | + if ./gradlew :integrationCheck; then echo passed; fi + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .contains("strict lane :leaf:databaseLane is in no executed stage") + .contains("|| true") + .contains("pipefail") + .contains("condition of if"); + } + + @Test + @DisplayName("짧은 플래그 묶음 -qm은 Gradle이 계획만 하는 명령이고, 검사도 그 단계를 실행으로 세지 않는다") + void aBundledDryRunFlagOnlyPlansInGradleAndDoesNotCountAsAnExecution() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + EXECUTING_WORKFLOW.replace( + "./gradlew :integrationCheck --continue", "./gradlew -qm :integrationCheck")); + BuildResult gradle = runner("-qm", ":ci").build(); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(gradle.getOutput()).contains(":leaf:test SKIPPED").contains(":ci SKIPPED"); + assertThat(result.getOutput()).contains("stage :integrationCheck is executed by no workflow"); + } + + @Test + @DisplayName("값을 받는 옵션이 묶음 첫 글자가 아니면 Gradle이 명령을 거부하고, 검사도 그 이유로 세지 않는다") + void aValueOptionLaterInABundleIsRejectedByGradleAndDoesNotCount() throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + EXECUTING_WORKFLOW.replace( + "./gradlew :integrationCheck --continue", "./gradlew -mx :leaf:test :integrationCheck")); + // TestKit reports a command line Gradle rejects as an exception, not as a failed build. + Throwable gradle = catchThrowable(() -> runner("-mx", ":leaf:test", ":ci").build()); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(gradle) + .hasStackTraceContaining("No argument was provided for command-line option '-x'"); + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .contains("Gradle rejects -mx"); + } + + @Test + @DisplayName("실패하면 단계도 실패하지만 검사가 읽지 않는 모양으로만 부른 단계는 세지 않고, 그 명령을 혼자 한 줄로 두라고 안내한다") + void aStageCalledOnlyInAShapeTheCheckDoesNotReadFailsSayingToPutItOnALineOfItsOwn() + throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: ./gradlew :ci --stacktrace + - run: | + ./gradlew :integrationCheck || { echo "::error::integration failed"; exit 1; } + echo done + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .contains("this check does not read") + .contains("put the stage command on a line of its own"); + } + + @Test + @DisplayName("재사용 workflow의 단계는 매 변경에 도는 workflow가 부를 때만 세고, 요청으로만 부르면 세지 않는다") + void aStageInAReusableWorkflowCountsOnlyThroughACallerThatRunsOnEveryChange() + throws Exception { + // given + leafLanes( + """ + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + """); + workflow( + """ + on: + workflow_call: + jobs: + gate: + runs-on: ubuntu-latest + steps: + - working-directory: src + run: ./gradlew :ci --stacktrace + """); + Files.writeString( + repository.resolve(".github/workflows/integration.yml"), + """ + on: + workflow_call: + jobs: + lanes: + runs-on: ubuntu-latest + steps: + - working-directory: src + run: ./gradlew :integrationCheck --continue + """); + Files.writeString( + repository.resolve(".github/workflows/pull-request.yml"), + """ + on: pull_request + jobs: + gate: + uses: ./.github/workflows/main.yml + """); + Files.writeString( + repository.resolve(".github/workflows/on-request.yml"), + """ + on: [workflow_dispatch, repository_dispatch] + jobs: + lanes: + uses: ./.github/workflows/integration.yml + """); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("stage :integrationCheck is executed by no workflow") + .contains("integration.yml: gradlew :integrationCheck") + .contains("workflow_call") + .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"), + """ + plugins { + id 'java' + id 'ca.strict-test-lane' + } + strictTestLanes { + %s + } + """ + .formatted(lanes)); + } + + private void workflow(String content) throws Exception { + Files.writeString(repository.resolve(".github/workflows/main.yml"), content); + } + + private GradleRunner runner(String... args) { + return GradleRunner.create() + .withProjectDir(gradleRoot.toFile()) + .withPluginClasspath() + .withArguments(args); + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneConventionTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneConventionTest.java new file mode 100644 index 0000000..208f2cd --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictTestLaneConventionTest.java @@ -0,0 +1,817 @@ +package dev.caskeleton.buildlogic.strictlane; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import org.gradle.testkit.runner.BuildResult; +import org.gradle.testkit.runner.GradleRunner; +import org.gradle.testkit.runner.TaskOutcome; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +class StrictTestLaneConventionTest { + @TempDir Path projectDir; + + @BeforeEach + void setUp() throws Exception { + Files.writeString(projectDir.resolve("settings.gradle"), "rootProject.name = 'fixture'\n"); + } + + @Test + void declaredLaneBecomesVerificationTaskWithDescription() throws Exception { + buildFile( + """ + strictTestLanes { + lane('contractLane') { + tag = 'contract' + description = 'What this lane proves.' + } + } + """); + BuildResult result = runner("tasks", "--group=verification").build(); + assertTrue(result.getOutput().contains("contractLane"), result.getOutput()); + assertTrue(result.getOutput().contains("What this lane proves."), result.getOutput()); + } + + @Test + void laneWithNoSelectionFailsAtConfigurationTime() throws Exception { + buildFile( + """ + strictTestLanes { + lane('untagged') { description = 'Selects nothing.' } + } + """); + BuildResult result = runner("tasks").buildAndFail(); + assertTrue( + result.getOutput().contains("lane 'untagged'") + && result.getOutput().contains("selects nothing"), + result.getOutput()); + } + + @Test + void laneWithNoDescriptionFails() throws Exception { + buildFile( + """ + strictTestLanes { + lane('undescribed') { tag = 'contract' } + } + """); + BuildResult result = runner("tasks").buildAndFail(); + assertTrue(result.getOutput().contains("declares no description"), result.getOutput()); + } + + @Test + void emptySourceSetFailsInsteadOfNoSourceSuccess() throws Exception { + buildFile( + """ + strictTestLanes { + lane('emptyLane') { + tag = 'nothing-carries-this-tag' + description = 'Selects a tag no test declares.' + } + } + """); + BuildResult result = runner("emptyLane").buildAndFail(); + assertTrue(result.getOutput().contains("has no sources"), result.getOutput()); + } + + @Test + void tagMatchingNothingFailsWhenTestsExist() throws Exception { + buildFile( + junitDependencies() + + """ + strictTestLanes { + lane('mismatchedLane') { + tag = 'no-test-carries-this' + description = 'A tag nothing declares.' + } + } + """); + writeTest( + "PresentTest.java", + """ + import org.junit.jupiter.api.Tag; + import org.junit.jupiter.api.Test; + class PresentTest { + @Test @Tag("carried") void present() {} + } + """); + BuildResult result = runner("mismatchedLane").buildAndFail(); + assertTrue(result.getOutput().toLowerCase().contains("no test"), result.getOutput()); + } + + @Test + void laneOfOnlySkippedTestsFails() throws Exception { + buildFile( + junitDependencies() + + """ + strictTestLanes { + lane('skippedLane') { + tag = 'carried' + description = 'Every test it selects is skipped.' + } + } + """); + writeTest( + "SkippedTest.java", + """ + import org.junit.jupiter.api.Assumptions; + import org.junit.jupiter.api.Disabled; + import org.junit.jupiter.api.Tag; + import org.junit.jupiter.api.Test; + class SkippedTest { + @Test @Tag("carried") @Disabled("quarantined") void disabled() {} + @Test @Tag("carried") void assumedAway() { Assumptions.assumeTrue(false, "no docker here"); } + } + """); + BuildResult result = runner("skippedLane").buildAndFail(); + assertTrue( + result.getOutput().contains("executed no test") + && result.getOutput().contains("skipped"), + result.getOutput()); + } + + @Test + void oneExecutionAllowsOtherSkippedTests() throws Exception { + buildFile( + junitDependencies() + + """ + strictTestLanes { + lane('mixedLane') { + tag = 'carried' + description = 'One test runs, one is skipped.' + } + } + """); + writeTest( + "MixedTest.java", + """ + import org.junit.jupiter.api.Disabled; + import org.junit.jupiter.api.Tag; + import org.junit.jupiter.api.Test; + class MixedTest { + @Test @Tag("carried") @Disabled("quarantined") void disabled() {} + @Test @Tag("carried") void ran() {} + } + """); + BuildResult result = runner("mixedLane").build(); + assertTrue(result.getOutput().contains("BUILD SUCCESSFUL"), result.getOutput()); + } + + @Test + void exactTestSelectionRunsOnlyNamedTest() throws Exception { + buildFile( + junitDependencies() + + """ + strictTestLanes { + lane('namedLane') { + description = 'Runs exactly one named contract.' + requires 'SelectedTest.selected' + } + } + """); + writeTest( + "SelectedTest.java", + """ + import org.junit.jupiter.api.Test; + class SelectedTest { + @Test void selected() {} + @Test void notSelected() { throw new AssertionError("this test is not in the lane"); } + } + """); + BuildResult result = runner("namedLane").build(); + assertTrue(result.getOutput().contains("BUILD SUCCESSFUL"), result.getOutput()); + } + + @Test + void missingRequiredTestFailsLane() throws Exception { + buildFile( + junitDependencies() + + """ + strictTestLanes { + lane('renamedLane') { + description = 'Names a test that was renamed away.' + requires 'SelectedTest.selected', 'SelectedTest.renamedAway' + } + } + """); + writeTest( + "SelectedTest.java", + """ + import org.junit.jupiter.api.Test; + class SelectedTest { @Test void selected() {} } + """); + BuildResult result = runner("renamedLane").buildAndFail(); + assertTrue( + result.getOutput().contains("renamedAway") + || result.getOutput().toLowerCase().contains("no tests found"), + result.getOutput()); + } + + @Test + void tagAndRequiredTestsCannotBothBeDeclared() throws Exception { + buildFile( + """ + strictTestLanes { + lane('doubleSelection') { + tag = 'contract' + description = 'Two selections at once.' + requires 'SomeTest.some' + } + } + """); + BuildResult result = runner("tasks").buildAndFail(); + assertTrue(result.getOutput().contains("pick one selection"), result.getOutput()); + } + + @Test + void duplicateLaneTaskNameFails() throws Exception { + buildFile( + """ + tasks.register('contractLane') { } + strictTestLanes { + lane('contractLane') { + tag = 'contract' + description = 'Collides with an existing task.' + } + } + """); + BuildResult result = runner("tasks").buildAndFail(); + assertTrue(result.getOutput().contains("contractLane"), result.getOutput()); + } + + @Test + void aLaneNamedAfterItsJvmTestSuiteMakesTheSuiteTaskStrict() throws Exception { + // given + buildFile( + """ + testing { + suites { + integrationTest(JvmTestSuite) { + useJUnitJupiter('5.11.3') + dependencies { implementation project() } + } + } + } + strictTestLanes { + lane('integrationTest') { + integration() + sourceSet = 'integrationTest' + description = 'The suite task under strict-lane rules.' + } + } + """); + Path suiteSource = projectDir.resolve("src/integrationTest/java"); + Files.createDirectories(suiteSource); + Files.writeString( + suiteSource.resolve("QuarantinedTest.java"), + """ + import org.junit.jupiter.api.Disabled; + import org.junit.jupiter.api.Test; + class QuarantinedTest { + @Test @Disabled("quarantined") void quarantined() {} + } + """); + + // when + BuildResult result = runner("integrationTest", "integrationTestLaneCheck").buildAndFail(); + + // then + assertTrue(result.getOutput().contains("a skip is not a result"), result.getOutput()); + } + + @Test + void laneSupportsTypedRuntimeAndOrderingOptions() throws Exception { + Files.createDirectories(projectDir.resolve("contracts")); + Files.writeString(projectDir.resolve("contracts/contract.txt"), "contract"); + buildFile( + """ + sourceSets { architecture } + tasks.register('fixtureProducer') + strictTestLanes { + lane('architectureLane') { + sourceSet = 'architecture' + description = 'Architecture verification.' + group = 'architecture verification' + maxHeapSize = '512m' + jvmArgs '-Duser.timezone=UTC' + shouldRunAfter 'test' + dependsOn 'fixtureProducer' + systemProperty 'lane.mode', 'strict' + inputDirectory file('contracts') + } + } + tasks.register('reportLane') { + doLast { + def lane = tasks.named('architectureLane', Test).get() + logger.lifecycle('group=' + lane.group) + logger.lifecycle('heap=' + lane.maxHeapSize) + logger.lifecycle('utc=' + lane.allJvmArgs.contains('-Duser.timezone=UTC')) + logger.lifecycle('after-test=' + lane.shouldRunAfter.getDependencies(lane)*.name.contains('test')) + logger.lifecycle('depends-producer=' + lane.taskDependencies.getDependencies(lane)*.name.contains('fixtureProducer')) + logger.lifecycle('mode=' + lane.systemProperties['lane.mode']) + logger.lifecycle('input=' + lane.inputs.files.files.any { it.name == 'contract.txt' }) + } + } + """); + + BuildResult result = runner("reportLane", "--console=plain").build(); + assertTrue(result.getOutput().contains("group=architecture verification"), result.getOutput()); + assertTrue(result.getOutput().contains("heap=512m"), result.getOutput()); + assertTrue(result.getOutput().contains("utc=true"), result.getOutput()); + assertTrue(result.getOutput().contains("after-test=true"), result.getOutput()); + assertTrue(result.getOutput().contains("depends-producer=true"), result.getOutput()); + assertTrue(result.getOutput().contains("mode=strict"), result.getOutput()); + assertTrue(result.getOutput().contains("input=true"), result.getOutput()); + } + + @Test + void rejectSkippedFailsWhenAnySelectedTestIsSkipped() throws Exception { + buildFile( + junitDependencies() + + """ + strictTestLanes { + lane('strictNoSkip') { + tag = 'carried' + description = 'Every selected test must execute.' + rejectSkipped = true + } + } + """); + writeTest( + "StrictNoSkipTest.java", + """ + import org.junit.jupiter.api.Disabled; + import org.junit.jupiter.api.Tag; + import org.junit.jupiter.api.Test; + class StrictNoSkipTest { + @Test @Tag("carried") void ran() {} + @Test @Tag("carried") @Disabled("must fail lane") void skipped() {} + } + """); + + BuildResult result = runner("strictNoSkip").buildAndFail(); + assertTrue(result.getOutput().contains("forbids skipped tests"), result.getOutput()); + } + + @Test + void categoryAggregatesFollowRepositoryTestTaxonomy() throws Exception { + buildFile( + """ + sourceSets { ordinary; integration; system; architecture; performance } + strictTestLanes { + lane('ordinaryLane') { + sourceSet = 'ordinary' + description = 'Hermetic test.' + } + lane('integrationLane') { + sourceSet = 'integration' + description = 'External-infrastructure integration.' + integration() + } + lane('systemLane') { + sourceSet = 'system' + description = 'Full application/system test.' + system() + } + lane('architectureLane') { + sourceSet = 'architecture' + description = 'Architecture.' + architecture() + } + lane('performanceLane') { + sourceSet = 'performance' + description = 'Performance.' + performance() + } + } + tasks.register('reportCategories') { + doLast { + ['strictTestLaneCheck', 'testLaneCheck', 'integrationTestLaneCheck', 'systemTestLaneCheck', + 'architectureTestLaneCheck', 'performanceTestLaneCheck'].each { name -> + def aggregate = tasks.named(name).get() + logger.lifecycle(name + '=' + aggregate.taskDependencies.getDependencies(aggregate)*.name.sort()) + } + } + } + """); + + BuildResult result = runner("reportCategories", "--console=plain").build(); + assertTrue( + result.getOutput().contains( + "strictTestLaneCheck=[architectureLane, integrationLane, ordinaryLane, performanceLane, systemLane]"), + result.getOutput()); + assertTrue(result.getOutput().contains("testLaneCheck=[ordinaryLane]"), result.getOutput()); + assertTrue(result.getOutput().contains("integrationTestLaneCheck=[integrationLane]"), result.getOutput()); + assertTrue(result.getOutput().contains("systemTestLaneCheck=[systemLane]"), result.getOutput()); + assertTrue(result.getOutput().contains("architectureTestLaneCheck=[architectureLane]"), result.getOutput()); + assertTrue(result.getOutput().contains("performanceTestLaneCheck=[performanceLane]"), result.getOutput()); + } + + @Test + void dedicatedSourceSetNeedsNoTag() throws Exception { + buildFile( + """ + sourceSets { performance } + strictTestLanes { + lane('performanceLane') { + sourceSet = 'performance' + description = 'Its own source set is the selection.' + } + } + """); + BuildResult result = runner("tasks", "--group=verification").build(); + assertTrue(result.getOutput().contains("performanceLane"), result.getOutput()); + } + + @Test + void aMainStageLaneLeavesTheLeafTestTaskAndJoinsMainCheck() throws Exception { + // given + buildFile( + junitDependencies() + + """ + tasks.register('mainCheck') + strictTestLanes { + lane('documentContractTest') { + tag = 'document-contract' + description = 'Compares the leaf with its documents.' + rejectSkipped = true + mainStage() + } + } + """); + writeTest( + "DocumentTest.java", + """ + import org.junit.jupiter.api.Tag; + import org.junit.jupiter.api.Test; + class DocumentTest { + @Test @Tag("document-contract") void comparesDocuments() { + throw new AssertionError("document lane test ran in the pull-request test task"); + } + @Test void ordinary() {} + } + """); + + // when + BuildResult test = runner("test").build(); + BuildResult mainCheck = runner("mainCheck", "--dry-run").build(); + + // then + assertTrue(test.getOutput().contains("BUILD SUCCESSFUL"), test.getOutput()); + assertTrue(mainCheck.getOutput().contains(":documentContractTest"), mainCheck.getOutput()); + } + + @Test + void anExplicitOnlyLaneStaysOutOfEveryAggregate() throws Exception { + // given + buildFile( + """ + sourceSets { integration } + strictTestLanes { + lane('credentialLane') { + sourceSet = 'integration' + description = 'Needs protected credentials.' + integration() + explicitOnly 'the protected credentials are not set' + } + } + tasks.register('reportAggregates') { + doLast { + ['strictTestLaneCheck', 'integrationTestLaneCheck'].each { name -> + def aggregate = tasks.named(name).get() + logger.lifecycle(name + '=' + aggregate.taskDependencies.getDependencies(aggregate)*.name.sort()) + } + } + } + """); + + // when + BuildResult result = + runner("reportAggregates", "integrationTestLaneCheck", "--console=plain").build(); + + // then + assertTrue(result.getOutput().contains("strictTestLaneCheck=[]"), result.getOutput()); + assertTrue(result.getOutput().contains("integrationTestLaneCheck=[]"), result.getOutput()); + assertTrue( + result.getOutput().contains("the protected credentials are not set"), result.getOutput()); + } + + @Test + @DisplayName("hermetic lane은 같은 입력이면 build cache에서 가져오고, 외부 상태와 문서를 보는 lane은 매번 다시 돈다") + void hermeticLanesComeFromTheBuildCacheWhileExternalAndMainStageLanesRunAgain() + throws Exception { + // given + buildFile( + junitDependencies() + + """ + tasks.register('mainCheck') + strictTestLanes { + lane('unitLane') { tag = 'unit'; description = 'Hermetic.' } + lane('rulesLane') { architecture(); tag = 'rules'; description = 'Architecture rules.' } + lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } + lane('documentLane') { tag = 'document-contract'; description = 'Documents.'; mainStage() } + } + """); + writeTest( + "LanesTest.java", + """ + import org.junit.jupiter.api.Tag; + import org.junit.jupiter.api.Test; + class LanesTest { + @Test @Tag("unit") void unit() {} + @Test @Tag("rules") void rules() {} + @Test @Tag("db") void database() {} + @Test @Tag("document-contract") void document() {} + } + """); + String[] lanes = {"unitLane", "rulesLane", "databaseLane", "documentLane", "--build-cache"}; + runner(lanes).build(); + runner("clean").build(); + + // when + BuildResult second = runner(lanes).build(); + + // then + assertThat( + List.of(":unitLane", ":rulesLane", ":databaseLane", ":documentLane").stream() + .map(path -> second.task(path).getOutcome()) + .toList()) + .containsExactly( + TaskOutcome.FROM_CACHE, TaskOutcome.FROM_CACHE, TaskOutcome.SUCCESS, TaskOutcome.SUCCESS); + } + + @Test + @DisplayName("lane 정책만 바꾼 다음 실행은 이전 결과를 다시 쓰지 않고 새 정책으로 판정한다") + void aLanePolicyChangeIsJudgedAgainInsteadOfReusingTheEarlierResult() throws Exception { + // given + String lane = + """ + strictTestLanes { + lane('carriedLane') { + tag = 'carried' + description = 'Selected tests.' + rejectSkipped = %s + } + } + """; + buildFile(junitDependencies() + lane.formatted("false")); + writeTest( + "CarriedTest.java", + """ + import org.junit.jupiter.api.Disabled; + import org.junit.jupiter.api.Tag; + import org.junit.jupiter.api.Test; + class CarriedTest { + @Test @Tag("carried") void ran() {} + @Test @Tag("carried") @Disabled("skipped while the policy allowed it") void skipped() {} + } + """); + runner("carriedLane", "--build-cache").build(); + buildFile(junitDependencies() + lane.formatted("true")); + + // when + BuildResult stricter = runner("carriedLane", "--build-cache").buildAndFail(); + + // then + assertThat(stricter.getOutput()).contains("forbids skipped tests"); + } + + @Test + @DisplayName("서버를 띄우지 않는 TEST·ARCHITECTURE lane은 실서버 lane의 단일 슬롯을 잡지 않는다") + void onlyServerLanesTakeTheExclusiveRealServerSlot() throws Exception { + // given + buildFile( + """ + sourceSets { architecture; integration } + strictTestLanes { + lane('rulesLane') { sourceSet = 'architecture'; architecture(); description = 'Architecture rules.' } + lane('databaseLane') { sourceSet = 'integration'; integration(); description = 'Real database.' } + } + tasks.register('reportSlots') { + doLast { + ['rulesLane', 'databaseLane'].each { name -> + def lane = tasks.named(name).get() + def services = lane.requiredServices.elements*.name + logger.lifecycle(name + '=' + services.contains('exclusiveRealServerLane')) + } + } + } + """); + + // when + BuildResult result = runner("reportSlots", "--console=plain").build(); + + // then + assertThat(result.getOutput()).contains("rulesLane=false").contains("databaseLane=true"); + } + + @Test + void aPerformanceLaneFailsOnAnExceededBoundWhenTheBuildSetsNoAssertionsProperty() + throws Exception { + // given + buildFile(performanceLane("")); + writePerformanceTest( + "BoundTest.java", + """ + import org.junit.jupiter.api.Test; + class BoundTest { + @Test void staysInsideTheBound() { + long p99Millis = 900; + // The shape the httpclient lane had: the machine-dependent bound behind the switch. + if (Boolean.parseBoolean(System.getProperty("performance.assertions.enabled", "false")) + && p99Millis > 500) { + throw new AssertionError("p99 900ms above the 500ms bound"); + } + } + } + """); + + // when + BuildResult result = runner("performanceTestLaneCheck").buildAndFail(); + + // then + assertThat(result.getOutput()).contains("BoundTest > staysInsideTheBound() FAILED"); + } + + @Test + void aPerformanceLaneFailsBeforeTestingWhenTheBuildTurnsItsAssertionsOff() throws Exception { + // given + buildFile(performanceLane("")); + writePerformanceTest( + "MeasuredTest.java", + """ + import org.junit.jupiter.api.Test; + class MeasuredTest { + @Test void measured() { throw new AssertionError("the lane ran a test"); } + } + """); + + // when + BuildResult result = + runner("performanceTestLaneCheck", "-Pperformance.assertions.enabled=false") + .buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("this build sets performance.assertions.enabled=false") + .contains("set it to true") + .doesNotContain("MeasuredTest > measured() FAILED"); + } + + @Test + void aPerformanceLaneFailsWhenItsOwnDeclarationTurnsTheAssertionsOff() throws Exception { + // given + buildFile( + performanceLane( + """ + systemProperty 'performance.assertions.enabled', + providers.gradleProperty('performance.assertions.enabled').orElse('false').get() + """)); + writePerformanceTest( + "MeasuredTest.java", + """ + import org.junit.jupiter.api.Test; + class MeasuredTest { @Test void measured() {} } + """); + + // when + BuildResult result = runner("performanceTestLaneCheck").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("its test JVM would get performance.assertions.enabled=false") + .contains("delete the override"); + } + + @Test + void aPerformanceLaneFailsWhenItsJvmArgumentsTurnTheAssertionsOff() throws Exception { + // given + buildFile(performanceLane("jvmArgs '-Dperformance.assertions.enabled=false'")); + writePerformanceTest( + "MeasuredTest.java", + """ + import org.junit.jupiter.api.Test; + class MeasuredTest { @Test void measured() {} } + """); + + // when + BuildResult result = runner("performanceTestLaneCheck").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("its test JVM would get performance.assertions.enabled=false") + .contains("delete the override"); + } + + @Test + void aPerformanceLaneFailsWhenOneOfItsTestsIsSkipped() throws Exception { + // given + buildFile(performanceLane("")); + writePerformanceTest( + "PartlyMeasuredTest.java", + """ + import org.junit.jupiter.api.Disabled; + import org.junit.jupiter.api.Test; + class PartlyMeasuredTest { + @Test void measured() {} + @Test @Disabled("too slow on this machine") void quarantined() {} + } + """); + + // when + BuildResult result = runner("performanceTestLaneCheck").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("forbids skipped tests") + .contains("a skipped test is a bound nobody measured"); + } + + @Test + void aPerformanceLaneAcceptsABuildThatTurnsItsAssertionsOnExplicitly() throws Exception { + // given + buildFile(performanceLane("")); + writePerformanceTest( + "MeasuredTest.java", + """ + import org.junit.jupiter.api.Test; + class MeasuredTest { @Test void measured() {} } + """); + + // when + BuildResult result = + runner("performanceTestLaneCheck", "-Pperformance.assertions.enabled=true").build(); + + // then + assertThat(result.task(":loadLane").getOutcome()).isEqualTo(TaskOutcome.SUCCESS); + } + + private void buildFile(String laneBlock) throws Exception { + Files.writeString( + projectDir.resolve("build.gradle"), + """ + plugins { + id 'java' + id 'ca.strict-test-lane' + } + repositories { mavenCentral() } + %s + """ + .formatted(laneBlock)); + } + + private void writeTest(String fileName, String source) throws Exception { + Path testSource = projectDir.resolve("src/test/java"); + Files.createDirectories(testSource); + Files.writeString(testSource.resolve(fileName), source); + } + + private void writePerformanceTest(String fileName, String source) throws Exception { + Path performanceSource = projectDir.resolve("src/performance/java"); + Files.createDirectories(performanceSource); + Files.writeString(performanceSource.resolve(fileName), source); + } + + private static String performanceLane(String extraDeclarations) { + return """ + sourceSets { performance } + dependencies { + performanceImplementation platform('org.junit:junit-bom:5.11.3') + performanceImplementation 'org.junit.jupiter:junit-jupiter' + performanceRuntimeOnly 'org.junit.platform:junit-platform-launcher' + } + strictTestLanes { + lane('loadLane') { + performance() + sourceSet = 'performance' + description = 'Measures a resource bound.' + %s + } + } + """ + .formatted(extraDeclarations); + } + + private static String junitDependencies() { + return """ + dependencies { + testImplementation platform('org.junit:junit-bom:5.11.3') + testImplementation 'org.junit.jupiter:junit-jupiter' + testRuntimeOnly 'org.junit.platform:junit-platform-launcher' + } + """; + } + + private GradleRunner runner(String... args) { + return GradleRunner.create() + .withProjectDir(projectDir.toFile()) + .withPluginClasspath() + .withArguments(args); + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/TaskSelectorsTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/TaskSelectorsTest.java new file mode 100644 index 0000000..76a189d --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/TaskSelectorsTest.java @@ -0,0 +1,71 @@ +package dev.caskeleton.buildlogic.strictlane; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.List; +import java.util.Map; +import java.util.Set; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +class TaskSelectorsTest { + + private static final Map> BUILD = + Map.of( + ":", Set.of("ci", "performanceCheck", "test"), + ":grpc", Set.of("test"), + ":grpc:grpc-testkit", + Set.of("test", "testClasses", "grpcPerformanceTest", "grpcPerformanceTestClasses"), + ":leaf", Set.of("test", "databaseLane", "databaseLoadTest")); + + @Test + @DisplayName("이름이 정확히 같은 태스크가 있으면 그 이름만 모든 프로젝트에서 뺀다") + void anExactNameRemovesOnlyThatNameInEveryProject() { + // when + Set excluded = TaskSelectors.excludedPaths(List.of("test"), BUILD); + + // then + assertThat(excluded) + .containsExactlyInAnyOrder(":test", ":grpc:test", ":grpc:grpc-testkit:test", ":leaf:test"); + } + + @Test + @DisplayName("camel-case 축약 이름은 Gradle처럼 그 태스크를 뺀다") + void aCamelCaseAbbreviationRemovesTheTaskGradleWouldRemove() { + // when + Set excluded = TaskSelectors.excludedPaths(List.of("grpcPerformanceT"), BUILD); + + // then + assertThat(excluded).containsExactly(":grpc:grpc-testkit:grpcPerformanceTest"); + } + + @Test + @DisplayName("경로의 프로젝트 이름도 축약할 수 있다") + void aQualifiedSelectorMayAbbreviateItsProjectNames() { + // when + Set excluded = TaskSelectors.excludedPaths(List.of(":grpc:grpcT:gPT"), BUILD); + + // then + assertThat(excluded).containsExactly(":grpc:grpc-testkit:grpcPerformanceTest"); + } + + @Test + @DisplayName("Gradle이 모호하다고 거부할 축약은 후보 전부를 뺀 것으로 본다") + void anAmbiguousAbbreviationRemovesEveryCandidate() { + // when + Set excluded = TaskSelectors.excludedPaths(List.of("database"), BUILD); + + // then + assertThat(excluded).containsExactlyInAnyOrder(":leaf:databaseLane", ":leaf:databaseLoadTest"); + } + + @Test + @DisplayName("맞는 태스크가 없는 선택자는 아무것도 빼지 않는다") + void aSelectorThatMatchesNothingRemovesNothing() { + // when + Set excluded = TaskSelectors.excludedPaths(List.of(":leaf:cacheLane"), BUILD); + + // then + assertThat(excluded).isEmpty(); + } +} diff --git a/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java b/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java new file mode 100644 index 0000000..ab24e44 --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java @@ -0,0 +1,1581 @@ +package dev.caskeleton.buildlogic.strictlane; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.buildlogic.strictlane.WorkflowGradleInvocations.Invocation; +import java.util.List; +import java.util.Map; +import java.util.Set; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +class WorkflowGradleInvocationsTest { + + @Test + @DisplayName("한 줄 run 단계의 gradlew 명령은 그 태스크를 실행하는 것으로 읽는다") + void oneLineRunStepExecutesItsTasks() { + // given + String workflow = + """ + jobs: + gate: + steps: + - name: Run + working-directory: src + run: ./gradlew :mainCheck --continue --warning-mode=fail --stacktrace + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).singleElement().satisfies( + invocation -> { + assertThat(invocation.tasks()).containsExactly(":mainCheck"); + assertThat(invocation.executes(":mainCheck", "src")).isTrue(); + }); + } + + @Test + @DisplayName("--dry-run 명령은 태스크를 계획만 하므로 실행으로 세지 않는다") + void dryRunPlansButDoesNotExecute() { + // given + String workflow = + """ + - run: | + for gate in ci integrationCheck; do + ./gradlew "${gate}" --dry-run --configuration-cache + done + ./gradlew integrationCheck -m + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .isNotEmpty() + .noneMatch(invocation -> invocation.executes(":integrationCheck", ".")); + } + + @Test + @DisplayName("주석에만 적힌 태스크는 실행으로 세지 않는다") + void taskNamedOnlyInACommentIsNotExecuted() { + // given + String workflow = + """ + # ./gradlew :integrationCheck runs every lane + job: + steps: + - run: ./gradlew :ci --stacktrace # then ./gradlew :integrationCheck + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .noneMatch(invocation -> invocation.executes(":integrationCheck", ".")) + .anyMatch(invocation -> invocation.executes(":ci", ".")); + } + + @Test + @DisplayName("-p로 다른 빌드를 실행하는 명령은 시작 빌드의 같은 이름 태스크로 세지 않는다") + void otherBuildDoesNotCountForTheStartBuild() { + // given + String workflow = + """ + - run: ./gradlew -p optional-platforms integrationCheck --stacktrace + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).singleElement().satisfies( + invocation -> { + assertThat(invocation.projectDir()).isEqualTo("optional-platforms"); + assertThat(invocation.executes(":integrationCheck", ".")).isFalse(); + assertThat(invocation.executes(":integrationCheck", "optional-platforms")).isTrue(); + }); + } + + @Test + @DisplayName("접힌 블록은 줄을 공백으로 잇고, 빈 줄 뒤는 별개의 셸 명령이 된다") + void foldedBlockJoinsLinesAndBreaksOnABlankLine() { + // given + String workflow = + """ + - name: Lanes + run: >- + ./gradlew + :adapter:inbound:web:performanceTest + :adapter:inbound:web:webJettyPerformanceTest + + ./gradlew --version + - name: Next + run: echo done + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).hasSize(2); + assertThat(invocations.get(0).tasks()) + .containsExactly( + ":adapter:inbound:web:performanceTest", ":adapter:inbound:web:webJettyPerformanceTest"); + assertThat(invocations.get(1).tasks()).isEmpty(); + } + + @Test + @DisplayName("루트 태스크는 콜론을 붙여도 빼도 같은 태스크로 읽는다") + void rootTaskWithOrWithoutLeadingColonIsTheSameTask() { + // given + String workflow = + """ + - run: ./gradlew integrationCheck example-app:check --tests '*Contract*' + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).singleElement().satisfies( + invocation -> { + assertThat(invocation.executes(":integrationCheck", ".")).isTrue(); + assertThat(invocation.executes(":example-app:check", ".")).isTrue(); + assertThat(invocation.tasks()).doesNotContain("*Contract*"); + }); + } + + @Test + @DisplayName("접힌 블록에서 빈 줄 뒤 옵션으로 시작하는 줄은 따로 떨어진 셸 명령이므로 문제로 보고한다") + void optionAfterABlankLineInAFoldedBlockIsReported() { + // given + String workflow = + """ + jobs: + gate: + steps: + - name: Lanes + run: >- + ./gradlew + :adapter:inbound:web:systemTest + + --stacktrace + """; + + // when + List problems = WorkflowGradleInvocations.foldedCommandBreaks(workflow); + + // then + assertThat(problems) + .singleElement() + .asString() + .contains("line 9") + .contains("--stacktrace"); + } + + @Test + @DisplayName("접힌 블록의 빈 줄 뒤가 새 명령이면 의도된 줄바꿈이라 문제로 보지 않는다") + void newCommandAfterABlankLineInAFoldedBlockIsNotReported() { + // given + String workflow = + """ + - run: >- + ./gradlew :ci + --stacktrace + + ./gradlew --version + - run: | + ./gradlew :ci + + --not-folded-so-not-ours + """; + + // when + List problems = WorkflowGradleInvocations.foldedCommandBreaks(workflow); + + // then + assertThat(problems).isEmpty(); + } + + @Test + @DisplayName("-x와 --exclude-task로 뺀 태스크는 경로나 이름이 맞는 태스크만 제외로 읽는다") + void excludedTasksAreReadFromBothSpellings() { + // given + String workflow = + """ + - run: ./gradlew :integrationCheck -x :leaf:databaseLane --exclude-task=test + """; + + // when + Invocation invocation = WorkflowGradleInvocations.read(workflow).get(0); + + // then + assertThat(invocation.excludedTasks()).containsExactly(":leaf:databaseLane", "test"); + assertThat( + TaskSelectors.excludedPaths( + invocation.excludedTasks(), + Map.of( + ":", Set.of("integrationCheck"), + ":leaf", Set.of("databaseLane", "cacheLane", "test"), + ":other", Set.of("test")))) + .containsExactlyInAnyOrder(":leaf:databaseLane", ":leaf:test", ":other:test"); + assertThat(invocation.executes(":integrationCheck", ".")).isTrue(); + } + + @Test + @DisplayName("-x에 태스크를 붙여 쓴 토큰은 Gradle처럼 그 태스크를 뺀 것으로 읽는다") + void anExcludedTaskAttachedToDashXIsReadAsAnExclusion() { + // given + String workflow = + """ + - run: ./gradlew performanceCheck -xgrpcPerformanceTest --exclude-task=:leaf:test + """; + + // when + Invocation invocation = WorkflowGradleInvocations.read(workflow).get(0); + + // then + assertThat(invocation.excludedTasks()).containsExactly("grpcPerformanceTest", ":leaf:test"); + } + + @Test + @DisplayName("-p에 디렉터리를 붙여 쓴 명령은 Gradle처럼 그 디렉터리의 빌드를 실행한다") + void aProjectDirectoryAttachedToDashPIsTheBuildTheCommandStarts() { + // given + String workflow = + """ + - run: ./gradlew -poptional-platforms integrationCheck --stacktrace + """; + + // when + Invocation invocation = WorkflowGradleInvocations.read(workflow).get(0); + + // then + assertThat(invocation.projectDir()).isEqualTo("optional-platforms"); + assertThat(invocation.executes(":integrationCheck", ".")).isFalse(); + assertThat(invocation.executes(":integrationCheck", "optional-platforms")).isTrue(); + } + + @Test + @DisplayName("job의 continue-on-error와 단계의 if 조건은 명령을 실행으로 세지 않는 이유로 남는다") + void jobAndStepGatingIsKeptAsTheReasonACommandDoesNotCount() { + // given + String workflow = + """ + jobs: + advisory: + continue-on-error: true + steps: + - run: ./gradlew :ci + gated: + steps: + - name: Manual only + if: github.event_name == 'workflow_dispatch' + run: ./gradlew :ci + plain: + steps: + - if: ${{ always() }} + run: ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).extracting(Invocation::uncountedReason) + .satisfiesExactly( + reason -> assertThat(reason).contains("job has continue-on-error: true"), + reason -> assertThat(reason).contains("step runs only if: github.event_name"), + reason -> assertThat(reason).isNull()); + } + + @Test + @DisplayName("workflow_dispatch로만 시작하는 workflow의 명령은 아무 실행도 막지 못하므로 세지 않는다") + void aWorkflowThatOnlyRunsOnDispatchGatesNothing() { + // given + String workflow = + """ + on: + workflow_dispatch: + inputs: + lane: + type: string + jobs: + manual: + steps: + - working-directory: src + run: ./gradlew :integrationCheck + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .singleElement() + .extracting(Invocation::uncountedReason) + .asString() + .contains("workflow_dispatch"); + } + + @Test + @DisplayName("workflow_dispatch 말고 다른 트리거도 있으면 명령을 실행으로 센다") + void aWorkflowWithAnotherTriggerBesidesDispatchCounts() { + // given + String workflow = + """ + on: [push, workflow_dispatch] + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :integrationCheck + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).singleElement().extracting(Invocation::uncountedReason).isNull(); + } + + @Test + @DisplayName("working-directory는 -p처럼 읽어서, 하위 디렉터리에서 부른 gradlew는 그 디렉터리의 빌드를 실행한다") + void workingDirectoryIsReadLikeDashP() { + // given + String workflow = + """ + jobs: + optional: + steps: + - working-directory: src/optional-platforms + run: ../gradlew ci --stacktrace + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).singleElement().satisfies( + invocation -> { + assertThat(invocation.executes(":ci", "src/optional-platforms")).isTrue(); + assertThat(invocation.executes(":ci", "src")).isFalse(); + }); + } + + @Test + @DisplayName("job의 defaults.run.working-directory도 그 job 단계의 시작 디렉터리로 읽는다") + void jobDefaultsWorkingDirectoryIsTheStepsStartDirectory() { + // given + String workflow = + """ + jobs: + release: + defaults: + run: + working-directory: src + steps: + - run: ./gradlew -p optional-platforms releaseCheck + - run: ./gradlew :releaseCheck + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).hasSize(2); + assertThat(invocations.get(0).executes(":releaseCheck", "src/optional-platforms")).isTrue(); + assertThat(invocations.get(1).executes(":releaseCheck", "src")).isTrue(); + } + + @Test + @DisplayName("같은 셸에서 먼저 실행한 cd 뒤의 gradlew는 그 디렉터리의 빌드를 실행한다") + void gradlewAfterACdInTheSameShellStartsTheBuildInThatDirectory() { + // given + String workflow = + """ + jobs: + main: + steps: + - run: cd src && ./gradlew :ci + - run: cd src; ./gradlew :ci + - run: | + cd src + ./gradlew :ci + - run: >- + cd src + + ./gradlew :ci + --stacktrace + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(4) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).isNull(); + assertThat(invocation.executes(":ci", "src")).isTrue(); + assertThat(invocation.executes(":ci", ".")).isFalse(); + }); + } + + @Test + @DisplayName("cd는 working-directory에서 시작해 상대 경로로 쌓이고, -p는 그 뒤에 붙는다") + void cdAccumulatesFromTheWorkingDirectoryAndDashPAppliesAfterIt() { + // given + String workflow = + """ + jobs: + main: + steps: + - working-directory: src + run: cd optional-platforms && ../gradlew ci + - run: | + cd src + cd .. + ./gradlew :ci + - run: cd src && ./gradlew -p optional-platforms ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .extracting(Invocation::buildDirectory) + .containsExactly("src/optional-platforms", ".", "src/optional-platforms"); + } + + @Test + @DisplayName("확실히 따라갈 수 없는 cd 뒤의 gradlew는 어느 빌드의 실행으로도 세지 않고 그 이유를 남긴다") + void gradlewAfterACdThatCannotBeFollowedCountsForNoBuildAndSaysWhy() { + // given + String workflow = + """ + jobs: + main: + steps: + - run: cd "$GITHUB_WORKSPACE/src" && ./gradlew :ci + - run: | + cd src + cd - + ./gradlew :ci + - run: pushd src && ./gradlew :ci + - run: | + ( cd src && ./gradlew :ci ) + ./gradlew :ci + - run: | + cd src || exit 1 + ./gradlew :ci + - run: | + if [ -d src ]; then cd src; fi + ./gradlew :ci + - run: | + cd src && echo ready + ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(8) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).containsPattern("\\b(cd|pushd)\\b"); + assertThat(invocation.executes(":ci", "src")).isFalse(); + assertThat(invocation.executes(":ci", ".")).isFalse(); + }); + } + + @Test + @DisplayName("실패가 처리되거나 상태가 버려지는 gradlew는 실행으로 세지 않고 그 이유를 남긴다") + void gradlewWhoseFailureIsHandledOrDroppedDoesNotCountAndSaysWhy() { + // given + String workflow = + """ + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci || true + - working-directory: src + run: ./gradlew :ci | tee ci.log + - working-directory: src + run: | + ! ./gradlew :ci + - working-directory: src + run: ./gradlew :ci & + - working-directory: src + run: echo ./gradlew :ci + - working-directory: src + run: echo "$(./gradlew :ci)" + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(6) + .allSatisfy( + invocation -> { + assertThat(invocation.requests(":ci")).isTrue(); + assertThat(invocation.uncountedReason()).isNotBlank(); + assertThat(invocation.executes(":ci", "src")).isFalse(); + }); + } + + @Test + @DisplayName("조건·반복·함수 본문 안에서만 도는 gradlew는 매번 실행된다고 볼 수 없으므로 세지 않는다") + void gradlewThatRunsOnlyUnderAConditionOrInALoopOrFunctionDoesNotCount() { + // given + String workflow = + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: | + if ./gradlew :ci; then echo passed; fi + - run: | + while ./gradlew :ci; do break; done + - run: | + if [ -n "$RUN" ]; then + ./gradlew :ci + fi + - run: | + for attempt in 1; do ./gradlew :ci; done + - run: | + case "$MODE" in + full) ./gradlew :ci ;; + esac + - run: | + gate() { + ./gradlew :ci + } + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(6) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).isNotBlank(); + assertThat(invocation.executes(":ci", "src")).isFalse(); + }); + } + + @Test + @DisplayName("앞 명령이 실패하면 건너뛰거나 실패를 삼키는 && 목록의 gradlew는 스크립트의 마지막 명령일 때만 센다") + void gradlewInAnAndListCountsOnlyWhenTheListIsTheScriptsLastCommand() { + // given + String workflow = + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: | + test -d build && ./gradlew :ci + echo done + - run: | + ./gradlew :ci && echo passed + echo done + - run: test -d build && ./gradlew :ci + - run: ./gradlew :ci && echo passed + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .extracting(invocation -> invocation.executes(":ci", "src")) + .containsExactly(false, false, true, true); + assertThat(invocations.subList(0, 2)) + .allSatisfy(invocation -> assertThat(invocation.uncountedReason()).contains("&&")); + } + + @Test + @DisplayName("exit-on-error를 끈 뒤나 최상위 exit 뒤의 gradlew는 단계를 실패시키지 못하므로 세지 않는다") + void gradlewAfterExitOnErrorIsTurnedOffOrAfterExitDoesNotCount() { + // given + String workflow = + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: | + set +e + ./gradlew :ci + echo done + - run: | + set +o errexit + ./gradlew :ci + echo done + - run: | + exit 0 + ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(3) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).isNotBlank(); + assertThat(invocation.executes(":ci", "src")).isFalse(); + }); + } + + @Test + @DisplayName("pipefail이 확실히 켜진 셸에서는 파이프 앞의 gradlew 실패도 단계를 실패시키므로 센다") + void gradlewPipedUnderPipefailCounts() { + // given + String workflow = + """ + jobs: + main: + steps: + - working-directory: src + shell: bash + run: ./gradlew :ci | tee ci.log + - working-directory: src + run: | + set -euo pipefail + ./gradlew :ci | tee ci.log + - working-directory: src + run: | + set -o pipefail + ./gradlew :ci 2>&1 | tee ci.log + defaulted: + defaults: + run: + shell: bash + working-directory: src + steps: + - run: ./gradlew :ci |& tee ci.log + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(4) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).isNull(); + assertThat(invocation.executes(":ci", "src")).isTrue(); + }); + } + + @Test + @DisplayName("bash와 sh 밖의 셸로 도는 단계의 gradlew는 실패 처리를 읽지 않으므로 세지 않는다") + void gradlewInAStepWhoseShellIsNotBashOrShDoesNotCount() { + // given + String workflow = + """ + jobs: + main: + steps: + - working-directory: src + shell: pwsh + run: ./gradlew :ci + - working-directory: src + shell: bash {0} + run: ./gradlew :ci + - working-directory: src + shell: sh + run: ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).hasSize(3); + assertThat(invocations.get(0).uncountedReason()).contains("shell: pwsh"); + assertThat(invocations.get(1).uncountedReason()).contains("shell: bash {0}"); + assertThat(invocations.get(2).executes(":ci", "src")).isTrue(); + } + + @Test + @DisplayName("셸이 그 자리에서 실행하지 않는 heredoc·여러 줄 문자열·이스케이프한 세미콜론 뒤의 cd는 따라가지 않는다") + void aCdTheShellDoesNotRunThereIsNotFollowed() { + // given + String workflow = + """ + jobs: + main: + steps: + - run: | + cat > enter.sh <<'EOF' + cd src + EOF + ./gradlew :ci + - run: | + echo "first + cd src + " + ./gradlew :ci + - run: echo a \\; cd src && ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(3) + .allSatisfy( + invocation -> { + assertThat(invocation.buildDirectory()).isEqualTo("."); + assertThat(invocation.executes(":ci", "src")).isFalse(); + }); + } + + @Test + @DisplayName("함수 본문의 cd는 부르는 곳을 읽지 않으므로 따라가지 않고, 그 뒤 명령은 이유를 대며 세지 않는다") + void aCdInAFunctionBodyIsNotFollowedAndTheCommandsAfterItDoNotCount() { + // given + String workflow = + """ + jobs: + main: + steps: + - run: | + enter() { + cd src + } + ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .singleElement() + .satisfies( + invocation -> { + assertThat(invocation.uncountedReason()).contains("cd src"); + assertThat(invocation.executes(":ci", "src")).isFalse(); + assertThat(invocation.executes(":ci", ".")).isFalse(); + }); + } + + @Test + @DisplayName("산술 확장·산술 명령·산술 for가 있는 스크립트도 셸 문법으로 읽어 마지막 gradlew를 센다") + void aScriptWithArithmeticIsReadAsShellAndItsLastGradlewCounts() { + // given + String workflow = + """ + jobs: + main: + steps: + - working-directory: src + run: | + echo $(( 1 + 2 )) "$(( 3 * 4 ))" + (( attempts = 1 )) + for ((i = 0; i < attempts; i++)); do echo "$i"; done + ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .singleElement() + .satisfies( + invocation -> { + assertThat(invocation.uncountedReason()).isNull(); + assertThat(invocation.executes(":ci", "src")).isTrue(); + }); + } + + @Test + @DisplayName("짧은 플래그 묶음은 Gradle처럼 첫 글자만 값을 붙여 받는 것으로 읽는다") + void bundledShortOptionsAreReadTheWayGradleReadsThem() { + // given + String workflow = + """ + - run: ./gradlew -qm :ci + - run: ./gradlew -sm :ci + - run: ./gradlew -dry-run :ci + - run: ./gradlew --m :ci + - run: ./gradlew :ci -x=:leaf:test + - run: ./gradlew -exclude-task :leaf:test :ci + - run: ./gradlew --x :leaf:test :ci + - run: ./gradlew -p=optional-platforms :ci + - run: ./gradlew -- :ci -x + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).extracting(Invocation::dryRun) + .containsExactly(true, true, true, true, false, false, false, false, false); + assertThat(invocations.subList(4, 7)) + .allSatisfy( + invocation -> assertThat(invocation.excludedTasks()).containsExactly(":leaf:test")); + assertThat(invocations.get(7).projectDir()).isEqualTo("optional-platforms"); + assertThat(invocations.get(8).tasks()).containsExactly(":ci", "-x"); + assertThat(invocations.get(8).excludedTasks()).isEmpty(); + } + + @Test + @DisplayName("Gradle이 거부하는 짧은 플래그 묶음의 명령은 단계를 실행하지 못하므로 그 이유와 함께 세지 않는다") + void aCommandLineGradleRejectsDoesNotCountAndSaysWhy() { + // given + String workflow = + """ + - run: ./gradlew -mx :leaf:test :ci + - run: ./gradlew -qpoptional-platforms :ci + - run: ./gradlew -m=yes :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(3) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).contains("Gradle rejects"); + assertThat(invocation.executes(":ci", ".")).isFalse(); + }); + } + + @Test + @DisplayName("Gradle이 버전·도움말·데몬 상태만 보이고 작업 없이 끝나는 옵션을 붙인 명령은 실행으로 세지 않는다") + void aCommandWithAnOptionAfterWhichGradleRunsNoTaskDoesNotCount() { + // given + String workflow = + """ + - run: ./gradlew :ci -v + - run: ./gradlew :ci --version + - run: ./gradlew -v :ci + - run: ./gradlew :ci --help + - run: ./gradlew :ci -h + - run: ./gradlew :ci -? + - run: ./gradlew -qv :ci + - run: ./gradlew :ci --status + - run: ./gradlew :ci --stop + - run: ./gradlew :ci --foreground + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(10) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).contains("runs no task"); + assertThat(invocation.executes(":ci", ".")).isFalse(); + }); + } + + @Test + @DisplayName("버전을 찍고 계속하는 -V는 작업을 실행하므로 센다") + void showVersionThatContinuesStillRunsTheTasks() { + // given + String workflow = + """ + - run: ./gradlew -V :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).singleElement().satisfies( + invocation -> assertThat(invocation.executes(":ci", ".")).isTrue()); + } + + @Test + @DisplayName("조건부 exit 0·인자 없는 exit·값을 모르는 exit·exec·set -n 뒤의 gradlew는 돌지 않을 수 있으므로 세지 않는다") + void gradlewAfterACommandThatMayEndTheScriptFirstDoesNotCount() { + // given + String workflow = + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: | + if git diff --quiet origin/main -- .; then echo "no source change"; exit 0; fi + ./gradlew :ci + - run: | + [ "$SKIP_CI" = true ] && exit 0 + ./gradlew :ci + - run: | + if [ -f skip ]; then echo skipping; exit; fi + ./gradlew :ci + - run: | + if [ -f skip ]; then exit "$code"; fi + ./gradlew :ci + - run: | + skip() { echo skip; exit 0; } + skip + ./gradlew :ci + - run: | + exec ./gradlew :help + ./gradlew :ci + - run: | + set -n + ./gradlew :ci + - run: | + set -o noexec + ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations.stream().filter(invocation -> invocation.requests(":ci")).toList()) + .hasSize(8) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).isNotBlank(); + assertThat(invocation.executes(":ci", "src")).isFalse(); + }); + } + + @Test + @DisplayName("EXIT·ERR trap이 exit하면 gradlew가 실패해도 단계가 성공할 수 있으므로 그 뒤 gradlew는 세지 않는다") + void gradlewAfterATrapThatExitsOnExitOrErrDoesNotCount() { + // given + String workflow = + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: | + trap 'exit 0' EXIT + ./gradlew :ci + - run: | + trap 'echo failed; exit 0' ERR + ./gradlew :ci + - run: | + trap 'echo failed; exit' err + ./gradlew :ci + - run: | + trap cleanup EXIT + cleanup() { rm -f build.lock; exit 0; } + ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(4) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).contains("trap"); + assertThat(invocation.executes(":ci", "src")).isFalse(); + }); + } + + @Test + @DisplayName("단계를 실패시키는 exit, 부르지 않은 함수·서브셸·명령 치환 안의 exit, 상태를 지키는 trap, 명령 없는 exec 뒤의 gradlew는 센다") + void gradlewAfterAnExitThatFailsTheStepOrThatDoesNotEndTheScriptStillCounts() { + // given + String workflow = + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: | + if [ ! -s snapshot.txt ]; then echo "::error::missing"; exit 1; fi + ./gradlew :ci + - run: | + [ -n "$RUN" ] || exit + ./gradlew :ci + - run: | + skip() { exit 0; } + ./gradlew :ci + - run: | + ( exit 0 ) + echo "$(exit 0)" + ./gradlew :ci + - run: | + trap 'rm -f build.lock' EXIT + ./gradlew :ci + - run: | + trap 'rm -f build.lock; exit' EXIT + ./gradlew :ci + - run: | + exec 2>&1 + ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .hasSize(7) + .allSatisfy( + invocation -> { + assertThat(invocation.uncountedReason()).isNull(); + assertThat(invocation.executes(":ci", "src")).isTrue(); + }); + } + + @Test + @DisplayName("셸을 정하지 않은 단계는 Windows일 수 있는 runner면 기본 셸이 pwsh일 수 있으므로 세지 않는다") + void aDefaultShellStepOnARunnerThatMayBeWindowsDoesNotCount() { + // given + String workflow = + """ + defaults: + run: + working-directory: src + jobs: + windows: + runs-on: windows-latest + steps: + - run: ./gradlew :ci + matrix: + runs-on: ${{ matrix.os }} + steps: + - run: ./gradlew :ci + unknown-self-hosted: + runs-on: [self-hosted, gpu] + steps: + - run: ./gradlew :ci + linux: + runs-on: ubuntu-latest + steps: + - run: ./gradlew :ci + mac: + runs-on: macos-14 + steps: + - run: ./gradlew :ci + linux-self-hosted: + runs-on: + - self-hosted + - Linux + steps: + - run: ./gradlew :ci + windows-bash: + runs-on: windows-latest + defaults: + run: + shell: bash + steps: + - run: ./gradlew :ci + linux-container: + runs-on: ${{ matrix.runner }} + container: eclipse-temurin:21 + steps: + - run: ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations) + .extracting(invocation -> invocation.executes(":ci", "src")) + .containsExactly(false, false, false, true, true, true, true, true); + assertThat(invocations.subList(0, 3)) + .allSatisfy(invocation -> assertThat(invocation.uncountedReason()).contains("pwsh")); + } + + @Test + @DisplayName("실패하면 단계도 실패하지만 판독기가 읽지 않는 모양은 실패를 막지 못한다고 하지 않고, 읽지 않는다며 혼자 한 줄로 두라고 말한다") + void aShapeThatWouldFailTheStepButIsNotReadSaysSoInsteadOfClaimingItCannotFail() { + // given + String workflow = + """ + defaults: + run: + working-directory: src + jobs: + main: + steps: + - run: | + ./gradlew :ci || exit 1 + echo done + - run: | + ./gradlew :ci || { echo "::error::ci failed"; exit 1; } + echo done + - run: | + { ./gradlew :ci; } + echo done + - run: | + ( ./gradlew :ci ) + echo done + - run: | + ./gradlew :ci || true + echo done + - run: | + if [ -n "$RUN" ]; then ./gradlew :ci; fi + echo done + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).extracting(Invocation::uncountedReason) + .satisfiesExactly( + reason -> assertThat(reason).contains("does not read").contains("line of its own"), + reason -> assertThat(reason).contains("does not read").contains("line of its own"), + reason -> assertThat(reason).contains("does not read").contains("line of its own"), + reason -> assertThat(reason).contains("does not read").contains("line of its own"), + reason -> assertThat(reason).contains("|| true").doesNotContain("does not read"), + reason -> assertThat(reason).contains("may not run").doesNotContain("does not read")); + } + + @Test + @DisplayName("요청이 있어야 시작하는 trigger만 있는 workflow의 명령은 세지 않는다") + void aWorkflowThatStartsOnlyOnRequestsGatesNothing() { + // given + List workflows = + List.of( + """ + on: [workflow_dispatch, repository_dispatch] + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci + """, + """ + on: + issue_comment: + types: [created] + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci + """, + """ + on: + pull_request: + types: [labeled] + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci + """); + + // when + List invocations = + workflows.stream().flatMap(workflow -> WorkflowGradleInvocations.read(workflow).stream()) + .toList(); + + // then + assertThat(invocations).extracting(Invocation::uncountedReason) + .satisfiesExactly( + reason -> assertThat(reason).contains("repository_dispatch"), + reason -> assertThat(reason).contains("issue_comment"), + reason -> assertThat(reason).contains("labeled")); + } + + @Test + @DisplayName("push·pull_request·merge_group·schedule 중 하나로도 시작하는 workflow의 명령은 센다") + void aWorkflowThatAlsoStartsOnTheChangeFlowCounts() { + // given + List workflows = + List.of( + """ + on: {pull_request: {branches: [main]}, issue_comment: {types: [created]}} + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci + """, + """ + on: + merge_group: + workflow_dispatch: + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci + """, + """ + on: + schedule: + - cron: '0 3 * * *' + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci + """, + """ + on: + pull_request: + types: [opened, synchronize, labeled] + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci + """); + + // when + List invocations = + workflows.stream().flatMap(workflow -> WorkflowGradleInvocations.read(workflow).stream()) + .toList(); + + // then + assertThat(invocations) + .hasSize(4) + .allSatisfy(invocation -> assertThat(invocation.executes(":ci", "src")).isTrue()); + } + + @Test + @DisplayName("paths·paths-ignore 필터가 붙은 change trigger로만 시작하는 workflow의 명령은 세지 않는다") + void aWorkflowThatStartsOnChangesOnlyThroughAPathFilterGatesNothing() { + // given + List workflows = + List.of( + """ + on: + pull_request: + paths: ["docs/**"] + push: + branches: [main] + paths: + - "docs/**" + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci + """, + """ + on: {push: {paths-ignore: ["docs/**"]}, workflow_dispatch: {}} + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci + """, + """ + on: + pull_request: {types: [opened, synchronize], paths: ["src/**"]} + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci + """); + + // when + List invocations = + workflows.stream().flatMap(workflow -> WorkflowGradleInvocations.read(workflow).stream()) + .toList(); + + // then + assertThat(invocations) + .hasSize(3) + .allSatisfy(invocation -> assertThat(invocation.executes(":ci", "src")).isFalse()); + assertThat(invocations).extracting(Invocation::uncountedReason) + .satisfiesExactly( + reason -> assertThat(reason).contains("pull_request (paths)", "push (paths)"), + reason -> assertThat(reason).contains("push (paths-ignore)"), + reason -> + assertThat(reason).contains("pull_request (types: opened, synchronize; paths)")); + } + + @Test + @DisplayName("paths 필터가 붙은 trigger 옆에 필터 없는 change trigger가 있으면 그 workflow의 명령은 센다") + void aWorkflowWithAnUnfilteredChangeTriggerBesidesAPathFilterCounts() { + // given + String workflow = + """ + on: + pull_request: + paths: ["docs/**"] + schedule: + - cron: '0 3 * * *' + jobs: + main: + steps: + - working-directory: src + run: ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).singleElement().satisfies( + 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() { + // given + String reusable = + """ + on: + workflow_call: + inputs: + lane: + type: string + jobs: + stage: + runs-on: ubuntu-latest + steps: + - working-directory: src + run: ./gradlew :ci + """; + String pushCaller = + """ + on: push + jobs: + call: + uses: ./.github/workflows/reusable.yml + """; + String conditionalCaller = + """ + on: push + jobs: + call: + if: github.ref == 'refs/heads/release' + uses: ./.github/workflows/reusable.yml + """; + String manualCaller = + """ + on: workflow_dispatch + jobs: + call: + uses: ./.github/workflows/reusable.yml + """; + + // when + List>> readings = + List.of( + WorkflowGradleInvocations.readAll(Map.of("reusable.yml", reusable)), + WorkflowGradleInvocations.readAll( + Map.of("reusable.yml", reusable, "push.yml", pushCaller)), + WorkflowGradleInvocations.readAll( + Map.of("reusable.yml", reusable, "conditional.yml", conditionalCaller)), + WorkflowGradleInvocations.readAll( + Map.of("reusable.yml", reusable, "manual.yml", manualCaller))); + + // then + assertThat(readings) + .extracting(reading -> reading.get("reusable.yml").get(0).executes(":ci", "src")) + .containsExactly(false, true, false, false); + assertThat(readings.get(0).get("reusable.yml").get(0).uncountedReason()) + .contains("workflow_call"); + assertThat(readings.get(2).get("reusable.yml").get(0).uncountedReason()) + .contains("conditional.yml"); + } + + @Test + @DisplayName("조건부 job이나 continue-on-error job을 needs로 기다리는 job의 명령은 세지 않고, always()로 끊으면 센다") + void aJobThatNeedsAJobThatMayBeSkippedDoesNotCount() { + // given + String workflow = + """ + defaults: + run: + working-directory: src + jobs: + changes: + runs-on: ubuntu-latest + if: github.event_name == 'push' + steps: + - run: echo changed + advisory: + runs-on: ubuntu-latest + continue-on-error: true + steps: + - run: echo maybe + plain: + runs-on: ubuntu-latest + steps: + - run: echo plain + after-changes: + runs-on: ubuntu-latest + needs: changes + steps: + - run: ./gradlew :ci + chained: + runs-on: ubuntu-latest + needs: [plain, after-changes] + steps: + - run: ./gradlew :ci + after-advisory: + runs-on: ubuntu-latest + needs: + - advisory + steps: + - run: ./gradlew :ci + always-after-changes: + runs-on: ubuntu-latest + needs: changes + if: ${{ !cancelled() }} + steps: + - run: ./gradlew :ci + after-plain: + runs-on: ubuntu-latest + needs: plain + steps: + - run: ./gradlew :ci + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + List gradle = + invocations.stream().filter(invocation -> invocation.requests(":ci")).toList(); + assertThat(gradle) + .extracting(invocation -> invocation.executes(":ci", "src")) + .containsExactly(false, false, false, true, true); + assertThat(gradle.subList(0, 3)) + .allSatisfy(invocation -> assertThat(invocation.uncountedReason()).contains("needs")); + } + + @Test + @DisplayName("uses 단계의 with 입력에 적힌 run은 셸 명령이 아니므로 읽지 않는다") + void aRunInputOfAnActionIsNotAShellCommand() { + // given + String workflow = + """ + jobs: + main: + steps: + - uses: some/action@v1 + with: + run: ./gradlew :integrationCheck + """; + + // when + List invocations = WorkflowGradleInvocations.read(workflow); + + // then + assertThat(invocations).isEmpty(); + } +} diff --git a/build.gradle b/build.gradle new file mode 100644 index 0000000..5bba9af --- /dev/null +++ b/build.gradle @@ -0,0 +1,315 @@ +import dev.caskeleton.buildlogic.java.JavaConventionsPlugin +import dev.caskeleton.buildlogic.publishing.SigningKeys + +plugins { + id 'ca.architecture' + // Every strict lane belongs to a stage a workflow executes (.gitea/workflows). Without it a lane + // that fails closed can still run nowhere (template review 2026-11-03 RR-06-03). + id 'ca.strict-lane-stages' + // The release SBOM is published as an artifact of its own, `messaging-library`, next to the modules. + id 'maven-publish' + id 'signing' + // JMH benchmarks in messaging-kafka and messaging-testkit (`./gradlew :messaging::jmh`); + // never part of a gate. Declared here so the modules apply it by id at the catalog's version. + alias(libs.plugins.jmh) apply false +} + +// The modules: every leaf the registry includes (settings.gradle). The family project `:messaging` is +// a folder, not a module. +def leaves = subprojects.findAll { it.childProjects.isEmpty() } +def leafPaths = leaves.collect { it.path } + +// The root's coordinate is the release's: the SBOM artifact carries the version the modules carry. +group = providers.gradleProperty('libraryGroup').get() +def revision = JavaConventionsPlugin.sourceRevision(providers) +version = JavaConventionsPlugin.releaseVersion(providers) + + (revision == JavaConventionsPlugin.UNKNOWN_REVISION ? '-SNAPSHOT' : '') +// Captured here: inside a task's configuration `group` and `version` are the task's own properties. +def libraryCoordinates = [project.group.toString(), project.version.toString()] + +tasks.register('resolveAndLockAll') { + group = 'build setup' + description = 'Regenerates dependency locks for every module (requires --write-locks).' + dependsOn leafPaths.collect { "${it}:resolveAndLockAll" } +} + +tasks.register('verifyDependencyLocks') { + group = 'verification' + description = 'Fails when a module resolves something its strict lockfile does not list.' + dependsOn leafPaths.collect { "${it}:verifyDependencyLocks" } +} + +tasks.register('checkAll') { + group = 'verification' + description = 'Runs every module check.' + dependsOn leafPaths.collect { "${it}:check" } +} + +tasks.register('qualityCheck') { + group = 'verification' + description = 'Runs production-bytecode static analysis for every module.' + dependsOn leafPaths.collect { "${it}:qualityCheck" } +} + +// SpotBugs + FindSecBugs over the test source sets (config/spotbugs/exclude-test.xml). The modules are +// small enough for the pull-request stage to afford it, so it joins `ci`. +tasks.register('testQualityCheck') { + group = 'verification' + description = 'Runs test-code static analysis for every module.' + dependsOn leafPaths.collect { "${it}:testQualityCheck" } +} + +// build-logic is a copy of the template's convention plugins (build-logic/UPSTREAM.md); its own +// TestKit and unit tests keep the copy honest when it is changed here. +tasks.register('buildLogicTest') { + group = 'verification' + description = 'Runs the included build-logic build\'s tests.' + dependsOn gradle.includedBuild('build-logic').task(':test') +} + +// The pull-request stage (pr.yml). messaging-testkit's `check` includes its repository-contract lane +// (the public-surface and settings-owner contracts read every module's sources and build script), so +// a dependency-scope or ownership drift stops a merge. +tasks.register('ci') { + group = 'verification' + description = 'The pull-request stage: module checks, architecture, static analysis, locks and build-logic tests.' + dependsOn tasks.named('checkAll') + dependsOn tasks.named('qualityCheck') + dependsOn tasks.named('testQualityCheck') + dependsOn tasks.named('verifyDependencyLocks') + // architectureCheck, not only the direction gate: it also runs verifyNoIgnoredSourcePackages. + dependsOn tasks.named('architectureCheck') + dependsOn tasks.named('buildLogicTest') +} + +// Every module's integration lanes, all Testcontainers: messaging-kafka's broker certification lane +// (Kafka behind Toxiproxy), messaging-reliability-jdbc-postgresql's outbox, inbox and admin-journal +// contracts against PostgreSQL, and the starter's assembled round trip (Kafka and PostgreSQL). Needs a +// container runtime. +tasks.register('integrationCheck') { + group = 'verification' + description = 'Runs every module integration test lane. Needs a container runtime.' + dependsOn leafPaths.collect { "${it}:integrationTestLaneCheck" } +} + +// The certification gate: the scenarios the committed manifest claims are the ones this run of the +// certification lane proved against a live broker (messaging-kafka/build.gradle). Editing the +// manifest by hand fails it; running the lane writes the produced copy to compare. +def certificationGate = ':messaging:messaging-kafka:verifyMessagingCertificationEvidence' + +// The main-branch stage (main.yml): the pull-request stage again on the merged commit, plus the lanes +// that start containers and the certification gate. The template ran the gate in a workflow of its own +// (messaging-certification.yml, weekly and on messaging paths); here every main push and the nightly +// run run it. No module has a performance lane: the JMH benchmarks are not a gate. +tasks.register('mainCheck') { + group = 'verification' + description = 'The main-branch stage: ci, integrationCheck and the broker certification gate.' + dependsOn tasks.named('ci') + dependsOn tasks.named('integrationCheck') + dependsOn certificationGate +} + +// ---------------------------------------------------------------- release (release.yml) + +def sbomFile = layout.buildDirectory.file("release/messaging-library-${version}-cyclonedx.json") + +tasks.register('verifyReleaseVersion') { + group = 'verification' + description = 'Fails unless this build names a release version and the commit it was built from.' + def releaseVersion = libraryCoordinates[1] + doLast { + if (releaseVersion.endsWith('-SNAPSHOT')) { + throw new GradleException("No commit id (-PgitRevision, GIT_SHA or GITHUB_SHA): ${releaseVersion} is not a release.") + } + if (releaseVersion == '0.0.1') { + throw new GradleException('No release version: run with RELEASE_TAG=vX.Y.Z (release.yml) or -PreleaseVersion.') + } + } +} + +tasks.register('releaseSbom', Exec) { + group = 'release' + description = 'Writes the CycloneDX SBOM of the published modules from their lockfiles (Trivy).' + outputs.file(sbomFile) + outputs.upToDateWhen { false } + commandLine 'bash', file('scripts/release/sbom.sh'), sbomFile.get().asFile +} + +tasks.register('dependencyVulnerabilityScan', Exec) { + group = 'verification' + description = 'Fails on a HIGH or CRITICAL dependency vulnerability or any CISA KEV match (Trivy).' + mustRunAfter tasks.named('releaseSbom') + def reports = layout.buildDirectory.dir('release/vulnerability') + commandLine 'bash', file('scripts/release/vulnerability-scan.sh'), reports.get().asFile +} + +// The tag-only stage: the hermetic lanes of every module, the integration lanes, the broker +// certification gate (a release claims what the support matrix says, so the evidence is re-proved on +// the tagged commit), the version check, the SBOM and the dependency gate. +tasks.register('releaseCheck') { + group = 'verification' + description = 'The release stage before publishing: certification gate, integration lanes, version, SBOM, dependency gate.' + dependsOn tasks.named('verifyReleaseVersion') + dependsOn leafPaths.collect { "${it}:testLaneCheck" } + dependsOn tasks.named('integrationCheck') + dependsOn certificationGate + dependsOn tasks.named('releaseSbom') + dependsOn tasks.named('dependencyVulnerabilityScan') +} + +publishing { + publications { + sbom(MavenPublication) { + artifactId = 'messaging-library' + artifact(sbomFile) { + classifier = 'cyclonedx' + extension = 'json' + builtBy tasks.named('releaseSbom') + } + pom { + name = 'messaging-library' + description = 'CycloneDX SBOM of the messaging-library modules of this version.' + url = providers.gradleProperty('repositoryUrl') + packaging = 'pom' + } + } + } + repositories { + maven { + name = 'gitea' + url = providers.gradleProperty('packagesUrl') + credentials(HttpHeaderCredentials) { + name = 'Authorization' + value = "token ${providers.environmentVariable('PACKAGE_TOKEN').getOrElse('')}" + } + authentication { + header(HttpHeaderAuthentication) + } + } + maven { + name = 'staging' + url = layout.buildDirectory.dir('staging-repository') + } + } +} + +// The armoured key, or the base64 of the armoured file (the usual way to keep it in a CI secret). +def signingKey = SigningKeys.armoured(providers.environmentVariable('SIGNING_KEY').getOrElse('')) + +// Before anything is signed: the secret's shape, that gpg imports it as the release key and that +// SIGNING_PASSWORD signs with it, printing no part of either. Gradle's signing reports every one of +// these as "Could not read PGP secret key" (v1.0.0 release run 9); this says which. A key other +// than the release key passes with -PsigningKeyFingerprint= (a rehearsal key). +// gpg reads only a passphrase's first line and Gradle the whole value, so the task then signs a few +// bytes with Gradle's own signatory: the verdict is the one the Sign tasks would reach. +tasks.register('verifySigningKey', Exec) { + group = 'verification' + description = 'Checks SIGNING_KEY and SIGNING_PASSWORD without printing them (scripts/release/check-signing-key.sh).' + outputs.upToDateWhen { false } + ignoreExitValue = true + commandLine 'bash', file('scripts/release/check-signing-key.sh'), + providers.gradleProperty('signingKeyFingerprint').getOrElse('') + def signed = !signingKey.isBlank() + doLast { + boolean scriptPassed = executionResult.get().exitValue == 0 + boolean gradlePassed = !signed + String verdict = 'skipped: no SIGNING_KEY' + if (signed) { + try { + signing.signatory.sign(new ByteArrayInputStream('signing check'.bytes), OutputStream.nullOutputStream()) + gradlePassed = true + verdict = 'ok' + } catch (Exception failure) { + // Exception text only: BouncyCastle names what failed (checksum mismatch, a tag), never the key. + def cause = failure.cause ? " (${failure.cause.class.simpleName}: ${failure.cause.message})" : '' + verdict = "failed: ${failure.message}${cause}" + } + } + logger.lifecycle("signing as Gradle's Sign tasks do (in-memory key): ${verdict}") + if (!scriptPassed || !gradlePassed) { + throw new GradleException('verifySigningKey: the signing secrets would not sign; the PROBLEM lines above say why.') + } + } +} +tasks.withType(Sign).configureEach { + mustRunAfter tasks.named('verifySigningKey') +} +if (!signingKey.isBlank()) { + signing { + useInMemoryPgpKeys(signingKey, providers.environmentVariable('SIGNING_PASSWORD').getOrElse('')) + sign publishing.publications.sbom + } +} + +tasks.withType(PublishToMavenRepository).configureEach { + mustRunAfter tasks.named('releaseCheck') + if (name.endsWith('ToGiteaRepository')) { + def signed = !signingKey.isBlank() + def token = providers.environmentVariable('PACKAGE_TOKEN').getOrElse('') + doFirst { + if (!signed) { + throw new GradleException('SIGNING_KEY is not set; refusing to publish unsigned files to Gitea.') + } + if (token.isBlank()) { + throw new GradleException('PACKAGE_TOKEN is not set; Gitea\'s job token cannot publish packages.') + } + } + } +} + +// Everything release.yml does up to the upload, into build/staging-repository: what `release` would +// publish, checked file by file. Needs no secret; with SIGNING_KEY set it also checks every .asc. +tasks.register('releaseRehearsal') { + group = 'release' + description = 'releaseCheck, then publishes every module and the SBOM to build/staging-repository and checks the files.' + dependsOn tasks.named('releaseCheck') + if (!signingKey.isBlank()) { + dependsOn tasks.named('verifySigningKey') + } + dependsOn tasks.named('publishAllPublicationsToStagingRepository') + dependsOn leafPaths.collect { "${it}:publishAllPublicationsToStagingRepository" } + def staging = layout.buildDirectory.dir('staging-repository') + def artifacts = leaves.collect { it.name } + def coordinates = libraryCoordinates + def signed = !signingKey.isBlank() + def checker = file('scripts/release/check-staging.py') + doLast { + def command = ['python3', checker.path, staging.get().asFile.path, coordinates[0], coordinates[1], + signed ? 'signed' : 'unsigned'] + artifacts + def process = command.execute() + process.waitForProcessOutput(System.out, System.err) + if (process.exitValue() != 0) { + throw new GradleException('releaseRehearsal: the staged release is incomplete (see above).') + } + } +} + +// The release: releaseCheck, then every module and the SBOM to Gitea Packages, then an anonymous read +// of each module's metadata. release.yml runs this one task on a vX.Y.Z tag. +tasks.register('release') { + group = 'release' + description = 'releaseCheck, publish to Gitea Packages, then verify the version is readable anonymously.' + dependsOn tasks.named('releaseCheck') + dependsOn tasks.named('verifySigningKey') + dependsOn tasks.named('publishAllPublicationsToGiteaRepository') + dependsOn leafPaths.collect { "${it}:publishAllPublicationsToGiteaRepository" } + def url = providers.gradleProperty('packagesUrl') + def artifacts = leaves.collect { it.name } + ['messaging-library'] + def coordinates = libraryCoordinates + def verifier = file('scripts/release/verify-published.sh') + doLast { + def command = ['bash', verifier.path, url.get(), coordinates[0], coordinates[1]] + artifacts + def process = command.execute() + process.waitForProcessOutput(System.out, System.err) + if (process.exitValue() != 0) { + throw new GradleException('release: a published module is not readable anonymously (see above).') + } + } +} + +// The stages a strict lane may belong to, executed by .gitea/workflows as `./gradlew ` from the +// repository root. releaseCheck may run on a tag push only. +strictLaneStages { + stage ':ci', ':mainCheck', ':releaseCheck' + workflowDirectory = layout.projectDirectory.dir('.gitea/workflows') +} diff --git a/config/architecture/modules.json b/config/architecture/modules.json new file mode 100644 index 0000000..1176ad4 --- /dev/null +++ b/config/architecture/modules.json @@ -0,0 +1,190 @@ +{ + "modules": [ + { + "id": "messaging-core-api", + "gradle_path": ":messaging:messaging-core-api", + "source_path": "messaging/messaging-core-api", + "allowed_dependencies": [] + }, + { + "id": "messaging-schema-json", + "gradle_path": ":messaging:messaging-schema-json", + "source_path": "messaging/messaging-schema-json", + "allowed_dependencies": [ + "messaging-core-api" + ] + }, + { + "id": "messaging-schema-avro", + "gradle_path": ":messaging:messaging-schema-avro", + "source_path": "messaging/messaging-schema-avro", + "allowed_dependencies": [ + "messaging-core-api" + ] + }, + { + "id": "messaging-schema-protobuf", + "gradle_path": ":messaging:messaging-schema-protobuf", + "source_path": "messaging/messaging-schema-protobuf", + "allowed_dependencies": [ + "messaging-core-api" + ] + }, + { + "id": "messaging-cloudevents", + "gradle_path": ":messaging:messaging-cloudevents", + "source_path": "messaging/messaging-cloudevents", + "allowed_dependencies": [ + "messaging-core-api" + ] + }, + { + "id": "messaging-policy", + "gradle_path": ":messaging:messaging-policy", + "source_path": "messaging/messaging-policy", + "allowed_dependencies": [ + "messaging-core-api" + ] + }, + { + "id": "messaging-transport-spi", + "gradle_path": ":messaging:messaging-transport-spi", + "source_path": "messaging/messaging-transport-spi", + "allowed_dependencies": [ + "messaging-core-api", + "messaging-policy" + ] + }, + { + "id": "messaging-runtime-core", + "gradle_path": ":messaging:messaging-runtime-core", + "source_path": "messaging/messaging-runtime-core", + "allowed_dependencies": [ + "messaging-core-api", + "messaging-policy", + "messaging-transport-spi", + "messaging-security", + "messaging-observability" + ] + }, + { + "id": "messaging-observability", + "gradle_path": ":messaging:messaging-observability", + "source_path": "messaging/messaging-observability", + "allowed_dependencies": [ + "messaging-core-api" + ] + }, + { + "id": "messaging-security", + "gradle_path": ":messaging:messaging-security", + "source_path": "messaging/messaging-security", + "allowed_dependencies": [ + "messaging-core-api" + ] + }, + { + "id": "messaging-kafka", + "gradle_path": ":messaging:messaging-kafka", + "source_path": "messaging/messaging-kafka", + "allowed_dependencies": [ + "messaging-core-api", + "messaging-policy", + "messaging-transport-spi", + "messaging-observability", + "messaging-security", + "messaging-admin" + ] + }, + { + "id": "messaging-reliability-api", + "gradle_path": ":messaging:messaging-reliability-api", + "source_path": "messaging/messaging-reliability-api", + "allowed_dependencies": [ + "messaging-core-api" + ] + }, + { + "id": "messaging-reliability", + "gradle_path": ":messaging:messaging-reliability", + "source_path": "messaging/messaging-reliability", + "allowed_dependencies": [ + "messaging-core-api", + "messaging-reliability-api" + ] + }, + { + "id": "messaging-reliability-jdbc-postgresql", + "gradle_path": ":messaging:messaging-reliability-jdbc-postgresql", + "source_path": "messaging/messaging-reliability-jdbc-postgresql", + "allowed_dependencies": [ + "messaging-core-api", + "messaging-reliability-api", + "messaging-admin", + "messaging-policy" + ] + }, + { + "id": "messaging-claim-check", + "gradle_path": ":messaging:messaging-claim-check", + "source_path": "messaging/messaging-claim-check", + "allowed_dependencies": [ + "messaging-core-api", + "messaging-reliability-api" + ] + }, + { + "id": "messaging-admin", + "gradle_path": ":messaging:messaging-admin", + "source_path": "messaging/messaging-admin", + "allowed_dependencies": [ + "messaging-core-api", + "messaging-observability" + ] + }, + { + "id": "messaging-spring-boot-starter", + "gradle_path": ":messaging:messaging-spring-boot-starter", + "source_path": "messaging/messaging-spring-boot-starter", + "allowed_dependencies": [ + "messaging-admin", + "messaging-core-api", + "messaging-observability", + "messaging-policy", + "messaging-reliability", + "messaging-reliability-api", + "messaging-reliability-jdbc-postgresql", + "messaging-runtime-core", + "messaging-schema-json", + "messaging-security", + "messaging-transport-spi" + ] + }, + { + "id": "messaging-spring-boot-starter-kafka", + "gradle_path": ":messaging:messaging-spring-boot-starter-kafka", + "source_path": "messaging/messaging-spring-boot-starter-kafka", + "allowed_dependencies": [ + "messaging-spring-boot-starter", + "messaging-kafka", + "messaging-admin", + "messaging-core-api", + "messaging-observability", + "messaging-policy", + "messaging-reliability-api", + "messaging-security", + "messaging-transport-spi" + ] + }, + { + "id": "messaging-testkit", + "gradle_path": ":messaging:messaging-testkit", + "source_path": "messaging/messaging-testkit", + "allowed_dependencies": [ + "messaging-core-api", + "messaging-policy", + "messaging-transport-spi" + ] + } + ] +} diff --git a/config/checkstyle/checkstyle-suppressions.xml b/config/checkstyle/checkstyle-suppressions.xml new file mode 100644 index 0000000..7b6033b --- /dev/null +++ b/config/checkstyle/checkstyle-suppressions.xml @@ -0,0 +1,28 @@ + + + + + + + + diff --git a/config/checkstyle/checkstyle.xml b/config/checkstyle/checkstyle.xml new file mode 100644 index 0000000..0d11fed --- /dev/null +++ b/config/checkstyle/checkstyle.xml @@ -0,0 +1,93 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/config/spotbugs/exclude-test.xml b/config/spotbugs/exclude-test.xml new file mode 100644 index 0000000..02ccbaa --- /dev/null +++ b/config/spotbugs/exclude-test.xml @@ -0,0 +1,84 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/config/spotbugs/exclude.xml b/config/spotbugs/exclude.xml new file mode 100644 index 0000000..978ff83 --- /dev/null +++ b/config/spotbugs/exclude.xml @@ -0,0 +1,200 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/config/testing/container-images.properties b/config/testing/container-images.properties new file mode 100644 index 0000000..a99ef65 --- /dev/null +++ b/config/testing/container-images.properties @@ -0,0 +1,25 @@ +# The container images the test lanes start, in one place. +# +# ca.java-conventions reads this file and hands every key to every Test JVM as the system property +# `ca.test.image.`; the file is an input of every Test task, so changing an image reruns the +# lanes that use it. Build scripts read the same values as `testContainerImages['']`. Copied +# from the backend template's src/config/testing/container-images.properties and cut to the images +# this library's lanes start. +# +# Each image is pinned by digest, with its tag in the comment above it: a red lane should mean this +# repository changed, not that someone pushed a new image under the same tag. A lane whose image +# cannot be pulled fails; it does not skip. The broker certification evidence records the Kafka +# digest (messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl), so a +# change of the `kafka` line below changes the evidence and has to rerun the certification lane. +# +# Pulling through a mirror: set TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX in the environment, for example +# `registry.internal/dockerhub/`. Images from other registries (ghcr.io below) are not rewritten by +# the prefix; mirror them under the same name or replace the value here. + +# postgres:16-alpine — the outbox, inbox and admin-journal lane (messaging-reliability-jdbc-postgresql) +# and the starter's consume round trip. +postgres-16=postgres@sha256:0cefaabd882e42bcb2a2f3dc56d3ce4770560ba62fd7f197f1a2e008fd5731ab +# apache/kafka:4.1.0 — the certification lane and the starter round trip. +kafka=apache/kafka@sha256:bff074a5d0051dbc0bbbcd25b045bb1fe84833ec0d3c7c965d1797dd289ec88f +# ghcr.io/shopify/toxiproxy:2.12.0 — the certification lane's fault injection. +toxiproxy=ghcr.io/shopify/toxiproxy@sha256:9378ed52a28bc50edc1350f936f518f31fa95f0d15917d6eb40b8e376d1a214e diff --git a/gradle.properties b/gradle.properties new file mode 100644 index 0000000..e5214de --- /dev/null +++ b/gradle.properties @@ -0,0 +1,13 @@ +# The Maven group every module publishes under, and where. ca.java-conventions refuses a build +# without libraryGroup; ca.library-publishing reads the other two. +libraryGroup=dev.cakit.messaging +packagesUrl=https://git.learn.hyeonworks.com/api/packages/donghyeon.kang/maven +repositoryUrl=https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library +# The release signing key (public fingerprint). verifySigningKey refuses any other key in SIGNING_KEY. +signingKeyFingerprint=92646CEAFE816CF8B9C249F0A1C936D7F791F8AB + +# Build defaults, copied from the backend template's src/gradle.properties. +org.gradle.workers.max=4 +org.gradle.jvmargs=-Xmx1g -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8 +org.gradle.caching=true +org.gradle.parallel=true diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml new file mode 100644 index 0000000..7114204 --- /dev/null +++ b/gradle/libs.versions.toml @@ -0,0 +1,87 @@ +# Version catalog — every dependency and tool version this build pins itself. +# +# Copied from the backend template's src/gradle/libs.versions.toml (see build-logic/UPSTREAM.md for +# the commit) and cut to the entries this library uses. Versions managed by an imported BOM (Spring +# Boot: kafka-clients, Spring JDBC, Micrometer, Jackson, Testcontainers) are not here. +# `gradle.lockfile` fixes what resolves; this file makes the chosen versions visible side by side. +# +# The `pinned-*` libraries: no module declares them, and their upstream still brings a version with +# a High or Critical advisory. build-logic's JavaConventionsPlugin pins every `pinned-*` entry +# through Spring dependency management in every configuration (the Checkstyle and Error Prone +# classpaths included). Delete an entry once every upstream named in its comment brings a fixed +# version itself. + +[versions] +assertj = "3.27.7" +# messaging-schema-avro's codec. +avro = "1.12.0" +# Checkstyle *tool* version (the `checkstyle` extension), not a plugin: Checkstyle is a Gradle +# built-in plugin with no coordinate of its own. +checkstyle = "13.5.0" +# messaging-cloudevents' binding. +cloudevents = "4.0.1" +errorprone = "2.49.0" +# The Gradle plugin that runs the checker above. Two different artifacts, two different version +# lines, deliberately adjacent so a bump of one is visibly not a bump of the other. +errorpronePlugin = "5.1.0" +findsecbugs = "1.14.0" +# Spotless's google-java-format step. A formatter version is a repository-wide decision: a bump +# reformats every file. +googleJavaFormat = "1.35.0" +# Pinned (see `pinned-*` below). CVE-2026-102554, fixed in 33.7.2. Brought by Error Prone (33.5.0) +# and the Checkstyle tool (33.6.0). +guava = "33.7.2-jre" +# Only build-logic resolves jackson3 as written (it reads the module registry); in the modules the +# Spring Boot BOM's jackson-bom decides. Keep it at the BOM's number. +jackson3 = "3.1.7" +# JMH benchmarks in messaging-kafka and messaging-testkit (`./gradlew :messaging::jmh`); never +# part of a gate. +jmh = "1.37" +jmhPlugin = "0.7.3" +junitJupiter = "5.11.3" +junitPlatform = "1.11.3" +# Pinned (see `pinned-*` below). CVE-2026-106451, fixed in 1.11.4. Brought by kafka-clients (1.10.1). +lz4Java = "1.11.4" +# Pinned (see `pinned-*` below). CVE-2025-67030, fixed in 3.6.1 on the 3.x line. Brought by the +# Checkstyle tool's doxia (3.3.0). +plexusUtils = "3.6.1" +# messaging-schema-protobuf's codec. +protobuf = "4.33.2" +# Pinned (see `pinned-*` below). CVE-2026-93451 and CVE-2026-108106, fixed in 1.1.10.9. Brought by +# kafka-clients (1.1.10.7). +snappyJava = "1.1.10.9" +# SpotBugs *tool* version (the `spotbugs` extension). The plugin that runs it is spotbugsPlugin. +spotbugs = "4.10.2" +spotbugsPlugin = "6.5.6" +spotless = "8.6.0" +springBoot = "4.0.9" +# The version that actually resolves. Spring Boot 4.0.9's own plugin brings +# dependency-management 1.1.7, so the 1.1.6 that used to be written here was a floor nothing ever +# selected (`./gradlew buildEnvironment` reported `1.1.6 -> 1.1.7`). build-logic applies the plugin +# too and has no Boot plugin to upgrade it, so a catalog stating a version nobody resolves would +# have given the convention plugins a different one from the leaves. +springDependencyManagement = "1.1.7" +# messaging-kafka's certification lane puts Toxiproxy between the client and the broker. +toxiproxy = "2.1.7" + +[libraries] +assertj-core = { module = "org.assertj:assertj-core", version.ref = "assertj" } +avro = { module = "org.apache.avro:avro", version.ref = "avro" } +cloudevents-api = { module = "io.cloudevents:cloudevents-api", version.ref = "cloudevents" } +cloudevents-core = { module = "io.cloudevents:cloudevents-core", version.ref = "cloudevents" } +errorprone-core = { module = "com.google.errorprone:error_prone_core", version.ref = "errorprone" } +findsecbugs-plugin = { module = "com.h3xstream.findsecbugs:findsecbugs-plugin", version.ref = "findsecbugs" } +jackson3-core = { module = "tools.jackson.core:jackson-core", version.ref = "jackson3" } +jackson3-databind = { module = "tools.jackson.core:jackson-databind", version.ref = "jackson3" } +junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junitJupiter" } +junit-platform-launcher = { module = "org.junit.platform:junit-platform-launcher", version.ref = "junitPlatform" } +protobuf-java = { module = "com.google.protobuf:protobuf-java", version.ref = "protobuf" } +toxiproxy-java = { module = "eu.rekawek.toxiproxy:toxiproxy-java", version.ref = "toxiproxy" } + +pinned-guava = { module = "com.google.guava:guava", version.ref = "guava" } +pinned-lz4-java = { module = "at.yawk.lz4:lz4-java", version.ref = "lz4Java" } +pinned-plexus-utils = { module = "org.codehaus.plexus:plexus-utils", version.ref = "plexusUtils" } +pinned-snappy-java = { module = "org.xerial.snappy:snappy-java", version.ref = "snappyJava" } + +[plugins] +jmh = { id = "me.champeau.jmh", version.ref = "jmhPlugin" } diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar new file mode 100644 index 0000000000000000000000000000000000000000..8bdaf60c75ab801e22807dde59e12a8735a34077 GIT binary patch literal 45457 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 c82=K%QXLKFx%@O{wJjEi6Y56o#$)Bpeg literal 0 HcmV?d00001 diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties new file mode 100644 index 0000000..6ca2586 --- /dev/null +++ b/gradle/wrapper/gradle-wrapper.properties @@ -0,0 +1,8 @@ +distributionBase=GRADLE_USER_HOME +distributionPath=wrapper/dists +distributionUrl=https\://services.gradle.org/distributions/gradle-9.0.0-bin.zip +distributionSha256Sum=8fad3d78296ca518113f3d29016617c7f9367dc005f932bd9d93bf45ba46072b +networkTimeout=10000 +validateDistributionUrl=true +zipStoreBase=GRADLE_USER_HOME +zipStorePath=wrapper/dists diff --git a/gradlew b/gradlew new file mode 100755 index 0000000..ef07e01 --- /dev/null +++ b/gradlew @@ -0,0 +1,251 @@ +#!/bin/sh + +# +# Copyright © 2015 the original authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 +# + +############################################################################## +# +# Gradle start up script for POSIX generated by Gradle. +# +# Important for running: +# +# (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is +# noncompliant, but you have some other compliant shell such as ksh or +# bash, then to run this script, type that shell name before the whole +# command line, like: +# +# ksh Gradle +# +# Busybox and similar reduced shells will NOT work, because this script +# requires all of these POSIX shell features: +# * functions; +# * expansions «$var», «${var}», «${var:-default}», «${var+SET}», +# «${var#prefix}», «${var%suffix}», and «$( cmd )»; +# * compound commands having a testable exit status, especially «case»; +# * various built-in commands including «command», «set», and «ulimit». +# +# Important for patching: +# +# (2) This script targets any POSIX shell, so it avoids extensions provided +# by Bash, Ksh, etc; in particular arrays are avoided. +# +# The "traditional" practice of packing multiple parameters into a +# space-separated string is a well documented source of bugs and security +# problems, so this is (mostly) avoided, by progressively accumulating +# options in "$@", and eventually passing that to Java. +# +# Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS, +# and GRADLE_OPTS) rely on word-splitting, this is performed explicitly; +# see the in-line comments for details. +# +# There are tweaks for specific operating systems such as AIX, CygWin, +# Darwin, MinGW, and NonStop. +# +# (3) This script is generated from the Groovy template +# https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt +# within the Gradle project. +# +# You can find Gradle at https://github.com/gradle/gradle/. +# +############################################################################## + +# Attempt to set APP_HOME + +# Resolve links: $0 may be a link +app_path=$0 + +# Need this for daisy-chained symlinks. +while + APP_HOME=${app_path%"${app_path##*/}"} # leaves a trailing /; empty if no leading path + [ -h "$app_path" ] +do + ls=$( ls -ld "$app_path" ) + link=${ls#*' -> '} + case $link in #( + /*) app_path=$link ;; #( + *) app_path=$APP_HOME$link ;; + esac +done + +# This is normally unused +# shellcheck disable=SC2034 +APP_BASE_NAME=${0##*/} +# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036) +APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit + +# Use the maximum available, or set MAX_FD != -1 to use that value. +MAX_FD=maximum + +warn () { + echo "$*" +} >&2 + +die () { + echo + echo "$*" + echo + exit 1 +} >&2 + +# OS specific support (must be 'true' or 'false'). +cygwin=false +msys=false +darwin=false +nonstop=false +case "$( uname )" in #( + CYGWIN* ) cygwin=true ;; #( + Darwin* ) darwin=true ;; #( + MSYS* | MINGW* ) msys=true ;; #( + NONSTOP* ) nonstop=true ;; +esac + +CLASSPATH="\\\"\\\"" + + +# Determine the Java command to use to start the JVM. +if [ -n "$JAVA_HOME" ] ; then + if [ -x "$JAVA_HOME/jre/sh/java" ] ; then + # IBM's JDK on AIX uses strange locations for the executables + JAVACMD=$JAVA_HOME/jre/sh/java + else + JAVACMD=$JAVA_HOME/bin/java + fi + if [ ! -x "$JAVACMD" ] ; then + die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME + +Please set the JAVA_HOME variable in your environment to match the +location of your Java installation." + fi +else + JAVACMD=java + if ! command -v java >/dev/null 2>&1 + then + die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. + +Please set the JAVA_HOME variable in your environment to match the +location of your Java installation." + fi +fi + +# Increase the maximum file descriptors if we can. +if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then + case $MAX_FD in #( + max*) + # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked. + # shellcheck disable=SC2039,SC3045 + MAX_FD=$( ulimit -H -n ) || + warn "Could not query maximum file descriptor limit" + esac + case $MAX_FD in #( + '' | soft) :;; #( + *) + # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked. + # shellcheck disable=SC2039,SC3045 + ulimit -n "$MAX_FD" || + warn "Could not set maximum file descriptor limit to $MAX_FD" + esac +fi + +# Collect all arguments for the java command, stacking in reverse order: +# * args from the command line +# * the main class name +# * -classpath +# * -D...appname settings +# * --module-path (only if needed) +# * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables. + +# For Cygwin or MSYS, switch paths to Windows format before running java +if "$cygwin" || "$msys" ; then + APP_HOME=$( cygpath --path --mixed "$APP_HOME" ) + CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" ) + + JAVACMD=$( cygpath --unix "$JAVACMD" ) + + # Now convert the arguments - kludge to limit ourselves to /bin/sh + for arg do + if + case $arg in #( + -*) false ;; # don't mess with options #( + /?*) t=${arg#/} t=/${t%%/*} # looks like a POSIX filepath + [ -e "$t" ] ;; #( + *) false ;; + esac + then + arg=$( cygpath --path --ignore --mixed "$arg" ) + fi + # Roll the args list around exactly as many times as the number of + # args, so each arg winds up back in the position where it started, but + # possibly modified. + # + # NB: a `for` loop captures its iteration list before it begins, so + # changing the positional parameters here affects neither the number of + # iterations, nor the values presented in `arg`. + shift # remove old arg + set -- "$@" "$arg" # push replacement arg + done +fi + + +# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"' + +# Collect all arguments for the java command: +# * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments, +# and any embedded shellness will be escaped. +# * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be +# treated as '${Hostname}' itself on the command line. + +set -- \ + "-Dorg.gradle.appname=$APP_BASE_NAME" \ + -classpath "$CLASSPATH" \ + -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \ + "$@" + +# Stop when "xargs" is not available. +if ! command -v xargs >/dev/null 2>&1 +then + die "xargs is not available" +fi + +# Use "xargs" to parse quoted args. +# +# With -n1 it outputs one arg per line, with the quotes and backslashes removed. +# +# In Bash we could simply go: +# +# readarray ARGS < <( xargs -n1 <<<"$var" ) && +# set -- "${ARGS[@]}" "$@" +# +# but POSIX shell has neither arrays nor command substitution, so instead we +# post-process each arg (as a line of input to sed) to backslash-escape any +# character that might be a shell metacharacter, then use eval to reverse +# that process (while maintaining the separation between arguments), and wrap +# the whole thing up as a single "set" statement. +# +# This will of course break if any of these variables contains a newline or +# an unmatched quote. +# + +eval "set -- $( + printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" | + xargs -n1 | + sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' | + tr '\n' ' ' + )" '"$@"' + +exec "$JAVACMD" "$@" diff --git a/gradlew.bat b/gradlew.bat new file mode 100644 index 0000000..5eed7ee --- /dev/null +++ b/gradlew.bat @@ -0,0 +1,94 @@ +@rem +@rem Copyright 2015 the original author or authors. +@rem +@rem Licensed under the Apache License, Version 2.0 (the "License"); +@rem you may not use this file except in compliance with the License. +@rem You may obtain a copy of the License at +@rem +@rem https://www.apache.org/licenses/LICENSE-2.0 +@rem +@rem Unless required by applicable law or agreed to in writing, software +@rem distributed under the License is distributed on an "AS IS" BASIS, +@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +@rem See the License for the specific language governing permissions and +@rem limitations under the License. +@rem +@rem SPDX-License-Identifier: Apache-2.0 +@rem + +@if "%DEBUG%"=="" @echo off +@rem ########################################################################## +@rem +@rem Gradle startup script for Windows +@rem +@rem ########################################################################## + +@rem Set local scope for the variables with windows NT shell +if "%OS%"=="Windows_NT" setlocal + +set DIRNAME=%~dp0 +if "%DIRNAME%"=="" set DIRNAME=. +@rem This is normally unused +set APP_BASE_NAME=%~n0 +set APP_HOME=%DIRNAME% + +@rem Resolve any "." and ".." in APP_HOME to make it shorter. +for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi + +@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m" + +@rem Find java.exe +if defined JAVA_HOME goto findJavaFromJavaHome + +set JAVA_EXE=java.exe +%JAVA_EXE% -version >NUL 2>&1 +if %ERRORLEVEL% equ 0 goto execute + +echo. 1>&2 +echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2 +echo. 1>&2 +echo Please set the JAVA_HOME variable in your environment to match the 1>&2 +echo location of your Java installation. 1>&2 + +goto fail + +:findJavaFromJavaHome +set JAVA_HOME=%JAVA_HOME:"=% +set JAVA_EXE=%JAVA_HOME%/bin/java.exe + +if exist "%JAVA_EXE%" goto execute + +echo. 1>&2 +echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2 +echo. 1>&2 +echo Please set the JAVA_HOME variable in your environment to match the 1>&2 +echo location of your Java installation. 1>&2 + +goto fail + +:execute +@rem Setup the command line + +set CLASSPATH= + + +@rem Execute Gradle +"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %* + +:end +@rem End local scope for the variables with windows NT shell +if %ERRORLEVEL% equ 0 goto mainEnd + +:fail +rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of +rem the _cmd.exe /c_ return code! +set EXIT_CODE=%ERRORLEVEL% +if %EXIT_CODE% equ 0 set EXIT_CODE=1 +if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE% +exit /b %EXIT_CODE% + +:mainEnd +if "%OS%"=="Windows_NT" endlocal + +:omega diff --git a/messaging/messaging-kafka/build.gradle b/messaging/messaging-kafka/build.gradle index 620f109..cfa3122 100644 --- a/messaging/messaging-kafka/build.gradle +++ b/messaging/messaging-kafka/build.gradle @@ -98,7 +98,7 @@ tasks.register('verifyMessagingCertificationEvidence') { description = 'Fails when the committed broker certification manifest claims a scenario the certification lane did not produce.' dependsOn 'messagingCertificationTest' def produced = layout.buildDirectory.file('messaging-certification/broker-certification-evidence.jsonl') - def committed = rootProject.file('platforms/messaging/messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl') + def committed = rootProject.file('messaging/messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl') inputs.file(produced) inputs.file(committed) doLast { diff --git a/messaging/messaging-testkit/build.gradle b/messaging/messaging-testkit/build.gradle index 0b4b657..7024edc 100644 --- a/messaging/messaging-testkit/build.gradle +++ b/messaging/messaging-testkit/build.gradle @@ -16,3 +16,31 @@ dependencies { api 'org.junit.jupiter:junit-jupiter' api 'org.assertj:assertj-core' } + +// The repository contracts of the whole library: every module's public signatures against its +// declared `api` scope, and the one owner of the `app.messaging` settings namespace. They read other +// modules' sources and build scripts, so they run in a lane of their own that declares exactly those +// files as inputs and receives the repository root; the plain `test` lane gets no root, and a test +// that reads the repository without the tag fails there. The template ran them in its app-bootstrap +// `repositoryContractTest` lane until the library left it. Part of `check`, so of the pull-request +// stage. +def repositoryRoot = rootProject.projectDir +strictTestLanes { + lane('repositoryContractTest') { + tag = 'repository-contract' + description = 'Holds every module to its declared api scope and the one owner of app.messaging.' + systemProperty 'ca.repository.root', repositoryRoot.absolutePath + customize { Test task -> + task.inputs.files(fileTree(repositoryRoot) { + include 'messaging/*/build.gradle', 'messaging/*/src/main/**', 'gradle/libs.versions.toml' + exclude '**/build/**' + }).withPathSensitivity(PathSensitivity.RELATIVE).withPropertyName('repositoryContractInputs') + } + } +} +tasks.named('test', Test) { + useJUnitPlatform { excludeTags 'repository-contract' } +} +tasks.named('check') { + dependsOn 'repositoryContractTest' +} diff --git a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java index c42097b..fb5b097 100644 --- a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java +++ b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingPublicSurfaceContractTest.java @@ -1,8 +1,7 @@ -package dev.caskeleton.bootstrap.contract.messaging; +package dev.caskeleton.messaging.testkit.contract; import static org.assertj.core.api.Assertions.assertThat; -import dev.caskeleton.bootstrap.contract.support.RepositoryContractResources; import java.io.IOException; import java.io.UncheckedIOException; import java.nio.file.Files; @@ -34,8 +33,8 @@ import org.junit.jupiter.api.Test; * *

So the rule is one-directional and mechanical: a vendor library named in a public or protected * signature is declared {@code api}; one used only behind private members stays {@code - * implementation}. {@code src/platforms/messaging/AGENTS.md} states it as policy — this holds it to - * the source so the two cannot drift. + * implementation}. {@code messaging/AGENTS.md} states it as policy — this holds it to the source so + * the two cannot drift. * *

The libraries checked are the ones an adopter would otherwise have to reverse-engineer into * their own build: broker clients, codec libraries, the metrics registry, the reactive facade. @@ -327,7 +326,7 @@ class MessagingPublicSurfaceContractTest { */ private static Map catalogModules() { Map modules = new LinkedHashMap<>(); - Path catalog = repositoryRoot().resolve("src/gradle/libs.versions.toml"); + Path catalog = repositoryRoot().resolve("gradle/libs.versions.toml"); if (!Files.isRegularFile(catalog)) { return modules; } @@ -345,7 +344,7 @@ class MessagingPublicSurfaceContractTest { } private static List messagingLeaves() { - Path family = repositoryRoot().resolve("src/platforms/messaging"); + Path family = repositoryRoot().resolve("messaging"); try (Stream children = Files.list(family)) { return children .filter(Files::isDirectory) @@ -378,9 +377,6 @@ class MessagingPublicSurfaceContractTest { } private static Path repositoryRoot() { - // Gradle hands the root only to the lanes that declare the repository files as inputs; the - // plain `test` lane gets none, so a test that reads the repository without a lane tag fails - // here instead of going stale behind an up-to-date check (review 2026-11-01 08-03). - return RepositoryContractResources.fromSystemProperty().repositoryRoot(); + return RepositoryRoot.fromSystemProperty(); } } diff --git a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingSettingsOwnerContractTest.java b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingSettingsOwnerContractTest.java new file mode 100644 index 0000000..42dc786 --- /dev/null +++ b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/MessagingSettingsOwnerContractTest.java @@ -0,0 +1,91 @@ +package dev.caskeleton.messaging.testkit.contract; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.io.IOException; +import java.io.UncheckedIOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.regex.Pattern; +import java.util.stream.Stream; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Tag; +import org.junit.jupiter.api.Test; + +/** + * How many types in this library own the {@code app.messaging} settings namespace. + * + *

The namespace is shared on purpose with one consumer: the backend template's outbound adapter + * binds {@code app.messaging.producer-id} through a settings type of its own, and the starter's + * {@code MessagingSettings} owns everything else, {@code broker} included. Spring binds both — each + * takes the fields it declares. While the two lived in one repository a single source scan counted + * both (the template's {@code MessagingAuthorityContractTest}, MSG-INT-002). Now each repository + * holds its own half: here, exactly one owner. A second one inside the library is how a setting + * comes to mean two things to two halves of the same product. The prefix is part of this library's + * public contract; renaming it is a MAJOR change. + */ +@Tag("repository-contract") +class MessagingSettingsOwnerContractTest { + + private static final Pattern MESSAGING_PREFIX = + Pattern.compile("@ConfigurationProperties\\(\\s*(prefix\\s*=\\s*)?\"app\\.messaging\""); + + private static final Pattern MESSAGING_PREFIX_CONSTANT = + Pattern.compile("@ConfigurationProperties\\(prefix = MessagingSettings\\.PREFIX\\)"); + + /** A strictly bound owner names its tree in a constant rather than an annotation. */ + private static final Pattern STRICT_BINDER_PREFIX = + Pattern.compile("String PREFIX\\s*=\\s*\"app\\.messaging\""); + + @Test + @DisplayName("이 라이브러리에서 app.messaging의 주인은 starter의 MessagingSettings 하나다") + void theStarterSettingsAreTheOnlyOwner() { + // given + List sources = productionSources(); + + // when + List owners = + sources.stream() + .filter(MessagingSettingsOwnerContractTest::ownsTheNamespace) + .map(path -> repositoryRoot().relativize(path).toString()) + .toList(); + + // then + assertThat(owners) + .containsExactly( + "messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/" + + "autoconfigure/MessagingSettings.java"); + } + + private static boolean ownsTheNamespace(Path source) { + String text = read(source); + return MESSAGING_PREFIX.matcher(text).find() + || MESSAGING_PREFIX_CONSTANT.matcher(text).find() + || STRICT_BINDER_PREFIX.matcher(text).find(); + } + + private static List productionSources() { + try (Stream walk = Files.walk(repositoryRoot().resolve("messaging"))) { + return walk.filter(path -> path.toString().endsWith(".java")) + .filter(path -> path.toString().contains("/src/main/java/")) + .filter(path -> !path.toString().contains("/build/")) + .sorted() + .toList(); + } catch (IOException unreadable) { + throw new UncheckedIOException(unreadable); + } + } + + private static String read(Path path) { + try { + return Files.readString(path); + } catch (IOException unreadable) { + throw new UncheckedIOException(unreadable); + } + } + + private static Path repositoryRoot() { + return RepositoryRoot.fromSystemProperty(); + } +} diff --git a/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/RepositoryRoot.java b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/RepositoryRoot.java new file mode 100644 index 0000000..9119634 --- /dev/null +++ b/messaging/messaging-testkit/src/test/java/dev/caskeleton/messaging/testkit/contract/RepositoryRoot.java @@ -0,0 +1,50 @@ +package dev.caskeleton.messaging.testkit.contract; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.InvalidPathException; +import java.nio.file.Path; +import java.util.List; + +/** + * The repository root for the contract tests that read other modules' files. + * + *

Gradle passes it only to messaging-testkit's {@code repositoryContractTest} lane, which + * declares the files those tests read as its inputs. The plain {@code test} lane gets no root, so + * an untagged test that reads the repository fails here rather than passing on a stale up-to-date + * result. The same rule as the backend template's {@code RepositoryContractResources}, which these + * tests used while they lived there. + */ +final class RepositoryRoot { + + static final String ROOT_PROPERTY = "ca.repository.root"; + private static final List ROOT_SENTINELS = + List.of("settings.gradle", "config/architecture/modules.json"); + + private RepositoryRoot() {} + + static Path fromSystemProperty() { + String configured = System.getProperty(ROOT_PROPERTY); + if (configured == null || configured.isBlank()) { + throw new IllegalStateException( + "Required system property '" + + ROOT_PROPERTY + + "' is missing or blank. Only the repository-contract lane receives it: tag a test" + + " that reads the repository with `repository-contract`."); + } + Path root; + try { + root = Path.of(configured).toRealPath(); + } catch (InvalidPathException | IOException unresolvable) { + throw new IllegalStateException( + "Repository root is not resolvable: " + configured, unresolvable); + } + for (String sentinel : ROOT_SENTINELS) { + if (!Files.isRegularFile(root.resolve(sentinel))) { + throw new IllegalStateException( + "Configured repository root must contain " + ROOT_SENTINELS + ": " + root); + } + } + return root; + } +} diff --git a/scripts/release/check-signing-key.sh b/scripts/release/check-signing-key.sh new file mode 100755 index 0000000..20a8db2 --- /dev/null +++ b/scripts/release/check-signing-key.sh @@ -0,0 +1,175 @@ +#!/usr/bin/env bash +# Checks the release signing secrets before anything is signed, without printing them. +# +# scripts/release/check-signing-key.sh [expected fingerprint] +# +# Reads SIGNING_KEY (an ASCII-armoured PGP secret key) and SIGNING_PASSWORD from the environment and +# prints only shapes and verdicts: line and character counts, whether the armour lines and the blank +# line after BEGIN are where OpenPGP puts them, whether the base64 body decodes and its CRC24 matches, +# the first packet's tag, whether gpg imports it, the imported key's fingerprint (public), and whether +# SIGNING_PASSWORD signs with it. No value, line or fragment of either secret is ever printed; do not +# add `set -x` here. +# +# Why it exists: Gradle's signing reports any of these problems as one "Could not read PGP secret +# key", and the cause sits in a secret nobody can look at in the job log (v1.0.0 release run 9). +# Exit codes: 0 = the key would sign, 1 = a check failed (the line says which), 2 = usage. +set -euo pipefail + +expected=${1:-} +fail=0 + +if [ -z "${SIGNING_KEY:-}" ]; then + echo "check-signing-key: SIGNING_KEY is empty or not set" + exit 1 +fi +[ -n "${SIGNING_PASSWORD:-}" ] || echo "check-signing-key: SIGNING_PASSWORD is empty (only right for a key without a passphrase)" +# The passphrase's shape only: a pasted value often carries a line break or spaces the key was not +# protected with, and Gradle uses the value as given. +python3 - <<'PY' || fail=1 +import os, sys +p = os.environ.get("SIGNING_PASSWORD", "") +print(f"password shape: {len(p)} characters, line breaks {p.count(chr(10))}, CR {p.count(chr(13))}," + f" leading whitespace {'yes' if p[:1].isspace() else 'no'}, trailing whitespace {'yes' if p[-1:].isspace() else 'no'}," + f" non-ASCII characters {sum(1 for c in p if ord(c) > 127)}") +if "-----BEGIN PGP" in p or len(p) > 1000: + print("PROBLEM: SIGNING_PASSWORD holds a PGP key block (or something as long), not the passphrase." + " Put in only the passphrase chosen when the key was made.") + sys.exit(1) +PY + +home=$(mktemp -d) +trap 'rm -rf "$home"' EXIT +chmod 700 "$home" +KEY_OUT=$home/key.asc EXPECTED_FINGERPRINT=$expected python3 - <<'PY' || fail=1 +import base64, os, re, sys + +key = os.environ["SIGNING_KEY"] +BEGIN = "-----BEGIN PGP PRIVATE KEY BLOCK-----" +END = "-----END PGP PRIVATE KEY BLOCK-----" +problems = [] + +print(f"shape: {len(key)} characters, {key.count(chr(10)) + 1} lines," + f" CR {'present' if chr(13) in key else 'absent'}," + f" literal backslash-n sequences {key.count(chr(92) + 'n')}," + f" non-ASCII characters {sum(1 for c in key if ord(c) > 127)}," + f" leading whitespace {'yes' if key[:1].isspace() else 'no'}," + f" trailing whitespace {'yes' if key[-1:].isspace() else 'no'}") + +stripped = key.strip() +compact = re.sub(r"\s", "", key) +if "-----BEGIN" not in key and re.fullmatch(r"[A-Za-z0-9+/]+={0,2}", compact or "x"): + try: + unwrapped = base64.b64decode(compact).decode("utf-8") + except Exception: + unwrapped = "" + if unwrapped.strip().startswith("-----BEGIN PGP PRIVATE KEY BLOCK-----"): + print("form: base64 of an armoured key file on one value; the build unwraps it (SigningKeys), so the checks below read the unwrapped text") + key = unwrapped + stripped = key.strip() + print(f"unwrapped shape: {len(key)} characters, {key.count(chr(10)) + 1} lines") + +if re.fullmatch(r"(0x)?[0-9A-Fa-f]{8}|(0x)?[0-9A-Fa-f]{16}|[0-9A-Fa-f]{40}", stripped): + expected = os.environ.get("EXPECTED_FINGERPRINT", "") + same = " (the release key's fingerprint)" if expected and stripped.upper() == expected.upper() else "" + print(f"PROBLEM: SIGNING_KEY holds a {len(stripped)}-hex-digit key ID or fingerprint{same}, not the key." + " Put in the output of `gpg --armor --export-secret-keys ` instead, BEGIN to END lines.") + sys.exit(1) + +lines = key.replace("\r\n", "\n").replace("\r", "\n").split("\n") +while lines and lines[-1].strip() == "": + lines.pop() +if "\n" not in key.replace("\r", "\n"): + problems.append("the value is one line: the newlines were lost (paste the file as is, with its line breaks)") +first = lines[0].strip() if lines else "" +last = lines[-1].strip() if lines else "" +print(f"armour: first line is BEGIN {'yes' if first == BEGIN else 'no'}, last line is END {'yes' if last == END else 'no'}") +if first != BEGIN: + kind = "a PUBLIC key block" if "PUBLIC KEY BLOCK" in first else "something else" + problems.append(f"the value does not start with the BEGIN PGP PRIVATE KEY BLOCK line (it starts with {kind})") +if last != END: + problems.append("the value does not end with the END PGP PRIVATE KEY BLOCK line (cut short?)") + +body = lines[1:-1] if first == BEGIN and last == END else lines +headers = [] +while body and ":" in body[0] and body[0].strip(): + headers.append(body.pop(0)) +blank_after = bool(body) and body[0].strip() == "" +print(f"armour headers: {len(headers)}, blank line after them {'yes' if blank_after else 'no'}") +if not blank_after: + problems.append("no blank line between the BEGIN line (and its headers) and the base64 body") +data = [l.strip() for l in body if l.strip()] +checksum = data.pop() if data and data[-1].startswith("=") else None +lengths = [len(l) for l in data] +full = sum(1 for n in lengths[:-1] if n == lengths[0]) if lengths else 0 +print(f"body: {len(data)} base64 lines, first {lengths[0] if lengths else 0} characters wide," + f" {full + (1 if lengths else 0)} of {len(data)} lines that width or the last," + f" checksum line {'present' if checksum else 'absent'}") +if lengths and any(n != lengths[0] for n in lengths[:-1]): + problems.append("base64 lines of different widths before the last one (lines joined, split or cut)") +joined = "".join(data) +bad = sum(1 for c in joined if not re.match(r"[A-Za-z0-9+/=]", c)) +if bad: + problems.append(f"{bad} characters outside the base64 alphabet in the body") +try: + raw = base64.b64decode(joined, validate=False) +except Exception as error: + raw = b"" + problems.append(f"the body does not decode as base64 ({type(error).__name__})") +if raw: + def crc24(data): + crc = 0xB704CE + for byte in data: + crc ^= byte << 16 + for _ in range(8): + crc <<= 1 + if crc & 0x1000000: + crc ^= 0x1864CFB + return crc & 0xFFFFFF + if checksum: + try: + stated = int.from_bytes(base64.b64decode(checksum[1:]), "big") + match = stated == crc24(raw) + except Exception: + match = False + print(f"CRC24 of the decoded body matches the checksum line: {'yes' if match else 'no'}") + if not match: + problems.append("the CRC24 checksum does not match: the base64 body was changed (a line lost, added or edited)") + header = raw[0] + tag = (header & 0x3F) if header & 0x40 else ((header & 0x3C) >> 2) + names = {5: "secret key", 6: "public key", 7: "secret subkey"} + print(f"first packet: tag {tag} ({names.get(tag, 'not a key packet')}), {len(raw)} bytes decoded") + if not header & 0x80 or tag != 5: + problems.append("the first packet is not a secret key packet (tag 5)") + +for problem in problems: + print(f"PROBLEM: {problem}") +with open(os.environ["KEY_OUT"], "w", encoding="utf-8") as out: + out.write(key) +sys.exit(1 if problems else 0) +PY + +if [ -s "$home/key.asc" ] && GNUPGHOME="$home" gpg --batch --quiet --import "$home/key.asc" >/dev/null 2>&1; then + fingerprint=$(GNUPGHOME="$home" gpg --batch --with-colons --list-secret-keys 2>/dev/null | awk -F: '/^fpr/{print $10; exit}') + echo "gpg import: ok, secret key fingerprint ${fingerprint:-none}" + if [ -n "$expected" ] && [ "${fingerprint:-}" != "$expected" ]; then + echo "PROBLEM: the imported key is not the release key ${expected}" + fail=1 + fi + printf 'signing check\n' > "$home/message" + # gpg reads only the first line of the file; the shape line above says whether there is more. + printf '%s' "${SIGNING_PASSWORD:-}" > "$home/passphrase" + if GNUPGHOME="$home" gpg --batch --pinentry-mode loopback --passphrase-file "$home/passphrase" \ + --status-fd 3 --local-user "${fingerprint:-none}" --detach-sign --output "$home/message.sig" \ + "$home/message" >/dev/null 2>&1 3>"$home/status"; then + echo "signing with SIGNING_PASSWORD: ok" + else + # gpg's status keywords only (BAD_PASSPHRASE, MISSING_PASSPHRASE, ERROR …): no values. + status=$(awk '$1 == "[GNUPG:]" {print $2}' "$home/status" | sort -u | tr '\n' ' ') + echo "PROBLEM: SIGNING_PASSWORD does not unlock the key for signing (gpg status: ${status:-none})" + fail=1 + fi +else + echo "PROBLEM: gpg cannot import SIGNING_KEY" + fail=1 +fi +exit "$fail" diff --git a/scripts/release/check-staging.py b/scripts/release/check-staging.py new file mode 100644 index 0000000..33ca784 --- /dev/null +++ b/scripts/release/check-staging.py @@ -0,0 +1,85 @@ +#!/usr/bin/env python3 +"""Checks a staged release (build/staging-repository) file by file before anything is uploaded. + + check-staging.py signed|unsigned ... + +For every module: the jar, sources and javadoc jars, POM and Gradle module file, each with its +.md5/.sha1/.sha256/.sha512 checksum (and .asc when signed), and every dependency in the POM and the +module file carries a version. The last check is the publishing trap the design names: the modules +declare most dependencies without a version and let a BOM fill it, and a published file written +from the declarations would leave consumers nothing to resolve. For the SBOM artifact +(messaging-library): its POM and the CycloneDX JSON. +""" +import json +import sys +import xml.etree.ElementTree as ET +from pathlib import Path + +CHECKSUMS = (".md5", ".sha1", ".sha256", ".sha512") +POM = "{http://maven.apache.org/POM/4.0.0}" + + +def expect(path: Path, signed: bool, problems: list[str]) -> None: + if not path.is_file(): + problems.append(f"missing {path.name}") + return + for suffix in CHECKSUMS + ((".asc",) if signed else ()): + if not path.with_name(path.name + suffix).is_file(): + problems.append(f"missing {path.name}{suffix}") + + +def unversioned_pom(pom: Path) -> list[str]: + root = ET.parse(pom).getroot() + out = [] + for dependency in root.iter(f"{POM}dependency"): + version = dependency.findtext(f"{POM}version") + if not version or not version.strip(): + out.append(f"{dependency.findtext(f'{POM}groupId')}:{dependency.findtext(f'{POM}artifactId')}") + return out + + +def unversioned_module(module: Path) -> list[str]: + data = json.loads(module.read_text(encoding="utf-8")) + out = [] + for variant in data.get("variants", []): + for dependency in variant.get("dependencies", []): + version = dependency.get("version") or {} + if not any(version.get(k) for k in ("requires", "strictly", "prefers")): + out.append(f"{variant['name']}: {dependency['group']}:{dependency['module']}") + return out + + +def main() -> int: + if len(sys.argv) < 6: + print(__doc__, file=sys.stderr) + return 2 + repository, group, version, signing = Path(sys.argv[1]), sys.argv[2], sys.argv[3], sys.argv[4] + signed = signing == "signed" + failed = False + for artifact in sys.argv[5:] + ["messaging-library"]: + directory = repository / group.replace(".", "/") / artifact / version + base = directory / f"{artifact}-{version}" + problems: list[str] = [] + if artifact == "messaging-library": + expect(base.with_name(base.name + ".pom"), signed, problems) + expect(base.with_name(base.name + "-cyclonedx.json"), signed, problems) + else: + for suffix in (".jar", "-sources.jar", "-javadoc.jar", ".pom", ".module"): + expect(base.with_name(base.name + suffix), signed, problems) + pom, module = base.with_name(base.name + ".pom"), base.with_name(base.name + ".module") + if pom.is_file(): + problems += [f"POM dependency without a version: {d}" for d in unversioned_pom(pom)] + if module.is_file(): + problems += [f"module dependency without a version: {d}" for d in unversioned_module(module)] + if problems: + failed = True + print(f"{group}:{artifact}:{version}", file=sys.stderr) + for problem in problems: + print(f" - {problem}", file=sys.stderr) + else: + print(f"staged: {group}:{artifact}:{version}{' (signed)' if signed else ''}") + return 1 if failed else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/release/sbom.sh b/scripts/release/sbom.sh new file mode 100755 index 0000000..9dccac0 --- /dev/null +++ b/scripts/release/sbom.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +# The release's software bill of materials: one CycloneDX JSON for the version, from the committed +# lockfiles of the published modules (build-logic is a build tool and is not shipped). Made before +# the blocking vulnerability check, so a failed release can still say what it would have shipped. +# +# scripts/release/sbom.sh +set -euo pipefail + +root=$(git rev-parse --show-toplevel) +output=${1:?usage: sbom.sh } +mkdir -p "$(dirname "$output")" +trivy=$("$root/scripts/tool.sh" trivy) +cd "$root" +"$trivy" fs --skip-version-check --format cyclonedx --skip-dirs build-logic --output "$output" . +python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); assert d.get("bomFormat")=="CycloneDX" and d.get("components"), "empty SBOM"; print("sbom:", len(d["components"]), "components")' "$output" diff --git a/scripts/release/verify-published.sh b/scripts/release/verify-published.sh new file mode 100755 index 0000000..b04574e --- /dev/null +++ b/scripts/release/verify-published.sh @@ -0,0 +1,22 @@ +#!/usr/bin/env bash +# After `publish`: every module's maven-metadata.xml, fetched anonymously, lists the new version. +# Anonymous on purpose: consumers (the backend template, its image build) read without a token, so a +# package only the owner can read is not published. +# +# scripts/release/verify-published.sh ... +set -euo pipefail + +url=${1:?}; group=${2:?}; version=${3:?}; shift 3 +[ $# -gt 0 ] || { echo "verify-published: no artifacts named" >&2; exit 2; } +path=${group//.//} +missing=0 +for artifact in "$@"; do + metadata=$(curl --fail --show-error --silent --location --retry 3 "$url/$path/$artifact/maven-metadata.xml" || true) + if grep -q "$version" <<<"$metadata"; then + echo "published: $group:$artifact:$version" + else + echo "verify-published: $group:$artifact:$version is not in $url/$path/$artifact/maven-metadata.xml" >&2 + missing=1 + fi +done +exit "$missing" diff --git a/scripts/release/vulnerability-scan.sh b/scripts/release/vulnerability-scan.sh new file mode 100755 index 0000000..f8d73ae --- /dev/null +++ b/scripts/release/vulnerability-scan.sh @@ -0,0 +1,47 @@ +#!/usr/bin/env bash +# The release's dependency gate over the committed lockfiles, the backend template's policy: +# 1. HIGH and CRITICAL fail. +# 2. MEDIUM and LOW are reported and do not fail. +# 3. Any finding listed in the CISA Known Exploited Vulnerabilities catalog fails, whatever its +# severity. An unreachable or malformed catalog fails too: a cross-check that did not run must +# not read as "no match". +# Suppressions: .trivyignore.yaml only (each entry with a statement and an expiry). +# +# scripts/release/vulnerability-scan.sh +set -euo pipefail + +root=$(git rev-parse --show-toplevel) +out=${1:?usage: vulnerability-scan.sh } +mkdir -p "$out" +trivy=$("$root/scripts/tool.sh" trivy) +cd "$root" + +"$trivy" fs --skip-version-check --scanners vuln --severity CRITICAL,HIGH --exit-code 1 --ignorefile .trivyignore.yaml . +"$trivy" fs --skip-version-check --scanners vuln --severity MEDIUM,LOW --exit-code 0 --ignorefile .trivyignore.yaml . +"$trivy" fs --skip-version-check --scanners vuln --severity CRITICAL,HIGH,MEDIUM,LOW,UNKNOWN --exit-code 0 \ + --ignorefile .trivyignore.yaml --format json --output "$out/trivy-all.json" . + +kev_url=${KEV_FEED_URL:-https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json} +if ! curl --fail --show-error --silent --location --retry 3 --proto '=https' --tlsv1.2 \ + "$kev_url" --output "$out/kev.json"; then + echo "vulnerability-scan: KEV feed unavailable ($kev_url); set KEV_FEED_URL to an approved mirror." >&2 + exit 1 +fi +python3 - "$out/trivy-all.json" "$out/kev.json" <<'PY' +import json, re, sys +findings, kev = (json.load(open(p, encoding="utf-8")) for p in sys.argv[1:3]) +ids = kev.get("vulnerabilities") +if not isinstance(ids, list) or not ids or kev.get("count") != len(ids): + sys.exit("vulnerability-scan: KEV feed is malformed, empty or count-inconsistent") +catalog = {v.get("cveID") for v in ids} +if not all(isinstance(c, str) and re.fullmatch(r"CVE-\d{4}-\d{4,}", c) for c in catalog): + sys.exit("vulnerability-scan: KEV feed holds an invalid cveID") +results = findings.get("Results") +if not isinstance(results, list) or not results: + sys.exit("vulnerability-scan: Trivy found no lockfile to scan") +found = {v["VulnerabilityID"] for r in results for v in (r.get("Vulnerabilities") or [])} +hits = sorted(found & catalog) +if hits: + sys.exit("vulnerability-scan: CISA KEV-listed vulnerability found regardless of severity: " + ", ".join(hits)) +print(f"vulnerability-scan: {len(found)} finding(s) below HIGH, none in the KEV catalog ({len(catalog)} entries).") +PY diff --git a/scripts/tool.sh b/scripts/tool.sh new file mode 100755 index 0000000..314e74c --- /dev/null +++ b/scripts/tool.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash +# Prints the path of a pinned, checksum-verified tool binary, downloading it once into +# ${TOOL_CACHE:-~/.cache/messaging-library}/-/. +# +# scripts/tool.sh trivy +# +# A tool is a native binary, not a Maven artifact, so Gradle cannot resolve it; this is the one place +# that says which version and which bytes. A download whose SHA-256 differs from the one written here +# fails and leaves nothing behind. Exit codes: 0 = path printed, 1 = download or checksum failed, +# 2 = usage or unsupported machine. +set -euo pipefail + +tool=${1:-} +case "$(uname -s)-$(uname -m)" in + Linux-x86_64) arch=amd64 ;; + Linux-aarch64 | Linux-arm64) arch=arm64 ;; + *) echo "tool.sh: unsupported machine $(uname -s)-$(uname -m)" >&2; exit 2 ;; +esac + +case "$tool" in + trivy) + # Trivy 0.71.2, the version and checksums the backend template's dependency-vulnerability.yml pins. + version=0.71.2 + [ "$arch" = amd64 ] && asset="trivy_${version}_Linux-64bit.tar.gz" || asset="trivy_${version}_Linux-ARM64.tar.gz" + [ "$arch" = amd64 ] \ + && sha256=0510e71e2fd39bf863856d499c8dc19feb4e7336546394c502a8f5cc7ab27460 \ + || sha256=fe1c7106e15a5365d485b098a8c338f91e3b7ba71cb0e4963b98a3a098763cfc + url="${TRIVY_DOWNLOAD_BASE_URL:-https://github.com/aquasecurity/trivy/releases/download/v${version}}/${asset}" + archive=1 + ;; + *) echo "usage: scripts/tool.sh trivy" >&2; exit 2 ;; +esac + +dir="${TOOL_CACHE:-$HOME/.cache/messaging-library}/${tool}-${version}" +binary="$dir/$tool" +if [ ! -x "$binary" ]; then + mkdir -p "$dir" + tmp=$(mktemp "$dir/.download.XXXXXX") + trap 'rm -f "$tmp"' EXIT + curl --fail --show-error --silent --location --retry 3 --proto '=https' --tlsv1.2 "$url" --output "$tmp" + if ! printf '%s %s\n' "$sha256" "$tmp" | sha256sum -c - >/dev/null 2>&1; then + echo "tool.sh: $asset does not match the pinned SHA-256 $sha256" >&2 + exit 1 + fi + if [ "$archive" = 1 ]; then + tar -xzf "$tmp" -C "$dir" "$tool" + else + mv "$tmp" "$binary" + fi + chmod 0755 "$binary" +fi +printf '%s\n' "$binary" diff --git a/scripts/verify.sh b/scripts/verify.sh index 3297275..8f41a3d 100755 --- a/scripts/verify.sh +++ b/scripts/verify.sh @@ -3,18 +3,20 @@ # # scripts/verify.sh <단계> [--on here|<호스트>] [--log <이름>] # -# 단계 무엇 채우는 곳 -# docs 루트 지침·장부 검사 run_docs(뼈대에 기본 검사가 있다) -# unit 빠른 단위 시험 run_unit -# pr PR 전에 통과해야 하는 게이트 묶음 run_pr -# app 앱을 띄워 health와 기본 기능을 직접 확인 run_app +# 단계 무엇 Gradle +# docs 루트 지침·장부 검사 (없음) +# unit 모듈 check 전부(단위 시험·정적 분석·lane 포함) checkAll +# pr PR 단계 = pr.yml ci, verifyStrictLaneStages --dry-run +# main main 단계 = main.yml(Docker 필요) mainCheck +# release release.yml에서 올리기 직전까지(Docker 필요, 비밀 값 없이) releaseRehearsal +# 라이브러리라 띄울 앱이 없다. 템플릿 뼈대의 `app` 단계는 두지 않는다. # # --on <호스트>: 지금 작업 트리(커밋 안 된 변경 포함)를 패치로 그 호스트에 옮긴다. 기준 커밋에서 새 worktree를 # 만들어 패치를 적용하고, 트리 해시가 여기와 같은지 본 뒤 잠금 아래에서 같은 단계를 돌리고 worktree를 지운다. # push하지 않는다. 기준 커밋은 원격 checkout이 fetch로 받을 수 있어야 한다(기본: origin/main과 갈라진 곳). # 환경 변수: VERIFY_HOST(--on 기본값, 없으면 here), VERIFY_REMOTE_REPO(원격 checkout, 기본 ~/workspace/), # VERIFY_BASE_REF(기본 origin/main), VERIFY_LOCK(기본 /tmp/claude-gates/heavy.lock), VERIFY_SSH(기본 ssh). -# 종료 코드: 단계의 종료 코드. 2 = 사용법, 3 = 아직 채우지 않은 단계, 4 = 원격 준비 실패. +# 종료 코드: 단계의 종료 코드. 2 = 사용법, 4 = 원격 준비 실패. set -euo pipefail ROOT=$(git rev-parse --show-toplevel) @@ -23,15 +25,10 @@ TMP_FILES=() trap '[ ${#TMP_FILES[@]} -eq 0 ] || rm -f "${TMP_FILES[@]}"' EXIT # 빈 배열 + set -u는 옛 bash에서 오류다 usage() { - sed -n '2,19p' "$0" | sed 's/^# \{0,1\}//' >&2 + sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//' >&2 exit 2 } -todo() { - echo "verify: '$1' 단계는 아직 정하지 않았다. scripts/verify.sh의 run_$1을 채운다." >&2 - return 3 -} - # ---------------------------------------------------------------- 단계 본문(프로젝트가 채운다) run_docs() { @@ -56,17 +53,24 @@ for n, line in enumerate(open(sys.argv[1], encoding="utf-8"), 1): return "$rc" } -run_unit() { todo unit; } +run_unit() { ./gradlew checkAll --console=plain; } -run_pr() { run_docs && run_unit && todo pr; } +run_pr() { run_docs && ./gradlew ci --console=plain && ./gradlew verifyStrictLaneStages --dry-run --console=plain; } -run_app() { todo app; } +run_main() { ./gradlew mainCheck --console=plain; } + +# releaseCheck needs a release version and a commit id. The rehearsal uses 0.0.0 unless +# RELEASE_VERSION is given: a version no release tag (v1.0.0 onward) will ever name. +run_release() { + RELEASE_VERSION=${RELEASE_VERSION:-0.0.0} GIT_SHA=${GIT_SHA:-$(git rev-parse HEAD)} \ + ./gradlew releaseRehearsal --console=plain +} # ---------------------------------------------------------------- 실행 위치 run_here() { case "$1" in - docs | unit | pr | app) "run_$1" ;; + docs | unit | pr | main | release) "run_$1" ;; *) usage ;; esac } diff --git a/settings-gradle.lockfile b/settings-gradle.lockfile new file mode 100644 index 0000000..709a43f --- /dev/null +++ b/settings-gradle.lockfile @@ -0,0 +1,4 @@ +# This is a Gradle generated file for dependency locking. +# Manual edits can break the build and are not advised. +# This file is expected to be part of source control. +empty=incomingCatalogForLibs0 diff --git a/settings.gradle b/settings.gradle new file mode 100644 index 0000000..da0e58e --- /dev/null +++ b/settings.gradle @@ -0,0 +1,20 @@ +// The library's one Gradle build. The repository root is the Gradle root: config/, gradle/ and +// build-logic/ sit next to the module family messaging/. +pluginManagement { + includeBuild('build-logic') +} + +// ca.architecture-registry includes every module config/architecture/modules.json lists, at its +// source_path. A module the registry does not list is not part of the build. +plugins { + id 'ca.architecture-registry' +} + +dependencyResolutionManagement { + repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) + repositories { + mavenCentral() + } +} + +rootProject.name = 'messaging-library'