From de070e16a7ad77d196ed4cc36bf097161340eb56 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 17:00:49 +0900 Subject: [PATCH 01/10] =?UTF-8?q?ci:=20=EB=8B=A4=EB=A5=B8=20=EB=8B=A8?= =?UTF-8?q?=EA=B3=84=EA=B0=80=20=EC=9D=B4=EB=AF=B8=20=EB=8F=8C=EB=A6=AC?= =?UTF-8?q?=EB=8A=94=20workflow=20job=EC=9D=84=20=EC=A7=80=EC=9A=B4?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit workflow 15개 가운데 모듈 모양 파일들이 PR·main·nightly 단계가 이미 계획하는 Gradle 태스크를 한 번 더 돌린다(설계 design-docs repo-structure/03-ci.md 3.1절 「중복」). - fileserver-pr.yml 다섯 job: 모두 leaf `test`나 그 부분집합이다. `ci`가 매 PR 돌린다. - fileserver-nightly.yml의 --rerun-tasks job 셋: 같은 `test`의 부분집합이다. NFS job만 남긴다. - jpa-nightly.yml의 failure·query plan·security·pool job: 모두 integration()·performance() lane이라 :integrationCheck· :performanceCheck가 돈다. PostgreSQL major 행렬만 남긴다. - notification-platform.yml의 pr job: `ci`와 :integrationCheck의 태스크다. 경로 필터가 docs/adr/로 옮긴 알림 ADR을 보지 못했다. chaos job만 남긴다. - object-storage-qualification.yml의 MinIO job 둘: integration lane이다. 보호된 AWS job만 남긴다. - link-check.yml: 문서 검사라 main 단계로(소유자 결정 2026-09-16). integration-main.yml의 links job으로 옮긴다. fileserver 지원 매트릭스는 지운 job id 대신 그 증거를 실제로 만드는 테스트 클래스·모듈 test·남은 job을 적고, FileserverDocumentation CoverageTest가 행마다 그 이름이 있는지 본다. job이 사라진 시험 문장 (PoolLaneClaimTest의 nightly job 검사, lychee 경로 필터 검사)은 지우거나 새 위치로 맞춘다. 위험: PR에서 경로로 켜지던 컨테이너 lane(notification의 실 PostgreSQL 두 lane, MinIO)은 이제 main push와 nightly에서만 돈다. 어댑터 컨테이너 lane을 main 단계로 옮긴 소유자 결정(2026-11-07 ②)과 같은 쪽이다. 검증: 기준 2959eff0의 desktop worktree에서 workflow의 Gradle 명령 50개를 --dry-run해 태스크 집합을 만들었다. 지운·옮긴 job 27개의 태스크는 모두 :ci·:mainCheck·:integrationCheck·:performanceCheck·:releaseCheck 계획 안에 있다(단계 집계 밖 0). 로그 desktop ~/t2a-backend-ci-logs/wave1-base/. python3 scripts/check-docs.py, check-work-docs.py 통과. Refs: design-docs repo-structure/03-ci.md 7.3절 Wave 1 --- .github/workflows/fileserver-nightly.yml | 52 +------- .github/workflows/fileserver-pr.yml | 110 ----------------- .github/workflows/integration-main.yml | 23 +++- .github/workflows/jpa-nightly.yml | 56 +-------- .github/workflows/link-check.yml | 49 -------- .github/workflows/notification-platform.yml | 81 ++----------- .../object-storage-qualification.yml | 33 +----- docs/capability-status.md | 2 +- docs/fileserver/support-matrix.md | 39 +++--- src/adapter/outbound/objectstorage/README.md | 6 +- .../outbound/objectstorage/build.gradle | 10 +- .../platform/PoolLaneClaimTest.java | 14 --- .../DeveloperExperienceContractTest.java | 58 +++------ .../fileserver-platform/build.gradle | 10 +- .../FileserverDocumentationCoverageTest.java | 112 +++++++++++++----- 15 files changed, 177 insertions(+), 478 deletions(-) delete mode 100644 .github/workflows/fileserver-pr.yml delete mode 100644 .github/workflows/link-check.yml diff --git a/.github/workflows/fileserver-nightly.yml b/.github/workflows/fileserver-nightly.yml index 20bd2d67..a4538f56 100644 --- a/.github/workflows/fileserver-nightly.yml +++ b/.github/workflows/fileserver-nightly.yml @@ -1,8 +1,8 @@ name: fileserver-nightly -# The environments that cannot run on every pull request: a real network filesystem, a foreign -# filesystem, and the long-running fault matrices. They are nightly rather than skipped because a -# green pull-request run is not certification of any of them. +# The one environment a pull request cannot provide: a real NFSv4 server. The crash, large-file and +# lease suites that used to run here with --rerun-tasks are tests of the leaves' `test`, which the +# pull-request `ci` already runs; their second run added no coverage. on: workflow_dispatch: @@ -36,49 +36,3 @@ jobs: - name: Tear down the NFS environment if: always() run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml down -v - - fileserver-process-kill-matrix: - runs-on: ubuntu-latest - timeout-minutes: 45 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the crash matrix and reconciliation suites - working-directory: src - run: >- - ./gradlew - :adapter:outbound:fileserver:test --tests '*CrashRecoveryMatrixTest' - :application-fileserver:test --tests '*FileReconciliationServiceTest' - --rerun-tasks - --stacktrace - - fileserver-large-file-performance: - runs-on: ubuntu-latest - timeout-minutes: 60 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the large-file and slow-client suites under a constrained heap - working-directory: src - env: - GRADLE_OPTS: -Xmx512m - run: >- - ./gradlew - :adapter:outbound:fileserver:test --tests '*LargeFileBoundedMemoryTest' - :adapter:outbound:fileserver:test --tests '*LocalAppendMemoryTest' - --rerun-tasks - --stacktrace - - fileserver-multi-instance-lease: - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Prove no run commits bytes from a stale lease - working-directory: src - run: >- - ./gradlew - :application-fileserver:test --tests '*MultiInstanceWriterLeaseTest' - --rerun-tasks - --stacktrace diff --git a/.github/workflows/fileserver-pr.yml b/.github/workflows/fileserver-pr.yml deleted file mode 100644 index 7dae30d0..00000000 --- a/.github/workflows/fileserver-pr.yml +++ /dev/null @@ -1,110 +0,0 @@ -name: fileserver-pr - -# Every claim in docs/fileserver/support-matrix.md that says "Stable" is backed by a job here. -# A support level with no job behind it is a marketing claim, not an engineering one, and -# DocumentationCoverageTest fails the build when the two drift apart. - -on: - workflow_dispatch: - pull_request: - paths: - - 'src/application-fileserver/**' - - 'src/adapter/inbound/web-fileserver/**' - - 'src/adapter/outbound/fileserver/**' - - 'src/adapter/outbound/persistence-fileserver/**' - - 'src/composition/fileserver-platform/**' - - 'src/adapter/outbound/persistence-jpa/src/**/fileserver/**' - - 'src/app-bootstrap/src/**/fileserver/**' - - 'docs/fileserver/**' - # The capability is not only its Java files. A change to the bound settings, the shipped - # environment, the registry that documents it, or the container that has to give it a - # writable volume changes how it behaves at runtime just as surely — and those were the - # exact files that could previously ship unverified. - - 'src/app-bootstrap/src/main/resources/application.yml' - - 'src/.env' - - 'docs/registries/env-keys.yaml' - - 'src/Dockerfile' - - 'compose.yaml' - - 'src/app-bootstrap/compose-lanes/fileserver.yaml' - - '.github/workflows/fileserver-pr.yml' - # Every Gradle job here installs its toolchain through this composite action, so a change to - # it changes what this gate runs. - - '.github/actions/setup-gradle-java/action.yml' - -permissions: - contents: read - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -jobs: - fileserver-unit-and-architecture: - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - # The architecture half of this claim is ci-quality-gates.yml's `architectureCheck`, which runs - # the whole ArchUnit suite on the same pull request; a filtered second run here was the repeat - # review BUILD-중복-6 removed. - - name: Run the fileserver application and assembly suites - working-directory: src - run: >- - ./gradlew - :application-fileserver:test - :composition:fileserver-platform:test - --stacktrace - - fileserver-local-ext4-contract: - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Certify the local content store against the shared contract - working-directory: src - run: >- - ./gradlew - :adapter:outbound:fileserver:test - --stacktrace - - fileserver-http-contract: - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the servlet transport contracts - working-directory: src - run: >- - ./gradlew - :adapter:inbound:web-fileserver:test - --stacktrace - - fileserver-security-suite: - runs-on: ubuntu-latest - timeout-minutes: 20 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the path, filename, range, and problem-detail hardening suite - working-directory: src - run: >- - ./gradlew - :adapter:inbound:web-fileserver:test --tests '*FileserverHardeningContractTest' - :adapter:outbound:fileserver:test --tests '*PhysicalPathResolverTest' - --stacktrace - - fileserver-bounded-memory: - runs-on: ubuntu-latest - timeout-minutes: 20 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Prove transfer cost does not scale with file size - working-directory: src - run: >- - ./gradlew - :adapter:outbound:fileserver:test --tests '*LargeFileBoundedMemoryTest' - --stacktrace diff --git a/.github/workflows/integration-main.yml b/.github/workflows/integration-main.yml index 6f8d8366..fd0a4bf6 100644 --- a/.github/workflows/integration-main.yml +++ b/.github/workflows/integration-main.yml @@ -55,7 +55,7 @@ concurrency: # compared against the registry, and a Markdown table compared against the declared source sets. # Each was a custom parser for a file format nobody controls, and each made a documentation edit a # precondition for a build. A stale sentence is a defect, but it is not one a build can be failed -# for, and link-check.yml already answers the one documentation question with a stable machine +# for, and the `links` job below answers the one documentation question with a stable machine # answer: does this link resolve. jobs: @@ -245,3 +245,24 @@ jobs: name: compose-runtime-smoke-evidence path: src/app-bootstrap/build/evidence/runtime-smoke if-no-files-found: warn + + # Every committed Markdown link, external URLs included (lychee). A documentation check, so the main + # stage rather than the pull request (owner decision 2026-09-16); the relative links of every living + # document are also checked on each pull request by scripts/check-docs.py, which needs no network. + links: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - name: Check committed documentation links + uses: lycheeverse/lychee-action@7cd0af4c74a61395d455af97419279d86aafaede # lycheeverse/lychee-action@v2.0.2 + with: + args: >- + --no-progress + --root-dir . + README.md + src/README.md + 'src/**/README.md' + 'src/**/CLAUDE.md' + 'docs/**/*.md' + '.github/**/*.md' + fail: true diff --git a/.github/workflows/jpa-nightly.yml b/.github/workflows/jpa-nightly.yml index adbf1ff4..91bac64f 100644 --- a/.github/workflows/jpa-nightly.yml +++ b/.github/workflows/jpa-nightly.yml @@ -1,11 +1,9 @@ name: jpa-nightly -# The suites that are too slow, too Docker-heavy, or too machine-dependent for a PR, and the middle -# of the PostgreSQL matrix. -# -# The failure-injection lane is the one that matters most and is easiest to lose: it is the only -# place the commit-ambiguity scenarios run, and they are the only evidence that a lost commit -# acknowledgement produces completion-unknown rather than a retry. +# The platform contract on every Stable PostgreSQL major, one major per job. The failure-injection, +# query-plan, security and pool lanes that used to have jobs here are `integration()` and +# `performance()` lanes, so `:integrationCheck` and `:performanceCheck` (integration-main.yml) run them +# on main and nightly; only the per-major fan-out is not in an aggregate. on: workflow_dispatch: @@ -38,49 +36,3 @@ jobs: :adapter:outbound:persistence-jpa:jpaPlatformContractTest -Pjpa.matrix.versions=${{ matrix.postgresql }} --stacktrace - - jpa-failure-injection: - runs-on: ubuntu-latest - timeout-minutes: 45 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Reproduce deadlock, serialization, and commit-ambiguity scenarios - working-directory: src - run: >- - ./gradlew - :adapter:outbound:persistence-jpa:jpaPlatformFailureTest - --stacktrace - - jpa-query-plan-and-security: - runs-on: ubuntu-latest - timeout-minutes: 45 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the query plan and database security suites - working-directory: src - run: >- - ./gradlew - :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest - :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest - --stacktrace - - jpa-pool-pressure: - runs-on: ubuntu-latest - timeout-minutes: 45 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Verify pool saturation and REQUIRES_NEW connection behaviour - working-directory: src - # A behaviour contract, not a measurement. This step used to switch assertions off with an - # explicit property and call the result a certification, so the only threshold it ever - # asserted was that thresholds were not being asserted. What - # it checks now — that REQUIRES_NEW needs two connections per concurrent thread, that a - # saturated pool reports its pending count, that a caller waits rather than proceeding - # without a connection — is true on any runner, so there is nothing to switch off. - run: >- - ./gradlew - :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest - --stacktrace diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml deleted file mode 100644 index ec0b2708..00000000 --- a/.github/workflows/link-check.yml +++ /dev/null @@ -1,49 +0,0 @@ -name: link-check - -on: - pull_request: - paths: - - "README.md" - - "src/README.md" - - "src/**/README.md" - - "src/**/CLAUDE.md" - - "docs/**/*.md" - - ".github/**/*.md" - - ".github/workflows/link-check.yml" - push: - branches: ["main"] - paths: - - "README.md" - - "src/README.md" - - "src/**/README.md" - - "src/**/CLAUDE.md" - - "docs/**/*.md" - - ".github/**/*.md" - - ".github/workflows/link-check.yml" - workflow_dispatch: - -permissions: - contents: read - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -jobs: - lychee: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - name: Check committed documentation links - uses: lycheeverse/lychee-action@7cd0af4c74a61395d455af97419279d86aafaede # lycheeverse/lychee-action@v2.0.2 - with: - args: >- - --no-progress - --root-dir . - README.md - src/README.md - 'src/**/README.md' - 'src/**/CLAUDE.md' - 'docs/**/*.md' - '.github/**/*.md' - fail: true diff --git a/.github/workflows/notification-platform.yml b/.github/workflows/notification-platform.yml index 2f131a09..09071da9 100644 --- a/.github/workflows/notification-platform.yml +++ b/.github/workflows/notification-platform.yml @@ -1,44 +1,16 @@ name: notification-platform -# Verification tiers for the Notification Delivery Platform. +# The notification platform's chaos tier: the fault, race and restart suites run again on their own, +# nightly, because they are the ones a single green run says least about. # -# The PR tier is deliberately free of any external provider. A gate that depends on a third-party -# sandbox fails for reasons that have nothing to do with the change under review, and a gate people -# learn to re-run is not a gate. Real provider smoke tests live in the secret-protected tier, where -# a failure is an environment signal rather than a merge blocker. -# -# Every job that invokes Gradle validates the wrapper first with the repository's pinned action; -# the wrapper JAR is executable code fetched at build time, so validating it is what keeps a -# compromised wrapper from turning any workflow run into arbitrary code execution. +# The pull-request tier that used to be here is gone. Its seven steps ran `:application-core:test`, +# the notification leaves' `test` and `check`, and `jpaPlatformContractTest`/`jpaPlatformMigrationTest` +# — tasks the pull-request `ci` and `:integrationCheck` already run — and its path filter could not +# see the notification ADRs once they moved to docs/adr/. NotificationReleaseGateTest holds those in +# the notification leaf's `test`, which `ci` runs on every pull request. on: - pull_request: - paths: - # The filter used to stop at the four notification source trees, so a change to the - # composition root, the settings binding, the schema migrations, or the evidence manifest - # ran none of this — and those are exactly the surfaces that decide whether the platform - # assembles, binds and migrates at all. - - 'src/application-core/src/**/notification/**' - - 'src/adapter/outbound/notification/**' - - 'src/adapter/outbound/persistence-notification/**' - # The notification real-PostgreSQL qualifications still run in the JPA leaf's lane. - - 'src/adapter/outbound/persistence-jpa/src/**/notification/**' - - 'src/adapter/inbound/web-notification/**' - - 'src/composition/notification-platform/**' - - 'src/app-bootstrap/src/main/resources/application*.yml' - - 'src/gradle/notification-*.gradle' - - 'src/config/architecture/modules.json' - - 'src/.env' - - 'docs/notification/**' - - 'src/app-bootstrap/compose-lanes/smoke/notification-smoke.sh' - - '.github/workflows/notification-platform.yml' - # Every Gradle job here installs its toolchain through this composite action, so a change to - # it changes what this gate runs. - - '.github/actions/setup-gradle-java/action.yml' - push: - branches: [ main ] schedule: - # Nightly: the chaos tier, which is slower and inherently less deterministic than the PR tier. - cron: '0 17 * * *' workflow_dispatch: @@ -50,47 +22,8 @@ concurrency: cancel-in-progress: true jobs: - pr: - name: contract (Java 21, no external provider) - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Compile and format check - working-directory: src - run: ./gradlew :application-core:compileJava :adapter:outbound:notification:compileJava --console=plain - - name: Application contracts - working-directory: src - run: ./gradlew :application-core:test --console=plain - - name: Provider contract suite - working-directory: src - run: ./gradlew :adapter:outbound:notification:test --console=plain - - name: Persistence and web - working-directory: src - run: ./gradlew :adapter:outbound:persistence-jpa:test :adapter:inbound:web-notification:test :composition:notification-platform:test --console=plain - # The PR tier never touched a database, so every claim about migrations, claim atomicity and - # lease fencing rested on a fake. Docker is available on this runner; the lane fails closed - # when the container cannot start, because a skipped contract reports success for a database - # nobody tested. - - name: Notification schema and claim contracts (real PostgreSQL) - working-directory: src - run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest --console=plain - - name: Notification migration upgrade (real PostgreSQL) - working-directory: src - run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest --console=plain - # The architecture gates run in ci-quality-gates.yml on the same pull request; the evidence - # manifest (NotificationEvidenceVerifierTest) and the environment registry - # (NotificationEnvironmentRegistryTest) are leaf tests the steps above already ran. - # verifyNotificationApiSurface is part of the leaf's `check` (owner decision 20), so the step - # below runs it; a separate API surface step would run it twice. - - name: Static analysis and API surface - working-directory: src - run: ./gradlew :adapter:outbound:notification:check -x test --console=plain - nightly-chaos: name: chaos (ambiguity, restart recovery, callback burst) - if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' runs-on: ubuntu-latest timeout-minutes: 60 steps: diff --git a/.github/workflows/object-storage-qualification.yml b/.github/workflows/object-storage-qualification.yml index da628638..64ef59fd 100644 --- a/.github/workflows/object-storage-qualification.yml +++ b/.github/workflows/object-storage-qualification.yml @@ -1,17 +1,9 @@ name: object-storage-qualification -# Only pull requests that touch object storage start the MinIO container (review BUILD-계획-B3). The -# MinIO lanes left the object storage leaf's `check`; they run in the root `integrationCheck` (main push -# and nightly, integration-main.yml) and here. +# The protected AWS lane, on request only: it needs the sandbox credentials. The MinIO contract and +# fault lanes that used to have jobs here are `integration()` lanes, so `:integrationCheck` +# (integration-main.yml, main and nightly) runs them. on: - pull_request: - paths: - - "src/application-objectstorage/**" - - "src/adapter/outbound/objectstorage/**" - - "src/gradle/**" - - ".github/workflows/object-storage-qualification.yml" - schedule: - - cron: "23 3 * * 2" workflow_dispatch: inputs: run_protected_aws: @@ -27,25 +19,6 @@ env: TESTCONTAINERS_REUSE_ENABLE: "false" jobs: - minio-managed-contract: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run exact-release MinIO managed contract - working-directory: src - run: ./gradlew :adapter:outbound:objectstorage:objectStorageMinioContractTest --stacktrace - - minio-managed-fault: - if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run digest-pinned MinIO and Toxiproxy fault contract - working-directory: src - run: ./gradlew :adapter:outbound:objectstorage:objectStorageMinioFaultTest --stacktrace - aws-managed-common-subset: if: >- github.event_name == 'workflow_dispatch' diff --git a/docs/capability-status.md b/docs/capability-status.md index 241afdf7..761fe1ca 100644 --- a/docs/capability-status.md +++ b/docs/capability-status.md @@ -399,7 +399,7 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap | `verifyNoStaleTraceableJars` | 해당 없음 — leaf jar 이름에 revision이 없어 stale jar가 생기지 않음 | — | | `GrpcStableReleaseGate`/`GrpcAdvancedPromotionGate` | 게이트에 연결된 적 없음(자기 테스트만). release `grpc-stable-release-gate` job은 그대로 | — | | notification evidence·env registry·mongo lane 계약(`test`) | `notificationDocumentContractTest`·`notificationEnvironmentContractTest`·`mongoDocumentContractTest` | `mainCheck` | -| objectstorage MinIO 레인(`check`) | objectstorage `mainCheck` + `integrationCheck` + object-storage-qualification.yml(경로 필터) | `mainCheck` | +| objectstorage MinIO 레인(`check`) | 루트 `integrationCheck` | main | | `releaseCheck`의 `ci` | ci-quality-gates.yml `:ci`(PR·main push) | PR | | fileserver-pr `architectureTest --tests '*Fileserver*'` | `:ci`의 `architectureCheck`(전체 ArchUnit) | PR | | legacy whole-`byte[]` 포트 `ObjectStoragePort`·`StoredObject` | `src/application-objectstorage/src/main/java/dev/caskeleton/application/storage/` | `c4a066df` | 한 기능에 한 세대(S1-#17b·S4-#11a). canonical semantic 포트로 대체 | diff --git a/docs/fileserver/support-matrix.md b/docs/fileserver/support-matrix.md index 50b30b6a..2ee31c8f 100644 --- a/docs/fileserver/support-matrix.md +++ b/docs/fileserver/support-matrix.md @@ -1,8 +1,11 @@ # Fileserver 지원 매트릭스 -여기의 지원 등급은 의도가 아니라 증거에 대한 주장이다. 행마다 그 증거를 만드는 CI job을 적는다. 행이 없는 -job을 적으면 `FileserverDocumentationCoverageTest`가 빌드를 실패시킨다. 그래서 등급은 그것을 정당화한 테스트보다 -오래 살 수 없다. +여기의 지원 등급은 의도가 아니라 증거에 대한 주장이다. 행마다 그 증거를 적는다: 테스트 클래스, 모듈의 `test` +태스크, 또는 그 테스트를 따로 돌리는 CI job. 없는 테스트·모듈·job을 적거나 증거 칸이 빈 행이 있으면 +`FileserverDocumentationCoverageTest`가 빌드를 실패시킨다. 그래서 등급은 그것을 정당화한 테스트보다 오래 살 수 없다. + +테스트 클래스와 모듈 `test`는 그 모듈의 `test`가 pull request 단계(`prCheck` 안의 `ci`)에서 매번 돈다. CI job은 그 +테스트에 환경(NFS 서버)이나 릴리스 시점이 따로 필요할 때만 적는다. ## 등급 @@ -11,31 +14,31 @@ job을 적으면 `FileserverDocumentationCoverageTest`가 빌드를 실패시킨 | 등급 | 뜻 | |---|---| | Stable | pull request마다 인증한다. 계약 변경은 깨지는 변경이다. | -| Beta | 매일 밤 인증한다. 폐기 예고와 함께 계약이 아직 바뀔 수 있다. | +| Beta | 증거 칸의 시험으로 인증한다. 폐기 예고와 함께 계약이 아직 바뀔 수 있다. | | Limited | 밝힌 제약 아래에서 릴리스 게이트에서만 인증한다. | | Compatibility | 받아들이지만 최적화하지 않는다. 알려진 주의점은 그 자리에 적는다. | | Experimental | 기본으로 꺼져 있고, 상위 표준이 확정되지 않았으며, 예고 없이 바뀔 수 있다. | ## 런타임 profile -| Profile | 등급 | CI job | +| Profile | 등급 | 증거 | |---|---|---| -| 로컬 파일 시스템(ext4) content 저장소 | Stable | `fileserver-local-ext4-contract` | -| Spring MVC transport(raw, multipart, batch, 다운로드) | Stable | `fileserver-http-contract` | -| 경로, 파일 이름, range, problem-detail 강화 | Stable | `fileserver-security-suite` | -| 메모리 상한이 있는 전송 | Stable | `fileserver-bounded-memory` | -| 애플리케이션·아키텍처 불변식 | Stable | `fileserver-unit-and-architecture` | -| 런타임 조립(flag를 켜면 capability가 시작한다) | Stable | `fileserver-unit-and-architecture` | -| tus 1.0 이어 올리기 업로드 | Stable | `fileserver-http-contract` | -| 장애 복구 매트릭스 | Beta | `fileserver-process-kill-matrix` | +| 로컬 파일 시스템(ext4) content 저장소 | Stable | `:adapter:outbound:fileserver:test` | +| Spring MVC transport(raw, multipart, batch, 다운로드) | Stable | `:adapter:inbound:web-fileserver:test` | +| 경로, 파일 이름, range, problem-detail 강화 | Stable | `FileserverHardeningContractTest`, `PhysicalPathResolverTest` | +| 메모리 상한이 있는 전송 | Stable | `LargeFileBoundedMemoryTest` | +| 애플리케이션·아키텍처 불변식 | Stable | `:application-fileserver:test`, `:composition:fileserver-platform:test` | +| 런타임 조립(flag를 켜면 capability가 시작한다) | Stable | `:composition:fileserver-platform:test` | +| tus 1.0 이어 올리기 업로드 | Stable | `:adapter:inbound:web-fileserver:test` | +| 장애 복구 매트릭스 | Beta | `CrashRecoveryMatrixTest`, `FileReconciliationServiceTest` | | NFSv4 결과 모름 처리 | Beta | `fileserver-nfs-ambiguity` | -| 큰 파일·느린 client 성능 | Beta | `fileserver-large-file-performance` | -| 여러 인스턴스 writer lease | Beta | `fileserver-multi-instance-lease` | -| Nginx `X-Accel-Redirect` 위임 | Limited | `fileserver-http-contract` | +| 큰 파일·느린 client 성능 | Beta | `LargeFileBoundedMemoryTest`, `LocalAppendMemoryTest` | +| 여러 인스턴스 writer lease | Beta | `MultiInstanceWriterLeaseTest` | +| Nginx `X-Accel-Redirect` 위임 | Limited | `:adapter:inbound:web-fileserver:test` | | telemetry 민감 데이터 억제 | Stable | `fileserver-sensitive-telemetry-scan` | | 문서와 지원 주장 범위 | Stable | `fileserver-documentation-gate` | | 전체 릴리스 검증 | Stable | `fileserver-full-verification` | -| HTTP resumable uploads draft-12 | Experimental | `fileserver-http-contract` | +| HTTP resumable uploads draft-12 | Experimental | `:adapter:inbound:web-fileserver:test` | ### WebFlux transport 제거 @@ -45,7 +48,7 @@ SERVLET으로 정한다. ## 주장하지 않는 것 -아래는 job이 없고, 그래서 주장도 없다. +아래는 증거가 없고, 그래서 주장도 없다. - Kubernetes PVC(ReadWriteOnce 포함). 이 repo는 클러스터 매니페스트와 그것을 검사하던 release job을 2026-11-07에 지웠다. volume이 지켜야 할 조건은 [operations.md](operations.md) 「운영 환경이 지켜야 할 diff --git a/src/adapter/outbound/objectstorage/README.md b/src/adapter/outbound/objectstorage/README.md index 89d51fed..4a2f9b4d 100644 --- a/src/adapter/outbound/objectstorage/README.md +++ b/src/adapter/outbound/objectstorage/README.md @@ -99,9 +99,9 @@ testImplementation testFixtures(project(':adapter:outbound:objectstorage')) ### MinIO 검증 lane `objectStorageMinioContractTest`와 `objectStorageMinioFaultTest`는 실제 MinIO와 Toxiproxy를 돌린다. 루트 -`integrationCheck`(main push와 nightly)와, object storage를 건드리는 pull request의 -`.github/workflows/object-storage-qualification.yml`에서 돈다 — 이 leaf의 `mainCheck`에서는 돌지 않는다. -거기서는 main push마다 두 번 돌았다. image는 파일 하나 +`integrationCheck`(main push와 nightly)에서 돈다. 이 leaf의 `mainCheck`에서는 돌지 않는다. 거기서도 돌던 때는 +main push마다 두 번 돌았다. object storage를 건드린 pull request에서 따로 돌던 workflow job은 2026-11-08에 +지웠다(같은 태스크를 `integrationCheck`가 돌린다). image는 파일 하나 `src/test/resources/object-storage/minio-provider-evidence.json`에서 읽는다. 그 `image` digest는 옆에 적힌 `status`, `excludedProfiles`, `limitations`를 잰 릴리스다. `MinioQualificationImage`(`src/test`에 있고, leaf의 `test`가 Docker 없이 검사한다)가 그것을 읽는다. diff --git a/src/adapter/outbound/objectstorage/build.gradle b/src/adapter/outbound/objectstorage/build.gradle index 15612ce7..ec9f7961 100644 --- a/src/adapter/outbound/objectstorage/build.gradle +++ b/src/adapter/outbound/objectstorage/build.gradle @@ -151,8 +151,8 @@ strictTestLanes { description = 'Runs only with explicit protected AWS sandbox authority and exact inputs.' requires 'dev.caskeleton.adapter.outbound.objectstorage.qualification.AwsS3QualificationPreconditionsTest' rejectSkipped = true - // The protected environment of object-storage-qualification.yml is the only caller that has - // the authority. Without it the lane can only fail, so integrationCheck leaves it out and + // The protected AWS workflow job, run on request with the sandbox secrets, is the only caller + // that has the authority. Without it the lane can only fail, so integrationCheck leaves it out and // says so (review NEW-16); naming the task still runs it and still fails closed. if (providers.environmentVariable('OBJECT_STORAGE_AWS_QUALIFICATION_ENABLED').getOrElse('') != 'true') { explicitOnly 'it needs OBJECT_STORAGE_AWS_QUALIFICATION_ENABLED=true and the protected AWS sandbox inputs' @@ -162,7 +162,7 @@ strictTestLanes { // The MinIO lanes start a container, so they are not this leaf's pull-request `check` (review // BUILD-계획-B3). They are integration lanes, and the root integrationCheck owns every container lane -// on main and nightly; object-storage-qualification.yml runs them on pull requests that touch object -// storage. This leaf's `mainCheck` used to run them too, so each main push ran them twice in two -// parallel jobs (review 2026-11-03 RR-06-09, original 08-04 (d)). +// on main and nightly. This leaf's `mainCheck` used to run them too, so each main push ran them twice +// in two parallel jobs (review 2026-11-03 RR-06-09, original 08-04 (d)); a path-filtered pull-request +// workflow ran them a third time until 2026-11-08. diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/platform/PoolLaneClaimTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/platform/PoolLaneClaimTest.java index ef94f18c..788f58db 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/platform/PoolLaneClaimTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/platform/PoolLaneClaimTest.java @@ -34,7 +34,6 @@ class PoolLaneClaimTest { "src/adapter/outbound/persistence-jpa/src/jpaPlatformPerformanceTest/java/dev/caskeleton/adapter/outbound/persistence/platform/pool/PoolPressureContractTest.java", "src/adapter/outbound/persistence-jpa/src/jpaPlatformPerformanceTest/java/dev/caskeleton/adapter/outbound/persistence/platform/pool/HikariPoolSaturationContractTest.java", "src/adapter/outbound/persistence-jpa/src/jpaPlatformPerformanceTest/java/dev/caskeleton/adapter/outbound/persistence/platform/pool/RequiresNewPoolPressureContractTest.java", - ".github/workflows/jpa-nightly.yml", "docs/jpa/repository-adaptation.md"); /** @@ -75,19 +74,6 @@ class PoolLaneClaimTest { } } - @Test - @DisplayName("nightly job은 동작 lane을 그 동작 이름으로 돌린다") - void theNightlyJobRunsTheBehaviourLane() { - String nightly = read(".github/workflows/jpa-nightly.yml"); - - assertThat(nightly) - .as("the lane that runs must be the one the build registers") - .contains(":adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest"); - assertThat(nightly) - .as("the old task name would silently select nothing") - .doesNotContain(":adapter:outbound:persistence-jpa:jpaPlatformPerformanceTest"); - } - /** Reads a repository-relative file, locating the root by walking up. */ private static String read(String repositoryRelativePath) { for (Path directory = Path.of("").toAbsolutePath(); diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java index bcf8e25e..11d1f23a 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java @@ -32,6 +32,7 @@ import org.yaml.snakeyaml.constructor.SafeConstructor; class DeveloperExperienceContractTest { private static final Path REPOSITORY_ROOT = repositoryRoot(); + private static final String MAIN_WORKFLOW = ".github/workflows/integration-main.yml"; // The workflow-mutation fixtures that stood here are gone with the tests that used them: a // hex-escaped `uses:`, a line-continued action reference, a `run:` block impersonating a @@ -143,47 +144,24 @@ class DeveloperExperienceContractTest { @Test @Tag("repository-contract") - void linkCheckIsBlockingAndUsesThePinnedLycheeAction() throws IOException { - String workflow = read(".github/workflows/link-check.yml"); + @DisplayName("링크 검사는 main 단계 job 하나가 고정한 lychee action으로 정해진 문서 범위를 실패하게 검사한다") + void linkCheckScansTheExactDocumentationScopeAndFails() throws IOException { + // given + Map links = requireMap(requireMap(parseYamlMap(read(MAIN_WORKFLOW)), "jobs"), "links"); - assertThat(workflow).contains("lycheeverse/lychee-action@v2.0.2").contains("fail: true"); - } - - @Test - @Tag("repository-contract") - void linkCheckTriggersAndScansTheExactDocumentationScope() throws IOException { - List expectedPaths = - List.of( - "README.md", - "src/README.md", - "src/**/README.md", - "src/**/CLAUDE.md", - "docs/**/*.md", - ".github/**/*.md", - ".github/workflows/link-check.yml"); - Map workflow = parseYamlMap(read(".github/workflows/link-check.yml")); - Map triggers = requireMap(workflow, workflow.containsKey("on") ? "on" : true); - - assertThat(triggers.keySet().stream().map(String::valueOf).toList()) - .containsExactlyInAnyOrder("pull_request", "push", "workflow_dispatch"); - assertThat(requireStringList(requireMap(triggers, "pull_request"), "paths")) - .containsExactlyElementsOf(expectedPaths); - Map push = requireMap(triggers, "push"); - assertThat(requireStringList(push, "branches")).containsExactly("main"); - assertThat(requireStringList(push, "paths")).containsExactlyElementsOf(expectedPaths); - - Map lycheeJob = requireMap(requireMap(workflow, "jobs"), "lychee"); - List steps = requireList(lycheeJob, "steps"); + // when Map lycheeStep = - steps.stream() + requireList(links, "steps").stream() .filter(Map.class::isInstance) .map(Map.class::cast) - .filter( - step -> - "lycheeverse/lychee-action@7cd0af4c74a61395d455af97419279d86aafaede" - .equals(step.get("uses"))) + .filter(step -> String.valueOf(step.get("uses")).contains("lychee-action@")) .findFirst() - .orElseThrow(() -> new AssertionError("missing pinned lychee action step")); + .orElseThrow(() -> new AssertionError("missing lychee action step")); + + // then + assertThat(links.containsKey("if")).as("a conditional link check is one nobody sees run").isFalse(); + assertThat(String.valueOf(lycheeStep.get("uses"))) + .endsWith("lycheeverse/lychee-action@7cd0af4c74a61395d455af97419279d86aafaede"); Map with = requireMap(lycheeStep, "with"); assertThat(with.get("fail")).isEqualTo(true); assertThat(shellWords(requireString(with, "args"))) @@ -288,16 +266,10 @@ class DeveloperExperienceContractTest { String staleSelector = ":app-bootstrap:test --tests 'dev.caskeleton.bootstrap.architecture.*'"; // The whole-repository architecture suite runs once per pull request, in ci-quality-gates.yml's - // `:ci` (architectureCheck). The fileserver workflow's filtered second run was removed (review - // BUILD-중복-6), and the release workflow runs only the tag-only releaseCheck. + // `:ci` (architectureCheck), and the release workflow runs only the tag-only releaseCheck. assertThat(read(".github/workflows/ci-quality-gates.yml")) .as("the pull-request gate is the one place the architecture suite runs") .contains("./gradlew :ci"); - assertThat(read(".github/workflows/fileserver-pr.yml")) - .as("the fileserver PR workflow must not repeat the architecture suite") - .doesNotContain(":app-bootstrap:architectureTest") - .doesNotContain(staleSelector); - assertThat(read(".github/workflows/release.yml")) .as("the release workflow runs the tag-only checks through releaseCheck") .contains("./gradlew :releaseCheck") diff --git a/src/composition/fileserver-platform/build.gradle b/src/composition/fileserver-platform/build.gradle index b46ed6b1..d800fec8 100644 --- a/src/composition/fileserver-platform/build.gradle +++ b/src/composition/fileserver-platform/build.gradle @@ -63,14 +63,20 @@ dependencies { } // FileserverDocumentationCoverageTest reads the fileserver documents, the workflows that define the -// support-matrix jobs and the fileserver transport sources. They are inputs of `test`, or Gradle -// would call it up to date after an edit to any of them — which is the edit it exists to catch. +// support-matrix jobs, the fileserver test sources the matrix names as evidence and the fileserver +// transport sources. They are inputs of `test`, or Gradle would call it up to date after an edit to +// any of them — which is the edit it exists to catch. def repositoryRoot = rootProject.projectDir.parentFile tasks.named('test') { inputs.dir(new File(repositoryRoot, 'docs/fileserver')).withPropertyName('fileserverDocuments') .withPathSensitivity(PathSensitivity.RELATIVE) inputs.dir(new File(repositoryRoot, '.github/workflows')).withPropertyName('workflows') .withPathSensitivity(PathSensitivity.RELATIVE) + inputs.files(['application-fileserver', 'adapter/inbound/web-fileserver', 'adapter/outbound/fileserver', + 'adapter/outbound/persistence-fileserver', 'composition/fileserver-platform'] + .collect { rootProject.file("${it}/src/test/java") }) + .withPropertyName('fileserverTestSources') + .withPathSensitivity(PathSensitivity.RELATIVE) inputs.dir(rootProject.file('adapter/inbound/web-fileserver/src/main/java')).withPropertyName('transportSources') .withPathSensitivity(PathSensitivity.RELATIVE) } diff --git a/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java b/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java index 3a5dbf88..9c18cd10 100644 --- a/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java +++ b/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java @@ -5,6 +5,7 @@ import static org.assertj.core.api.Assertions.assertThatCode; import dev.caskeleton.adapter.outbound.fileserver.platform.autoconfigure.FileserverPlatformSettings; import java.io.IOException; +import java.io.UncheckedIOException; import java.nio.file.Files; import java.nio.file.Path; import java.util.ArrayList; @@ -14,6 +15,7 @@ import java.util.Map; import java.util.regex.Matcher; import java.util.regex.Pattern; import java.util.stream.Stream; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; import org.springframework.boot.context.properties.bind.BindHandler; import org.springframework.boot.context.properties.bind.Bindable; @@ -32,21 +34,45 @@ import org.springframework.core.env.StandardEnvironment; */ class FileserverDocumentationCoverageTest { - private static final Pattern CI_JOB = Pattern.compile("`(fileserver-[a-z0-9-]+)`"); + private static final String WORKFLOWS = ".github/workflows"; + private static final Pattern EVIDENCE = Pattern.compile("`([^`]+)`"); + private static final Pattern CI_JOB = Pattern.compile("fileserver-[a-z0-9-]+"); + private static final Pattern TEST_TASK = Pattern.compile("(:[a-z0-9:-]+):test"); + private static final Pattern TEST_CLASS = Pattern.compile("[A-Z][A-Za-z0-9]*Test"); private static final Pattern WORKFLOW_JOB = Pattern.compile("^ {2}([a-z0-9-]+):\\s*$"); + private static final String PROFILE_TABLE_HEADER = "| Profile | 등급 | 증거 |"; + private static final List FILESERVER_LEAVES = + List.of( + "src/application-fileserver", + "src/adapter/inbound/web-fileserver", + "src/adapter/outbound/fileserver", + "src/adapter/outbound/persistence-fileserver", + "src/composition/fileserver-platform"); private static final Pattern MAPPING_PATH = Pattern.compile("\"(/v1/[^\"]*|/internal/fileserver[^\"]*)\""); @Test - void everySupportClaimNamesAJobThatExists() throws IOException { - List claimed = - referencedCiJobs(repositoryRoot().resolve("docs/fileserver/support-matrix.md")); - List defined = definedWorkflowJobs(); + @DisplayName("지원 매트릭스의 행마다 있는 테스트·모듈·job을 증거로 적는다") + void everySupportClaimNamesEvidenceThatExists() throws IOException { + // given + Map> claims = + evidenceByProfile(repositoryRoot().resolve("docs/fileserver/support-matrix.md")); - assertThat(claimed) - .as("a support level whose evidence job does not exist is an unbacked claim") - .isNotEmpty() - .allSatisfy(job -> assertThat(defined).contains(job)); + // when + Map> unbacked = new LinkedHashMap<>(); + claims.forEach( + (profile, evidence) -> { + List missing = evidence.stream().filter(item -> !exists(item)).toList(); + if (evidence.isEmpty() || !missing.isEmpty()) { + unbacked.put(profile, evidence.isEmpty() ? List.of("(none)") : missing); + } + }); + + // then + assertThat(claims).isNotEmpty(); + assertThat(unbacked) + .as("a support level whose evidence does not exist is an unbacked claim") + .isEmpty(); } @Test @@ -201,30 +227,62 @@ class FileserverDocumentationCoverageTest { Map.entry("quota.soft-high-water", "0.70"), Map.entry("quota.hard-high-water", "0.85")); - private static List referencedCiJobs(Path supportMatrix) throws IOException { - List jobs = new ArrayList<>(); - Matcher matcher = CI_JOB.matcher(Files.readString(supportMatrix)); - while (matcher.find()) { - jobs.add(matcher.group(1)); + /** The evidence cell of every runtime-profile row, keyed by the profile it backs. */ + private static Map> evidenceByProfile(Path supportMatrix) + throws IOException { + Map> claims = new LinkedHashMap<>(); + List lines = Files.readAllLines(supportMatrix); + int header = lines.indexOf(PROFILE_TABLE_HEADER); + assertThat(header).as("the runtime-profile table header").isNotNegative(); + for (String line : lines.subList(header + 2, lines.size())) { + if (!line.startsWith("|")) { + break; + } + String[] cells = line.split("\\|", -1); + List evidence = new ArrayList<>(); + Matcher matcher = EVIDENCE.matcher(cells[3]); + while (matcher.find()) { + evidence.add(matcher.group(1)); + } + claims.put(cells[1].trim(), evidence); } - return jobs; + return claims; } /** - * Job identifiers across every fileserver workflow and the release workflow (which holds the - * certification jobs since review BUILD-계획-B2), read from the two-space indent level. + * Whether one evidence item names something real: a CI job defined in a workflow, a project whose + * {@code test} has test sources, or a test class of a fileserver leaf. */ + private static boolean exists(String evidence) { + try { + if (CI_JOB.matcher(evidence).matches()) { + return definedWorkflowJobs().contains(evidence); + } + Matcher task = TEST_TASK.matcher(evidence); + if (task.matches()) { + return Files.isDirectory( + repositoryRoot().resolve("src" + task.group(1).replace(':', '/') + "/src/test/java")); + } + if (TEST_CLASS.matcher(evidence).matches()) { + for (String leaf : FILESERVER_LEAVES) { + try (Stream files = Files.walk(repositoryRoot().resolve(leaf + "/src/test/java"))) { + if (files.anyMatch(file -> file.getFileName().toString().equals(evidence + ".java"))) { + return true; + } + } + } + } + return false; + } catch (IOException unreadable) { + throw new UncheckedIOException(unreadable); + } + } + + /** Job identifiers of every workflow, read from the two-space indent level. */ private static List definedWorkflowJobs() throws IOException { List jobs = new ArrayList<>(); - Path workflows = repositoryRoot().resolve(".github/workflows"); - try (Stream files = Files.list(workflows)) { - for (Path file : - files - .filter( - path -> - path.getFileName().toString().startsWith("fileserver-") - || path.getFileName().toString().equals("release.yml")) - .toList()) { + try (Stream files = Files.list(repositoryRoot().resolve(WORKFLOWS))) { + for (Path file : files.toList()) { for (String line : Files.readAllLines(file)) { Matcher matcher = WORKFLOW_JOB.matcher(line); if (matcher.matches()) { @@ -269,7 +327,7 @@ class FileserverDocumentationCoverageTest { private static Path repositoryRoot() { Path working = Path.of("").toAbsolutePath(); Path candidate = working; - while (candidate != null && !Files.isDirectory(candidate.resolve(".github/workflows"))) { + while (candidate != null && !Files.isDirectory(candidate.resolve(WORKFLOWS))) { candidate = candidate.getParent(); } if (candidate == null) { From 61b1d57515d6be12690f39061c121c6318e1537e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 21:55:43 +0900 Subject: [PATCH 02/10] =?UTF-8?q?fix(compose):=20dev=20overlay=EC=9D=98=20?= =?UTF-8?q?heap=20dump=EB=A5=BC=20named=20volume=EC=97=90=20=EB=91=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit dev lane overlay(src/app-bootstrap/compose-lanes/dev.yaml)가 heap dump 폴더를 bind mount `./tmp/heap-dumps`로 두었다. Docker가 그 폴더를 root 소유로 만들어, compose lane을 돌린 git worktree를 일반 사용자가 지우지 못했다(`git worktree remove`가 Permission denied). 그래서 operate.md 4.1절에 컨테이너로 폴더를 지우는 우회 문장이 있었다. named volume `heap-dumps`로 바꾼다. dump는 컨테이너가 사라져도 남고, `docker compose cp`로 꺼낸다. 우회 문장을 지운다. 버린 것: bind mount에 사용자 uid를 맞추기(이미지·환경마다 다르다). 검증: desktop PR 단계(`verifyComposeProfiles`가 렌더링된 모델의 mount 대상 중복을 본다)와 nightly compose smoke. --- docs/work/operate.md | 2 +- src/app-bootstrap/compose-lanes/dev.yaml | 15 ++++++++++----- .../compose/ComposeMergeCharacterizationTest.java | 8 ++++---- 3 files changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/work/operate.md b/docs/work/operate.md index 2bc00406..27e9e5d9 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -61,7 +61,7 @@ git worktree remove ~/workspace/<작업 이름> - 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다. 같은 worktree의 다음 실행이 결과 XML을 덮어쓰니, 명령이 끝날 때마다 그 태스크의 `build/test-results/<태스크>/`를 로그 폴더로 복사한다(세는 법은 [reference/gates.md](reference/gates.md) 4절). - RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다. - workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다. 도구가 실행 때 받는 데이터(trivy 취약점 DB)는 설치가 아니다. 받아도 되고, 받은 DB의 갱신 시각을 기록에 적는다. -- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(dev lane overlay `src/app-bootstrap/compose-lanes/dev.yaml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`compose.yaml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`. +- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. - Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다. **push 전에 검증하기.** push한 커밋은 고쳐 쓰지 않는다. 그래서 커밋 본문에 desktop 결과를 쓰거나 push가 허용되지 않았으면, 커밋 전에 바꾼 것을 패치로 보내 같은 트리에서 돌린다. diff --git a/src/app-bootstrap/compose-lanes/dev.yaml b/src/app-bootstrap/compose-lanes/dev.yaml index 38456b5c..55a303a2 100644 --- a/src/app-bootstrap/compose-lanes/dev.yaml +++ b/src/app-bootstrap/compose-lanes/dev.yaml @@ -74,21 +74,23 @@ services: disable: true # Do not restart automatically so crash loops stay visible. restart: "no" - # Optional: mount heap dump directory to host for dev analysis. + # Heap dumps survive the container that wrote them. # The base declares /var/tmp/heap as a tmpfs, which is right for an ephemeral runtime and wrong # for dev: a heap dump written into a tmpfs dies with the container that produced it, which is # the one moment somebody wants the file. Compose refuses to have both, and correctly — it will # not silently pick one — so the tmpfs list is replaced rather than appended to. # + # A named volume, not a bind mount of ./tmp/heap-dumps: Docker created that folder as root inside + # the checkout, and a git worktree holding it could not be removed without root. Copy a dump out + # with `docker compose cp app:/var/tmp/heap/ .` or read it from the volume. + # # `!override` needs Compose >= 2.24.4. An empty sequence is not assumed to delete the base # sequence by itself; scripts/verify-compose-profile-contracts.sh checks mount-target uniqueness # in the merged model, which is what actually proves the collision is gone. volumes: - - type: bind - source: ./tmp/heap-dumps + - type: volume + source: heap-dumps target: /var/tmp/heap - bind: - create_host_path: true # The same network the shared infrastructure lives on. The local stack (now compose.yaml) joins it and the dev # overlay did not, so a dev lane that started PostgreSQL beside the application put the two on # different networks: `UnknownHostException: db`, from a container that was running and healthy @@ -102,3 +104,6 @@ networks: # Defined in compose.yaml, where the services that share it live. caskeleton-infra: external: false + +volumes: + heap-dumps: diff --git a/src/app-bootstrap/src/integrationTest/java/dev/caskeleton/bootstrap/compose/ComposeMergeCharacterizationTest.java b/src/app-bootstrap/src/integrationTest/java/dev/caskeleton/bootstrap/compose/ComposeMergeCharacterizationTest.java index 2091cfa5..9469a0d0 100644 --- a/src/app-bootstrap/src/integrationTest/java/dev/caskeleton/bootstrap/compose/ComposeMergeCharacterizationTest.java +++ b/src/app-bootstrap/src/integrationTest/java/dev/caskeleton/bootstrap/compose/ComposeMergeCharacterizationTest.java @@ -17,10 +17,10 @@ import org.junit.jupiter.api.Test; * *

A stack that cannot merge has no failure mode short of total: nothing starts, and the error * arrives at the moment somebody most wants the environment. The dev stack was in exactly that - * state — the base declares {@code /var/tmp/heap} as a tmpfs, the dev overlay bind-mounts the same - * target so heap dumps survive on the host, and the overlay\'s {@code tmpfs: []} merged with the - * base list instead of replacing it. {@code !override} replaces it, and the merged model is checked - * for duplicate mount targets rather than the fix being assumed from the syntax. + * state — the base declares {@code /var/tmp/heap} as a tmpfs, the dev overlay mounts a volume at + * the same target so heap dumps survive the container, and the overlay\'s {@code tmpfs: []} merged + * with the base list instead of replacing it. {@code !override} replaces it, and the merged model + * is checked for duplicate mount targets rather than the fix being assumed from the syntax. */ class ComposeMergeCharacterizationTest { From b9866407cabe9d9716826177eeaeef3727f6a315 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 21:55:43 +0900 Subject: [PATCH 03/10] =?UTF-8?q?fix(notification):=20=EC=95=8C=EB=A6=BC?= =?UTF-8?q?=20=EB=AC=B8=EC=84=9C=EC=99=80=20NOTIF-ADR=EC=9D=84=20test?= =?UTF-8?q?=EC=9D=98=20=EC=9E=85=EB=A0=A5=EC=9C=BC=EB=A1=9C=20=EC=84=A0?= =?UTF-8?q?=EC=96=B8=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit NotificationReleaseGateTest(알림 leaf의 `test`)는 docs/notification의 문서와 docs/adr의 NOTIF-ADR 넷이 있는지 본다. 그 파일들이 test 태스크의 입력이 아니어서, ADR을 옮기거나 지워도 Gradle이 태스크를 up-to-date나 캐시로 끝내고 시험이 다시 돌지 않았다. 지운 notification-platform.yml의 경로 필터가 docs/adr/로 옮긴 ADR을 못 보던 것과 같은 빈틈이다. 두 경로를 test의 입력으로 선언한다. 이 시험은 `ci` → `prCheck` 안에서 경로 필터 없이 매 PR 돈다(--dry-run 계획으로 확인). 검증: desktop PR 단계. --- src/adapter/outbound/notification/build.gradle | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/adapter/outbound/notification/build.gradle b/src/adapter/outbound/notification/build.gradle index b252150f..5c06ddfd 100644 --- a/src/adapter/outbound/notification/build.gradle +++ b/src/adapter/outbound/notification/build.gradle @@ -108,6 +108,18 @@ apiSurface { ] } +// NotificationReleaseGateTest (pull-request `test`) requires the notification documents and the +// NOTIF-ADR records to exist. They are inputs of `test`, or a moved or deleted ADR would leave the +// task up to date and its absence unseen — the path filter of the workflow that used to run the +// notification tests had the same blind spot once the ADRs moved to docs/adr/. +tasks.named('test') { + inputs.dir(rootProject.file('../docs/notification')).withPropertyName('notificationDocuments') + .withPathSensitivity(PathSensitivity.RELATIVE) + inputs.files(fileTree(rootProject.file('../docs/adr')) { include 'NOTIF-ADR-*' }) + .withPropertyName('notificationAdrs') + .withPathSensitivity(PathSensitivity.RELATIVE) +} + // NotificationEvidenceVerifierTest's repository case holds docs/notification/evidence-manifest.json, // the support matrix it grades and the evidence files it names to each other. A comparison with // repository documents, so it runs in this leaf's `mainCheck`, not in the pull-request `test` From d46bab965914c420e4d80b4149a17b95de277131 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 21:55:43 +0900 Subject: [PATCH 04/10] =?UTF-8?q?ci!:=20workflow=EB=A5=BC=20pr=C2=B7main?= =?UTF-8?q?=C2=B7release=20=EC=85=8B=EC=9C=BC=EB=A1=9C=20=EC=A0=91?= =?UTF-8?q?=EA=B3=A0=20=EB=8B=A8=EA=B3=84=20job=20=EB=AA=A8=EC=96=91?= =?UTF-8?q?=EB=A7=8C=20=EA=B2=80=EC=82=AC=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로 나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations· TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸 모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는 한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절). 소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다. - .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와 `./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities` (trivy), 필수 검사 하나 `done`. - main.yml: push마다 mainCheck·integrationCheck·build-logic 시험· configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서 PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos, jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck. - release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea 레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명 앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은 `needs: jpa-release-gate`가 대신한다. - 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 + 저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다. - verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의 계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로 바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에 선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른 run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는 needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른 working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job 하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다 (build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를 TestKit 시험으로 둔다. - scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업 트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의 손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트 포워더·configuration cache 스크립트다. - workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을 .gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다. - 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조, docs/upgrade B-57~B-61. 버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수 없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기 (결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다. 위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지 않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를 다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다. `.github/workflows/messaging-certification.yml`은 메시징 분리 작업이 지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이 없어 실제 태그로는 돌려 보지 않았다. BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법, 릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity- review.md B-57~B-61을 따른다. --- .claude/skills/desktop-gates/SKILL.md | 17 +- .gitea/actions/setup-java-gradle/action.yml | 26 + .gitea/workflows/main.yml | 306 +++ .gitea/workflows/pr.yml | 66 + .gitea/workflows/release.yml | 299 +++ .github/CODEOWNERS | 2 + .github/actions/setup-gradle-java/action.yml | 41 - .github/dependency-review-config.yml | 18 - .github/dependency-vulnerability-policy.md | 28 +- .github/scripts/install-jq.sh | 50 - .github/workflows/build-logic.yml | 37 - .github/workflows/ci-quality-gates.yml | 85 - .../workflows/dependency-vulnerability.yml | 180 -- .github/workflows/docs-check.yml | 28 - .github/workflows/fileserver-nightly.yml | 38 - .github/workflows/integration-main.yml | 268 --- .github/workflows/jpa-next.yml | 75 - .github/workflows/jpa-nightly.yml | 38 - .github/workflows/notification-platform.yml | 77 - .../object-storage-qualification.yml | 38 - .github/workflows/pr-adapters.yml | 262 --- .github/workflows/redis-sdk-topology.yml | 202 -- .github/workflows/release.yml | 676 ------- AGENTS.md | 7 +- docs/README.md | 6 +- docs/capability-status.md | 2 +- docs/ci-cd/boundary.md | 15 +- docs/ci-cd/template-vs-consumer.md | 20 +- docs/httpclient/performance-baseline.md | 2 +- docs/httpclient/repository-adaptation.md | 2 +- docs/jpa/experimental-support-matrix.md | 2 +- docs/jpa/repository-adaptation.md | 4 +- docs/jpa/support-matrix.md | 10 +- docs/upgrade/2026-11-maturity-review.md | 14 + docs/work/delegate.md | 2 +- docs/work/operate.md | 18 +- docs/work/reference/gates.md | 127 +- scripts/check-docs.py | 6 +- scripts/check-repo-layout.py | 3 +- scripts/ci/forward-ports.py | 48 + scripts/ci/redis-topology.sh | 65 + scripts/ci/trivy-scan.sh | 108 ++ scripts/ci/verify-configuration-cache.sh | 26 + scripts/verify.sh | 190 ++ src/README.md | 22 +- src/adapter/outbound/cache-redis/README.md | 2 +- src/adapter/outbound/cache-redis/build.gradle | 6 +- src/adapter/outbound/httpclient/build.gradle | 4 +- .../outbound/persistence-jpa/build.gradle | 2 +- .../next/Hibernate8CompatibilityTest.java | 3 +- .../next/Jpa4CompatibilityTest.java | 3 +- .../next/PostgreSql19CompatibilityTest.java | 3 +- .../testkit/JpaReleaseRenderingTest.java | 14 +- .../testkit/release/JpaReleaseRendering.java | 35 +- .../outbound/redis-sdk/compose/README.md | 6 +- src/app-bootstrap/build.gradle | 4 +- .../DeveloperExperienceContractTest.java | 58 +- src/build-logic/AGENTS.md | 14 +- src/build-logic/README.md | 4 +- src/build-logic/build.gradle | 4 - .../redis/RedisTopologyLanePlugin.java | 2 +- .../buildlogic/strictlane/ShellScript.java | 1659 ----------------- .../strictlane/StrictLaneStagesExtension.java | 86 +- .../strictlane/StrictLaneStagesPlugin.java | 454 +++-- .../buildlogic/strictlane/TaskSelectors.java | 214 --- .../strictlane/WorkflowGradleInvocations.java | 1410 -------------- .../strictlane/GradleCommandLineTest.java | 162 -- .../StrictLaneStagesFunctionalTest.java | 903 +++------ .../strictlane/TaskSelectorsTest.java | 71 - .../WorkflowGradleInvocationsTest.java | 1581 ---------------- src/build.gradle | 72 +- .../fileserver-platform/build.gradle | 2 +- .../FileserverDocumentationCoverageTest.java | 2 +- src/gradle.properties | 4 +- src/gradle/libs.versions.toml | 2 +- 75 files changed, 1995 insertions(+), 8347 deletions(-) create mode 100644 .gitea/actions/setup-java-gradle/action.yml create mode 100644 .gitea/workflows/main.yml create mode 100644 .gitea/workflows/pr.yml create mode 100644 .gitea/workflows/release.yml delete mode 100644 .github/actions/setup-gradle-java/action.yml delete mode 100644 .github/dependency-review-config.yml delete mode 100644 .github/scripts/install-jq.sh delete mode 100644 .github/workflows/build-logic.yml delete mode 100644 .github/workflows/ci-quality-gates.yml delete mode 100644 .github/workflows/dependency-vulnerability.yml delete mode 100644 .github/workflows/docs-check.yml delete mode 100644 .github/workflows/fileserver-nightly.yml delete mode 100644 .github/workflows/integration-main.yml delete mode 100644 .github/workflows/jpa-next.yml delete mode 100644 .github/workflows/jpa-nightly.yml delete mode 100644 .github/workflows/notification-platform.yml delete mode 100644 .github/workflows/object-storage-qualification.yml delete mode 100644 .github/workflows/pr-adapters.yml delete mode 100644 .github/workflows/redis-sdk-topology.yml delete mode 100644 .github/workflows/release.yml create mode 100644 scripts/ci/forward-ports.py create mode 100755 scripts/ci/redis-topology.sh create mode 100755 scripts/ci/trivy-scan.sh create mode 100755 scripts/ci/verify-configuration-cache.sh create mode 100755 scripts/verify.sh delete mode 100644 src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ShellScript.java delete mode 100644 src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TaskSelectors.java delete mode 100644 src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java delete mode 100644 src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/GradleCommandLineTest.java delete mode 100644 src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/TaskSelectorsTest.java delete mode 100644 src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java diff --git a/.claude/skills/desktop-gates/SKILL.md b/.claude/skills/desktop-gates/SKILL.md index 1ec3abdd..49a2ea8d 100644 --- a/.claude/skills/desktop-gates/SKILL.md +++ b/.claude/skills/desktop-gates/SKILL.md @@ -5,13 +5,12 @@ description: 이 repo에서 Gradle·Docker·테스트·게이트·성능 측정 # desktop에서 게이트 돌리기 -정본은 `docs/work/operate.md` 4.1절(실행 위치)·4.2절(기록)과 `docs/work/reference/gates.md`(무엇을 돌릴지)다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다. CI 재편에서 검증 진입점 스크립트(설계 이름 `verify.sh`)가 생기면 이 절차를 그 스크립트가 대신한다. +정본은 `docs/work/operate.md` 4.1절(실행 위치)·4.2절(기록)과 `docs/work/reference/gates.md`(무엇을 돌릴지)다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다. -1. 돌릴 게이트를 고른다: 바꾼 것에 맞는 게이트는 `gates.md` 2절, PR·main 단계 묶음은 3절이다. leaf의 Gradle path는 registry `gradle_path`에서 읽는다. -2. 트리를 정한다. push가 허용됐으면 push한 브랜치, 아니면 4.1절 「push 전에 검증하기」대로 기준 커밋 + 패치를 보내고 노트북 `git write-tree`와 desktop `git write-tree`가 같은지 본다. -3. desktop에 따로 worktree를 만든다. 기존 checkout의 브랜치와 `stash@{0}`는 건드리지 않는다. 로그 폴더는 `~/<작업 이름>-logs/`다. -4. `uptime`을 적고, 게이트마다 `flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?"`로 하나씩 돌린다. 증거로 쓸 실행은 `--rerun`이나 `--no-build-cache`로 캐시 결과를 쓰지 않는다(`gates.md` 4절). -5. 테스트 수는 결과 XML 사본에서 센다(`gates.md` 4절). 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다(`operate.md` 7절). -6. 다른 세션이 잠금을 쥐고 있으면 기다린다. 기다리는 동안 다른 일을 하고, 잠금 대기는 완료나 첫 실패에서 끝나는 대기 하나로 둔다. -7. 끝나면 compose를 내리고(`docker compose … down`) worktree를 지운다. root 소유 폴더가 남으면 4.1절의 정리법을 쓴다. -8. 보고에는 게이트, rc, 직전 부하, 로그 경로, 대상 트리 해시, 캐시 여부를 적는다. +1. 돌릴 단계를 고른다: 바꾼 것에 맞는 게이트는 `gates.md` 2절, 단계 묶음은 1절의 `scripts/verify.sh` 단계(`leaf `·`pr`·`main`·`nightly`·`release`·`round`)다. leaf의 Gradle path는 registry `gradle_path`에서 읽는다. +2. `scripts/verify.sh <단계> [--no-cache]`를 노트북 저장소 루트에서 돌린다. 스크립트가 커밋하지 않은 변경까지 패치로 desktop에 보내고, 기준 커밋에서 새 worktree를 만들어 트리 해시를 맞추고, 공유 잠금 `flock /tmp/claude-gates/heavy.lock` 아래에서 돌리고, 로그를 desktop `~/<브랜치 이름>-logs/<단계>.log`에 남기고, worktree를 지운다. 오래 걸리는 단계는 background로 두고 끝나면 알림을 받는다. +3. 증거로 쓸 실행은 `--no-cache`로 돌린다(`gates.md` 3절). 로그의 `FROM-CACHE`가 0인지 본다. +4. 테스트 수는 `verify.sh`가 worktree를 지우기 전에 결과 XML에서 세어 로그 끝에 남긴다(`verify: 테스트 tests=…`). 명령별로 나눈 수가 필요하면 단계 밖에서 손으로 돌려 `gates.md` 4절대로 센다. 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다(`operate.md` 7절). +5. 다른 세션이 잠금을 쥐고 있으면 기다린다. 기다리는 동안 다른 일을 하고, 잠금 대기는 완료나 첫 실패에서 끝나는 대기 하나로 둔다. +6. 단계 밖의 명령(lane 하나, `spotlessApply`, 탐침)은 `operate.md` 4.1절 「절차」대로 손으로 하고, `--no-daemon`을 붙인다(오래 사는 daemon이 여러 worktree를 받으면 compiler worker가 쌓여 desktop 메모리를 채운다). desktop 기존 checkout의 브랜치와 `stash@{0}`는 건드리지 않는다. +7. 보고에는 단계, rc, 직전 부하(로그 첫 줄), 로그 경로, 대상 트리 해시, 캐시 여부를 적는다. diff --git a/.gitea/actions/setup-java-gradle/action.yml b/.gitea/actions/setup-java-gradle/action.yml new file mode 100644 index 00000000..00aba415 --- /dev/null +++ b/.gitea/actions/setup-java-gradle/action.yml @@ -0,0 +1,26 @@ +name: Set up Java and Gradle +description: >- + Installs the repository's pinned Temurin JDK, then configures Gradle through the official + setup-gradle action, which validates every checked-in wrapper jar and manages the Gradle cache. + +# A Gradle job is two lines: checkout, then this action. `actions/checkout` cannot move in here: a +# `./.gitea/actions/...` reference is resolved from the checked-out working copy, so this file does +# not exist until checkout has run. +# +# Full URLs, because the runner resolves a bare `owner/name` against its own default action host, +# and a pinned commit SHA, the only immutable action reference. The JDK is the version in +# .tool-versions under the name Temurin publishes it (`+10.0.LTS`); setup-java rejects `+10`. + +runs: + using: composite + steps: + - uses: https://github.com/actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # actions/setup-java@v4.7.1 + with: + distribution: temurin + java-version: "21.0.11+10.0.LTS" + # Gradle's own caching, not setup-java's `cache: gradle`. The two cache the same directory with + # different keys, and running both is how a job restores one cache and saves the other. + - uses: https://github.com/gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # gradle/actions@v6 + with: + build-scan-publish: false + cache-read-only: ${{ github.ref != 'refs/heads/main' }} diff --git a/.gitea/workflows/main.yml b/.gitea/workflows/main.yml new file mode 100644 index 00000000..be32b441 --- /dev/null +++ b/.gitea/workflows/main.yml @@ -0,0 +1,306 @@ +# Main-branch stage: is the merged state healthy. It does not block a merge — the merge has already +# happened — but it fails loudly, after the change it reports on (owner decision 2026-09-16). +# +# On every push to main: the main stage, the container lanes, the build-logic tests, configuration +# cache, links and the dependency scan. Nightly (and on a manual run) also the jobs that need a matrix +# or an environment the stage tasks do not have, and last the performance lanes, which need a +# machine nothing else is using: the runner takes one job at a time, and `needs` puts them after +# every other heavy job (owner decision 2026-11-07). +# +# Which lanes a stage means is decided by its Gradle task (src/build.gradle). The stage jobs +# (`main`, `integration`, `performance`) run it as one line; `verifyStrictLaneStages` fails a pull +# request that changes that line, its condition, or adds a way for it to pass quietly. +name: main + +on: + push: + branches: [main] + schedule: + # 04:00 KST. grpc-library runs at 03:00 and messaging-library at 03:30 on the same runner. + - cron: "0 19 * * *" + workflow_dispatch: + inputs: + run_protected_aws: + description: Also run the protected AWS object-storage lane (needs the sandbox secrets) + type: boolean + default: false + +permissions: + contents: read + +concurrency: + group: main-${{ github.ref }} + cancel-in-progress: false + +defaults: + run: + working-directory: src + +env: + # Reuse would hand one lane a container another lane had already faulted. + TESTCONTAINERS_REUSE_ENABLE: "false" + +jobs: + # Environment contract, full-boot qualification, public-path baseline, transport and messaging + # qualification, document-contract lanes, test-code analysis, the feature generator round trip. + # `--continue`: one failed lane must not hide the others. + main: + runs-on: ubuntu-latest + timeout-minutes: 120 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :mainCheck --continue + + # Every integration-category strict lane: real PostgreSQL, MongoDB, Kafka, MinIO, nginx, Toxiproxy. + # A lane joins by declaring `integration()`; no line here names it. Lanes that need an input this + # job does not have are explicitOnly and named in the output. + integration: + runs-on: ubuntu-latest + timeout-minutes: 240 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :integrationCheck --continue + + # The included build's own tests (TestKit for the convention plugins). The main task graph does + # not reach them; `ci` already runs every plugin they test (owner decision 2026-11-07: main stage). + build-logic: + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew -p build-logic test + + configuration-cache: + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: bash ../scripts/ci/verify-configuration-cache.sh + + # Every committed Markdown link, external URLs included. A documentation check, so the main stage + # (owner decision 2026-09-16); scripts/check-docs.py checks the relative links on every pull request. + links: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - name: Check committed documentation links + uses: https://github.com/lycheeverse/lychee-action@7cd0af4c74a61395d455af97419279d86aafaede # lycheeverse/lychee-action@v2.0.2 + with: + args: >- + --no-progress + --root-dir . + README.md + src/README.md + 'src/**/README.md' + 'src/**/CLAUDE.md' + 'docs/**/*.md' + '.github/**/*.md' + fail: true + + # The dependency tree against today's vulnerability database: new advisories appear without a + # commit, so main and nightly scan again what the pull request scanned. + vulnerabilities: + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - run: bash scripts/ci/trivy-scan.sh filesystem + working-directory: . + + # Experimental by design: the result is reported, never used to block anything. + http3-experimental: + runs-on: ubuntu-latest + timeout-minutes: 30 + continue-on-error: true + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true + + # --------------------------------------------------------------------------------------------- + # Nightly and manual runs only. + + # The platform contract on every Stable PostgreSQL major, one major per job: the integration stage + # runs the lane once, on the default major. JpaReleaseRenderingTest holds this list to the release + # registry's Stable majors (src/adapter/outbound/persistence-jpa/release/release-registry.json). + jpa-postgresql: + if: ${{ github.event_name != 'push' }} + runs-on: ubuntu-latest + timeout-minutes: 60 + strategy: + fail-fast: false + matrix: + postgresql: ["16", "17", "18"] + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest -Pjpa.matrix.versions=${{ matrix.postgresql }} + + # One HTTP transport per job, so a transport that stops satisfying the shared contract fails on its + # own row. `ci` runs the lane once over both. + httpclient-transport: + if: ${{ github.event_name != 'push' }} + runs-on: ubuntu-latest + timeout-minutes: 30 + strategy: + fail-fast: false + matrix: + transport: [apache, jdk] + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :adapter:outbound:httpclient:httpClientStableContractTest -Phttpclient.contract.transports=${{ matrix.transport }} + + # Sentinel promotion, Cluster redirects and TLS against real servers, every supported version. + # docs/redis/support-matrix.md says which lane produced which evidence; the job log carries the + # commit, the server version and the image digest. + redis-topology: + if: ${{ github.event_name != 'push' }} + runs-on: ubuntu-latest + timeout-minutes: 30 + strategy: + fail-fast: false + matrix: + include: + - { topology: standalone, redis: "7.2" } + - { topology: standalone, redis: "7.4" } + - { topology: standalone, redis: "8.2" } + - { topology: sentinel, redis: "7.2" } + - { topology: sentinel, redis: "7.4" } + - { topology: sentinel, redis: "8.2" } + - { topology: cluster, redis: "7.2" } + - { topology: cluster, redis: "7.4" } + - { topology: cluster, redis: "8.2" } + - { topology: tls, redis: "7.4" } + - { topology: tls, redis: "8.2" } + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: bash scripts/ci/redis-topology.sh ${{ matrix.topology }} ${{ matrix.redis }} + working-directory: . + + # The one fileserver environment a pull request cannot provide: a real NFSv4 server. + fileserver-nfs-ambiguity: + if: ${{ github.event_name != 'push' }} + runs-on: ubuntu-latest + timeout-minutes: 45 + env: + FILESERVER_NFS_TESTS: "true" + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: docker compose -f adapter/outbound/fileserver/compose/nfs/compose.yml up -d --wait + - run: ./gradlew :adapter:outbound:fileserver:test --tests '*NfsAmbiguityIntegrationTest' + - if: ${{ always() }} + run: docker compose -f adapter/outbound/fileserver/compose/nfs/compose.yml down -v + + # The notification fault, race and restart suites run again on their own: one green run says least + # about exactly these. + notification-chaos: + if: ${{ github.event_name != 'push' }} + runs-on: ubuntu-latest + timeout-minutes: 60 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - name: Ambiguity and fault harness + run: ./gradlew :adapter:outbound:notification:test --tests '*ChaosSecurity*' --tests '*CrossProviderContractSuite*' --rerun + - name: Concurrency and rotation races + run: ./gradlew :adapter:outbound:notification:test --tests '*ConcurrencyTest' --tests '*ProviderRuntimeStateTest' --rerun + - name: Restart recovery and lease fencing (real PostgreSQL) + run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest :adapter:outbound:persistence-jpa:jpaPlatformFailureTest + # A filter that matches nothing passes. Each filter above names classes that exist today; if + # one is renamed the job fails rather than quietly stops covering it. + - name: Every named suite actually ran + run: | + for suite in ChaosSecurity CrossProviderContractSuite ConcurrencyTest ProviderRuntimeStateTest; do + find . -path '*/build/test-results/*' -name "*${suite}*.xml" | grep -q . || { + echo "no test results for ${suite}: the filter matched nothing" >&2 + exit 1 + } + done + + # Advisory probes for the next JPA, Hibernate and PostgreSQL majors. The targets are not resolvable + # yet, so each records NOT_EXECUTABLE with its reason instead of implying compatibility evidence. + # JpaReleaseRenderingTest requires every Experimental PostgreSQL major to be the `target` here. + jpa-next: + if: ${{ github.event_name != 'push' }} + runs-on: ubuntu-latest + timeout-minutes: 60 + continue-on-error: true + strategy: + fail-fast: false + matrix: + include: + - id: jakarta-persistence-4 + target: Jakarta Persistence 4 + test: "*Jpa4CompatibilityTest" + reason: the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it + - id: hibernate-8 + target: Hibernate 8 + test: "*Hibernate8CompatibilityTest" + reason: Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it + - id: postgresql-19 + target: PostgreSQL 19 + test: "*PostgreSql19CompatibilityTest" + reason: no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :adapter:outbound:persistence-jpa:test --tests '${{ matrix.test }}' --rerun + - if: ${{ always() }} + run: | + echo "${{ matrix.target }} compatibility is NOT_EXECUTABLE (${{ github.sha }}): ${{ matrix.reason }}" + + # The protected AWS lane, only on a manual run that asks for it: it needs the sandbox secrets. + object-storage-aws: + if: ${{ github.event_name == 'workflow_dispatch' && inputs.run_protected_aws }} + runs-on: ubuntu-latest + timeout-minutes: 30 + env: + OBJECT_STORAGE_AWS_QUALIFICATION_ENABLED: "true" + OBJECT_STORAGE_AWS_BUCKET: ${{ secrets.OBJECT_STORAGE_AWS_BUCKET }} + OBJECT_STORAGE_AWS_REGION: ${{ secrets.OBJECT_STORAGE_AWS_REGION }} + OBJECT_STORAGE_AWS_EXPECTED_OWNER: ${{ secrets.OBJECT_STORAGE_AWS_EXPECTED_OWNER }} + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :adapter:outbound:objectstorage:objectStorageAwsQualificationTest + + # Every blocking Compose runtime lane, on the qualification image (src/Dockerfile + # COMPOSITION=qualification: every capability module present). + compose-smoke: + if: ${{ github.event_name != 'push' }} + runs-on: ubuntu-latest + timeout-minutes: 180 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - run: bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json + working-directory: . + + # Load, slow-client, shutdown, pool and resource bounds. Last, after every other heavy job of the + # run, so the bounds are measured on a runner that is not building something else. + performance: + needs: + - main + - integration + - build-logic + - configuration-cache + - jpa-postgresql + - httpclient-transport + - redis-topology + - fileserver-nfs-ambiguity + - notification-chaos + - compose-smoke + if: ${{ !cancelled() && github.event_name != 'push' }} + runs-on: ubuntu-latest + timeout-minutes: 120 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :performanceCheck --continue diff --git a/.gitea/workflows/pr.yml b/.gitea/workflows/pr.yml new file mode 100644 index 00000000..1340595e --- /dev/null +++ b/.gitea/workflows/pr.yml @@ -0,0 +1,66 @@ +# Pull-request stage. Everything here blocks a merge, and the branch protection requires one check: +# `done`. Which leaves, lanes and checks the stage means is decided by the Gradle task `prCheck` +# (src/build.gradle), not here; `verifyStrictLaneStages` fails when this job stops running it as one +# line (docs/work/reference/gates.md). +# +# The adapter container lanes are not here: they run in main.yml on every push to main (owner +# decision 2026-11-07). A change that touches an adapter runs that leaf's strict lanes on the +# desktop before it merges (docs/work/reference/gates.md 2). +name: pr + +on: + pull_request: + +permissions: + contents: read + +concurrency: + group: pr-${{ github.ref }} + cancel-in-progress: true + +defaults: + run: + working-directory: src + +env: + TESTCONTAINERS_REUSE_ENABLE: "false" + +jobs: + gradle: + runs-on: ubuntu-latest + timeout-minutes: 60 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :prCheck + # Plans every stage (--dry-run: nothing executes), so it cannot be a dependency of prCheck. + - run: ./gradlew :verifyStrictLaneStages --dry-run + + # Known High and Critical vulnerabilities and CISA KEV matches in the dependency tree. + vulnerabilities: + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - run: bash scripts/ci/trivy-scan.sh filesystem + working-directory: . + + # The one required check. A job added above joins `needs` here, and the branch protection does + # not change. + done: + needs: [gradle, vulnerabilities] + if: ${{ always() }} + runs-on: ubuntu-latest + steps: + - name: Require every job of this stage to have succeeded + working-directory: . + env: + RESULTS: ${{ needs.gradle.result }} ${{ needs.vulnerabilities.result }} + run: | + for result in ${RESULTS}; do + if [ "${result}" != success ]; then + echo "pr / done: a job of this stage ended with ${result}" + exit 1 + fi + done + echo "pr / done: every job of this stage succeeded." diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml new file mode 100644 index 00000000..c6389272 --- /dev/null +++ b/.gitea/workflows/release.yml @@ -0,0 +1,299 @@ +# Release stage: produce the deployable artifact. One workflow, because there is one deployable unit, +# `app-bootstrap`; CI does not deploy (docs/ci-cd/boundary.md). +# +# A `vMAJOR.MINOR.PATCH` tag runs everything and publishes the image to this Gitea's container +# registry, signed by digest. A manual run is the rehearsal: every gate, the image build, the SBOM +# and the image scan, and nothing that publishes or signs. +# +# Secrets (repository settings, created by the owner): PACKAGE_TOKEN, a personal access token with +# package read/write (the job token cannot publish packages); COSIGN_PRIVATE_KEY and COSIGN_PASSWORD, +# the release signing key pair's private half and its password (owner decision 2026-11-07: Gitea +# issues no OIDC token, so keyless signing cannot run here). +name: release + +on: + push: + tags: ["v*"] + workflow_dispatch: + +permissions: + contents: read + +# Never cancel a release in flight. A half-pushed manifest is worse than a slow one. +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +defaults: + run: + working-directory: src + +env: + TESTCONTAINERS_REUSE_ENABLE: "false" + +jobs: + # The tag-only checks: release provenance and the public path baseline. Not `ci` again: a tag is + # cut from a main commit the pull-request and main stages already ran on. + release: + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :releaseCheck + + # Every web lane `check` cannot reach. webAdvancedTest selects tests `:web-advanced:test` already + # runs; what it adds is failing closed when its tag selects nothing. + web-stable-release-gate: + runs-on: ubuntu-latest + timeout-minutes: 90 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :adapter:inbound:web:systemTest :adapter:inbound:web:webJettyCompatTest :adapter:inbound:web-advanced:webAdvancedTest + + websocket-stable-release-gate: + runs-on: ubuntu-latest + timeout-minutes: 60 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: >- + ./gradlew + :adapter:inbound:websocket:test + :adapter:inbound:websocket:systemTest + :adapter:inbound:websocket:websocketJettyTest + :adapter:inbound:websocket:websocketNginxTest + :adapter:inbound:websocket:websocketTransportQualificationTest + + httpclient-release-gate: + runs-on: ubuntu-latest + timeout-minutes: 60 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: >- + ./gradlew + :adapter:outbound:httpclient:test + :adapter:outbound:httpclient:spring62ApiSurfaceScan + :adapter:outbound:httpclient:spring70CompatibilityTest + :adapter:outbound:httpclient:httpClientStableContractTest + :adapter:outbound:httpclient:httpClientSecurityTest + :adapter:outbound:httpclient:httpClientFailureInjectionTest + :adapter:outbound:httpclient:httpClientPerformanceTest + + httpclient-documentation: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - run: python3 scripts/verify-httpclient-docs.py + working-directory: . + + # One job per Stable PostgreSQL major: one job for three majors was one job for one major, because + # the platform starts only the first selected version. persistence-jpa's + # release/release-registry.json owns the gate tasks (jpaReleaseQualification depends on them), and + # JpaReleaseRenderingTest holds this list to the registry's Stable majors. The image job needs this + # job, so every major has passed, in this run and on this commit, before anything is published. + jpa-release-gate: + runs-on: ubuntu-latest + timeout-minutes: 90 + strategy: + fail-fast: false + matrix: + postgresql: ["16", "17", "18"] + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew jpaReleaseQualification -Pjpa.matrix.versions=${{ matrix.postgresql }} + + jpa-registry-and-docs: + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: >- + ./gradlew :adapter:outbound:persistence-jpa:test + --tests '*JpaReleaseManifestTest' --tests '*JpaReleaseRenderingTest' --tests '*JpaReadinessRegistryTest' + + # Fileserver certification. docs/fileserver/support-matrix.md names these job ids as evidence, and + # FileserverDocumentationCoverageTest fails when a named job is missing. + fileserver-full-verification: + runs-on: ubuntu-latest + timeout-minutes: 60 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: >- + ./gradlew + :application-fileserver:check + :adapter:inbound:web-fileserver:check + :adapter:outbound:fileserver:check + :adapter:outbound:persistence-fileserver:check + :composition:fileserver-platform:check + + fileserver-documentation-gate: + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :composition:fileserver-platform:test --tests '*FileserverDocumentationCoverageTest' + + fileserver-sensitive-telemetry-scan: + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + - uses: ./.gitea/actions/setup-java-gradle + - run: ./gradlew :application-fileserver:test --tests '*FileserverObservabilityTest' + + # Build, inventory and scan the image; on a tag also push it. It waits on every evidence job: + # `needs` does not reach across workflows, so a gate in another file could still be running. + app-image-release: + needs: + - release + - web-stable-release-gate + - websocket-stable-release-gate + - httpclient-release-gate + - httpclient-documentation + - jpa-release-gate + - jpa-registry-and-docs + - fileserver-full-verification + - fileserver-documentation-gate + - fileserver-sensitive-telemetry-scan + outputs: + pinned_reference: ${{ steps.push.outputs.pinned_reference }} + runs-on: ubuntu-latest + timeout-minutes: 90 + defaults: + run: + working-directory: . + steps: + - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 + # The tag is the release identity; a tag that does not parse stops the release here. A manual + # run is a rehearsal and builds version 0.0.0, which no release tag names. + - name: Resolve the release coordinates + run: | + set -euo pipefail + if [ "${GITHUB_REF_TYPE}" = tag ]; then + if [[ ! "${GITHUB_REF_NAME}" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then + echo "release: the tag must be vMAJOR.MINOR.PATCH with no suffix; got '${GITHUB_REF_NAME}'" >&2 + exit 1 + fi + version="${BASH_REMATCH[1]}" + else + version=0.0.0 + fi + registry="${GITHUB_SERVER_URL#https://}" + repository="${registry}/$(printf '%s' "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')/caskeleton" + { + echo "REGISTRY=${registry}" + echo "RELEASE_VERSION=${version}" + echo "BUILD_VERSION=${version}+${GITHUB_SHA}" + echo "IMAGE_REPOSITORY=${repository}" + echo "SOURCE_URL=${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}" + } >> "${GITHUB_ENV}" + echo "release: ${GITHUB_REF_NAME} -> ${repository}:${version} and :sha-${GITHUB_SHA}" + # SOURCE_DATE_EPOCH is the commit time, so the image config `created` field and every history + # timestamp are a function of the commit. It does not rewrite file mtimes inside the layers; + # byte-identical layers would need the containerd image store. + - name: Build the release image + run: | + set -euo pipefail + SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)" + export SOURCE_DATE_EPOCH + DOCKER_BUILDKIT=1 docker build \ + --file src/Dockerfile \ + --tag "${IMAGE_REPOSITORY}:${RELEASE_VERSION}" \ + --tag "${IMAGE_REPOSITORY}:sha-${GITHUB_SHA}" \ + --build-arg RELEASE_VERSION="${RELEASE_VERSION}" \ + --build-arg BUILD_VERSION="${BUILD_VERSION}" \ + --build-arg GIT_SHA="${GITHUB_SHA}" \ + --build-arg SOURCE_URL="${SOURCE_URL}" \ + --label org.opencontainers.image.created="$(git log -1 --format=%cI)" \ + src + # The SBOM is printed and kept in the log before the blocking scan, so the inventory of an image + # that is refused still exists. A vulnerable image is never pushed: the push comes after. + - name: Inventory and scan the release image + run: | + set -euo pipefail + bash scripts/ci/trivy-scan.sh image "${IMAGE_REPOSITORY}:${RELEASE_VERSION}" + echo "release: SBOM image-sbom.cdx.json, $(wc -c < image-sbom.cdx.json) bytes, sha256 $(sha256sum image-sbom.cdx.json | cut -d' ' -f1)" + # Two tags, one digest. The digest recorded here is what a GitOps manifest pins; the tags exist + # so a person can find it. + - name: Push the release and revision tags + id: push + if: ${{ github.ref_type == 'tag' }} + env: + PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }} + run: | + set -euo pipefail + [ -n "${PACKAGE_TOKEN}" ] || { echo "release: PACKAGE_TOKEN is not set" >&2; exit 1; } + printf '%s' "${PACKAGE_TOKEN}" | docker login "${REGISTRY}" --username "${GITHUB_REPOSITORY_OWNER}" --password-stdin + docker push "${IMAGE_REPOSITORY}:${RELEASE_VERSION}" + docker push "${IMAGE_REPOSITORY}:sha-${GITHUB_SHA}" + pinned="$(docker image inspect --format '{{range .RepoDigests}}{{println .}}{{end}}' "${IMAGE_REPOSITORY}:${RELEASE_VERSION}" \ + | awk -v prefix="${IMAGE_REPOSITORY}@sha256:" 'index($0, prefix) == 1 { print; exit }')" + [ -n "${pinned}" ] || { echo "release: no registry digest for ${IMAGE_REPOSITORY} after push" >&2; exit 1; } + echo "pinned_reference=${pinned}" >> "${GITHUB_OUTPUT}" + echo "release: pin this in the GitOps manifest: ${pinned}" + + # Signs the pushed digest with the release key pair and verifies the signature before the release + # counts as done, so a signature a cluster would reject fails here rather than at admission. A job + # of its own, so the private key exists only in a job that checks nothing out and builds nothing. + app-image-signing: + needs: + - app-image-release + if: ${{ github.ref_type == 'tag' }} + runs-on: ubuntu-latest + timeout-minutes: 30 + defaults: + run: + working-directory: . + env: + PINNED_REFERENCE: ${{ needs.app-image-release.outputs.pinned_reference }} + steps: + # A pinned release binary with an asserted SHA-256, no action: the cosign-linux-{amd64,arm64} + # lines of the official v3.1.3 cosign_checksums.txt. The checksum file is fetched again and must + # still carry the pinned line, so a re-published asset fails the job. + - name: Install pinned cosign + run: | + set -euo pipefail + readonly COSIGN_VERSION='3.1.3' + readonly COSIGN_SHA256_AMD64='4629c757b7618056f8ddd7e2625ae9fdd94c0372a65049520bc7d9df9efc7f71' + readonly COSIGN_SHA256_ARM64='c5d324e091826b0d7a78eb16fef316450b4eb9aaec045611c08ba06f5e73220a' + readonly DOWNLOAD_BASE_URL="https://github.com/sigstore/cosign/releases/download/v${COSIGN_VERSION}" + case "$(uname -m)" in + x86_64) asset='cosign-linux-amd64'; expected="${COSIGN_SHA256_AMD64}" ;; + aarch64) asset='cosign-linux-arm64'; expected="${COSIGN_SHA256_ARM64}" ;; + *) echo "release: unsupported architecture $(uname -m)" >&2; exit 1 ;; + esac + install_dir="${RUNNER_TEMP}/cosign-${COSIGN_VERSION}" + mkdir -p "${install_dir}" + curl --fail --show-error --silent --location --retry 3 --proto '=https' --tlsv1.2 \ + "${DOWNLOAD_BASE_URL}/cosign_checksums.txt" --output "${RUNNER_TEMP}/cosign_checksums.txt" + grep -qxF "${expected} ${asset}" "${RUNNER_TEMP}/cosign_checksums.txt" \ + || { echo "release: cosign_checksums.txt no longer lists the pinned ${asset} hash" >&2; exit 1; } + curl --fail --show-error --silent --location --retry 3 --proto '=https' --tlsv1.2 \ + "${DOWNLOAD_BASE_URL}/${asset}" --output "${install_dir}/cosign" + printf '%s %s\n' "${expected}" "${install_dir}/cosign" | sha256sum -c - + chmod 0755 "${install_dir}/cosign" + echo "${install_dir}" >> "${GITHUB_PATH}" + - name: Sign the image digest and verify the signature + env: + PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }} + COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }} + COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }} + run: | + set -euo pipefail + [[ "${PINNED_REFERENCE}" =~ ^[a-z0-9.-]+/[a-z0-9._/-]+@sha256:[0-9a-f]{64}$ ]] \ + || { echo "release: app-image-release handed over no digest reference; got '${PINNED_REFERENCE}'" >&2; exit 1; } + [ -n "${COSIGN_PRIVATE_KEY}" ] || { echo "release: COSIGN_PRIVATE_KEY is not set" >&2; exit 1; } + printf '%s' "${PACKAGE_TOKEN}" | cosign login "${PINNED_REFERENCE%%/*}" --username "${GITHUB_REPOSITORY_OWNER}" --password-stdin + cosign sign --yes --key env://COSIGN_PRIVATE_KEY "${PINNED_REFERENCE}" + cosign public-key --key env://COSIGN_PRIVATE_KEY > "${RUNNER_TEMP}/cosign.pub" + cosign verify --key "${RUNNER_TEMP}/cosign.pub" "${PINNED_REFERENCE}" > /dev/null + echo "release: signed and verified ${PINNED_REFERENCE} with:" + cat "${RUNNER_TEMP}/cosign.pub" diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 71d8983a..4f02f381 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -3,6 +3,8 @@ /.trivyignore.yaml @DongHyeonka /.github/ @DongHyeonka +/.gitea/ @DongHyeonka +/scripts/ci/ @DongHyeonka /renovate.json @DongHyeonka # Public security and compatibility baselines require an explicit maintainer review. diff --git a/.github/actions/setup-gradle-java/action.yml b/.github/actions/setup-gradle-java/action.yml deleted file mode 100644 index 4417776b..00000000 --- a/.github/actions/setup-gradle-java/action.yml +++ /dev/null @@ -1,41 +0,0 @@ -name: Set up Java and Gradle -description: >- - Installs the repository's pinned Temurin JDK, then configures Gradle through the official - setup-gradle action — which validates every checked-in wrapper jar and manages the Gradle cache. - Every Gradle job used to carry the JDK block verbatim, so the JDK patch level lived in fifty-nine - places; every job also carried a separate three-line wrapper-validation step, so the pinned action - SHA lived in forty. - -# Wrapper validation is INSIDE this action now. -# -# It could not be before, and the reason was not a GitHub limitation: .github/scripts/ -# verify-gradle-wrapper.sh read every workflow job and required it to contain, literally and in this -# order, an `actions/checkout@` step, the exact three-field pinned wrapper-validation step, and then -# the Gradle invocation. That literalness was the whole guard — "this job validated the wrapper" had -# to be answerable from the workflow file alone — and it is what made the step uninlineable. -# -# That script is gone (it also byte-hashed all twelve workflow files, so a comment change needed a -# hash update, while an attacker with write access would simply have updated both). The guarantee it -# was protecting is now the official action's own: `gradle/actions/setup-gradle` validates all -# wrapper jars by default (`validate-wrappers`, default true), and the action is pinned to a full -# commit SHA here — which GitHub's own hardening guide calls the only immutable action reference. -# -# `actions/checkout` still cannot move here: a `./.github/actions/...` reference is resolved from the -# checked-out working copy, so this file does not exist until checkout has already run. A composite -# action cannot contain the step that makes itself readable. -# -# So a Gradle job is two lines — checkout, then this action. - -runs: - using: composite - steps: - - uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # actions/setup-java@v4.7.1 - with: - distribution: temurin - java-version: "21.0.11+10" - # Gradle's own caching, not setup-java's `cache: gradle`. The two cache the same directory with - # different keys, and running both is how a job restores one cache and saves the other. - - uses: gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # gradle/actions@v6 - with: - build-scan-publish: false - cache-read-only: ${{ github.ref != 'refs/heads/main' }} diff --git a/.github/dependency-review-config.yml b/.github/dependency-review-config.yml deleted file mode 100644 index 08e1eec9..00000000 --- a/.github/dependency-review-config.yml +++ /dev/null @@ -1,18 +0,0 @@ -# GitHub dependency-review configuration. The workflow guards this GitHub-only API so other forges -# use the platform-neutral Trivy filesystem snapshot instead. -fail-on-severity: high - -fail-on-scopes: - - runtime - -# Template legal posture: deny strong and network copyleft for newly introduced dependencies. -# Forks must have their legal/security owner review this organization-specific list. -deny-licenses: - - GPL-2.0-only - - GPL-2.0-or-later - - GPL-3.0-only - - GPL-3.0-or-later - - AGPL-3.0-only - - AGPL-3.0-or-later - -comment-summary-in-pr: never diff --git a/.github/dependency-vulnerability-policy.md b/.github/dependency-vulnerability-policy.md index cda1c924..73717ac7 100644 --- a/.github/dependency-vulnerability-policy.md +++ b/.github/dependency-vulnerability-policy.md @@ -1,28 +1,25 @@ # 의존성 취약점 정책 이 정책을 강제하는 것은 -[`dependency-vulnerability.yml`](workflows/dependency-vulnerability.yml), -[`dependency-review-config.yml`](dependency-review-config.yml), +[`scripts/ci/trivy-scan.sh`](../scripts/ci/trivy-scan.sh)(pull request·main·nightly workflow의 +`vulnerabilities` job과 release workflow의 이미지 job이 부른다), [`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS, [`../renovate.json`](../renovate.json)이다. ## 실행 위치와 플랫폼 경계 -정본 workflow 파일은 `.github/workflows` 아래에 있다. 지금 origin은 Gitea이고, 서버 쪽 Actions는 밖에서 -꺼져 있다. 이 통제를 커밋해도 원격 실행이 켜지거나 증명되지 않는다. 관리자가 따로 Actions를 켜고, 맞는 -runner를 주고, 필수 검사(required check)를 설정하고, code owner 리뷰를 필수로 해야 한다. +workflow는 `.gitea/workflows`의 `pr.yml`·`main.yml`·`release.yml`이고 Gitea Actions(desktop runner)에서 돈다. +`vulnerabilities` job은 pull request, `main` push, 매일 예약 실행, 손으로 부른 실행에서 돈다. pull request의 +필수 검사 `pr / done`이 그 결과를 포함한다. 외부 action은 확인한 전체 커밋 SHA로만 실행한다. 리뷰를 위해 같은 줄 주석에 바뀌지 않는 릴리스 태그를 -남긴다. GitHub dependency review는 검사 결과만 내고 PR 요약 댓글은 쓰지 않는다. 그래서 workflow 전체의 -`contents: read` 권한이 유지된다. +남긴다. 스캐너는 action이 아니라 체크섬을 고정한 릴리스 실행 파일이다. -GitHub dependency review와 dependency submission은 GitHub.com API에 기댄다. 둘은 -`github.server_url == 'https://github.com'` 조건으로 막혀 있고, Gitea에서는 일부러 건너뛴다. `trivy-fs`는 -플랫폼에 묶이지 않는, 릴리스를 막는 전체 스냅숏 검사다. pull request, `main` push, 매일 예약 실행, 손으로 -부른 실행에서 돈다. +GitHub dependency review와 dependency submission은 GitHub.com API에만 있어 2026-11-08 Gitea로 옮길 때 +지웠다. Trivy 전체 스냅숏 검사가 플랫폼에 묶이지 않는, 병합을 막는 검사다. -이미지 빌드·스캔, SBOM, 서명, provenance, 태그 릴리스는 `workflows/release.yml`이 맡는다. 이 정책은 그 -job을 다루지 않는다. +이미지 빌드·스캔, SBOM, 서명, 태그 릴리스는 `.gitea/workflows/release.yml`이 맡는다. 이미지 스캔도 같은 +스크립트(`image` 모드)와 같은 예외 파일을 쓴다. ## 심각도와 대응 @@ -34,8 +31,7 @@ job을 다루지 않는다. | Low | 알리기만 한다 | 가능한 대로 | High/Critical이 이 템플릿의 릴리스 기준이다. 정확한 기준과 고칠 기한은 외부 규정이 아니라 팀 정책이다. -템플릿을 받아 쓸 때 다시 검토한다. GitHub dependency review도 새로 들어온 runtime 의존성에 같은 High -기준을 쓴다. +템플릿을 받아 쓸 때 다시 검토한다. Trivy JSON 스냅숏은 CISA KEV(Known Exploited Vulnerabilities, 실제 악용이 확인된 취약점) 목록과도 대조한다. 겹치는 항목이 있으면 Trivy 심각도와 상관없이 막는다. 대조하기 전에 CI는 KEV 목록을 확인한다. @@ -63,7 +59,7 @@ runner는 다음 곳으로 HTTPS로 나갈 수 있어야 한다. - Trivy 취약점 DB(스캐너 기본값, 보통 OCI 레지스트리) - jq 릴리스(`JQ_DOWNLOAD_BASE_URL`이 내부 mirror를 가리키면 그쪽) - CISA KEV 목록(`KEV_FEED_URL`이 내부 mirror를 가리키면 그쪽) -- forge가 action을 mirror하지 않으면 GitHub action 출처 +- workflow가 전체 URL로 부르는 GitHub action 출처(`https://github.com/...`) 닫힌 네트워크에서는 고정한 Trivy·jq 산출물과 체크섬을 mirror하고, `TRIVY_DOWNLOAD_BASE_URL`과 `JQ_DOWNLOAD_BASE_URL`을 설정하고, Trivy 문서에 있는 DB mirror 환경을 설정하고, `KEV_FEED_URL`을 설정한다. diff --git a/.github/scripts/install-jq.sh b/.github/scripts/install-jq.sh deleted file mode 100644 index 92f0f62e..00000000 --- a/.github/scripts/install-jq.sh +++ /dev/null @@ -1,50 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -readonly JQ_VERSION='1.8.1' -readonly JQ_SHA256_AMD64='020468de7539ce70ef1bceaf7cde2e8c4f2ca6c3afb84642aabc5c97d9fc2a0d' -readonly JQ_SHA256_ARM64='6bc62f25981328edd3cfcfe6fe51b073f2d7e7710d7ef7fcdac28d4e384fc3d4' -readonly DOWNLOAD_BASE_URL="${JQ_DOWNLOAD_BASE_URL:-https://github.com/jqlang/jq/releases/download/jq-${JQ_VERSION}}" - -: "${RUNNER_TEMP:?RUNNER_TEMP must be set by the CI runner}" -: "${GITHUB_PATH:?GITHUB_PATH must be set by the CI runner}" - -architecture="${RUNNER_ARCH:-$(uname -m)}" -case "${architecture}" in - X64 | x86_64 | amd64) - asset='jq-linux-amd64' - expected_sha256="${JQ_SHA256_AMD64}" - ;; - ARM64 | aarch64 | arm64) - asset='jq-linux-arm64' - expected_sha256="${JQ_SHA256_ARM64}" - ;; - *) - printf '::error::install-jq: unsupported runner architecture: %s\n' "${architecture}" >&2 - exit 1 - ;; -esac - -install_dir="${RUNNER_TEMP}/jq-${JQ_VERSION}/bin" -destination="${install_dir}/jq" -mkdir -p "${install_dir}" - -temporary="$(mktemp "${RUNNER_TEMP}/jq-${JQ_VERSION}.XXXXXX")" -trap 'rm -f "${temporary}"' EXIT - -curl --fail --show-error --silent --location --retry 3 \ - --proto '=https' --tlsv1.2 \ - "${DOWNLOAD_BASE_URL}/${asset}" \ - --output "${temporary}" -printf '%s %s\n' "${expected_sha256}" "${temporary}" | sha256sum -c - -chmod 0755 "${temporary}" -mv "${temporary}" "${destination}" -trap - EXIT - -printf '%s\n' "${install_dir}" >> "${GITHUB_PATH}" -installed_version="$("${destination}" --version)" -if [[ "${installed_version}" != "jq-${JQ_VERSION}" ]]; then - printf '::error::install-jq: expected jq-%s, got %s\n' "${JQ_VERSION}" "${installed_version}" >&2 - exit 1 -fi -printf 'install-jq: %s installed under RUNNER_TEMP\n' "${installed_version}" diff --git a/.github/workflows/build-logic.yml b/.github/workflows/build-logic.yml deleted file mode 100644 index beedb6dc..00000000 --- a/.github/workflows/build-logic.yml +++ /dev/null @@ -1,37 +0,0 @@ -name: build-logic - -# The included build's own tests (TestKit for the convention plugins, unit tests for the verifiers). -# The main task graph does not reach them, so they run here — and only when a pull request touches -# the included build or the catalog it reads. build-tools was folded into build-logic (review -# 2026-09-24 BUILD-O3-6). - -on: - pull_request: - paths: - - "src/build-logic/**" - - "src/gradle/**" - - ".github/workflows/build-logic.yml" - push: - branches: ["main"] - paths: - - "src/build-logic/**" - - "src/gradle/**" - - ".github/workflows/build-logic.yml" - workflow_dispatch: - -permissions: - contents: read - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -jobs: - included-builds: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Test the build-logic convention plugins - working-directory: src - run: ./gradlew -p build-logic test --stacktrace diff --git a/.github/workflows/ci-quality-gates.yml b/.github/workflows/ci-quality-gates.yml deleted file mode 100644 index 830d59cb..00000000 --- a/.github/workflows/ci-quality-gates.yml +++ /dev/null @@ -1,85 +0,0 @@ -name: ci-quality-gates - -# The pull-request gate. Everything here blocks a merge. -# -# The job list used to include `gate-matrix-lint`, which ran .github/scripts/verify-gate-matrix.sh -# against .github/ci-gate-matrix.yml: a 1,025-line register of all 107 CI controls, checked for -# consistency against the Gradle task graph and this workflow by a 568-line shell script, which was -# itself checked by contract tests in :app-bootstrap. Adding one check meant editing Gradle, a -# workflow, the matrix, the verifier's expectations and a Java test. The information was already in -# the task graph and the job graph; the matrix was a third copy that had to be kept equal to both. - -on: - pull_request: - push: - branches: ["main"] - workflow_dispatch: - -permissions: - contents: read - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -env: - TESTCONTAINERS_REUSE_ENABLE: "false" - -jobs: - quality-gates: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Export the live Gradle verification task map - working-directory: src - run: ./gradlew tasks --group verification --console=plain > ../verification-tasks.txt - - name: Upload the Gradle verification task map - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # actions/upload-artifact@v7.0.1 - with: - name: gradle-verification-task-map - path: verification-tasks.txt - if-no-files-found: error - # `ci`, not `check`. A leaf's `check` is that leaf's — compile, its tests, Spotless, Checkstyle - # and Error Prone — and the repository-wide gates are named tasks of their own: - # ci = every leaf check + architectureCheck + qualityCheck - # A leaf's `check` includes its API surface verification (owner decision 20). The main-branch - # stage (`mainCheck`: environment contract, full-boot qualification, public-path baseline, - # transport and messaging lanes, document-contract lanes) runs in integration-main.yml. - - name: Run the pull-request gate - working-directory: src - run: ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --stacktrace - # Plans every stage (`--dry-run`: nothing executes) and fails when a strict lane is in no stage - # a workflow executes, or a stage is executed by no workflow (review 2026-11-01 08-01). A new - # lane fails here, on its own pull request, instead of running nowhere after it merges. - - name: Require every strict lane to be in an executed stage - working-directory: src - run: ./gradlew :verifyStrictLaneStages --dry-run --stacktrace - - name: Verify Compose profile contracts render exactly as declared - run: bash scripts/verify-compose-profile-contracts.sh - # The repository root and src/ hold only the entries on the allow list (owner decision - # 2026-11-07): a new top-level folder is a decision, not a side effect of a feature commit. - - name: Refuse a top-level folder outside the allow list - run: python3 scripts/check-repo-layout.py - - release-gate: - needs: - - quality-gates - if: always() - runs-on: ubuntu-latest - permissions: - contents: read - steps: - - name: Require every current blocking job to succeed - env: - QUALITY_RESULT: ${{ needs.quality-gates.result }} - run: | - set -euo pipefail - for result in \ - "${QUALITY_RESULT}"; do - if [[ "${result}" != "success" ]]; then - echo "::error::release-gate: required job result was ${result}" - exit 1 - fi - done - echo "release-gate: all current blocking quality jobs succeeded." diff --git a/.github/workflows/dependency-vulnerability.yml b/.github/workflows/dependency-vulnerability.yml deleted file mode 100644 index e8f27d59..00000000 --- a/.github/workflows/dependency-vulnerability.yml +++ /dev/null @@ -1,180 +0,0 @@ -name: dependency-vulnerability - -on: - pull_request: - push: - branches: ["main"] - schedule: - - cron: "0 6 * * *" - workflow_dispatch: - -permissions: - contents: read - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -jobs: - # The compare API exists only on GitHub.com. Trivy remains the full-snapshot backstop elsewhere. - dependency-review: - if: github.event_name == 'pull_request' && github.server_url == 'https://github.com' - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - name: Review newly introduced dependencies - uses: actions/dependency-review-action@56339e523c0409420f6c2c9a2f4292bbb3c07dd3 # actions/dependency-review-action@v4.8.0 - with: - config-file: ./.github/dependency-review-config.yml - - # The submission API is also GitHub.com-only and is not required for the platform-neutral scan. - dependency-submission: - if: github.event_name == 'push' && github.server_url == 'https://github.com' - runs-on: ubuntu-latest - permissions: - contents: write - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Submit the resolved Gradle dependency graph - uses: gradle/actions/dependency-submission@748248ddd2a24f49513d8f472f81c3a07d4d50e1 # gradle/actions@v4.4.4 - with: - build-root-directory: src - - trivy-fs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - name: Install pinned Trivy under RUNNER_TEMP - env: - TRIVY_DOWNLOAD_BASE_URL: ${{ vars.TRIVY_DOWNLOAD_BASE_URL }} - run: | - set -euo pipefail - readonly TRIVY_VERSION='0.71.2' - readonly TRIVY_SHA256_AMD64='0510e71e2fd39bf863856d499c8dc19feb4e7336546394c502a8f5cc7ab27460' - readonly TRIVY_SHA256_ARM64='fe1c7106e15a5365d485b098a8c338f91e3b7ba71cb0e4963b98a3a098763cfc' - readonly DOWNLOAD_BASE_URL="${TRIVY_DOWNLOAD_BASE_URL:-https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}}" - case "${RUNNER_ARCH:-X64}" in - X64) - asset_arch='64bit' - expected_sha256="${TRIVY_SHA256_AMD64}" - ;; - ARM64) - asset_arch='ARM64' - expected_sha256="${TRIVY_SHA256_ARM64}" - ;; - *) - echo "::error::unsupported runner architecture: ${RUNNER_ARCH:-unknown}" - exit 1 - ;; - esac - install_dir="${RUNNER_TEMP}/trivy-${TRIVY_VERSION}" - archive="${RUNNER_TEMP}/trivy-${TRIVY_VERSION}.tar.gz" - mkdir -p "${install_dir}" - curl --fail --show-error --silent --location --retry 3 \ - --proto '=https' --tlsv1.2 \ - "${DOWNLOAD_BASE_URL}/trivy_${TRIVY_VERSION}_Linux-${asset_arch}.tar.gz" \ - --output "${archive}" - printf '%s %s\n' "${expected_sha256}" "${archive}" | sha256sum -c - - tar -xzf "${archive}" -C "${install_dir}" trivy - chmod 0755 "${install_dir}/trivy" - printf '%s\n' "${install_dir}" >> "${GITHUB_PATH}" - - name: Install checksum-pinned jq - env: - JQ_DOWNLOAD_BASE_URL: ${{ vars.JQ_DOWNLOAD_BASE_URL }} - run: bash .github/scripts/install-jq.sh - - - name: Block High and Critical vulnerabilities - run: | - trivy fs \ - --scanners vuln,license \ - --severity CRITICAL,HIGH \ - --exit-code 1 \ - --ignorefile .trivyignore.yaml \ - . - - - name: Report Medium and Low vulnerabilities - run: | - trivy fs \ - --scanners vuln,license \ - --severity MEDIUM,LOW \ - --exit-code 0 \ - --ignorefile .trivyignore.yaml \ - . - - - name: Produce the governed all-severity KEV input - run: | - trivy fs \ - --scanners vuln \ - --severity CRITICAL,HIGH,MEDIUM,LOW,UNKNOWN \ - --exit-code 0 \ - --ignorefile .trivyignore.yaml \ - --format json \ - --output trivy-kev.json \ - . - - - name: Fail closed on any CISA KEV match - env: - CONFIGURED_KEV_FEED_URL: ${{ vars.KEV_FEED_URL }} - run: | - set -euo pipefail - readonly DEFAULT_KEV_FEED_URL='https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json' - readonly KEV_FEED_URL="${CONFIGURED_KEV_FEED_URL:-${DEFAULT_KEV_FEED_URL}}" - if ! curl --fail --show-error --silent --location --retry 3 \ - --proto '=https' --tlsv1.2 "${KEV_FEED_URL}" --output kev.json; then - echo "::error::KEV feed unavailable; configure KEV_FEED_URL to an approved internal mirror" - exit 1 - fi - if ! jq -e ' - (.catalogVersion | type == "string" and test("\\S")) - and (.dateReleased | type == "string" and test("\\S")) - and (.count | type == "number") - and (.count > 0) - and (.count == (.count | floor)) - and (.vulnerabilities | type == "array") - and ((.vulnerabilities | length) > 0) - and (.count == (.vulnerabilities | length)) - and (all( - .vulnerabilities[]; - (.cveID | type == "string" and test("^CVE-[0-9]{4}-[0-9]{4,}$")) - )) - and (([.vulnerabilities[].cveID] | unique | length) == .count) - ' kev.json >/dev/null; then - echo "::error::KEV feed is malformed, empty, count-inconsistent, or contains invalid/duplicate cveID values" - exit 1 - fi - if ! jq -e ' - (type == "object") - and (.Results | type == "array") - and ((.Results | length) > 0) - and (all(.Results[]; type == "object")) - and (all( - .Results[]; - (.Vulnerabilities == null) or (.Vulnerabilities | type == "array") - )) - and (all( - .Results[]; - all( - .Vulnerabilities[]?; - (type == "object") - and (.VulnerabilityID | type == "string" and test("\\S")) - ) - )) - ' trivy-kev.json >/dev/null; then - echo "::error::Trivy KEV input is malformed, empty, or contains an invalid VulnerabilityID" - exit 1 - fi - jq -r '[.Results[]?.Vulnerabilities[]?.VulnerabilityID | select(type == "string")] | unique[]?' \ - trivy-kev.json | sort -u > found-cves.txt - jq -r '.vulnerabilities[]?.cveID | select(type == "string")' \ - kev.json | sort -u > kev-cves.txt - # No `|| true`. comm exits non-zero only when it cannot read or order its inputs, and - # swallowing that would have turned an unreadable CVE list into an empty intersection and - # printed "no catalog match" — a KEV cross-check that passes because it never ran. - hits="$(comm -12 found-cves.txt kev-cves.txt)" - if [[ -n "${hits}" ]]; then - echo "::error::CISA KEV-listed vulnerability found regardless of CVSS:" - printf '%s\n' "${hits}" - exit 1 - fi - echo "KEV cross-check: no catalog match." diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml deleted file mode 100644 index 932a3fa6..00000000 --- a/.github/workflows/docs-check.yml +++ /dev/null @@ -1,28 +0,0 @@ -name: docs-check - -# Document language, record head blocks, references and copied numbers (scripts/check-docs.py). -# It runs on every pull request, not on a docs/** path filter: deleting a file or a Gradle project -# in code is exactly what makes a living document point at nothing, and that change touches no -# document. The checker is plain Python outside Gradle, because the build does not parse documents. -on: - pull_request: - push: - branches: ["main"] - workflow_dispatch: - -permissions: - contents: read - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -jobs: - docs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - name: Test the document checker - run: python3 -m unittest discover -s scripts/tests - - name: Check documents - run: python3 scripts/check-docs.py diff --git a/.github/workflows/fileserver-nightly.yml b/.github/workflows/fileserver-nightly.yml deleted file mode 100644 index a4538f56..00000000 --- a/.github/workflows/fileserver-nightly.yml +++ /dev/null @@ -1,38 +0,0 @@ -name: fileserver-nightly - -# The one environment a pull request cannot provide: a real NFSv4 server. The crash, large-file and -# lease suites that used to run here with --rerun-tasks are tests of the leaves' `test`, which the -# pull-request `ci` already runs; their second run added no coverage. - -on: - workflow_dispatch: - schedule: - - cron: '0 18 * * *' - -permissions: - contents: read - -concurrency: - group: ${{ github.workflow }} - cancel-in-progress: false - -jobs: - fileserver-nfs-ambiguity: - runs-on: ubuntu-latest - timeout-minutes: 45 - env: - FILESERVER_NFS_TESTS: "true" - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Start the NFSv4 certification environment - run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d --wait - - name: Run the network-filesystem ambiguity suite - working-directory: src - run: >- - ./gradlew - :adapter:outbound:fileserver:test --tests '*NfsAmbiguityIntegrationTest' - --stacktrace - - name: Tear down the NFS environment - if: always() - run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml down -v diff --git a/.github/workflows/integration-main.yml b/.github/workflows/integration-main.yml deleted file mode 100644 index fd0a4bf6..00000000 --- a/.github/workflows/integration-main.yml +++ /dev/null @@ -1,268 +0,0 @@ -name: integration-main - -# Stage 2: is the merged state healthy. -# -# The question this stage answers is different from stage 1's. Stage 1 asks whether a diff is safe -# and blocks a merge; stage 2 asks whether main is healthy and does not — the merge has already -# happened. That difference is the point, and it is what lets a control exist without being an -# obstacle: a gate here still fails loudly, it just fails after the thing it is reporting on. -# -# Two kinds of work live here. -# -# 1. The lanes that need a machine that is not simultaneously compiling something else — load, -# abuse, graceful shutdown, TCP fault injection, resource bounds. They were web-nightly.yml and -# httpclient-nightly.yml, two module-shaped files whose only real difference was the cadence they -# shared. They now run on every push to main as well as nightly, which is strictly more often -# than before. -# -# 2. The container-backed lanes, run as the root category aggregates `:integrationCheck` and -# `:performanceCheck` rather than one workflow line per lane. A lane nobody runs is not coverage; -# it is a file that looks like coverage — and naming lanes here one by one is how fourteen of -# them came to run nowhere (review 2026-11-01 08-01). The pull-request gate's -# `verifyStrictLaneStages` now fails when a strict lane is in no stage a workflow executes. They -# are here rather than in stage 1 because every one of them starts containers or real servers, -# and the pull-request budget is minutes for the whole gate. -# -# What is deliberately NOT here: the web "Advanced capability" nightly lane that used to exist as -# web-advanced-nightly.yml (websocket-advanced-nightly.yml went with the websocket Advanced code, -# deleted 2026-09-25). The web leaf's build file says it outright — "They also run inside `test`, -# deliberately ... excluding them from the PR gate to make this lane look meaningful would mean the -# PR gate stopped covering a fifth of the leaf" — so `webAdvancedTest` selects tagged tests that -# `::test` already runs, and `::test` runs inside the root `check` on every pull request -# and every push to main. The strict lane itself survives in release.yml, where its -# fail-on-nothing-discovered guard is worth a job. - -on: - push: - branches: ["main"] - schedule: - # 03:00 UTC. Late enough that the day's merges are in, early enough that a failure is triaged - # before the next working day starts. - - cron: '0 3 * * *' - workflow_dispatch: - -permissions: - contents: read - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: false - -# The documentation-drift gates that used to run here are gone rather than demoted. -# -# They were four hand-written parsers: README shell blocks compared against the Gradle task graph, -# runbook identifiers compared against every declared Java type, a leaf count written in prose -# compared against the registry, and a Markdown table compared against the declared source sets. -# Each was a custom parser for a file format nobody controls, and each made a documentation edit a -# precondition for a build. A stale sentence is a defect, but it is not one a build can be failed -# for, and the `links` job below answers the one documentation question with a stable machine -# answer: does this link resolve. - -jobs: - # The main-branch stage of the Gradle gates (`:mainCheck`): the environment contract, full-boot - # qualification, the public-path baseline, the conditional transport - # lanes, the messaging contract lanes and each leaf's document-contract lanes. API surfaces are - # in the pull-request `check` (owner decision 20). The rest left the pull-request gate (review - # 2026-09-24 BUILD, item 12); none of them is deleted. - main-check: - runs-on: ubuntu-latest - timeout-minutes: 60 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - name: Require the committed public-path security baseline - run: | - set -euo pipefail - readonly snapshot='docs/security/public-paths-snapshot.txt' - if [[ ! -s "${snapshot}" ]] || ! git ls-files --error-unmatch "${snapshot}" >/dev/null 2>&1; then - echo "::error::${snapshot} is missing, empty or not committed; verifyPublicPathSnapshot must not create its own baseline." - exit 1 - fi - - uses: ./.github/actions/setup-gradle-java - - name: Run the main-branch stage - working-directory: src - # `--continue`: one failed lane (an external image that cannot be pulled, say) must not stop - # the other main-stage gates from reporting (review 2026-11-01 08-04). - run: ./gradlew :mainCheck --continue --warning-mode=fail --stacktrace - - # Storability only: the `--dry-run` below plans `integrationCheck` without running a lane. The - # lanes run in `integration-check`. - # - # Two questions. Can every task in the repository-wide gates be *stored* (a property of the task - # graph, so `--dry-run` answers it for all of them in seconds)? And is a stored entry *reused* while - # the build still executes its work (checked on the two core leaves)? - configuration-cache: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Require every repository-wide gate to be storable - working-directory: src - shell: bash - run: | - set -euo pipefail - for gate in ci mainCheck integrationCheck releaseCheck; do - echo "::group::${gate}" - ./gradlew "${gate}" --dry-run \ - --configuration-cache --configuration-cache-problems=fail --stacktrace - output="$({ ./gradlew "${gate}" --dry-run \ - --configuration-cache --configuration-cache-problems=fail --stacktrace; } 2>&1)" - printf '%s\n' "${output}" - echo '::endgroup::' - grep -Fq 'Reusing configuration cache.' <<<"${output}" || { - echo "::error::Gradle did not reuse the configuration cache for ${gate}." - exit 1 - } - done - - name: Store configuration cache for the everyday core build - working-directory: src - run: >- - ./gradlew - :domain-core:check - :application-core:check - --configuration-cache - --configuration-cache-problems=fail - --stacktrace - - name: Require configuration-cache reuse - working-directory: src - shell: bash - run: | - set -euo pipefail - output="$({ ./gradlew :domain-core:check :application-core:check \ - --configuration-cache --configuration-cache-problems=fail --stacktrace; } 2>&1)" - printf '%s\n' "${output}" - grep -Fq 'Reusing configuration cache.' <<<"${output}" || { - echo '::error::Gradle did not reuse the configuration cache on the second identical build.' - exit 1 - } - - # The integration stage: every integration-category strict lane (`:integrationCheck`). - # - # This job replaced six jobs that named lanes one by one — the MongoDB lanes, app-bootstrap's - # Testcontainers lane, the moved messaging/object-storage/sample contracts, six of the - # persistence-jpa PostgreSQL contracts and the httpclient fault injection. Naming lanes was how - # eleven persistence-jpa readiness lanes ended up running nowhere: a lane added to Gradle without a - # workflow line was declared, failed closed, and executed on no machine (review 2026-11-01 08-01). - # The aggregate is the list now. A lane joins it by declaring `integration()`, and the root - # `verifyStrictLaneStages` (pull-request gate) fails when a strict lane is in no stage a workflow - # executes. - # - # `--continue` so that one red lane does not hide the others: every failed lane is named in the - # same run. Lanes that need an input this job does not have (the Redis topology coordinates, the - # protected AWS sandbox) are `explicitOnly`; the aggregate prints which ones it left out. - # The container lanes take the build-wide `exclusiveRealServerLane` slot one at a time, so the - # job's length is the sum of the lanes. Split the aggregate across jobs when it outgrows its - # timeout rather than going back to naming lanes. - # - # Measured length (one local run of `:integrationCheck`, 2026-11-01, 37 lanes, images already - # pulled, machine load 24): 794 s for the command, of which the lanes' test JVMs took about 624 s - # in sum — mongoSecurityIntegrationTest 89, jpaPlatformContractTest 104, messagingCertificationTest - # 70, mongoCompatibilityTest 69, jpaPlatformMigrationTest 66, mongoFailoverTest 59, the eleven JPA - # readiness lanes 57 together, httpClientFailureInjectionTest 27, sample integrationTest 23, - # messaging starter integrationTest 21, the rest under 10 each — and the remainder was compilation - # and container start-up between lanes. A hosted runner adds cold image pulls (about 5 GB - # uncompressed across the PostgreSQL, MongoDB, Kafka, nginx, httpbin and Toxiproxy images) and a - # cold Gradle cache; expect 25 to 40 minutes (an estimate, not a measured hosted run). The 240-minute timeout is a ceiling for a hung container, not a budget. - integration-check: - runs-on: ubuntu-latest - timeout-minutes: 240 - env: - # Reuse would hand the failover lane a replica set another lane had already faulted. - TESTCONTAINERS_REUSE_ENABLE: "false" - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run every integration-category strict lane - working-directory: src - run: ./gradlew :integrationCheck --continue --stacktrace - - name: Publish the integration lane reports - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: integration-check-reports - path: src/**/build/reports/tests/ - if-no-files-found: warn - - # The performance stage: every performance-category strict lane (`:performanceCheck`) — Tomcat and - # Jetty load, slow-client and graceful shutdown, the Hikari pool contract, the httpclient pool, - # streaming, retry and rotation bounds, the MongoDB resource budget. They measure behaviour that - # degrades gradually rather than breaking outright, which is the kind of regression a per-PR gate - # never catches. This job replaced `web-load-abuse-and-shutdown`, which despite its name ran - # `:adapter:inbound:web:test` and `webJettyCompatTest` — two lanes the pull-request and main stages - # already run — and never the load lanes (review 2026-11-01 08-01), and `httpclient-performance`. - # No assertions switch: the strict-lane convention asserts every performance lane's bounds, so this - # job and a person on a workstation run the same command and get the same bounds. - performance-check: - runs-on: ubuntu-latest - timeout-minutes: 120 - env: - TESTCONTAINERS_REUSE_ENABLE: "false" - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run every performance-category strict lane - working-directory: src - run: ./gradlew :performanceCheck --continue --stacktrace - - name: Publish the performance lane reports - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: performance-check-reports - path: src/**/build/reports/tests/ - if-no-files-found: warn - - httpclient-http3-experimental: - runs-on: ubuntu-latest - timeout-minutes: 30 - # Experimental by design (D-08): the result is reported, never used to block a merge. Registered - # advisory so that "this job cannot fail the - # build" is written down rather than inferred from a field two hundred lines into a workflow. - continue-on-error: true - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Exercise the experimental HTTP/3 opt-in - working-directory: src - run: ./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true --stacktrace - - # Dynamic half of the compose-profile contract. Every blocking lane the matrix declares runs on - # main and nightly; a partial lane run is reproduction only and cannot satisfy this job. The count - # is not written here on purpose — a number in prose drifts the moment a lane is added, and the - # matrix file is the thing this job reads. - # - # The lanes boot the qualification image (src/Dockerfile COMPOSITION=qualification: every - # capability module present). The script selects it; release.yml builds the default image. - compose-runtime-smoke: - runs-on: ubuntu-latest - timeout-minutes: 180 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - name: Run every blocking Compose runtime lane - run: bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json - - name: Publish sanitized runtime-smoke evidence - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: compose-runtime-smoke-evidence - path: src/app-bootstrap/build/evidence/runtime-smoke - if-no-files-found: warn - - # Every committed Markdown link, external URLs included (lychee). A documentation check, so the main - # stage rather than the pull request (owner decision 2026-09-16); the relative links of every living - # document are also checked on each pull request by scripts/check-docs.py, which needs no network. - links: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - name: Check committed documentation links - uses: lycheeverse/lychee-action@7cd0af4c74a61395d455af97419279d86aafaede # lycheeverse/lychee-action@v2.0.2 - with: - args: >- - --no-progress - --root-dir . - README.md - src/README.md - 'src/**/README.md' - 'src/**/CLAUDE.md' - 'docs/**/*.md' - '.github/**/*.md' - fail: true diff --git a/.github/workflows/jpa-next.yml b/.github/workflows/jpa-next.yml deleted file mode 100644 index 7492dbbb..00000000 --- a/.github/workflows/jpa-next.yml +++ /dev/null @@ -1,75 +0,0 @@ -name: jpa-next - -# Advisory compatibility probes for future JPA/Hibernate/PostgreSQL majors. These targets are not -# resolved by the current build, so the artifact records NOT_EXECUTABLE rather than implying that a -# green policy test is compatibility evidence. - -on: - workflow_dispatch: - schedule: - - cron: '0 5 * * 1' - -permissions: - contents: read - -jobs: - compatibility: - strategy: - fail-fast: false - matrix: - include: - - id: jakarta-persistence-4 - target: Jakarta Persistence 4 - coordinate: jakarta.persistence:jakarta.persistence-api:4.x - test: "*Jpa4CompatibilityTest" - reason: the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it - - id: hibernate-8 - target: Hibernate 8 - coordinate: org.hibernate.orm:hibernate-core:8.x - test: "*Hibernate8CompatibilityTest" - reason: Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it - - id: postgresql-19 - target: PostgreSQL 19 - coordinate: postgres:19-alpine - test: "*PostgreSql19CompatibilityTest" - reason: no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane - runs-on: ubuntu-latest - timeout-minutes: 60 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the current-runtime policy probe - id: compatibility-probe - working-directory: src - run: >- - ./gradlew - :adapter:outbound:persistence-jpa:test - --tests '${{ matrix.test }}' - --stacktrace - - name: Record what this lane did and did not execute - if: always() - env: - PROBE_OUTCOME: ${{ steps.compatibility-probe.outcome }} - TARGET: ${{ matrix.target }} - TARGET_COORDINATE: ${{ matrix.coordinate }} - REASON: ${{ matrix.reason }} - run: | - mkdir -p compatibility-evidence - { - echo "target=${TARGET}" - echo "target-coordinate=${TARGET_COORDINATE}" - echo "status=NOT_EXECUTABLE" - echo "probe-result=${PROBE_OUTCOME}" - echo "reason=${REASON}" - echo "what-ran=the current runtime's own version canary for this target" - echo "sha=${{ github.sha }}" - } > compatibility-evidence/status.properties - echo "::notice::${TARGET} compatibility is NOT_EXECUTABLE: ${REASON}" - - name: Upload the compatibility status - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: compatibility-status-${{ matrix.id }} - path: compatibility-evidence/status.properties - retention-days: 30 - if-no-files-found: error diff --git a/.github/workflows/jpa-nightly.yml b/.github/workflows/jpa-nightly.yml deleted file mode 100644 index 91bac64f..00000000 --- a/.github/workflows/jpa-nightly.yml +++ /dev/null @@ -1,38 +0,0 @@ -name: jpa-nightly - -# The platform contract on every Stable PostgreSQL major, one major per job. The failure-injection, -# query-plan, security and pool lanes that used to have jobs here are `integration()` and -# `performance()` lanes, so `:integrationCheck` and `:performanceCheck` (integration-main.yml) run them -# on main and nightly; only the per-major fan-out is not in an aggregate. - -on: - workflow_dispatch: - schedule: - # 02:30 UTC daily. - - cron: '30 2 * * *' - -permissions: - contents: read - -concurrency: - group: ${{ github.workflow }} - cancel-in-progress: false - -jobs: - jpa-full-matrix: - runs-on: ubuntu-latest - timeout-minutes: 60 - strategy: - fail-fast: false - matrix: - postgresql: ["16", "17", "18"] - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Certify the platform against PostgreSQL ${{ matrix.postgresql }} - working-directory: src - run: >- - ./gradlew - :adapter:outbound:persistence-jpa:jpaPlatformContractTest - -Pjpa.matrix.versions=${{ matrix.postgresql }} - --stacktrace diff --git a/.github/workflows/notification-platform.yml b/.github/workflows/notification-platform.yml deleted file mode 100644 index 09071da9..00000000 --- a/.github/workflows/notification-platform.yml +++ /dev/null @@ -1,77 +0,0 @@ -name: notification-platform - -# The notification platform's chaos tier: the fault, race and restart suites run again on their own, -# nightly, because they are the ones a single green run says least about. -# -# The pull-request tier that used to be here is gone. Its seven steps ran `:application-core:test`, -# the notification leaves' `test` and `check`, and `jpaPlatformContractTest`/`jpaPlatformMigrationTest` -# — tasks the pull-request `ci` and `:integrationCheck` already run — and its path filter could not -# see the notification ADRs once they moved to docs/adr/. NotificationReleaseGateTest holds those in -# the notification leaf's `test`, which `ci` runs on every pull request. - -on: - schedule: - - cron: '0 17 * * *' - workflow_dispatch: - -permissions: - contents: read - -concurrency: - group: notification-platform-${{ github.ref }} - cancel-in-progress: true - -jobs: - nightly-chaos: - name: chaos (ambiguity, restart recovery, callback burst) - runs-on: ubuntu-latest - timeout-minutes: 60 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - # This job is named for ambiguity, restart recovery and callback burst. It used to run a - # unit-test filter and then `test` — neither of which restarts anything or bursts anything — - # so the job name was the only place those three properties existed. - - name: Ambiguity and fault harness - working-directory: src - run: ./gradlew :adapter:outbound:notification:test --tests '*ChaosSecurity*' --tests '*CrossProviderContractSuite*' --console=plain - - name: Concurrency and rotation races - working-directory: src - run: ./gradlew :adapter:outbound:notification:test --tests '*ConcurrencyTest' --tests '*ProviderRuntimeStateTest' --console=plain - - name: Restart recovery and lease fencing (real PostgreSQL) - working-directory: src - run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest :adapter:outbound:persistence-jpa:jpaPlatformFailureTest --console=plain - - name: Notification regression suite - working-directory: src - run: >- - ./gradlew - :application-core:test - :adapter:outbound:notification:test - :adapter:outbound:persistence-jpa:test - :adapter:inbound:web-notification:test - :composition:notification-platform:test - --console=plain - # A filter that matches nothing passes. Each --tests filter above names a class that exists - # today; if one is renamed the job must fail rather than quietly stop covering it. - - name: Every named suite actually ran - working-directory: src - run: | - set -euo pipefail - for suite in ChaosSecurity CrossProviderContractSuite ConcurrencyTest ProviderRuntimeStateTest; do - if ! find . -path '*/build/test-results/*' -name "*${suite}*.xml" | grep -q .; then - echo "no test results for ${suite}: the filter matched nothing and the job passed vacuously" >&2 - exit 1 - fi - done - - # There is no provider-sandbox job. It ran only on workflow_dispatch and could not succeed by - # any path: with no credentials its first step exit 1-ed, and with credentials the only test it - # ran was ProviderSandboxSmokeTest, whose body is an unconditional fail() saying a real sandbox - # call is not implemented. Its credential check read secrets.NOTIFICATION_SANDBOX_CREDENTIALS, - # which nothing in this repository consumes — the test reads NOTIFICATION_SANDBOX_ENABLED — so - # any non-empty string satisfied it and was then dropped. - # - # The unimplemented state is still stated in two places that do not depend on a workflow: - # ProviderSandboxSmokeTest itself, and the unsatisfied provider-wire-qualified claim in - # docs/notification/evidence-manifest.json, which NotificationEvidenceVerifierTest enforces in - # the notification leaf's tests. When a real sandbox call is implemented, the job comes back with it. diff --git a/.github/workflows/object-storage-qualification.yml b/.github/workflows/object-storage-qualification.yml deleted file mode 100644 index 64ef59fd..00000000 --- a/.github/workflows/object-storage-qualification.yml +++ /dev/null @@ -1,38 +0,0 @@ -name: object-storage-qualification - -# The protected AWS lane, on request only: it needs the sandbox credentials. The MinIO contract and -# fault lanes that used to have jobs here are `integration()` lanes, so `:integrationCheck` -# (integration-main.yml, main and nightly) runs them. -on: - workflow_dispatch: - inputs: - run_protected_aws: - description: Run the protected AWS sandbox qualification lane - required: true - default: false - type: boolean - -permissions: - contents: read - -env: - TESTCONTAINERS_REUSE_ENABLE: "false" - -jobs: - aws-managed-common-subset: - if: >- - github.event_name == 'workflow_dispatch' - && inputs.run_protected_aws - environment: object-storage-aws-qualification - runs-on: ubuntu-latest - env: - OBJECT_STORAGE_AWS_QUALIFICATION_ENABLED: "true" - OBJECT_STORAGE_AWS_BUCKET: ${{ secrets.OBJECT_STORAGE_AWS_BUCKET }} - OBJECT_STORAGE_AWS_REGION: ${{ secrets.OBJECT_STORAGE_AWS_REGION }} - OBJECT_STORAGE_AWS_EXPECTED_OWNER: ${{ secrets.OBJECT_STORAGE_AWS_EXPECTED_OWNER }} - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run protected AWS common-subset qualification - working-directory: src - run: ./gradlew :adapter:outbound:objectstorage:objectStorageAwsQualificationTest --stacktrace diff --git a/.github/workflows/pr-adapters.yml b/.github/workflows/pr-adapters.yml deleted file mode 100644 index da1ca9f6..00000000 --- a/.github/workflows/pr-adapters.yml +++ /dev/null @@ -1,262 +0,0 @@ -name: pr-adapters - -# Stage 1, the adapter half: the lanes a pull request must clear that `ci-quality-gates.yml` cannot -# reach. -# -# It replaces web-pr.yml, websocket-pr.yml, httpclient-contract.yml and jpa-pr.yml, which were four -# files split by module rather than by stage. Splitting by module is what made the duplication -# invisible: each file opened with its own "unit and architecture" job running -# `::test verifyCleanArchitectureDependencies`, and all four of those were already inside the -# root `check` that ci-quality-gates.yml runs on every pull request with no path filter. Four jobs, -# four runners, four Gradle configurations, zero additional coverage. They are gone; what is left -# here is only what `check` does not run. -# -# What `check` does not run, and therefore what this file is for: -# * lanes with their own source set — the servlet system contract, a second servlet container, -# a real Nginx; -# * lanes parameterised per run — one PostgreSQL major per job, one HTTP transport per job. -# Each of those genuinely cannot run inside `check`, which is the test for whether a job belongs -# here at all. -# -# Path filtering is per job rather than per workflow. The four files it replaces each carried an -# `on.pull_request.paths` list, so the whole file was skipped or run as a unit; a change touching -# web and JPA started two workflows and a change touching neither still started none. Here one -# `changes` job computes the answer once from the pull request's own diff and every lane reads it. -# The filter is a plain `git diff` rather than a filter action: this repository pins every action by -# commit SHA and adding a third-party action to compute a boolean is a supply-chain decision, not a -# convenience. - -on: - pull_request: - workflow_dispatch: - -permissions: - contents: read - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -jobs: - # One diff, read once. `workflow_dispatch` answers "everything changed", because a manual run is - # somebody asking for the lanes and there is no base ref to compare against. - changes: - runs-on: ubuntu-latest - timeout-minutes: 10 - outputs: - web: ${{ steps.filter.outputs.web }} - websocket: ${{ steps.filter.outputs.websocket }} - httpclient: ${{ steps.filter.outputs.httpclient }} - jpa: ${{ steps.filter.outputs.jpa }} - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - with: - # Both endpoints of the pull request's diff have to be present locally; the default - # shallow fetch has neither the base commit nor the merge base. - fetch-depth: 0 - - name: Decide which adapter lanes this diff can affect - id: filter - env: - BASE_SHA: ${{ github.event.pull_request.base.sha }} - HEAD_SHA: ${{ github.event.pull_request.head.sha }} - run: | - set -euo pipefail - if [ "${GITHUB_EVENT_NAME}" != 'pull_request' ]; then - changed='ALL' - else - if [ -z "${BASE_SHA}" ] || [ -z "${HEAD_SHA}" ]; then - echo "::error::pull request diff endpoints are missing; refusing to report no lanes" - exit 1 - fi - changed="$(git diff --name-only "${BASE_SHA}" "${HEAD_SHA}")" - fi - # Fail closed rather than reporting "nothing changed": an empty diff on a pull request - # means the comparison did not work, and a filter that answers false on a broken - # comparison silently turns every lane below off. - if [ "${changed}" != 'ALL' ] && [ -z "${changed}" ]; then - echo "::error::the pull request diff is empty; the comparison did not run" - exit 1 - fi - printf 'changed files:\n%s\n' "${changed}" - emit() { - lane="$1" - shift - if [ "${changed}" = 'ALL' ]; then - printf '%s=true\n' "${lane}" >> "${GITHUB_OUTPUT}" - printf 'lane %s: true (manual run)\n' "${lane}" - return 0 - fi - for pattern in "$@"; do - if printf '%s\n' "${changed}" | grep -qE -- "${pattern}"; then - printf '%s=true\n' "${lane}" >> "${GITHUB_OUTPUT}" - printf 'lane %s: true (%s)\n' "${lane}" "${pattern}" - return 0 - fi - done - printf '%s=false\n' "${lane}" >> "${GITHUB_OUTPUT}" - printf 'lane %s: false\n' "${lane}" - } - # This workflow and the composite action every lane below uses are in every lane's path - # set: a change to either changes what the lanes do, and a gate that does not re-run when - # its own definition changes is a gate nobody has seen run in its current form. - common='^\.github/workflows/pr-adapters\.yml$|^\.github/actions/' - emit web \ - '^src/adapter/inbound/web/' \ - '^src/application-core/src/.*/operation/' \ - '^src/application-core/src/.*/idempotency/' \ - '^src/adapter/outbound/persistence-jpa/src/.*/operation/' \ - '^docs/web/' \ - "${common}" - emit websocket \ - '^src/adapter/inbound/websocket/' \ - '^docs/websocket/' \ - "${common}" - emit httpclient \ - '^src/adapter/outbound/httpclient/' \ - '^src/app-bootstrap/src/.*/httpclient/' \ - '^docs/httpclient/' \ - '^scripts/verify-httpclient-docs\.py$' \ - "${common}" - emit jpa \ - '^src/adapter/outbound/persistence-jpa/' \ - '^src/app-bootstrap/src/.*/jpa/' \ - '^src/config/architecture/modules\.json$' \ - '^docs/jpa/' \ - '^docs/adr/ADR-JPA-' \ - "${common}" - - # The servlet system contract on both containers the template supports (Tomcat, Jetty). Real - # sockets, so neither lane is part of `check`. - web-servlet-containers: - needs: changes - if: needs.changes.outputs.web == 'true' - runs-on: ubuntu-latest - timeout-minutes: 40 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the servlet system contract on Tomcat and Jetty - working-directory: src - run: >- - ./gradlew - :adapter:inbound:web:systemTest - :adapter:inbound:web:webJettyCompatTest - --stacktrace - - name: Publish the test reports - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: web-servlet-containers-reports - path: src/adapter/inbound/web/build/reports/tests/ - if-no-files-found: warn - - websocket-container-matrix: - needs: changes - if: needs.changes.outputs.websocket == 'true' - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the runtime contract on the second servlet container - working-directory: src - run: >- - ./gradlew - :adapter:inbound:websocket:websocketJettyTest - --stacktrace - - # Docker-gated, and the lane fails rather than skipping. Upgrade handling is the single most - # common WebSocket deployment failure and it is invisible from either side alone. - websocket-nginx-contract: - needs: changes - if: needs.changes.outputs.websocket == 'true' - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the upgrade and forwarded-header contract behind a real Nginx - working-directory: src - run: >- - ./gradlew - :adapter:inbound:websocket:websocketNginxTest - --stacktrace - - # One transport per job, so a transport that stops satisfying the shared contract fails on its own - # row instead of disappearing into an aggregate run. `check` runs this lane once, unparameterised. - httpclient-stable-contract: - needs: changes - if: needs.changes.outputs.httpclient == 'true' - runs-on: ubuntu-latest - timeout-minutes: 30 - strategy: - fail-fast: false - matrix: - transport: [apache, jdk] - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Certify one transport against the shared contract - working-directory: src - run: >- - ./gradlew - :adapter:outbound:httpclient:httpClientStableContractTest - -Phttpclient.contract.transports=${{ matrix.transport }} - --stacktrace - - # Only the Spring 7.0 lane. httpClientSecurityTest and spring62ApiSurfaceScan used to run here - # too; both are `dependsOn` of this leaf's `check` - # (src/adapter/outbound/httpclient/build.gradle), so ci-quality-gates.yml already ran them on the - # same pull request. spring70CompatibilityTest is deliberately outside `check` and is what is left. - httpclient-security-and-compatibility: - needs: changes - if: needs.changes.outputs.httpclient == 'true' - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the next-major Spring compatibility lane - working-directory: src - run: >- - ./gradlew - :adapter:outbound:httpclient:spring70CompatibilityTest - --stacktrace - - # 16 and 18 — the ends of the Stable matrix. 17 runs in the integration stage. What this does not - # do is skip the container lane on a runner without Docker: PostgreSqlContainerFactory throws, - # because a skipped contract reports success for a database nobody tested. - jpa-postgresql-contract: - needs: changes - if: needs.changes.outputs.jpa == 'true' - runs-on: ubuntu-latest - timeout-minutes: 45 - strategy: - fail-fast: false - matrix: - postgresql: ["16", "18"] - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Certify the platform against PostgreSQL ${{ matrix.postgresql }} - working-directory: src - run: >- - ./gradlew - :adapter:outbound:persistence-jpa:jpaPlatformContractTest - -Pjpa.matrix.versions=${{ matrix.postgresql }} - --stacktrace - - jpa-migration-smoke: - needs: changes - if: needs.changes.outputs.jpa == 'true' - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the migration upgrade smoke scenarios - working-directory: src - run: >- - ./gradlew - :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest - --stacktrace diff --git a/.github/workflows/redis-sdk-topology.yml b/.github/workflows/redis-sdk-topology.yml deleted file mode 100644 index 2e099e99..00000000 --- a/.github/workflows/redis-sdk-topology.yml +++ /dev/null @@ -1,202 +0,0 @@ -# Redis SDK topology evidence. -# -# The lanes in src/adapter/outbound/redis-sdk/compose answer what the deterministic in-memory gateway cannot — Sentinel -# promotion behaviour, Cluster redirects, ACL coverage. docs/redis/support-matrix.md records which -# lane produced which evidence, and RedisSupportMatrixTest refuses an evidence claim that does not -# name the test class behind it. -# -# Three cadences, because the cost and the question differ: -# -# pull_request standalone only, current supported version. The cheapest lane that can still -# catch "this change cannot talk to a real Redis at all". A PR gate that starts -# three topologies is a PR gate people learn to ignore. -# schedule the full supported-version x topology matrix, nightly. This is where Sentinel -# promotion and Cluster redirect evidence comes from. -# workflow_dispatch one lane on demand, for reproducing a specific failure. -# -# A release candidate uses the nightly matrix run for its tag: `release-candidate` selects the full -# matrix on demand so an RC does not have to wait for the next scheduled run. -# -# Each lane has its own endpoint. A sentinel is not a data node and a cluster node is not the whole -# cluster, so the address, port, and (for Sentinel) the monitored primary's name are per-lane rather -# than one hardcoded 6379 that happens to be right for standalone only. -# -# The Gradle task is fail-closed on its own account: an unknown mode, a missing endpoint, a lane -# with no tagged test class, and a run that executed zero tests are all errors. This workflow does -# not need to re-check those, but it does have to keep the evidence, which is why every run uploads -# the JUnit XML together with the commit SHA, the server version and the resolved image digest. An -# evidence artifact that cannot say which image produced it is not evidence. -name: redis-sdk-topology - -on: - pull_request: - paths: - - "src/adapter/outbound/redis-runtime/**" - - "src/adapter/outbound/redis-sdk/**" - - "src/adapter/outbound/cache-redis/**" - - "compose/redis/**" - - ".github/workflows/redis-sdk-topology.yml" - # Every Gradle job here installs its toolchain through this composite action, so a change to - # it changes what this gate runs. - - ".github/actions/setup-gradle-java/action.yml" - schedule: - # 02:30 UTC daily. Nightly, not hourly: the matrix starts real servers. - - cron: "30 2 * * *" - workflow_dispatch: - inputs: - topology: - description: standalone, sentinel, cluster, tls, or release-candidate for the full matrix - required: true - default: standalone - type: choice - options: [standalone, sentinel, cluster, tls, release-candidate] - redis_version: - description: server version tag - required: true - default: "7.4" - type: string - -permissions: - contents: read - -jobs: - # The matrix is computed rather than duplicated per trigger, so adding a supported version is one - # edit and no trigger can silently keep testing an old set. - lanes: - runs-on: ubuntu-latest - outputs: - matrix: ${{ steps.select.outputs.matrix }} - steps: - - id: select - run: | - set -euo pipefail - case "${{ github.event_name }}" in - pull_request) - matrix='{"include":[{"topology":"standalone","redis_version":"7.4"}]}' - ;; - schedule) - matrix='{"include":[ - {"topology":"standalone","redis_version":"7.2"}, - {"topology":"standalone","redis_version":"7.4"}, - {"topology":"standalone","redis_version":"8.2"}, - {"topology":"sentinel","redis_version":"7.2"}, - {"topology":"sentinel","redis_version":"7.4"}, - {"topology":"sentinel","redis_version":"8.2"}, - {"topology":"cluster","redis_version":"7.2"}, - {"topology":"cluster","redis_version":"7.4"}, - {"topology":"cluster","redis_version":"8.2"}, - {"topology":"tls","redis_version":"7.4"}, - {"topology":"tls","redis_version":"8.2"}]}' - ;; - *) - if [ "${{ inputs.topology }}" = "release-candidate" ]; then - matrix='{"include":[ - {"topology":"standalone","redis_version":"7.2"}, - {"topology":"standalone","redis_version":"7.4"}, - {"topology":"standalone","redis_version":"8.2"}, - {"topology":"sentinel","redis_version":"7.2"}, - {"topology":"sentinel","redis_version":"7.4"}, - {"topology":"sentinel","redis_version":"8.2"}, - {"topology":"cluster","redis_version":"7.2"}, - {"topology":"cluster","redis_version":"7.4"}, - {"topology":"cluster","redis_version":"8.2"}, - {"topology":"tls","redis_version":"7.4"}, - {"topology":"tls","redis_version":"8.2"}]}' - else - matrix='{"include":[{"topology":"${{ inputs.topology }}","redis_version":"${{ inputs.redis_version }}"}]}' - fi - ;; - esac - printf 'matrix=%s\n' "$(printf '%s' "$matrix" | tr -d '\n ')" >> "$GITHUB_OUTPUT" - - topology-evidence: - needs: lanes - runs-on: ubuntu-latest - timeout-minutes: 30 - strategy: - fail-fast: false - matrix: ${{ fromJson(needs.lanes.outputs.matrix) }} - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Start the topology - env: - REDIS_VERSION: ${{ matrix.redis_version }} - run: docker compose -f "src/adapter/outbound/redis-sdk/compose/${{ matrix.topology }}/compose.yml" up -d --wait - - name: Record the image digest - id: image - run: | - set -euo pipefail - # The tag says 7.4; the digest says which 7.4. Evidence that names only the tag cannot be - # reproduced once the tag moves. - # - # This used to end in `|| echo 'unresolved'`, which absorbed the failure that `set -e` was - # there to catch: the manifest below recorded `image_digest=unresolved`, the upload - # satisfied `if-no-files-found: error`, and the lane went green holding exactly the - # artifact this workflow's header calls "not evidence". Compose pulls the image in the - # step before this one, so RepoDigests is populated; if it is not, the run has nothing to - # certify and says so. - digest="$(docker image inspect --format '{{index .RepoDigests 0}}' \ - "redis:${{ matrix.redis_version }}")" - if [[ -z "$digest" ]]; then - echo "::error::no repository digest for redis:${{ matrix.redis_version }}; this run cannot say which image produced its evidence" - exit 1 - fi - printf 'digest=%s\n' "$digest" >> "$GITHUB_OUTPUT" - - name: Run the topology contracts - working-directory: src - run: | - set -euo pipefail - # Each leaf declares the lanes its tests qualify; a mode a leaf does not declare fails - # closed, so each topology names exactly the leaves that have classes for it. - runtime=:adapter:outbound:redis-runtime:redisTopologyTest - sdk=:adapter:outbound:redis-sdk:redisTopologyTest - semantic=:adapter:outbound:cache-redis:redisTopologyTest - case '${{ matrix.topology }}' in - standalone) port=6379; extra=''; tasks="$runtime $sdk $semantic" ;; - sentinel) port=27010; extra='-Predis.topology.master=skeleton'; tasks="$runtime $sdk" ;; - cluster) port=7100; extra=''; tasks="$runtime $sdk $semantic" ;; - # The TLS lane's CA is generated at start-up, so the trust material is extracted from - # the lane rather than checked in. A checked-in key is a secret in the repository - # however loudly the file is named "test". - tls) - port=6390 - docker compose -f adapter/outbound/redis-sdk/compose/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem" - extra="-Predis.topology.trust-material=$RUNNER_TEMP/redis-lane-ca.pem" - tasks="$runtime" - ;; - *) echo "unknown topology"; exit 1 ;; - esac - ./gradlew $tasks --continue --console=plain \ - -Predis.topology.host=localhost \ - -Predis.topology.port="$port" \ - -Predis.topology.mode='${{ matrix.topology }}' \ - $extra - - name: Write the evidence manifest - if: always() - run: | - set -euo pipefail - out=src/build/redis-topology-evidence - mkdir -p "$out" - cat > "$out/evidence-manifest.txt" <- - ./gradlew - :adapter:inbound:web:systemTest - :adapter:inbound:web:webJettyCompatTest - :adapter:inbound:web-advanced:webAdvancedTest - --stacktrace - - name: Publish the release evidence - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: web-release-evidence - path: | - src/adapter/inbound/web/build/reports/tests/ - src/adapter/inbound/web-advanced/build/reports/tests/ - if-no-files-found: error - - websocket-stable-release-gate: - runs-on: ubuntu-latest - timeout-minutes: 60 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run every websocket lane - working-directory: src - run: >- - ./gradlew - :adapter:inbound:websocket:test - :adapter:inbound:websocket:systemTest - :adapter:inbound:websocket:websocketJettyTest - :adapter:inbound:websocket:websocketNginxTest - :adapter:inbound:websocket:websocketTransportQualificationTest - --stacktrace - - name: Publish the release evidence - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: websocket-release-evidence - path: src/adapter/inbound/websocket/build/reports/tests/ - if-no-files-found: error - - # Each gate runs as its own single-line `./gradlew ` step so that a failure names the gate - # rather than a folded command. The architecture dependency gate that used to end this list is now - # architecture-and-surface above; it was the fourth copy of the same invocation. - httpclient-release-gate: - runs-on: ubuntu-latest - timeout-minutes: 60 - defaults: - run: - working-directory: src - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the HTTP client release qualification graph - run: >- - ./gradlew - :adapter:outbound:httpclient:test - :adapter:outbound:httpclient:spring62ApiSurfaceScan - :adapter:outbound:httpclient:spring70CompatibilityTest - :adapter:outbound:httpclient:httpClientStableContractTest - :adapter:outbound:httpclient:httpClientSecurityTest - :adapter:outbound:httpclient:httpClientFailureInjectionTest - :adapter:outbound:httpclient:httpClientPerformanceTest - --stacktrace - - - httpclient-documentation: - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # actions/setup-python@v5.6.0 - with: - python-version: '3.12' - - name: Verify documentation matches the code - run: python3 scripts/verify-httpclient-docs.py - - # --------------------------------------------------------------------------------------------- - # JPA release gates (were jpa-release.yml). One job per PostgreSQL major, because one job for - # three majors was one job for one major: `-Pjpa.matrix.versions=16,17,18` reached - # JpaPlatformContractSupport.start(), which started only the first selected version, while - # docs/jpa/support-matrix.md recorded all three as covered. start() now fails closed on a - # multi-version selection, so this matrix is the only way the Stable majors get covered. - # - # persistence-jpa release/release-registry.json is the gate-task source: jpaReleaseQualification (persistence-jpa - # build.gradle) depends on its blocking gates, so a gate naming a missing task fails when the task - # graph is built, and JpaReleaseRenderingTest holds this matrix and the promotion list below to the - # registry's Stable majors. Editing one without the other fails the persistence-jpa unit lane. - jpa-release-gate: - runs-on: ubuntu-latest - timeout-minutes: 90 - strategy: - fail-fast: false - matrix: - postgresql: ["16", "17", "18"] - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the JPA database qualification set on PostgreSQL ${{ matrix.postgresql }} - working-directory: src - run: >- - ./gradlew - jpaReleaseQualification - -Pjpa.matrix.versions=${{ matrix.postgresql }} - --stacktrace - - name: Record which major this evidence covers - if: always() - working-directory: src - run: | - mkdir -p build/jpa-release-evidence - { - echo "sha=${{ github.sha }}" - echo "ref=${{ github.ref }}" - echo "postgresql-major=${{ matrix.postgresql }}" - echo "task-set=jpa-database-qualification" - } > "build/jpa-release-evidence/manifest-${{ matrix.postgresql }}.properties" - - name: Upload the release evidence - if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2 - with: - name: jpa-release-evidence-pg${{ matrix.postgresql }} - path: | - src/build/jpa-release-evidence/manifest-${{ matrix.postgresql }}.properties - src/adapter/outbound/persistence-jpa/build/test-results/**/*.xml - retention-days: 30 - if-no-files-found: error - - # The promotion decision. Every Stable major's evidence, all from this SHA — an aggregate that - # accepted a re-run artifact from another commit would promote a release on evidence produced by - # different code. - jpa-release-promotion: - runs-on: ubuntu-latest - timeout-minutes: 15 - needs: jpa-release-gate - steps: - - name: Download every major's evidence - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # actions/download-artifact@v4.3.0 - with: - pattern: jpa-release-evidence-pg* - path: evidence - - name: Require every Stable major, all from this SHA - run: | - set -euo pipefail - missing=0 - for major in 16 17 18; do - manifest=$(find evidence -name "manifest-${major}.properties" -print -quit) - if [ -z "${manifest}" ]; then - echo "::error::no release evidence for PostgreSQL ${major}" - missing=1 - continue - fi - sha=$(sed -n 's/^sha=//p' "${manifest}") - if [ "${sha}" != "${{ github.sha }}" ]; then - echo "::error::PostgreSQL ${major} evidence is from ${sha}, not ${{ github.sha }}" - missing=1 - fi - done - if [ "${missing}" -ne 0 ]; then - echo "::error::the release gate covers every Stable PostgreSQL major; promotion needs all of them" - exit 1 - fi - echo "Every Stable PostgreSQL major's evidence is present and from ${{ github.sha }}." - - jpa-registry-and-docs: - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Verify the release registry, the readiness cards and the support matrix - working-directory: src - run: >- - ./gradlew - :adapter:outbound:persistence-jpa:test - --tests '*JpaReleaseManifestTest' - --tests '*JpaReleaseRenderingTest' - --tests '*JpaReadinessRegistryTest' - --stacktrace - - # --------------------------------------------------------------------------------------------- - # Fileserver certification (was fileserver-certification.yml). Its job list is the same shape as - # docs/fileserver/support-matrix.md: nothing is advertised at a support level whose evidence job - # is absent. FileserverDocumentationCoverageTest reads the job ids from this file and from - # `.github/workflows/fileserver-*.yml`. "Certification" rather than "release" on purpose: these - # jobs prove a storage topology, a support matrix and a telemetry redaction claim, and deploy - # nothing (docs/ci-cd/boundary.md). - fileserver-full-verification: - runs-on: ubuntu-latest - timeout-minutes: 60 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Run the complete fileserver suite across every leaf - working-directory: src - run: >- - ./gradlew - :application-fileserver:check - :adapter:inbound:web-fileserver:check - :adapter:outbound:fileserver:check - :adapter:outbound:persistence-fileserver:check - :composition:fileserver-platform:check - --stacktrace - - fileserver-documentation-gate: - runs-on: ubuntu-latest - timeout-minutes: 20 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Prove every support claim maps to a job and every endpoint is documented - working-directory: src - run: >- - ./gradlew - :composition:fileserver-platform:test --tests '*FileserverDocumentationCoverageTest' - --stacktrace - - fileserver-sensitive-telemetry-scan: - runs-on: ubuntu-latest - timeout-minutes: 20 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - - uses: ./.github/actions/setup-gradle-java - - name: Prove telemetry carries no filename, path, or raw identifier - working-directory: src - run: >- - ./gradlew - :application-fileserver:test --tests '*FileserverObservabilityTest' - --stacktrace - - app-image-release: - needs: - - architecture-and-surface - - web-stable-release-gate - - websocket-stable-release-gate - - httpclient-release-gate - - httpclient-documentation - - jpa-release-promotion - - jpa-registry-and-docs - - fileserver-full-verification - - fileserver-documentation-gate - - fileserver-sensitive-telemetry-scan - # Job-level, because a job that declares `permissions:` replaces the workflow set entirely: this - # job and app-image-signing are the only ones that write anything anywhere, and - # `packages: write` stops at their boundary. No OIDC token here: this job runs the repository's - # Gradle build inside the Dockerfile, and the signing identity stays out of that. - permissions: - contents: read - packages: write - # The signing job below reads the digest from here. It is the digest, not a tag, that is signed. - outputs: - pinned_reference: ${{ steps.push.outputs.pinned_reference }} - runs-on: ubuntu-latest - timeout-minutes: 90 - steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - # The builder stage inside src/Dockerfile runs this repository's Gradle wrapper to produce the - # JAR that becomes the image. Validating the wrapper here checks the thing that is about to - # execute, before it executes, rather than after an image already exists. - # The tag is the release identity; everything below derives from it. A tag that does not parse - # stops the release here, rather than producing an image named after whatever ref happened to - # be checked out. - # - # GHCR rejects an uppercase path, and this repository's owner is mixed case — the naive - # `ghcr.io/${{ github.repository }}` fails at push time with a message about the manifest - # rather than about the case, so the lowercasing is explicit and the result is asserted. - - name: Resolve the release coordinates - env: - CONFIGURED_IMAGE_NAME: ${{ vars.APP_IMAGE_NAME }} - run: | - set -euo pipefail - readonly REGISTRY='ghcr.io' - if [[ "${GITHUB_REF_TYPE}" != 'tag' ]]; then - echo "::error::container-release runs only for a release tag; ref type was ${GITHUB_REF_TYPE}" - exit 1 - fi - release_tag="${GITHUB_REF_NAME}" - # Bare MAJOR.MINOR.PATCH, because src/build.gradle's release-version guard refuses a - # pre-release or build suffix and the image tag must be the same string the JAR reports. - if [[ ! "${release_tag}" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then - echo "::error::release tag must be vMAJOR.MINOR.PATCH with no suffix; got '${release_tag}'" - exit 1 - fi - release_version="${BASH_REMATCH[1]}" - owner_path="$(printf '%s' "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')" - image_name="${CONFIGURED_IMAGE_NAME:-${owner_path}/caskeleton}" - image_repository="${REGISTRY}/${image_name}" - if [[ "${image_repository}" != "${image_repository,,}" ]]; then - echo "::error::image repository must be lowercase; got '${image_repository}'" - exit 1 - fi - if [[ "${image_repository}" =~ [[:space:]] || "${image_repository}" == *:* ]]; then - echo "::error::image repository must carry no tag and no whitespace; got '${image_repository}'" - exit 1 - fi - { - printf 'REGISTRY=%s\n' "${REGISTRY}" - printf 'RELEASE_VERSION=%s\n' "${release_version}" - printf 'BUILD_VERSION=%s+%s\n' "${release_version}" "${GITHUB_SHA}" - printf 'IMAGE_REPOSITORY=%s\n' "${image_repository}" - printf 'IMAGE_VERSION_TAG=%s\n' "${release_version}" - printf 'IMAGE_REVISION_TAG=sha-%s\n' "${GITHUB_SHA}" - printf 'SOURCE_URL=%s/%s\n' "${GITHUB_SERVER_URL}" "${GITHUB_REPOSITORY}" - } >> "${GITHUB_ENV}" - printf 'container-release: %s -> %s:%s and %s:sha-%s\n' \ - "${release_tag}" "${image_repository}" "${release_version}" \ - "${image_repository}" "${GITHUB_SHA}" - # Byte-identical to the install in dependency-vulnerability.yml, deliberately: the same - # checksum-pinned binary at the same version scans the filesystem and the image, so the two - # gates cannot disagree because one of them silently moved to a newer database schema. - # - # This repository installs its scanner rather than calling a scanner action, which is why no - # third-party action appears in this workflow: a pinned tarball with an asserted SHA-256 is a - # supply-chain claim that can be checked offline, and an action pinned to a commit is not. - - name: Install pinned Trivy under RUNNER_TEMP - env: - TRIVY_DOWNLOAD_BASE_URL: ${{ vars.TRIVY_DOWNLOAD_BASE_URL }} - run: | - set -euo pipefail - readonly TRIVY_VERSION='0.71.2' - readonly TRIVY_SHA256_AMD64='0510e71e2fd39bf863856d499c8dc19feb4e7336546394c502a8f5cc7ab27460' - readonly TRIVY_SHA256_ARM64='fe1c7106e15a5365d485b098a8c338f91e3b7ba71cb0e4963b98a3a098763cfc' - readonly DOWNLOAD_BASE_URL="${TRIVY_DOWNLOAD_BASE_URL:-https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}}" - case "${RUNNER_ARCH:-X64}" in - X64) - asset_arch='64bit' - expected_sha256="${TRIVY_SHA256_AMD64}" - ;; - ARM64) - asset_arch='ARM64' - expected_sha256="${TRIVY_SHA256_ARM64}" - ;; - *) - echo "::error::unsupported runner architecture: ${RUNNER_ARCH:-unknown}" - exit 1 - ;; - esac - install_dir="${RUNNER_TEMP}/trivy-${TRIVY_VERSION}" - archive="${RUNNER_TEMP}/trivy-${TRIVY_VERSION}.tar.gz" - mkdir -p "${install_dir}" - curl --fail --show-error --silent --location --retry 3 \ - --proto '=https' --tlsv1.2 \ - "${DOWNLOAD_BASE_URL}/trivy_${TRIVY_VERSION}_Linux-${asset_arch}.tar.gz" \ - --output "${archive}" - printf '%s %s\n' "${expected_sha256}" "${archive}" | sha256sum -c - - tar -xzf "${archive}" -C "${install_dir}" trivy - chmod 0755 "${install_dir}/trivy" - printf '%s\n' "${install_dir}" >> "${GITHUB_PATH}" - # SOURCE_DATE_EPOCH is the commit time, not the wall clock, so the image metadata is a function - # of the commit rather than of when the runner happened to pick the job up. Verified locally, - # and worth stating exactly because it is easy to overclaim: BuildKit uses it for the image - # config `created` field and for every history timestamp — both came back as the commit time — - # and it does NOT rewrite file mtimes inside the layers. Those still carry the build time, so - # two builds of the same commit agree on metadata but their layer digests still differ. - # Byte-identical layers additionally need `--output type=image,rewrite-timestamp=true`, which - # needs the containerd image store; that is a runner-capability change, not a flag to add - # untested to the one job that publishes releases. - # - # The OCI `created` label comes from the same commit for the same reason: `date -u` there would - # have made every rebuild a different image for no reason anybody could see. - # - # Both base images are already digest-pinned inside src/Dockerfile, and so is the Dockerfile - # frontend in its `# syntax` directive, so nothing in this build resolves a floating tag. - - name: Build the release image - run: | - set -euo pipefail - SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)" - export SOURCE_DATE_EPOCH - created="$(git log -1 --format=%cI)" - printf 'SOURCE_DATE_EPOCH=%s (%s)\n' "${SOURCE_DATE_EPOCH}" "${created}" - DOCKER_BUILDKIT=1 docker build \ - --file src/Dockerfile \ - --tag "${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}" \ - --tag "${IMAGE_REPOSITORY}:${IMAGE_REVISION_TAG}" \ - --build-arg RELEASE_VERSION="${RELEASE_VERSION}" \ - --build-arg BUILD_VERSION="${BUILD_VERSION}" \ - --build-arg GIT_SHA="${GITHUB_SHA}" \ - --build-arg SOURCE_URL="${SOURCE_URL}" \ - --label org.opencontainers.image.created="${created}" \ - src - docker image inspect \ - --format 'built {{.Id}} ({{.Size}} bytes, {{len .RootFS.Layers}} layers)' \ - "${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}" - # Generated before the blocking scan, and uploaded before it too, so the inventory of what is - # in the image survives the run that refuses to publish it. An SBOM you only get on a green - # build is an SBOM you cannot use to answer "what was in the one that failed". - - name: Generate the image SBOM - run: | - set -euo pipefail - trivy image \ - --format cyclonedx \ - --scanners license \ - --output image-sbom.cdx.json \ - "${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}" - test -s image-sbom.cdx.json - - name: Upload the image SBOM - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # actions/upload-artifact@v7.0.1 - with: - name: container-release-sbom - path: image-sbom.cdx.json - if-no-files-found: error - retention-days: 90 - # The same policy dependency-vulnerability.yml applies to the filesystem, applied to the thing - # that actually ships: CRITICAL and HIGH block, everything else is reported. The filesystem - # scan cannot see the base image's OS packages, which is most of an image's attack surface, so - # a green trivy-fs has never been evidence about the artifact. - # - # --ignorefile is mandatory here as everywhere: .trivyignore.yaml is the single suppression - # source. Each entry carries a rationale and an expiry by policy, reviewed through CODEOWNERS - # (.github/dependency-vulnerability-policy.md); an inline --skip or a second ignore file would - # be a suppression nobody reviews. - # - # This step is the reason `docker push` is further down. A vulnerable image that was pushed and - # then reported is already pullable by everything that watches the tag. - - name: Block High and Critical vulnerabilities in the release image - run: | - set -euo pipefail - trivy image \ - --scanners vuln,license \ - --severity CRITICAL,HIGH \ - --exit-code 1 \ - --ignorefile .trivyignore.yaml \ - "${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}" - - name: Report Medium and Low vulnerabilities in the release image - run: | - set -euo pipefail - trivy image \ - --scanners vuln,license \ - --severity MEDIUM,LOW \ - --exit-code 0 \ - --ignorefile .trivyignore.yaml \ - "${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}" - - name: Sign in to the container registry - env: - REGISTRY_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - set -euo pipefail - printf '%s' "${REGISTRY_TOKEN}" \ - | docker login "${REGISTRY}" --username "${GITHUB_ACTOR}" --password-stdin - # Two tags, one digest. The semver tag is what a human reads and what a release note cites; the - # sha- tag is the one that can never be moved to different content, because the git SHA it - # names is the only commit that can produce it. - # - # Neither is what a manifest should pin. Both are mutable names in a registry: a later push can - # point `1.2.3` at something else, and nothing about a tag tells a cluster it did not. The - # digest recorded below is immutable by construction, and it is the field the GitOps repository - # pins — the tags exist so a person can find the digest, not so a cluster can resolve one. - - name: Push the release and revision tags - id: push - run: | - set -euo pipefail - docker push "${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}" - docker push "${IMAGE_REPOSITORY}:${IMAGE_REVISION_TAG}" - # awk rather than `grep | head`, deliberately. Under `set -e` with `pipefail`, a grep that - # matches nothing exits 1 and kills the step right here — so the explicit check below, - # and its message, would never run and the failure would surface as a bare exit code. - # awk exits 0 whether or not it matched, which leaves the empty case for us to report. - pinned_reference="$( - docker image inspect \ - --format '{{range .RepoDigests}}{{println .}}{{end}}' \ - "${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}" \ - | awk -v prefix="${IMAGE_REPOSITORY}@sha256:" \ - 'index($0, prefix) == 1 { print; exit }' - )" - if [[ -z "${pinned_reference}" ]]; then - echo "::error::no registry digest for ${IMAGE_REPOSITORY} after push" - exit 1 - fi - printf 'PINNED_REFERENCE=%s\n' "${pinned_reference}" >> "${GITHUB_ENV}" - printf 'pinned_reference=%s\n' "${pinned_reference}" >> "${GITHUB_OUTPUT}" - printf 'container-release: pushed %s\n' "${pinned_reference}" - # The handoff to the GitOps repository, in a form a person and a script can both read. It is - # written to the job summary as well as to an artifact because the summary is where somebody - # looks first and the artifact is what survives the ninety days a release audit asks about. - - name: Record the immutable image reference - run: | - set -euo pipefail - digest="${PINNED_REFERENCE#*@}" - { - printf 'release_tag: %s\n' "${GITHUB_REF_NAME}" - printf 'git_sha: %s\n' "${GITHUB_SHA}" - printf 'image_repository: %s\n' "${IMAGE_REPOSITORY}" - printf 'version_tag: %s\n' "${IMAGE_VERSION_TAG}" - printf 'revision_tag: %s\n' "${IMAGE_REVISION_TAG}" - printf 'digest: %s\n' "${digest}" - printf 'pinned_reference: %s\n' "${PINNED_REFERENCE}" - } > image-release.txt - { - printf '### container-release\n\n' - printf 'Pin this in the GitOps manifest as the container image:\n\n' - printf '```\n%s\n```\n\n' "${PINNED_REFERENCE}" - printf -- '- release tag: `%s`\n' "${GITHUB_REF_NAME}" - printf -- '- version tag: `%s:%s`\n' "${IMAGE_REPOSITORY}" "${IMAGE_VERSION_TAG}" - printf -- '- revision tag: `%s:%s`\n' "${IMAGE_REPOSITORY}" "${IMAGE_REVISION_TAG}" - } >> "${GITHUB_STEP_SUMMARY}" - cat image-release.txt - - name: Upload the immutable image reference - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # actions/upload-artifact@v7.0.1 - with: - name: container-release-image-reference - path: image-release.txt - if-no-files-found: error - retention-days: 90 - - # Keyless signature of the pushed digest (owner decision 31). A job of its own so that - # `id-token: write` — the GitHub OIDC token Fulcio turns into a short-lived signing certificate - # naming this workflow and tag — exists only here, in a job that checks nothing out and builds - # nothing. The signature goes to the registry beside the image (hence `packages: write`) and the - # transparency-log entry to Rekor; there is no key to store or rotate. - # - # The digest is signed, never a tag: a tag can be moved to other content, a digest cannot. - # Verification runs right after signing with the identity a deployment should require, so a - # release whose signature a cluster would reject fails here instead of at admission. - # - # Local limit: signing needs the tag run's OIDC token and a pushed GHCR image, so it is exercised - # only by a real release. DeveloperExperienceContractTest pins the structure of this job. - app-image-signing: - needs: - - app-image-release - permissions: - contents: read - packages: write - id-token: write - runs-on: ubuntu-latest - timeout-minutes: 30 - env: - PINNED_REFERENCE: ${{ needs.app-image-release.outputs.pinned_reference }} - steps: - # Same policy as Trivy above: a pinned release binary with an asserted SHA-256, no action. - # The two hashes are the cosign-linux-{amd64,arm64} lines of the official v3.1.3 - # cosign_checksums.txt, which was itself verified against its Sigstore bundle - # (identity keyless@projectsigstore.iam.gserviceaccount.com, issuer https://accounts.google.com) - # when they were pinned. The checksum file is fetched again here and must still carry the - # pinned line, so a re-published release asset fails the job instead of passing silently. - - name: Install pinned cosign under RUNNER_TEMP - run: | - set -euo pipefail - readonly COSIGN_VERSION='3.1.3' - readonly COSIGN_SHA256_AMD64='4629c757b7618056f8ddd7e2625ae9fdd94c0372a65049520bc7d9df9efc7f71' - readonly COSIGN_SHA256_ARM64='c5d324e091826b0d7a78eb16fef316450b4eb9aaec045611c08ba06f5e73220a' - readonly DOWNLOAD_BASE_URL="https://github.com/sigstore/cosign/releases/download/v${COSIGN_VERSION}" - case "${RUNNER_ARCH:-X64}" in - X64) - asset='cosign-linux-amd64' - expected_sha256="${COSIGN_SHA256_AMD64}" - ;; - ARM64) - asset='cosign-linux-arm64' - expected_sha256="${COSIGN_SHA256_ARM64}" - ;; - *) - echo "::error::unsupported runner architecture: ${RUNNER_ARCH:-unknown}" - exit 1 - ;; - esac - install_dir="${RUNNER_TEMP}/cosign-${COSIGN_VERSION}" - mkdir -p "${install_dir}" - curl --fail --show-error --silent --location --retry 3 \ - --proto '=https' --tlsv1.2 \ - "${DOWNLOAD_BASE_URL}/cosign_checksums.txt" \ - --output "${RUNNER_TEMP}/cosign_checksums.txt" - if ! grep -qxF "${expected_sha256} ${asset}" "${RUNNER_TEMP}/cosign_checksums.txt"; then - echo "::error::cosign_checksums.txt no longer lists the pinned ${asset} hash" - exit 1 - fi - curl --fail --show-error --silent --location --retry 3 \ - --proto '=https' --tlsv1.2 \ - "${DOWNLOAD_BASE_URL}/${asset}" \ - --output "${install_dir}/cosign" - printf '%s %s\n' "${expected_sha256}" "${install_dir}/cosign" | sha256sum -c - - chmod 0755 "${install_dir}/cosign" - printf '%s\n' "${install_dir}" >> "${GITHUB_PATH}" - - name: Check the reference to sign - run: | - set -euo pipefail - if [[ ! "${PINNED_REFERENCE}" =~ ^ghcr\.io/[a-z0-9._/-]+@sha256:[0-9a-f]{64}$ ]]; then - echo "::error::app-image-release handed over no digest reference; got '${PINNED_REFERENCE}'" - exit 1 - fi - printf 'CERTIFICATE_IDENTITY=%s/%s\n' "${GITHUB_SERVER_URL}" "${GITHUB_WORKFLOW_REF}" \ - >> "${GITHUB_ENV}" - - name: Sign in to the container registry - env: - REGISTRY_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - set -euo pipefail - printf '%s' "${REGISTRY_TOKEN}" \ - | docker login ghcr.io --username "${GITHUB_ACTOR}" --password-stdin - - name: Sign the image digest (keyless) - run: | - set -euo pipefail - cosign sign --yes "${PINNED_REFERENCE}" - # The identity a deployment admission policy should require: this workflow file at this tag, - # issued by GitHub's OIDC provider. Anything else — another workflow, another repository, a - # branch run — does not verify. - - name: Verify the signature with the release identity - run: | - set -euo pipefail - cosign verify \ - --certificate-identity "${CERTIFICATE_IDENTITY}" \ - --certificate-oidc-issuer https://token.actions.githubusercontent.com \ - "${PINNED_REFERENCE}" > cosign-verify.json - { - printf '### container-release signature\n\n' - printf -- '- signed: `%s`\n' "${PINNED_REFERENCE}" - printf -- '- certificate identity: `%s`\n' "${CERTIFICATE_IDENTITY}" - printf -- '- issuer: `https://token.actions.githubusercontent.com`\n' - } >> "${GITHUB_STEP_SUMMARY}" diff --git a/AGENTS.md b/AGENTS.md index f990d2ef..5f48b998 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,9 +26,10 @@ Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버 ## 검증 -- leaf 하나: registry의 `gradle_path`로 `./gradlew :check --console=plain`(`src/`에서). 기억이나 폴더 이름으로 짐작하지 않는다. -- 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때). 게이트 고르기는 `docs/work/reference/gates.md`. -- 문서·지침을 고쳤으면 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`. +- 진입점은 `scripts/verify.sh <단계>`다. 단계 이름은 workflow와 같다(`pr`·`main`·`nightly`·`release`, 그리고 `docs`·`leaf`·`app`·`round`). Gradle·Docker가 드는 단계는 스크립트가 desktop으로 옮겨 잠금 아래에서 돌린다. +- leaf 하나: `scripts/verify.sh leaf `. 경로는 registry의 `gradle_path`다. 기억이나 폴더 이름으로 짐작하지 않는다. +- 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때, `src/`에서), 단계 묶음은 `scripts/verify.sh pr` 등. 게이트 고르기는 `docs/work/reference/gates.md`. +- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북에서 돈다). ## 일하는 방식 diff --git a/docs/README.md b/docs/README.md index 7b84d7f8..2dd25401 100644 --- a/docs/README.md +++ b/docs/README.md @@ -190,7 +190,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것 | --- | --- | | `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) | | `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 | -| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | +| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | | `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`src/gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 | | `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 | | `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 | @@ -205,11 +205,11 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것 - 줄을 지우면 같은 변경에서 `scripts/check-docs.py`의 `FROZEN`에서 그 줄의 지문도 뺀다. 남겨 두면 실패한다(남은 지문은 지운 줄을 다시 더하는 길이다). 2026-11-07 번역 단계에서 목록과 `FROZEN`이 모두 비었다. - 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`. -- 상대 링크는 `link` 검사가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL은 lychee(`link-check` workflow)가 본다. +- 상대 링크는 `link` 검사가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL은 lychee(`main.yml`의 `links` job)가 본다. 기록 안의 외부 링크가 죽어도 기록 본문은 고치지 않는다. 그 URL을 저장소 루트의 `.lycheeignore`에 더한다. ## 여기에 없는 것 -- 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다. +- 실행되는 검증 스크립트는 문서가 아니다. `scripts/`(workflow가 부르는 것은 `scripts/ci/`)에 있다. - 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다. - 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다. diff --git a/docs/capability-status.md b/docs/capability-status.md index 761fe1ca..fdd268db 100644 --- a/docs/capability-status.md +++ b/docs/capability-status.md @@ -400,7 +400,7 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap | `GrpcStableReleaseGate`/`GrpcAdvancedPromotionGate` | 게이트에 연결된 적 없음(자기 테스트만). release `grpc-stable-release-gate` job은 그대로 | — | | notification evidence·env registry·mongo lane 계약(`test`) | `notificationDocumentContractTest`·`notificationEnvironmentContractTest`·`mongoDocumentContractTest` | `mainCheck` | | objectstorage MinIO 레인(`check`) | 루트 `integrationCheck` | main | -| `releaseCheck`의 `ci` | ci-quality-gates.yml `:ci`(PR·main push) | PR | +| `releaseCheck`의 `ci` | `pr.yml`의 `:prCheck`(`ci` 포함) | PR | | fileserver-pr `architectureTest --tests '*Fileserver*'` | `:ci`의 `architectureCheck`(전체 ArchUnit) | PR | | legacy whole-`byte[]` 포트 `ObjectStoragePort`·`StoredObject` | `src/application-objectstorage/src/main/java/dev/caskeleton/application/storage/` | `c4a066df` | 한 기능에 한 세대(S1-#17b·S4-#11a). canonical semantic 포트로 대체 | | legacy 어댑터 `FilesystemObjectStorageAdapter`·`S3ObjectStorageAdapter`와 `ObjectStorageConfig`·`ObjectStorageSettings`(`ca-skeleton.objectstorage.*`) | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/` | `c4a066df` | 같은 이유 | diff --git a/docs/ci-cd/boundary.md b/docs/ci-cd/boundary.md index 1281e831..3caff17d 100644 --- a/docs/ci-cd/boundary.md +++ b/docs/ci-cd/boundary.md @@ -1,10 +1,10 @@ -# CI/CD 경계 — GitHub Actions는 CI, Argo CD는 CD +# CI/CD 경계 — Gitea Actions는 CI, Argo CD는 CD ## 결론 -GitHub Actions는 **검증하고 아티팩트를 만든다**. Argo CD는 **배포한다**. 두 역할은 겹치지 않는다. +Gitea Actions(`.gitea/workflows`)는 **검증하고 아티팩트를 만든다**. Argo CD는 **배포한다**. 두 역할은 겹치지 않는다. -GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync` 중 어느 것도 하지 +Gitea Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync` 중 어느 것도 하지 않는다. 그러므로 CI에는 클러스터 자격증명(kubeconfig, 서비스 계정 토큰)이 들어가지 않는다. ## 흐름 @@ -13,7 +13,7 @@ GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync git push / tag │ ▼ - GitHub Actions ─────────────── CI ───────────────┐ + Gitea Actions ─────────────── CI ───────────────┐ • 테스트 · 정적분석 · 아키텍처 검증 │ • 컨테이너 이미지 빌드 │ • 취약점 스캔 (Trivy) │ @@ -53,9 +53,10 @@ GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync | 항목 | 상태 | | --- | --- | -| 이미지 빌드/스캔/push | `release.yml`이 수행 | -| SBOM | `release.yml`이 생성 | -| 이미지 서명 · provenance attestation | **없음.** 추가 대상 | +| 이미지 빌드/스캔/push | `.gitea/workflows/release.yml`이 수행. 이 Gitea의 컨테이너 레지스트리 | +| SBOM | `release.yml`이 생성(CycloneDX, 이미지 검사 전) | +| 이미지 서명 | `release.yml`이 digest를 cosign 키 쌍으로 서명하고 확인한다(태그에서만) | +| provenance attestation | **없음.** 추가 대상 | | GitOps 저장소 | **없음.** 별도 저장소로 만들 예정 | | Argo CD Application 정의 | **없음.** GitOps 저장소에 둘 예정 | | CI에서의 클러스터 접근 | 없음 — 유일했던 `kubectl apply`는 제거됨 | diff --git a/docs/ci-cd/template-vs-consumer.md b/docs/ci-cd/template-vs-consumer.md index cd0bf320..c2a3197a 100644 --- a/docs/ci-cd/template-vs-consumer.md +++ b/docs/ci-cd/template-vs-consumer.md @@ -17,8 +17,7 @@ | 대상 | 무엇을 지키는가 | | --- | --- | | `docs/design/**`, `docs/history/**` | 이 템플릿을 만든 과정의 설계서·계획서·납품 패키지·증거·학습 기록 | -| `gradle/qualification/**` | 이 템플릿이 벤더링한 플랫폼(JPA, messaging)의 인증 체계 | -| `*-certification.yml`, `*-qualification.yml`, `jpa-next-*.yml` | 템플릿이 광고하는 지원 매트릭스의 근거 | +| `main.yml`의 nightly 행렬 job(`jpa-postgresql`, `httpclient-transport`, `redis-topology`, `fileserver-nfs-ambiguity`, `notification-chaos`, `jpa-next`, `object-storage-aws`)과 `release.yml`의 영역별 release lane | 템플릿이 광고하는 지원 매트릭스의 근거. 서비스가 그 capability를 쓰면 남기고, 지운 capability의 job은 같이 지운다 | ## Consumer 필수 (파생 프로젝트가 유지해야 한다) @@ -29,13 +28,16 @@ | `qualityCheck` | SpotBugs / FindSecBugs | | `configContractCheck` | 환경변수 계약 | | `verifyDependencyLocks` | 재현 가능한 의존성 해석 | -| `dependency-vulnerability.yml` | dependency-review + Trivy | -| `ci-quality-gates.yml` | PR 게이트 | -| `release.yml` | 이미지 · SBOM 생산 | -| `docs-check.yml` | 문서 규칙(`scripts/check-docs.py`: 언어·머리 블록·참조·숫자·지도·링크·문체)과 Gradle 밖 스크립트·편집 훅의 시험(`scripts/tests/`). 파생 서비스의 문서도 같은 규칙을 따른다(`docs/README.md`) | -| `link-check.yml` | 문서의 외부 URL과 상대 링크(lychee) | -| `scripts/check-repo-layout.py`(`ci-quality-gates.yml` 안) | 저장소 최상위 배치. 서비스가 최상위 항목을 더하면 허용 목록과 `AGENTS.md` 지도를 함께 고친다 | -| action의 full SHA 핀 | 공급망 | +| `pr.yml`(`./gradlew :prCheck`, 필수 검사 `pr / done`) | PR 단계. 무엇을 돌리는지는 Gradle 태스크 `prCheck`가 정한다 | +| `main.yml`의 `main`·`integration`·`build-logic`·`configuration-cache` job | main 단계(`mainCheck`, `integrationCheck`) | +| `main.yml`의 `performance` job | nightly 성능 단계(`performanceCheck`) | +| `vulnerabilities` job(`scripts/ci/trivy-scan.sh`) | Trivy와 CISA KEV | +| `release.yml` | `releaseCheck`, 이미지 · SBOM · 서명 | +| `scripts/verify.sh` | 사람·세션이 workflow와 같은 단계를 돌리는 진입점 | +| `prCheck`의 `documentCheck`·`testDocumentChecks` | 문서 규칙(`scripts/check-docs.py`: 언어·머리 블록·참조·숫자·지도·링크·문체)과 Gradle 밖 스크립트·편집 훅의 시험(`scripts/tests/`). 파생 서비스의 문서도 같은 규칙을 따른다(`docs/README.md`) | +| `main.yml`의 `links` job | 문서의 외부 URL과 상대 링크(lychee) | +| `scripts/check-repo-layout.py`(`prCheck`의 `verifyRepositoryLayout`) | 저장소 최상위 배치. 서비스가 최상위 항목을 더하면 허용 목록과 `AGENTS.md` 지도를 함께 고친다 | +| action의 전체 URL·full SHA 핀 | 공급망 | ## 파생 프로젝트가 할 일 diff --git a/docs/httpclient/performance-baseline.md b/docs/httpclient/performance-baseline.md index ea6a387b..84edc224 100644 --- a/docs/httpclient/performance-baseline.md +++ b/docs/httpclient/performance-baseline.md @@ -16,7 +16,7 @@ lane은 매번 모든 상한을 단언한다. 기계에 따라 다른 상한을 끄는 스위치는 없다. 빌드가 `performance.assertions.enabled`에 `true` 아닌 값을 넣으면 strict lane convention이 성능 lane을 돌기 전에 실패시키고, -테스트 하나라도 건너뛰면 실패시킨다. `integration-main.yml`(`:performanceCheck`)과 `release.yml`이 도는 것도 같은 +테스트 하나라도 건너뛰면 실패시킨다. `main.yml`의 nightly `performance` job(`:performanceCheck`)과 `release.yml`이 도는 것도 같은 명령이다. 매번 잰 heap 증가량(`[httpclient-performance] streaming download heap increase … bytes, bound … bytes`)을 테스트 출력과 보고서에 찍고, 실패한 상한은 단언 메시지에 그 값을 다시 적는다. 판정 없는 숫자가 필요하면 JMH를 쓴다. diff --git a/docs/httpclient/repository-adaptation.md b/docs/httpclient/repository-adaptation.md index fbd7d5b9..bb61d15a 100644 --- a/docs/httpclient/repository-adaptation.md +++ b/docs/httpclient/repository-adaptation.md @@ -65,7 +65,7 @@ Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbo | 설계 §6.2는 Apache HttpClient 5를 HTTP/2 가능으로 등급 매긴다 | Spring의 blocking factory는 Apache의 **classic** client를 쓰고, 그것은 HTTP/1.1만 한다. HTTP/2는 Apache의 async client에 있다 | `ApacheBlockingTransportProvider`는 HTTP/1.1을 선언하고 HTTP/2 profile을 시작 때 거부한다. blocking HTTP/2는 JDK transport가 맡고, `NegotiatedProtocolContractTest`가 잰다. | | 설계 §28.1은 상태 있는 fixture로 WireMock을 든다 | WireMock의 Jetty 모듈은 이 모듈이 HTTP/3 때문에 이미 쓰는 Boot 관리 Jetty 12와 ABI가 달라 서버 시작에서 실패한다 | `StatefulUpstream`이 기존 fixture 서버 위에서 경로별 상태 있는 응답을 준다. shaded jar로 돌아가지 않고 WireMock 의존성을 지웠다 | | 작업마다 `git commit` | `AGENTS.md`: 커밋 정책은 `human-only` | 구현은 stage하지 않은 채 넘겼고, 커밋은 사람이 했다. 계획 중 일부러 실행하지 않은 단계는 이것 하나이고, 여기 적어 둔다. | -| `docs/httpclient/**`, `.github/workflows/httpclient-*.yml`, `scripts/verify-httpclient-docs.py` | 저장소가 이미 `docs/`와 `.github/workflows/`를 가진다 | 같은 저장소 상대 경로에 만들었다. | +| `docs/httpclient/**`, httpclient workflow, `scripts/verify-httpclient-docs.py` | 저장소가 이미 `docs/`와 workflow 폴더를 가진다 | 같은 저장소 상대 경로에 만들었다. httpclient 전용 workflow 파일은 2026-11-08 단계 파일 셋(`.gitea/workflows`)의 job으로 접었다. | ## 4. 설계에서 바뀌지 않은 것 diff --git a/docs/jpa/experimental-support-matrix.md b/docs/jpa/experimental-support-matrix.md index 15bee87f..492b6830 100644 --- a/docs/jpa/experimental-support-matrix.md +++ b/docs/jpa/experimental-support-matrix.md @@ -11,7 +11,7 @@ Experimental 코드는 `dev.caskeleton.adapter.outbound.persistence.experimental | 테넌트마다 schema | `schema.SchemaMultiTenantConnectionProvider`, `schema.SchemaTenantMigrationOrchestrator` | `SchemaTenantMigrationContractTest` | Experimental | | 테넌트마다 DB의 풀 예산 | `database.TenantDataSourceRegistry`, `database.TenantPoolBudget` | `TenantPoolCapacityContractTest` | Experimental | | 일관성을 아는 read replica | `replica.ConsistencyAwareDataSourceRouter`(`ReplicaLagMonitor`는 직접 구현) | `ReadAfterWriteRoutingContractTest` | Experimental | -| Jakarta Persistence 4.0, Hibernate ORM 8, PostgreSQL 19 | 없음 — `.github/workflows/jpa-next.yml`의 probe가 `NOT_EXECUTABLE`을 기록 | `Jpa4CompatibilityTest`, `Hibernate8CompatibilityTest`, `PostgreSql19CompatibilityTest`(unit lane의 버전 canary) | 실행 불가 | +| Jakarta Persistence 4.0, Hibernate ORM 8, PostgreSQL 19 | 없음 — `.gitea/workflows/main.yml`의 nightly `jpa-next` job이 `NOT_EXECUTABLE`을 기록 | `Jpa4CompatibilityTest`, `Hibernate8CompatibilityTest`, `PostgreSql19CompatibilityTest`(unit lane의 버전 canary) | 실행 불가 | > 이력: 이것들 앞에 있던 `backend.jpa.experimental.*` 스위치와 `ExperimentalFeatureGate`는 2026-09-25에 지웠다. 어떤 코드도 > 설정에서 스위치를 읽지 않아서 켜도 아무 일이 없었고, gate는 호출자가 스스로 만든 map만 확인했다. diff --git a/docs/jpa/repository-adaptation.md b/docs/jpa/repository-adaptation.md index 2bb8bcf2..2cb9d25c 100644 --- a/docs/jpa/repository-adaptation.md +++ b/docs/jpa/repository-adaptation.md @@ -91,8 +91,8 @@ Docker가 필요한 lane은 건너뛰지 않고 닫힌 채 실패한다. 이 lea | PostgreSQL 16·17·18 Stable matrix | 컨테이너 이미지는 `src/config/testing/container-images.properties`에 digest로 고정한다 | `PostgreSqlVersion`이 PG 16, 17, 18을 정확히 선언한다. 기본 lane은 16이고, 다른 major는 `-Pjpa.matrix.versions=`로 고른다. 계약 suite(`JpaPlatformContractSupport.start()`)는 JVM 하나에 major 하나만 받는다. 여러 major를 한 번에 받는 것은 `StablePostgreSqlMatrixContractTest`뿐이다. 모르는 값이나 빈 선택은 건너뛰지 않고 오류다. | | `settings.gradle.kts` 모듈 등록 | fail-closed registry | registry는 바꾸지 않았다. leaf 신원, Gradle path, 허용 의존은 그대로다. | | `infra/jpa/{postgres,roles,toxiproxy}` | 이 repo는 운영 인프라 파일을 두지 않는다(2026-11-07 소유자 결정) | 2026-11-07에 지웠다(쓰는 곳이 없거나 운영 인프라 파일). 운영 DB 조건은 `docs/jpa/security.md`로 옮겼다. | -| `docs/jpa/**`, `docs/adr/ADR-JPA-*`, `.github/workflows/jpa-*.yml` | 저장소가 이미 `docs/`와 `.github/workflows/`를 가진다 | 같은 저장소 상대 경로에 만들었다. | -| 릴리스를 막는 집계 | `persistence-jpa/release/release-registry.json` 위의 `jpaReleaseQualification`(persistence-jpa `build.gradle`). `.github/workflows/release.yml`의 `jpa-release-gate` job이 PostgreSQL major마다 돌린다 | registry가 막는 lane을 이름 대고, Gradle이 lane마다 도는 법을 정하고, CI는 matrix 일정만 잡는다. | | +| `docs/jpa/**`, `docs/adr/ADR-JPA-*`, JPA workflow | 저장소가 이미 `docs/`와 workflow 폴더를 가진다 | 같은 저장소 상대 경로에 만들었다. JPA 전용 workflow 파일은 2026-11-08 단계 파일 셋(`.gitea/workflows`)의 job으로 접었다. | +| 릴리스를 막는 집계 | `persistence-jpa/release/release-registry.json` 위의 `jpaReleaseQualification`(persistence-jpa `build.gradle`). `.gitea/workflows/release.yml`의 `jpa-release-gate` job이 PostgreSQL major마다 돌린다 | registry가 막는 lane을 이름 대고, Gradle이 lane마다 도는 법을 정하고, CI는 matrix 일정만 잡는다. | | | task마다 `git add` + `git commit` | `AGENTS.md`: 커밋 정책은 `human-only`다. 에이전트는 stage, commit, amend, push를 하지 않는다 | 구현은 stage하지 않은 채로 넘겼다. 일부러 하지 않은 계획 단계는 이것 하나이고, 여기에 기록한다. | | Querydsl을 선택 모듈 의존성으로 | Querydsl은 이 저장소의 의존성 묶음에 없다 | `querydsl`은 계획의 계약대로 구현하되 Querydsl 타입을 `compileOnly` 뒤에 둔다. 그래서 Stable 런타임 classpath에는 Querydsl이 없고, 쓰기로 한 배포가 artifact를 직접 더한다. | | Hibernate Envers를 모듈 의존성으로 | Envers는 이 저장소의 의존성 묶음에 없다 | Querydsl과 같다. `compileOnly` + 명시적 opt-in. 계획의 "Envers is opt-in and never enabled by a global base class"와 맞는다. | diff --git a/docs/jpa/support-matrix.md b/docs/jpa/support-matrix.md index b0b5cf92..95a65f05 100644 --- a/docs/jpa/support-matrix.md +++ b/docs/jpa/support-matrix.md @@ -6,16 +6,16 @@ registry는 major마다 지원 수준을 칸으로 선언하고, gate마다 그 증거를 만드는 Gradle 태스크를 이름 댄다. 이 문서는 registry가 말하는 것을 설명한다. 표를 고치지 말고 registry를 고친다. 표가 따라오지 않으면 빌드가 실패한다. -- `JpaReleaseRenderingTest`가 DB 표, gate 표, `release.yml`의 JPA matrix와 승격 목록을 registry와 비교한다. +- `JpaReleaseRenderingTest`가 DB 표, gate 표, `.gitea/workflows/release.yml`의 JPA matrix를 registry와 비교한다. 릴리스 이미지 job은 그 matrix job 전부를 `needs`로 기다린다. 그래서 같은 실행·같은 커밋에서 모든 Stable major가 통과해야 이미지가 나간다. - `jpaReleaseQualification` 집계 태스크는 막는 gate마다 그 태스크에 의존한다. 그래서 없는 태스크를 이름 댄 gate는 태스크 그래프를 만들 때 실패한다. -- `jpa-nightly.yml`의 matrix도 같은 비교를 받는다. Experimental major는 `.github/workflows`의 어떤 lane이 그것을 대상으로 - 기록해야 하고, Stable lane은 그것을 돌리면 안 된다. +- `.gitea/workflows/main.yml`의 nightly `jpa-postgresql` matrix도 같은 비교를 받는다. Experimental major는 `.gitea/workflows`의 + 어떤 lane이 그것을 대상으로 기록해야 하고(지금 `main.yml`의 `jpa-next` job), Stable lane은 그것을 돌리면 안 된다. > 이력: 전에는 `JpaReleaseManifest`가 이 파일을 정규식으로 읽었다. 어느 표나 문장에서 나왔든 `PostgreSQL NN`이 지원 > 버전이 됐다. Experimental major가 Stable 목록에 들어갔고, 본문에 한 번 나온 버전이 지원으로 셌고, 문자열이 문서 > 어딘가에 남아 있는 한 major를 내려도 아무것도 바뀌지 않았다. registry로 옮긴 뒤에도 한동안 아래 표는 손으로 썼다. -> 그래서 registry에서 내린 major가 여기서는 Stable로 남고 자기 전체 릴리스 job을 계속 가졌다. `jpa-nightly.yml`은 자기 +> 그래서 registry에서 내린 major가 여기서는 Stable로 남고 자기 전체 릴리스 job을 계속 가졌다. nightly workflow는 자기 > matrix를 아무도 확인하지 않아서, 내리기가 릴리스 lane만 고치고 nightly lane은 그 major를 계속 인증했다. Experimental > major의 「compatibility lane only」는 어떤 파일도 가리키지 않았다. lane은 있었지만 registry, 이 문서, 릴리스 workflow를 > 끝까지 읽어도 그것을 알 수 없어서, 찾던 사람은 없다고 결론 냈다. @@ -27,7 +27,7 @@ registry가 말하는 것을 설명한다. 표를 고치지 말고 registry를 | PostgreSQL 16 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) | | PostgreSQL 17 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) | | PostgreSQL 18 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) | -| PostgreSQL 19 | Experimental | [`jpa-next.yml`](../../.github/workflows/jpa-next.yml) — `NOT_EXECUTABLE`: `postgres:19-alpine`이 게시되지 않아 그 major의 컨테이너를 띄운 적이 없다. 승격에는 ADR이 필요하다 | +| PostgreSQL 19 | Experimental | [`main.yml`](../../.gitea/workflows/main.yml)의 `jpa-next` job — `NOT_EXECUTABLE`: `postgres:19-alpine`이 게시되지 않아 그 major의 컨테이너를 띄운 적이 없다. 승격에는 ADR이 필요하다 | | H2 | Local convenience | PostgreSQL 동작의 증거가 **절대** 아니다 | major마다 **자기 릴리스 job**이 있다. `release.yml`의 `jpa-release-gate` job이 major마다 job 하나로 펼치고, 승격 job은 세 diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index 6196463b..ac1ff8b0 100644 --- a/docs/upgrade/2026-11-maturity-review.md +++ b/docs/upgrade/2026-11-maturity-review.md @@ -162,6 +162,20 @@ PR 단계 trivy 검사(`dependency-vulnerability.yml`의 HIGH·CRITICAL 단계) | B-55 | 삭제: `src/platforms/grpc`, `src/platforms/grpc-advanced`, `src/platforms/optional-build`(두 번째 빌드 `optional-platforms` 전체), registry의 `"build": "optional-grpc"` 9행, workflow job `ci-quality-gates.yml` `optional-platforms`·`grpc-proto-buf`(그리고 `release-gate`의 두 `needs`), `integration-main.yml`의 optional 성능 단계와 job `grpc-optional-platform-integration`, `release.yml` job `grpc-stable-release-gate`(그리고 이미지 job의 `needs` 한 줄), 살아 있는 문서 `docs/compatibility/`(폴더째), `docs/runbooks/grpc-platform-operations.md`·`grpc-advanced-capabilities.md`. 새 자리는 grpc-library repo이고 같은 이름의 파일이 이력째 있다. 기록(`docs/adr/ADR-GRPC-*` 7개, `docs/design/2026-08-30-grpc-platform-adaptation-design.md`)은 본문을 두고 머리 블록 「현재 정본」만 그 repo를 가리키게 했다. 사본이 그 repo에도 있다. 그 repo에서 Maven group과 Java 패키지는 `dev.cakit.grpc`, proto 패키지는 `cakit.grpc.common.v1`이다(템플릿 재사용 체크리스트의 `dev.caskeleton` 바꾸기와 겹치지 않게 다른 이름) | 이 경로를 고친 서비스는 「수정 대 삭제」 충돌이 난다. `project(':grpc:…')`·`project(':grpc-advanced:…')`나 `-p platforms/optional-build`를 쓴 서비스는 빌드가 실패한다 | 쓰지 않았으면 삭제를 그대로 받는다. 썼으면 grpc-library 첫 버전(`1.0.0`, 소유자가 태그를 단 뒤)을 좌표 `dev.cakit.grpc:<모듈>:1.0.0`으로 받고(저장소 선언은 그 repo README 「받는 법」), import를 `dev.caskeleton.grpc` → `dev.cakit.grpc`로 바꾼다 | design-docs `repo-structure/05-library-repos.md` 4·13절, `docs/work/reference/related-repos.md` | | B-56 | 빌드 규칙·카탈로그: build-logic의 `ca.grpc-platform-module`·`ca.optional-architecture-registry` 플러그인과 `MainBuild`(두 번째 빌드에서 주 빌드를 찾던 것)를 지웠다. 도구 설정·테스트 이미지 목록·registry는 Gradle 루트(`src/`)에서만 찾는다. 카탈로그에서 `protobufPlugin`·`protobuf-java-grpc`·`protoc`·plugin `protobuf`를, SpotBugs 제외에서 gRPC 플랫폼 클래스 줄을 지웠다 | 서비스 leaf가 `ca.grpc-platform-module`이나 `libs.protoc`·`libs.protobuf.java.grpc`·`libs.plugins.protobuf`를 쓰면 빌드가 실패한다. `src/` 밖 두 번째 빌드에서 이 build-logic을 쓰던 서비스는 도구 설정을 못 찾는다 | 그 leaf `build.gradle`에서 `io.grpc:grpc-bom` import와 protobuf 플러그인 버전을 직접 적거나, 지운 카탈로그 항목을 서비스 카탈로그에 다시 더한다 | 같은 설계 13.1절 2단계 | +### 3.9 CI — workflow를 단계 파일 셋으로 접었다 + +2026-11-08. 소유자가 design-docs `repo-structure/03-ci.md` 7절 B안과 11절 ①~⑧을 권하는 안대로 정했다(2026-11-07). workflow 15개를 `.gitea/workflows`의 `pr.yml`·`main.yml`·`release.yml` 셋으로 접고, 무엇을 돌릴지는 Gradle 단계 태스크가 정한다. Gitea Actions(desktop runner)에서 실제로 돈다. + +| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 | +|---|---|---|---|---| +| B-57 | 삭제: `.github/workflows`의 `build-logic.yml`, `ci-quality-gates.yml`, `dependency-vulnerability.yml`, `docs-check.yml`, `fileserver-nightly.yml`, `fileserver-pr.yml`, `integration-main.yml`, `jpa-next.yml`, `jpa-nightly.yml`, `link-check.yml`, `notification-platform.yml`, `object-storage-qualification.yml`, `pr-adapters.yml`, `redis-sdk-topology.yml`, `release.yml`, 그리고 `.github/actions/setup-gradle-java`, `.github/scripts/install-jq.sh`, `.github/dependency-review-config.yml`. 다른 단계가 이미 돌리던 job(`fileserver-pr` 다섯, `fileserver-nightly` 재실행 셋, `jpa-nightly` lane 셋, `notification-platform` `pr`, object storage MinIO 둘)은 옮기지 않고 지웠다. 나머지는 세 파일의 job이 됐다: PR은 `pr.yml`(`gradle`·`vulnerabilities`·`done`), main과 nightly는 `main.yml`(`main`·`integration`·`build-logic`·`configuration-cache`·`links`·`vulnerabilities`·`http3-experimental`, nightly 행렬과 `compose-smoke`, 마지막에 `performance`), 태그는 `release.yml` | 이 파일을 고친 서비스는 「수정 대 삭제」 충돌이 난다. Gitea는 `.gitea/workflows`가 있으면 `.github/workflows`를 읽지 않으므로 남긴 `.github/workflows` 파일은 돌지 않는다 | 자기 workflow 변경을 세 파일의 같은 단계 job으로 옮긴다. 새 workflow 파일을 만들지 않는다(`docs/work/reference/gates.md` 7절). GitHub에서 돌리는 서비스는 `https://github.com/` 접두어를 뺀다 | design-docs `repo-structure/03-ci.md` 3.1·7.2절 | +| B-58 | 단계 이동: 어댑터 컨테이너 lane(web·websocket·httpclient·jpa)과 Redis standalone topology lane이 PR에서 빠졌다. 매개 변수가 없는 것은 원래부터 `mainCheck`·`integrationCheck` 안이고, 행렬(PostgreSQL major, HTTP transport, Redis topology)은 nightly job이다. `performanceCheck`는 매 main push가 아니라 nightly에서 다른 무거운 job 뒤에 돈다. build-logic 시험은 main 단계다. main push는 `ci`를 다시 돌리지 않는다(PR 단계가 돌렸다) | PR이 어댑터 회귀를 막지 않고 main에서 빨갛게 된다 | 어댑터를 바꾼 PR은 그 leaf의 strict lane을 desktop에서 돌린다(`docs/work/reference/gates.md` 2절). main을 오래된 PR 머리로 병합하지 않게 branch protection의 「오래된 브랜치 막기」를 켠다 | 같은 설계 11절 ②③⑦ | +| B-59 | 새 Gradle 태스크: `prCheck`(= `ci` + `verifyDependencyLocks` + `verifyComposeProfiles` + `verifyRepositoryLayout` + `documentCheck`←`testDocumentChecks`). `verifyStrictLaneStages`가 workflow YAML·bash를 해석하지 않고 그래프 검사와 형식 검사만 한다. `strictLaneStages` 문법이 `stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle'` 모양으로 바뀌었고(단계마다 workflow·이벤트·필터·job·옵션·조건), `workflowDirectory`는 `.gitea/workflows`다. build-logic의 `ShellScript`·`WorkflowGradleInvocations`·`TaskSelectors`를 지웠다 | 서비스 `src/build.gradle`의 옛 `stage ':ci', ':mainCheck', …` 줄은 설정 단계에서 실패한다. 단계 job이 정해진 한 줄이 아니면 `verifyStrictLaneStages --dry-run`이 실패한다 | `src/build.gradle`의 `strictLaneStages` 블록을 템플릿 것으로 바꾸고 자기 workflow job 이름에 맞춘다. 단계 job은 `run: ./gradlew <단계> <옵션>` 한 줄로 쓴다(`src/build-logic/AGENTS.md` 「단계 job의 모양」) | 같은 설계 7.4절 | +| B-60 | 릴리스: 이미지를 ghcr가 아니라 이 Gitea의 컨테이너 레지스트리(`<서버>/<소유자>/caskeleton`)에 올리고, cosign keyless 대신 키 쌍으로 서명한다. repo secret `PACKAGE_TOKEN`·`COSIGN_PRIVATE_KEY`·`COSIGN_PASSWORD`가 필요하다. JPA 승격은 artifact 대조 대신 `needs: jpa-release-gate`(같은 실행의 행렬 전부)다. 손으로 실행하면 push·서명 앞까지 돈다. `actions/upload-artifact`·`download-artifact`를 쓰지 않는다(증거는 job 로그) | 태그를 달아도 secret이 없으면 push에서 실패한다. keyless 신원(`--certificate-identity`)으로 확인하던 admission 정책은 새 서명을 거절한다 | secret을 만들고, admission 정책을 서명 job이 로그에 남긴 공개 키로 바꾼다. 다른 레지스트리를 쓰면 `release.yml`의 `REGISTRY` 계산을 바꾼다 | 같은 설계 9절, 11절 ④ | +| B-61 | 검증 진입점 `scripts/verify.sh <단계>`(`docs`·`leaf`·`pr`·`main`·`nightly`·`release`·`app`·`round`). 단계 이름이 workflow와 같고, 무거운 단계는 지금 작업 트리를 패치로 desktop에 보내 잠금 아래에서 돌린다. workflow가 부르는 스크립트는 `scripts/ci/`(`trivy-scan.sh`, `redis-topology.sh`, `forward-ports.py`, `verify-configuration-cache.sh`)다 | 없음(새 파일). desktop·잠금 경로는 소유자 환경 값이다 | 자기 환경에 맞게 `VERIFY_HOST`·`VERIFY_REMOTE_REPO`·`VERIFY_LOCK`을 주거나 `--on here`로 쓴다 | design-docs `harness/01-harness-design.md` 6절 | +| B-62 | dev lane overlay(`src/app-bootstrap/compose-lanes/dev.yaml`)의 heap dump가 bind mount `./tmp/heap-dumps`가 아니라 named volume `heap-dumps`다. Docker가 root 소유로 만든 폴더 때문에 worktree를 지우지 못했다 | 호스트 `tmp/heap-dumps`에 dump가 생기지 않는다 | `docker compose cp app:/var/tmp/heap/ .`로 꺼낸다 | `docs/work/operate.md` 4.1절 | +| B-63 | fileserver 지원 매트릭스(`docs/fileserver/support-matrix.md`)의 증거 칸이 job id 대신 테스트 클래스·모듈 `test`·남은 job(`fileserver-nfs-ambiguity`, release의 셋)이고, `FileserverDocumentationCoverageTest`가 행마다 그 이름이 있는지 본다 | 서비스가 그 표에 지운 job id를 적었으면 시험이 실패한다 | 그 행의 증거를 실제 테스트 클래스나 모듈 `test`로 바꾼다 | B-57 | + ## 4. DB 마이그레이션 ### 4.1 새 버전과 영향 diff --git a/docs/work/delegate.md b/docs/work/delegate.md index 22e50aa0..5b3b590d 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -71,7 +71,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 | `docs/registries/*.yaml` | 오류 코드·env 키·지표를 여러 기능이 함께 쓴다 | | `docs/architecture/*-api-surface.txt`, `docs/security/public-paths-snapshot.txt` | 생성되는 스냅숏이다 | | 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`·`skills/`·`agents/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 | -| `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 | +| `.gitea/workflows/*`, `strictLaneStages`(`src/build.gradle`) | 단계 job의 모양을 함께 검사한다 | 나눌 때 지킬 것: diff --git a/docs/work/operate.md b/docs/work/operate.md index 27e9e5d9..78f08c7a 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -30,10 +30,14 @@ - 노트북에서는 git, grep, 파일 읽기, 문서 편집, `python3 scripts/*.py` 검사만 한다. **Gradle, Docker, Testcontainers, 테스트, 게이트, 성능 측정은 desktop에서 돌린다.** 예외는 편집 훅의 한 파일 포매터 하나다(Gradle 없이 JVM 한 번, 캐시에 있는 jar만. 소유자 결정 2026-11-07, `scripts/hooks/README.md`). - desktop의 Gradle·Docker 실행은 모두 공유 잠금 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 짝 프론트 repo도 같은 desktop에서 같은 잠금을 쓴다. +- desktop의 Gradle은 `--no-daemon`(다시 부르는 Gradle에는 `GRADLE_OPTS=-Dorg.gradle.daemon=false`)으로 돌린다. 오래 사는 daemon 하나가 여러 worktree의 빌드를 받으면 서로 호환되지 않는 compiler worker가 쌓여 메모리를 채운다(2026-11-08: worker 41개, 14.2GB, 스왑 4GB). `scripts/verify.sh`는 둘 다 한다. 노트북 개발자용 repo 기본값(`src/gradle.properties`)은 daemon을 그대로 쓴다. - desktop의 기존 checkout `~/workspace/clean-architecture-backend-template`은 여러 세션이 함께 쓴다. 그 `stash@{0}`는 소유자의 보관분이다. 건드리지 않는다. `git stash pop`·`drop`·`clear`와 이름 없는 `git stash`를 쓰지 않는다. - design-docs repo는 노트북 `~/workspace/desktop-server-git/design-docs`에 있다. - desktop 기본 셸은 zsh다. 파이프의 rc는 `bash -o pipefail -c '<명령> | tee <로그>'; echo "rc=$?"`로 받는다(zsh에는 `PIPESTATUS`가 없다). 자기 실행을 멈출 때는 시작할 때 남긴 PID로 `kill `를 쓴다. `pkill -f <경로>`는 그 경로가 든 ssh 명령줄 자신과도 맞아 세션을 끊는다. - CI runner(2026-11-07): Gitea Actions가 켜졌고, desktop에 `desktop-runner` 하나(`gitea/runner` dind, `capacity: 1`, label `ubuntu-latest`)가 돈다. desktop은 12코어·31GB다. CI job은 공유 잠금을 쓰지 않으므로, 손으로 돌린 게이트가 느리면 `docker ps`로 runner job이 함께 도는지 본다. +- runner의 job 컨테이너 안의 `localhost`는 dind 데몬이 띄운 서비스가 아니다. Testcontainers는 이것을 스스로 처리한다. compose로 띄운 서비스에 `localhost`로 붙는 job은 `scripts/ci/redis-topology.sh`처럼 포트를 넘겨야 한다. + +**`scripts/verify.sh`가 아래 절차를 한다.** `scripts/verify.sh <단계>`는 지금 작업 트리(커밋하지 않은 변경 포함)를 패치로 만들어 desktop에 보내고, 기준 커밋에서 새 worktree를 만들어 얹고, 트리 해시가 같은지 본 뒤 잠금 아래에서 단계를 돌리고, 로그를 `~/<브랜치 이름>-logs/<단계>.log`에 남기고, worktree를 지운다. push하지 않는다. 단계와 돌리는 명령은 [reference/gates.md](reference/gates.md) 1절이다. 아래는 스크립트가 하는 일이고, 스크립트를 쓸 수 없을 때(다른 기준 커밋, 단계 밖의 명령 하나) 손으로 한다. 절차: @@ -51,7 +55,7 @@ uptime # 다른 빌드가 돌고 있는지 부 # 3) 공유 잠금 아래에서 한 번에 하나씩 돌리고 rc와 로그를 남긴다 cd ~/workspace/<작업 이름>/src -flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?" +flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --no-daemon --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?" # 4) 끝나면 worktree를 지운다 cd ~/workspace/clean-architecture-backend-template @@ -80,7 +84,7 @@ git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업 - 형식은 편집 훅이 파일마다 맞추므로 보통 바뀌는 것이 없다. 그래도 커밋을 나누기 전에 확인한다(나눈 뒤에 고치면 앞 커밋을 다시 만들어야 한다). 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다. ```bash -ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --console=plain' +ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --no-daemon --console=plain' ssh desktop 'cd ~/workspace/<작업 이름> && git diff --binary' | git apply --index && git write-tree # 노트북 ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' # 같은 해시여야 한다 ``` @@ -89,7 +93,7 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' ### 4.2 게이트 실행과 기록 -1. [reference/gates.md](reference/gates.md) 2절로 돌릴 게이트를 고른다. 라운드 끝이면 3절의 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것, (다) 로컬 도구가 없는 것 전체다. +1. [reference/gates.md](reference/gates.md) 2절로 돌릴 게이트를 고른다. 라운드 끝이면 3절의 `scripts/verify.sh round`, (나) workflow에만 있는 job 중 바뀐 영역의 것, (다) 로컬 도구가 없는 것 전체다. 2. 잠금을 얻은 뒤 1분 부하를 적고 돌린다. 한 번에 하나씩이다. 3. 첫 실행이 실패하면 원인을 찾아 고치고 다시 돌린다. 첫 실행과 다시 돌린 결과를 둘 다 적는다. 4. 결과를 [reference/gates.md](reference/gates.md) 4절 형식으로 적는다: 게이트, rc, 시간, 직전 부하, 로그 경로, 대상 커밋. @@ -97,10 +101,10 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' ### 4.3 릴리스 -- 릴리스는 `v*` 태그 push로 시작한다(`.github/workflows/release.yml`). 태그와 push는 소유자가 한다. -- 태그 전에 그 커밋에서 `./gradlew :releaseCheck -PgitRevision= --console=plain`을 desktop에서 돌린다. sha 없이 돌리면 설계대로 실패한다. -- 태그는 PR 게이트와 main 단계를 이미 통과한 main 커밋에서 자른다. 그래서 `releaseCheck`는 `ci`를 다시 돌리지 않는다. -- 이미지 서명·SBOM은 workflow가 한다(cosign keyless). +- 릴리스는 `v*` 태그 push로 시작한다(`.gitea/workflows/release.yml`). 태그와 push는 소유자가 한다. +- 태그 전에 그 커밋에서 `scripts/verify.sh release`를 돌리고, `release.yml`을 손으로 실행(`workflow_dispatch`)해 리허설한다. 손으로 실행하면 모든 release lane, 이미지 빌드, SBOM, 이미지 검사까지 돌고 push·서명은 하지 않는다. +- 태그는 PR 단계와 main 단계를 이미 통과한 main 커밋에서 자른다. 그래서 `releaseCheck`는 `ci`를 다시 돌리지 않는다. +- 이미지는 이 Gitea의 컨테이너 레지스트리(`<서버>/<소유자>/caskeleton`)에 올리고, digest를 cosign 키 쌍으로 서명한다(소유자 결정 2026-11-07: Gitea는 keyless 서명에 필요한 OIDC 토큰을 주지 않는다). repo secret `PACKAGE_TOKEN`·`COSIGN_PRIVATE_KEY`·`COSIGN_PASSWORD`는 소유자가 만든다. 서명 job은 확인에 쓴 공개 키를 로그에 남긴다. 배포 쪽 admission 정책은 그 공개 키로 확인한다. ### 4.4 파생 서비스에 템플릿 변경 넘기기 diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index ef7224e1..b848cdcd 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -1,16 +1,31 @@ # 게이트 -무엇을, 언제, 어디서 돌리는지 정한다. 게이트 구성의 정본은 `src/build.gradle`의 라이프사이클과 `.github/workflows/`다. 이 문서와 그 둘이 다르면 그 둘이 맞고, 이 문서를 고친다. 실행 위치(desktop, 잠금)는 [operate.md](../operate.md) 「실행 위치」다. +무엇을, 언제, 어디서 돌리는지 정한다. 무엇이 한 단계인지는 `src/build.gradle`의 단계 태스크(`prCheck`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`)가 정한다. workflow(`.gitea/workflows/`의 `pr.yml`·`main.yml`·`release.yml`)와 `scripts/verify.sh`는 그 태스크를 부르기만 한다. 이 문서와 그 셋이 다르면 그 셋이 맞고, 이 문서를 고친다. 실행 위치(desktop, 잠금)는 [operate.md](../operate.md) 「실행 위치」다. ```text -작업 중 :check (+ 그 leaf의 관련 strict lane) +작업 중 scripts/verify.sh leaf (+ 그 leaf의 관련 strict lane) 묶음 끝 + architectureCheck · 바뀐 표면의 검사(env 키·공개 경로·의존성 잠금) · 관련 lane -라운드 끝 합친 트리에서 3절 묶음 전체 — workflow가 PR·main에서 돌리는 것과 같은 명령 +라운드 끝 합친 트리에서 scripts/verify.sh round — workflow가 PR·main·nightly·태그에서 돌리는 것과 같은 명령 ``` ## 1. 게이트 목록 -명령은 모두 `src/`에서 실행한다. leaf의 Gradle path는 `src/config/architecture/modules.json`의 `gradle_path`에서 읽는다. leaf별 명령 목록을 문서에 적지 않는다. +Gradle 명령은 모두 `src/`에서 실행한다. `scripts/verify.sh`는 저장소 루트에서 부르고, Gradle·Docker가 드는 단계를 desktop으로 옮겨 잠금 아래에서 돌린다([operate.md](../operate.md) 4.1절). leaf의 Gradle path는 `src/config/architecture/modules.json`의 `gradle_path`에서 읽는다. leaf별 명령 목록을 문서에 적지 않는다. + +| `scripts/verify.sh` 단계 | 무엇을 돌리나 | workflow | +| --- | --- | --- | +| `docs` | `check-work-docs.py`, `check-docs.py`, `scripts/tests` 자기 시험, `check-repo-layout.py`(Gradle 없음, 노트북 가능) | `pr.yml`의 `prCheck` 안 | +| `leaf ` | 그 leaf의 `check` | — | +| `pr` | `./gradlew :prCheck`, `./gradlew :verifyStrictLaneStages --dry-run` | `pr.yml` `gradle` | +| `main` | `:mainCheck --continue`, `:integrationCheck --continue`, `-p build-logic test`, `scripts/ci/verify-configuration-cache.sh` | `main.yml`(push) | +| `nightly` | compose smoke 전부, 마지막에 `:performanceCheck --continue` | `main.yml`(schedule·수동) | +| `release` | `:releaseCheck`(지금 커밋을 provenance로) | `release.yml` `release` | +| `app` | `scripts/bootstrap-local.sh`(앱을 띄워 health와 기본 endpoint 확인) | — | +| `round` | `pr` → `main` → `nightly` → `release`, 첫 실패에서 멈춘다 | — | + +workflow에만 있는 job: `pr.yml`·`main.yml`의 `vulnerabilities`(trivy, `scripts/ci/trivy-scan.sh`), `main.yml`의 `links`(lychee), nightly 행렬(`jpa-postgresql`·`httpclient-transport`·`redis-topology`·`fileserver-nfs-ambiguity`·`notification-chaos`·`jpa-next`), `release.yml`의 release lane과 이미지 job. 도구를 내려받거나 runner 환경이 필요해 `verify.sh`에 넣지 않았다. 손으로 돌리는 법은 3절 (다)다. + +게이트 하나씩: | 게이트 | 무엇 | 단계 | 정의·workflow | | --- | --- | --- | --- | @@ -19,18 +34,18 @@ | `./gradlew :app-bootstrap:architectureTest` | 저장소 전체 ArchUnit suite만 | 작업 중 | app-bootstrap `architectureTest` source set | | `qualityCheck` | SpotBugs, FindSecBugs(운영 코드) | PR(`ci` 안) | `src/build.gradle` | | `testQualityCheck` | 같은 분석을 모든 테스트 source set에(`config/spotbugs/exclude-test.xml` 기준) | main(`mainCheck` 안) | `src/build.gradle` | -| `ci` | leaf `check`(API surface 포함) + `architectureCheck` + `qualityCheck` | PR | `ci-quality-gates.yml`: `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` | -| `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 단계에 속하는가 | PR | `ci-quality-gates.yml` | -| `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가(저장소 루트에서) | PR | `ci-quality-gates.yml` | -| `python3 scripts/check-repo-layout.py` | 저장소 루트와 `src/` 최상위에 허용 목록 밖의 항목이 없는가, registry 경로가 허용 폴더 안인가. 아무도 가리키지 않는 compose·스크립트 파일은 경고 | PR | `ci-quality-gates.yml` | -| `python3 scripts/check-docs.py` | 살아 있는 문서의 언어, 기록·ADR 머리 블록, 문서의 인라인 코드 경로·Gradle 경로가 지금 있는가, 복사한 숫자(`docs/README.md` 「문서 검사」). 앞에 자기 시험 `python3 -m unittest discover -s scripts/tests`를 돈다 | PR·main push | `docs-check.yml`(경로 필터 없음) | -| `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `integration-main.yml`: `./gradlew :mainCheck --continue --warning-mode=fail` | -| `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `integration-main.yml` | -| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | main·nightly | `integration-main.yml`. 5절 | -| `releaseCheck -PgitRevision=` | 릴리스 provenance + 공개 경로 스냅숏. sha 없이 돌리면 설계대로 실패한다 | 태그 | `release.yml` | +| `ci` | leaf `check`(API surface 포함) + `architectureCheck` + `qualityCheck` | PR(`prCheck` 안) | `src/build.gradle` | +| `prCheck` | `ci` + `verifyDependencyLocks` + `verifyComposeProfiles`(compose lane이 선언대로 렌더링되는가) + `verifyRepositoryLayout`(`check-repo-layout.py`) + `documentCheck`(`check-docs.py`, 앞에 `scripts/tests` 자기 시험) | PR | `pr.yml` `gradle`: `./gradlew :prCheck` | +| `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 단계 태스크 하나의 계획에 들어 있는가(그래프 검사), 단계마다 선언한 workflow job이 `./gradlew <단계>` 한 줄을 정해진 조건으로 돌리는가(형식 검사) | PR | `pr.yml` `gradle` 둘째 줄. 형식은 `src/build-logic/AGENTS.md` | +| `python3 scripts/check-repo-layout.py` | 저장소 루트와 `src/` 최상위에 허용 목록 밖의 항목이 없는가, registry 경로가 허용 폴더 안인가. 아무도 가리키지 않는 compose·스크립트 파일은 경고 | PR(`prCheck` 안) | `verifyRepositoryLayout` | +| `python3 scripts/check-docs.py` | 살아 있는 문서의 언어, 기록·ADR 머리 블록, 문서의 인라인 코드 경로·Gradle 경로가 지금 있는가, 복사한 숫자, 상대 링크(`docs/README.md` 「문서 검사」) | PR(`prCheck` 안) | `documentCheck` | +| `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `main.yml` `main`: `./gradlew :mainCheck --continue` | +| `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `main.yml` `integration` | +| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | nightly(다른 무거운 job 뒤) | `main.yml` `performance`. 5절 | +| `releaseCheck` | 릴리스 provenance + 공개 경로 스냅숏. 커밋을 `GITHUB_SHA`·`GIT_SHA`·`-PgitRevision=`로 받고, 없으면 설계대로 실패한다 | 태그 | `release.yml` `release` | | `:app-bootstrap:verifyEnvKeys` | env 키 레지스트리와 profile YAML·`.env.example` | `mainCheck` 안(`configContractCheck`) | build-logic `ca.config-contract` | | `verifyPublicPathSnapshot` | 기본 공개 경로가 `docs/security/public-paths-snapshot.txt`와 같은가 | `mainCheck`·`releaseCheck` 안 | `src/build.gradle` | -| `verifyDependencyLocks` | lockfile | PR | `ci-quality-gates.yml` | +| `verifyDependencyLocks` | lockfile | PR(`prCheck` 안) | `src/build.gradle` | | `:app-bootstrap:documentContractTest` | 문서와 코드를 대조하는 lane(태그 `document-contract`) | main(`mainCheck` 안) | `src/app-bootstrap/build.gradle` | | `:app-bootstrap:repositoryContractTest` | 빌드 스크립트·workflow·compose를 읽는 계약(태그 `repository-contract`) | PR | `src/app-bootstrap/build.gradle` | @@ -51,11 +66,11 @@ | 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서가 가리키던 경로가 사라진다) | | `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서 | `python3 scripts/check-work-docs.py` | | 다른 매뉴얼에서 이력 ID를 걷어냄 | `python3 scripts/check-work-docs.py --history <파일 또는 폴더>` | -| build-logic·workflow | `-p build-logic check javadoc`, `verifyStrictLaneStages --dry-run` | +| build-logic·workflow(`.gitea/`) | `-p build-logic check javadoc`, `verifyStrictLaneStages --dry-run` | | 패키지 규칙, 생성 명령 템플릿 | `verifyFeatureScaffold`(`mainCheck` 안) | | 마이그레이션 | persistence-jpa `check`, 잠금 대기 lane(`postgresqlMigrationLockWaitIntegrationTest`), 마이그레이션 lane | | 테스트 코드(ArchUnit fixture 포함) | 그 leaf `testQualityCheck` | -| compose·Dockerfile | compose 검사 스크립트, 실제 `docker build`와 기동 | +| compose·Dockerfile | `verifyComposeProfiles`(compose 렌더링), 실제 `docker build`와 기동(`scripts/verify.sh nightly`의 smoke) | - ArchUnit 위반·허용 fixture도 `testQualityCheck`(SpotBugs)가 분석한다. 외부 라이브러리의 Lombok 클래스를 상속한 fixture는 SpotBugs가 `lombok.Generated`를 찾지 못해 실패한다(missing analysis class). 그런 상속 fixture는 두지 않는다. @@ -68,83 +83,53 @@ - 커밋하는 수정이 그 source set에 없던 의존성을 쓰면 lockfile도 같은 커밋에 넣는다. desktop worktree에서 `./gradlew :resolveAndLockAll --write-locks`로 다시 만들어 가져오고 `verifyDependencyLocks`로 본다. 손으로 고친 lockfile은 Gradle이 실제로 고른 버전과 다를 수 있다. - 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 `build.gradle` 한 줄을 더하고 `--write-locks`로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다. -**링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 그 범위 밖의 지침 문서(루트 `AGENTS.md`·`CLAUDE.md`, 지역 규칙 `src/**/AGENTS.md`, `.claude/` 아래 문서)의 상대 링크는 PR마다 `scripts/check-docs.py`의 `link`가 본다. `src/**/CLAUDE.md`는 `@AGENTS.md` 한 줄이라 링크가 없다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다): - -```bash -python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(glob)src/**/README.md' ':(glob)src/**/AGENTS.md' ':(glob)docs/**/*.md' ':(glob).github/**/*.md') -``` - -`--links docs`만 돌리면 `src/**/README.md`·`src/**/AGENTS.md`·`.github/**/*.md`를 빠뜨린다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다). +**링크 검사**: 상대 링크는 PR마다 `scripts/check-docs.py`의 `link`가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL까지 보는 lychee는 문서 검사라 main 단계다(`main.yml` `links`, 범위 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`). 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다). ## 3. 라운드 끝 — 합친 트리의 전체 묶음 -여러 묶음을 합친 트리는 workflow가 PR과 main push에서 돌리는 것을 모두 돌린다. 정본은 `.github/workflows/`다. (가)는 늘 도는 것, (나)는 바뀐 파일로 켜지는 것, (다)는 로컬에 도구가 없는 것이다. 한 번에 하나씩, 공유 잠금 아래에서 돌린다. +여러 묶음을 합친 트리는 workflow가 PR·main·nightly·태그에서 돌리는 단계를 모두 돌린다. 경로 필터로 켜지는 job은 없다(2026-11-08부터, 단계 workflow의 경로 필터는 `verifyStrictLaneStages`가 거절한다). (가)는 `scripts/verify.sh` 단계, (나)는 workflow에만 있는 job이다. 한 번에 하나씩, 공유 잠금 아래에서 돈다(`verify.sh`가 잠근다). -**단계별 묶음.** brief가 단계 이름으로 게이트를 시키면 아래 줄을 돈다. +**단계별 묶음.** brief가 단계 이름으로 게이트를 시키면 같은 이름의 `verify.sh` 단계를 돈다. | brief의 말 | 돌릴 것 | | --- | --- | -| pull request 단계 게이트 | (가)의 `# PR` 줄과 `verify-compose-profile-contracts.sh`·`check-repo-layout.py`·`check-docs.py`(자기 시험 포함), (나)에서 `pull_request`로 켜지는 것, (다) | -| main 단계 | (가)의 `# main push` 줄과 `run-compose-runtime-smoke.sh`·`check-docs.py`(자기 시험 포함), (나)에서 main `push`로 켜지는 것 | -| 라운드 끝 | 위 둘 전부와 (가)의 `# 태그` 두 줄 | +| pull request 단계 게이트 | `scripts/verify.sh pr --no-cache` + `scripts/verify.sh docs` | +| main 단계 | `scripts/verify.sh main --no-cache` | +| nightly, compose smoke, 성능 | `scripts/verify.sh nightly --no-cache` | +| 라운드 끝 | `scripts/verify.sh round --no-cache` + `scripts/verify.sh docs`, 그리고 (나)에서 바뀐 영역에 걸리는 job | -- 태그 두 줄(`releaseCheck`)은 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. `release.yml`의 다른 job(web·websocket·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다([operate.md](../operate.md) 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다. +- `release` 단계(`releaseCheck`)는 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. `release.yml`의 다른 job(web·websocket·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다([operate.md](../operate.md) 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다. +- `verify.sh`는 단계 하나를 로그 하나(`~/<로그 이름>-logs/<단계>.log`)로 남긴다. 4절 표에는 그 안의 Gradle 명령마다 한 줄을 쓴다. -**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. workflow 명령에 그 옵션이 없어도(예: `tasks --group verification`) 증거 실행에는 붙인다. 바뀌는 것은 캐시 사용뿐이라 판정은 같다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다. +**실제로 돌았음을 보이기.** `--on desktop`(기본)은 새 detached worktree에서 시작한다. `--no-cache`가 모든 Gradle 명령에 `--no-build-cache`를 붙인다. 바뀌는 것은 캐시 사용뿐이라 판정은 같다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다. - `mainCheck` 안의 `verifyFeatureScaffold`는 생성한 복사본에서 Gradle을 따로 띄워(`scripts/verify-feature-scaffold.sh`) 바깥의 `--no-build-cache`를 받지 않는다. 바깥 빌드는 FROM-CACHE를 만들 수 없으니 그 로그에 나온 FROM-CACHE는 중첩 빌드의 것이다. 「실제 실행」 칸에 "바깥 FROM-CACHE 0, 중첩 빌드 FROM-CACHE N(태스크 이름)"으로 적는다. - -(가) 늘 도는 것: - -```bash -cd src -# PR: ci-quality-gates.yml -./gradlew :ci :verifyDependencyLocks --warning-mode=fail --no-build-cache --console=plain -./gradlew :verifyStrictLaneStages --dry-run --console=plain -# main push: integration-main.yml -./gradlew :mainCheck --continue --warning-mode=fail --no-build-cache --console=plain -./gradlew :integrationCheck --continue --no-build-cache --console=plain -./gradlew :performanceCheck --continue --no-build-cache --console=plain -./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true --no-build-cache --console=plain # 실험 job, 실패해도 workflow는 통과 -# 태그: release.yml (CI는 GITHUB_SHA로 커밋을 받는다. 손으로 돌릴 때는 -PgitRevision) -./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain -cd .. -bash scripts/verify-compose-profile-contracts.sh -python3 scripts/check-repo-layout.py -python3 -m unittest discover -s scripts/tests # docs-check.yml(PR·main push): 문서 검사의 자기 시험 -python3 scripts/check-docs.py -bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json -``` - -- 여러 명령으로 된 main job 둘은 그 job의 `run` 줄을 차례로 그대로 돌린다: `integration-main.yml`의 `configuration-cache`(로그에 "Reusing configuration cache."가 있어야 한다), `notification-platform.yml`의 `pr`(main push마다 경로와 상관없이 돈다). +- `verify.sh`를 쓸 수 없는 환경이면 단계 함수의 명령을 `src/`에서 그대로 차례로 돈다. 단계 함수가 명령의 정본이다. - 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다. - 합친 뒤에만 드러나는 결함이 있다. 묶음별 검증으로 이 단계를 대신하지 않는다. -(나) 바뀐 파일로 켜지는 것 — brief의 "바뀐 영역의 lane"은 이것이다: +(나) workflow에만 있는 job — brief의 "바뀐 영역의 lane"은 이것이다: 1. 바뀐 파일 목록을 만든다: `git diff --name-only <기준 커밋> <합친 커밋>`. -2. 그 목록을 두 종류의 패턴과 맞춘다. - - `on.pull_request.paths`가 있는 workflow(`grep -l 'paths:' .github/workflows/*.yml`). 패턴은 glob이다(`**`는 폴더 여러 단계). - - `pr-adapters.yml`의 `changes` job에 있는 `emit` 줄. lane(web·websocket·httpclient·jpa)마다 정규식이고, `grep -E`로 맞춘다. -3. 걸린 workflow·job의 `run` 줄을 그대로 돌린다. matrix가 있으면 값마다 한 번이다(예: jpa는 PostgreSQL 버전마다, httpclient는 transport마다). compose가 필요한 job은 그 job의 `docker compose … up`·`down` 단계도 같이 한다. -4. 걸리지 않은 workflow는 이름과 "경로 안 걸림"을, nightly·수동 전용 job은 "PR·main 단계 아님"을 결과 표에 적는다. -5. 경로로 처음 켜진 lane이 이번 변경과 무관한 이전부터의 실패를 드러내면(예: 진입 문서만 바꿨는데 그 영역 lane이 켜짐), 기준 커밋에서 같은 실패인지 보고 「이전부터」로 적는다. 그 lane 영역의 남은 문제로 넘기고 이번 변경 몫으로 세지 않는다. +2. 바뀐 영역의 job을 고른다: PostgreSQL major(`jpa-postgresql`, persistence-jpa), HTTP transport(`httpclient-transport`, httpclient), Redis topology(`redis-topology`, redis leaf 셋), NFS(`fileserver-nfs-ambiguity`, fileserver), 알림 chaos(`notification-chaos`), 릴리스 lane(`release.yml`의 같은 영역 job). +3. 그 job의 `run` 줄을 `src/`에서 그대로 돌린다. 행렬은 값마다 한 번이다. 스크립트 job(`scripts/ci/redis-topology.sh `)은 desktop에서도 같은 줄로 돈다. +4. 고르지 않은 job은 이름과 "바뀐 영역 아님"을 결과 표에 적는다. +5. 처음 켠 job이 이번 변경과 무관한 이전부터의 실패를 드러내면(예: 진입 문서만 바꿨는데 그 영역 job을 돌림), 기준 커밋에서 같은 실패인지 보고 「이전부터」로 적는다. 그 영역의 남은 문제로 넘기고 이번 변경 몫으로 세지 않는다. (다) 로컬에 도구가 없는 것: | job | 로컬에서 | 대체가 못 보는 것 | | --- | --- | --- | -| `link-check.yml`(lychee) | 2절 끝의 같은 범위 상대 링크 검사. desktop에 lychee 공식 이미지가 이미 있으면 그 이미지로 같은 범위를 돌린다 | 외부 URL | -| `dependency-vulnerability.yml` `dependency-review`·`dependency-submission` | GitHub에서만 돈다. diff에 lockfile·`src/gradle/libs.versions.toml` 변경이 없으면 "해당 없음", 있으면 PR 결과를 보고 남은 문제로 적는다 | 전부 | -| `dependency-vulnerability.yml` `trivy-fs` | 이미 설치된 trivy나 desktop에 이미 있는 trivy 공식 이미지가 있으면 job의 검사 줄 그대로. workflow가 쓰는 버전이 없으면 있는 버전으로 기준 트리와 이번 트리를 같은 DB로 돌려 새로 생긴 걸림만 이번 변경 몫으로 본다. job이 trivy를 내려받아 설치하는 줄은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) | +| `main.yml` `links`(lychee) | `scripts/verify.sh docs`의 상대 링크 검사. desktop에 lychee 공식 이미지가 이미 있으면 그 이미지로 같은 범위를 돌린다 | 외부 URL | +| `vulnerabilities`(trivy) | 이미 설치된 trivy나 desktop에 이미 있는 trivy 공식 이미지가 있으면 `scripts/ci/trivy-scan.sh`의 검사 줄 그대로. 그 버전이 없으면 있는 버전으로 기준 트리와 이번 트리를 같은 DB로 돌려 새로 생긴 걸림만 이번 변경 몫으로 본다. 스크립트가 trivy를 내려받아 설치하는 부분은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) | ## 4. 결과 기록 | 단계 | 게이트(명령) | 결과 | 시간 | 실행 직전 1분 부하 | 실제 실행 | 로그 | | --- | --- | --- | --- | --- | --- | --- | -| PR | `:ci :verifyDependencyLocks --warning-mode=fail --no-build-cache` | rc=0 | 6분 32초 | 0.39 | 태스크 756 executed, FROM-CACHE 0, 테스트 7298 실패 0 | desktop `~/<작업 이름>-logs/ci.log` | +| PR | `:prCheck --no-build-cache` | rc=0 | 6분 32초 | 0.39 | 태스크 756 executed, FROM-CACHE 0, 테스트 7298 실패 0 | desktop `~/<작업 이름>-logs/pr.log` | -- 한 줄은 명령 하나다. 여러 명령으로 된 job(`configuration-cache`, notification `pr`)은 명령마다 한 줄을 쓰고 「게이트」 칸에 ` 1/7`처럼 순번을 붙인다. Gradle의 태스크 집계 줄은 명령마다 하나씩 나오므로 로그도 명령마다 나눈다. +- 한 줄은 명령 하나다. `verify.sh` 단계 하나는 Gradle 명령 여럿이다. 명령마다 한 줄을 쓰고 「게이트」 칸에 `main 2/4`처럼 순번을 붙인다. Gradle의 태스크 집계 줄(`BUILD SUCCESSFUL in …`, `N actionable tasks`)은 명령마다 하나씩 나오므로 단계 로그에서 명령별로 나눠 읽는다. - 「실제 실행」 칸은 로그의 `> Task` 줄에서 센다: executed(꼬리 없음), UP-TO-DATE, FROM-CACHE. 테스트 수는 그 명령이 새로 쓴 JUnit XML에서 센다. **테스트 수 세기.** 성공한 Gradle 로그(`--console=plain`)에는 테스트 수가 찍히지 않는다. 같은 worktree의 다음 실행(특히 `--tests` 필터 실행)은 같은 leaf의 XML을 덮어쓴다. 그래서 명령이 끝날 때마다 XML을 로그 폴더로 복사하고 사본에서 센다. @@ -198,8 +183,8 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | | 거짓 통과 모양 | 지금의 장치 | | --- | --- | -| 어떤 workflow도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR) | -| 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `src/build-logic/AGENTS.md` 「`verifyStrictLaneStages`가 세는 명령」 | +| 어떤 단계도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR)의 그래프 검사 | +| 단계 job이 단계를 조용히 돌리지 않음(바뀐 명령 줄, `if:`, `continue-on-error`, 경로 필터) | `verifyStrictLaneStages --dry-run`의 형식 검사(`src/build-logic/AGENTS.md` 「단계 job의 모양」) | | lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 | | 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) | | 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 | @@ -209,18 +194,18 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | | smoke rc=0인데 앱이 OOM으로 재시작함 | `scripts/run-compose-runtime-smoke.sh`가 lane 컨테이너 재시작·OOMKilled를 실패로 보고 `restarts.txt`·`app-memory-peak-bytes.txt`를 남긴다. 그 밖의 compose 실행은 `docker inspect -f '{{.RestartCount}} {{.State.OOMKilled}}' <컨테이너>`로 본다 | | 셸 함수·`if` 조건 안에서 `set -e`가 꺼져 중간 실패가 지나감 | 실패를 받아야 하는 명령은 `if`·`&&`·`||` 조건 밖에 두거나 rc를 직접 본다(`<명령>; rc=$?; [ "$rc" -eq 0 ] \|\| exit "$rc"`) | -게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다. +게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. workflow를 바꿨으면 바꾸기 전후로 이벤트마다 계획되는 태스크 집합(`--dry-run`)을 비교한다. ## 7. workflow·검사 스크립트를 더할 때 리뷰는 빠진 검사만 찾기 쉽다. 장치를 더하기 전에 아래를 보고, 더하는 PR 본문에 답을 적는다. workflow 파일을 고치는 일은 CI 담당 작업이 한다. -1. 어느 단계인가(PR·main·nightly·release), 그리고 그 단계의 기존 workflow에 job으로 넣을 수 없는 이유를 한 줄로 쓴다. 모듈 이름의 workflow 파일은 만들지 않는다. +1. 어느 단계인가(PR·main·nightly·release). workflow 파일은 셋(`pr.yml`·`main.yml`·`release.yml`)뿐이다. 먼저 단계 태스크(`prCheck` 등)의 의존으로 넣을 수 있는지 보고, 안 되면 그 단계 파일의 job으로 넣는다. 새 workflow 파일과 모듈 이름의 workflow는 만들지 않는다. 2. 새 job이 다른 단계가 이미 돌리는 태스크를 다시 돌리지 않는지 `--dry-run` 태스크 목록으로 보인다. 3. lane 고르기·순서·집계는 Gradle에 둔다. 단계 job의 `run:`은 한 줄이다. 4. 경로 필터를 새로 쓰려면 그 lane이 다른 단계에서 무조건 돈다는 것을 보인다. 5. 문서·이름·개수·CI 배선을 검사하는 것은 main 단계다(2026-09-16 소유자 결정). PR에 두어야 하면 이유를 적는다. 6. 이벤트별 job 수 변화와 잰 실행 시간을 적는다. runner 용량은 [operate.md](../operate.md) 4.1절의 값으로 판단한다. 7. 실행 환경(Gitea)에서 돌지 않는 action·권한(`id-token`, ghcr, GitHub 의존성 그래프, `upload-artifact@v4` 이상)을 쓰지 않는다. 써야 하면 `github.server_url` 조건을 단다. -8. Gradle 밖 검사 스크립트는 `scripts/`에 두고, 머리 주석에 누가 부르는지(workflow·Gradle·사람·훅)를 적는다. 부르는 곳이 없는 검사 스크립트는 만들지 않는다. 같은 일을 하는 빌드 태스크가 있으면 거기에 넣는다. 스크립트의 시험은 `scripts/tests/`에 unittest로 둔다. `docs-check.yml`이 PR마다 `python3 -m unittest discover -s scripts/tests`로 돌린다. +8. Gradle 밖 검사 스크립트는 `scripts/`(workflow만 부르면 `scripts/ci/`)에 두고, 머리 주석에 누가 부르는지(workflow·Gradle·사람·훅)를 적는다. 부르는 곳이 없는 검사 스크립트는 만들지 않는다. 같은 일을 하는 빌드 태스크가 있으면 거기에 넣는다. 스크립트의 시험은 `scripts/tests/`에 unittest로 둔다. `prCheck`의 `testDocumentChecks`가 PR마다 `python3 -m unittest discover -s scripts/tests`로 돌린다. 9. 같은 장치에서 결함이 두 라운드 연속 나오면 고치기 전에 그 장치가 필요한지 다시 본다([improve.md](../improve.md) 7절). diff --git a/scripts/check-docs.py b/scripts/check-docs.py index 36c123e9..30df3579 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -10,7 +10,7 @@ head 기록(docs/design, docs/history, docs/adr)의 .md는 맨 위에 머리 블록이 있다. 상태는 종류별 고정 어휘, 작성일은 날짜, 요약은 한국어, 현재 정본과 대체됨이 가리키는 경로는 지금 있다. - reference 살아 있는 문서의 인라인 코드 안 repo 경로(src/, docs/, scripts/, compose/, .github/로 + reference 살아 있는 문서의 인라인 코드 안 repo 경로(src/, docs/, scripts/, compose/, .github/, .gitea/로 시작. 2026-11-07에 지운 infra/ 아래 경로도 본다)와 Gradle 경로(:a:b)가 지금 트리와 registry에 있다. 「있다」는 git이 아는 파일(추적 + 무시되지 않은 새 파일)과 그 위 폴더다. 디스크에만 있는 것(git mv가 남긴 빈 폴더 등)은 새 checkout에 없으므로 세지 않는다. 기록의 「현재 정본」·「대체됨」 @@ -125,7 +125,7 @@ TOKEN = re.compile(r"[^\s가-힣]+") WORD = re.compile(r"^[(\[\"'“‘*_]*[A-Za-z][a-z]*(?:['’][a-z]+)?(?:-[a-z]+)*[)\]\"'”’*_.,;:!?…]*$") # --- 참조 -PATH_ROOTS = ("src/", "docs/", "scripts/", "compose/", "infra/", ".github/") +PATH_ROOTS = ("src/", "docs/", "scripts/", "compose/", "infra/", ".github/", ".gitea/") PLACEHOLDER = re.compile(r"[*?<>{}\[\]$…]|\.\.\.|YYYY|NNN|[가-힣]") LINE_SUFFIX = re.compile(r"(?::\d+(?:[-,]\d+)*)+$") # 모든 leaf에 있는 소스 세트 이름(src/test, src/main/java)은 어느 leaf의 것인지 문장이 정한다. @@ -148,7 +148,7 @@ VERSION = re.compile(r"(? to : for each port given, until killed. + +Called by scripts/ci/redis-topology.sh when it runs inside a CI job container. The runner's job +container does not share the network of the Docker daemon that starts the Compose lanes, so the +daemon's published ports are on the daemon host, not on the job's localhost — while the Redis lanes +are built around localhost: the cluster announces 127.0.0.1 in its redirects and the TLS lane's +certificate names localhost. Forwarding keeps those lanes exactly as they run on a workstation. + + python3 scripts/ci/forward-ports.py ... +""" + +import asyncio +import sys + + +async def pipe(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None: + try: + while data := await reader.read(65536): + writer.write(data) + await writer.drain() + except (ConnectionError, asyncio.CancelledError): + pass + finally: + writer.close() + + +async def serve(host: str, port: int) -> asyncio.base_events.Server: + async def handle(client_reader, client_writer): + try: + upstream_reader, upstream_writer = await asyncio.open_connection(host, port) + except OSError: + client_writer.close() + return + await asyncio.gather(pipe(client_reader, upstream_writer), pipe(upstream_reader, client_writer)) + + return await asyncio.start_server(handle, "127.0.0.1", port) + + +async def main(host: str, ports: list[int]) -> None: + servers = [await serve(host, port) for port in ports] + print(f"forward-ports: 127.0.0.1 -> {host} for {ports}", flush=True) + await asyncio.gather(*(server.serve_forever() for server in servers)) + + +if __name__ == "__main__": + if len(sys.argv) < 3: + sys.exit(__doc__) + asyncio.run(main(sys.argv[1], [int(port) for port in sys.argv[2:]])) diff --git a/scripts/ci/redis-topology.sh b/scripts/ci/redis-topology.sh new file mode 100755 index 00000000..0a929343 --- /dev/null +++ b/scripts/ci/redis-topology.sh @@ -0,0 +1,65 @@ +#!/usr/bin/env bash +# One Redis topology lane against a real server: start the Compose topology, run the leaves' +# `redisTopologyTest` for it, print the evidence manifest, stop the topology. Called by the +# `redis-topology` nightly job of .gitea/workflows/main.yml (one call per matrix row); a person can +# run the same line on a machine with Docker. +# +# bash scripts/ci/redis-topology.sh +# +# The lanes are explicitOnly: they need the endpoint this script passes, so no stage runs them +# (docs/redis/support-matrix.md records which lane produced which evidence). Each Gradle task fails +# closed on its own account: an unknown mode, a missing endpoint, a lane with no tagged test class +# and a run that executed zero tests are all errors. +set -euo pipefail + +topology=${1:?topology} +version=${2:?redis version} +cd "$(dirname "${BASH_SOURCE[0]}")/../.." +compose=(docker compose -f "src/adapter/outbound/redis-sdk/compose/${topology}/compose.yml") +forwarder='' +stop() { + [ -z "${forwarder}" ] || kill "${forwarder}" 2>/dev/null || true + "${compose[@]}" down -v +} +trap stop EXIT + +runtime=:adapter:outbound:redis-runtime:redisTopologyTest +sdk=:adapter:outbound:redis-sdk:redisTopologyTest +semantic=:adapter:outbound:cache-redis:redisTopologyTest +extra=() +case "${topology}" in + standalone) port=6379; ports=(6379); tasks=("${runtime}" "${sdk}" "${semantic}") ;; + sentinel) port=27010; ports=(7010 7011 27010 27011 27012); tasks=("${runtime}" "${sdk}"); extra=(-Predis.topology.master=skeleton) ;; + cluster) port=7100; ports=(7100 7101 7102 7103 7104 7105); tasks=("${runtime}" "${sdk}" "${semantic}") ;; + tls) port=6390; ports=(6390); tasks=("${runtime}") ;; + *) echo "redis-topology: unknown topology ${topology}" >&2; exit 2 ;; +esac + +REDIS_VERSION=${version} "${compose[@]}" up -d --wait + +# Inside a CI job container the Docker daemon's ports are on the daemon host, not on localhost, and +# the lanes are built around localhost (cluster redirects announce 127.0.0.1, the TLS certificate +# names localhost). Forward them, so the lane runs exactly as it does on a workstation. +if [ -f /.dockerenv ]; then + daemon_host=$(awk '$2 == "00000000" { printf "%d.%d.%d.%d\n", "0x" substr($3,7,2), "0x" substr($3,5,2), "0x" substr($3,3,2), "0x" substr($3,1,2); exit }' /proc/net/route) + python3 scripts/ci/forward-ports.py "${daemon_host}" "${ports[@]}" & + forwarder=$! + sleep 1 +fi + +# The tag says 7.4; the digest says which 7.4. Evidence that names only the tag cannot be reproduced +# once the tag moves, so a run that cannot name its digest has nothing to certify. +digest=$(docker image inspect --format '{{index .RepoDigests 0}}' "redis:${version}") +[ -n "${digest}" ] || { echo "redis-topology: no repository digest for redis:${version}" >&2; exit 1; } +if [ "${topology}" = tls ]; then + trust=$(mktemp "${RUNNER_TEMP:-/tmp}/redis-lane-ca.XXXXXX") + "${compose[@]}" cp redis:/tls/ca.crt "${trust}" + extra=(-Predis.topology.trust-material="${trust}") +fi + +(cd src && ./gradlew "${tasks[@]}" --continue \ + -Predis.topology.host=localhost -Predis.topology.port="${port}" -Predis.topology.mode="${topology}" \ + "${extra[@]}") + +printf 'evidence: commit=%s run=%s topology=%s redis_version=%s image_digest=%s\n' \ + "$(git rev-parse HEAD)" "${GITHUB_RUN_ID:-local}" "${topology}" "${version}" "${digest}" diff --git a/scripts/ci/trivy-scan.sh b/scripts/ci/trivy-scan.sh new file mode 100755 index 00000000..07d4ae31 --- /dev/null +++ b/scripts/ci/trivy-scan.sh @@ -0,0 +1,108 @@ +#!/usr/bin/env bash +# Vulnerability gate, shared by the stage workflows. Called by .gitea/workflows/pr.yml and main.yml +# (`filesystem`) and release.yml (`image `); not by Gradle and not on the desktop, because +# it downloads and installs its tools (docs/work/operate.md 4.1). +# +# bash scripts/ci/trivy-scan.sh filesystem dependency tree: block High/Critical, report +# Medium/Low, fail on any CISA KEV match +# bash scripts/ci/trivy-scan.sh image release image: write image-sbom.cdx.json, +# block High/Critical, report Medium/Low +# +# Tools are pinned release binaries with an asserted SHA-256, installed under RUNNER_TEMP (or a +# temporary directory): a checksum is a supply-chain claim that can be checked offline, an action +# pinned to a commit is not. .trivyignore.yaml is the one suppression source; each entry carries a +# reason and an expiry by policy (.github/dependency-vulnerability-policy.md). +# Optional mirrors: TRIVY_DOWNLOAD_BASE_URL, JQ_DOWNLOAD_BASE_URL, KEV_FEED_URL. +set -euo pipefail + +readonly TRIVY_VERSION='0.71.2' +readonly TRIVY_SHA256_AMD64='0510e71e2fd39bf863856d499c8dc19feb4e7336546394c502a8f5cc7ab27460' +readonly TRIVY_SHA256_ARM64='fe1c7106e15a5365d485b098a8c338f91e3b7ba71cb0e4963b98a3a098763cfc' +readonly JQ_VERSION='1.8.1' +readonly JQ_SHA256_AMD64='020468de7539ce70ef1bceaf7cde2e8c4f2ca6c3afb84642aabc5c97d9fc2a0d' +readonly JQ_SHA256_ARM64='6bc62f25981328edd3cfcfe6fe51b073f2d7e7710d7ef7fcdac28d4e384fc3d4' +readonly DEFAULT_KEV_FEED_URL='https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json' + +cd "$(dirname "${BASH_SOURCE[0]}")/../.." +tools="$(mktemp -d "${RUNNER_TEMP:-/tmp}/trivy-scan.XXXXXX")" +trap 'rm -rf "${tools}"' EXIT + +download() { # url, sha256, destination + curl --fail --show-error --silent --location --retry 3 --proto '=https' --tlsv1.2 "$1" --output "$3" + printf '%s %s\n' "$2" "$3" | sha256sum -c - +} + +case "$(uname -m)" in + x86_64 | amd64) trivy_arch='64bit'; trivy_sha="${TRIVY_SHA256_AMD64}"; jq_asset='jq-linux-amd64'; jq_sha="${JQ_SHA256_AMD64}" ;; + aarch64 | arm64) trivy_arch='ARM64'; trivy_sha="${TRIVY_SHA256_ARM64}"; jq_asset='jq-linux-arm64'; jq_sha="${JQ_SHA256_ARM64}" ;; + *) echo "trivy-scan: unsupported architecture $(uname -m)" >&2; exit 1 ;; +esac + +download "${TRIVY_DOWNLOAD_BASE_URL:-https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}}/trivy_${TRIVY_VERSION}_Linux-${trivy_arch}.tar.gz" \ + "${trivy_sha}" "${tools}/trivy.tar.gz" +tar -xzf "${tools}/trivy.tar.gz" -C "${tools}" trivy +download "${JQ_DOWNLOAD_BASE_URL:-https://github.com/jqlang/jq/releases/download/jq-${JQ_VERSION}}/${jq_asset}" \ + "${jq_sha}" "${tools}/jq" +chmod 0755 "${tools}/trivy" "${tools}/jq" +export PATH="${tools}:${PATH}" +[ "$(jq --version)" = "jq-${JQ_VERSION}" ] || { echo "trivy-scan: unexpected $(jq --version)" >&2; exit 1; } + +scan_filesystem() { + trivy fs --scanners vuln,license --severity CRITICAL,HIGH --exit-code 1 --ignorefile .trivyignore.yaml . + trivy fs --scanners vuln,license --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 "${tools}/trivy-kev.json" . + + # A KEV-listed vulnerability fails regardless of its CVSS score. The feed and the scan are both + # checked for shape first: an empty or malformed input would otherwise intersect to nothing and + # print "no catalog match" for a check that never ran. + if ! curl --fail --show-error --silent --location --retry 3 --proto '=https' --tlsv1.2 \ + "${KEV_FEED_URL:-${DEFAULT_KEV_FEED_URL}}" --output "${tools}/kev.json"; then + echo "trivy-scan: KEV feed unavailable; set KEV_FEED_URL to an approved mirror" >&2 + exit 1 + fi + jq -e ' + (.catalogVersion | type == "string" and test("\\S")) + and (.dateReleased | type == "string" and test("\\S")) + and (.count | type == "number") + and (.count > 0) + and (.count == (.count | floor)) + and (.vulnerabilities | type == "array") + and ((.vulnerabilities | length) > 0) + and (.count == (.vulnerabilities | length)) + and (all(.vulnerabilities[]; (.cveID | type == "string" and test("^CVE-[0-9]{4}-[0-9]{4,}$")))) + and (([.vulnerabilities[].cveID] | unique | length) == .count) + ' "${tools}/kev.json" > /dev/null || { echo "trivy-scan: the KEV feed is malformed" >&2; exit 1; } + jq -e ' + (type == "object") + and (.Results | type == "array") + and ((.Results | length) > 0) + and (all(.Results[]; type == "object")) + and (all(.Results[]; (.Vulnerabilities == null) or (.Vulnerabilities | type == "array"))) + and (all(.Results[]; all(.Vulnerabilities[]?; + (type == "object") and (.VulnerabilityID | type == "string" and test("\\S"))))) + ' "${tools}/trivy-kev.json" > /dev/null || { echo "trivy-scan: the Trivy KEV input is malformed" >&2; exit 1; } + jq -r '[.Results[]?.Vulnerabilities[]?.VulnerabilityID] | unique[]' "${tools}/trivy-kev.json" | sort -u > "${tools}/found.txt" + jq -r '.vulnerabilities[].cveID' "${tools}/kev.json" | sort -u > "${tools}/kev.txt" + hits="$(comm -12 "${tools}/found.txt" "${tools}/kev.txt")" + if [ -n "${hits}" ]; then + printf 'trivy-scan: CISA KEV-listed vulnerability found regardless of CVSS:\n%s\n' "${hits}" >&2 + exit 1 + fi + echo "trivy-scan: no KEV catalog match." +} + +# The image scan sees the base image's OS packages, which the filesystem scan cannot. The SBOM is +# written before the blocking scan, so the inventory survives the run that refuses to publish. +scan_image() { + trivy image --format cyclonedx --scanners license --output image-sbom.cdx.json "$1" + test -s image-sbom.cdx.json + trivy image --scanners vuln,license --severity CRITICAL,HIGH --exit-code 1 --ignorefile .trivyignore.yaml "$1" + trivy image --scanners vuln,license --severity MEDIUM,LOW --exit-code 0 --ignorefile .trivyignore.yaml "$1" +} + +case "${1:-}" in + filesystem) scan_filesystem ;; + image) scan_image "${2:?image reference}" ;; + *) sed -n '2,13p' "$0" >&2; exit 2 ;; +esac diff --git a/scripts/ci/verify-configuration-cache.sh b/scripts/ci/verify-configuration-cache.sh new file mode 100755 index 00000000..7395e8eb --- /dev/null +++ b/scripts/ci/verify-configuration-cache.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +# Two questions about Gradle's configuration cache. Called by the `configuration-cache` job of +# .gitea/workflows/main.yml and by scripts/verify.sh main. +# 1. Can every repository-wide gate be stored? A property of the task graph, so --dry-run answers it +# for all of them in seconds without running a lane. +# 2. Is a stored entry reused while the build still executes its work? Checked on the two core +# leaves, whose check runs in a minute. +# prCheck and verifyStrictLaneStages are not in the list: the strict-lane check reads the task graph +# itself and is declared incompatible, and prCheck is ci plus scripts. +set -euo pipefail +cd "$(dirname "${BASH_SOURCE[0]}")/../../src" + +reused() { # gradle arguments...; fails unless the second identical run reuses the stored entry + ./gradlew "$@" --configuration-cache --configuration-cache-problems=fail + output=$(./gradlew "$@" --configuration-cache --configuration-cache-problems=fail 2>&1) + printf '%s\n' "${output}" + grep -Fq 'Reusing configuration cache.' <<<"${output}" || { + echo "configuration cache: not reused for: $*" >&2 + exit 1 + } +} + +for gate in ci mainCheck integrationCheck releaseCheck; do + reused "${gate}" --dry-run +done +reused :domain-core:check :application-core:check diff --git a/scripts/verify.sh b/scripts/verify.sh new file mode 100755 index 00000000..c96b2e1d --- /dev/null +++ b/scripts/verify.sh @@ -0,0 +1,190 @@ +#!/usr/bin/env bash +# 검증 진입점. 사람·세션·문서가 같은 명령을 쓰고, 단계 이름은 workflow(.gitea/workflows)와 같다. +# +# scripts/verify.sh <단계> [대상] [--on here|<호스트>] [--log <이름>] [--no-cache] +# +# 단계 무엇 workflow +# docs 문서·지침 검사와 스크립트 시험(Gradle 없음) pr.yml의 prCheck 안 +# leaf <경로> registry gradle_path 하나의 check (작업 중) +# pr :prCheck, :verifyStrictLaneStages --dry-run pr.yml `gradle` +# main :mainCheck, :integrationCheck, build-logic 시험, 설정 캐시 main.yml(push) +# nightly compose smoke 전부, :performanceCheck(마지막) main.yml(nightly) +# release :releaseCheck(이 커밋을 provenance로) release.yml `release` +# app 앱을 띄워 health와 기본 endpoint를 직접 본다 (없음) +# round pr → main → nightly → release, 첫 실패에서 멈춘다 라운드 끝 묶음 +# docs 밖의 단계는 Gradle·Docker를 쓴다. 이 repo에서는 desktop에서만 돈다(docs/work/operate.md 4.1절). +# trivy·lychee·nightly 행렬(Redis topology, PostgreSQL major, NFS)은 도구를 내려받거나 runner 환경이 필요해 +# workflow에서만 돈다. +# +# --on <호스트>: 지금 작업 트리(커밋 안 된 변경 포함)를 패치로 그 호스트에 옮긴다. 기준 커밋에서 새 worktree를 +# 만들어 패치를 적용하고, 트리 해시가 여기와 같은지 본 뒤 잠금 아래에서 같은 단계를 돌리고 worktree를 지운다. +# push하지 않는다. 기준 커밋은 원격 checkout이 fetch로 받을 수 있어야 한다(기본: origin/main과 갈라진 곳). +# docs 밖의 단계는 기본이 desktop이다. desktop에서 직접 돌릴 때는 --on here. +# --no-cache: Gradle 명령마다 --no-build-cache를 붙인다(증거로 쓸 실행, docs/work/reference/gates.md 3절). +# 환경 변수: VERIFY_HOST(무거운 단계의 --on 기본값, 없으면 desktop), VERIFY_REMOTE_REPO(원격 checkout, 기본 +# ~/workspace/), VERIFY_BASE_REF(기본 origin/main), VERIFY_LOCK(기본 /tmp/claude-gates/heavy.lock), +# VERIFY_SSH(기본 ssh). +# 종료 코드: 단계의 종료 코드. 2 = 사용법, 4 = 원격 준비 실패. +set -euo pipefail + +ROOT=$(git rev-parse --show-toplevel) +cd "$ROOT" +TMP_FILES=() +trap '[ ${#TMP_FILES[@]} -eq 0 ] || rm -f "${TMP_FILES[@]}"' EXIT # 빈 배열 + set -u는 옛 bash에서 오류다 +# 빌드마다 쓰고 버리는 daemon. 여러 worktree의 빌드를 한 오래 사는 daemon이 받으면 서로 호환되지 않는 compiler +# worker가 쌓여 desktop 메모리를 채운다(2026-11-08 측정: worker 41개, 14.2GB). GRADLE_OPTS는 단계 안에서 다시 부르는 +# Gradle(생성 명령 왕복, 설정 캐시·Redis 스크립트)에도 같은 규칙을 준다. repo 기본값(src/gradle.properties)은 그대로다. +GRADLE_FLAGS=(--console=plain --no-daemon) +export GRADLE_OPTS="${GRADLE_OPTS:+$GRADLE_OPTS }-Dorg.gradle.daemon=false" +LOCK=${VERIFY_LOCK:-/tmp/claude-gates/heavy.lock} + +usage() { + awk 'NR > 1 && /^#/ { sub(/^# ?/, ""); print; next } NR > 1 { exit }' "$ROOT/scripts/verify.sh" >&2 + exit 2 +} + +gradle() { (cd src && ./gradlew "$@" "${GRADLE_FLAGS[@]}"); } + +# ---------------------------------------------------------------- 단계 본문 + +run_docs() { + python3 scripts/check-work-docs.py + python3 scripts/check-docs.py + python3 -m unittest discover -s scripts/tests + python3 scripts/check-repo-layout.py +} + +# 대상은 registry의 gradle_path여야 한다. 폴더 이름이나 기억으로 짐작한 경로는 여기서 거절한다. +run_leaf() { + local path=${1:?leaf 뒤에 registry gradle_path(예: :adapter:outbound:persistence-jpa)} + python3 - "$path" <<'PY' || { echo "verify: $path는 registry(src/config/architecture/modules.json)의 gradle_path가 아니다" >&2; exit 2; } +import json, sys +paths = {m["gradle_path"] for m in json.load(open("src/config/architecture/modules.json"))["modules"]} +sys.exit(0 if sys.argv[1] in paths else 1) +PY + gradle "$path:check" +} + +run_pr() { + gradle :prCheck + gradle :verifyStrictLaneStages --dry-run +} + +run_main() { + gradle :mainCheck --continue + gradle :integrationCheck --continue + gradle -p build-logic test + bash scripts/ci/verify-configuration-cache.sh +} + +# performanceCheck는 마지막이다: 상한은 다른 빌드가 돌지 않는 머신에서만 뜻이 있다. +run_nightly() { + bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json + gradle :performanceCheck --continue +} + +# CI는 GITHUB_SHA로 커밋을 받는다. 여기서는 HEAD를 준다(--on 원격 실행에서는 패치를 얹은 기준 커밋). +run_release() { GIT_SHA=${GIT_SHA:-$(git rev-parse HEAD)} gradle :releaseCheck; } + +run_app() { bash scripts/bootstrap-local.sh; } + +# 함수를 && 목록 안에서 부르면 그 안의 set -e가 꺼진다. 그래서 차례로 부른다. +run_round() { + run_pr + run_main + run_nightly + run_release +} + +# ---------------------------------------------------------------- 실행 위치 + +run_here() { + local stage=$1 + shift + case "$stage" in + docs) run_docs ;; + leaf | pr | main | nightly | release | app | round) + # 같은 머신의 다른 세션·프론트 repo와 무거운 실행이 겹치지 않게 공유 잠금 아래에서 돈다. + if [ -z "${VERIFY_LOCKED:-}" ] && [ -d "$(dirname "$LOCK")" ]; then + export VERIFY_LOCKED=1 + exec flock "$LOCK" "$ROOT/scripts/verify.sh" "$stage" "$@" --on here "${NO_CACHE[@]}" + fi + "run_$stage" "$@" + ;; + *) usage ;; + esac +} + +run_remote() { + local stage=$1 target=$2 host=$3 log=$4 ssh=${VERIFY_SSH:-ssh} + local name base tree tmp_index patch id remote_repo + name=$(basename "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")") + remote_repo=${VERIFY_REMOTE_REPO:-"~/workspace/$name"} + base=$(git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}") + tmp_index=$(mktemp) + patch=$(mktemp) + TMP_FILES+=("$tmp_index" "$patch") + cp "$(git rev-parse --git-path index)" "$tmp_index" + GIT_INDEX_FILE=$tmp_index git add -A + tree=$(GIT_INDEX_FILE=$tmp_index git write-tree) + git diff --binary "$base" "$tree" > "$patch" + id="verify-$(date +%s)-$$" + echo "verify: $host에서 '$stage $target' (기준 ${base:0:12}, 트리 ${tree:0:12}, 로그 ~/$log-logs/$stage.log)" >&2 + $ssh "$host" "cat > /tmp/$id.patch" < "$patch" + # compose lane이 만든 root 소유 파일이 있어도 지울 수 있게 정리는 worktree remove --force 하나로 한다. + $ssh "$host" bash -s <&2; exit 4; fi +mkdir -p "\$(dirname $LOCK)" ~/$log-logs +echo "verify: \$(uptime)" >&2 +VERIFY_LOCKED=1 flock $LOCK ./scripts/verify.sh $stage $target --on here ${NO_CACHE[*]} 2>&1 | tee ~/$log-logs/$stage.log +rc=\${PIPESTATUS[0]} +# 새 worktree라 여기 있는 JUnit XML은 모두 이번 실행의 것이다. worktree를 지우기 전에 센다. +find . -path '*/build/test-results/*' -name 'TEST-*.xml' -print0 | xargs -0 -r cat \\ + | grep -o ']*' \\ + | awk '{ for (i = 1; i <= NF; i++) if (split(\$i, kv, "=") == 2) { gsub(/"/, "", kv[2]); n[kv[1]] += kv[2] } } + END { printf "verify: 테스트 tests=%d failures=%d errors=%d skipped=%d\\n", n["tests"], n["failures"], n["errors"], n["skipped"] }' \\ + | tee -a ~/$log-logs/$stage.log +echo "verify: rc=\$rc" | tee -a ~/$log-logs/$stage.log +exit \$rc +EOF +} + +main() { + local stage=${1:-} target="" on="" log="" + NO_CACHE=() + [ -n "$stage" ] || usage + shift + if [ "$stage" = leaf ] && [ $# -gt 0 ] && [ "${1#--}" = "$1" ]; then + target=$1 + shift + fi + while [ $# -gt 0 ]; do + case "$1" in + --on) on=${2:?--on 뒤에 호스트}; shift 2 ;; + --log) log=${2:?--log 뒤에 이름}; shift 2 ;; + --no-cache) NO_CACHE=(--no-cache); GRADLE_FLAGS+=(--no-build-cache); shift ;; + *) usage ;; + esac + done + if [ -z "$on" ]; then + if [ "$stage" = docs ]; then on=here; else on=${VERIFY_HOST:-desktop}; fi + fi + if [ "$on" = here ]; then + run_here "$stage" ${target:+"$target"} + else + log=${log:-$(git branch --show-current | tr '/' '-')} + run_remote "$stage" "$target" "$on" "${log:-detached}" + fi +} + +main "$@" diff --git a/src/README.md b/src/README.md index 552f5ec5..86538d91 100644 --- a/src/README.md +++ b/src/README.md @@ -27,9 +27,10 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇 | `configContractCheck` | `:app-bootstrap:verifyEnvKeys`로 환경 설정 계약을 검사 | | `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 | | `integrationCheck` | 선언된 strict integration lane을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 | -| `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(`-Pperformance.assertions.enabled`가 `true`가 아니면 실패, skip된 테스트가 있어도 실패). `integration-main.yml` `performance-check`가 main·nightly에 같은 명령으로 돌림 | -| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-v`·`--help` 등)과, 실패해도 단계가 실패하지 않을 수 있거나(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) 돌지 않을 수 있거나(조건부 `exit 0` 뒤, 요청으로만 시작하는 workflow, `paths` 필터로만 시작하는 workflow, `releaseCheck` 밖의 단계를 태그 push·`release`로만 시작하는 workflow 등) 검사가 읽지 않는(`\|\| exit 1`, `{ }` 안 등) 명령은 실행으로 세지 않는다. 자세한 목록은 `build-logic/README.md`. PR 게이트가 돌림 | -| `ci` | PR 게이트: 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` | +| `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(`-Pperformance.assertions.enabled`가 `true`가 아니면 실패, skip된 테스트가 있어도 실패). `main.yml` `performance` job이 nightly에 다른 무거운 job 뒤에서 같은 명령으로 돌림 | +| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 `strictLaneStages`에 선언한 단계(`prCheck`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 단계마다 선언한 workflow job이 `./gradlew <단계>`를 정해진 한 줄로 조건 없이(또는 선언한 조건으로) 돌리는지 검사. 형식은 `build-logic/AGENTS.md` 「단계 job의 모양」. PR 단계가 돌림 | +| `prCheck` | PR 단계: `ci` + `verifyDependencyLocks` + compose 렌더링(`verifyComposeProfiles`) + 저장소 배치(`verifyRepositoryLayout`) + 문서 검사(`documentCheck`) | +| `ci` | 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` | | `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) | | `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) | @@ -80,7 +81,7 @@ version은 root `.tool-versions`의 Temurin 값으로 맞춘다. archive task 자체는 timestamp 비보존·재현 가능한 file order·고정 mode를 강제한다. 현재 저장소에는 별도의 `verify-reproducible-build.sh`가 없으므로 byte-for-byte 이중-build 비교를 자동 게이트라고 주장하지 않는다. 릴리스 검증의 정본 진입점은 `./gradlew releaseCheck`와 -`.github/workflows/release.yml`이다. +`.gitea/workflows/release.yml`이다. ### `-parameters` 컴파일러 플래그 @@ -190,18 +191,17 @@ drift하기 시작하면 그때 자동화한다. 진짜 항목을 상대로, 진 - **소유 범위.** 이 계약은 *게이트 배선*(어떤 게이트가 CI 에서 돌고 실패 시 어떻게 릴리스를 막는가)을 소유한다. 개별 scanner/tool/severity *정책* 은 owner 브랜치가 소유하며, 그 20행 매핑의 in-repo - SSOT는 Gradle task graph와 GitHub Actions job graph 그 자체다. + SSOT는 Gradle task graph와 workflow job graph 그 자체다. > 이력: 게이트 표 `.github/ci-gate-matrix.yml`(1,025줄, 107개 게이트 행)과 그 검사기 > `.github/scripts/verify-gate-matrix.sh`(568줄)는 삭제했다. 그 표는 이미 두 그래프에 있는 정보의 > 세 번째 사본이었고, 검사기는 세 사본을 서로 같게 유지하는 일을 했다. 결과적으로 체크 하나를 > 추가하려면 Gradle · workflow · 표 · 검사기 기대값 · Java 계약 테스트 다섯 곳을 같이 고쳐야 했다. -- **워크플로.** `.github/workflows/ci-quality-gates.yml` 의 `release-gate` 잡이 모든 release-blocking - 게이트의 fan-in(단일 required status check)이다. included build 테스트는 경로 필터가 걸린 - `build-logic.yml`이, main 단계(`mainCheck`)·configuration-cache·JPA candidate evidence는 - `integration-main.yml`이 돌린다. 위임 게이트(Trivy SCA/이미지 스캔)는 `dependency-vulnerability.yml` 가 소유하며, - GitHub Actions 는 워크플로 간 `needs` 를 못 쓰므로 branch protection 의 required check 합집합으로 - 묶는다. +- **워크플로.** `.gitea/workflows/`의 세 파일이다. `pr.yml`의 `done` job이 PR 단계의 모든 job(`gradle`: + `./gradlew :prCheck`와 `verifyStrictLaneStages --dry-run`, `vulnerabilities`: Trivy)을 모으는 단일 필수 검사다. + `main.yml`이 main 단계(`mainCheck`·`integrationCheck`·build-logic 시험·configuration cache·링크)와 + nightly(행렬 job, compose smoke, 마지막에 `performanceCheck`)를, `release.yml`이 태그 단계를 돌린다. + 무엇을 돌릴지는 Gradle 단계 태스크가 정하고, `verifyStrictLaneStages`가 단계 job의 모양을 지킨다. --- diff --git a/src/adapter/outbound/cache-redis/README.md b/src/adapter/outbound/cache-redis/README.md index 47e879e3..4b13ad5e 100644 --- a/src/adapter/outbound/cache-redis/README.md +++ b/src/adapter/outbound/cache-redis/README.md @@ -329,7 +329,7 @@ rate-limit 어댑터가 있다고 SDK 명령 정책이 강제된다고 짐작하 `redisContainerContractTest`는 cache-region, lease, 멱등성 store 포트 계약(메모리 fake가 통과하는 것. 멱등성 계약의 시간 있는 경우는 여기서 서버 자신의 시계로 돌고, `test`에서는 명령 fake의 시계로 돈다 — 후자는 program 자체가 아니라 fixture가 가진 program 사본을 증명한다)과 살아 있는 semantic 포트 시험을, standalone topology의 ACL 파일 아래에서 스스로 -띄운 Redis에 대고 돌린다. `integrationCheck`(integration-main.yml의 `integration-check` job)에 있고 거기에만 있다: +띄운 Redis에 대고 돌린다. `integrationCheck`(`main.yml`의 `integration` job)에 있고 거기에만 있다: `mainCheck`에도 적었을 때는 main push마다 두 번 돌았다. image는 `config/testing/container-images.properties`의 `redis`다. diff --git a/src/adapter/outbound/cache-redis/build.gradle b/src/adapter/outbound/cache-redis/build.gradle index d0f217cb..c0738d53 100644 --- a/src/adapter/outbound/cache-redis/build.gradle +++ b/src/adapter/outbound/cache-redis/build.gradle @@ -71,9 +71,9 @@ redisTopologyLane { // the same defect (05-02, 05-03). The image is config/testing/container-images.properties' `redis`, // and the ACL file is the one the development stack and the redis-sdk topologies share // (compose/redis/acl), so the accounts and their rights are the standalone -// topology's. Integration category, so integrationCheck runs it — integration-main.yml's -// `integration-check` job, on every push to main and nightly. It is deliberately not in this leaf's -// mainCheck as well: `main-check` and `integration-check` are two jobs of the same workflow run, so a +// topology's. Integration category, so integrationCheck runs it — main.yml's `integration` job, on +// every push to main and nightly. It is deliberately not in this leaf's mainCheck as well: `main` and +// `integration` are two jobs of the same workflow run, so a // lane in both started a second Redis container and ran every live contract twice per push without // covering anything the first run did not (found while fixing review 2026-11-03). Sentinel, cluster // and TLS remain the topology lane's. diff --git a/src/adapter/outbound/httpclient/build.gradle b/src/adapter/outbound/httpclient/build.gradle index 2673999a..a900f790 100644 --- a/src/adapter/outbound/httpclient/build.gradle +++ b/src/adapter/outbound/httpclient/build.gradle @@ -230,8 +230,8 @@ strictTestLanes { // the deadline and evidence contracts against real TCP faults — a slow drip, a cut stream, a refused // connect — and review 2026-11-01 05-06/05-16 put it in the main stage because it was reachable only // through integrationCheck, which then ran on no main-branch build. That premise no longer holds: -// integration-main.yml's `integration-check` job runs integrationCheck (an integration lane, so this -// one) on every push to main and nightly, in the same workflow run as the `main-check` job. In both +// main.yml's `integration` job runs integrationCheck (an integration lane, so this one) on every push +// to main and nightly, in the same workflow run as the `main` job. In both // stages, every main push started a second Toxiproxy and httpbin and ran every fault twice without // covering anything the first run did not (review 2026-11-03 README §8, closed in round 9; the // cache-redis container lane left mainCheck for the same reason). verifyStrictLaneStages still fails diff --git a/src/adapter/outbound/persistence-jpa/build.gradle b/src/adapter/outbound/persistence-jpa/build.gradle index 6ef7a85e..44ffb59d 100644 --- a/src/adapter/outbound/persistence-jpa/build.gradle +++ b/src/adapter/outbound/persistence-jpa/build.gradle @@ -313,7 +313,7 @@ tasks.named('test') { // The whole directory, not the two named workflows: the Experimental-major check asks whether // *some* lane records that major as its target, so adding or deleting any workflow can change // its answer. Naming files here would leave the lane that matters outside the up-to-date check. - inputs.dir(new File(rootProject.projectDir.parentFile, '.github/workflows')) + inputs.dir(new File(rootProject.projectDir.parentFile, '.gitea/workflows')) inputs.file(file('build.gradle')) inputs.dir(file('src/jpaPlatformPerformanceTest/java')) // AppliedMigrationImmutabilityTest pins the notification and fileserver streams where they live. diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/Hibernate8CompatibilityTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/Hibernate8CompatibilityTest.java index 10ab750a..8b024d4e 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/Hibernate8CompatibilityTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/Hibernate8CompatibilityTest.java @@ -7,7 +7,8 @@ import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; /** - * The Hibernate 8 probe that {@code .github/workflows/jpa-next.yml} runs. + * The Hibernate 8 probe that the nightly {@code jpa-next} job of {@code .gitea/workflows/main.yml} + * runs. * *

The provider version is read from Hibernate itself rather than from the build file, because * the build file states an intent and the classpath states the fact. Dependency resolution, diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/Jpa4CompatibilityTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/Jpa4CompatibilityTest.java index 61c98fc2..0bc3b0e2 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/Jpa4CompatibilityTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/Jpa4CompatibilityTest.java @@ -7,7 +7,8 @@ import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; /** - * The Jakarta Persistence 4 probe that {@code .github/workflows/jpa-next.yml} runs. + * The Jakarta Persistence 4 probe that the nightly {@code jpa-next} job of {@code + * .gitea/workflows/main.yml} runs. * *

JPA 4 is not released, so nothing can run against it. The probe reads the specification * version off the API actually on the classpath, so the day a dependency upgrade brings JPA 4 in it diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/PostgreSql19CompatibilityTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/PostgreSql19CompatibilityTest.java index 1be2c1aa..f7a97105 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/PostgreSql19CompatibilityTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/experimental/next/PostgreSql19CompatibilityTest.java @@ -6,7 +6,8 @@ import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; /** - * The PostgreSQL 19 probe that {@code .github/workflows/jpa-next.yml} runs. + * The PostgreSQL 19 probe that the nightly {@code jpa-next} job of {@code + * .gitea/workflows/main.yml} runs. * *

Unlike the specification and provider probes, this one has no artifact to detect: a server * version is only observable by starting one. So the assertion is about the support matrix instead diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/testkit/JpaReleaseRenderingTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/testkit/JpaReleaseRenderingTest.java index 641b3e6e..a4003bff 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/testkit/JpaReleaseRenderingTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/testkit/JpaReleaseRenderingTest.java @@ -31,8 +31,8 @@ class JpaReleaseRenderingTest { private final JpaReleaseManifest manifest = JpaReleaseManifest.loadFromRepository(); private final String supportMatrix = read("docs/jpa/support-matrix.md"); - private final String releaseWorkflow = read(".github/workflows/release.yml"); - private final String nightlyWorkflow = read(".github/workflows/jpa-nightly.yml"); + private final String releaseWorkflow = read(".gitea/workflows/release.yml"); + private final String nightlyWorkflow = read(".gitea/workflows/main.yml"); @Test @DisplayName("the support document states the registry's support level for every major") @@ -109,14 +109,6 @@ class JpaReleaseRenderingTest { .containsExactlyElementsOf(manifest.stableVersions()); } - @Test - @DisplayName("the promotion job requires evidence for exactly the Stable majors") - void thePromotionJobRequiresEvidenceForExactlyTheStableMajors() { - assertThat(JpaReleaseRendering.workflowPromotionMajors(releaseWorkflow)) - .as("promotion that checks fewer majors than the matrix runs ignores a failed one") - .containsExactlyElementsOf(manifest.stableVersions()); - } - @Test @DisplayName("a workflow matrix that drops a Stable major is caught") void aWorkflowMatrixThatDropsAStableMajorIsCaught() { @@ -204,7 +196,7 @@ class JpaReleaseRenderingTest { */ private static List compatibilityTargetsAcrossWorkflows() { List targets = new ArrayList<>(); - Path directory = locate(".github/workflows"); + Path directory = locate(".gitea/workflows"); try (var entries = Files.list(directory)) { for (Path workflow : entries.sorted().toList()) { if (workflow.getFileName().toString().endsWith(".yml")) { diff --git a/src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/release/JpaReleaseRendering.java b/src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/release/JpaReleaseRendering.java index e5e45dd4..0f54f717 100644 --- a/src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/release/JpaReleaseRendering.java +++ b/src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/release/JpaReleaseRendering.java @@ -27,7 +27,6 @@ public final class JpaReleaseRendering { private static final Pattern DOCUMENT_GATE_ROW = Pattern.compile("^\\|\\s*`([a-z0-9-]+)`\\s*\\|\\s*gate\\s*\\|", Pattern.MULTILINE); private static final Pattern WORKFLOW_MATRIX = Pattern.compile("postgresql:\\s*\\[([^\\]]*)\\]"); - private static final Pattern WORKFLOW_PROMOTION_LOOP = Pattern.compile("for major in ([0-9 ]+);"); private static final Pattern QUOTED_MAJOR = Pattern.compile("\"(\\d+)\""); private static final Pattern COMPATIBILITY_TARGET = Pattern.compile("^\\s*target:\\s*PostgreSQL\\s+(\\d+)\\s*$", Pattern.MULTILINE); @@ -77,26 +76,6 @@ public final class JpaReleaseRendering { return majors; } - /** - * The majors the promotion job requires evidence for. - * - *

Read separately from the matrix on purpose. They are two hand-written lists in one file, and - * a promotion that requires fewer majors than the matrix produces is a promotion that ignores a - * failed one. - */ - public static List workflowPromotionMajors(String workflow) { - Objects.requireNonNull(workflow, "workflow"); - Matcher loop = WORKFLOW_PROMOTION_LOOP.matcher(workflow); - if (!loop.find()) { - throw new IllegalArgumentException("the release workflow declares no promotion major list"); - } - List majors = new ArrayList<>(); - for (String major : loop.group(1).trim().split("\\s+", -1)) { - majors.add(Integer.parseInt(major)); - } - return majors; - } - /** * Every major some job in a workflow fans out to. * @@ -122,15 +101,15 @@ public final class JpaReleaseRendering { * The majors a compatibility lane records itself as targeting. * *

An Experimental major is declared "compatibility lane only" and nothing tied that phrase to - * a file. The lane does exist — it runs weekly and records {@code NOT_EXECUTABLE} with its reason - * — but the registry, the support document and the release workflow could each be read end to end - * without establishing that. A reader who cannot find the lane concludes there is none, which is - * the conclusion this repository's own review pass reached before checking the workflow + * a file. The lane does exist — it runs nightly and records {@code NOT_EXECUTABLE} with its + * reason — but the registry, the support document and the release workflow could each be read end + * to end without establishing that. A reader who cannot find the lane concludes there is none, + * which is the conclusion this repository's own review pass reached before checking the workflow * directory. * - *

The target is read from the workflow matrix declaration rather than from its filename. The - * status artifact receives that same matrix value through {@code TARGET}; a lane that stops - * declaring its PostgreSQL target therefore stops counting as a lane. + *

The target is read from the workflow matrix declaration rather than from a job name. The + * job's NOT_EXECUTABLE line prints that same matrix value; a lane that stops declaring its + * PostgreSQL target therefore stops counting as a lane. */ public static List compatibilityLaneTargets(String workflow) { Objects.requireNonNull(workflow, "workflow"); diff --git a/src/adapter/outbound/redis-sdk/compose/README.md b/src/adapter/outbound/redis-sdk/compose/README.md index a990dff2..eb81e9ba 100644 --- a/src/adapter/outbound/redis-sdk/compose/README.md +++ b/src/adapter/outbound/redis-sdk/compose/README.md @@ -5,8 +5,10 @@ 허락하는지. 넷 모두 Redis 7.4에서 돌았고 증거는 `docs/redis/support-matrix.md`에 적혀 있다. -`.github/workflows/redis-sdk-topology.yml`은 Redis leaf를 건드리는 pull request마다 standalone lane을, 매일 밤 -지원 버전 × topology 표 전체를, 릴리스 후보에는 요청할 때 같은 표를 돌린다. +`.gitea/workflows/main.yml`의 nightly `redis-topology` job이 매일 밤(그리고 손으로 실행할 때) 지원 버전 × topology 표 +전체를 행마다 `scripts/ci/redis-topology.sh `으로 돌린다. 같은 줄을 Docker가 있는 머신에서 +손으로 돌릴 수 있다. pull request마다 돌던 standalone lane은 2026-11-08에 nightly로 옮겼다(어댑터 컨테이너 lane은 +main 단계, 소유자 결정 2026-11-07). TLS는 손으로 배선할 것이 아니라 그 표의 lane 하나다. 배포 모드가 아니라 `tls`다: 모양은 standalone이고 검증하는 것은 전송이다. 그래서 `redisTopologyTest`는 시험에서 lane 이름을 `standalone`으로 대응시키고, tag 필터와 필요한 diff --git a/src/app-bootstrap/build.gradle b/src/app-bootstrap/build.gradle index 05cb31fb..e65b9211 100644 --- a/src/app-bootstrap/build.gradle +++ b/src/app-bootstrap/build.gradle @@ -330,13 +330,13 @@ dependencies { // leaves it up to date // // The pull-request lane exists because some of those contracts are release and security -// properties — the signing job's OIDC scope, the Docker staging contract, the request-logging body +// properties — the signing job's key handling, the Docker staging contract, the request-logging body // capture ban — that must stop a merge, not be found after one. def repositoryRootForContractTests = rootProject.projectDir.parentFile def repositoryContractExcludes = ['**/build/**', '**/.gradle/**', '**/node_modules/**'] def repositoryContractInputs = files( fileTree(repositoryRootForContractTests) { - include '.github/**', 'compose/**', 'scripts/**', '*.yml', '*.yaml', '*.example', '.tool-versions' + include '.gitea/**', '.github/**', 'compose/**', 'scripts/**', '*.yml', '*.yaml', '*.example', '.tool-versions' exclude '**/*.md' exclude repositoryContractExcludes }, diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java index 11d1f23a..fdd99573 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/DeveloperExperienceContractTest.java @@ -32,7 +32,9 @@ import org.yaml.snakeyaml.constructor.SafeConstructor; class DeveloperExperienceContractTest { private static final Path REPOSITORY_ROOT = repositoryRoot(); - private static final String MAIN_WORKFLOW = ".github/workflows/integration-main.yml"; + private static final String PR_WORKFLOW = ".gitea/workflows/pr.yml"; + private static final String MAIN_WORKFLOW = ".gitea/workflows/main.yml"; + private static final String RELEASE_WORKFLOW = ".gitea/workflows/release.yml"; // The workflow-mutation fixtures that stood here are gone with the tests that used them: a // hex-escaped `uses:`, a line-continued action reference, a `run:` block impersonating a @@ -159,7 +161,9 @@ class DeveloperExperienceContractTest { .orElseThrow(() -> new AssertionError("missing lychee action step")); // then - assertThat(links.containsKey("if")).as("a conditional link check is one nobody sees run").isFalse(); + assertThat(links.containsKey("if")) + .as("a conditional link check is one nobody sees run") + .isFalse(); assertThat(String.valueOf(lycheeStep.get("uses"))) .endsWith("lycheeverse/lychee-action@7cd0af4c74a61395d455af97419279d86aafaede"); Map with = requireMap(lycheeStep, "with"); @@ -182,8 +186,9 @@ class DeveloperExperienceContractTest { void testcontainersReuseIsLocalOptInAndExplicitlyDisabledInCi() throws IOException { assertThat(read("testcontainers.properties.example")) .contains("testcontainers.reuse.enable=true"); - assertThat(read(".github/workflows/ci-quality-gates.yml")) - .contains("TESTCONTAINERS_REUSE_ENABLE: \"false\""); + for (String workflow : List.of(PR_WORKFLOW, MAIN_WORKFLOW, RELEASE_WORKFLOW)) { + assertThat(read(workflow)).as(workflow).contains("TESTCONTAINERS_REUSE_ENABLE: \"false\""); + } } @Test @@ -204,7 +209,7 @@ class DeveloperExperienceContractTest { // // The wrapper guarantee itself is unchanged and is now the official action's: // gradle/actions/setup-gradle validates every wrapper jar in the repository by default, it is - // applied through .github/actions/setup-gradle-java, and it is pinned to a full commit SHA. + // applied through .gitea/actions/setup-java-gradle, and it is pinned to a full commit SHA. // What is left to assert here is what that action cannot: that the wrapper is committed, and // that its distribution is pinned by checksum rather than by URL alone. assertThat(REPOSITORY_ROOT.resolve("src/gradle/wrapper/gradle-wrapper.jar")).isRegularFile(); @@ -216,13 +221,14 @@ class DeveloperExperienceContractTest { .contains("validateDistributionUrl=true") .contains("https\\://services.gradle.org/distributions/"); - String setupAction = read(".github/actions/setup-gradle-java/action.yml"); + String setupAction = read(".gitea/actions/setup-java-gradle/action.yml"); assertThat(setupAction) .as("wrapper validation has to be reachable from every Gradle job") .contains("gradle/actions/setup-gradle@"); assertThat(setupAction) .as("an action reference is only immutable when it is a full commit SHA") - .containsPattern("uses: [\\w./-]+@[0-9a-f]{40} #"); + .containsPattern("uses: [\\w.:/-]+@[0-9a-f]{40} #") + .doesNotContainPattern("uses: [\\w.:/-]+@(?![0-9a-f]{40} )"); } @Test @@ -265,12 +271,13 @@ class DeveloperExperienceContractTest { void architectureWorkflowSelectorsUseTheArchitectureSourceSetTask() throws IOException { String staleSelector = ":app-bootstrap:test --tests 'dev.caskeleton.bootstrap.architecture.*'"; - // The whole-repository architecture suite runs once per pull request, in ci-quality-gates.yml's - // `:ci` (architectureCheck), and the release workflow runs only the tag-only releaseCheck. - assertThat(read(".github/workflows/ci-quality-gates.yml")) - .as("the pull-request gate is the one place the architecture suite runs") - .contains("./gradlew :ci"); - assertThat(read(".github/workflows/release.yml")) + // The whole-repository architecture suite runs once per pull request, in pr.yml's `:prCheck` + // (`ci` -> architectureCheck), and the release workflow runs only the tag-only releaseCheck. + assertThat(read(PR_WORKFLOW)) + .as("the pull-request stage is the one place the architecture suite runs") + .contains("./gradlew :prCheck") + .doesNotContain(staleSelector); + assertThat(read(RELEASE_WORKFLOW)) .as("the release workflow runs the tag-only checks through releaseCheck") .contains("./gradlew :releaseCheck") .doesNotContain(staleSelector); @@ -293,29 +300,23 @@ class DeveloperExperienceContractTest { @Test @Tag("repository-contract") - @DisplayName("릴리스 이미지는 서명 job 하나만 OIDC 토큰을 받아 digest를 keyless 서명하고 검증한다") - void onlyTheSigningJobHoldsAnOidcTokenAndItSignsAndVerifiesTheDigest() throws IOException { + @DisplayName("릴리스 이미지는 태그에서만 서명 job 하나가 키 쌍으로 digest를 서명하고 검증한다") + void onlyTheSigningJobHoldsTheReleaseKeyAndItSignsAndVerifiesTheDigest() throws IOException { // given - Map workflow = parseYamlMap(read(".github/workflows/release.yml")); - Map jobs = requireMap(workflow, "jobs"); + Map jobs = requireMap(parseYamlMap(read(RELEASE_WORKFLOW)), "jobs"); // when - List jobsWithIdToken = + List jobsWithTheKey = jobs.entrySet().stream() - .filter( - job -> - job.getValue() instanceof Map body - && body.get("permissions") instanceof Map permissions - && permissions.containsKey("id-token")) + .filter(job -> String.valueOf(job.getValue()).contains("secrets.COSIGN_PRIVATE_KEY")) .map(job -> String.valueOf(job.getKey())) .toList(); // then - assertThat(requireMap(workflow, "permissions").containsKey("id-token")).isFalse(); - assertThat(jobsWithIdToken).containsExactly("app-image-signing"); + assertThat(jobsWithTheKey).containsExactly("app-image-signing"); Map signing = requireMap(jobs, "app-image-signing"); - assertThat(requireMap(signing, "permissions").get("id-token")).isEqualTo("write"); assertThat(requireStringList(signing, "needs")).containsExactly("app-image-release"); + assertThat(requireString(signing, "if")).contains("github.ref_type == 'tag'"); String script = String.join( "\n", @@ -326,9 +327,8 @@ class DeveloperExperienceContractTest { assertThat(script) .contains("cosign_checksums.txt") .contains("sha256sum -c -") - .contains("cosign sign --yes") - .contains("cosign verify") - .contains("--certificate-oidc-issuer https://token.actions.githubusercontent.com"); + .contains("cosign sign --yes --key env://COSIGN_PRIVATE_KEY") + .contains("cosign verify --key"); assertThat(requireList(signing, "steps")) .as("the signing job installs a checksum-pinned binary, not a third-party action") .noneMatch(step -> step instanceof Map map && map.containsKey("uses")); diff --git a/src/build-logic/AGENTS.md b/src/build-logic/AGENTS.md index d5f1fa86..1221026e 100644 --- a/src/build-logic/AGENTS.md +++ b/src/build-logic/AGENTS.md @@ -7,7 +7,7 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 - `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다. - `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다. - `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(`strictTestLanes`). leaf는 `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다. -- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전·리비전. +- `src/build.gradle`: 루트 라이프사이클(`ci`, `prCheck`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 그것을 workflow job에 묶는 `strictLaneStages`, 버전·리비전. ## 저장소 파일을 읽는 테스트 @@ -23,15 +23,11 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 - `PERFORMANCE` lane은 상한을 매번 단언한다. 끄는 스위치가 없다. convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도). 사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다. - `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의 `ca.config-contract`다. -## `verifyStrictLaneStages`가 세는 명령 +## 단계 job의 모양 -`verifyStrictLaneStages --dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는 단계(`ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈 줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. `-x`로 뺀 lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-m`·`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는 짧은 옵션 묶음(`-mx`), 다른 빌드를 실행하는 명령은 세지 않는다. 그 밖에 세지 않는 명령은 이유가 셋이다. - -1. 실패해도 단계가 실패하지 않을 수 있다: `|| exit <0 아닌 값>` 밖의 `||`(`|| true` 등), pipefail 없는 파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤, `exit 0` 하는 `EXIT`·`ERR` trap 뒤, `continue-on-error`. -2. 돌지 않을 수 있다: `||` 뒤, 마지막이 아닌 `&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나 부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태 함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만 시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore` 필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches` 없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이 부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job. -3. 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른 명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤, `bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`). - -실패 메시지는 명령마다 이유를 적고 단계 명령을 혼자 한 줄로 두라고 안내한다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서 시작해 같은 셸이 그 앞에서 확실히 실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다. +- `verifyStrictLaneStages --dry-run`(PR)은 `explicitOnly`가 아닌 strict lane마다 `src/build.gradle`의 `strictLaneStages`가 선언한 단계 태스크 하나의 계획에 들어 있는지 본다(그래프 검사). +- 단계마다 선언한 workflow job은 step의 `run: ./gradlew <단계> <옵션>` 줄을 가지고, 다른 step `run:`도 셸 문법 없는 `./gradlew` 한 줄이며, 선언 밖의 `if:`, 선언한 조건이 `!cancelled()`·`always()`가 아닌데 `needs:`, `continue-on-error`·`shell:`·`defaults:`, 따옴표 키·flow 형식, 이 빌드 밖의 `working-directory`가 없다. workflow는 선언한 이벤트로, 선언한 필터 한 줄만 달고 시작하고, PR 단계 job 하나가 이 검사를 돌린다(형식 검사, 셸을 해석하지 않는다). +- 단계를 더하거나 job을 바꾸면 `strictLaneStages`의 `stage` 줄과 workflow를 같은 커밋에서 고친다. ## 테스트 diff --git a/src/build-logic/README.md b/src/build-logic/README.md index 71cf803e..0e6a3f21 100644 --- a/src/build-logic/README.md +++ b/src/build-logic/README.md @@ -15,8 +15,8 @@ capability를 가진 leaf의 시험이고, 그 시험이 읽는 파일은 그 | `ca.java-library` / `ca.spring-library` / `ca.spring-config` | 평범한 라이브러리와 Spring 라이브러리를 위한 Java·품질 규약의 leaf 단위 조합 | | `ca.platform-module` | 들여온 플랫폼 leaf(`messaging:*`)가 무엇인가: `java-library`. gRPC 플랫폼과 그 BOM 규약(`ca.grpc-platform-module`)은 2026-11-08에 별도 repo `grpc-library`로 옮겼다 | | `ca.strict-test-lane` | 「이름 댄 시험이 돌았고 건너뛴 것이 없다」를 보는 유일한 장치: tag·이름·자기 source set으로 고른 `Test` lane이 아무것도 실행하지 않거나, `requires` 클래스를 빠뜨리거나, (`rejectSkipped`이면) 무엇이든 건너뛰면 실패한다. `performance()` lane은 언제나 건너뛰기를 거절하고 `performance.assertions.enabled=true`로 돈다. 빌드(`-P`, `GRADLE_OPTS`)나 lane이 다른 값을 넣으면 시험이 돌기 전에 실패한다. `mainStage()`는 tag로 고른 lane을 `test`에서 빼 leaf의 `mainCheck`로 옮긴다. `explicitOnly(reason)`는 바깥 입력이 필요한 lane을 모든 묶음 태스크에서 빼고, 묶음 태스크가 그 이유를 출력한다. 시험 source set을 더 두려면 leaf에 Gradle `jvm-test-suite` suite로 선언한다(`testing { suites { … } }`). suite 이름을 딴 lane은 그 suite 자신의 `Test` 태스크를 엄격하게 만들고, `ca.java-conventions`는 모든 suite에 BOM의 JUnit을 준다 | -| `ca.strict-lane-stages` (주 빌드의 루트) | lane 장치의 나머지 절반: `verifyStrictLaneStages --dry-run`은 그 빌드의 `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 선언된 단계 어느 것의 태스크 계획에도 없거나, 선언된 단계를 실행하는 workflow가 없으면 실패한다. workflow는 함께 읽고(`WorkflowGradleInvocations.readAll`. 그래서 재사용 workflow는 그것을 부르는 쪽으로 판정한다) `run:` 스크립트는 bash로 파싱한다(`ShellScript`: 따옴표, 주석, heredoc 본문, 치환, 복합 명령을 셸이 읽듯 읽는다. 그래서 heredoc이나 문자열 안의 `cd`는 데이터다). Gradle이 태스크를 하나도 돌리지 않는 명령은 세지 않는다 — `--dry-run`/`-m`(`-qm` 같은 묶음 안도), `-v`/`--version`, `-h`/`-?`/`--help`, `--status`, `--stop`, `--foreground`(`-qv` 같은 묶음 안도) — Gradle이 거절하는 명령도 세지 않는다: 뒤 글자가 값을 받는 짧은 옵션 묶음(`-mx`: 묶음에서는 첫 글자만 값을 받는다), 값을 받지 않는 옵션에 준 값(`-m=yes`). 읽는 방식은 Gradle 9.0의 파서를 따른다. `GradleCommandLineTest`는 옵션 표를 build-logic을 돌리는 Gradle의 `--help`와 맞춘다 — 옵션을 더하는 업그레이드는(9.2가 `--task-graph`를 더하듯) 그 옵션을 자리에 넣기 전까지 실패한다 — 그리고 `--stop`과 `--foreground`를 뺀 태스크 없는 옵션마다 launcher를 돌린다(둘은 Gradle `BuildActionsFactory`에서 빌드가 아니라 daemon 동작을 돌려준다). 어떤 옵션이 값을 받는지는 round 9에 9.0.0으로 탐침했고 다시 돌리지 않는다. 다른 빌드를 위한 명령도 세지 않는다(명령이 시작하는 빌드는 그 step의 `working-directory`, 또는 job이나 workflow의 `defaults.run.working-directory`에서 시작해, 같은 `run:` 셸이 그 앞에서 반드시 돌린 `cd <리터럴 상대 경로>`마다 옮기고 — 혼자 있는 목록이거나 같은 `&&` 목록에서 그 명령 앞에 있을 때 — 그다음 `-p`로 이은 곳이다. 플러그인은 이 빌드 자신의 디렉터리를 `.github/workflows`를 가진 저장소 아래 어디에 있는지로 읽는다). 세지 않는 그 밖의 명령은 모두 세 이유 중 하나를 댄다. **실패해도 step이 실패하지 않을 수 있다**: `\|\| true`, `\|\| :`, `\|\| exit <0 아닌 값>`이 아닌 모든 `\|\|`, `pipefail` 없는 pipe의 왼쪽(`shell: bash`나 최상위 `set -o pipefail`이면 켜진다), `!`, `&`, `if`/`while` 조건, 스크립트의 마지막 명령이 아닌 목록에서 `&&` 앞부분, `set +e` 뒤, `EXIT`나 `ERR` 동작이 상태 0으로 `exit`할 수 있는 `trap` 뒤(`EXIT` trap 안의 맨 `exit`는 상태를 지키지만 `ERR` trap 안에서는 아니다), `continue-on-error`. **돌지 않을 수 있다**: `\|\|` 뒤, 스크립트의 마지막 명령이 아닌 목록에서 `&&` 뒤, `if`/`while`/`for`/`case` 안이나 함수 본문 안, 최상위 `exit`·`exec `·`set -n` 뒤, 다른 곳 — 복합 명령, and-or 목록, 스크립트가 부르는 함수 — 에서 스크립트를 상태 0으로 끝낼 수 있는 것(`exit 0`, `\|\|` 바로 뒤가 아닌 맨 `exit`, `exit "$code"`), 스크립트를 바꿔치는 것, 명령 실행을 멈추는 것(`set -o noexec`) 뒤, `always()`/`success()`/`!cancelled()`가 아닌 `if:` 아래, 누가 또는 무엇이 요청해야만 시작하는 이벤트(`workflow_dispatch`, `repository_dispatch`, `issue_comment`, `types: [labeled]`인 pull request, `workflow_run`, …. `push`, `pull_request`, `pull_request_target`, `merge_group`, `schedule`, `release`는 센다)로만 시작하는 workflow 안, 변경 흐름 트리거가 모두 `paths`나 `paths-ignore` 필터를 가진 workflow 안(그 경로 밖의 변경은 workflow를 시작하지 않는다. 소유자 결정 2026-11-06), 요청이나 경로 필터 없이 릴리스 흐름에서만 시작하는 workflow 안의 `:releaseCheck`가 아닌 단계 — 릴리스 흐름은 `release`, 또는 `tags`/`tags-ignore`가 있고 `branches`/`branches-ignore`가 없는 `push`로, 브랜치 push로는 시작하지 않는다(소유자 결정 2026-11-07. `:releaseCheck`가 태그 전용 단계다) — 센 job 어느 것도 `uses: ./.github/workflows/`로 부르지 않는 재사용(`workflow_call`만 있는) workflow 안, 그리고 그런 `if:`나 `continue-on-error`를 가진 job을 직접 또는 다른 job을 거쳐 `needs`하는 job 안(자기 `if:`가 `always()`나 `!cancelled()`이면 예외). **이 검사가 읽지 않는다**(실패하면 step이 실패하지만, 일부러 거짓 실패로 둔다): `\|\| exit 1`, `\|\| { …; exit 1; }`, `{ }`나 `( )` 안, `$( )`, `bash -c`, 다른 명령의 인자인 `gradlew`(`timeout 60 ./gradlew`), 읽는 쪽이 따라가지 않는 디렉터리 이동 뒤(`cd "$VAR"`, `cd -`, `cd ~`, 절대 경로, `pushd`/`popd`, `builtin cd`, `eval`/`source`, 복합 명령이나 함수 본문 안의 `cd`, `\|\|`로 이은 것, pipe나 background로 돌린 것, 다른 명령과 같은 `&&` 목록에 있는 `cd`의 뒤 줄 — 짐작하지 않는다), `shell:`이 `bash`나 `sh`가 아닌 step, `runs-on`이 Windows runner일 수 있는 job에서 `shell:`이 없는 step(기본 셸이 `pwsh`다. Windows label, `${{ matrix.os }}` 같은 표현식, `linux`나 `macos`가 없는 self-hosted label 집합. Linux·macOS runner의 기본은 `bash -e`, `container:` job의 기본은 `sh -e`이고 둘을 같이 읽는다). step을 실패시키는 `exit` — `exit 1`, `cmd \|\| exit` — 와 부르지 않는 함수, `( )` subshell, `$( )` 안의 `exit`는 그 뒤의 명령이 세지는 것을 막지 않는다. 실패 메시지는 단계 이름을 대지만 그 단계를 실행하지 않는 모든 명령을 그 이유나 그것이 시작하는 다른 빌드와 함께 대고, 단계를 혼자 있는 줄의 `./gradlew`로 돌리라고 말한다. 명령이 `-x`로 뺀 lane은 덮인 것이 아니다 — Gradle이 태스크·프로젝트 이름을 맞추는 방식(약어 포함)으로 맞춘다(`TaskSelectors`, Gradle 내부 `NameMatcher`의 사본). `uses:` step의 `run:` 입력은 명령이 아니다. 계획은 Gradle 자신의 것이다. workflow는 YAML folding을 적용해 `run:` step을 읽는다(review 2026-11-01 08-01, 2026-11-03 RR-06-03/04, 2026-11-04 RR2-04-04, `cd`에 대한 소유자 결정 2026-11-04, round 9의 RR5-02-01/02/03, 2026-11-05 RR6-04-01..06, 2026-11-06 RR7-05-01, 릴리스 흐름에 대한 소유자 결정 2026-11-07) | -| `ca.redis-topology-lane` | redis-sdk-topology workflow가 돌리는 Redis topology lane(모드 고르기, `-P` 속성 검증, 모드별 필수 클래스) | +| `ca.strict-lane-stages` (주 빌드의 루트) | lane 장치의 나머지 절반: `verifyStrictLaneStages --dry-run`은 그 빌드의 `explicitOnly`가 아닌 strict lane이 `strictLaneStages`에 선언한 단계 태스크 어느 것의 계획에도 없으면 실패한다(계획은 Gradle 자신의 것). 단계마다 그것을 돌리는 workflow job(파일·이벤트·job·옵션·조건)도 선언하고, 그 job이 정해진 한 줄 모양인지 고정 문자열로 본다(`src/build-logic/AGENTS.md` 「단계 job의 모양」). 2026-11-08까지 이 자리에 workflow YAML과 bash를 해석하던 판독기(`WorkflowGradleInvocations`·`ShellScript`·`TaskSelectors`)가 있었고, workflow를 셋으로 접으면서 지웠다 | +| `ca.redis-topology-lane` | `main.yml`의 nightly `redis-topology` job(`scripts/ci/redis-topology.sh`)이 돌리는 Redis topology lane(모드 고르기, `-P` 속성 검증, 모드별 필수 클래스) | | `ca.api-surface` | 읽기 전용 공개 API surface 검증과 따로 둔 갱신 태스크. leaf의 `check`에 배선한다(소유자 결정 20). 다른 leaf의 import를 리뷰한 adopter 부분집합(`adopterBaseline`)에 묶을 수도 있다 | | `ca.config-contract` | app-bootstrap의 `verifyEnvKeys`(지운 build-tools included build에서 옮겼다. 소유자 결정 4가 그 태스크를 app-bootstrap에 둔다) | | `ca.bootrun-dotenv` | `bootRun`의 `.env` | diff --git a/src/build-logic/build.gradle b/src/build-logic/build.gradle index e1a7f4d5..88d9c824 100644 --- a/src/build-logic/build.gradle +++ b/src/build-logic/build.gradle @@ -96,8 +96,4 @@ gradlePlugin { 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/src/build-logic/src/main/java/dev/caskeleton/buildlogic/redis/RedisTopologyLanePlugin.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/redis/RedisTopologyLanePlugin.java index 33ba01e0..99a82e69 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/redis/RedisTopologyLanePlugin.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/redis/RedisTopologyLanePlugin.java @@ -65,7 +65,7 @@ public final class RedisTopologyLanePlugin implements Plugin { // so rather than failing on an input it was never given (review NEW-16). lane.explicitOnly( "it needs -Predis.topology.mode= and the topology" - + " coordinates from redis-sdk/compose (redis-sdk-topology.yml passes them)"); + + " coordinates from redis-sdk/compose (scripts/ci/redis-topology.sh passes them)"); } lane.setTag("redis-topology & lane-" + declaredMode); lane.setDescription( diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ShellScript.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ShellScript.java deleted file mode 100644 index 4f930134..00000000 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/ShellScript.java +++ /dev/null @@ -1,1659 +0,0 @@ -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/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesExtension.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesExtension.java index ef53b68e..c1f10035 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesExtension.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesExtension.java @@ -1,29 +1,83 @@ package dev.caskeleton.buildlogic.strictlane; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import java.util.Set; +import org.gradle.api.GradleException; 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. + * The stages a strict lane may belong to, and the one workflow job that runs each of them. * - *

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. + *

+ * strictLaneStages {
+ *   workflowDirectory = layout.projectDirectory.dir('../.gitea/workflows')
+ *   stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle'
+ *   stage ':mainCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]',
+ *       job: 'main', options: '--continue'
+ *   stage ':performanceCheck', workflow: 'main.yml', event: 'schedule', job: 'performance',
+ *       options: '--continue', condition: '${{ !cancelled() }}'
+ * }
+ * 
+ * + *

The job runs the stage as {@code ./gradlew } on a line of its own. {@code + * filter} is the one line under the event (none if absent; a schedule takes its cron lines), and + * {@code condition} is the job's {@code if:}: both are written out here so that changing when a + * stage runs is a reviewed change of the build rather than an edit to a workflow. Single quotes, + * because Groovy reads {@code ${...}} in double quotes as its own expression. */ public abstract class StrictLaneStagesExtension { - public abstract ListProperty getStages(); + /** The options a stage line may carry: none of them changes which tasks run. */ + static final Set STAGE_OPTIONS = Set.of("--continue", "--stacktrace"); - /** - * 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}, in - * the optional gRPC build that has since moved to its own repository). - */ + private final List stages = new ArrayList<>(); + + /** The repository's workflow directory. Its grandparent is the repository root. */ public abstract DirectoryProperty getWorkflowDirectory(); - public void stage(String... taskPaths) { - getStages().addAll(taskPaths); + public void stage(Map job, String taskPath) { + Stage stage = + new Stage( + taskPath, + required(job, "workflow", taskPath), + required(job, "event", taskPath), + job.get("filter"), + required(job, "job", taskPath), + job.getOrDefault("options", ""), + job.get("condition")); + for (String option : stage.options().split(" ", -1)) { + if (!option.isEmpty() && !STAGE_OPTIONS.contains(option)) { + throw new GradleException( + "stage " + taskPath + ": option " + option + " is not one of " + STAGE_OPTIONS); + } + } + stages.add(stage); + } + + List getStages() { + return List.copyOf(stages); + } + + private static String required(Map job, String key, String taskPath) { + String value = job.get(key); + if (value == null || value.isBlank()) { + throw new GradleException("stage " + taskPath + " needs '" + key + "'"); + } + return value; + } + + /** One stage and the workflow job that runs it. */ + record Stage( + String taskPath, + String workflow, + String event, + String filter, + String job, + String options, + String condition) { + String command() { + return options.isEmpty() ? "./gradlew " + taskPath : "./gradlew " + taskPath + " " + options; + } } } diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java index 28ca1692..493887fb 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesPlugin.java @@ -5,16 +5,16 @@ import java.io.IOException; import java.io.UncheckedIOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; +import java.nio.file.Path; 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 java.util.regex.Matcher; +import java.util.regex.Pattern; import org.gradle.api.GradleException; import org.gradle.api.Plugin; import org.gradle.api.Project; @@ -22,63 +22,51 @@ import org.gradle.api.Task; import org.gradle.api.execution.TaskExecutionGraph; /** - * Fails when a strict lane belongs to no stage a workflow executes. + * Fails when a strict lane belongs to no stage, or when a stage's workflow job does not run it. * *

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: + * reaches is a file that looks like coverage (review 2026-11-01 08-01 found fourteen). Two checks + * answer that, both with fixed rules rather than by interpreting shell: * *

    - *
  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). + *
  3. Graph. Every strict lane that is not {@code explicitOnly} is in the task plan of a + * declared stage. The plan is Gradle's own: this task depends on the stages, so its {@code + * --dry-run} builds the real plan, and the check reads it when the graph is ready. + *
  4. Form. Each stage names the workflow job that runs it, and that job has one shape. + * Its steps' {@code run:} lines are single {@code ./gradlew} commands with no shell syntax, and + * one of them is {@code ./gradlew }. It has no {@code if:} but the declared + * condition, no {@code needs:} unless that condition runs it after a skipped or failed job, no + * {@code continue-on-error}, {@code shell:} or {@code defaults:}, no quoted keys or flow + * mappings, and every {@code working-directory} in it or in the workflow's {@code defaults} + * is this build's. The workflow starts on the declared event with exactly the declared filter + * (a misspelt branch is a filter too). One pull-request stage job also runs this check. *
* - *

A build that holds strict lanes applies it at its root (here, the main build; until 2026-11-08 - * the optional gRPC platform build applied it too). 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).

+ *

Until 2026-11-08 the second half read every workflow's shell with a general interpreter, which + * produced a new defect in nearly every review round. A narrow form needs no interpreter: a job that + * does not have it fails here, on its own pull request. * - *

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. + *

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)"; + /** The command a pull-request stage job runs so that this check itself runs. */ + static final String SELF_CHECK = "./gradlew :" + TASK_NAME + " --dry-run"; + + private static final Pattern ANY_RUN = Pattern.compile("^\\s*(?:-\\s+)?run:"); + /** A step's command: `- run:` at the step indent, or `run:` under a step's first key. */ + private static final Pattern STEP_RUN = Pattern.compile("^(?: {6}- | {8})run: (.*?)\\s*$"); + /** One Gradle invocation and nothing a shell would read as more than words. */ + private static final Pattern GRADLE_LINE = Pattern.compile("^\\./gradlew(?: [\\w:.=-]+)+$"); + private static final Pattern IF = Pattern.compile("^(\\s*)(?:-\\s+)?if:\\s*(.*?)\\s*$"); + private static final Pattern WORKING_DIRECTORY = + Pattern.compile("^\\s*(?:-\\s+)?working-directory:\\s*(.*?)\\s*$"); + private static final Pattern FORBIDDEN_IN_JOB = + Pattern.compile("^\\s*(?:-\\s+)?(continue-on-error|shell|defaults):"); + private static final Pattern NEEDS = Pattern.compile("^ {4}needs:"); + private static final Pattern QUOTED_KEY = Pattern.compile("^\\s*(?:-\\s+)?[\"'][^\"']*[\"']\\s*:"); + private static final Pattern EXPRESSION = Pattern.compile("\\$\\{\\{.*?}}"); @Override public void apply(Project project) { @@ -95,12 +83,18 @@ public final class StrictLaneStagesPlugin implements Plugin { task -> { task.setGroup("verification"); task.setDescription( - "Fails when a strict lane is in no stage a workflow executes. Run with --dry-run."); + "Fails when a strict lane is in no stage or a stage's workflow job does not" + + " run it. 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()))); + ignored -> + verify.configure( + task -> + extension + .getStages() + .forEach(stage -> task.dependsOn(stage.taskPath())))); project .getGradle() .getTaskGraph() @@ -110,207 +104,275 @@ public final class StrictLaneStagesPlugin implements Plugin { if (!graph.hasTask(task)) { return; } + List stages = extension.getStages(); if (!project.getGradle().getStartParameter().isDryRun()) { throw new GradleException( TASK_NAME + " checks the plan of " - + extension.getStages().get() + + stages.stream().map(StrictLaneStagesExtension.Stage::taskPath).toList() + " 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)); + List problems = new ArrayList<>(laneProblems(project, graph, stages)); + String buildDirectory = buildDirectory(project, workflowDirectory); + boolean selfChecked = false; + for (StrictLaneStagesExtension.Stage stage : stages) { + Path workflow = workflowDirectory.toPath().resolve(stage.workflow()); + problems.addAll(formProblems(workflow, buildDirectory, stage)); + selfChecked |= + stage.event().equals("pull_request") && runs(workflow, stage, SELF_CHECK); + } + if (!selfChecked) { + problems.add( + "no pull_request stage job runs `" + + SELF_CHECK + + "`; without it nothing checks the stages on a pull request"); + } 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 - " + + " problem(s). A lane no stage reaches runs nowhere; put it in a stage, or" + + " declare explicitOnly(\"reason\") if it needs an input no stage has. A" + + " stage job runs `./gradlew ` on a line of its own.\n - " + String.join("\n - ", problems)); } project .getLogger() - .lifecycle( - TASK_NAME + ": every strict lane is in an executed stage."); + .lifecycle(TASK_NAME + ": every strict lane is in a stage its workflow job runs."); }); } - 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)); + private static List laneProblems( + Project root, TaskExecutionGraph graph, List stages) { + Set planned = new HashSet<>(); + for (StrictLaneStagesExtension.Stage stage : stages) { + Task stageTask = root.getTasks().findByPath(stage.taskPath()); + if (stageTask != null) { + planned.addAll(plan(graph, stageTask)); } } - List lanes = new ArrayList<>(); + List problems = new ArrayList<>(); root.getAllprojects().stream() .sorted(Comparator.comparing(Project::getPath)) .forEach( project -> { - StrictTestLaneExtension lanesOf = + StrictTestLaneExtension lanes = project.getExtensions().findByType(StrictTestLaneExtension.class); - if (lanesOf == null) { + if (lanes == null) { return; } - lanesOf.getLanes().stream() + lanes.getLanes().stream() .filter(lane -> lane.getExplicitOnlyReason() == null) .map(lane -> taskPath(project, lane.getName())) .sorted() - .forEach(lanes::add); + .filter(lane -> !planned.contains(lane)) + .forEach( + lane -> + problems.add( + "strict lane " + + lane + + " is in no stage of " + + stages.stream() + .map(StrictLaneStagesExtension.Stage::taskPath) + .toList())); }); - 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; + } + + /** What the stage job must look like; each problem names the file and job. */ + static List formProblems( + Path workflow, String buildDirectory, StrictLaneStagesExtension.Stage stage) { + String file = workflow.getFileName().toString(); + String where = file + " job " + stage.job(); + if (!Files.exists(workflow)) { + return List.of(file + " does not exist; nothing runs " + stage.taskPath()); + } + List lines = read(workflow); + List problems = new ArrayList<>(); + List triggers = block(lines, "on:", 0); + if (!triggers.contains(" " + stage.event() + ":")) { + problems.add(file + " does not start on " + stage.event()); + } else { + List filter = content(block(triggers, " " + stage.event() + ":", 2)); + boolean exact = + stage.event().equals("schedule") + ? !filter.isEmpty() && filter.stream().allMatch(line -> line.startsWith("- cron:")) + : filter.equals(stage.filter() == null ? List.of() : List.of(stage.filter())); + if (!exact) { + problems.add( + file + + " starts on " + + stage.event() + + " only with " + + filter + + "; the build declares " + + (stage.filter() == null ? "no filter" : List.of(stage.filter()))); } } + List defaults = block(lines, "defaults:", 0); + int jobs = lines.indexOf("jobs:"); + List job = + jobs < 0 + ? List.of() + : block(lines.subList(jobs + 1, lines.size()), " " + stage.job() + ":", 2); + if (job.isEmpty()) { + problems.add(where + " does not exist; nothing runs " + stage.taskPath()); + return problems; + } + for (String line : defaults) { + if (line.strip().startsWith("shell:")) { + problems.add(file + " sets a default shell, which can hide every run's result"); + } + } + List directories = new ArrayList<>(defaults); + directories.addAll(job); + for (String line : directories) { + Matcher directory = WORKING_DIRECTORY.matcher(line); + if (directory.matches() && !directory.group(1).equals(buildDirectory)) { + problems.add( + where + + " runs in " + + directory.group(1) + + ", not in this build's directory " + + buildDirectory); + } + } + boolean runsStage = false; + boolean waits = false; + List conditions = new ArrayList<>(); + for (String line : content(job, false)) { + String bare = EXPRESSION.matcher(line).replaceAll(""); + if (bare.contains("{") || bare.contains("}") || QUOTED_KEY.matcher(line).find()) { + problems.add(where + " has `" + line.strip() + "`; write it as a plain block mapping"); + continue; + } + if (ANY_RUN.matcher(line).find()) { + Matcher run = STEP_RUN.matcher(line); + if (!run.matches()) { + problems.add(where + " has `" + line.strip() + "`, which is not a step's command"); + } else if (!GRADLE_LINE.matcher(run.group(1)).matches()) { + problems.add(where + " runs `" + run.group(1) + "`, which is not one ./gradlew line"); + } else { + runsStage |= run.group(1).equals(stage.command()); + } + } + Matcher condition = IF.matcher(line); + if (condition.matches()) { + conditions.add(condition.group(1).length() == 4 ? condition.group(2) : line.strip()); + } + Matcher forbidden = FORBIDDEN_IN_JOB.matcher(line); + if (forbidden.find()) { + problems.add(where + " has " + forbidden.group(1) + ", which can hide its result"); + } + waits |= NEEDS.matcher(line).find(); + } + if (!runsStage) { + problems.add(where + " has no line `run: " + stage.command() + "`"); + } + List expected = stage.condition() == null ? List.of() : List.of(stage.condition()); + if (!conditions.equals(expected)) { + problems.add( + where + + " has the conditions " + + conditions + + "; the build declares " + + (expected.isEmpty() ? "none" : expected)); + } + boolean runsAfterAnything = + stage.condition() != null + && (stage.condition().contains("!cancelled()") + || stage.condition().contains("always()")); + if (waits && !runsAfterAnything) { + problems.add( + where + + " needs other jobs, so a skipped or failed one skips the stage; declare a" + + " condition with !cancelled() or always()"); + } 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); + /** Whether the stage's job has the step {@code run: }. */ + private static boolean runs(Path workflow, StrictLaneStagesExtension.Stage stage, String command) { + if (!Files.exists(workflow)) { + return false; + } + List lines = read(workflow); + int jobs = lines.indexOf("jobs:"); + if (jobs < 0) { + return false; + } + return block(lines.subList(jobs + 1, lines.size()), " " + stage.job() + ":", 2).stream() + .map(STEP_RUN::matcher) + .anyMatch(run -> run.matches() && run.group(1).equals(command)); } - /** The tasks {@code stage} reaches as a command runs it: what its -x removes is cut off. */ - private static Set plan(TaskExecutionGraph graph, Task stage, Set excluded) { + private static List read(Path workflow) { + try { + return Files.readAllLines(workflow, StandardCharsets.UTF_8); + } catch (IOException unreadable) { + throw new UncheckedIOException(unreadable); + } + } + + /** The non-blank, non-comment lines, stripped. */ + private static List content(List lines) { + return content(lines, true).stream().map(String::strip).toList(); + } + + private static List content(List lines, boolean ignored) { + return lines.stream() + .filter(line -> !line.isBlank() && !line.strip().startsWith("#")) + .toList(); + } + + /** + * The lines under {@code header}, a key at {@code indent} spaces, up to the next line at the same + * or a lower indent. Comments and blank lines belong to the block they are in. Job keys are the + * only two-space keys after {@code jobs:} in a workflow, and the first match is the job. + */ + private static List block(List lines, String header, int indent) { + List block = new ArrayList<>(); + boolean inside = false; + for (String line : lines) { + if (!inside) { + inside = line.stripTrailing().equals(header); + continue; + } + String content = line.strip(); + boolean structural = !content.isEmpty() && !content.startsWith("#"); + if (structural && line.length() - line.stripLeading().length() <= indent) { + break; + } + block.add(line); + } + return block; + } + + /** The tasks {@code stage} reaches in this build's plan. */ + private static Set plan(TaskExecutionGraph graph, Task stage) { 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())) { + if (seen.add(task.getPath())) { 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. - */ + /** This build's directory from the repository root, the workflow directory's grandparent. */ private static String buildDirectory(Project root, File workflowDirectory) { - File repository = workflowDirectory.getAbsoluteFile().getParentFile().getParentFile(); + Path repository = workflowDirectory.getAbsoluteFile().toPath().getParent().getParent(); String relative = repository - .toPath() .normalize() .relativize(root.getRootDir().getAbsoluteFile().toPath().normalize()) .toString() .replace(File.separatorChar, '/'); - return WorkflowGradleInvocations.Invocation.normalized(relative); + return relative.isEmpty() ? "." : relative; } private static String taskPath(Project project, String name) { diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TaskSelectors.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TaskSelectors.java deleted file mode 100644 index 6dad58eb..00000000 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TaskSelectors.java +++ /dev/null @@ -1,214 +0,0 @@ -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/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java deleted file mode 100644 index 365d2f31..00000000 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocations.java +++ /dev/null @@ -1,1410 +0,0 @@ -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/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/GradleCommandLineTest.java b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/GradleCommandLineTest.java deleted file mode 100644 index e33291eb..00000000 --- a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/GradleCommandLineTest.java +++ /dev/null @@ -1,162 +0,0 @@ -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/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java index 7a0b09ee..65e726d8 100644 --- a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java +++ b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/StrictLaneStagesFunctionalTest.java @@ -1,31 +1,67 @@ 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 java.util.stream.Stream; 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; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.Arguments; +import org.junit.jupiter.params.provider.MethodSource; /** - * A two-project build: a root that declares stages, and a leaf with strict lanes. The workflows + * A two-project build: a root that declares two 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 = + private static final String PR_WORKFLOW = """ + name: pr + on: + pull_request: + defaults: + run: + working-directory: src jobs: - main: + gradle: + runs-on: ubuntu-latest steps: - - working-directory: src - run: ./gradlew :ci --stacktrace - - working-directory: src - run: ./gradlew :integrationCheck --continue --stacktrace + - uses: actions/checkout@v4 + - run: ./gradlew :ci + - run: ./gradlew :verifyStrictLaneStages --dry-run + """; + private static final String MAIN_WORKFLOW = + """ + name: main + on: + push: + branches: [main] + schedule: + # Nightly. + - cron: "0 19 * * *" + defaults: + run: + working-directory: src + jobs: + build: + runs-on: ubuntu-latest + steps: + - run: ./gradlew :ci + integration: + needs: [build] + if: ${{ !cancelled() }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + # The stage line. + - name: Integration + run: ./gradlew :integrationCheck --continue """; @TempDir Path repository; @@ -35,7 +71,7 @@ class StrictLaneStagesFunctionalTest { void setUp() throws Exception { gradleRoot = repository.resolve("src"); Files.createDirectories(gradleRoot.resolve("leaf/src/test/java")); - Files.createDirectories(repository.resolve(".github/workflows")); + Files.createDirectories(repository.resolve(".gitea/workflows")); Files.writeString( gradleRoot.resolve("settings.gradle"), "rootProject.name = 'fixture'\ninclude 'leaf'\n"); Files.writeString( @@ -45,36 +81,31 @@ class StrictLaneStagesFunctionalTest { tasks.register('ci') { dependsOn ':leaf:check' } tasks.register('integrationCheck') { dependsOn ':leaf:integrationTestLaneCheck' } strictLaneStages { - stage ':ci', ':integrationCheck' - workflowDirectory = layout.projectDirectory.dir('../.github/workflows') + workflowDirectory = layout.projectDirectory.dir('../.gitea/workflows') + stage ':ci', workflow: 'pr.yml', event: 'pull_request', job: 'gradle' + stage ':integrationCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]', + job: 'integration', options: '--continue', condition: '${{ !cancelled() }}' } """); - Files.writeString( - gradleRoot.resolve("leaf/src/test/java/LaneTest.java"), - """ - class LaneTest {} - """); - } - - @Test - @DisplayName("모든 lane이 workflow가 실행하는 단계에 들어 있으면 통과한다") - void passesWhenEveryLaneIsInAnExecutedStage() throws Exception { - // given + Files.writeString(gradleRoot.resolve("leaf/src/test/java/LaneTest.java"), "class LaneTest {}\n"); 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"); + workflow("pr.yml", PR_WORKFLOW); + workflow("main.yml", MAIN_WORKFLOW); } @Test - @DisplayName("어느 단계 집계에도 들지 않는 lane이 있으면 그 lane 이름으로 실패한다") + @DisplayName("모든 lane이 단계에 있고 단계 job이 정해진 모양이면 통과한다") + void passesWhenEveryLaneIsInAStageItsJobRuns() { + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").build(); + + assertThat(result.getOutput()).contains("every strict lane is in a stage its workflow job runs"); + } + + @Test + @DisplayName("① 어느 단계에도 들지 않는 strict lane을 더하면 그 lane 이름으로 실패한다") void failsNamingALaneThatNoStageReaches() throws Exception { // given leafLanes( @@ -82,50 +113,16 @@ class StrictLaneStagesFunctionalTest { 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") + .contains("strict lane :leaf:loadLane is in no stage of [:ci, :integrationCheck]") .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 { @@ -134,625 +131,211 @@ class StrictLaneStagesFunctionalTest { """ lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } lane('sandboxLane') { - integration(); tag = 'sandbox'; description = 'Protected sandbox.' + performance(); 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"); + assertThat(result.getOutput()).contains("every strict lane is in a stage its workflow job runs"); + } + + /** + * Each row changes one workflow so that its stage job could stop running the stage, or stop + * failing when the stage fails, and names the problem the check must report. + */ + static Stream jobsThatMayNotRunTheirStage() { + return Stream.of( + Arguments.of( + "② 단계 줄을 바꿈", + "pr.yml", + "- run: ./gradlew :ci\n", + "- run: ./gradlew :ci -x :leaf:test\n", + "pr.yml job gradle has no line `run: ./gradlew :ci`"), + Arguments.of( + "③ step에 선언하지 않은 if:", + "pr.yml", + " - run: ./gradlew :ci\n", + " - if: github.actor != 'renovate'\n run: ./gradlew :ci\n", + "pr.yml job gradle has the conditions [- if: github.actor != 'renovate']; the build" + + " declares none"), + Arguments.of( + "③ continue-on-error", + "main.yml", + " if: ${{ !cancelled() }}\n", + " if: ${{ !cancelled() }}\n continue-on-error: true\n", + "main.yml job integration has continue-on-error, which can hide its result"), + Arguments.of( + "선언과 다른 job 조건", + "main.yml", + "if: ${{ !cancelled() }}", + "if: ${{ github.event_name == 'never' }}", + "main.yml job integration has the conditions [${{ github.event_name == 'never' }}]"), + Arguments.of( + "건너뛸 수 있는 job을 needs로 기다림", + "pr.yml", + " runs-on: ubuntu-latest\n", + " needs: [lint]\n runs-on: ubuntu-latest\n", + "pr.yml job gradle needs other jobs, so a skipped or failed one skips the stage"), + Arguments.of( + "./gradlew 한 줄이 아닌 run", + "pr.yml", + "- run: ./gradlew :verifyStrictLaneStages --dry-run\n", + "- run: ./gradlew :verifyStrictLaneStages --dry-run\n - run: exit 0\n", + "pr.yml job gradle runs `exit 0`, which is not one ./gradlew line"), + Arguments.of( + "셸로 이은 명령", + "pr.yml", + "- run: ./gradlew :verifyStrictLaneStages --dry-run\n", + "- run: ./gradlew :verifyStrictLaneStages --dry-run\n" + + " - run: ./gradlew help; rm -rf leaf\n", + "pr.yml job gradle runs `./gradlew help; rm -rf leaf`, which is not one ./gradlew line"), + Arguments.of( + "step 명령이 아닌 자리의 run:", + "pr.yml", + " - run: ./gradlew :ci\n", + " - uses: ./setup\n with:\n run: ./gradlew :ci\n", + "pr.yml job gradle has `run: ./gradlew :ci`, which is not a step's command"), + Arguments.of( + "따옴표 친 키", + "pr.yml", + " runs-on: ubuntu-latest\n", + " \"if\": false\n runs-on: ubuntu-latest\n", + "pr.yml job gradle has `\"if\": false`; write it as a plain block mapping"), + Arguments.of( + "flow 형식 step", + "pr.yml", + " - uses: actions/checkout@v4\n", + " - uses: actions/checkout@v4\n - { run: \"git rm -rq leaf\" }\n", + "pr.yml job gradle has `- { run: \"git rm -rq leaf\" }`; write it as a plain block"), + Arguments.of( + "step의 shell:", + "pr.yml", + " - run: ./gradlew :ci\n", + " - run: ./gradlew :ci\n shell: python\n", + "pr.yml job gradle has shell, which can hide its result"), + Arguments.of( + "workflow 기본 shell", + "pr.yml", + " working-directory: src\n", + " working-directory: src\n shell: true {0}\n", + "pr.yml sets a default shell, which can hide every run's result"), + Arguments.of( + "job 단위 defaults", + "pr.yml", + " runs-on: ubuntu-latest\n", + " runs-on: ubuntu-latest\n defaults:\n run:\n working-directory: src\n", + "pr.yml job gradle has defaults, which can hide its result"), + Arguments.of( + "경로 필터", + "pr.yml", + " pull_request:\n", + " pull_request:\n paths-ignore: ['docs/**']\n", + "pr.yml starts on pull_request only with [paths-ignore: ['docs/**']]; the build declares" + + " no filter"), + Arguments.of( + "pull request 종류 필터", + "pr.yml", + " pull_request:\n", + " pull_request:\n types: [closed]\n", + "pr.yml starts on pull_request only with [types: [closed]]"), + Arguments.of( + "잘못 쓴 브랜치", + "main.yml", + "branches: [main]", + "branches: [mian]", + "main.yml starts on push only with [branches: [mian]]; the build declares" + + " [branches: [main]]"), + Arguments.of( + "선언한 이벤트가 없음", + "pr.yml", + " pull_request:\n", + " workflow_dispatch:\n", + "pr.yml does not start on pull_request"), + Arguments.of( + "workflow 기본 폴더가 다른 빌드", + "pr.yml", + "working-directory: src", + "working-directory: src/other", + "pr.yml job gradle runs in src/other, not in this build's directory src"), + Arguments.of( + "step 폴더가 다른 빌드", + "main.yml", + " - name: Integration\n", + " - name: Integration\n working-directory: other\n", + "main.yml job integration runs in other, not in this build's directory src"), + Arguments.of( + "이 검사를 PR에서 돌리지 않음", + "pr.yml", + " - run: ./gradlew :verifyStrictLaneStages --dry-run\n", + "", + "no pull_request stage job runs `./gradlew :verifyStrictLaneStages --dry-run`"), + Arguments.of( + "jobs 밖에 같은 이름의 미끼", + "pr.yml", + "jobs:\n gradle:\n", + " gradle:\n steps:\n - run: ./gradlew :ci\njobs:\n build:\n", + "pr.yml job gradle does not exist; nothing runs :ci")); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("jobsThatMayNotRunTheirStage") + @DisplayName("단계를 조용히 돌리지 않을 수 있는 job은 그 workflow·job과 이유로 실패한다") + void failsOnAJobThatMayNotRunItsStage( + String change, String file, String from, String to, String problem) throws Exception { + // given + String original = Files.readString(repository.resolve(".gitea/workflows").resolve(file)); + assertThat(original).as("fixture for %s", change).contains(from); + workflow(file, original.replace(from, to)); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()).contains(problem); + } + + @Test + @DisplayName("단계 workflow 파일이나 job이 없으면 실패한다") + void failsWhenTheStageJobIsMissing() throws Exception { + // given + Files.delete(repository.resolve(".gitea/workflows/main.yml")); + workflow("pr.yml", PR_WORKFLOW.replace(" gradle:\n", " build:\n")); + + // when + BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("main.yml does not exist; nothing runs :integrationCheck") + .contains("pr.yml job gradle does not exist; nothing runs :ci"); } @Test @DisplayName("--dry-run 없이 부르면 모든 단계를 실행하게 되므로 시작 전에 거절한다") - void refusesToRunWithoutDryRun() throws Exception { - // given - leafLanes( - """ - lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' } - """); - workflow(EXECUTING_WORKFLOW); - - // when + void refusesToRunWithoutDryRun() { 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 { + @DisplayName("단계 줄의 옵션이 정해진 것 밖이면 설정 단계에서 거절한다") + void refusesAStageOptionThatChangesWhatRuns() 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 - """); + Files.readString(gradleRoot.resolve("build.gradle")) + .replace("options: '--continue'", "options: '--continue -x :leaf:test'")); // 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"); + assertThat(result.getOutput()).contains("stage :integrationCheck: option -x is not one of"); } private void leafLanes(String lanes) throws Exception { @@ -770,8 +353,8 @@ class StrictLaneStagesFunctionalTest { .formatted(lanes)); } - private void workflow(String content) throws Exception { - Files.writeString(repository.resolve(".github/workflows/main.yml"), content); + private void workflow(String name, String content) throws Exception { + Files.writeString(repository.resolve(".gitea/workflows").resolve(name), content); } private GradleRunner runner(String... args) { diff --git a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/TaskSelectorsTest.java b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/TaskSelectorsTest.java deleted file mode 100644 index 76a189dc..00000000 --- a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/TaskSelectorsTest.java +++ /dev/null @@ -1,71 +0,0 @@ -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/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java deleted file mode 100644 index ab24e44b..00000000 --- a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/strictlane/WorkflowGradleInvocationsTest.java +++ /dev/null @@ -1,1581 +0,0 @@ -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/src/build.gradle b/src/build.gradle index 8e15f199..af30c4a4 100644 --- a/src/build.gradle +++ b/src/build.gradle @@ -18,7 +18,8 @@ plugins { // and archive hygiene is gone with the revision it cleaned out of every leaf's jar name (review // 2026-09-24 BUILD-O3-5). id 'ca.architecture' - // Every strict lane belongs to a stage a workflow executes (review 2026-11-01 08-01). + // Every strict lane belongs to a stage, and each stage's workflow job runs it (review + // 2026-11-01 08-01). id 'ca.strict-lane-stages' } @@ -65,7 +66,9 @@ tasks.register('verifyDependencyLocks') { // check every leaf's check (Gradle matches the name across projects) // architectureCheck dependency direction + purity + app-bootstrap whole-repository ArchUnit // qualityCheck SpotBugs + FindSecBugs across every leaf (ca.quality-conventions) -// ci the pull-request gate: leaf checks + architectureCheck + qualityCheck +// ci leaf checks + architectureCheck + qualityCheck +// prCheck the pull-request stage: ci + dependency locks + the Compose render, the +// repository layout and the document checks (scripts outside Gradle) // mainCheck the main-branch stage: environment contract, full-boot qualification, // public-path baseline, transport and messaging qualification lanes, each // leaf's document-contract lanes, and the feature generator round trip @@ -104,7 +107,7 @@ tasks.register('integrationCheck') { } // Performance lanes are not the pull request's or the main stage's: their bounds need a machine that -// is not compiling something else. integration-main.yml runs this aggregate on main and nightly. +// is not compiling something else. main.yml runs this aggregate nightly, after its other jobs. tasks.register('performanceCheck') { group = 'verification' description = "Runs every production CI leaf's performance-category test lanes. Several need a container runtime." @@ -190,14 +193,63 @@ tasks.register('mainCheck') { dependsOn tasks.named('verifyFeatureScaffold') } -// The stages a strict lane may belong to. `verifyStrictLaneStages --dry-run` (pull-request gate) -// fails when a strict lane that is not `explicitOnly` is in the plan of none of these, or when a -// stage is executed by no workflow — the gap that left fourteen lanes running nowhere while each -// one failed closed (review 2026-11-01 08-01). A new lane joins a stage through its category -// aggregate; no workflow line names it. +// The checks outside Gradle that the pull-request stage runs. Each is a script with its own tests +// (scripts/tests); these tasks only give them a stage, so pr.yml and scripts/verify.sh run the same +// one line. Repository root as working directory: that is where the scripts expect to start. +def repositoryRoot = rootProject.projectDir.parentFile +tasks.register('verifyComposeProfiles', Exec) { + group = 'verification' + description = 'Renders every Compose lane and checks it renders exactly what it declares.' + workingDir = repositoryRoot + commandLine 'bash', 'scripts/verify-compose-profile-contracts.sh' +} +tasks.register('verifyRepositoryLayout', Exec) { + group = 'verification' + description = 'Refuses a top-level entry of the repository or src/ outside the allow list.' + workingDir = repositoryRoot + commandLine 'python3', 'scripts/check-repo-layout.py' +} +tasks.register('testDocumentChecks', Exec) { + group = 'verification' + description = 'Runs the tests of the scripts outside Gradle (document checker, hooks, ledger).' + workingDir = repositoryRoot + commandLine 'python3', '-m', 'unittest', 'discover', '-s', 'scripts/tests' +} +tasks.register('documentCheck', Exec) { + group = 'verification' + description = 'Checks living documents: language, head blocks, references, numbers, links, style.' + workingDir = repositoryRoot + commandLine 'python3', 'scripts/check-docs.py' + dependsOn tasks.named('testDocumentChecks') +} + +tasks.register('prCheck') { + group = 'verification' + description = 'The pull-request stage: ci, dependency locks, the Compose render, the layout and the documents.' + dependsOn tasks.named('ci') + dependsOn tasks.named('verifyDependencyLocks') + dependsOn tasks.named('verifyComposeProfiles') + dependsOn tasks.named('verifyRepositoryLayout') + dependsOn tasks.named('documentCheck') +} + +// The stages a strict lane may belong to, and the one workflow job that runs each. +// `verifyStrictLaneStages --dry-run` (pull-request stage) fails when a strict lane that is not +// `explicitOnly` is in the plan of none of them — the gap that left fourteen lanes running nowhere +// while each one failed closed (review 2026-11-01 08-01) — or when a stage job is not the line +// `./gradlew ` under the declared event and condition. A new lane joins a stage +// through its category aggregate; no workflow line names it. The performance lane runs only +// nightly, after the other heavy jobs, on a runner nothing else is using (owner decision 2026-11-07). strictLaneStages { - stage ':ci', ':mainCheck', ':integrationCheck', ':performanceCheck', ':releaseCheck' - workflowDirectory = layout.projectDirectory.dir('../.github/workflows') + workflowDirectory = layout.projectDirectory.dir('../.gitea/workflows') + stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle' + stage ':mainCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]', job: 'main', + options: '--continue' + stage ':integrationCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]', job: 'integration', + options: '--continue' + stage ':performanceCheck', workflow: 'main.yml', event: 'schedule', job: 'performance', options: '--continue', + condition: '${{ !cancelled() && github.event_name != \'push\' }}' + stage ':releaseCheck', workflow: 'release.yml', event: 'push', filter: 'tags: ["v*"]', job: 'release' } // The deny-by-default public path baseline: app-bootstrap's approval-test lane under its old name. diff --git a/src/composition/fileserver-platform/build.gradle b/src/composition/fileserver-platform/build.gradle index d800fec8..7a305eb5 100644 --- a/src/composition/fileserver-platform/build.gradle +++ b/src/composition/fileserver-platform/build.gradle @@ -70,7 +70,7 @@ def repositoryRoot = rootProject.projectDir.parentFile tasks.named('test') { inputs.dir(new File(repositoryRoot, 'docs/fileserver')).withPropertyName('fileserverDocuments') .withPathSensitivity(PathSensitivity.RELATIVE) - inputs.dir(new File(repositoryRoot, '.github/workflows')).withPropertyName('workflows') + inputs.dir(new File(repositoryRoot, '.gitea/workflows')).withPropertyName('workflows') .withPathSensitivity(PathSensitivity.RELATIVE) inputs.files(['application-fileserver', 'adapter/inbound/web-fileserver', 'adapter/outbound/fileserver', 'adapter/outbound/persistence-fileserver', 'composition/fileserver-platform'] diff --git a/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java b/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java index 9c18cd10..8d14063e 100644 --- a/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java +++ b/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java @@ -34,7 +34,7 @@ import org.springframework.core.env.StandardEnvironment; */ class FileserverDocumentationCoverageTest { - private static final String WORKFLOWS = ".github/workflows"; + private static final String WORKFLOWS = ".gitea/workflows"; private static final Pattern EVIDENCE = Pattern.compile("`([^`]+)`"); private static final Pattern CI_JOB = Pattern.compile("fileserver-[a-z0-9-]+"); private static final Pattern TEST_TASK = Pattern.compile("(:[a-z0-9:-]+):test"); diff --git a/src/gradle.properties b/src/gradle.properties index c447eaa6..74149dd4 100644 --- a/src/gradle.properties +++ b/src/gradle.properties @@ -20,7 +20,7 @@ org.gradle.parallel=true # `resolveAndLockAll`), which is `notCompatibleWithConfigurationCache`. Resolving every # configuration at execution time is not an implementation detail of that task, it is the task: # STRICT lock validation happens during resolution, so moving it behind a provider would move lock -# verification into every build's configuration phase. Because the pull-request gate runs `:ci` and +# verification into every build's configuration phase. Because the pull-request stage runs `:ci` and # `:verifyDependencyLocks` in one invocation, turning the flag on repository-wide would discard the # entry for that invocation anyway. Enabling it is therefore a change to how CI is split, not a -# property — and `.github/workflows/ci-quality-gates.yml` proves the storable half on every PR. +# property — and scripts/ci/verify-configuration-cache.sh (main.yml) proves the storable half. diff --git a/src/gradle/libs.versions.toml b/src/gradle/libs.versions.toml index fd868f6d..576784c3 100644 --- a/src/gradle/libs.versions.toml +++ b/src/gradle/libs.versions.toml @@ -147,7 +147,7 @@ toxiproxy-java = { module = "eu.rekawek.toxiproxy:toxiproxy-java", version.ref = uuid-creator = { module = "com.github.f4b6a3:uuid-creator", version.ref = "uuidCreator" } # Pinned: libraries no leaf declares, whose upstream still brings a version with a High or Critical -# advisory (the trivy gate in dependency-vulnerability.yml). Not for a leaf to depend on: build-logic's +# advisory (the trivy gate, scripts/ci/trivy-scan.sh). Not for a leaf to depend on: build-logic's # JavaConventionsPlugin pins every `pinned-*` entry, through Spring dependency management, in every # configuration of every leaf — the Checkstyle and Error Prone classpaths included. The version's # comment names the advisory and the upstream; delete the entry once every upstream named there From a2dfefb6ded31668fae9e5b7550eb998d2959b2a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 21:59:19 +0900 Subject: [PATCH 05/10] =?UTF-8?q?docs(operate):=20=EB=A6=B4=EB=A6=AC?= =?UTF-8?q?=EC=8A=A4=20secret=20=EC=85=8B=EC=9D=84=20=EB=A7=8C=EB=93=9C?= =?UTF-8?q?=EB=8A=94=20=EB=B2=95=EC=9D=84=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit release.yml이 태그에서 이미지를 올리고 서명하려면 repo secret PACKAGE_TOKEN·COSIGN_PRIVATE_KEY·COSIGN_PASSWORD가 필요하다. 이름만 있고 만드는 법이 없어 소유자가 첫 릴리스 전에 찾아야 했다. operate.md 4.3절에 각 값의 출처(개인 access token의 package 범위, cosign generate-key-pair의 cosign.key와 비밀번호)와 공개 키를 어디에 주는지 적는다. 검증: python3 scripts/check-docs.py, check-work-docs.py 통과. --- docs/work/operate.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/work/operate.md b/docs/work/operate.md index 78f08c7a..d6abc978 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -104,7 +104,10 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' - 릴리스는 `v*` 태그 push로 시작한다(`.gitea/workflows/release.yml`). 태그와 push는 소유자가 한다. - 태그 전에 그 커밋에서 `scripts/verify.sh release`를 돌리고, `release.yml`을 손으로 실행(`workflow_dispatch`)해 리허설한다. 손으로 실행하면 모든 release lane, 이미지 빌드, SBOM, 이미지 검사까지 돌고 push·서명은 하지 않는다. - 태그는 PR 단계와 main 단계를 이미 통과한 main 커밋에서 자른다. 그래서 `releaseCheck`는 `ci`를 다시 돌리지 않는다. -- 이미지는 이 Gitea의 컨테이너 레지스트리(`<서버>/<소유자>/caskeleton`)에 올리고, digest를 cosign 키 쌍으로 서명한다(소유자 결정 2026-11-07: Gitea는 keyless 서명에 필요한 OIDC 토큰을 주지 않는다). repo secret `PACKAGE_TOKEN`·`COSIGN_PRIVATE_KEY`·`COSIGN_PASSWORD`는 소유자가 만든다. 서명 job은 확인에 쓴 공개 키를 로그에 남긴다. 배포 쪽 admission 정책은 그 공개 키로 확인한다. +- 이미지는 이 Gitea의 컨테이너 레지스트리(`<서버>/<소유자>/caskeleton`)에 올리고, digest를 cosign 키 쌍으로 서명한다(소유자 결정 2026-11-07: Gitea는 keyless 서명에 필요한 OIDC 토큰을 주지 않는다). repo secret 셋은 소유자가 만든다(repo 설정 → Actions → Secrets). + - `PACKAGE_TOKEN`: 소유자 계정의 개인 access token, 범위는 package 읽기·쓰기(사용자 설정 → Applications). job 토큰은 package를 올릴 수 없다. + - `COSIGN_PRIVATE_KEY`·`COSIGN_PASSWORD`: 노트북에서 `cosign generate-key-pair`로 만든 `cosign.key`의 내용 전체와 그때 넣은 비밀번호. `cosign.pub`는 배포 쪽 admission 정책에 준다. `cosign.key`는 secret에 넣은 뒤 지운다. + - 서명 job은 확인에 쓴 공개 키를 로그에 남긴다. 그것이 `cosign.pub`와 같은지 첫 릴리스에서 본다. ### 4.4 파생 서비스에 템플릿 변경 넘기기 From d0c3f91a3b92333042dc84b84ee77130eb0cf3c5 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 22:32:16 +0900 Subject: [PATCH 06/10] =?UTF-8?q?docs:=20=EB=B9=84=EC=A0=84=EA=B3=BC=20?= =?UTF-8?q?=EB=AC=B8=EC=A0=9C=20=EC=A0=95=EC=9D=98=EC=9D=98=20=EB=B9=88=20?= =?UTF-8?q?=EC=96=91=EC=8B=9D=EC=9D=84=20=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 하네스 설계(design-docs harness/01-harness-design.md)는 검증 진입점 scripts/verify.sh와 비전 문서 docs/vision.md가 함께 생긴다고 했다. verify.sh는 이 브랜치가 만들었는데 비전과 문제 정의 자리가 없었다. claude-harness template/docs의 두 양식을 옮긴다. vision.md는 세 문장 자리만 두고 소유자가 쓴다(에이전트는 읽기만 한다). problem-statement.md는 고객의 말 그대로·지금 버티는 법·하지 않는 것·잴 수 있는 성공 기준 칸을 둔다. AGENTS.md 첫 문단과 docs/README.md 「폴더 밖 문서」가 두 파일을 가리킨다. 검증: python3 scripts/check-docs.py, check-work-docs.py 통과. --- AGENTS.md | 2 +- docs/README.md | 2 ++ docs/problem-statement.md | 34 ++++++++++++++++++++++++++++++++++ docs/vision.md | 10 ++++++++++ 4 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 docs/problem-statement.md create mode 100644 docs/vision.md diff --git a/AGENTS.md b/AGENTS.md index 6b3587d5..5915582a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md — 백엔드 템플릿의 정본 -Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `src/gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다. +Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `src/gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다. 비전 전문은 `docs/vision.md`(소유자가 쓴다), 문제 정의는 `docs/problem-statement.md`다. ## HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다 diff --git a/docs/README.md b/docs/README.md index 21489589..4ba6ed42 100644 --- a/docs/README.md +++ b/docs/README.md @@ -100,6 +100,8 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 | --- | --- | | [capability-status.md](capability-status.md) | capability마다 코드가 있나·조립되나·실제 제공자로 검증됐나, 그리고 지운 코드의 표(「제거된 코드」) | | [storage-capability-boundary.md](storage-capability-boundary.md) | 파일 서버와 객체 저장소가 각각 맡는 경계 | +| [vision.md](vision.md) | 비전: 누구의 어떤 문제를 푸나, 성공하면 무엇이 달라지나, 속도보다 먼저 지킬 것(세 문장, 소유자가 쓴다. 에이전트는 읽기만 한다) | +| [problem-statement.md](problem-statement.md) | 문제 정의: 고객의 말 그대로, 지금 버티는 법, 하지 않는 것, 잴 수 있는 성공 기준 | ## 문서 수명과 언어 diff --git a/docs/problem-statement.md b/docs/problem-statement.md new file mode 100644 index 00000000..3889b7ac --- /dev/null +++ b/docs/problem-statement.md @@ -0,0 +1,34 @@ +# 문제 정의 — clean-architecture-backend-template + +> 아이디어가 아니라 고객의 문제에서 출발한다. 좋은 스펙은 헷갈리지 않게 하는 스펙이다. +> 바뀌면 고친다(살아 있는 문서). 왜 바꿨는지는 커밋 본문이나 결정 기록에 남긴다. + +## 고객의 말 그대로 + +- (채울 것: 고객이 실제로 한 말을 따옴표로. 해석하지 않는다) + +## 지금은 어떻게 버티나 + +- (채울 것: 고객이 지금 쓰는 우회 방법과 그 비용) + +## 하지 않는 것 + +- (채울 것: 이번에 일부러 풀지 않는 문제, 만들지 않는 기능) + +## 성공 기준 + +| 기준 | 구체적으로 | 어떻게 재나 | 목표 값 | 기한 | +|---|---|---|---|---| +| (채울 것) | | | | | + +## 세 관점 점검 + +| 관점 | 묻는 것 | 답 | +|---|---|---| +| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | (채울 것) | +| 기술 | 만들 수 있나, 가장 위험한 가정은 | (채울 것) | +| 고객 | 쓸모 있나, 지금 방법보다 나은가 | (채울 것) | + +## 되돌릴 수 없는 결정 + +- (채울 것: 되돌리기 비싼 결정만 여기 적고 `docs/adr/`에 결정 기록을 남긴다. 되돌릴 수 있는 결정은 빨리 한다) diff --git a/docs/vision.md b/docs/vision.md new file mode 100644 index 00000000..4f1fa798 --- /dev/null +++ b/docs/vision.md @@ -0,0 +1,10 @@ +# 비전 — clean-architecture-backend-template + +> 소유자가 직접 쓴다. AI에게 맡기지 않는다. 방향·목적·철학만, 길어야 세 문장이다. +> 에이전트는 이 문서를 읽기만 한다. 고칠 일이 보이면 제안만 한다. + +1. 누구의 어떤 문제를 푸는가: (채울 것) +2. 성공하면 무엇이 달라지나(잴 수 있게): (채울 것) +3. 속도보다 먼저 지킬 것: (채울 것) + +점검 질문: 이 목표를 다 이뤘는데도 실패한다면 무엇 때문일까? 그 답이 빠진 목표다. From b0bca2a62ae9f6f7908b31189875202fac243eef Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 23:52:07 +0900 Subject: [PATCH 07/10] =?UTF-8?q?fix(websocket):=20Nginx=20lane=EC=9D=B4?= =?UTF-8?q?=20job=20=EC=BB=A8=ED=85=8C=EC=9D=B4=EB=84=88=20=EC=95=88?= =?UTF-8?q?=EC=9D=98=20=EC=95=B1=EC=97=90=EB=8F=84=20=EB=8B=BF=EA=B2=8C=20?= =?UTF-8?q?=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit websocketNginxTest의 Nginx 컨테이너는 host.docker.internal을 host-gateway(Docker 호스트)로 풀어 시험 JVM의 앱에 붙었다. desktop에서는 Docker 호스트가 곧 JVM의 호스트라 됐지만, Gitea runner처럼 job이 자기 컨테이너 안에서 돌면 앱은 거기 없다. release 수동 실행(run 51)의 websocket-stable-release-gate가 upgrade마다 DeploymentException으로 실패했다. Testcontainers의 호스트 포트 노출(exposeHostPorts, withAccessToHost)로 host.testcontainers.internal을 이 JVM으로 잇는다. 두 환경에서 같은 이름이다. 버린 것: runner 설정을 host 네트워크로 바꾸기(platform-core 몫, job 격리를 푼다). 위험: Testcontainers가 sshd 보조 컨테이너를 하나 더 띄운다(이미지는 Testcontainers가 고정한 것, container-images.properties 밖). 검증: desktop에서 :adapter:inbound:websocket:websocketNginxTest. --- .../websocket/proxy/NginxWebSocketHarness.java | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/adapter/inbound/websocket/src/nginxWebSocketTest/java/dev/caskeleton/adapter/inbound/websocket/proxy/NginxWebSocketHarness.java b/src/adapter/inbound/websocket/src/nginxWebSocketTest/java/dev/caskeleton/adapter/inbound/websocket/proxy/NginxWebSocketHarness.java index 70c8859b..3f1173ed 100644 --- a/src/adapter/inbound/websocket/src/nginxWebSocketTest/java/dev/caskeleton/adapter/inbound/websocket/proxy/NginxWebSocketHarness.java +++ b/src/adapter/inbound/websocket/src/nginxWebSocketTest/java/dev/caskeleton/adapter/inbound/websocket/proxy/NginxWebSocketHarness.java @@ -30,12 +30,15 @@ public final class NginxWebSocketHarness implements AutoCloseable { */ @SuppressWarnings("resource") public NginxWebSocketHarness(int applicationPort, String configurationResource) { + // The application listens in this JVM's network, which a container reaches by name only through + // Testcontainers' host-port tunnel. `host-gateway` was the Docker host, which is this JVM's host + // on a workstation but not on a CI runner whose job runs in a container of its own (the Gitea + // runner): there Nginx reached nothing and every upgrade failed as a deployment error. + org.testcontainers.Testcontainers.exposeHostPorts(applicationPort); this.nginx = new GenericContainer<>(IMAGE) .withExposedPorts(8080) - // host.docker.internal is not resolvable on stock Linux Docker; without the gateway - // the container fails with a connection refused that reads as a config error. - .withExtraHost("host.docker.internal", "host-gateway") + .withAccessToHost(true) .withCopyToContainer( Transferable.of(configuration(configurationResource, applicationPort)), "/etc/nginx/nginx.conf"); @@ -68,7 +71,7 @@ public final class NginxWebSocketHarness implements AutoCloseable { throw new IllegalStateException(resource + " is missing from the lane's resources"); } return new String(stream.readAllBytes(), StandardCharsets.UTF_8) - .replace("APPLICATION_HOST", "host.docker.internal") + .replace("APPLICATION_HOST", "host.testcontainers.internal") .replace("APPLICATION_PORT", Integer.toString(applicationPort)); } catch (IOException e) { throw new IllegalStateException(resource + " could not be read", e); From 74b0599f12c9a5fe1c2e0bdc71e406b834277a40 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Mon, 9 Nov 2026 06:56:38 +0900 Subject: [PATCH 08/10] =?UTF-8?q?fix(ci):=20Redis=20topology=20=EC=8A=A4?= =?UTF-8?q?=ED=81=AC=EB=A6=BD=ED=8A=B8=EA=B0=80=20=EB=8D=B0=EB=AA=AC=20?= =?UTF-8?q?=ED=98=B8=EC=8A=A4=ED=8A=B8=20=EC=A3=BC=EC=86=8C=EB=A5=BC=20?= =?UTF-8?q?=EB=B0=94=EB=A5=B4=EA=B2=8C=20=EC=9D=BD=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit redis-topology.sh는 job 컨테이너의 기본 게이트웨이(=Docker 데몬 호스트)를 /proc/net/route에서 awk로 읽었다. awk는 "0x.." 문자열을 0으로 읽어 주소가 0.0.0.0이 됐고, 포워더가 자기 자신에게 이어 붙어 "Too many open files"로 main.yml 수동 실행(run 52)의 redis-topology 11행이 모두 실패했다. python3로 little-endian 16진수를 바르게 바꾸고, 주소가 없거나 0.0.0.0이면 그 자리에서 실패한다. 검증: 노트북에서 같은 계산이 기본 게이트웨이를 낸다. runner 재실행은 다음 main.yml 수동 실행에서. --- scripts/ci/redis-topology.sh | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/scripts/ci/redis-topology.sh b/scripts/ci/redis-topology.sh index 0a929343..24df7f82 100755 --- a/scripts/ci/redis-topology.sh +++ b/scripts/ci/redis-topology.sh @@ -41,7 +41,16 @@ REDIS_VERSION=${version} "${compose[@]}" up -d --wait # the lanes are built around localhost (cluster redirects announce 127.0.0.1, the TLS certificate # names localhost). Forward them, so the lane runs exactly as it does on a workstation. if [ -f /.dockerenv ]; then - daemon_host=$(awk '$2 == "00000000" { printf "%d.%d.%d.%d\n", "0x" substr($3,7,2), "0x" substr($3,5,2), "0x" substr($3,3,2), "0x" substr($3,1,2); exit }' /proc/net/route) + # The default gateway of the job's network is the daemon host. /proc/net/route stores it as + # little-endian hex; awk reads "0x.." as 0 and would point the forwarder at itself. + daemon_host=$(python3 -c 'import socket, struct +for line in open("/proc/net/route").readlines()[1:]: + fields = line.split() + if fields[1] == "00000000": + print(socket.inet_ntoa(struct.pack("&2; exit 1; } python3 scripts/ci/forward-ports.py "${daemon_host}" "${ports[@]}" & forwarder=$! sleep 1 From 78cbc865f3bf5bcf06e5ae643c2de742f3c40401 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Mon, 9 Nov 2026 06:56:44 +0900 Subject: [PATCH 09/10] =?UTF-8?q?docs(ledger):=20CI=20=EC=9E=AC=ED=8E=B8?= =?UTF-8?q?=20=EC=9E=91=EC=97=85=EC=9D=98=20=EC=98=88=EC=B8=A1=C2=B7?= =?UTF-8?q?=EC=8B=A4=EC=B8=A1=EA=B3=BC=20=ED=95=98=EB=84=A4=EC=8A=A4=20?= =?UTF-8?q?=ED=9A=8C=EA=B3=A0=20=EC=A4=84=EC=9D=84=20=EB=82=A8=EA=B8=B4?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit t2a-backend-ci의 착수 예측(p30·p50·p80)과 실측(작업 중 132분, 호출 374, 출력 37.5만, 벽시계 849분)을 더한다. 하네스 회고(claude-harness docs/retro/2026-11-08.md 7절)가 정한 retro 줄 셋(h3·x2·x3)을 ledger.py append로 더한다. 이미 있던 줄은 고치지 않았다. --- docs/ledger/estimates.jsonl | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/ledger/estimates.jsonl b/docs/ledger/estimates.jsonl index e3638e1b..05613f66 100644 --- a/docs/ledger/estimates.jsonl +++ b/docs/ledger/estimates.jsonl @@ -4,3 +4,8 @@ {"schema": 1, "kind": "actual", "task": "x2-grpc-library", "recorded_at": "2026-11-08T14:02+09:00", "transcript": "dc504d75-c815-4dfa-98dd-80c224db983f", "minutes": 194, "active_minutes": 99, "calls": 330, "output_tokens": 303528, "cache_read_tokens": 136483127, "max_context": 746863, "within": "p30", "result": "done", "commits": ["5e204e6a", "2921f596", "91804ec1", "57988c2e", "grpc-library:76a9244", "grpc-library:414666c", "grpc-library:41d73a1", "grpc-library:239547b", "grpc-library:90306b2", "grpc-library:8d705bc", "grpc-library:ce83f4d", "grpc-library:39d4b6d", "grpc-library:c10f4af"], "why": "모든 값이 p30보다 작았다(작업 중 99분, 벽시계 194분). 예측은 desktop 대기(템플릿 게이트 1회차 약 65분, 라이브러리 반복 6회, 재실행 3회)를 작업 중 시간에 넣었는데, 대기는 빈틈마다 5분으로 잘리고 그동안 문서·라이브러리 일을 같이 했다. 패키지 이름 바꾸기 315파일, SpotBugs 제외 정리, 템플릿 삭제 397파일을 스크립트 몇 번으로 끝내 결정 수(약 35) 대비 호출이 적었다. 다음 예측은 desktop 대기를 시간에서 빼고 결정 수와 실행 횟수만으로 잡는다. 라이브러리 PR #1 병합은 권한 분류기에 막혀 남았다"} {"schema": 1, "kind": "estimate", "task": "x3-messaging-library", "recorded_at": "2026-11-08T16:00+09:00", "transcript": "462a3688-07fc-4460-a565-62afcf6ae072", "started_at": "2026-11-08T15:55:32+09:00", "base": "2959eff0", "task_kind": "improve", "size": "large", "minutes": {"p30": 140, "p50": 200, "p80": 300}, "calls": {"p30": 420, "p50": 580, "p80": 850}, "output_tokens": {"p30": 450000, "p50": 650000, "p80": 950000}, "basis": "착수 노트(공유 노트 x3-messaging-library.md, 16:00)에 쓴 값을 옮겼다. 선례 x2-grpc-library 1차(만들기~PR) 작업 중 99분·호출 330·출력 30.4만, 결정 약 35. 이번은 결정 약 45로 봤다: gRPC 결정(배치·build-logic·배포·workflow)은 본보기를 따르면 되지만 템플릿에 소비자가 있어 좌표 전환 4 leaf, migration 결합, 계약 테스트 나누기, registry 「허용 라이브러리」 칸(build-logic 변경과 시험), lockfile, Kafka 인증 lane의 runner 실행이 새로 붙는다. desktop 실행은 라이브러리 4~6회 + 템플릿 게이트 묶음 2~3회 + runner 3회 이상. desktop 대기는 시간에서 뺐다(x2 회고)"} {"schema": 1, "kind": "actual", "task": "x3-messaging-library", "recorded_at": "2026-11-08T22:00+09:00", "transcript": "462a3688-07fc-4460-a565-62afcf6ae072", "minutes": 361, "active_minutes": 110, "calls": 346, "output_tokens": 271613, "cache_read_tokens": 177759293, "max_context": 820126, "within": "p30", "result": "done", "commits": ["77b81811", "5af94155", "7dc5725f", "messaging-library:f593229", "messaging-library:2e9298e", "messaging-library:f076f6a", "messaging-library:2e7e073", "messaging-library:dd19478", "messaging-library:d2bacc6", "messaging-library:31c5178"], "why": "모든 값이 p30보다 작았다(작업 중 110분, 벽시계 361분). 벽시계의 큰 몫은 기다림이었다: 총괄의 PR #1 병합·태그·release(약 50분), 템플릿 게이트 묶음(17:12~20:12, 공유 잠금 대기 포함), 노트북 네트워크 끊김(17:30~21:50). 작업 중 시간은 빈틈마다 5분으로 잘려 그 대기가 거의 빠졌다. 본보기(grpc-library)의 build-logic·workflow·release 스크립트를 복사하고 이름 바꾸기·삭제·SpotBugs 정리를 스크립트로 해 결정 수(약 45) 대비 호출이 적었다. 예측에 없던 일: 구조 리뷰가 찾은 system caller 규칙 결함(MessageHandler가 프로젝트 밖 타입이 됨)과 순서 시험 두 개. 다음 예측은 소비자가 있는 분리면 「리뷰가 찾는 규칙 결함」 1~2건 몫을 더한다"} +{"schema": 1, "kind": "estimate", "task": "t2a-backend-ci", "recorded_at": "2026-11-08T16:55+09:00", "transcript": "9946b681-b5db-4c9f-898d-9e09bfdf14a2", "started_at": "2026-11-08T16:47+09:00", "base": "2959eff0", "task_kind": "improve", "size": "large", "minutes": {"p30": 180, "p50": 260, "p80": 380}, "calls": {"p30": 450, "p50": 650, "p80": 950}, "output_tokens": {"p30": 450000, "p50": 650000, "p80": 1000000}, "basis": "착수 노트(공유 노트 t2a-backend-ci.md, 16:55)에 쓴 값을 옮겼다. 선례 x2-grpc-library 작업 중 99분·호출 330·출력 30.4만(결정 약 35, 지우기·이름 바꾸기가 스크립트). 이번은 결정 약 50(지울 job 12, 새 workflow 셋 job 약 20, prCheck, 공통 action, trivy·redis 스크립트, release를 Gitea에 맞춤, 판독기 교체와 TestKit 시험, verify.sh, 계약 시험 6개, 문서 10여 개)이고 새로 쓰는 Java·셸이 많으며, runner 첫 실행이라 실패-고침 반복 2~4번을 더했다. desktop·runner 대기는 시간에서 뺐다"} +{"schema": 1, "kind": "retro", "task": "h3-backend-harness", "cause": "예측 근거 없음", "level": "architecture", "note": "파일 수를 호출 수로 옮겼다. 4건 모두 p30 아래(실측/p50 시간 0.43)라 precedents 보정 줄과 estimate 보정 규칙을 더했다", "ref": "claude-harness docs/retro/2026-11-08.md", "fix": "calib-median", "recorded_at": "2026-11-08T23:21+09:00"} +{"schema": 1, "kind": "retro", "task": "x2-grpc-library", "cause": "예측 근거 없음", "level": "architecture", "note": "desktop 대기를 작업 중 시간에 넣었다. calib-median으로 묶는다", "ref": "claude-harness docs/retro/2026-11-08.md", "recorded_at": "2026-11-08T23:21+09:00"} +{"schema": 1, "kind": "retro", "task": "x3-messaging-library", "cause": "예측 근거 없음", "level": "architecture", "note": "결정 수를 시간 배수로 옮겼다. calib-median으로 묶는다", "ref": "claude-harness docs/retro/2026-11-08.md", "recorded_at": "2026-11-08T23:21+09:00"} +{"schema": 1, "kind": "actual", "task": "t2a-backend-ci", "transcript": "9946b681-b5db-4c9f-898d-9e09bfdf14a2", "minutes": 849, "active_minutes": 132, "calls": 374, "output_tokens": 374573, "cache_read_tokens": 189885057, "max_context": 822088, "within": "p30", "result": "partial", "commits": ["de070e16", "61b1d575", "b9866407", "d46bab96", "a2dfefb6", "4d778c22", "d0c3f91a", "b0bca2a6"], "why": "작업 중 시간·호출·출력 모두 p30 아래였다(132분·374·37.5만). 지우는 코드(판독기 5,800줄)와 문서 이름 바꾸기를 스크립트로 했고, 결정 대부분을 설계(03-ci.md 7절)가 이미 정해 착수 뒤 판단이 적었다. 벽시계 849분의 대부분은 대기였다: desktop 공유 잠금(프론트 게이트 뒤), 네트워크 끊김, runner 대기열(옛 workflow 18개, X3 병합 push), Gitea 503(desktop 디스크 90%). 예측은 대기를 빼고 잡았으므로 맞는 쪽이지만, runner 첫 실행에서 dind 환경 문제(compose bind mount, NFS 권한, 포트 포워딩)가 대기 시간보다 큰 위험이었다. 다음 예측은 「새 실행 환경에서 처음 도는 job 수」를 근거에 넣는다. 결과 partial: desktop 네 단계와 runner PR 단계는 초록, runner release는 Nginx lane 하나(고침), main.yml은 runner 환경 탓 job 여럿이 빨강으로 남았다", "recorded_at": "2026-11-09T06:56+09:00"} From 9c202b7b58a1b3998735cd5564877153e34c36f2 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Mon, 9 Nov 2026 10:53:58 +0900 Subject: [PATCH 10/10] =?UTF-8?q?style(websocket):=20Nginx=20=ED=95=98?= =?UTF-8?q?=EB=84=A4=EC=8A=A4=20=EC=A3=BC=EC=84=9D=EC=9D=84=20100=EC=B9=B8?= =?UTF-8?q?=20=EC=95=88=EC=9C=BC=EB=A1=9C=20=EC=A4=84=EC=9D=B8=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit b0bca2a6이 단 주석 한 줄이 100칸을 넘어 spotlessJavaCheck가 PR #7의 pr.yml(run 61)을 막았다. 같은 뜻으로 줄을 다시 나눈다. 검증: desktop :adapter:inbound:websocket:spotlessJavaCheck와 check 통과. --- .../inbound/websocket/proxy/NginxWebSocketHarness.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/adapter/inbound/websocket/src/nginxWebSocketTest/java/dev/caskeleton/adapter/inbound/websocket/proxy/NginxWebSocketHarness.java b/src/adapter/inbound/websocket/src/nginxWebSocketTest/java/dev/caskeleton/adapter/inbound/websocket/proxy/NginxWebSocketHarness.java index 3f1173ed..fe777f20 100644 --- a/src/adapter/inbound/websocket/src/nginxWebSocketTest/java/dev/caskeleton/adapter/inbound/websocket/proxy/NginxWebSocketHarness.java +++ b/src/adapter/inbound/websocket/src/nginxWebSocketTest/java/dev/caskeleton/adapter/inbound/websocket/proxy/NginxWebSocketHarness.java @@ -30,10 +30,10 @@ public final class NginxWebSocketHarness implements AutoCloseable { */ @SuppressWarnings("resource") public NginxWebSocketHarness(int applicationPort, String configurationResource) { - // The application listens in this JVM's network, which a container reaches by name only through - // Testcontainers' host-port tunnel. `host-gateway` was the Docker host, which is this JVM's host - // on a workstation but not on a CI runner whose job runs in a container of its own (the Gitea - // runner): there Nginx reached nothing and every upgrade failed as a deployment error. + // The application listens in this JVM's network, which a container reaches by name only + // through Testcontainers' host-port tunnel. `host-gateway` was the Docker host: this JVM's + // host on a workstation, but not on a CI runner whose job runs in a container of its own + // (the Gitea runner), where Nginx reached nothing and every upgrade failed. org.testcontainers.Testcontainers.exposeHostPorts(applicationPort); this.nginx = new GenericContainer<>(IMAGE)