From 414666cfc78edc04d74028039c56c9ab8c32fa63 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 11:10:21 +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 옮겨 온 gRPC 모듈은 템플릿의 두 번째 빌드(optional build)였다. 그 빌드는 템플릿 build-logic·카탈로그·registry·config를 상대 경로로 읽었고, grpc-operation-ledger-jpa는 템플릿 persistence-jpa의 testFixtures 파일 셋을 빌드 때 복사해 왔다. 별도 repo에는 그 경로가 없다. repo 루트를 Gradle 루트로 둔다. - build-logic: 템플릿 22df3525의 src/build-logic을 복사하고 쓰지 않는 플러그인(bootrun-dotenv, redis topology, config contract, spring-library, optional registry, purity 태스크)을 뺐다. 출처와 고친 곳은 build-logic/UPSTREAM.md에 적었다(설계 10.3절 L1). - registry config/architecture/modules.json: 템플릿의 optional-grpc 9행, source_path는 Gradle 루트 기준. - 카탈로그·config: 이 repo가 쓰는 항목만. SpotBugs 제외는 이 repo 클래스와 일반 규칙만 남겼다. - group은 gradle.properties의 libraryGroup(com.hyeonworks.grpc)에서 읽는다. 버전은 -PreleaseVersion 말고 RELEASE_TAG(vX.Y.Z)에서도 읽고, 다른 모양의 태그는 빌드 전에 거부한다. - 배포: 새 ca.library-publishing이 모듈마다 Maven publication(sources· javadoc jar, versionMapping으로 해석된 버전)과 저장소 gitea·staging, SIGNING_KEY가 있으면 PGP 서명을 단다. 루트는 SBOM artifact grpc-library와 단계 태스크 ci·mainCheck·releaseCheck·release· releaseRehearsal을 가진다. Trivy·Buf는 scripts/tool.sh가 SHA-256으로 고정해 받는다. - testFixtures 결합(설계 4.6절 2번)은 integrationTest 안 사본으로 끊었다. - Buf lint·breaking은 Gradle 태스크(scripts/buf.sh)로 ci에 넣었다. 버린 대안: build-logic을 템플릿이 배포(L2, 순환), 공통 repo(L3, repo가 하나 더), 표준 플러그인만으로 새로 쓰기(L4, strict lane과 방향 검사를 잃음). SBOM은 CycloneDX Gradle 플러그인 대신 이미 고정해 쓰는 Trivy로 만든다(도구를 늘리지 않는다). 위험: strictlane 단계 검사는 included build 태스크를 따라가다 실패해서 그 태스크를 건너뛰게 고쳤다(UPSTREAM.md). Gitea에 실제로 올리는 경로는 비밀 값이 없어 이 커밋에서는 시험하지 못했다. 검증(desktop, 이 트리): ./gradlew ci rc=0, 테스트 739개(build-logic 포함) 중 첫 실행 실패 1개(템플릿 경로를 찾던 GrpcPackageOwnershipTest)를 고친 뒤 통과. ./gradlew verifyStrictLaneStages --dry-run rc=0. Refs: design-docs repo-structure/05-library-repos.md 4.6·7·10절 --- .gitignore | 8 + .trivyignore.yaml | 15 + build-logic/AGENTS.md | 8 + build-logic/CLAUDE.md | 1 + build-logic/UPSTREAM.md | 38 + build-logic/build.gradle | 95 + 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 | 298 +++ .../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 ++ .../GrpcPlatformModuleConventionPlugin.java | 28 + .../JavaLibraryConventionPlugin.java | 13 + .../PlatformModuleConventionPlugin.java | 14 + .../SpringConfigConventionPlugin.java | 44 + .../java/JavaConventionsPlugin.java | 358 ++++ .../java/MockitoAgentArgumentProvider.java | 38 + .../java/ResolveConfigurationsTask.java | 39 + .../publishing/LibraryPublishingPlugin.java | 161 ++ .../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 | 183 ++ .../buildlogic/RequiredTestExecutionTest.java | 39 + .../apisurface/ApiSurfaceConventionTest.java | 199 ++ ...ectureResolvedClasspathFunctionalTest.java | 182 ++ ...NoIgnoredSourcePackagesFunctionalTest.java | 122 ++ .../PlatformModuleConventionTest.java | 197 ++ .../strictlane/GradleCommandLineTest.java | 162 ++ .../StrictLaneStagesFunctionalTest.java | 783 ++++++++ .../StrictTestLaneConventionTest.java | 817 ++++++++ .../strictlane/TaskSelectorsTest.java | 71 + .../WorkflowGradleInvocationsTest.java | 1581 ++++++++++++++++ build.gradle | 268 ++- config/architecture/modules.json | 79 + config/checkstyle/checkstyle-suppressions.xml | 28 + config/checkstyle/checkstyle.xml | 93 + config/spotbugs/exclude-test.xml | 64 + config/spotbugs/exclude.xml | 175 ++ config/testing/container-images.properties | 16 + gradle.properties | 12 +- gradle/libs.versions.toml | 75 + gradle/wrapper/gradle-wrapper.jar | Bin 0 -> 45457 bytes gradle/wrapper/gradle-wrapper.properties | 8 + gradlew | 251 +++ gradlew.bat | 94 + grpc/grpc-contract/buf.yaml | 9 +- grpc/grpc-contract/build.gradle | 26 +- grpc/grpc-operation-ledger-jpa/build.gradle | 34 +- ...rpcOperationLedgerMigrationLockWaitIT.java | 4 +- .../ledger/GrpcOperationLedgerMigrations.java | 2 +- .../ConcurrentIndexMigrationInspector.java | 119 ++ .../ledger/migration/MigrationResource.java | 23 + .../migration/VersionedMigrationFiles.java | 99 + .../testkit/GrpcPackageOwnershipTest.java | 4 +- scripts/buf.sh | 64 + 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 | 62 + settings.gradle | 30 +- 86 files changed, 13472 insertions(+), 117 deletions(-) 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/GrpcPlatformModuleConventionPlugin.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/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/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 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/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 grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/ConcurrentIndexMigrationInspector.java create mode 100644 grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/MigrationResource.java create mode 100644 grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/VersionedMigrationFiles.java create mode 100755 scripts/buf.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 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..045f8d6 --- /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 라이브러리 + 배포) 또는 `ca.grpc-platform-module`(위 + io.grpc BOM)을 쓴다. 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..1dbe611 --- /dev/null +++ b/build-logic/UPSTREAM.md @@ -0,0 +1,38 @@ +# build-logic의 출처 — 백엔드 템플릿에서 복사해 줄였다 + +- 복사한 곳: `clean-architecture-backend-template` main `22df3525`의 `src/build-logic/`(2026-11-08) +- 함께 복사: `src/gradle/libs.versions.toml`(이 repo가 쓰는 항목만), `src/gradle/wrapper/`, `src/gradlew*`, `src/config/checkstyle/`, `src/config/spotbugs/`(이 repo 클래스와 일반 규칙만), `src/config/testing/container-images.properties`(`postgres-16`만) +- 근거: design-docs `repo-structure/05-library-repos.md` 10.3절 L1(복사 후 줄이기). 다시 열 조건: 라이브러리 repo가 셋 이상이 되거나, 6개월 안에 템플릿에서 이 사본으로 옮긴 수정이 3번을 넘으면 공통 빌드 규칙 repo(L3)를 본다. + +## 뺀 것 + +| 무엇 | 이유 | +| --- | --- | +| `ca.bootrun-dotenv`, `ca.redis-topology-lane`, `ca.config-contract`, `ca.spring-library` | 이 repo 모듈이 쓰지 않는다 | +| `ca.optional-architecture-registry`, `MainBuild` | 템플릿 안 두 번째 빌드(optional build)를 위한 것. 여기서는 repo 루트가 곧 Gradle 루트다 | +| `VerifyApplicationCoreDependencyPurityTask`(`ca.architecture` 안) | 템플릿 계층 이름(`domain-core`·`application-*`·`shared-contract`)에만 걸린다 | +| `README.md`, 템플릿 `AGENTS.md` | 템플릿 빌드 설명이다. 이 폴더 `AGENTS.md`로 바꿨다 | +| 위 플러그인의 테스트 | 플러그인과 함께 | + +`ca.api-surface`는 남겼다. 설계 10.1절은 라이브러리 모듈에 켜기를 권하지만, 공개 타입 기준선 파일과 정책은 새 결정이라 아직 어느 모듈에도 켜지 않았다. + +## 고친 것 + +| 파일 | 바뀐 점 | +| --- | --- | +| `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`)는 묻지 않는다. 템플릿 `ci`에는 그런 의존이 없어 드러나지 않았다. 템플릿에도 옮길 만한 수정이다 | +| 새 `publishing/LibraryPublishingPlugin`(`ca.library-publishing`) | 모듈마다 Maven publication(sources·javadoc jar, 해석된 버전), 저장소 `gitea`·`staging`, `SIGNING_KEY`가 있으면 PGP 서명 | +| 테스트 fixture | `source_path`를 Gradle 루트 기준으로, `PlatformModuleConventionTest`에 `libraryGroup` | + +Java 패키지 `dev.caskeleton.buildlogic`은 그대로 두었다. 배포하지 않는 빌드 도구이고, 템플릿 파일과 나란히 비교하기 쉽게 하려는 것이다. + +## 템플릿 수정을 옮기는 법 + +1. 템플릿에서 `git log --oneline 22df3525..main -- src/build-logic`으로 이후 변경을 본다. +2. 위 「뺀 것」에 해당하지 않는 변경만 같은 파일에 옮긴다. 옮긴 커밋은 본문에 템플릿 커밋 SHA를 적는다. +3. 옮긴 뒤 이 파일의 「복사한 곳」 커밋을 그 템플릿 커밋으로 바꾸고, 옮긴 횟수를 세어 다시 열 조건과 비교한다. diff --git a/build-logic/build.gradle b/build-logic/build.gradle new file mode 100644 index 0000000..4f46fbd --- /dev/null +++ b/build-logic/build.gradle @@ -0,0 +1,95 @@ +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' + } + grpcPlatformModuleConvention { + id = 'ca.grpc-platform-module' + implementationClass = 'dev.caskeleton.buildlogic.convention.GrpcPlatformModuleConventionPlugin' + } + } +} + +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..a917abb --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/ModuleRegistry.java @@ -0,0 +1,298 @@ +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); + String buildName = module.has("build") ? requireNonBlankText(module, "build", id) : "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/GrpcPlatformModuleConventionPlugin.java b/build-logic/src/main/java/dev/caskeleton/buildlogic/convention/GrpcPlatformModuleConventionPlugin.java new file mode 100644 index 0000000..145058c --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/convention/GrpcPlatformModuleConventionPlugin.java @@ -0,0 +1,28 @@ +package dev.caskeleton.buildlogic.convention; + +import io.spring.gradle.dependencymanagement.dsl.DependencyManagementExtension; +import org.gradle.api.GradleException; +import org.gradle.api.Plugin; +import org.gradle.api.Project; +import org.gradle.api.artifacts.VersionCatalogsExtension; + +public final class GrpcPlatformModuleConventionPlugin implements Plugin { + @Override + public void apply(Project project) { + project.getPluginManager().apply("ca.platform-module"); + + var catalogs = project.getExtensions().getByType(VersionCatalogsExtension.class); + var grpc = + catalogs + .named("libs") + .findVersion("grpc") + .orElseThrow( + () -> + new GradleException( + "Version catalog 'libs' must define version 'grpc' for ca.grpc-platform-module")); + String grpcVersion = grpc.getRequiredVersion(); + DependencyManagementExtension dependencyManagement = + project.getExtensions().getByType(DependencyManagementExtension.class); + dependencyManagement.imports(imports -> imports.mavenBom("io.grpc:grpc-bom:" + grpcVersion)); + } +} 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..5789685 --- /dev/null +++ b/build-logic/src/main/java/dev/caskeleton/buildlogic/publishing/LibraryPublishingPlugin.java @@ -0,0 +1,161 @@ +package dev.caskeleton.buildlogic.publishing; + +import io.spring.gradle.dependencymanagement.dsl.DependencyManagementExtension; +import org.gradle.api.GradleException; +import org.gradle.api.Plugin; +import org.gradle.api.Project; +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.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) 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)); + + Provider packagesUrl = project.getProviders().gradleProperty("packagesUrl"); + Provider repositoryUrl = project.getProviders().gradleProperty("repositoryUrl"); + Provider token = project.getProviders().environmentVariable("PACKAGES_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 = 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); + } + + // 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( + "PACKAGES_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/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..a91b360 --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/ModuleRegistryTest.java @@ -0,0 +1,183 @@ +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 buildOwnershipDefaultsToMainAndCanSelectOptionalModules() throws Exception { + 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"} + """); + ModuleRegistry parsed = read(json); + assertEquals("main", parsed.byId("app-bootstrap").buildName()); + assertEquals("optional-grpc", parsed.byId("grpc-client").buildName()); + assertEquals(List.of("app-bootstrap"), parsed.modulesForBuild("main").stream().map(ModuleRegistry.Module::id).toList()); + assertEquals(List.of("grpc-client"), parsed.modulesForBuild("optional-grpc").stream().map(ModuleRegistry.Module::id).toList()); + } + + @Test + void blankBuildOwnershipIsRefused() { + 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("nonblank string 'build'"), 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..7675cc8 --- /dev/null +++ b/build-logic/src/test/java/dev/caskeleton/buildlogic/convention/PlatformModuleConventionTest.java @@ -0,0 +1,197 @@ +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(true); + // 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 grpcConventionImportsBom() throws Exception { + buildFile( + """ + plugins { id 'ca.grpc-platform-module' } + tasks.register('reportManagedVersion') { + String managed = dependencyManagement.managedVersions['io.grpc:grpc-api'] + doLast { logger.lifecycle('managed-grpc-api=' + managed) } + } + """); + BuildResult result = runner("reportManagedVersion").build(); + assertTrue(result.getOutput().contains("managed-grpc-api=1.68.1"), result.getOutput()); + } + + @Test + void grpcConventionRefusesMissingVersion() throws Exception { + writeCatalog(false); + buildFile("plugins { id 'ca.grpc-platform-module' }\n"); + BuildResult result = runner("tasks").buildAndFail(); + assertTrue( + result.getOutput().contains("Version catalog 'libs' must define version 'grpc'"), + result.getOutput()); + } + + @Test + void grpcConventionBringsDependencyManagement() throws Exception { + buildFile( + """ + plugins { id 'ca.grpc-platform-module' } + tasks.register('reportDependencyManagement') { + boolean present = project.extensions.findByName('dependencyManagement') != null + doLast { logger.lifecycle('dependency-management-present=' + present) } + } + """); + BuildResult result = runner("reportDependencyManagement").build(); + assertTrue(result.getOutput().contains("dependency-management-present=true"), 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(boolean grpc) 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" + %s + + [libraries] + pinned-fixture = { module = "org.example:pinned-fixture", version = "2.0.1" } + unpinned-fixture = { module = "org.example:unpinned-fixture", version = "1.0.0" } + """.formatted(grpc ? "grpc = \"1.68.1\"" : "")); + } + + 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/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 index 9a2eb59..ffcc373 100644 --- a/build.gradle +++ b/build.gradle @@ -1,92 +1,264 @@ +import dev.caskeleton.buildlogic.java.JavaConventionsPlugin + plugins { id 'ca.architecture' - // Every strict lane of this build belongs to a stage a workflow executes, checked here exactly - // as in the main build: the main build's check cannot see this build's lanes, and while only it - // applied the plugin, grpcPerformanceTest ran nowhere (review 2026-11-03 RR-06-03). + // 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, `grpc-library`, next to the modules. + id 'maven-publish' + id 'signing' } -// No `ca.release-provenance` any more: each gRPC leaf's `ca.java-conventions` derives its version -// and `sourceRevision` from the same -PreleaseVersion/-PgitRevision (GIT_SHA, GITHUB_SHA) inputs the -// main build reads, so one commit produces one version scheme in both builds (review BUILD-O3-5). +// The modules: every leaf the registry includes (settings.gradle). The family projects `:grpc` and +// `:grpc-advanced` are folders, not modules. +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' : '') tasks.register('resolveAndLockAll') { group = 'build setup' - description = 'Regenerates dependency locks for every optional gRPC leaf (requires --write-locks).' - dependsOn subprojects.findAll { it.childProjects.isEmpty() }.collect { "${it.path}:resolveAndLockAll" } + 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 gRPC optional-platform leaf check.' - dependsOn subprojects.findAll { it.childProjects.isEmpty() }.collect { "${it.path}:check" } + description = 'Runs every module check.' + dependsOn leafPaths.collect { "${it}:check" } } tasks.register('qualityCheck') { group = 'verification' - description = 'Runs production-bytecode static analysis for every optional-platform leaf.' - dependsOn subprojects.findAll { it.childProjects.isEmpty() }.collect { "${it.path}:qualityCheck" } + 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). This build has -// no main stage, and the run is short (eleven tasks), so it joins `ci`. +// SpotBugs + FindSecBugs over the test source sets (config/spotbugs/exclude-test.xml). Short here +// (nine modules), so it joins `ci`. tasks.register('testQualityCheck') { group = 'verification' - description = 'Runs test-code static analysis for every optional-platform leaf.' - dependsOn subprojects.findAll { it.childProjects.isEmpty() }.collect { "${it.path}:testQualityCheck" } + 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). Buf lint and breaking-change policy run here rather than in each +// module's `check`: Buf is a downloaded binary and the breaking check reads Git history, which a +// local `./gradlew :grpc:grpc-contract:check` should not need. tasks.register('ci') { group = 'verification' - description = 'Runs the optional gRPC platform verification surface.' + description = 'The pull-request stage: module checks, architecture, static analysis, locks, Buf and build-logic tests.' dependsOn tasks.named('checkAll') dependsOn tasks.named('qualityCheck') dependsOn tasks.named('testQualityCheck') - // architectureCheck, not only the direction gate: it also runs verifyNoIgnoredSourcePackages, so - // a gRPC source Git would drop fails this build's ci the way it fails the main build's. + dependsOn tasks.named('verifyDependencyLocks') + // architectureCheck, not only the direction gate: it also runs verifyNoIgnoredSourcePackages. dependsOn tasks.named('architectureCheck') + dependsOn ':grpc:grpc-contract:bufLint', ':grpc:grpc-contract:bufBreaking' + dependsOn tasks.named('buildLogicTest') } -// A strict integration lane that no workflow invokes is not coverage; it is a file that looks like -// coverage. `grpc-operation-ledger-jpa` declares a Testcontainers PostgreSQL lane that certifies the -// atomic `INSERT ... ON CONFLICT DO NOTHING` claim the whole durable-idempotency contract rests on, -// and until this aggregate existed `ci` reached `checkAll`, `qualityCheck` and the dependency -// verifier only — none of which runs a lane whose category is INTEGRATION. -// -// Kept out of `ci`: every lane here starts a container, and `ci` is the per-PR gate for this build. -// The caller is integration-main.yml, the stage that owns container-backed lanes. +// Every module's integration lanes: grpc-operation-ledger-jpa's Testcontainers PostgreSQL lane, which +// certifies the atomic `INSERT ... ON CONFLICT DO NOTHING` claim durable idempotency rests on. Needs a +// container runtime. tasks.register('integrationCheck') { group = 'verification' - description = 'Runs every optional-platform leaf integration test lane. Needs a container runtime.' - dependsOn subprojects.findAll { it.childProjects.isEmpty() }.collect { "${it.path}:integrationTestLaneCheck" } + description = 'Runs every module integration test lane. Needs a container runtime.' + dependsOn leafPaths.collect { "${it}:integrationTestLaneCheck" } } -// The performance stage of this build: grpcPerformanceTest. It asserts the shape of a measurement -// (ordered percentiles, a gate that reads them) with a generous budget, not a number, so it can run -// on a shared runner. integration-main.yml's performance-check job runs it next to the main build's -// `:performanceCheck`; before this aggregate it ran when somebody asked for it by name, which was -// nobody (review 2026-11-03 RR-06-03). +// grpcPerformanceTest asserts the shape of a measurement (ordered percentiles, a gate that reads +// them) with a generous budget, not a number, so it can run on a shared runner. tasks.register('performanceCheck') { group = 'verification' - description = 'Runs every optional-platform leaf performance test lane.' - dependsOn subprojects.findAll { it.childProjects.isEmpty() }.collect { "${it.path}:performanceTestLaneCheck" } + description = 'Runs every module performance test lane.' + dependsOn leafPaths.collect { "${it}:performanceTestLaneCheck" } } -// The tag-only stage of this build: the hermetic strict lanes (the three gRPC certification lanes). -// Their tests already run inside each leaf's `test`; the lanes add the one thing `test` cannot say — -// that a tag still selects something — which is worth asserting once per release tag. release.yml -// runs this aggregate instead of naming the lanes, so a lane added here is in the release gate -// without a workflow edit. +// The main-branch stage (main.yml): the pull-request stage again on the merged commit, plus the lanes +// that start containers or measure. +tasks.register('mainCheck') { + group = 'verification' + description = 'The main-branch stage: ci, integrationCheck and performanceCheck.' + dependsOn tasks.named('ci') + dependsOn tasks.named('integrationCheck') + dependsOn tasks.named('performanceCheck') +} + +// ---------------------------------------------------------------- release (release.yml) + +def sbomFile = layout.buildDirectory.file("release/grpc-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 = version.toString() + 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 certification lanes of every module (their tests already run in +// `test`; a lane adds that its tag still selects something), the integration lanes, the version +// check, the SBOM and the dependency gate. grpcPerformanceTest is not release evidence on a shared +// runner and stays in mainCheck. tasks.register('releaseCheck') { group = 'verification' - description = 'Runs every optional-platform leaf hermetic strict test lane (the release gate).' - dependsOn subprojects.findAll { it.childProjects.isEmpty() }.collect { "${it.path}:testLaneCheck" } + description = 'The release stage before publishing: certification and integration lanes, version, SBOM, dependency gate.' + dependsOn tasks.named('verifyReleaseVersion') + dependsOn leafPaths.collect { "${it}:testLaneCheck" } + dependsOn tasks.named('integrationCheck') + dependsOn tasks.named('releaseSbom') + dependsOn tasks.named('dependencyVulnerabilityScan') } -// The stages this build's strict lanes may belong to, executed by workflows as -// `./gradlew -p platforms/optional-build ` from `src`. A command counts when it starts in this -// directory (working-directory joined with -p), which the plugin reads from where this build is. +publishing { + publications { + sbom(MavenPublication) { + artifactId = 'grpc-library' + artifact(sbomFile) { + classifier = 'cyclonedx' + extension = 'json' + builtBy tasks.named('releaseSbom') + } + pom { + name = 'grpc-library' + description = 'CycloneDX SBOM of the grpc-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('PACKAGES_TOKEN').getOrElse('')}" + } + authentication { + header(HttpHeaderAuthentication) + } + } + maven { + name = 'staging' + url = layout.buildDirectory.dir('staging-repository') + } + } +} + +def signingKey = providers.environmentVariable('SIGNING_KEY').getOrElse('') +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('PACKAGES_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('PACKAGES_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') + dependsOn(([path] + leafPaths).collect { "${it == ':' ? '' : it}:publishAllPublicationsToStagingRepository" }) + def staging = layout.buildDirectory.dir('staging-repository') + def artifacts = leaves.collect { it.name } + def coordinates = [group.toString(), version.toString()] + 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(([path] + leafPaths).collect { "${it == ':' ? '' : it}:publishAllPublicationsToGiteaRepository" }) + def url = providers.gradleProperty('packagesUrl') + def artifacts = leaves.collect { it.name } + ['grpc-library'] + def coordinates = [group.toString(), version.toString()] + 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', ':integrationCheck', ':performanceCheck', ':releaseCheck' - workflowDirectory = layout.projectDirectory.dir('../../../.github/workflows') + 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..d3e1a37 --- /dev/null +++ b/config/architecture/modules.json @@ -0,0 +1,79 @@ +{ + "modules": [ + { + "id": "grpc-contract", + "gradle_path": ":grpc:grpc-contract", + "source_path": "grpc/grpc-contract", + "allowed_dependencies": [] + }, + { + "id": "grpc-core-api", + "gradle_path": ":grpc:grpc-core-api", + "source_path": "grpc/grpc-core-api", + "allowed_dependencies": [] + }, + { + "id": "grpc-observability", + "gradle_path": ":grpc:grpc-observability", + "source_path": "grpc/grpc-observability", + "allowed_dependencies": [ + "grpc-core-api" + ] + }, + { + "id": "grpc-operation-ledger-jpa", + "gradle_path": ":grpc:grpc-operation-ledger-jpa", + "source_path": "grpc/grpc-operation-ledger-jpa", + "allowed_dependencies": [ + "grpc-core-api" + ] + }, + { + "id": "grpc-runtime", + "gradle_path": ":grpc:grpc-runtime", + "source_path": "grpc/grpc-runtime", + "allowed_dependencies": [ + "grpc-core-api" + ] + }, + { + "id": "grpc-spring-boot-starter", + "gradle_path": ":grpc:grpc-spring-boot-starter", + "source_path": "grpc/grpc-spring-boot-starter", + "allowed_dependencies": [ + "grpc-core-api", + "grpc-runtime", + "grpc-observability" + ] + }, + { + "id": "grpc-testkit", + "gradle_path": ":grpc:grpc-testkit", + "source_path": "grpc/grpc-testkit", + "allowed_dependencies": [ + "grpc-core-api", + "grpc-runtime", + "grpc-observability", + "grpc-operation-ledger-jpa" + ] + }, + { + "id": "grpc-advanced", + "gradle_path": ":grpc-advanced:grpc-advanced", + "source_path": "grpc-advanced/grpc-advanced", + "allowed_dependencies": [ + "grpc-core-api", + "grpc-runtime" + ] + }, + { + "id": "grpc-advanced-compat", + "gradle_path": ":grpc-advanced:grpc-advanced-compat", + "source_path": "grpc-advanced/grpc-advanced-compat", + "allowed_dependencies": [ + "grpc-core-api", + "grpc-runtime" + ] + } + ] +} 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..ec64026 --- /dev/null +++ b/config/spotbugs/exclude-test.xml @@ -0,0 +1,64 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/config/spotbugs/exclude.xml b/config/spotbugs/exclude.xml new file mode 100644 index 0000000..5b2f535 --- /dev/null +++ b/config/spotbugs/exclude.xml @@ -0,0 +1,175 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/config/testing/container-images.properties b/config/testing/container-images.properties new file mode 100644 index 0000000..b53b2f4 --- /dev/null +++ b/config/testing/container-images.properties @@ -0,0 +1,16 @@ +# 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. 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. +# +# Pulling through a mirror: set TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX in the environment, for example +# `registry.internal/dockerhub/`. + +# postgres:16-alpine — grpc-operation-ledger-jpa's integrationTest lane. +postgres-16=postgres@sha256:0cefaabd882e42bcb2a2f3dc56d3ce4770560ba62fd7f197f1a2e008fd5731ab diff --git a/gradle.properties b/gradle.properties index cabb814..7a0f866 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,8 +1,10 @@ -# optional-platforms is a build of its own (`./gradlew -p platforms/optional-build ...`), and Gradle reads -# gradle.properties from the build's root directory only, so src/gradle.properties never reached it: -# the optional build ran serially and without the build cache (review 2026-11-01 08-06). -# The values and their reasons are src/gradle.properties'. settings.gradle fails the build when the -# two files disagree, so this is a copy that cannot drift, not a second source. +# 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=com.hyeonworks.grpc +packagesUrl=https://git.learn.hyeonworks.com/api/packages/donghyeon.kang/maven +repositoryUrl=https://git.learn.hyeonworks.com/donghyeon.kang/grpc-library + +# 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 diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml new file mode 100644 index 0000000..a2386ae --- /dev/null +++ b/gradle/libs.versions.toml @@ -0,0 +1,75 @@ +# 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, io.grpc) are not here; `grpc` below is the version of the BOM itself. `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" +# 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" +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 gRPC (33.2.1), Error +# Prone (33.5.0) and the Checkstyle tool (33.6.0). +guava = "33.7.2-jre" +# io.grpc BOM. ca.grpc-platform-module imports it in the modules that apply that convention. +grpc = "1.75.0" +# 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" +junitJupiter = "5.11.3" +junitPlatform = "1.11.3" +# 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" +# protobuf-java for grpc:grpc-contract's generated messages. Keep it at the protobuf-java that +# grpc-protobuf of the gRPC BOM above declares, so the schema runs on the runtime gRPC was built +# against. +protobufGrpc = "3.25.8" +# The Gradle plugin that runs protoc for grpc:grpc-contract. protoc and the protobuf-java runtime +# the generated code links against are both `protobufGrpc` above, so generator and runtime move +# together with the gRPC BOM. +protobufPlugin = "0.10.0" +# 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" + +[libraries] +assertj-core = { module = "org.assertj:assertj-core", version.ref = "assertj" } +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-grpc = { module = "com.google.protobuf:protobuf-java", version.ref = "protobufGrpc" } +protoc = { module = "com.google.protobuf:protoc", version.ref = "protobufGrpc" } + +pinned-guava = { module = "com.google.guava:guava", version.ref = "guava" } +pinned-plexus-utils = { module = "org.codehaus.plexus:plexus-utils", version.ref = "plexusUtils" } + +[plugins] +protobuf = { id = "com.google.protobuf", version.ref = "protobufPlugin" } 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/grpc/grpc-contract/buf.yaml b/grpc/grpc-contract/buf.yaml index d81d5f1..1a17321 100644 --- a/grpc/grpc-contract/buf.yaml +++ b/grpc/grpc-contract/buf.yaml @@ -1,12 +1,11 @@ # Buf module configuration for the Stable gRPC schema. # # Buf owns lint and breaking-change policy for src/main/proto; protoc (the Gradle protobuf plugin in -# build.gradle) owns compilation. CI runs both `buf lint` and `buf breaking` from this directory — -# see the `grpc-proto-buf` job in .github/workflows/ci-quality-gates.yml. +# build.gradle) owns compilation. The root `ci` stage runs `buf lint` and `buf breaking` through +# scripts/buf.sh: # -# cd src/platforms/grpc/grpc-contract -# buf lint -# buf breaking --against '#subdir=src/platforms/grpc/grpc-contract' +# scripts/buf.sh lint (from the repository root; :grpc:grpc-contract:bufLint) +# scripts/buf.sh breaking (:grpc:grpc-contract:bufBreaking) # # No dependencies: the only imports are protoc's own well-known types (google/protobuf/*.proto). version: v2 diff --git a/grpc/grpc-contract/build.gradle b/grpc/grpc-contract/build.gradle index 8e93d9a..5e0fbe9 100644 --- a/grpc/grpc-contract/build.gradle +++ b/grpc/grpc-contract/build.gradle @@ -7,10 +7,12 @@ plugins { // from them. // // protoc, not a hand-written parser, decides whether the schema is valid, and Buf (buf.yaml next to -// this file) owns lint and breaking-change policy. Buf runs in CI — `.github/workflows/ -// ci-quality-gates.yml` job `grpc-proto-buf` — because it is a native binary and not a Maven -// artifact; this build does not re-implement its rules. Until 2026-09-28 this leaf was -// grpc-proto-contract + grpc-codegen, which did both with regular expressions (owner decision 18). +// this file) owns lint and breaking-change policy. Buf is a native binary and not a Maven +// artifact, so bufLint and bufBreaking below run scripts/buf.sh (a pinned, checksum-verified +// binary), and the root `ci` stage depends on them rather than this module's `check`: the breaking +// check reads Git history and a download, which a local module check should not need. This build +// does not re-implement Buf's rules. Until 2026-09-28 this leaf was grpc-proto-contract + +// grpc-codegen, which did both with regular expressions (owner decision 18). // // Generated code lands under build/, in the package each file's `java_package` names // (`caskeleton.*.generated`), which is disjoint from the hand-written `dev.caskeleton` root. @@ -45,3 +47,19 @@ tasks.named('checkstyleMain') { tasks.withType(JavaCompile).configureEach { options.errorprone.excludedPaths = '.*/build/generated/.*' } + +def protoSources = fileTree('src/main/proto') + files('buf.yaml') +tasks.register('bufLint', Exec) { + group = 'verification' + description = 'Runs buf lint over the Stable schema (buf.yaml).' + inputs.files(protoSources) + outputs.upToDateWhen { false } + commandLine 'bash', rootProject.file('scripts/buf.sh'), 'lint' +} +tasks.register('bufBreaking', Exec) { + group = 'verification' + description = 'Refuses a breaking change to the Stable schema against the baseline commit (scripts/buf.sh).' + inputs.files(protoSources) + outputs.upToDateWhen { false } + commandLine 'bash', rootProject.file('scripts/buf.sh'), 'breaking' +} diff --git a/grpc/grpc-operation-ledger-jpa/build.gradle b/grpc/grpc-operation-ledger-jpa/build.gradle index 6a83f77..731426d 100644 --- a/grpc/grpc-operation-ledger-jpa/build.gradle +++ b/grpc/grpc-operation-ledger-jpa/build.gradle @@ -16,33 +16,13 @@ configurations { integrationTestRuntimeOnly.extendsFrom testRuntimeOnly } -// One definition of a versioned migration file and of Flyway's order for both builds (re-review -// README 12, r6-b; r9), and one concurrent index check (round 7, RR7-03-01). This build cannot -// depend on persistence-jpa's testkit, so the files the ledger lanes need from it, all JDK only — -// VersionedMigrationFiles, and ConcurrentIndexMigrationInspector with the MigrationResource it -// takes — are copied from there into this lane's sources at build time instead of being kept here -// as second copies that could drift. -// Rejected: that testkit directory as a source root of this lane (Spotless refuses a target outside -// this project's directory, and the include filter would cover this lane's own sources too), a -// dependency on the main build (it would pull the whole main build into this one), and a test that -// compares two copies (two definitions stay, and the test would have to parse Java source text). -def sharedMigrationFileSources = tasks.register('sharedMigrationFileSources', Sync) { - from(file('../../../adapter/outbound/persistence-jpa/src/testFixtures/java')) { - include 'dev/caskeleton/adapter/outbound/persistence/testkit/migration/VersionedMigrationFiles.java' - include 'dev/caskeleton/adapter/outbound/persistence/testkit/migration/ConcurrentIndexMigrationInspector.java' - include 'dev/caskeleton/adapter/outbound/persistence/testkit/migration/MigrationResource.java' - } - into(layout.buildDirectory.dir('generated/sources/sharedMigrationFiles/java')) -} -sourceSets.integrationTest.java.srcDir(sharedMigrationFileSources) -// The copy is not this build's to format: Spotless here would name the generated file, and its -// spotlessApply would rewrite only that copy, which the next Sync puts back (re-review 2026-11-03 -// round 6, RR6-03-04). The main build's persistence-jpa spotlessCheck formats the original. -spotless { - java { - targetExclude('build/generated/sources/sharedMigrationFiles/**') - } -} +// The ledger lanes need three JDK-only migration helpers that the backend template keeps in +// adapter:outbound:persistence-jpa's testFixtures: VersionedMigrationFiles (Flyway's order of +// versioned files), ConcurrentIndexMigrationInspector and the MigrationResource it takes. They live +// here as copies in src/integrationTest/java/.../ledger/migration, an edge-less copy like the digest +// helpers in grpc-runtime: this repository cannot depend on the template, and until the split the +// build copied them in from the template's source tree by path, which a separate repository has +// no path to. The template's files are the original; a fix there is copied here by hand. // Durable mutation idempotency: the operation ledger entity, its state machine, the vendor-neutral // repository port and the Spring Data JPA binding, plus the migration that owns the unique diff --git a/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java index 9ff4829..2de6ced 100644 --- a/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java +++ b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java @@ -4,8 +4,8 @@ import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.catchThrowable; import static org.junit.jupiter.params.provider.Arguments.arguments; -import dev.caskeleton.adapter.outbound.persistence.testkit.migration.ConcurrentIndexMigrationInspector; -import dev.caskeleton.adapter.outbound.persistence.testkit.migration.MigrationResource; +import dev.caskeleton.grpc.ledger.migration.ConcurrentIndexMigrationInspector; +import dev.caskeleton.grpc.ledger.migration.MigrationResource; import java.io.IOException; import java.sql.Connection; import java.sql.ResultSet; diff --git a/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrations.java b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrations.java index c237e17..76113e1 100644 --- a/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrations.java +++ b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrations.java @@ -1,6 +1,6 @@ package dev.caskeleton.grpc.ledger; -import dev.caskeleton.adapter.outbound.persistence.testkit.migration.VersionedMigrationFiles; +import dev.caskeleton.grpc.ledger.migration.VersionedMigrationFiles; import java.io.IOException; import java.io.InputStream; import java.io.Reader; diff --git a/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/ConcurrentIndexMigrationInspector.java b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/ConcurrentIndexMigrationInspector.java new file mode 100644 index 0000000..3e43ce0 --- /dev/null +++ b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/ConcurrentIndexMigrationInspector.java @@ -0,0 +1,119 @@ +package dev.caskeleton.grpc.ledger.migration; + +import java.util.Locale; +import java.util.Objects; +import java.util.regex.Pattern; + +/** + * Requires a concurrent index statement to say that it runs outside a transaction, and to be alone + * in its migration (design §32; {@code docs/jpa/migration-guide.md}, "Concurrent index builds"). + * + *

PostgreSQL refuses {@code CREATE INDEX CONCURRENTLY}, {@code DROP INDEX CONCURRENTLY} and + * {@code REINDEX ... CONCURRENTLY} inside a transaction block. Flyway 11 runs a script outside its + * transaction on its own when it holds {@code CREATE} or {@code DROP INDEX CONCURRENTLY}, or {@code + * REINDEX SCHEMA|DATABASE} with or without {@code CONCURRENTLY}. It runs {@code REINDEX INDEX|TABLE + * ... CONCURRENTLY} — the option-list form {@code REINDEX (CONCURRENTLY) TABLE} included — in the + * transaction, and PostgreSQL refuses it at deploy ({@code + * postgresqlMigrationLockWaitIntegrationTest} shows the five forms; re-review 2026-11-03 round 7, + * RR7-03-02). So {@link #validate} wants {@code executeInTransaction=false} beside every concurrent + * statement, whether Flyway would detect it or not. + * + *

{@link #requireIsolatedStatement} wants the statement alone in its migration. Next to another + * statement it is refused by Flyway before any of the script runs when nothing configures the file + * (Flyway's default {@code mixed=false}); with the {@code executeInTransaction=false} that {@link + * #validate} asks for, Flyway runs and commits each statement on its own, and a failed build leaves + * the statements before it applied (round 7, RR7-03-04). Alone, a failed statement leaves an + * invalid index and its version's failed history row, which Flyway refuses the next deploy over + * until the row is gone: {@code docs/runbooks/migration-failed.md} ("Recover a failed concurrent + * index migration") deletes that one row, after dropping the index a failed build or rebuild left. + * A failed {@code DROP INDEX CONCURRENTLY} leaves invalid the index it was dropping, and the deploy + * after the row is gone drops it ({@code postgresqlConcurrentIndexMigrationIntegrationTest} runs + * all three; round 7, RR7-03-03; round 8, RR8-03-01). + * + *

Outside a transaction, {@code CREATE INDEX CONCURRENTLY} and {@code REINDEX ... CONCURRENTLY} + * still wait for every transaction older than themselves. They finish because the template's Flyway + * holds its PostgreSQL lock for the session ({@code FlywaySchemaPolicy.configure()}): under + * Flyway's default the lock's own open transaction is one of those, and the deploy never ends + * (re-review 2026-11-03 round 6, RR6-03-01 and RR6-03-05). + * + *

The gRPC ledger's lane uses it too. It lives in the optional build, which cannot depend on + * this testkit, so {@code grpc-operation-ledger-jpa} compiles this file and {@link + * MigrationResource} from here into its integration-test sources at build time (its {@code + * build.gradle}, {@code sharedMigrationFileSources}; round 7, RR7-03-01). Hence the rule for both + * files: the JDK only, nothing else from this testkit. + */ +public final class ConcurrentIndexMigrationInspector { + + /** + * A concurrent index statement in any spelling PostgreSQL accepts: {@code UNIQUE}, any + * whitespace, and {@code CONCURRENTLY} after the object kind or, for {@code REINDEX}, in its + * option list ({@code (CONCURRENTLY)}, {@code (VERBOSE, CONCURRENTLY true)}; not {@code + * (CONCURRENTLY false)}). + */ + private static final Pattern CONCURRENT_STATEMENT = + Pattern.compile( + "\\b(?:create\\s+(?:unique\\s+)?index|drop\\s+index" + + "|reindex\\s*(?:\\([^)]*\\)\\s*)?(?:index|table|schema|database|system))" + + "\\s+concurrently\\b" + + "|\\breindex\\s*\\((?=[^)]*\\bconcurrently\\b(?!\\s*(?:false|off|0)\\b))"); + + /** + * Fails when a migration containing a concurrent index statement is transactional. + * + * @param executeInTransaction whether Flyway will wrap this migration in a transaction + * @throws IllegalStateException naming the migration and the required marker + */ + public void validate(MigrationResource migration, boolean executeInTransaction) { + Objects.requireNonNull(migration, "migration"); + if (!executeInTransaction || !containsConcurrentIndexStatement(migration.sql())) { + return; + } + throw new IllegalStateException( + migration.name() + + " must set executeInTransaction=false: PostgreSQL refuses a concurrent index" + + " statement inside a transaction block, and Flyway runs REINDEX INDEX|TABLE ..." + + " CONCURRENTLY in one unless the migration says otherwise"); + } + + /** Whether the script contains a statement PostgreSQL forbids inside a transaction. */ + public boolean containsConcurrentIndexStatement(String sql) { + if (sql == null) { + return false; + } + return CONCURRENT_STATEMENT.matcher(sql.toLowerCase(Locale.ROOT)).find(); + } + + /** + * Fails when a concurrent-index migration also contains other statements. + * + *

A concurrent index statement can fail and leave an invalid index and its version's failed + * history row behind. When the migration did nothing else, recovering is the runbook's few + * statements: drop the index a failed build left, delete that one failed row, deploy again + * ({@code docs/runbooks/migration-failed.md}, "Recover a failed concurrent index migration"). + * When it did more, Flyway ran the file outside a transaction and has committed the statements + * before the failed one, and that partial state has to be reconstructed by hand. + */ + public void requireIsolatedStatement(MigrationResource migration) { + Objects.requireNonNull(migration, "migration"); + if (!containsConcurrentIndexStatement(migration.sql())) { + return; + } + long statements = + migration + .sql() + .lines() + .map(line -> line.trim()) + .filter(line -> !line.isEmpty() && !line.startsWith("--")) + .filter(line -> line.endsWith(";")) + .count(); + if (statements > 1L) { + throw new IllegalStateException( + migration.name() + + " mixes a concurrent index statement with other statements; outside a" + + " transaction Flyway commits each of them on its own, so a failed build leaves the" + + " others applied. Alone, a failed statement is recovered by deleting its version's" + + " failed history row (docs/runbooks/migration-failed.md, \"Recover a failed" + + " concurrent index migration\")"); + } + } +} diff --git a/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/MigrationResource.java b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/MigrationResource.java new file mode 100644 index 0000000..50fbba0 --- /dev/null +++ b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/MigrationResource.java @@ -0,0 +1,23 @@ +package dev.caskeleton.grpc.ledger.migration; + +import java.util.Objects; + +/** + * One migration script as the inspector sees it (design §32). + * + *

The gRPC ledger's lane in the optional build compiles this file with {@link + * ConcurrentIndexMigrationInspector} (see there), so it keeps to the JDK only. + * + * @param name the versioned script name, e.g. {@code V42__order_index.sql} + * @param sql the script body + */ +public record MigrationResource(String name, String sql) { + + public MigrationResource { + Objects.requireNonNull(name, "name"); + Objects.requireNonNull(sql, "sql"); + if (name.isBlank()) { + throw new IllegalArgumentException("migration name must not be blank"); + } + } +} diff --git a/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/VersionedMigrationFiles.java b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/VersionedMigrationFiles.java new file mode 100644 index 0000000..9d86479 --- /dev/null +++ b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/migration/VersionedMigrationFiles.java @@ -0,0 +1,99 @@ +package dev.caskeleton.grpc.ledger.migration; + +import java.io.IOException; +import java.math.BigInteger; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Objects; +import java.util.SortedMap; +import java.util.TreeMap; +import java.util.regex.Pattern; +import java.util.stream.Stream; + +/** + * The versioned migrations of one tree, found the way Flyway finds them: {@code V}, a version whose + * parts are separated by {@code _} or {@code .} ({@code V22}, {@code V22_1}, {@code V22.1}), two + * underscores, a description, {@code .sql}. Repeatable ({@code R__}) and undo ({@code U}) scripts + * and {@code .sql.conf} files are not versioned migrations. + * + *

One definition for every check that walks a tree — the operating trees' lock-wait and checksum + * checks and the sample stream's. Two copies had drifted: the operating trees' skipped {@code + * V22_1__} while the sample's counted it, so a decimal version in an operating tree was neither + * pinned nor held to the lock-wait rule (re-review 2026-11-03 round 3, RR3-02-03). + * + *

The gRPC ledger's lanes use it too. They live in the optional build, which cannot depend on + * this testkit, so {@code grpc-operation-ledger-jpa} compiles this one file from here into its + * integration-test sources at build time (its {@code build.gradle}, {@code + * sharedMigrationFileSources}) instead of keeping a copy that could drift (re-review README 12, + * r6-b; r9). Hence the rule for this file: the JDK only, nothing else from this testkit. + */ +public final class VersionedMigrationFiles { + + private static final Pattern VERSIONED = Pattern.compile("V\\d+(?:[._]\\d+)*__.+\\.sql"); + + private VersionedMigrationFiles() {} + + /** + * Every versioned migration below {@code root}, keyed by its path relative to {@code root} with + * {@code /} separators ({@code postgresql/V22__...sql}). + */ + public static SortedMap under(Path root) throws IOException { + Objects.requireNonNull(root, "root"); + SortedMap migrations = new TreeMap<>(); + try (Stream files = Files.walk(root)) { + for (Path file : files.filter(VersionedMigrationFiles::isVersioned).toList()) { + migrations.put(root.relativize(file).toString().replace('\\', '/'), file); + } + } + return migrations; + } + + /** + * Every versioned migration below {@code root} in the order Flyway applies them: by version, its + * parts compared as numbers, a missing part as zero ({@code V2 < V2_1 < V2.10 < V10}, and {@code + * V1} is {@code V1_0}). + * + * @throws IllegalStateException naming both files when two have the same version, which Flyway + * refuses as well + */ + public static List inVersionOrder(Path root) throws IOException { + List ordered = new ArrayList<>(under(root).values()); + ordered.sort((left, right) -> compareVersions(version(left), version(right))); + for (int i = 1; i < ordered.size(); i++) { + if (compareVersions(version(ordered.get(i - 1)), version(ordered.get(i))) == 0) { + throw new IllegalStateException( + ordered.get(i - 1).getFileName() + + " and " + + ordered.get(i).getFileName() + + " have the same version; Flyway refuses two migrations with one version"); + } + } + return ordered; + } + + private static boolean isVersioned(Path file) { + return VERSIONED.matcher(file.getFileName().toString()).matches(); + } + + private static BigInteger[] version(Path file) { + String name = file.getFileName().toString(); + return Arrays.stream(name.substring(1, name.indexOf("__")).split("[._]")) + .map(BigInteger::new) + .toArray(BigInteger[]::new); + } + + private static int compareVersions(BigInteger[] left, BigInteger[] right) { + for (int i = 0; i < Math.max(left.length, right.length); i++) { + BigInteger l = i < left.length ? left[i] : BigInteger.ZERO; + BigInteger r = i < right.length ? right[i] : BigInteger.ZERO; + int compared = l.compareTo(r); + if (compared != 0) { + return compared; + } + } + return 0; + } +} diff --git a/grpc/grpc-testkit/src/test/java/dev/caskeleton/grpc/testkit/GrpcPackageOwnershipTest.java b/grpc/grpc-testkit/src/test/java/dev/caskeleton/grpc/testkit/GrpcPackageOwnershipTest.java index 706fc1b..9462358 100644 --- a/grpc/grpc-testkit/src/test/java/dev/caskeleton/grpc/testkit/GrpcPackageOwnershipTest.java +++ b/grpc/grpc-testkit/src/test/java/dev/caskeleton/grpc/testkit/GrpcPackageOwnershipTest.java @@ -20,7 +20,7 @@ class GrpcPackageOwnershipTest { List leaves = List.of("grpc-core-api", "grpc-runtime", "grpc-operation-ledger-jpa"); Map> owners = new LinkedHashMap<>(); for (String leaf : leaves) { - Path source = repo.resolve("src/platforms/grpc").resolve(leaf).resolve("src/main/java"); + Path source = repo.resolve("grpc").resolve(leaf).resolve("src/main/java"); try (var files = Files.walk(source)) { for (Path file : files.filter(path -> path.toString().endsWith(".java")).toList()) { var matcher = PACKAGE.matcher(Files.readString(file)); @@ -44,7 +44,7 @@ class GrpcPackageOwnershipTest { private static Path repositoryRoot() { Path candidate = Path.of("").toAbsolutePath(); while (candidate != null - && !Files.isRegularFile(candidate.resolve("src/config/architecture/modules.json"))) { + && !Files.isRegularFile(candidate.resolve("config/architecture/modules.json"))) { candidate = candidate.getParent(); } if (candidate == null) { diff --git a/scripts/buf.sh b/scripts/buf.sh new file mode 100755 index 0000000..eeda901 --- /dev/null +++ b/scripts/buf.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +# Buf lint and breaking-change policy for the Stable gRPC schema (grpc/grpc-contract, buf.yaml there). +# +# scripts/buf.sh lint +# scripts/buf.sh breaking +# +# protoc (the Gradle protobuf plugin) compiles the schema; Buf owns lint and breaking policy. The +# root `ci` stage runs both through :grpc:grpc-contract:bufLint and :bufBreaking. +# +# breaking compares the working tree with a baseline commit: +# BUF_AGAINST set → that ref +# a pull request (GITHUB_BASE_REF) → the merge base with origin/ +# otherwise → the merge base with origin/main, or HEAD^ when HEAD is on it +# (or when a local clone has no origin/main) +# A baseline without grpc/grpc-contract/buf.yaml has nothing to be compatible with, and the check +# says so and passes. A baseline Git cannot find fails: a shallow clone cannot answer the question. +set -euo pipefail + +root=$(git rev-parse --show-toplevel) +module=grpc/grpc-contract +buf=$("$root/scripts/tool.sh" buf) +cd "$root/$module" + +case "${1:-}" in + lint) + "$buf" lint + ;; + breaking) + if [ -n "${BUF_AGAINST:-}" ]; then + baseline=$BUF_AGAINST + else + base_branch="origin/${GITHUB_BASE_REF:-main}" + if git rev-parse --verify --quiet "$base_branch^{commit}" >/dev/null; then + baseline=$(git merge-base HEAD "$base_branch") + elif [ "${GITHUB_ACTIONS:-}" = true ]; then + # In CI the base branch must be there; a missing one means a shallow checkout, and comparing + # with something else would answer a different question. + echo "buf.sh: $base_branch is not in this clone; fetch it (actions/checkout fetch-depth: 0)." >&2 + exit 1 + else + echo "buf.sh: no $base_branch here; comparing with HEAD^ (set BUF_AGAINST to choose)." + baseline=$(git rev-parse HEAD) + fi + if [ -z "${GITHUB_BASE_REF:-}" ] && [ "$baseline" = "$(git rev-parse HEAD)" ]; then + baseline=$(git rev-parse --verify --quiet 'HEAD^' || true) + fi + fi + commit=$(git rev-parse --verify --quiet "${baseline}^{commit}" || true) + if [ -z "$commit" ]; then + echo "buf.sh: no baseline commit for '${baseline:-HEAD^}'; nothing to compare (first commit)." >&2 + [ -z "${baseline:-}" ] && exit 0 || exit 1 + fi + if ! git cat-file -e "$commit:$module/buf.yaml" 2>/dev/null; then + echo "buf.sh: baseline ${commit:0:12} has no $module/buf.yaml; breaking check skipped." + exit 0 + fi + echo "buf.sh: breaking against ${commit:0:12}" + "$buf" breaking --against "$root/.git#ref=$commit,subdir=$module" + ;; + *) + echo "usage: scripts/buf.sh lint|breaking" >&2 + exit 2 + ;; +esac diff --git a/scripts/release/check-staging.py b/scripts/release/check-staging.py new file mode 100644 index 0000000..121e77e --- /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 +(grpc-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:] + ["grpc-library"]: + directory = repository / group.replace(".", "/") / artifact / version + base = directory / f"{artifact}-{version}" + problems: list[str] = [] + if artifact == "grpc-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..3f88171 --- /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 --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..31c2f47 --- /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 --scanners vuln --severity CRITICAL,HIGH --exit-code 1 --ignorefile .trivyignore.yaml . +"$trivy" fs --scanners vuln --severity MEDIUM,LOW --exit-code 0 --ignorefile .trivyignore.yaml . +"$trivy" fs --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..c57980e --- /dev/null +++ b/scripts/tool.sh @@ -0,0 +1,62 @@ +#!/usr/bin/env bash +# Prints the path of a pinned, checksum-verified tool binary, downloading it once into +# ${TOOL_CACHE:-~/.cache/grpc-library}/-/. +# +# scripts/tool.sh buf|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 + buf) + # Buf 1.73.0, the version the backend template's grpc-proto-buf job ran. + version=1.73.0 + [ "$arch" = amd64 ] && asset=buf-Linux-x86_64 || asset=buf-Linux-aarch64 + [ "$arch" = amd64 ] \ + && sha256=8f2986298ad08f0cc1bf999b9797b7c383adf32d7edf0f73d6f1e1a701baeac1 \ + || sha256=902b75267db7f4391e99b7fa0756050e5354234cc0437ef50eee9c788950c7a3 + url="https://github.com/bufbuild/buf/releases/download/v${version}/${asset}" + archive=0 + ;; + 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 buf|trivy" >&2; exit 2 ;; +esac + +dir="${TOOL_CACHE:-$HOME/.cache/grpc-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/settings.gradle b/settings.gradle index bec7702..bf9090e 100644 --- a/settings.gradle +++ b/settings.gradle @@ -1,9 +1,13 @@ +// The library's one Gradle build. The repository root is the Gradle root: config/, gradle/ and +// build-logic/ sit next to the module families grpc/ and grpc-advanced/. pluginManagement { - includeBuild('../../build-logic') + 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.optional-architecture-registry' + id 'ca.architecture-registry' } dependencyResolutionManagement { @@ -11,26 +15,6 @@ dependencyResolutionManagement { repositories { mavenCentral() } - versionCatalogs { - libs { - from(files('../../gradle/libs.versions.toml')) - } - } } -rootProject.name = 'optional-platforms' - -// gradle.properties here must say what src/gradle.properties says (review 2026-11-01 08-06): Gradle -// reads only this build's own file, and a copy that drifted would make the optional build quietly -// slower or differently configured than the main one. -def readBuildProperties = { File file -> - def properties = new Properties() - file.withInputStream { properties.load(it) } - properties -} -def mainBuildProperties = readBuildProperties(new File(settingsDir, '../../gradle.properties')) -def ownBuildProperties = readBuildProperties(new File(settingsDir, 'gradle.properties')) -if (mainBuildProperties != ownBuildProperties) { - throw new GradleException("platforms/optional-build/gradle.properties differs from src/gradle.properties: " + - "${ownBuildProperties} vs ${mainBuildProperties}. Copy the main build's values.") -} +rootProject.name = 'grpc-library'