review-followup Wave 3 라운드 1(P16): 빌드 게이트 정리 — JPA evidence manifest 폐기, build-tools 제거, API surface를 leaf check로

- 결정 4: JPA evidence·qualification manifest 폐기 → persistence-jpa 테스트, build-tools included build 비움(verifyEnvKeys는
  app-bootstrap 태스크, 구현은 build-logic `ca.config-contract`), gRPC release gate 삭제
- 결정 20: API surface 검사를 leaf `check`로, JPA adopter 검사를 `ca.api-surface`로 합침(구현 하나)
- 레인 단계 정리(문서 대조 레인은 `mainStage()`), integrationCheck가 입력 없는 레인을 이름과 함께 제외 → 로컬 통과(NEW-16)
- release workflow 통합, releaseCheck는 tag 전용, build-logic 비핵심 플러그인 정리, sample을 ArchUnit 대상에
- 보류 4행(B3 변경 모듈만 실행, C 이미지 서명, messaging 카드 검증 이동 2행 — 결정 필요), 남음 2행(O3-5 나머지)
- 통합: P17이 옮긴 gRPC release gate 사본 삭제, `grpc-proto-buf`를 release-gate needs에(P17-new-3)

검증: ./gradlew ci verifyDependencyLocks --warning-mode=fail 통과(685 task), mainCheck 통과(268 task),
-p optional-platforms ci 통과, -p build-logic test 78건 통과(손상된 TestKit 캐시 삭제 후)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-28 16:44:17 +09:00
co-authored by Claude Opus 5.5
parent 4fb7943b85
commit 0ed7bc8df7
166 changed files with 1666 additions and 6571 deletions
+3 -7
View File
@@ -1,21 +1,20 @@
name: build-logic
# The included builds' own tests (TestKit for the convention plugins, unit tests for build-tools).
# 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 builds or the catalog they read.
# 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/build-tools/**"
- "src/gradle/**"
- ".github/workflows/build-logic.yml"
push:
branches: ["main"]
paths:
- "src/build-logic/**"
- "src/build-tools/**"
- "src/gradle/**"
- ".github/workflows/build-logic.yml"
workflow_dispatch:
@@ -36,6 +35,3 @@ jobs:
- name: Test the build-logic convention plugins
working-directory: src
run: ./gradlew -p build-logic test --stacktrace
- name: Test the build-tools verifiers
working-directory: src
run: ./gradlew -p build-tools test --stacktrace
+7 -3
View File
@@ -43,8 +43,9 @@ jobs:
# `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
# The main-branch stage (`mainCheck`: environment contract, full-boot qualification, public-path
# baseline, API surfaces, transport and messaging lanes) runs in integration-main.yml.
# 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
@@ -110,6 +111,7 @@ jobs:
- quality-gates
- sample-portfolio
- optional-platforms
- grpc-proto-buf
if: always()
runs-on: ubuntu-latest
permissions:
@@ -120,12 +122,14 @@ jobs:
QUALITY_RESULT: ${{ needs.quality-gates.result }}
SAMPLE_RESULT: ${{ needs.sample-portfolio.result }}
OPTIONAL_PLATFORMS_RESULT: ${{ needs.optional-platforms.result }}
GRPC_PROTO_BUF_RESULT: ${{ needs.grpc-proto-buf.result }}
run: |
set -euo pipefail
for result in \
"${QUALITY_RESULT}" \
"${SAMPLE_RESULT}" \
"${OPTIONAL_PLATFORMS_RESULT}"; do
"${OPTIONAL_PLATFORMS_RESULT}" \
"${GRPC_PROTO_BUF_RESULT}"; do
if [[ "${result}" != "success" ]]; then
echo "::error::release-gate: required job result was ${result}"
exit 1
@@ -1,115 +0,0 @@
name: fileserver-certification
# The certification a release must clear. Its job list is deliberately the same shape as the support
# matrix: nothing may be advertised at a support level whose evidence job is absent here.
#
# Named "certification", not "release", and the name is the point. This workflow proves a storage
# topology, a support matrix and a telemetry redaction claim. It deploys nothing and holds no cluster
# credential. Calling it `fileserver-release.yml` read as if GitHub Actions released the fileserver,
# which is the CI/CD boundary this repository has now fixed in docs/ci-cd/boundary.md: GitHub Actions
# tests, scans and publishes artifacts; Argo CD deploys.
#
# It used to be workflow_dispatch only, which made that sentence false: the four jobs below are the
# only place the fileserver support matrix, the PVC manifest and the telemetry redaction proof are
# checked, and a release tag reached none of them unless somebody remembered to press a button.
#
# `v*` is the only release tag. The adapter-scoped `fileserver-v*` pattern is gone: this repository
# has one deployable unit (app-bootstrap), so an adapter-scoped tag could only ever run a subset of
# the release gates and call the result a release — the tag-namespace split that release.yml exists
# to end.
#
# These four jobs stay in their own file, and not in release.yml, for one mechanical reason:
# FileserverDocumentationCoverageTest reads job ids out of `.github/workflows/fileserver-*.yml` and
# requires every `fileserver-...` job docs/fileserver/support-matrix.md names to be defined in one
# of them. Renaming the file or moving these jobs needs that document changed in the same change.
on:
push:
tags:
- "v*"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false
jobs:
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-core:check
:adapter:inbound:web:check
:adapter:outbound:fileserver: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
:app-bootstrap:test --tests '*FileserverDocumentationCoverageTest'
--stacktrace
fileserver-pvc-certification:
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
# This job checks the manifest, and only the manifest. It deliberately does not apply anything
# to a cluster.
#
# There used to be a second step here that applied the job to a release cluster when
# secrets.FILESERVER_PVC_KUBECONFIG was set and `exit 0`-ed with a ::warning:: when it was
# not. With no secret configured — which is every fork of this template and was this
# repository — the step printed a warning and the job went green under the name
# "fileserver-pvc-certification", so a release read as ReadWriteOnce-certified against a
# cluster nothing had ever touched. It also wrote a `certified` output that no job, step or
# script in this repository read.
#
# The cluster result comes from an operator running infra/fileserver/kubernetes/
# pvc-certification-job.yaml against a real cluster and recording it in
# docs/fileserver/storage-certification.md. That is registered as
# docs/fileserver/storage-certification.md, and the absence of a cluster result is stated
# there rather than hidden behind a green check.
- name: Check the certification manifest still says what the claim depends on
run: |
set -euo pipefail
manifest=infra/fileserver/kubernetes/pvc-certification-job.yaml
test -f "$manifest"
grep -q 'kind: PersistentVolumeClaim' "$manifest"
grep -q 'kind: Job' "$manifest"
# ReadWriteMany is explicitly not claimed; a manifest that quietly widened the access
# mode would certify a topology the support matrix says is uncertified.
grep -q 'ReadWriteOnce' "$manifest"
! grep -q 'ReadWriteMany' "$manifest"
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-core:test --tests '*FileserverObservabilityTest'
--stacktrace
+2 -2
View File
@@ -49,7 +49,7 @@ jobs:
run: >-
./gradlew
:adapter:outbound:fileserver:test --tests '*CrashRecoveryMatrixTest'
:application-core:test --tests '*FileReconciliationServiceTest'
:application-fileserver:test --tests '*FileReconciliationServiceTest'
--rerun-tasks
--stacktrace
@@ -82,7 +82,7 @@ jobs:
working-directory: src
run: >-
./gradlew
:application-core:test --tests '*MultiInstanceWriterLeaseTest'
:application-fileserver:test --tests '*MultiInstanceWriterLeaseTest'
--rerun-tasks
--stacktrace
+13 -8
View File
@@ -8,9 +8,11 @@ on:
workflow_dispatch:
pull_request:
paths:
- 'src/application-core/src/**/fileserver/**'
- 'src/adapter/inbound/web/src/**/fileserver/**'
- '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/**'
@@ -45,12 +47,15 @@ jobs:
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the fileserver application and architecture suites
# 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-core:test
:app-bootstrap:architectureTest --tests '*Fileserver*'
:application-fileserver:test
:composition:fileserver-platform:test
--stacktrace
@@ -74,11 +79,11 @@ jobs:
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the servlet and reactive transport contracts
- name: Run the servlet transport contracts
working-directory: src
run: >-
./gradlew
:adapter:inbound:web:test
:adapter:inbound:web-fileserver:test
--stacktrace
@@ -92,7 +97,7 @@ jobs:
working-directory: src
run: >-
./gradlew
:adapter:inbound:web:test --tests '*FileserverHardeningContractTest'
:adapter:inbound:web-fileserver:test --tests '*FileserverHardeningContractTest'
:adapter:outbound:fileserver:test --tests '*PhysicalPathResolverTest'
--stacktrace
+5 -21
View File
@@ -58,9 +58,10 @@ concurrency:
jobs:
# The main-branch stage of the Gradle gates (`:mainCheck`): the environment contract, full-boot
# qualification, the sample web contract, the public-path baseline, the API surfaces, the
# conditional transport lanes, the messaging contract lanes and the JPA readiness registry. They
# left the pull-request gate (review 2026-09-24 BUILD, item 12); none of them is deleted.
# qualification, the sample web contract, 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
@@ -127,23 +128,6 @@ jobs:
exit 1
}
jpa-candidate-evidence:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Produce zero-skip JPA candidate manifests
working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:verifyJpaCandidateEvidence --stacktrace
- name: Retain content-addressed JPA candidate manifests
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # actions/upload-artifact@v7.0.1
with:
name: jpa-candidate-evidence-${{ github.sha }}
path: src/adapter/outbound/persistence-jpa/build/jpa-evidence/manifests
if-no-files-found: error
retention-days: 14
# Load, abuse and graceful shutdown measure behaviour that degrades gradually rather than breaking
# outright — which is exactly the kind of regression a per-PR gate never catches.
web-load-abuse-and-shutdown:
@@ -306,7 +290,7 @@ jobs:
run: ./gradlew :adapter:outbound:objectstorage:integrationTest --stacktrace
- name: Standalone sample PostgreSQL contract
working-directory: src
run: ./gradlew :sample-portfolio:integrationTest --stacktrace
run: ./gradlew :sample-portfolio:integrationTestLaneCheck --stacktrace
# These six PostgreSQL contracts moved from app-bootstrap into persistence-jpa. They are named
# directly instead of relying on readiness-card membership: provider ownership and evidence
-45
View File
@@ -1,45 +0,0 @@
name: jpa-r2-evidence
on:
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
TESTCONTAINERS_REUSE_ENABLE: "false"
jobs:
jpa-r2-evidence:
runs-on: ubuntu-latest
timeout-minutes: 30
env:
JPA_EVIDENCE_PROFILE: r2
JPA_EVIDENCE_CI_JOB: >-
actions:${{ github.workflow }}:${{ github.run_id }}:${{ github.job }}
JPA_EVIDENCE_ARTIFACT_LOCATION: >-
${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
JPA_EVIDENCE_TOPOLOGY: postgresql-16-testcontainers-tls-and-fault-matrix
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Verify the production-profile JPA R2 manifest DAG
working-directory: src
run: >-
./gradlew
:adapter:outbound:persistence-jpa:verifyJpaPrimaryFoundationEvidence
-PjpaEvidenceProfile=r2
--stacktrace
- name: Retain JPA R2 attempt manifests
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # actions/upload-artifact@v7.0.1
with:
name: jpa-r2-evidence-${{ github.sha }}-${{ github.run_id }}
path: src/adapter/outbound/persistence-jpa/build/jpa-evidence/manifests
if-no-files-found: error
retention-days: 30
-125
View File
@@ -1,125 +0,0 @@
name: jpa-release
# The release registry is the gate-task source: jpaReleaseQualification reads its blocking gates,
# while JpaReleaseRenderingTest holds this file's matrix and promotion lists to the registry's Stable
# majors and verifyJpaReleaseGateTasks resolves each declared task against the real Gradle graph.
# CI therefore owns release scheduling, not a second JPA gate-task inventory.
#
# The matrix below is therefore not free to drift: editing it without editing the registry fails the
# unit lane.
on:
workflow_dispatch:
push:
tags:
- 'v*'
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false
jobs:
# 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
# selectedVersions().get(0) — so twenty-eight integration classes ran against PG16 and nothing
# ran against 17 or 18, while docs/jpa/support-matrix.md recorded all three as "full contract
# suite, release lane". A JSONB mapping, a Hibernate dialect difference or a Flyway upgrade that
# only breaks on 18 shipped with a green release.
#
# start() now fails closed on a multi-version selection, so the fan-out is not optional: the
# matrix is the only way the three majors get covered, and removing a major from it removes the
# evidence rather than quietly reusing another major's.
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. Three majors' evidence, and all three must come 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 all three majors, 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 three PostgreSQL majors; promotion needs all three"
exit 1
fi
echo "PostgreSQL 16, 17 and 18 evidence all present and all from ${{ github.sha }}."
jpa-architecture-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 and the support matrix
working-directory: src
run: >-
./gradlew
:verifyJpaReleaseGateTasks
:verifyJpaReadinessRegistry
:adapter:outbound:persistence-jpa:test --tests '*JpaReleaseManifestTest'
--stacktrace
+3 -4
View File
@@ -81,10 +81,9 @@ jobs:
# 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.
- name: Notification API surface
working-directory: src
run: ./gradlew :adapter:outbound:notification:verifyNotificationApiSurface --console=plain
- name: Static analysis
# 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
@@ -1,7 +1,14 @@
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 its `mainCheck` on main and here.
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:
+194 -21
View File
@@ -5,31 +5,24 @@ name: release
# One workflow, because there is one deployable unit. `app-bootstrap` is the composition root and
# the only thing a cluster runs; the adapters are leaves of that artifact, not independently
# shippable services. Eight files used to answer a release tag — web-release, web-advanced-release,
# websocket-release, httpclient-release, container-release, and the three that still have to live
# apart (see below) — and between them they ran `verifyCleanArchitectureDependencies` six times and
# `:app-bootstrap:test` four times for one release, on separate runners, with no job in any of them
# able to wait on a job in another.
# websocket-release, httpclient-release, container-release, jpa-release, fileserver-certification
# and one more — and between them they ran `verifyCleanArchitectureDependencies` six times and the
# composition root's unit tests four times for one release, on separate runners, with no job in any
# of them able to wait on a job in another.
#
# Tag scheme: `v*` only. The adapter-scoped patterns (`web-v*`, `websocket-v*`, `fileserver-v*`) are
# gone. They were the namespace-split bug: tagging `v1.2.3` and tagging `web-v1.2.3` ran different
# sets of gates, so a release could choose which gate it cleared, and the adapter-scoped half could
# not build an image because there is no per-adapter image to build.
#
# Two release workflows still stand outside this file, both for a mechanical reason rather than a
# design one:
# * jpa-release.yml — JpaReleaseRenderingTest reads that exact path and holds its PostgreSQL
# matrix and promotion list to src/config/jpa/release-registry.json.
# * fileserver-certification.yml — FileserverDocumentationCoverageTest requires every job id named
# in docs/fileserver/support-matrix.md to be defined in a `.github/workflows/fileserver-*.yml`.
# It is named "certification" rather than "release" on purpose: it certifies a storage topology
# and a support matrix, it deploys nothing, and the CI/CD boundary in docs/ci-cd/boundary.md
# says GitHub Actions does not deploy.
# Folding either one in needs its src-side test (and, for fileserver, the support document) changed
# in the same commit. Until then the image job below cannot wait on them — a stated gap.
# The JPA release gates and the fileserver certification used to stand outside this file
# (jpa-release.yml, fileserver-certification.yml), so the image job could not wait on them. They are
# jobs here now (review 2026-09-24 BUILD-계획-B2): JpaReleaseRenderingTest reads this file's JPA
# matrix and promotion list, and FileserverDocumentationCoverageTest reads its fileserver job ids.
#
# The image job DOES now wait on the evidence jobs in this file, which is new: while the image build
# lived in its own workflow it could publish while a sibling suite was still running or already red,
# because `needs:` does not reach across workflows.
# The image job waits on every evidence job in this file: `needs:` does not reach across
# workflows, so a gate in another file could still be running, or already red, when the image
# published.
on:
push:
@@ -46,9 +39,10 @@ concurrency:
cancel-in-progress: false
jobs:
# The repository release contract, once. releaseCheck contains the PR gate plus provenance,
# stale-archive hygiene and the public path snapshot, so those tasks are no longer merely
# registered/documented — the tag workflow executes them before any image can publish.
# The tag-only checks. releaseCheck no longer re-runs `ci`: a release tag is cut from a main
# commit that ci-quality-gates.yml (the pull-request gate) and integration-main.yml (`mainCheck`)
# already ran on, and running the whole PR gate a third time was the repeat review BUILD-중복-6
# asked to remove.
architecture-and-surface:
runs-on: ubuntu-latest
timeout-minutes: 90
@@ -193,6 +187,179 @@ jobs:
- 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.
#
# config/jpa/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-pvc-certification:
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
# This job checks the manifest, and only the manifest; it applies nothing to a cluster. The
# cluster result comes from an operator running infra/fileserver/kubernetes/
# pvc-certification-job.yaml and recording it in docs/fileserver/storage-certification.md,
# where the absence of a cluster result is stated rather than hidden behind a green check.
- name: Check the certification manifest still says what the claim depends on
run: |
set -euo pipefail
manifest=infra/fileserver/kubernetes/pvc-certification-job.yaml
test -f "$manifest"
grep -q 'kind: PersistentVolumeClaim' "$manifest"
grep -q 'kind: Job' "$manifest"
# ReadWriteMany is explicitly not claimed; a manifest that quietly widened the access
# mode would certify a topology the support matrix says is uncertified.
grep -q 'ReadWriteOnce' "$manifest"
! grep -q 'ReadWriteMany' "$manifest"
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
@@ -201,6 +368,12 @@ jobs:
- grpc-stable-release-gate
- httpclient-release-gate
- httpclient-documentation
- jpa-release-promotion
- jpa-registry-and-docs
- fileserver-full-verification
- fileserver-documentation-gate
- fileserver-pvc-certification
- fileserver-sensitive-telemetry-scan
# Job-level, because a job that declares `permissions:` replaces the workflow set entirely: this
# is the only job that writes anything anywhere, and `packages: write` stops at its boundary.
permissions:
+6 -5
View File
@@ -63,10 +63,11 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
(`strictTestLanes`). leaf는 `ca.java-library` / `ca.spring-library` / `ca.platform-module` 중
자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다.
`ca.architecture`가 아키텍처 검증 태스크를 소유한다. 기능별 검사(notification·mongo·messaging·
graphql 등)는 build-logic이 아니라 소유 leaf의 테스트다. 테스트가 저장소 파일을 읽으면 그 파일을
그 leaf의 test task `inputs`로 선언한다.
- `src/build-tools/`: 아직 옮기지 않은 검사만 남는다(`ca.config-contract`의 `verifyEnvKeys`, JPA
evidence·readiness·release registry). 새 검사를 여기에 추가하지 않는다.
graphql·JPA readiness 등)는 build-logic이 아니라 소유 leaf의 테스트다. 테스트가 저장소 파일을 읽으면
그 파일을 그 leaf의 test task `inputs`로 선언한다. 저장소 문서와 대조하는 테스트는 `mainStage()`
레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다.
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(소유자 결정 4). 구현은 build-logic의
`ca.config-contract`다. `src/build-tools/` included build는 비워서 삭제했다.
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `releaseCheck`, `qualityCheck`,
`configContractCheck`, `integrationCheck`)과 버전/리비전
@@ -186,7 +187,7 @@ cd src
./gradlew architectureCheck # 의존 방향·domain-core/shared-contract/application-* 순수성·ArchUnit
./gradlew qualityCheck # SpotBugs + FindSecBugs (leaf check에는 없다)
./gradlew ci # PR 게이트 = leaf check + architecture + quality
./gradlew mainCheck # main 단계 = env 계약·전체 기동·public path·API surface·전송/메시징 레인·JPA readiness
./gradlew mainCheck # main 단계 = env 계약·전체 기동·public path·전송/메시징 레인·leaf 문서 대조 레인
./gradlew verifyPublicPathSnapshot
./gradlew :app-bootstrap:verifyEnvKeys
```
+11 -8
View File
@@ -28,9 +28,11 @@ If this summary drifts from `AGENTS.md`, `AGENTS.md` wins and this summary must
- `src/settings.gradle`: fail-closed registry validation, project inclusion, and directory mapping.
- `src/build-logic/`: the architecture core (registry, direction and purity tasks), the conventions,
and one test-lane mechanism (`strictTestLanes`). Feature-specific checks are the owning leaf's
tests; a test that reads repository files declares them as that leaf's test `inputs`.
- `src/build-tools/`: only checks not yet moved (`verifyEnvKeys`, JPA evidence/readiness/release
registry). Do not add new checks there.
tests; a test that reads repository files declares them as that leaf's test `inputs`, and a test
that compares a leaf with repository documents is a `mainStage()` lane (tag `document-contract`)
in that leaf's `mainCheck`.
- `verifyEnvKeys` stays an app-bootstrap task (owner decision 4); its implementation is build-logic's
`ca.config-contract`. The `src/build-tools/` included build was emptied and removed.
- `src/build.gradle`: the root lifecycle (`ci`, `mainCheck`, `releaseCheck` and the named
repository-wide gates).
@@ -121,11 +123,12 @@ A leaf's `check` covers that leaf only — compile, its tests, Spotless, Checkst
Repository-wide questions have their own names: `architectureCheck` (dependency direction, purity
of domain-core/shared-contract/application-*, Git-carryable sources, ArchUnit), `qualityCheck`
(SpotBugs, FindSecBugs), `configContractCheck` (the environment contract), `integrationCheck` (the
declared strict integration lanes). `ci` (pull request) is leaf checks + architectureCheck +
qualityCheck; `mainCheck` (main branch) is configContractCheck + qualificationCheck + the sample web
contract + the public-path snapshot + API surfaces + the transport and messaging qualification lanes
+ the JPA readiness registry; `releaseCheck` is `ci` + provenance, archive hygiene and the
public-path snapshot.
declared strict integration lanes; a lane that needs an input the build was not given is left out
and named). `ci` (pull request) is leaf checks (API surfaces included, owner decision 20) +
architectureCheck + qualityCheck; `mainCheck` (main branch) is configContractCheck +
qualificationCheck + the sample web contract + the public-path snapshot + the transport and
messaging qualification lanes + every leaf's `mainCheck` (document-contract lanes, MinIO lanes);
`releaseCheck` is the tag-only checks: release provenance and the public-path snapshot.
Test-writing rules (behavior-sentence names that assert what they promise, given/when/then comments,
one `// when`, one fake per port in the port owner's testFixtures, fake and adapter sharing one
+2 -3
View File
@@ -38,11 +38,10 @@ test는 해당 Gradle path에서 `./gradlew <gradle-path>:test --console=plain`
전제조건은 Temurin 21(루트 [.tool-versions](.tool-versions)에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다.
```bash
cd src
./gradlew bootstrap
scripts/bootstrap-local.sh # 다른 Compose overlay는 scripts/bootstrap-local.sh <profile>
```
`bootstrap`은 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, sample 격리 검증, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 각 단계가 별도 Gradle task라 실패 단계가 task 이름으로 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
```bash
curl -fsS http://localhost:8080/api/healthcheck
@@ -29,7 +29,9 @@ production unapproved — because the remedy differs in each case.
**Promotion evidence is per capability.** `GrpcAdvancedPromotionEvidence` is one record per
capability, so no promotion can drag another along;
`GrpcAdvancedPromotionGate.capabilitiesDraggedAlong` returns an empty list, and that is a tested
property rather than a claim. Two thresholds: seven days of soak plus complete evidence for
property rather than a claim. (2026-09-28: the gate classes were removed because nothing outside
their own tests called them — review 2026-09-24 S5-lead-4. The per-capability rule stands as a
review rule in `docs/runbooks/grpc-advanced-capabilities.md`.) Two thresholds: seven days of soak plus complete evidence for
`ADVANCED_STABLE`, thirty for a Stable default, because the second means every deployment gets the
capability's dependencies and its failure modes.
@@ -1,6 +1,8 @@
# Supported production adopter surface for the JPA persistence leaf.
# Language-level public implementation types are not compatibility promises.
# Adding an import outside this list requires an explicit review of the adopter contract.
# Checked by verifyJpaApiSurface (ca.api-surface adopterBaseline); every entry must be in
# jpa-api-surface.txt. persistence-fileserver types are that leaf's own surface, not listed here.
dev.caskeleton.adapter.outbound.persistence.api.capability.CapabilitySupport
dev.caskeleton.adapter.outbound.persistence.api.capability.JpaCapability
dev.caskeleton.adapter.outbound.persistence.audit.AuditContextPort
@@ -8,7 +10,6 @@ dev.caskeleton.adapter.outbound.persistence.audit.AuditableEntity
dev.caskeleton.adapter.outbound.persistence.config.PersistenceJpaConfig
dev.caskeleton.adapter.outbound.persistence.config.PersistenceVendorSettings
dev.caskeleton.adapter.outbound.persistence.failure.SqlStateErrorMapping
dev.caskeleton.adapter.outbound.persistence.fileserver.FileserverSchemaActivation
dev.caskeleton.adapter.outbound.persistence.hibernate.HibernateProviderPolicy
dev.caskeleton.adapter.outbound.persistence.migration.FlywaySchemaPolicy
dev.caskeleton.adapter.outbound.persistence.outbox.OutboxClaimRepository
+24
View File
@@ -378,3 +378,27 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
| `JpaSchemaSafetyValidator`, `JpaSchemaSafetyValidatorTest` | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaSchemaSafetyValidator.java` | `93251e76` | S6-#3c. guard와 중복, guard보다 늦게 돌아 발동한 적 없음 |
| `isProdActive()` wrapper 4개 | `persistence-jpa/.../startup/{FlywayProdSafetyValidator,PersistenceVendorProdSafetyValidator,PostgreSqlTransportSecurityValidator}.java`, `app-bootstrap/.../runtime/SecretSourceValidator.java` | `93251e76` | S6-#3d. `RuntimeProfileSnapshot.isProduction()` 1줄 위임 |
| `DurableOperationJpaRepository`의 `JpaRepository` 상속(findAll/deleteAll 등) | `persistence-jpa/.../operation/DurableOperationJpaRepository.java` | `93251e76` | E-6b. tenant 범위 없는 bulk 메서드 노출 |
| build-tools included build 전체(`ca.jpa-evidence`, `ca.jpa-qualification`, `jpa/` 45파일, `junit/` 2파일과 테스트) | `src/build-tools/` | `016597ac` | 소유자 결정 4(JPA evidence manifest 폐기). `config/`는 build-logic으로 이동 |
| `jpa-r2-evidence.yml`, integration-main `jpa-candidate-evidence` job | `.github/workflows/` | `016597ac` | JPA evidence manifest 폐기 |
| `JpaAdopterApiSurfaceTest` | `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/` | `016597ac` | `ca.api-surface` `adopterBaseline`으로 통합(BUILD-중복-3) |
| `GrpcStableReleaseGate`·`GrpcCompatibilityMatrix`·`GrpcReleaseDecision`·`GrpcReleaseEvidence`(+Test) | `src/grpc/grpc-testkit/src/{main,test}/java/dev/caskeleton/grpc/release/` | `016597ac` | 호출처가 자기 테스트뿐(S5-lead-4) |
| `GrpcAdvancedPromotionGate`·`…Decision`·`…Evidence`·`GrpcAdvancedSupportMatrix`(+Test) | `src/grpc-advanced/grpc-advanced-bootstrap/src/{main,test}/java/dev/caskeleton/grpc/advanced/release/` | `016597ac` | 같음 |
| `ca.public-path-snapshot`(publicpath 5파일 + renderer test) | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/publicpath/` | `016597ac` | app-bootstrap `PublicPathSnapshotTest`로(BUILD-O3-5) |
| `ca.archive-hygiene`(archive 5파일 + test) | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/archive/` | `016597ac` | leaf version에서 revision 제거로 stale jar가 생기지 않음 |
| `ca.developer-bootstrap`(`DeveloperBootstrapPlugin`, `BootstrapSmokeTask` + functional test) | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/bootstrap/` | `016597ac` | `scripts/bootstrap-local.sh`로 |
| `BuildVerificationPurityContractTest`(archive·public-path TestKit 10개) | `src/build-logic/src/test/java/dev/caskeleton/bootstrap/contract/` | `016597ac` | 대상 플러그인 삭제; public-path 케이스는 `PublicPathSnapshotTest`로 |
| `jpa-release.yml`, `fileserver-certification.yml` | `.github/workflows/` | `016597ac` | job을 `release.yml`로 이동(B2) |
| 삭제·이동한 검사 | 지금 도는 곳 | 게이트 |
| `verifyJpaReadinessRegistry`(카드 구조·선행·task 존재·migration stream) | persistence-jpa `JpaReadinessRegistryTest` | `ci`(leaf `test`) |
| `verifyJpaCandidateEvidence`/`verifyJpaPrimaryFoundationEvidence`(JUnit XML selector·no-skip) | readiness 레인 `requires`(카드 인용 scenario 전부) + `rejectSkipped` | `integrationCheck`, `release.yml` `jpa-release-gate` |
| `verifyJpaReleaseGateTasks`(gate task 존재) | `jpaReleaseQualification` dependsOn(없는 task면 그래프 생성 실패) + `JpaReleaseRenderingTest` | release, `ci` |
| `jpaReleaseQualification`(루트) | persistence-jpa 같은 이름 태스크 | `release.yml` `jpa-release-gate` |
| `JpaAdopterApiSurfaceTest` | `:adapter:outbound:persistence-jpa:verifyJpaApiSurface` adopter 검사 | `ci`(leaf `check`) |
| `verifyEnvKeys`(build-tools) | build-logic `ca.config-contract`, 태스크 동일 | `mainCheck`(`configContractCheck`) |
| `verifyPublicPathSnapshot`/`updatePublicPathSnapshot`(플러그인) | `:app-bootstrap:publicPathSnapshotTest`(루트 별칭 `verifyPublicPathSnapshot`) + 렌더링 단위 테스트 3개(`test`) | `mainCheck`, `releaseCheck`, `ci`(단위) |
| `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` |
| `releaseCheck`의 `ci` | ci-quality-gates.yml `:ci`(PR·main push) | PR |
| fileserver-pr `architectureTest --tests '*Fileserver*'` | `:ci`의 `architectureCheck`(전체 ArchUnit) | PR |
+4 -3
View File
@@ -60,11 +60,12 @@ GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync
| Argo CD Application 정의 | **없음.** GitOps 저장소에 둘 예정 |
| CI에서의 클러스터 접근 | 없음 — 유일했던 `kubectl apply`는 제거됨 |
`fileserver-certification.yml`은 예외처럼 보이지만 아니다. PVC 매니페스트가 여전히 ReadWriteOnce를
`release.yml`의 fileserver certification 잡(`fileserver-pvc-certification` 등, 예전
`fileserver-certification.yml`)은 예외처럼 보이지만 아니다. PVC 매니페스트가 여전히 ReadWriteOnce를
선언하는지 **파일만** 확인하고, 클러스터에는 아무것도 적용하지 않는다. 실제 클러스터에서의 인증은
운영자가 `infra/fileserver/kubernetes/pvc-certification-job.yaml`을 직접 실행하고
`docs/fileserver/storage-certification.md`에 기록한다. 이름을 `fileserver-release.yml`에서 바꾼 이유가
이것이다 — 이 워크플로는 릴리스하지 않는다.
`docs/fileserver/storage-certification.md`에 기록한다. 잡 이름이 "release"가 아니라 "certification"인
이유가 이것이다 — 이 잡은 릴리스하지 않는다.
## 규칙
+4 -2
View File
@@ -4,8 +4,10 @@ What the Stable gRPC platform (`:grpc:*`) is certified against, what it is only
what is merely watched. The distinction is the point: "works with Spring Boot" is not a statement
anyone can act on.
`GrpcCompatibilityMatrix.caSkeleton()` is the machine-readable form of this table, and
`GrpcStableReleaseGate` blocks a release when a certified lane has no result or a failing one.
The release gate is the `grpc-stable-release-gate` job in `.github/workflows/release.yml`: each
certified lane is a strict test lane that fails when it runs nothing. The in-code
`GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` pair was removed (review 2026-09-24 S5-lead-4):
no production or build code called it, so it gated nothing.
## Lanes
+3 -2
View File
@@ -79,7 +79,8 @@ existing name.
The plan declares seven JVM test suites (`test`, `integrationTest`, `contractTest`,
`migrationTest`, `failureTest`, `performanceTest`, `compatibilityTest`). This leaf already owns a
Docker-backed `postgresqlIntegrationTest` source set and its readiness Gradle tasks are registered
in a fail-closed contract (`verifyJpaReadinessRegistry` in `src/build.gradle`).
as strict lanes in this leaf's `build.gradle`; `JpaReadinessRegistryTest` holds the readiness cards
to those lanes (it replaced the build-tools `verifyJpaReadinessRegistry`).
| Plan suite | Repository lane |
|---|---|
@@ -101,7 +102,7 @@ Docker-dependent lanes fail closed rather than skipping, matching the existing
| `settings.gradle.kts` module registration | Fail-closed 19-leaf registry | No registry change: leaf identity, Gradle path, allowed dependencies, and runtime memberships are unchanged. |
| `infra/jpa/{postgres,roles,toxiproxy}` | Repository already owns `infra/` | Created at the same repository-relative paths. |
| `docs/jpa/**`, `docs/adr/ADR-JPA-*`, `.github/workflows/jpa-*.yml` | Repository already owns `docs/` and `.github/workflows/` | Created at the same repository-relative paths. |
| release blocking aggregate | `.github/workflows/jpa-release.yml` | CI names the blocking JPA lanes directly; Gradle only defines how each lane runs. |
| release blocking aggregate | `jpaReleaseQualification` (persistence-jpa `build.gradle`) over `config/jpa/release-registry.json`, run per PostgreSQL major by the `jpa-release-gate` job in `.github/workflows/release.yml` | The registry names the blocking lanes; Gradle defines how each lane runs; CI only schedules the matrix. | |
| Per-task `git add` + `git commit` | `AGENTS.md`: commit policy is `human-only`; agents do not stage, commit, amend, or push | Implementation is delivered unstaged. This is the only plan step intentionally not executed, and it is recorded here. |
| Querydsl as an optional module dependency | Querydsl is not part of this repository's dependency set | `querydsl` is implemented against the plan's contracts with the Querydsl types kept behind `compileOnly`, so the Stable runtime classpath never carries Querydsl and a deployment opting in adds the artifact itself. |
| Hibernate Envers as a module dependency | Envers is not part of this repository's dependency set | Same treatment as Querydsl: `compileOnly` + explicit opt-in, matching the plan's "Envers is opt-in and never enabled by a global base class". |
+5 -4
View File
@@ -12,9 +12,10 @@ evidence, and this document describes what the registry says.
Being a rendering used to be a claim rather than a mechanism: the tables below were still typed by
hand, so a major demoted in the registry stayed Stable here and kept its full release job.
`JpaReleaseRenderingTest` now compares the database table, the gate table and `jpa-release.yml`'s
matrix and promotion lists to the registry, and `verifyJpaReleaseGateTasks` resolves every gate's
task against the real Gradle task graph. Edit the registry; these tables follow, or the build fails.
`JpaReleaseRenderingTest` now compares the database table, the gate table and `release.yml`'s JPA
matrix and promotion lists to the registry, and the `jpaReleaseQualification` aggregate depends on
every blocking gate's task, so a gate naming a task that does not exist fails when the task graph is
built. Edit the registry; these tables follow, or the build fails.
Two renderings stayed outside that comparison until they were added to it. `jpa-nightly.yml` runs
its own matrix and nothing checked it, so a demotion corrected the release lane and left the nightly
@@ -38,7 +39,7 @@ Each major gets its **own release job**, because for a while it did not. The rel
`-Pjpa.matrix.versions=16,17,18` to a `JpaPlatformContractSupport.start()` that used
`selectedVersions().get(0)`, so the whole integration suite ran against PostgreSQL 16 and this table
recorded 17 and 18 as fully covered on the strength of a three-assertion smoke test. `start()` now
refuses a multi-version selection outright, `jpa-release.yml` fans out to one job per major, and a
refuses a multi-version selection outright, the `jpa-release-gate` job in `release.yml` fans out to one job per major, and a
promotion job requires all three majors' evidence to carry the same commit SHA — so a removed major
removes the release, not the evidence for it.
@@ -0,0 +1,90 @@
# W3-P16 — Wave 3 빌드 게이트
worktree `.claude/worktrees/agent-ac6714988540478ba`, 브랜치 `worktree-agent-ac6714988540478ba`.
커밋: `de075afe`(JPA evidence 폐기·build-tools 비움·gRPC gate 삭제), `6107ca80`(API surface → check, adopter 검사 통합),
`eaf1af1c`(레인 단계 정리·integrationCheck 로컬 통과), `6d3050d4`(release workflow 통합·releaseCheck tag 전용·build-logic 정리),
`7fe5d754`(spotlessApply), 그리고 이 결과 파일 커밋.
## 행 결과
| ID | 결과 | 근거 |
|---|---|---|
| O-4c | 완료 | `JavaConventionsPlugin`에 runtime classpath `metaInf` 정규화(`Implementation-Version`·`Build-Revision` 무시), `src/build-logic/src/main/java/dev/caskeleton/buildlogic/java/JavaConventionsPlugin.java`. 재현: `GIT_SHA`만 바꿔 `:application-core:test` 두 번 실행 — 정규화 없이 재실행됨(FAIL, cache miss) → 정규화 후 `UP-TO-DATE`(PASS). 추가로 leaf version에서 revision을 뺐다(BUILD-O3-5) |
| O-8 / BUILD-중복-2 / BUILD-바로할것-6 | 완료 | build-tools `junit` 패키지(`JUnitEvidenceReader`)를 JPA evidence와 함께 삭제(`de075afe`). 남은 "지정 테스트 실행·skip 없음" 구현은 `StrictLaneExecutionTracker`(정본)와 `RedisTopologyExecutionTracker`(소유자 결정 4로 유지) 둘 |
| BUILD-결론-1 | 남음 | build-logic+build-tools Java 10,504줄 → build-logic 6,185줄(main 4,184 + test 2,001; build-tools 0). 목표 3.5–4k에는 BUILD-O3-5 나머지(auxiliary → jvm-test-suite, release-provenance 제거)가 필요 |
| BUILD-결론-2 | 완료 | 기능별 evidence 검사 중 JPA(`jpa/` 2,701+706줄, `junit/` 138+76줄) 삭제. 남은 E는 redis topology(소유자 결정 4로 유지) |
| BUILD-결론-4 | 완료 | 하위 행으로 추적: B2·B4-17·B4-27·B4-28·B4-30·중복-6 완료, B3의 "변경 모듈만 실행"과 C는 보류(각 행) |
| BUILD-중복-3 | 완료 | `ca.api-surface`에 `adopterBaseline`/`adopterSources` 추가(javac로 import 파싱, adopter 목록 ⊆ 공개 surface 확인): `ApiSurfacePlugin`, `VerifyApiSurfaceTask`, `ApiSurfacePolicy.verifyAdopters`, `JavaPublicTypes.imports`. `ApiSurfaceConventionTest.anAdopterImportOutsideTheAdopterBaselineFailsTheVerification`·`anAdopterImportTheAdopterBaselineListsPasses`·`anAdopterBaselineEntryTheSurfaceNoLongerHasFailsTheVerification` FAIL(fixture가 없는 `adopterBaseline` 속성을 씀)→PASS. `JpaAdopterApiSurfaceTest` 삭제, persistence-jpa `apiSurface { adopterBaseline … }` |
| BUILD-중복-6 | 완료 | `releaseCheck`에서 `ci` 의존 제거(`src/build.gradle` releaseCheck = `verifyReleaseProvenance` + `verifyPublicPathSnapshot`), `fileserver-pr.yml`의 `:app-bootstrap:architectureTest --tests '*Fileserver*'` 삭제. `DeveloperExperienceContractTest.architectureWorkflowSelectorsUseTheArchitectureSourceSetTask`를 새 계약(PR `:ci`에서 한 번)으로 수정 |
| BUILD-중복-7 | 완료 | 루트 `id 'ca.jpa-qualification'` 삭제(`de075afe`). 루트에 남은 플러그인은 `ca.release-provenance`, `ca.architecture` |
| BUILD-중복-8 | 완료 | `src/app-bootstrap/build.gradle` `architectureTestRuntimeOnly project(':sample-portfolio')` + optional-platforms는 Gradle 방향 게이트로 충분하다는 주석. sample을 넣자 `ForbiddenApiArchitectureTest.NO_UUID_RANDOM_IN_CONTROLLER` FAIL(`PublishPosterImageUseCase.handle`의 `UUID.randomUUID()`) → id 포트(`ids.allocate()`)로 고쳐 PASS(`:app-bootstrap:architectureTest` 180/180). app-bootstrap lockfile 재생성(+1줄) |
| BUILD-계획-B2 | 완료 | `jpa-release.yml`·`fileserver-certification.yml`의 job을 `release.yml`로 옮기고 두 파일 삭제, `app-image-release`가 `jpa-release-promotion`·`jpa-registry-and-docs`·fileserver 4 job을 `needs`. `JpaReleaseRenderingTest`는 `release.yml`을 읽고, `FileserverDocumentationCoverageTest`는 `fileserver-*.yml` + `release.yml`의 job id를 읽음(둘 다 PASS) |
| BUILD-계획-B3 | 보류 | 구현한 부분: `object-storage-qualification.yml` PR 트리거에 경로 필터, MinIO 두 레인을 objectstorage `check`에서 `mainCheck`로(`src/adapter/outbound/objectstorage/build.gradle`). 남은 "PR `ci`를 변경 모듈만 실행"은 영향 모듈 계산 방식(Gradle 의존 그래프 역추적·경로 매핑)과 누락 위험 수용 범위를 정해야 하고 로컬에서 검증할 수 없음. 승인자: 저장소 소유자 결정 필요 |
| BUILD-계획-B4-17 | 완료 | 결정 20: API surface는 PR(`check`)에서 돈다(NEW-13d). notification-platform.yml PR job의 별도 `verifyNotificationApiSurface` step은 같은 job의 `:adapter:outbound:notification:check -x test`가 이미 돌리므로 삭제("PR에서 main으로" 방향은 결정 20에 따라 닫음) |
| BUILD-계획-B4-27 | 완료 | `NotificationEvidenceVerifierTest.repositorySupportMatrixClaimsNoMoreThanTheManifestProves`에 `@Tag("document-contract")`, 레인 `notificationDocumentContractTest`(`mainStage()`, `rejectSkipped`) → leaf `mainCheck`. fixture 케이스는 `test`에 남음. `test` inputs 선언 제거(레인은 항상 실행). `StrictTestLaneConventionTest.aMainStageLaneLeavesTheLeafTestTaskAndJoinsMainCheck` FAIL→PASS |
| BUILD-계획-B4-28 | 완료 | `NotificationEnvironmentRegistryTest`에 태그, 레인 `notificationEnvironmentContractTest`(`src/composition/notification-platform/build.gradle`) |
| BUILD-계획-B4-30 | 완료 | `MongoTestLaneContractTest`에 태그, 레인 `mongoDocumentContractTest`(`src/adapter/outbound/persistence-mongo/build.gradle`). `mainCheck` 실행에서 세 레인 모두 실행 확인 |
| BUILD-계획-C | 보류 | 서명 대상(GHCR push)과 keyless OIDC 토큰은 tag 실행에서만 있어 로컬 검증 불가. 이 workflow는 제3자 action 대신 체크섬 고정 바이너리를 설치하는 정책인데, 이 환경에서 cosign 릴리스 체크섬을 확인할 수 없어 확인하지 않은 체크섬·action SHA를 넣지 않음. 결정할 것: cosign 버전·설치 방식(체크섬 고정 vs `sigstore/cosign-installer` SHA 고정), image job에 `id-token: write` 부여. 승인자: 저장소 소유자 결정 필요 |
| BUILD-O3-2 | 완료 | build-tools `jpa/`·`junit/`, `ca.jpa-evidence`·`ca.jpa-qualification` 삭제. readiness 카드 검사 → `JpaReadinessRegistryTest`(persistence-jpa `test`, 입력 `readiness-cards.yaml`·`src/postgresqlIntegrationTest/java` 선언). `everyImplementedCardNamesTasksThisLeafDeclares` FAIL(삭제된 `verifyJpaPrimaryFoundationEvidence`를 가리키던 카드, AssertionError at :106) → 카드를 `integrationTestLaneCheck`로 고쳐 PASS. 카드가 인용한 scenario는 readiness 레인의 `requires` + `rejectSkipped`로(manifest가 JUnit XML로 확인하던 것). `jpaReleaseQualification`은 leaf 집계 태스크(registry의 blocking gate를 dependsOn). workflow: `jpa-r2-evidence.yml`, integration-main `jpa-candidate-evidence` 삭제 |
| BUILD-O3-5 | 남음 | 완료: public-path → app-bootstrap `PublicPathSnapshotTest`(main 단계 레인 `publicPathSnapshotTest`, 루트 별칭 `verifyPublicPathSnapshot`, 승인 `-PapprovePublicPathChange`; 기준선은 헤더의 명령만 바뀜), developer-bootstrap → `scripts/bootstrap-local.sh`, leaf version에서 revision 제거 후 archive-hygiene 삭제, app-bootstrap `springBoot.buildInfo`(`build.revision`, `time` 제외). 남음: (1) `ca.release-provenance` 플러그인 제거 — `src/optional-platforms/build.gradle`이 적용하고 있어 이번 Wave에서 건드리지 않기로 한 gRPC build 파일 수정이 필요, (2) auxiliary → `jvm-test-suite` — grpc·messaging 포함 14개 leaf build 파일을 바꾸는 작업이라 동시 묶음과 충돌. 둘 다 다음 순차 작업으로 |
| BUILD-O3-6 | 완료 | `config` 패키지를 `dev.caskeleton.buildlogic.config`로 이동(테스트 2개 포함), `includeBuild('build-tools')`·Dockerfile `COPY build-tools/`·build-logic.yml step 삭제, `src/build-tools` 삭제. 태스크는 `:app-bootstrap:verifyEnvKeys` 그대로(PASS) |
| BUILD-바로할것-7 | 완료 | BUILD-중복-3과 같음. adopter 목록 파일(`docs/architecture/jpa-adopter-api-surface.txt`)은 따로 두되 구현은 `ca.api-surface` 하나(surface 기준선은 렌더링이 재생성하므로 표시를 섞지 않음). persistence-fileserver 타입 `FileserverSchemaActivation` 항목은 JPA surface가 아니어서 제거 |
| BUILD-바로할것-12d | 완료 | api-surface 부분은 결정 20에 따라 PR `check`로(반대 방향 행을 결정 20으로 닫음). notification evidence·env registry·mongo lane contract는 B4-27·28·30의 main 단계 레인 |
| X1-지도-readiness / evidence / API-surface / moduleboundary | 보류 | 완료: JPA readiness·evidence → persistence-jpa 테스트(manifest 폐기), API surface 구현 하나. 남은 "messaging 카드 검증은 messaging leaf로": `MessagingCapabilityRegistryContractTest`는 `config/messaging/*.yaml`을 snakeyaml로 읽는데 `adapter:outbound:messaging`은 모든 configuration(테스트 포함)에서 YAML·Jackson 2를 exclude+reject한다("Jackson 3 only and YAML-free"). 옮기려면 카드 파일을 JSON으로 바꾸거나 test 설정만 예외로 둘지 정해야 함. 승인자: 저장소 소유자 결정 필요 |
| X1-#7a | 보류 | 위 행과 같은 작업. JPA 검증기는 leaf 테스트로 옮김, messaging 검증기 이동은 같은 사유로 결정 필요. 승인자: 저장소 소유자 결정 필요 |
| S1-#16 | 완료 | `src/application-core/build.gradle` `implementation project(':domain-core')` 복원(registry 허용 edge). `architectureCheck` PASS. 같은 행의 `NotificationIdGeneratorPort`·`UploadIdentifierFactory` → `IdFactory` 정리는 application-notification/fileserver·persistence-jpa·composition을 바꾸는 작업이라 하지 않음(P16-new-5) |
| S5-lead-4 | 완료 | `grpc/grpc-testkit/.../release/`(4 main + 1 test), `grpc-advanced/grpc-advanced-bootstrap/.../release/`(4 main + 1 test) 삭제, 문서 4곳 정정. `-p optional-platforms ci` PASS. build 파일은 건드리지 않음 |
| NEW-13a | 완료 | `CLAUDE.md`·`AGENTS.md`·`src/README.md`·build-logic README를 "verifyEnvKeys = app-bootstrap 유지(결정 4), 구현은 build-logic `ca.config-contract`, build-tools 삭제"로 수정 |
| NEW-13b | 완료 | O3-2와 같음. 수정 방향과 다른 점: `readiness-cards.yaml`·`release-registry.json`은 지우지 않음 — 결정 4·X1 결정은 "leaf 테스트로 옮김"이고, `release-registry.json`은 persistence-jpa testFixtures `JpaReleaseManifest`·`JpaReleaseRenderingTest`·`jpaReleaseQualification`의 SSOT, 카드 파일은 `JpaReadinessRegistryTest`와 readiness 레인 `requires`의 입력. `MessagingCapabilityRegistryContractTest`는 JPA 카드를 읽지 않음(`config/messaging`만 읽음, 현황표 근거가 틀림) |
| NEW-13d | 완료 | `ApiSurfacePlugin`이 verify를 leaf `check`에 연결. `ApiSurfaceConventionTest.theLeafCheckRunsTheSurfaceVerification` FAIL→PASS, `./gradlew check --dry-run`에 graphql·notification·jpa·mongo `verify*ApiSurface` 포함 |
| NEW-13e | 완료 | `posterImageMigrationTest`에 `integration()`, 루트 `integrationCheck`에 `:sample-portfolio:integrationTestLaneCheck`, `verifyMessagingContracts`에 `:sample-portfolio:messagingSampleContractQualificationTest`, integration-main.yml 호출을 `:sample-portfolio:integrationTestLaneCheck`로 |
| NEW-16 | 완료 | `strictTestLanes`에 `explicitOnly(reason)`(모든 집계에서 빠지고 집계가 돌 때 이유 출력) — `StrictTestLaneConventionTest.anExplicitOnlyLaneStaysOutOfEveryAggregate` FAIL→PASS. Redis topology는 `-Predis.topology.mode`가 없으면 explicit-only(`RedisTopologyLanePluginFunctionalTest.withoutADeclaredModeTheLaneStaysOutOfTheIntegrationAggregate`·`aDeclaredModePutsTheLaneInTheIntegrationAggregate` FAIL→PASS), AWS lane은 `OBJECT_STORAGE_AWS_QUALIFICATION_ENABLED=true`가 없으면 explicit-only, httpclient `disabledProxyFailsBeforeARequestCanBeSent`는 Docker userland proxy와 무관한 loopback 닫힌 포트 시나리오 `refusedConnectionFailsBeforeARequestCanBeSent`로 교체(P11-new-3도 해소). `./gradlew integrationCheck --continue` BUILD SUCCESSFUL(14m), 기존 실패 3종 없음, 빠진 lane 4개는 이유 출력 |
## 제거된 코드
| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |
|---|---|---|---|
| build-tools included build 전체(`ca.jpa-evidence`, `ca.jpa-qualification`, `jpa/` 45파일, `junit/` 2파일과 테스트) | `src/build-tools/` | `016597ac` | 소유자 결정 4(JPA evidence manifest 폐기). `config/`는 build-logic으로 이동 |
| `jpa-r2-evidence.yml`, integration-main `jpa-candidate-evidence` job | `.github/workflows/` | `016597ac` | JPA evidence manifest 폐기 |
| `JpaAdopterApiSurfaceTest` | `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/` | `016597ac` | `ca.api-surface` `adopterBaseline`으로 통합(BUILD-중복-3) |
| `GrpcStableReleaseGate`·`GrpcCompatibilityMatrix`·`GrpcReleaseDecision`·`GrpcReleaseEvidence`(+Test) | `src/grpc/grpc-testkit/src/{main,test}/java/dev/caskeleton/grpc/release/` | `016597ac` | 호출처가 자기 테스트뿐(S5-lead-4) |
| `GrpcAdvancedPromotionGate`·`…Decision`·`…Evidence`·`GrpcAdvancedSupportMatrix`(+Test) | `src/grpc-advanced/grpc-advanced-bootstrap/src/{main,test}/java/dev/caskeleton/grpc/advanced/release/` | `016597ac` | 같음 |
| `ca.public-path-snapshot`(publicpath 5파일 + renderer test) | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/publicpath/` | `016597ac` | app-bootstrap `PublicPathSnapshotTest`로(BUILD-O3-5) |
| `ca.archive-hygiene`(archive 5파일 + test) | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/archive/` | `016597ac` | leaf version에서 revision 제거로 stale jar가 생기지 않음 |
| `ca.developer-bootstrap`(`DeveloperBootstrapPlugin`, `BootstrapSmokeTask` + functional test) | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/bootstrap/` | `016597ac` | `scripts/bootstrap-local.sh`로 |
| `BuildVerificationPurityContractTest`(archive·public-path TestKit 10개) | `src/build-logic/src/test/java/dev/caskeleton/bootstrap/contract/` | `016597ac` | 대상 플러그인 삭제; public-path 케이스는 `PublicPathSnapshotTest`로 |
| `jpa-release.yml`, `fileserver-certification.yml` | `.github/workflows/` | `016597ac` | job을 `release.yml`로 이동(B2) |
(마지막으로 존재한 커밋은 이 묶음의 기준 HEAD `016597ac`. `6d27356e`에도 모두 존재한다.)
### 게이트에서 빠진 검사가 없는지
| 삭제·이동한 검사 | 지금 도는 곳 | 게이트 |
|---|---|---|
| `verifyJpaReadinessRegistry`(카드 구조·선행·task 존재·migration stream) | persistence-jpa `JpaReadinessRegistryTest` | `ci`(leaf `test`) |
| `verifyJpaCandidateEvidence`/`verifyJpaPrimaryFoundationEvidence`(JUnit XML selector·no-skip) | readiness 레인 `requires`(카드 인용 scenario 전부) + `rejectSkipped` | `integrationCheck`, `release.yml` `jpa-release-gate` |
| `verifyJpaReleaseGateTasks`(gate task 존재) | `jpaReleaseQualification` dependsOn(없는 task면 그래프 생성 실패) + `JpaReleaseRenderingTest` | release, `ci` |
| `jpaReleaseQualification`(루트) | persistence-jpa 같은 이름 태스크 | `release.yml` `jpa-release-gate` |
| `JpaAdopterApiSurfaceTest` | `:adapter:outbound:persistence-jpa:verifyJpaApiSurface` adopter 검사 | `ci`(leaf `check`) |
| `verifyEnvKeys`(build-tools) | build-logic `ca.config-contract`, 태스크 동일 | `mainCheck`(`configContractCheck`) |
| `verifyPublicPathSnapshot`/`updatePublicPathSnapshot`(플러그인) | `:app-bootstrap:publicPathSnapshotTest`(루트 별칭 `verifyPublicPathSnapshot`) + 렌더링 단위 테스트 3개(`test`) | `mainCheck`, `releaseCheck`, `ci`(단위) |
| `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` |
| `releaseCheck`의 `ci` | ci-quality-gates.yml `:ci`(PR·main push) | PR |
| fileserver-pr `architectureTest --tests '*Fileserver*'` | `:ci`의 `architectureCheck`(전체 ArchUnit) | PR |
### 실행한 검증
- `./gradlew -p build-logic test` PASS(78 tests, skip 0). build-tools는 삭제되어 없음.
- `./gradlew ci verifyDependencyLocks --continue --max-workers=2`: 1차 실패 = 새 테스트 4파일 Spotless(수정 `7fe5d754`) + `S3AsyncResponseBodyBridgeTest.oversizedSdkChunkFailsClosed` 1건(P16-new-4, 재실행 PASS). 2차 BUILD SUCCESSFUL(685 tasks).
- `./gradlew mainCheck --continue` BUILD SUCCESSFUL(새 main 단계 레인·MinIO 레인·publicPathSnapshotTest 실행 확인).
- `./gradlew integrationCheck --continue` BUILD SUCCESSFUL(14m). Redis topology 3개·AWS lane은 이유를 출력하고 빠짐, httpclient fault lane 2/2 PASS, sample `posterImageMigrationTest` 실행.
- `GIT_SHA=… ./gradlew releaseCheck` PASS, `./gradlew -p optional-platforms ci` PASS, `:app-bootstrap:verifyEnvKeys` PASS, `ci`/`mainCheck`/`integrationCheck`/`releaseCheck` `--dry-run --configuration-cache --configuration-cache-problems=fail` 모두 저장 가능, `:app-bootstrap:architectureTest`(sample 포함) 180/180.
## 새로 발견한 결함
- `P16-new-1` — fileserver workflow가 P4 이동 전 위치를 가리킴: `fileserver-certification.yml` `:app-bootstrap:test --tests '*FileserverDocumentationCoverageTest'`(지금 `composition:fileserver-platform`), `:application-core:test --tests '*FileserverObservabilityTest'`(지금 `application-fileserver`), full-verification이 `application-core`/`adapter:inbound:web` check, `fileserver-pr.yml` `:adapter:inbound:web:test --tests '*FileserverHardeningContractTest'`(지금 `web-fileserver`)와 경로 필터, `fileserver-nightly.yml`의 `application-core` 두 호출. **고침**(release.yml·fileserver-pr.yml·fileserver-nightly.yml).
- `P16-new-2` — `FileserverDocumentationCoverageTest`가 `docs/fileserver/`·`.github/workflows/`·web-fileserver 소스를 읽는데 `composition/fileserver-platform` `test` inputs에 선언이 없어 문서만 바꾸면 up-to-date로 건너뜀. **고침**(`src/composition/fileserver-platform/build.gradle`).
- `P16-new-3` — sample `PublishPosterImageUseCase.handle`이 `UUID.randomUUID()`로 멱등성 attempt id를 만듦(`NO_UUID_RANDOM_IN_CONTROLLER` 위반, sample이 ArchUnit 밖이라 안 보였음). **고침**(`ids.allocate()`).
- `P16-new-4` — `S3AsyncResponseBodyBridgeTest.oversizedSdkChunkFailsClosed` 간헐 실패(`expected "S3 response chunk exceeds the bounded bridge size" but was "S3 consumer did not read the exact response range"`) — 소비 스레드와 chunk 크기 검사 순서 경합으로 보임. 재실행 PASS. 고치지 않음(objectstorage 소유).
- `P16-new-5` — S1-#16 나머지: `NotificationIdGeneratorPort`·`UploadIdentifierFactory`를 domain `IdFactory` 기반으로 정리하는 작업은 남음(여러 leaf 변경).
- `P16-new-6` — persistence-fileserver의 공개 타입을 다른 leaf가 import하는 것은 이제 어떤 adopter 검사도 보지 않음(예전 정규식 테스트는 `…outbound.persistence.` 접두어 전체를 봤음). persistence-fileserver에 `ca.api-surface`를 붙일지 결정 필요.
- `P16-new-7` — `docs/study/postgresql-jpa-walkthrough.ko.md` §15.6 등이 삭제된 JPA evidence manifest·`verifyJpa*Evidence`를 설명함(결정 6, Wave 5 문서 갱신 대상). 고치지 않음.
@@ -540,12 +540,12 @@ Wave 1–2 구현 중 나온 질문에 대해 받은 7건(2026-09-28):
| O-3d | Required | 이 검사의 테스트가 0개 | 남음 | `git grep -l IgnoredSource -- src/build-logic/src/test src/app-bootstrap/src src/build-tools/src/test` 0건 | W4 | TestKit 케이스: integrationTest source set에 ignore 대상 패키지 → 실패, git 실패 → 실패 |
| O-4a | Required | app-bootstrap `test`가 선언 안 된 저장소 파일(runbook, `.env.example`)을 읽어 UP-TO-DATE 거짓 통과 | 완료 | `src/app-bootstrap/build.gradle:276-294` (`docs/**`, `*.example`, `.env*` 등을 `repositoryContractInputs`로 RELATIVE 선언). 커밋 `6d27356e` | - | - |
| O-4b | Required | messaging adapter test가 schema 파일을 sysprop으로 읽으면서 입력 미선언 | 완료 | `src/adapter/outbound/messaging/build.gradle:45-48` (`inputs.file(config/messaging/evidence/build-evidence-manifest-v1.schema.json)`). 커밋 `6d27356e` | - | - |
| O-4c | Required | CI에서 커밋마다 jar manifest version이 바뀌어 test·SpotBugs cache가 항상 miss | 남음 | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/release/ReleaseProvenancePlugin.java:29` (`GITHUB_SHA`), `src/build-logic/src/main/java/dev/caskeleton/buildlogic/java/JavaConventionsPlugin.java:65` (`Implementation-Version`), normalization 설정 0건 | W3 | 입력 선언이 끝났으므로(O-4a/b) `JavaConventionsPlugin`에 `normalization.runtimeClasspath.metaInf.ignoreAttribute("Implementation-Version")` 추가 |
| O-4c | Required | CI에서 커밋마다 jar manifest version이 바뀌어 test·SpotBugs cache가 항상 miss | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `JavaConventionsPlugin`에 runtime classpath `metaInf` 정규화(`Implementation-Version`·`Build-Revision` 무시), `src/build-logic/src/main/java/dev/caskeleton/buildlogic/java/JavaConventionsPlugin.java`. 재현: `GIT_SHA`만 바꿔 `:application-core:test` 두 번 실행 — 정규화 없이 재실행됨(FAIL, cache miss) → 정규화 후 `UP-TO-DATE`(PASS). 추가로 leaf version에서 revision을 뺐다(BUILD-O3-5) | - | 입력 선언이 끝났으므로(O-4a/b) `JavaConventionsPlugin`에 `normalization.runtimeClasspath.metaInf.ignoreAttribute("Implementation-Version")` 추가 |
| O-5a | Consider | 의존성 artifact checksum 검증(`verification-metadata.xml`)이 없음 | 보류 | `src/gradle/`에 `verification-metadata.xml` 없음 | - | 보류: lockfile로 버전은 고정됨, 의존성 갱신마다 metadata 재생성 부담을 지지 않음. 승인자: 저장소 소유자(2026-09-25) |
| O-5b | Consider | included build(build-logic/build-tools)의 plugin 의존성이 lock 없이 `gradlePluginPortal`에서 받아짐 | 완료 | Wave 1–2 P13 (fcddab7e·Wave 2 커밋): W1 `50cb2d9e`. `src/build-logic/build.gradle:9-12`, `src/build-tools/build.gradle:10-13`에 `dependencyLocking { lockAllConfigurations(); lockMode = STRICT }`. lockfile 커밋: `src/build-logic/gradle.lockfile`, `src/build-tools/gradle.lockfile`(+ `--write-locks`가 만든 `settings-gradle.lockfile` 2개, main build와 같은 형태). 재생성: `./gradlew -p build-logic dependencies --write-locks`(build-tools도 같음). 재현(FAIL): lockfile의 `spotless-plugin-gradle:8.6.0`을 `8.5.0`으로 바꾸고 `./gradlew -p build-logic compileJava` → `:compileJava FAILED ... Dependency version enforced by Dependency Locking`. 복원 후 `-p build-logic test` 80/80, `-p build-tools test` 35/35 통과. 범위 한계는 P13-new-1 참고. | - | `src/build-logic/build.gradle`에 `dependencyLocking { lockAllConfigurations() }` + lockfile 커밋(build-tools는 비울 예정이면 생략) |
| O-6 | Consider | 프로젝트 좌표 `dev.caskeleton:messaging-kafka` 중복(adapter vs vendored) | 완료 | `src/adapter/outbound/messaging-kafka/build.gradle:14-23` (`group = 'dev.caskeleton.adapter'`, `archivesName = 'adapter-outbound-messaging-kafka'`). 커밋 `6d27356e` | - | - |
| O-7 / BUILD-중복-1 / BUILD-바로할것-1 | Consider | runtime membership 검사가 방향 게이트와 중복 | 완료 | `ca.runtime-membership` 삭제: `src/build-logic/README.md:41`, `git ls-files src/build-logic \| grep RuntimeMembership` 0건. 커밋 `6d27356e`<br>BUILD-중복-1: `ca.runtime-membership` id·코드 grep 0건(`src/build-logic/build.gradle`), 삭제 표 `src/build-logic/README.md:41`. 컴파일러·방향 task·ArchUnit은 리뷰대로 유지<br>BUILD-바로할것-1: id·클래스 grep 0건, `src/build.gradle`에 적용 없음 | - | - |
| O-8 / BUILD-중복-2 / BUILD-바로할것-6 | Consider | "지정 테스트가 실행됐고 skip 없음" 검사 구현이 5개 | 남음 | 4개(`ca.strict-qualification`, `ca.conditional-transport-qualification`, `ca.graphql-platform`, `ca.evidence`)는 삭제되고 `strictTestLanes` + `RequiredTestExecution`으로 합쳐짐(`src/build-logic/README.md:42-44`). 남은 1개: `src/build-tools/src/main/java/dev/caskeleton/buildtools/junit/JUnitEvidenceReader.java` (사용처 `src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/JpaEvidenceTestResultLocator.java`뿐)<br>BUILD-중복-2: 3개 남음: `StrictLaneExecutionTracker`(정본), `RedisTopologyExecutionTracker`(`src/build-logic/src/main/java/dev/caskeleton/buildlogic/redis/RedisTopologyLanePlugin.java:81`, 소유자 결정으로 유지), `JUnitEvidenceReader`(`src/build-tools/src/main/java/dev/caskeleton/buildtools/junit/`, `JpaEvidenceTestResultLocator`가 사용). RejectSkippedTestsListener·JUnitEvidence·MongoJUnitXml은 grep 0건<br>BUILD-바로할것-6: `MongoJUnitXml` 삭제. `JUnitEvidenceReader`는 JPA evidence 전용으로 남음(`src/build-tools/src/main/java/dev/caskeleton/buildtools/junit/JUnitEvidenceReader.java`) | W3 | 소유자 결정대로 JPA evidence manifest(`ca.jpa-evidence`, `ca.jpa-qualification`)를 leaf 테스트로 옮길 때 `buildtools/junit/` 패키지를 함께 삭제<br>BUILD-중복-2: JPA evidence를 폐기할 때 `junit` 패키지(138+76줄)도 같이 삭제<br>BUILD-바로할것-6: BUILD-O3-2와 같이 삭제 |
| O-8 / BUILD-중복-2 / BUILD-바로할것-6 | Consider | "지정 테스트가 실행됐고 skip 없음" 검사 구현이 5개 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): build-tools `junit` 패키지(`JUnitEvidenceReader`)를 JPA evidence와 함께 삭제(`de075afe`). 남은 "지정 테스트 실행·skip 없음" 구현은 `StrictLaneExecutionTracker`(정본)와 `RedisTopologyExecutionTracker`(소유자 결정 4로 유지) 둘 | - | 소유자 결정대로 JPA evidence manifest(`ca.jpa-evidence`, `ca.jpa-qualification`)를 leaf 테스트로 옮길 때 `buildtools/junit/` 패키지를 함께 삭제<br>BUILD-중복-2: JPA evidence를 폐기할 때 `junit` 패키지(138+76줄)도 같이 삭제<br>BUILD-바로할것-6: BUILD-O3-2와 같이 삭제 |
| O-9 / BUILD-계획-B6 / BUILD-바로할것-2 | Consider | quarantine job이 테스트 0개를 돌리려고 저장소 전체를 컴파일 | 완료 | `.github/workflows/ci-quality-gates.yml`에 quarantine job 없음, `git grep quarantineTest 6d27356e -- src .github` 0건(README 제외), `src/build-logic/README.md:46`. 커밋 `6d27356e`<br>BUILD-계획-B6: quarantine grep 0건. jmh는 `me.champeau.jmh`로 3개 leaf에 적용, 수동 실행 전용(`src/build.gradle:11-12` "never part of a gate")<br>BUILD-바로할것-2: `JavaConventionsPlugin`, `src/build.gradle`, workflow에서 `quarantineTest` grep 0건 | - | - |
| O-10a | Nit | httpclient build가 같은 sysprop 3줄을 7번 반복 | 남음 | `src/adapter/outbound/httpclient/build.gradle:136-139,160-163,171-174,186-189,195-198,214-217,228-231` | W5 | `tasks.withType(Test).configureEach { ... }` 한 블록으로 |
| O-10b | Nit | `user.timezone=UTC`가 leaf build 파일 11개에 28번 반복 | 남음 | `git grep -c user.timezone -- '*.gradle'` (예: `src/adapter/inbound/web/build.gradle` 5번, `src/app-bootstrap/build.gradle` 4번), `JavaConventionsPlugin`에는 없음 | W5 | `JavaConventionsPlugin`에 `withType(Test).configureEach { systemProperty("user.timezone", "UTC") }` 한 번 넣고 leaf 줄 삭제 |
@@ -570,42 +570,42 @@ Wave 1–2 구현 중 나온 질문에 대해 받은 7건(2026-09-28):
| ID | 심각도 | 요약 | 상태 | 근거 | Wave | 수정 방향 |
|---|---|---|---|---|---|---|
| BUILD-결론-1 | 권고 | 빌드 코드가 목적에 비해 너무 큼(16,768줄 중 아키텍처 검사 13%) | 남음 | 현재 Java(main+test) build-logic 6,184 + build-tools 4,320 = 10,504줄. O3 목표는 3.5–4k줄 | W3 | BUILD-O3-2·5·6 진행으로 줄인다 |
| BUILD-결론-2 | 권고 | 기능별 증거 검사(E)가 46%로 가장 큰 덩어리 | 남음 | notification·messaging·mongo 플러그인은 삭제됨(`6d27356e`). 남은 E: build-tools `jpa` 2,701+706줄, `junit` 138+76줄, build-logic `redis` 270+151줄(소유자 결정으로 유지) | W3 | JPA evidence 폐기(BUILD-O3-2) |
| BUILD-결론-1 | 권고 | 빌드 코드가 목적에 비해 너무 큼(16,768줄 중 아키텍처 검사 13%) | 남음 | 현재 Java(main+test) build-logic 6,184 + build-tools 4,320 = 10,504줄. O3 목표는 3.5–4k줄<br>Wave 3 W3-P16: 미완 — build-logic+build-tools Java 10,504줄 → build-logic 6,185줄(main 4,184 + test 2,001; build-tools 0). 목표 3.5–4k에는 BUILD-O3-5 나머지(auxiliary → jvm-test-suite, release-provenance 제거)가 필요 | W3 | BUILD-O3-2·5·6 진행으로 줄인다 |
| BUILD-결론-2 | 권고 | 기능별 증거 검사(E)가 46%로 가장 큰 덩어리 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): 기능별 evidence 검사 중 JPA(`jpa/` 2,701+706줄, `junit/` 138+76줄) 삭제. 남은 E는 redis topology(소유자 결정 4로 유지) | - | JPA evidence 폐기(BUILD-O3-2) |
| BUILD-결론-3 | 권고 | 아키텍처 게이트(방향 task·ArchUnit)는 크기가 적정하니 유지 | 완료 | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java:58-223` 방향·순수성·ignored-source 유지, `src/app-bootstrap/build.gradle:45-52` architectureTest 레인 유지 | - | - |
| BUILD-결론-4 | 권고 | 09-16 단계 분리 계획이 절반만 이행됨(2단계 게이트가 PR에서 돎) | 남음 | 루트 `ci`는 leaf check + architecture + quality만(`src/build.gradle:127-132`). 남은 것은 BUILD-계획-B2·B3·B4-17·B4-27·B4-28·B4-30·C 행 | W3 | 해당 행 참고 |
| BUILD-중복-3 | 권고 | API surface 검사 구현이 3개 | 남음 | Notification 정규식 verifier 삭제, `ca.api-surface` 하나로 graphql·notification·jpa·mongo 처리. JPA adopter 검사는 import 정규식 테스트로 따로 남음: `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/JpaAdopterApiSurfaceTest.java:29-60` | W3 | BUILD-바로할것-7과 같음 |
| BUILD-결론-4 | 권고 | 09-16 단계 분리 계획이 절반만 이행됨(2단계 게이트가 PR에서 돎) | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): 하위 행으로 추적: B2·B4-17·B4-27·B4-28·B4-30·중복-6 완료, B3의 "변경 모듈만 실행"과 C는 보류(각 행) | - | 해당 행 참고 |
| BUILD-중복-3 | 권고 | API surface 검사 구현이 3개 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `ca.api-surface`에 `adopterBaseline`/`adopterSources` 추가(javac로 import 파싱, adopter 목록 ⊆ 공개 surface 확인): `ApiSurfacePlugin`, `VerifyApiSurfaceTask`, `ApiSurfacePolicy.verifyAdopters`, `JavaPublicTypes.imports`. `ApiSurfaceConventionTest.anAdopterImportOutsideTheAdopterBaselineFailsTheVerification`·`anAdopterImportTheAdopterBaselineListsPasses`·`anAdopterBaselineEntryTheSurfaceNoLongerHasFailsTheVerification` FAIL(fixture가 없는 `adopterBaseline` 속성을 씀)→PASS. `JpaAdopterApiSurfaceTest` 삭제, persistence-jpa `apiSurface { adopterBaseline … }` | - | BUILD-바로할것-7과 같음 |
| BUILD-중복-4 | 권고 | fileserver 제외 규칙이 registry와 dependencyPolicy에서 서로 모순 | 완료 | `ca.dependency-policy` 삭제. fileserver는 선택형 capability `composition-fileserver-platform`으로 바뀜(`src/app-bootstrap/build.gradle:152` 주석 처리된 runtimeOnly 줄) | - | - |
| BUILD-중복-5 | 권고 | 빌드 단계 HS1 구멍: 순수성 task가 application-*만 봄 | 완료 | `ArchitecturePlugin.java:143-147,219-223` `isPure`에 domain-core·shared-contract 추가 | - | - |
| BUILD-중복-6 | 권고 | CI가 아키텍처 게이트를 여러 번 반복 실행 | 남음 | notification-platform·fileserver-certification·jpa-release의 중복 호출은 삭제 확인. 남은 것: `releaseCheck`가 `ci`를 통째로 다시 돌림(`src/build.gradle:148-154`, `.github/workflows/release.yml:60`), `.github/workflows/fileserver-pr.yml:53`의 `:app-bootstrap:architectureTest --tests '*Fileserver*'`(같은 PR의 ci-quality-gates와 중복) | W3 | `releaseCheck`에서 `ci` 의존을 빼고 tag 전용 검사만 남긴다. fileserver-pr의 architectureTest 호출은 삭제한다 |
| BUILD-중복-7 | 권고 | 기능 전용 플러그인 5개가 root에 적용됨 | 남음 | root에 기능 플러그인이 1개 남음: `ca.jpa-qualification`(`src/build.gradle:20`) | W3 | JPA evidence를 폐기할 때 root 적용도 제거(BUILD-O3-2) |
| BUILD-중복-8 | 권고 | ArchUnit이 모든 leaf를 보지 않음 | 남음 | websocket·grpc 어댑터는 이제 포함됨(`src/app-bootstrap/build.gradle:116-128,155` capabilityProjects를 architectureTestRuntimeOnly로). 여전히 제외: optional-platforms build의 `grpc:*`·`grpc-advanced:*` leaf(registry에 등록됨, `src/optional-platforms/build.gradle`의 `ci`는 `verifyCleanArchitectureDependencies`만 실행)와 `sample-portfolio`. 같은 파일 `:111` 주석은 "architecture suite sees every module"이라고 적혀 있음 | W3 | 결정(2026-09-25): sample-portfolio를 app-bootstrap ArchUnit 대상에 다시 넣고, optional-platforms는 Gradle 방향 게이트로 충분하다고 주석·문서에 명시 |
| BUILD-중복-6 | 권고 | CI가 아키텍처 게이트를 여러 번 반복 실행 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `releaseCheck`에서 `ci` 의존 제거(`src/build.gradle` releaseCheck = `verifyReleaseProvenance` + `verifyPublicPathSnapshot`), `fileserver-pr.yml`의 `:app-bootstrap:architectureTest --tests '*Fileserver*'` 삭제. `DeveloperExperienceContractTest.architectureWorkflowSelectorsUseTheArchitectureSourceSetTask`를 새 계약(PR `:ci`에서 한 번)으로 수정 | - | `releaseCheck`에서 `ci` 의존을 빼고 tag 전용 검사만 남긴다. fileserver-pr의 architectureTest 호출은 삭제한다 |
| BUILD-중복-7 | 권고 | 기능 전용 플러그인 5개가 root에 적용됨 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): 루트 `id 'ca.jpa-qualification'` 삭제(`de075afe`). 루트에 남은 플러그인은 `ca.release-provenance`, `ca.architecture` | - | JPA evidence를 폐기할 때 root 적용도 제거(BUILD-O3-2) |
| BUILD-중복-8 | 권고 | ArchUnit이 모든 leaf를 보지 않음 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `src/app-bootstrap/build.gradle` `architectureTestRuntimeOnly project(':sample-portfolio')` + optional-platforms는 Gradle 방향 게이트로 충분하다는 주석. sample을 넣자 `ForbiddenApiArchitectureTest.NO_UUID_RANDOM_IN_CONTROLLER` FAIL(`PublishPosterImageUseCase.handle`의 `UUID.randomUUID()`) → id 포트(`ids.allocate()`)로 고쳐 PASS(`:app-bootstrap:architectureTest` 180/180). app-bootstrap lockfile 재생성(+1줄) | - | 결정(2026-09-25): sample-portfolio를 app-bootstrap ArchUnit 대상에 다시 넣고, optional-platforms는 Gradle 방향 게이트로 충분하다고 주석·문서에 명시 |
| BUILD-계획-A | 권고 | Track A: 망가진 게이트 24건 | 완료 | 리뷰 시점에 이미 완료. workflow에서 `*CleanArchitectureTest` 필터 grep 0건 | - | - |
| BUILD-계획-B2 | 권고 | release workflow를 1개로 | 남음 | tag `v*`에서 도는 workflow가 여전히 3개: `.github/workflows/release.yml:36`, `jpa-release.yml:14`, `fileserver-certification.yml:28` | W3 | jpa·fileserver의 tag job을 release.yml의 job으로 옮기고, 두 파일의 tag 트리거를 삭제 |
| BUILD-계획-B3 | 권고 | PR에서는 변경된 모듈만 실행 | 남음 | PR마다 모든 leaf의 `:ci` 실행(`.github/workflows/ci-quality-gates.yml:50`). `object-storage-qualification.yml:4`는 경로 필터 없는 `pull_request`로 MinIO 컨테이너를 띄우고, 같은 레인이 `src/adapter/outbound/objectstorage/build.gradle:96-98` `check`에도 걸려 있어 `ci`에서 한 번 더 돎 | W3 | object-storage-qualification에 경로 필터를 달거나 PR 트리거 제거. MinIO 레인은 objectstorage `check`에서 떼어 main 단계로. `ci`의 변경 모듈 한정은 따로 설계 |
| BUILD-계획-B2 | 권고 | release workflow를 1개로 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `jpa-release.yml`·`fileserver-certification.yml`의 job을 `release.yml`로 옮기고 두 파일 삭제, `app-image-release`가 `jpa-release-promotion`·`jpa-registry-and-docs`·fileserver 4 job을 `needs`. `JpaReleaseRenderingTest`는 `release.yml`을 읽고, `FileserverDocumentationCoverageTest`는 `fileserver-*.yml` + `release.yml`의 job id를 읽음(둘 다 PASS) | - | jpa·fileserver의 tag job을 release.yml의 job으로 옮기고, 두 파일의 tag 트리거를 삭제 |
| BUILD-계획-B3 | 권고 | PR에서는 변경된 모듈만 실행 | 보류 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): 구현한 부분: `object-storage-qualification.yml` PR 트리거에 경로 필터, MinIO 두 레인을 objectstorage `check`에서 `mainCheck`로(`src/adapter/outbound/objectstorage/build.gradle`). 남은 "PR `ci`를 변경 모듈만 실행"은 영향 모듈 계산 방식(Gradle 의존 그래프 역추적·경로 매핑)과 누락 위험 수용 범위를 정해야 하고 로컬에서 검증할 수 없음. 승인자: 저장소 소유자 결정 필요 | W3 | object-storage-qualification에 경로 필터를 달거나 PR 트리거 제거. MinIO 레인은 objectstorage `check`에서 떼어 main 단계로. `ci`의 변경 모듈 한정은 따로 설계 |
| BUILD-계획-B4-15 | 권고 | conditional-transport 레인을 PR에서 main으로 | 완료 | 집계 task(`src/build.gradle:111-118`)가 `mainCheck`(`:143`)에만 연결됨. 각 레인은 leaf `check`에 연결되지 않음 | - | - |
| BUILD-계획-B4-17 | 권고 | API surface를 PR에서 main으로 | 남음 | Gradle 쪽은 완료: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/ApiSurfacePlugin.java:96-101`에서 leaf `mainCheck`에 연결. PR에 남은 것: `.github/workflows/notification-platform.yml:84-86` PR job이 `verifyNotificationApiSurface` 실행 | W3 | notification-platform.yml PR job에서 API surface step을 빼고 main push·nightly job으로 옮김 |
| BUILD-계획-B4-17 | 권고 | API surface를 PR에서 main으로 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): 결정 20: API surface는 PR(`check`)에서 돈다(NEW-13d). notification-platform.yml PR job의 별도 `verifyNotificationApiSurface` step은 같은 job의 `:adapter:outbound:notification:check -x test`가 이미 돌리므로 삭제("PR에서 main으로" 방향은 결정 20에 따라 닫음) | - | notification-platform.yml PR job에서 API surface step을 빼고 main push·nightly job으로 옮김 |
| BUILD-계획-B4-18 | 권고 | public-path 스냅샷을 PR에서 main으로 | 완료 | `ci-quality-gates.yml:50`에서 빠짐. `src/build.gradle:142`(mainCheck), `:153`(releaseCheck) | - | - |
| BUILD-계획-B4-22 | 권고 | verifyEnvKeys를 PR에서 main으로 | 완료 | `configContractCheck`(`src/build.gradle:75-79`)는 `mainCheck`(`:139`)에만 연결됨. notification-platform.yml의 호출도 삭제됨 | - | - |
| BUILD-계획-B4-23 | 권고 | graphql stable 레인을 PR에서 main으로 | 완료 | `src/build.gradle:144` mainCheck. graphql `check`에는 연결 없음. jar 검사는 leaf 테스트 `GraphQlProductionClassesTest`로 | - | - |
| BUILD-계획-B4-26 | 권고 | JPA evidence/qualification을 PR에서 main/tag로 | 완료 | jpa `check`와의 연결이 끊김. readiness는 `src/adapter/outbound/persistence-jpa/build.gradle:262-264`에서 mainCheck, candidate는 `.github/workflows/integration-main.yml:130-145`, release는 `jpa-release.yml`. 폐기는 BUILD-O3-2 | - | - |
| BUILD-계획-B4-27 | 권고 | notification API surface·evidence를 PR에서 main으로 | 남음 | API surface는 B4-17. evidence는 leaf 테스트 `NotificationEvidenceVerifierTest`로 옮겨져 `test`, 즉 PR의 `ci`에서 돎(`src/adapter/outbound/notification/build.gradle:79-94` inputs) | W3 | 문서 대조 테스트에 태그를 달아 `test`에서 빼고, `strictTestLanes` 레인(rejectSkipped)으로 만들어 leaf `mainCheck`에 연결 |
| BUILD-계획-B4-28 | 권고 | notification-configuration을 PR에서 main으로 | 남음 | env-keys.yaml과 대조하는 `NotificationEnvironmentRegistryTest`가 composition/notification-platform의 `test`에서 PR로 돎(`src/composition/notification-platform/build.gradle:31-35`) | W3 | B4-27과 같은 방식으로 main 레인에 둠 |
| BUILD-계획-B4-30 | 권고 | mongo-verification을 PR에서 main으로 | 남음 | 플러그인은 삭제. release-contracts.json과 대조하는 `MongoTestLaneContractTest`가 `test`, 즉 PR에서 돎(`src/adapter/outbound/persistence-mongo/build.gradle:224-231`) | W3 | B4-27과 같은 방식 |
| BUILD-계획-B4-27 | 권고 | notification API surface·evidence를 PR에서 main으로 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `NotificationEvidenceVerifierTest.repositorySupportMatrixClaimsNoMoreThanTheManifestProves`에 `@Tag("document-contract")`, 레인 `notificationDocumentContractTest`(`mainStage()`, `rejectSkipped`) → leaf `mainCheck`. fixture 케이스는 `test`에 남음. `test` inputs 선언 제거(레인은 항상 실행). `StrictTestLaneConventionTest.aMainStageLaneLeavesTheLeafTestTaskAndJoinsMainCheck` FAIL→PASS | - | 문서 대조 테스트에 태그를 달아 `test`에서 빼고, `strictTestLanes` 레인(rejectSkipped)으로 만들어 leaf `mainCheck`에 연결 |
| BUILD-계획-B4-28 | 권고 | notification-configuration을 PR에서 main으로 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `NotificationEnvironmentRegistryTest`에 태그, 레인 `notificationEnvironmentContractTest`(`src/composition/notification-platform/build.gradle`) | - | B4-27과 같은 방식으로 main 레인에 둠 |
| BUILD-계획-B4-30 | 권고 | mongo-verification을 PR에서 main으로 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `MongoTestLaneContractTest`에 태그, 레인 `mongoDocumentContractTest`(`src/adapter/outbound/persistence-mongo/build.gradle`). `mainCheck` 실행에서 세 레인 모두 실행 확인 | - | B4-27과 같은 방식 |
| BUILD-계획-B4-34 | 권고 | qualificationCheck/systemTestCheck를 PR에서 main으로 | 완료 | `ci`에서 빠지고 `mainCheck`(`src/build.gradle:140`)로 이동. 참고: `src/app-bootstrap/build.gradle:71-73`의 `check`→`systemTestLaneCheck`(기본 조립 기동 `DefaultCompositionBootTest` 등 4개 클래스)는 `208077fd`에도 있었고 지금도 PR에서 돎 | - | - |
| BUILD-계획-B4-35 | 권고 | sampleWebContractCheck·configContractCheck를 PR에서 main으로 | 완료 | `src/build.gradle:139,141` mainCheck. `ci`(`:127-132`)에는 없음 | - | - |
| BUILD-계획-B5 | 권고 | gate matrix가 release 차단을 실제로 강제하도록 연결 | 해당 없음(코드 삭제) | matrix 파일 삭제(`.github/ci-gate-matrix.yml` 없음, `ci-quality-gates.yml:5-10` 주석) | - | - |
| BUILD-계획-C | 권고 | 컨테이너 이미지 서명 | 남음 | release.yml에 GHCR push·Trivy는 있음. `cosign`/`attest` grep 0건 | W3 | release.yml의 push 다음에 cosign keyless 서명 step 추가(`id-token: write`) |
| BUILD-계획-C | 권고 | 컨테이너 이미지 서명 | 보류 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): 서명 대상(GHCR push)과 keyless OIDC 토큰은 tag 실행에서만 있어 로컬 검증 불가. 이 workflow는 제3자 action 대신 체크섬 고정 바이너리를 설치하는 정책인데, 이 환경에서 cosign 릴리스 체크섬을 확인할 수 없어 확인하지 않은 체크섬·action SHA를 넣지 않음. 결정할 것: cosign 버전·설치 방식(체크섬 고정 vs `sigstore/cosign-installer` SHA 고정), image job에 `id-token: write` 부여. 승인자: 저장소 소유자 결정 필요 | W3 | release.yml의 push 다음에 cosign keyless 서명 step 추가(`id-token: write`) |
| BUILD-O3-1 | 권고 | O3: 기능 검사를 소유 leaf 테스트로(notification·messaging·mongo·graphql) | 완료 | build-tools id 6개 삭제(`src/build-tools/build.gradle`에 jpa-evidence·config-contract·jpa-qualification만 남음). leaf 테스트 추가(`6d27356e`): `NotificationEvidenceVerifierTest`, `NotificationEnvironmentRegistryTest`, `MessagingEvidenceSchemaValidatorTest`, `MongoTestLaneContractTest`, `GraphQlProductionClassesTest`. 읽는 파일은 `test` inputs로 선언됨. 실행 단계 문제는 B4-27·28·30 | - | - |
| BUILD-O3-2 | 권고 | O3: JPA evidence manifest(`ca.jpa-evidence`, `ca.jpa-qualification`) 폐기, leaf 테스트로 | 남음 | 소유자가 폐기로 결정함. 코드는 그대로 남아 있음: `src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/` 2,701+706줄, `src/build.gradle:20`, `src/adapter/outbound/persistence-jpa/build.gradle:5,262-264`, `.github/workflows/integration-main.yml:130-145`, `jpa-r2-evidence.yml:34`, `jpa-release.yml:120-125` | W3 | 두 플러그인과 `junit` 패키지를 삭제하고, readiness/release registry 검사만 persistence-jpa 테스트(inputs 선언)로 옮김. workflow의 evidence task 호출도 정리 |
| BUILD-O3-2 | 권고 | O3: JPA evidence manifest(`ca.jpa-evidence`, `ca.jpa-qualification`) 폐기, leaf 테스트로 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): build-tools `jpa/`·`junit/`, `ca.jpa-evidence`·`ca.jpa-qualification` 삭제. readiness 카드 검사 → `JpaReadinessRegistryTest`(persistence-jpa `test`, 입력 `readiness-cards.yaml`·`src/postgresqlIntegrationTest/java` 선언). `everyImplementedCardNamesTasksThisLeafDeclares` FAIL(삭제된 `verifyJpaPrimaryFoundationEvidence`를 가리키던 카드, AssertionError at :106) → 카드를 `integrationTestLaneCheck`로 고쳐 PASS. 카드가 인용한 scenario는 readiness 레인의 `requires` + `rejectSkipped`로(manifest가 JUnit XML로 확인하던 것). `jpaReleaseQualification`은 leaf 집계 태스크(registry의 blocking gate를 dependsOn). workflow: `jpa-r2-evidence.yml`, integration-main `jpa-candidate-evidence` 삭제 | - | 두 플러그인과 `junit` 패키지를 삭제하고, readiness/release registry 검사만 persistence-jpa 테스트(inputs 선언)로 옮김. workflow의 evidence task 호출도 정리 |
| BUILD-O3-3 | 권고 | O3: verifyEnvKeys 위치 | 완료 | 소유자 결정은 bootstrap에 유지. 현재 `src/app-bootstrap/build.gradle:5`(`ca.config-contract`), `src/build.gradle:75-79`→mainCheck | - | - |
| BUILD-O3-4 | 권고 | O3: redis topology lane을 strict lane으로 흡수 | 완료 | 소유자 결정은 유지. `src/build-logic/src/main/java/dev/caskeleton/buildlogic/redis/` 유지, `.github/workflows/redis-sdk-topology.yml` 경로 필터 PR | - | - |
| BUILD-O3-5 | 권고 | O3: build-logic에는 코어·컨벤션·레인 하나만 남김(인벤토리 #11·#18·#19·#20·#31) | 남음 | 남은 비핵심 플러그인(main+test 줄 수): publicpath 288+37, archive 216+46, release 138+71, bootstrap(developer-bootstrap·bootrun-dotenv) 328+203, auxiliary 151+145. leaf 버전은 아직 SHA 버전(`src/build-logic/src/main/java/dev/caskeleton/buildlogic/java/JavaConventionsPlugin.java:36-39`) | W3 | public-path는 app-bootstrap approval test로, release-provenance는 `springBoot { buildInfo() }`로 바꾸고, leaf 버전 고정 후 archive-hygiene 삭제. developer-bootstrap은 `scripts/`로, auxiliary는 `jvm-test-suite`로 |
| BUILD-O3-6 | 권고 | O3: build-tools를 비움 | 남음 | 남은 것: `config`(verifyEnvKeys) 488+211줄, `jpa`, `junit`(`src/settings.gradle:6` includeBuild) | W3 | JPA 폐기 후 `ConfigContractPlugin`을 build-logic으로 옮기고 `includeBuild('build-tools')` 삭제. task는 계속 `:app-bootstrap:verifyEnvKeys` |
| BUILD-O3-5 | 권고 | O3: build-logic에는 코어·컨벤션·레인 하나만 남김(인벤토리 #11·#18·#19·#20·#31) | 남음 | 남은 비핵심 플러그인(main+test 줄 수): publicpath 288+37, archive 216+46, release 138+71, bootstrap(developer-bootstrap·bootrun-dotenv) 328+203, auxiliary 151+145. leaf 버전은 아직 SHA 버전(`src/build-logic/src/main/java/dev/caskeleton/buildlogic/java/JavaConventionsPlugin.java:36-39`)<br>Wave 3 W3-P16: 미완 — 완료: public-path → app-bootstrap `PublicPathSnapshotTest`(main 단계 레인 `publicPathSnapshotTest`, 루트 별칭 `verifyPublicPathSnapshot`, 승인 `-PapprovePublicPathChange`; 기준선은 헤더의 명령만 바뀜), developer-bootstrap → `scripts/bootstrap-local.sh`, leaf version에서 revision 제거 후 archive-hygiene 삭제, app-bootstrap `springBoot.buildInfo`(`build.revision`, `time` 제외). 남음: (1) `ca.release-provenance` 플러그인 제거 — `src/optional-platforms/build.gradle`이 적용하고 있어 이번 Wave에서 건드리지 않기로 한 gRPC build 파일 수정이 필요, (2) auxiliary → `jvm-test-suite` — grpc·messaging 포함 14개 leaf build 파일을 바꾸는 작업이라 동시 묶음과 충돌. 둘 다 다음 순차 작업으로 | W3 | public-path는 app-bootstrap approval test로, release-provenance는 `springBoot { buildInfo() }`로 바꾸고, leaf 버전 고정 후 archive-hygiene 삭제. developer-bootstrap은 `scripts/`로, auxiliary는 `jvm-test-suite`로 |
| BUILD-O3-6 | 권고 | O3: build-tools를 비움 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `config` 패키지를 `dev.caskeleton.buildlogic.config`로 이동(테스트 2개 포함), `includeBuild('build-tools')`·Dockerfile `COPY build-tools/`·build-logic.yml step 삭제, `src/build-tools` 삭제. 태스크는 `:app-bootstrap:verifyEnvKeys` 그대로(PASS) | - | JPA 폐기 후 `ConfigContractPlugin`을 build-logic으로 옮기고 `includeBuild('build-tools')` 삭제. task는 계속 `:app-bootstrap:verifyEnvKeys` |
| BUILD-바로할것-1b | Nit | runtime-membership 삭제 후 남은 주석 문구 | 남음 | `src/sample-portfolio/build.gradle:175`, `.github/workflows/ci-quality-gates.yml:55` "runtime-membership policy" | W5 | 두 주석에서 해당 문구 삭제 |
| BUILD-바로할것-4 | 권고 | `ca.strict-qualification`을 `strictTestLanes` requires + rejectSkipped로 (= O-8) | 완료 | `strictQualification` grep 0건, id 없음. 예: `src/app-bootstrap/build.gradle:61-68` 레인 `requires`+`rejectSkipped` | - | - |
| BUILD-바로할것-5 | 권고 | `ca.evidence` 삭제, conditional-transport를 레인으로 (= O-8) | 완료 | 두 id 모두 없음. leaf별 레인 3개 + app-bootstrap 레인 1개를 루트 `conditionalTransportQualification`(`src/build.gradle:111-118`)이 모음 | - | - |
| BUILD-바로할것-7 | 권고 | API surface 구현을 하나로 | 남음 | `JpaAdopterApiSurfaceVerifier`가 import 정규식 테스트로 바뀌어 남음(`JpaAdopterApiSurfaceTest.java:29-60`, 기준선 `docs/architecture/jpa-adopter-api-surface.txt`) | W3 | 리뷰 권고대로 adopter 목록을 `ca.api-surface` 기준선(`docs/architecture/jpa-api-surface.txt`)에 합치고 테스트 삭제 |
| BUILD-바로할것-7 | 권고 | API surface 구현을 하나로 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): BUILD-중복-3과 같음. adopter 목록 파일(`docs/architecture/jpa-adopter-api-surface.txt`)은 따로 두되 구현은 `ca.api-surface` 하나(surface 기준선은 렌더링이 재생성하므로 표시를 섞지 않음). persistence-fileserver 타입 `FileserverSchemaActivation` 항목은 JPA surface가 아니어서 제거 | - | 리뷰 권고대로 adopter 목록을 `ca.api-surface` 기준선(`docs/architecture/jpa-api-surface.txt`)에 합치고 테스트 삭제 |
| BUILD-바로할것-8 | 권고 | `dependency-policy`를 Gradle 기본 기능으로 대체 | 완료 | 플러그인 삭제. `componentSelection` 거부 규칙: `src/adapter/outbound/notification/build.gradle:58-64`, `src/adapter/outbound/messaging/build.gradle:36-42`. fileserver는 registry·opt-in으로 처리 | - | - |
| BUILD-바로할것-9 | 권고 | 순수성 task 필터에 domain-core·shared-contract 추가 | 완료 | `ArchitecturePlugin.java:219-223` | - | - |
| BUILD-바로할것-10 | 권고 | workflow에서 아키텍처 게이트 중복 실행 제거 | 완료 | notification-platform(`:81-83` 주석으로 대체), fileserver-certification, jpa-release(`:115-125`)에서 `verifyCleanArchitectureDependencies`·`architectureTest` 호출 삭제. 남은 중복은 BUILD-중복-6 | - | - |
@@ -613,7 +613,7 @@ Wave 1–2 구현 중 나온 질문에 대해 받은 7건(2026-09-28):
| BUILD-바로할것-12a | 권고 | `ci`에서 configContractCheck·qualificationCheck·sampleWebContractCheck 제거 | 완료 | `src/build.gradle:127-132` | - | - |
| BUILD-바로할것-12b | 권고 | PR workflow에서 `:verifyPublicPathSnapshot` 제거 | 완료 | `.github/workflows/ci-quality-gates.yml:50` `:ci :verifyDependencyLocks`만 | - | - |
| BUILD-바로할것-12c | 권고 | graphqlStable·conditionalTransport·jpa-candidate·configuration-cache를 main 단계로 | 완료 | `src/build.gradle:143-144` mainCheck. `integration-main.yml:85-128` configuration-cache, `:130-145` jpa-candidate-evidence | - | - |
| BUILD-바로할것-12d | 권고 | notification·jpa·mongo·api-surface 검사를 leaf `check`에서 `mainCheck`로 | 남음 | api-surface·JPA readiness는 mainCheck로 옮김. notification evidence·env registry, mongo lane contract는 leaf `test`(PR)로 옮겨져 여전히 PR에서 돎. 상세는 B4-27·28·30 | W3 | B4-27과 같은 방식 |
| BUILD-바로할것-12d | 권고 | notification·jpa·mongo·api-surface 검사를 leaf `check`에서 `mainCheck`로 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): api-surface 부분은 결정 20에 따라 PR `check`로(반대 방향 행을 결정 20으로 닫음). notification evidence·env registry·mongo lane contract는 B4-27·28·30의 main 단계 레인 | - | B4-27과 같은 방식 |
| BUILD-바로할것-12e | 권고 | build-logic·build-tools job에 경로 필터 | 완료 | `.github/workflows/build-logic.yml:3-16` paths | - | - |
| BUILD-순수성 | 권고 | domain-core 순수성 구멍(빌드 단계 순수성 검사가 application-*만 봄) | 완료 | `ArchitecturePlugin.java:143-147`(주석·루프), `:219-223`(`isPure`) | - | - |
| BUILD-순수성-이름 | Nit | 순수성 task·클래스 이름이 아직 application-core만 가리킴 | 남음 | `ArchitecturePlugin.java:62` `verifyApplicationCoreDependencyPurity`, `:177` `VerifyApplicationCoreDependencyPurityTask`, `:181` 설명 "this application module" | W5 | `verifyPureModuleDependencies` 같은 이름으로 바꾸고 문서의 명령도 함께 수정 |
@@ -683,7 +683,7 @@ Wave 1–2 구현 중 나온 질문에 대해 받은 7건(2026-09-28):
| X1-지도-Admission / in-flight | 권고 | 유지하되 gRPC check-then-increment는 `Semaphore`로 (= N-5) | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): N-5a와 같은 수정. `Semaphore` 대신 한 락: in-flight와 queued 두 카운터를 한 결정에서 함께 봐야 해서 semaphore 두 개로는 원자적으로 안 된다. `GrpcAdmissionController.java:52`, `GrpcAdmissionControllerTest` | - | X1-#10a |
| X1-지도-Kafka producer | 권고 | legacy seam·platform 2개, 둘 다 TLS/SASL 없음 → outbox 정리에 포함 | 남음 | platform producer는 Wave 1(1-4)에서 보안 적용. legacy `KafkaSenderAutoConfiguration.java:60-80` `kafkaSeamProducer`에 `security.protocol`·SASL·SSL 설정 없음 | W1 | X1-#1f |
| X1-지도-파일 control plane / canonical JSON | 권고 | 소비자 0인 `FilePublicationPort` plane 삭제, parser 3개 → 1개 | 완료 | publication R1/R2 31개·`FilePublicationPort`·`FileExportPort` 삭제(`docs/capability-status.md:76-77`), 남은 직접 파서 `objectstorage/control/CanonicalJsonReader.java` 1개, 커밋 `6d27356e` | - | - |
| X1-지도-readiness / evidence / API-surface / moduleboundary | 권고 | 카드 스키마·검증기·API-surface gate·moduleboundary 여러 벌 → 하나로 | 남음 | moduleboundary main 3벌 삭제, API-surface는 `ca.api-surface` 하나. 남은 것: 카드 스키마 3개·검증기 3곳, JPA evidence plugin(build-tools `jpa/` 48파일) | W3 | 결정(2026-09-25): O3 — JPA readiness·evidence는 persistence-jpa 테스트로(manifest 폐기), messaging 카드 검증은 messaging leaf로 |
| X1-지도-readiness / evidence / API-surface / moduleboundary | 권고 | 카드 스키마·검증기·API-surface gate·moduleboundary 여러 벌 → 하나로 | 보류 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): 완료: JPA readiness·evidence → persistence-jpa 테스트(manifest 폐기), API surface 구현 하나. 남은 "messaging 카드 검증은 messaging leaf로": `MessagingCapabilityRegistryContractTest`는 `config/messaging/*.yaml`을 snakeyaml로 읽는데 `adapter:outbound:messaging`은 모든 configuration(테스트 포함)에서 YAML·Jackson 2를 exclude+reject한다("Jackson 3 only and YAML-free"). 옮기려면 카드 파일을 JSON으로 바꾸거나 test 설정만 예외로 둘지 정해야 함. 승인자: 저장소 소유자 결정 필요 | W3 | 결정(2026-09-25): O3 — JPA readiness·evidence는 persistence-jpa 테스트로(manifest 폐기), messaging 카드 검증은 messaging leaf로 |
| X1-지도-테스트 fake / contract kit | 권고 | 같은 포트 fake가 모듈마다 따로 → 포트 소유 leaf testFixtures에 contract kit | 남음 | `TransactionPort` fake 21 → 10, kit 4개(DurableOperation·OutboxLeaseFencing·GrpcOperationLedger·sample WorkLogRepository) | W4 | X1-#3a~#3d |
| X1-#1a | Required | Outbox V2 삭제 + v1 claim에 owner+token fencing 이식 | 완료 | `persistence-jpa/.../db/migration/postgresql/V17__outbox_event_lease_fencing.sql`, `OutboxStoreAdapter.java:102-123`(markPublished·markFailed·markDead가 `lease.owner()`·`lease.token()` 조건부 UPDATE), V2 코드·`jpa/outbox-storage`·`jpa/outbox-polling` 삭제(`docs/capability-status.md:175-179`), 커밋 `6d27356e` | - | - |
| X1-#1b | Required | append 포트를 `OutboxAppendPort` 하나로, legacy는 cutover 후 삭제 | 남음 | `OutboxAppendPort` main 소비자 0(구현 `CanonicalOutboxAppendAdapter`뿐). `LegacyOutboxAppendPort` 소비자 4곳: `SubmitDurableOperationUseCase.java:56`, sample `PosterEventPublisher.java:25`·`PosterImagePublicationEventPublisher.java:12`·`CreateWorkLogUseCase.java:42`. canonical 경로는 `IntegrationEventEncoderPort` 구현이 필요한데 템플릿은 주지 않음(`src/messaging/CLAUDE.md:83-89`, main 구현 0) | W3 | 결정(2026-09-25): canonical 통일(S1-#2b와 같은 작업) |
@@ -709,7 +709,7 @@ Wave 1–2 구현 중 나온 질문에 대해 받은 7건(2026-09-28):
| X1-#6d | Required | `ClaimFencingContract` kit를 application-core testFixtures에 두고 row lease store마다 실행 | 남음 | outbox 전용 `OutboxLeaseFencingContract`만 있음. durable operation(`claimNext`·`heartbeat`), notification `JpaRecipientLeaseStore`는 공통 fencing kit 없음 | W4 | `OutboxLeaseFencingContract`의 "밀려난 쪽 종결 쓰기는 0건" 시나리오를 범용 `ClaimFencingContract`로 올리고 durable operation·recipient lease store 2곳에 상속 추가 |
| X1-#6e | Required | notification `recipients.save`가 lease 확인 없이 씀 (= B-5) | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): B-5a·B-5b와 같은 결함. 같은 수정·테스트(`DispatchOutcomeRecorder.java:122,153`) | - | projection 뒤 recipient를 다시 읽고 recorder 소유 필드만 `saveHeldBy(lease)`로 기록 + late-match 회귀 테스트 |
| X1-#6f | 권고 | shared-contract `OperationalRecordStorePort`(CAS 저장 포트) 사용처 0 — 리뷰 권고 "미사용분 삭제" 적용 대상 | 남음 | `shared-contract/.../opstore/OperationalRecordStorePort.java:19`, 같은 패키지 `OperationalRecord`·`OperationalRecordConflictException` 포함 구현·호출·테스트·문서 참조 0(`git grep -w OperationalRecordStorePort` → 자기 파일뿐) | W3 | `shared-contract/src/main/java/dev/caskeleton/shared/opstore/` 3개 삭제, `docs/capability-status.md` 제거 표에 한 줄 |
| X1-#7a | Required | readiness 카드 스키마 3개·검증기 3개, family별 evidence plugin | 남음 | 카드: `src/config/jpa/readiness-cards.yaml`(kebab JSON), `src/config/messaging/readiness-cards.yaml`(camelCase), `docs/registries/object-storage-readiness.yaml`(snake_case). 검증기: build-tools `JpaReadinessRegistryValidator.java`, app-bootstrap `MessagingCapabilityRegistryContractTest.java`, objectstorage `ObjectStorageReadinessRegistryTest.java`. messaging·notification·mongo evidence plugin은 leaf 테스트로 이동, JPA evidence는 build-tools `jpa/` 48파일에 남음(계획서 진행 기록 Wave 5 "남은 설계 결정") | W3 | 결정(2026-09-25): O3 방향(X1-지도-readiness와 같은 작업) |
| X1-#7a | Required | readiness 카드 스키마 3개·검증기 3개, family별 evidence plugin | 보류 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): 위 행과 같은 작업. JPA 검증기는 leaf 테스트로 옮김, messaging 검증기 이동은 같은 사유로 결정 필요. 승인자: 저장소 소유자 결정 필요 | W3 | 결정(2026-09-25): O3 방향(X1-지도-readiness와 같은 작업) |
| X1-#7b | Required | API-surface gate 3개 → `ca.api-surface` 하나 | 완료 | notification·persistence-jpa·persistence-mongo·graphql 모두 `id 'ca.api-surface'`(`adapter/outbound/notification/build.gradle:4`, `persistence-jpa/build.gradle:7`), `ca.notification-api-surface`·`verifyJpaAdopterApiSurface` 삭제. JPA adopter import 검사는 leaf 테스트 `JpaAdopterApiSurfaceTest`, 커밋 `6d27356e` | - | - |
| X1-#7c | Required | web·graphql·websocket main의 moduleboundary 3벌 → ArchUnit | 완료 | 3벌 삭제(`docs/capability-status.md:80,93,113`), graphql 규칙 2개는 `GraphQlTransportBoundaryArchitectureTest.java`로, 커밋 `6d27356e` | - | - |
| X1-#8a | Consider | 소비자 0인 `FilePublicationPort` plane 삭제, parser 3→1, 경계 결정 문서화 | 완료 | `docs/capability-status.md:76-77`, fileserver `FileserverControlRecordCodec`·`LocalPublicationJournalCodec` 삭제, 남은 파서 `CanonicalJsonReader.java` 1개, `docs/storage-capability-boundary.md` "Decision rule" 절, 커밋 `6d27356e` | - | - |
@@ -784,7 +784,7 @@ Wave 1–2 구현 중 나온 질문에 대해 받은 7건(2026-09-28):
| S1-#15b | Consider | shared-contract `opstore/*` 구현·소비자 0 | 남음 | `shared-contract/.../opstore/OperationalRecordStorePort.java` 외 2개, shared-contract 밖 참조 0(graphql `advanced/**` 삭제 뒤) | W3 | `opstore` 패키지 삭제 |
| S1-#15c | Consider | ratelimit 정책 타입이 cache-redis 전용 | 남음 | `shared-contract/.../ratelimit/RateLimitPolicy`·`RateLimitAlgorithm` main 소비자는 cache-redis뿐, `RateLimitEvaluationDedupPolicy`는 테스트만 참조 | W3 | 세 타입을 `adapter:outbound:cache-redis`로 이동(`EdgeRateLimitPort` 계열만 shared에 유지) |
| S1-#15d | Consider | shared-contract CLAUDE.md 책임 목록이 패키지 일부만 설명 | 남음 | `shared-contract/CLAUDE.md:17-30`은 response·error·request·health·tracing만, 실제 패키지 15개(annotation·concurrency·headers·metrics·operation·registry·runtime·security·ratelimit·opstore 누락) | W5 | 책임 목록을 현재 패키지 기준으로 갱신 |
| S1-#16 | Consider | 문서가 말하는 `application-core → domain-core` 의존이 빌드에 없음 | 남음 | `application-core/build.gradle:9-15`에 `domain-core` 없음, `application-*` main의 `dev.caskeleton.domain` import 0, 반면 `AGENTS.md:118-119`·registry(`modules.json`)는 이 방향을 허용·전제 | W3 | `application-core/build.gradle`에 `implementation project(':domain-core')` 복원, `NotificationIdGeneratorPort`·`UploadIdentifierFactory`를 `IdFactory` 기반으로 정리 |
| S1-#16 | Consider | 문서가 말하는 `application-core → domain-core` 의존이 빌드에 없음 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `src/application-core/build.gradle` `implementation project(':domain-core')` 복원(registry 허용 edge). `architectureCheck` PASS. 같은 행의 `NotificationIdGeneratorPort`·`UploadIdentifierFactory` → `IdFactory` 정리는 application-notification/fileserver·persistence-jpa·composition을 바꾸는 작업이라 하지 않음(P16-new-5) | - | `application-core/build.gradle`에 `implementation project(':domain-core')` 복원, `NotificationIdGeneratorPort`·`UploadIdentifierFactory`를 `IdFactory` 기반으로 정리 |
| S1-#17a | Consider | objectstorage 식별자 클래스 6개·가드 2개 복사 | 남음 | `application-objectstorage/.../identity/{ObjectId,ObjectReference,ObjectStageHandle,ObjectVersionToken,PartReceiptToken,DirectTransferSessionId}.java` 각 40줄 클래스, `model/ObjectModelSupport.java` vs `request/ObjectRequestSupport.java:14-18` | W3 | 식별자를 record + `toString` 재정의로, 가드는 하나로 |
| S1-#17b | Consider | legacy `application.storage` 네임스페이스 공존(Javadoc 모순) | 남음 | `application-objectstorage/.../storage/ObjectStoragePort.java:6,12`("the only dependency" + "Legacy compatibility only"), 104줄 남음(migration은 삭제), 사용처 sample + objectstorage `S3ObjectStorageAdapter`·`FilesystemObjectStorageAdapter` | W3 | 「한 기능에 한 세대」: sample `UploadPosterImageUseCase`를 `application.objectstorage` 포트로 옮기고 legacy 포트·어댑터 2개 삭제 |
| S1-#18a | Consider | `V2` 접미사 타입 | 완료 | `6d27356e`: 멱등성 V2 → 무접미사, outbox V2 삭제. main의 `*V2*.java`는 sample 이벤트 스키마 버전 `PosterImageAttachmentReadyV2` 하나뿐 | - | - |
@@ -933,7 +933,7 @@ Wave 1–2 구현 중 나온 질문에 대해 받은 7건(2026-09-28):
| S5-lead-1 | 권고 | client 에러 문구 언어가 전송마다 다름(web 영어, graphql 한국어) (= X2-P2-1) | 완료 | Wave 3 W3-P15 (Wave 3 라운드 1 커밋): 결정 11: `ClientErrorMessages`(한국어, Category별) 하나를 web·fileserver·GraphQL·gRPC(status description) 모두 사용. gRPC `GrpcExceptionHandlingInterceptorTest.theStatusDescriptionIsTheSharedClientMessageOfTheCategory` FAIL(`expected: "요청한 리소스를 찾을 수 없습니다." but was: "ROUTE_NOT_FOUND"`)→PASS, `GrpcP1BoundaryWireTest` 기대값 갱신 PASS. STOMP `message` 헤더는 X2-P2-9b 지시대로 고정값 유지 | - | 결정(2026-09-25): client 에러 문구는 한국어 — `Category`별 문구 표 하나를 shared-contract에 두고 모든 전송이 사용 |
| S5-lead-2 | 권고 | moduleboundary 세 번째 사본(websocket) | 해당 없음(코드 삭제) | `WebSocketStableModule`·`WebSocketBuildModel` 0건. 표 80행 | - | - |
| S5-lead-3 | 권고 | request/tenant context 타입이 전송마다 따로 있음 (= X2-P2-6) | 남음 | 이름이 같은 `TenantContext` 두 개의 모양·검증이 다름. web `core/TenantContext.java:17,20`은 `(String tenantId)`, `[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`. graphql `context/TenantContext.java:15,17,30`은 `(value, source)`, 비어 있지 않고 128자 이하면 모두 허용. 같은 tenant가 한 전송은 통과하고 다른 전송은 거부됨<br>Wave 1–2 P8: 미완 — 이유: 공통 tenant 값 타입(shared-contract/application-core)을 만들고 web·graphql(그리고 messaging·persistence·notification의 tenant 타입)이 담게 하는 일은 계획서 Wave 3 3-D 「tenant 값 타입」 공통 작업이고 web은 P10 범위. 이번에는 증상만 막음: GraphQL `TenantContext` 검증을 web과 같은 문법 `[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`으로 맞춰 "한 전송만 통과하는 tenant"를 없앰. `context/GraphQlRequestContextTest.aTenantTheWebTransportRefusesIsRefusedHereToo`(4건) FAIL(`Expecting actual not to be null`) → PASS. `.../context/TenantContext.java:38`. 커밋 `aa5f4d90` | W2 | tenant 값 타입 하나(검증 규칙 하나)를 application-core/shared-contract에 두고, 두 전송 context가 그것을 담게 한다 |
| S5-lead-4 | 권고 | release/promotion gate가 websocket/grpc에도 반복되는지 | 남음 | web·graphql·websocket gate는 삭제(표 80·114·115행, web Advanced release 행). grpc에 남음: `grpc/grpc-testkit/…/release/GrpcStableReleaseGate.java`, `grpc-advanced/grpc-advanced-bootstrap/…/release/GrpcAdvancedPromotionGate.java`. 둘 다 main 참조 0건(test만) | W3 | 두 gate와 테스트를 삭제하거나 test source set으로 옮긴다(S6/S7 grpc 항목과 같이) |
| S5-lead-4 | 권고 | release/promotion gate가 websocket/grpc에도 반복되는지 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `grpc/grpc-testkit/.../release/`(4 main + 1 test), `grpc-advanced/grpc-advanced-bootstrap/.../release/`(4 main + 1 test) 삭제, 문서 4곳 정정. `-p optional-platforms ci` PASS. build 파일은 건드리지 않음 | - | 두 gate와 테스트를 삭제하거나 test source set으로 옮긴다(S6/S7 grpc 항목과 같이) |
| S5-lead-5 | 권고 | bulkhead: graphql·fileserver·httpclient가 겹치는지 | 해당 없음(코드 삭제) | 겹치던 web `BlockingBridgeBudget`·`SemaphoreAdmissionController`는 삭제. 남은 3개는 방식이 다름: `GraphQlBlockingBridge.java:45-57`(bounded `ThreadPoolExecutor`+AbortPolicy), `BlockingTransferExecutor.java:26`(Spring `ThreadPoolTaskExecutor`), `BlockingAttemptBulkhead.java:39`(`Semaphore`). 각 100줄 이하 | - | - |
**조사 메모**
@@ -1066,11 +1066,11 @@ Wave 1–2 구현 중 나온 질문에 대해 받은 7건(2026-09-28):
| NEW-10d | Nit | web fixture 앱 2개와 sample이 `WebAdapterAutoConfiguration` 전체를 제외한다. sample webSystemTest 4곳은 문자열 이름으로 제외한다. | 남음 | 클래스로 제외: `src/adapter/inbound/web/src/testFixtures/java/dev/caskeleton/webtestkit/ContractFixtureApplication.java:38`, `PipelineOrderFixtureApplication.java:46`, `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/SamplePortfolioApplication.java:30,49`. 문자열로 제외: `OpenApiDriftContractTest.java:172`, `OpenApiSnapshotTest.java:103`, `DateHeaderContractTest.java:69`, `VirtualThreadMdcE2ETest.java:152`(모두 `src/sample-portfolio/src/webSystemTest/...`). 제외하는 이유는 production security chain을 빼기 위해서다(`ContractFixtureApplication.java:27-30`). | W3 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebAdapterAutoConfiguration.java`의 `@Import` 목록을 `WebAdapterAutoConfiguration`(core)과 `WebSecurityAutoConfiguration`(`JwtDecoderConfig`·`SecurityConfig`·`MethodSecurityConfig`·`RedisSessionWebConfig`·`JwtToAuthenticatedPrincipalConverter`·`AuthorizationAdapter`)으로 나눈다. fixture·sample은 security root만 클래스로 제외하고, sample은 `dev.caskeleton.adapter.inbound.web` component scan(`SamplePortfolioApplication.java:31-40`)을 지운다. 문자열 제외는 클래스 참조로 바꾼다. |
| NEW-11 | Consider | fileserver를 JPA 줄 없이 고르면 Boot 관계형 자동 설정이 켜지고, 원인을 알기 어려운 오류로 기동에 실패한다. | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `src/composition/fileserver-platform/build.gradle`에 `runtimeOnly project(':adapter:outbound:persistence-jpa')`, `src/config/architecture/modules.json` edge 추가, README 갱신(`src/composition/fileserver-platform/README.md` 저장소 줄, `src/README.md:270` 표). `architectureCheck`·`verifyDependencyLocks` 통과. JPA 줄 없이 fileserver만 고른 조립의 기동 테스트는 추가하지 않았다: 모든 테스트 classpath(app-bootstrap integrationTest 포함)에 persistence-jpa가 이미 있어 "없는 조립"을 만들 수 없다. 대신 조립 lane `:app-bootstrap:integrationTest`(fileserver PG 왕복 포함 4건) 통과 | - | 결정(2026-09-25): 한 줄 원칙 — fileserver·notification composition이 persistence-jpa를 `runtimeOnly`로 함께 가져옴 |
| NEW-12 | Nit | `bootstrap.autoconfigure` 패키지가 component scan 범위 안에 있다. | 남음 | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/CaSkeletonApplication.java:19`: `@SpringBootApplication`이 `dev.caskeleton.bootstrap..` 전체를 scan한다. 지금 `autoconfigure/` 아래 4개 root는 imports에 있어서 Boot의 `AutoConfigurationExcludeFilter`가 걸러낸다. 그 외 stereotype은 `@ConfigurationProperties` record 3개뿐이다(grep: `@Configuration`·`@Component` 0건). 지금 당장 문제는 없고, 나중에 root가 아닌 `@Configuration`을 추가하면 조건 없이 등록되는 잠재 위험이다. | W3 | NEW-2 이동 뒤에 남는 `common`·`tracing` root를 scan 밖 패키지(예: `dev.caskeleton.autoconfigure.bootstrap`)로 옮긴다. 옮기지 않을 거면 architectureTest에 "`bootstrap.autoconfigure..`의 `@Configuration`은 `@AutoConfiguration`이어야 한다" 규칙을 추가한다. |
| NEW-13a | Consider | `verifyEnvKeys`는 bootstrap에 유지하기로 결정됐는데, 문서는 아직 "옮기지 않은 검사"라고 적고 있다. | 남음 | 태스크는 `src/app-bootstrap/build.gradle:5`(`ca.config-contract`), 루트 `src/build.gradle:78`(`configContractCheck`)에 있다. 구현은 `src/build-tools/src/main/java/dev/caskeleton/buildtools/config/`(6개 파일)에 있다. 문구는 `CLAUDE.md:32`, `AGENTS.md:68`에 있다. | W3 | JPA evidence를 삭제하면(NEW-13b) build-tools에는 `ca.config-contract` 하나만 남는다. 그 plugin을 `src/build-logic/`으로 옮기고 `src/settings.gradle:6` `includeBuild('build-tools')`와 `build-logic.yml`의 build-tools 단계를 지운다. `CLAUDE.md:32`·`AGENTS.md:68`은 "verifyEnvKeys = app-bootstrap 유지"로 고친다. |
| NEW-13b | Consider | JPA evidence manifest(`ca.jpa-evidence`, `ca.jpa-qualification`)를 폐기하고 leaf 테스트로 옮기기로 결정됐다. 아직 코드에 남아 있다. | 남음 | plugin: `src/build-tools/build.gradle:18-27`, 구현은 `src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/`(45개 파일, 2,701줄). 적용 위치: `src/build.gradle:20`, `src/adapter/outbound/persistence-jpa/build.gradle:5,141-178,216,261-264`. 입력: `src/config/jpa/readiness-cards.yaml`, `src/config/jpa/release-registry.json`. CI: `.github/workflows/jpa-r2-evidence.yml` 전체, `integration-main.yml:130-143`(`jpa-candidate-evidence`), `jpa-release.yml:121-122`. 다른 사용처: `MessagingCapabilityRegistryContractTest.java:128,140,225`가 `readiness-cards.yaml`을 읽고, `JpaReleaseManifest.java:46`(persistence-jpa testFixtures)가 `release-registry.json`을 읽는다. | W3 | build-tools의 `jpa/` 패키지와 두 plugin id를 삭제한다. evidence가 확인하던 사실(마이그레이션 순서, PG 버전 매트릭스, lane 존재)은 persistence-jpa `postgresqlIntegrationTest`의 JUnit 테스트로 옮긴다. yaml·json 입력과 `jpa-r2-evidence.yml`, integration-main의 `jpa-candidate-evidence` 잡, jpa-release의 두 태스크를 지운다. `MessagingCapabilityRegistryContractTest`에서 readiness-cards 의존을 뺀다. |
| NEW-13a | Consider | `verifyEnvKeys`는 bootstrap에 유지하기로 결정됐는데, 문서는 아직 "옮기지 않은 검사"라고 적고 있다. | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `CLAUDE.md`·`AGENTS.md`·`src/README.md`·build-logic README를 "verifyEnvKeys = app-bootstrap 유지(결정 4), 구현은 build-logic `ca.config-contract`, build-tools 삭제"로 수정 | - | JPA evidence를 삭제하면(NEW-13b) build-tools에는 `ca.config-contract` 하나만 남는다. 그 plugin을 `src/build-logic/`으로 옮기고 `src/settings.gradle:6` `includeBuild('build-tools')`와 `build-logic.yml`의 build-tools 단계를 지운다. `CLAUDE.md:32`·`AGENTS.md:68`은 "verifyEnvKeys = app-bootstrap 유지"로 고친다. |
| NEW-13b | Consider | JPA evidence manifest(`ca.jpa-evidence`, `ca.jpa-qualification`)를 폐기하고 leaf 테스트로 옮기기로 결정됐다. 아직 코드에 남아 있다. | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): O3-2와 같음. 수정 방향과 다른 점: `readiness-cards.yaml`·`release-registry.json`은 지우지 않음 — 결정 4·X1 결정은 "leaf 테스트로 옮김"이고, `release-registry.json`은 persistence-jpa testFixtures `JpaReleaseManifest`·`JpaReleaseRenderingTest`·`jpaReleaseQualification`의 SSOT, 카드 파일은 `JpaReadinessRegistryTest`와 readiness 레인 `requires`의 입력. `MessagingCapabilityRegistryContractTest`는 JPA 카드를 읽지 않음(`config/messaging`만 읽음, 현황표 근거가 틀림) | - | build-tools의 `jpa/` 패키지와 두 plugin id를 삭제한다. evidence가 확인하던 사실(마이그레이션 순서, PG 버전 매트릭스, lane 존재)은 persistence-jpa `postgresqlIntegrationTest`의 JUnit 테스트로 옮긴다. yaml·json 입력과 `jpa-r2-evidence.yml`, integration-main의 `jpa-candidate-evidence` 잡, jpa-release의 두 태스크를 지운다. `MessagingCapabilityRegistryContractTest`에서 readiness-cards 의존을 뺀다. |
| NEW-13c | Nit | redis topology lane은 유지하기로 결정됐다. | 완료 | lane plugin은 build-logic `ca.redis-topology-lane`에 있고, `src/adapter/outbound/cache-redis/build.gradle:4,51-53`, `src/adapter/outbound/redis-sdk/build.gradle:3,19-21`, `src/adapter/outbound/redis-runtime/build.gradle:5`이 쓴다. CI는 `redis-sdk-topology.yml`이다. 코드는 옮길 필요가 없다. | W5 | 문서에 "유지"라고만 적는다(`docs/superpowers/plans/2026-09-25-capability-module-packaging.md` 진행 기록 Wave 5 "남은 설계 결정" 문장). |
| NEW-13d | Consider | API surface 검사가 `mainCheck`로 옮겨가서 PR에서 공개 타입 변경을 바로 잡지 못한다. | 남음 | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/ApiSurfacePlugin.java:96-101`: `verify`를 `mainCheck`에만 연결한다. 루트 `ci`(`src/build.gradle:127-133`)는 leaf `check` + architecture + quality이고, `mainCheck`(:135-146)는 main push에서만 돈다. 적용 leaf는 graphql, httpclient, notification, persistence-jpa다. | W3 | 결정(2026-09-25): API surface 검사를 PR 단계(`check`)로 올림 |
| NEW-13e | Consider | 어떤 집계 태스크·CI에도 묶이지 않은 strict lane이 있다: `messagingSampleContractQualificationTest`, `posterImageMigrationTest`. | 남음 | 둘 다 `src/sample-portfolio/build.gradle:185-201`에 있다. category를 지정하지 않아 `TEST`로 분류되고(`StrictTestLaneSpec.java:21`), 루트는 `testLaneCheck`를 집계하지 않는다(`src/build.gradle:81-101`에는 integration/architecture/system만 있다). sample은 `leafPaths`에서도 빠진다(`src/build.gradle:65-67`). `.github` grep 결과 0건이다. CI는 `:sample-portfolio:integrationTest`(`integration-main.yml:309`)만 부르며, 이것은 strict(zero-skip)가 아니다. | W3 | `messagingSampleContractQualificationTest`는 루트 `verifyMessagingContracts`(`src/build.gradle:120-125`)의 dependsOn에 추가한다. `posterImageMigrationTest`는 lane에 `integration()`을 지정하고, 루트 `integrationCheck`에 `:sample-portfolio:integrationTestLaneCheck`를 추가하거나 `integration-main.yml:309`를 lane 이름으로 바꾼다. |
| NEW-13d | Consider | API surface 검사가 `mainCheck`로 옮겨가서 PR에서 공개 타입 변경을 바로 잡지 못한다. | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `ApiSurfacePlugin`이 verify를 leaf `check`에 연결. `ApiSurfaceConventionTest.theLeafCheckRunsTheSurfaceVerification` FAIL→PASS, `./gradlew check --dry-run`에 graphql·notification·jpa·mongo `verify*ApiSurface` 포함 | - | 결정(2026-09-25): API surface 검사를 PR 단계(`check`)로 올림 |
| NEW-13e | Consider | 어떤 집계 태스크·CI에도 묶이지 않은 strict lane이 있다: `messagingSampleContractQualificationTest`, `posterImageMigrationTest`. | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `posterImageMigrationTest`에 `integration()`, 루트 `integrationCheck`에 `:sample-portfolio:integrationTestLaneCheck`, `verifyMessagingContracts`에 `:sample-portfolio:messagingSampleContractQualificationTest`, integration-main.yml 호출을 `:sample-portfolio:integrationTestLaneCheck`로 | - | `messagingSampleContractQualificationTest`는 루트 `verifyMessagingContracts`(`src/build.gradle:120-125`)의 dependsOn에 추가한다. `posterImageMigrationTest`는 lane에 `integration()`을 지정하고, 루트 `integrationCheck`에 `:sample-portfolio:integrationTestLaneCheck`를 추가하거나 `integration-main.yml:309`를 lane 이름으로 바꾼다. |
| NEW-14a | Consider | `docs/study/*.ko.md` 2개가 삭제된 코드를 설명한다. | 남음 | `docs/study/graphql-walkthrough.ko.md`(3,655줄): 208077fd에는 있고 HEAD에는 없는 클래스 216개를 언급하고, 해당 줄은 약 227줄이다. `docs/study/postgresql-jpa-walkthrough.ko.md`(3,574줄): 70개, 약 110줄. 측정 방법: 문서의 CamelCase 식별자 ∩ (208077fd `.java` − HEAD `.java`). | W5 | 아래 메모 참고. |
| NEW-14b | Consider | `docs/*-superpowers-package/` 3개가 삭제된 코드를 설명한다. | 남음 | graphql package(7개 파일, 9,229줄): 삭제 클래스 약 250개, 해당 줄 약 709줄. web package(8개, 9,812줄): 약 170개, 약 516줄. websocket package(8개, 10,764줄): 약 58개, 약 216줄. 문서마다 `MANIFEST.sha256`와 `validate_*_docs.py`가 있다(CI에서 부르지 않는다. `.github` grep 0건). `validate_graphql_docs.py`는 삭제된 클래스 20개를 하드코딩하고 있다. | W5 | 아래 메모 참고. |
@@ -1161,7 +1161,7 @@ Wave 1–2 구현 묶음(`P1`–`P13`)이 작업 중 찾은 결함과 통합 검
| P13-new-1 | 발견 | included build lock은 build-logic·build-tools 자신의 configuration(compile/test)만 잠근다. main build가 plugin을 쓸 때의 settings·root buildscript classpath는 main build에서 따로 해석되고 잠기지 않는다. 증거: `./gradlew buildEnvironment`에서 `project :build-tool… | 보류 | 사유: 잠그면 Spring Boot plugin을 올릴 때마다 lock 갱신 필요, included build 자체는 잠갔다. 승인자: 저장소 소유자(2026-09-28, 결정 27) | - | - |
| P13-new-2 | 발견 | `local-redis` lane은 기동 로그 무음 검사(스크립트 3c)를 통과할 수 없다. lane 자신이 주는 `APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=true`와 advanced credential 미설정 때문에 `RedisSdkAutoConfiguration`이 기동 중 WARN 2줄(`Redis is running without credentials… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P13.md` | W4 | `local-redis` lane 설정 또는 smoke 무음 검사 기준 정리(NEW-1b와 함께) |
| NEW-15 | 발견 | gRPC proto 조직 이름이 템플릿 이름이 아니라 `hyeonworks`로 고정 — `GrpcProtoStyleManifest.caSkeleton()` `organization`, 기본 proto 패키지 `hyeonworks.grpc.common.v1`, `GrpcCodegenManifest`, 테스트 38개 파일. 재사용 체크리스트에도 없음 | 완료 | Wave 3 W3-P17 (Wave 3 라운드 1 커밋): `e2397d2f`. `hyeonworks` → `caskeleton`: proto 디렉터리 `src/grpc/grpc-contract/src/main/proto/caskeleton/grpc/common/v1/`, `package caskeleton.grpc.common.v1`, `java_package caskeleton.grpc.common.v1.generated`, Edition fixture, 테스트 문자열 전부(기계적 치환). `GrpcProtoStyleManifest`·`GrpcCodegenManifest`는 S7-#13으로 삭제돼 organization 필드 자체가 없다. `AGENTS.md` 「템플릿 재사용 체크리스트」 2번에 proto 조직 이름 한 줄. `src/grpc/**`·`src/grpc-advanced/**`에 `hyeonworks` 0건. 과거 리뷰·계획 문서(`docs/reviews/**`, `docs/*-superpowers-package/**`, 7월 계획)의 언급은 이력이라 두었다 | - | 결정 18(protobuf 플러그인 전환)과 함께 `caskeleton`으로 바꾸고 `AGENTS.md` 재사용 체크리스트에 한 줄 |
| NEW-16 | 발견 | `integrationCheck`가 로컬에서 통과할 수 없는 lane을 묶음 — Redis topology 3개는 `-Predis.topology.mode` 없이 fail-closed, AWS 보호 lane은 보호 자격 증명 env가 없으면 실패. 그래서 집계 태스크가 항상 실패 | 남음 | Wave 1·2 검증 로그: `redisTopologyTest was selected with redis.topology.mode='unset'`, `AwsS3QualificationPreconditionsTest` | W3 | 매개변수·자격 증명이 필요한 lane은 `integrationCheck`에서 빼고 전용 워크플로에서만(또는 입력이 있을 때만 포함) |
| NEW-16 | 발견 | `integrationCheck`가 로컬에서 통과할 수 없는 lane을 묶음 — Redis topology 3개는 `-Predis.topology.mode` 없이 fail-closed, AWS 보호 lane은 보호 자격 증명 env가 없으면 실패. 그래서 집계 태스크가 항상 실패 | 완료 | Wave 3 W3-P16 (Wave 3 라운드 1 커밋): `strictTestLanes`에 `explicitOnly(reason)`(모든 집계에서 빠지고 집계가 돌 때 이유 출력) — `StrictTestLaneConventionTest.anExplicitOnlyLaneStaysOutOfEveryAggregate` FAIL→PASS. Redis topology는 `-Predis.topology.mode`가 없으면 explicit-only(`RedisTopologyLanePluginFunctionalTest.withoutADeclaredModeTheLaneStaysOutOfTheIntegrationAggregate`·`aDeclaredModePutsTheLaneInTheIntegrationAggregate` FAIL→PASS), AWS lane은 `OBJECT_STORAGE_AWS_QUALIFICATION_ENABLED=true`가 없으면 explicit-only, httpclient `disabledProxyFailsBeforeARequestCanBeSent`는 Docker userland proxy와 무관한 loopback 닫힌 포트 시나리오 `refusedConnectionFailsBeforeARequestCanBeSent`로 교체(P11-new-3도 해소). `./gradlew integrationCheck --continue` BUILD SUCCESSFUL(14m), 기존 실패 3종 없음, 빠진 lane 4개는 이유 출력 | - | 매개변수·자격 증명이 필요한 lane은 `integrationCheck`에서 빼고 전용 워크플로에서만(또는 입력이 있을 때만 포함) |
| P14-new-1 | 발견 | operator force-delete(`application-fileserver/.../admin/DefaultFileserverAdminService.java:167`)가 P4-new-4와 같은 결함 — 진행 중 upload를 지우면 세션이 ACTIVE로 남고 staging 정리가 예약되지 않는다. | 남음 | Wave 2.5 P14 결과 파일 | W2 | lifecycle delete와 같은 `unfinishedUpload` 처리를 admin 경로에도(생성자에 `StagingUploadLocator`). 라운드 2 P24 |
| P14-new-2 | 발견 | `S3AsyncResponseBodyBridgeTest.deliversAnExactBoundedBodyOnTheWorkerAndInvalidatesTheSource`가 전체 `check` 부하에서 간헐 실패(`Expecting code to raise a throwable`), 단독 통과. | 남음 | Wave 2.5 P14 결과 파일 | W4 | 타이밍 의존 제거(결정적 executor/latch) |
| P14-new-3 | 발견 | main에 `ReconcilePosterImageUploadUseCase`를 부르는 worker가 없다(`claimPending` 호출자 0). 게시가 이긴 ABORT_AUTHORIZED intent는 reconcile 명령이 와야 붙는다. | 남음 | Wave 2.5 P14 결과 파일 | W3 | sample에 reconcile worker(PENDING·ABORT_AUTHORIZED 모두)를 두거나 수동 명령임을 문서화. 라운드 2 P25 |
@@ -1178,3 +1178,10 @@ Wave 1–2 구현 묶음(`P1`–`P13`)이 작업 중 찾은 결함과 통합 검
| P26-new-1 | 발견 | Dynamic Target 호출이 deadline 검사와 admission permit을 거치지 않았다(만료 deadline에도 hop 전송). | 완료 | Wave 3 P26: `CallSetup` 공유, 재현 테스트 FAIL→PASS | - | - |
| P26-new-2 | 발견 | prod의 schema 변경 `ddl-auto` 거부가 문서의 `PROFILE_MISMATCH`가 아니라 `IllegalStateException`이었다. | 완료 | Wave 3 P26: 검사 하나로 합치며 수정 | - | - |
| P26-new-3 | 발견 | cache-redis가 `secret://src/`(빈 이름)를 `SecretSourcePort.resolve("")`로 넘겼다. | 완료 | Wave 3 P26: `SecretReference.parse`가 거부 | - | - |
| P16-new-1 | 발견 | fileserver workflow가 P4 이동 전 leaf의 테스트를 가리킴(`FileserverDocumentationCoverageTest` 등). | 완료 | Wave 3 P16: release.yml·fileserver-pr.yml·fileserver-nightly.yml | - | - |
| P16-new-2 | 발견 | `FileserverDocumentationCoverageTest`가 읽는 문서·workflow·소스가 test inputs에 없음. | 완료 | Wave 3 P16: `src/composition/fileserver-platform/build.gradle` | - | - |
| P16-new-3 | 발견 | sample `PublishPosterImageUseCase.handle`이 `UUID.randomUUID()`로 attempt id 생성(ArchUnit 밖이라 안 보였음). | 완료 | Wave 3 P16: `ids.allocate()`, sample을 ArchUnit 대상에 포함 | - | - |
| P16-new-4 | 발견 | `S3AsyncResponseBodyBridgeTest.oversizedSdkChunkFailsClosed` 간헐 실패(소비 스레드와 chunk 크기 검사 경합). | 남음 | Wave 3 P16 결과 파일 | W4 | P14-new-2와 함께 결정적 테스트로 |
| P16-new-5 | 발견 | S1-#16 나머지: `NotificationIdGeneratorPort`·`UploadIdentifierFactory`를 domain `IdFactory` 기반으로. | 남음 | Wave 3 P16 결과 파일 | W3 | 3-D(P19) |
| P16-new-6 | 발견 | persistence-fileserver 공개 타입의 adopter import를 보는 검사가 없어짐(예전 정규식 테스트가 접두어 전체를 봤음). | 남음 | Wave 3 P16 결과 파일 | W3 | persistence-fileserver에 `ca.api-surface` 적용 — 빌드 잔여 묶음 |
| P16-new-7 | 발견 | `docs/study/postgresql-jpa-walkthrough.ko.md` §15.6 등이 삭제된 JPA evidence manifest를 설명. | 남음 | Wave 3 P16 결과 파일 | W5 | 결정 6: 현재 코드 기준으로 갱신 |
+5 -6
View File
@@ -84,12 +84,11 @@ rather than retrying a failure.
## Promoting a capability
`GrpcAdvancedPromotionGate.evaluate` names every missing item. Promotion to `ADVANCED_STABLE` needs
compatibility evidence, a security review, fault evidence, performance evidence, an ADR, a runbook, a
real-environment test and seven days of soak. A Stable default needs thirty.
Promotions are independent: promoting one capability changes no other's grade, and
`GrpcAdvancedSupportMatrix.apply` refuses a decision made against a different matrix state.
Promotion to `ADVANCED_STABLE` needs compatibility evidence, a security review, fault evidence,
performance evidence, an ADR, a runbook, a real-environment test and seven days of soak. A Stable
default needs thirty. Promotions are independent: promoting one capability changes no other's
grade. This is a review checklist; the in-code `GrpcAdvancedPromotionGate` that restated it was
removed (review 2026-09-24 S5-lead-4) because nothing but its own test called it.
Before citing a suite as evidence, check that it ran against the real infrastructure it needs (proxy,
container, control plane or toolchain). A suite that ran without it passed and established nothing.
+4 -4
View File
@@ -60,11 +60,11 @@ status: active
4. Change the marker to `ACTIVE` only after the compatible application revision is deployed and its
readiness check succeeds. Disabling or rolling back application code changes the marker to
`INSTALLED_INACTIVE`; it does not drop history or owned data.
5. Re-run the candidate evidence task before promoting:
5. Re-run the readiness lanes before promoting (every card's scenarios, no skips):
```bash
cd src
./gradlew :adapter:outbound:persistence-jpa:verifyJpaCandidateEvidence --console=plain
./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck --console=plain
```
6. Record the failed revision, stream/history table, root cause, recovery migration, elapsed time
@@ -92,5 +92,5 @@ result is unknown.
---
This runbook is forward-only. The reviewed migration artifact and the per-card evidence manifest
are the audit sources.
This runbook is forward-only. The reviewed migration artifact and the readiness lanes' JUnit
results from CI are the audit sources.
+1 -1
View File
@@ -2,5 +2,5 @@
# SSOT: ca-skeleton.security.public-paths default in app-bootstrap/src/main/resources/config/security.yml
# -> SecurityConfig permitAll(); anyRequest authenticated. An operator's own SECURITY_PUBLIC_PATHS
# overrides it at run time and is outside this snapshot.
# Update only after review with: ./gradlew updatePublicPathSnapshot -PapprovePublicPathChange
# Update only after review with: ./gradlew verifyPublicPathSnapshot -PapprovePublicPathChange
/v1/healthcheck
@@ -229,7 +229,7 @@ W1·W2 잔여 21행(Wave 2.5)은 P14로 1라운드에서 함께 처리한다. W1
| P23 | 3 | notification: SES → sesv2(결정 17), `persistence-notification` 추출, SRP | `S1-#4` `S1-#9` `S1-#10b` `S2-#1b` `S2-#6c` `S2-#8a` `S2-#13b` `S4-#3c` `S4-#4b` `S4-#9` `S4-#14b` `S4-#15` `S4-lead-3` `S4-lead-5` |
| P20 | 4 | 3-B 설정 prefix `app.*`(결정 16), strict 바인딩 | `X2-P1-3c` `S3-lead-2` `S3-lead-4` `S6-#14` `P11-new-1` |
- [ ] 라운드 1: P14 · P15 · P16 · P17 → 통합·검증·커밋
- [x] 라운드 1: P14 · P15 · P16 · P17 → 통합·검증·커밋 (2026-09-28, `9fdb0af4`·`c4a066df`·라운드 1 마무리 커밋)
- [ ] 라운드 2: P18 · P24 · P25 · P26 → 통합·검증·커밋
- [ ] 라운드 3: P19 · P21 · P22 · P23 → 통합·검증·커밋
- [ ] 라운드 4: P20 → 통합 → Wave 종료 검증 → 현황표·「제거된 코드」 갱신 → 커밋 `review-followup Wave 3`
+63
View File
@@ -0,0 +1,63 @@
#!/usr/bin/env bash
# The ordered local start-up: compile, Docker preflight, dependency wait, migrate-and-start, smoke.
#
# scripts/bootstrap-local.sh # the `local` overlay (docker-compose.local.yml)
# scripts/bootstrap-local.sh <profile> # docker-compose.<profile>.yml merged onto docker-compose.yml
#
# This was the build-logic `ca.developer-bootstrap` plugin (`./gradlew bootstrap`). Starting
# containers and probing an HTTP endpoint is not a build rule, so it is a script now (review
# 2026-09-24 BUILD-O3-5). The four stages and their order are unchanged: the next stage starts only
# when the previous one succeeded, and the app stage waits for startup Flyway through the compose
# healthcheck before the smoke probe runs.
set -euo pipefail
readonly repository_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
readonly profile="${1:-local}"
readonly base_compose="${repository_dir}/docker-compose.yml"
readonly overlay="${repository_dir}/docker-compose.${profile}.yml"
readonly health_endpoint="${BOOTSTRAP_HEALTH_ENDPOINT:-http://localhost:8080/api/healthcheck}"
readonly smoke_timeout_seconds="${BOOTSTRAP_SMOKE_TIMEOUT_SECONDS:-60}"
if [[ ! -f "${overlay}" ]]; then
available="$(cd "${repository_dir}" && ls docker-compose.*.yml 2>/dev/null \
| sed -e 's/^docker-compose\.//' -e 's/\.yml$//' | tr '\n' ' ')"
echo "bootstrap: '${profile}' names no overlay; expected $(basename "${overlay}") beside" \
"docker-compose.yml. Available: ${available:-none}" >&2
exit 64
fi
compose=(docker compose -f "${base_compose}" -f "${overlay}")
echo "bootstrap 1/4: compiling the default application composition"
(cd "${repository_dir}/src" && ./gradlew :app-bootstrap:compileTestJava --console=plain)
if ! docker info >/dev/null 2>&1; then
echo "bootstrap: Docker가 필요합니다. Docker Desktop/daemon을 시작한 뒤 \`docker info\`가 성공하는지 확인하세요." >&2
exit 69
fi
echo "bootstrap 2/4: starting the ${profile} PostgreSQL dependency and waiting for readiness"
"${compose[@]}" up -d --wait db
echo "bootstrap 3/4: building and starting the app; startup Flyway finishes before health is ready"
"${compose[@]}" up -d --build --wait app
echo "bootstrap 4/4: requiring HTTP 200 and status=UP from ${health_endpoint}"
deadline=$((SECONDS + smoke_timeout_seconds))
last_result="no response"
while ((SECONDS < deadline)); do
if body="$(curl --silent --show-error --max-time 2 --write-out '\n%{http_code}' "${health_endpoint}" 2>&1)"; then
status="${body##*$'\n'}"
body="${body%$'\n'*}"
if [[ "${status}" == "200" && "${body}" == *'"status":"UP"'* ]]; then
echo "bootstrap: OK — ${health_endpoint} returned HTTP 200 and status=UP."
exit 0
fi
last_result="HTTP ${status}: ${body}"
else
last_result="${body}"
fi
sleep 1
done
echo "bootstrap: ${health_endpoint} did not become healthy within ${smoke_timeout_seconds}s;" \
"last result: ${last_result}" >&2
exit 1
-1
View File
@@ -51,7 +51,6 @@ COPY --parents settings.gradle build.gradle **/build.gradle **/gradle.lockfile .
# so settings.gradle's `includeBuild('build-logic')` resolved against a build that declared no
# plugins and every leaf failed on an unknown plugin id, in the dependency-resolution stage below.
COPY build-logic/ ./build-logic/
COPY build-tools/ ./build-tools/
# Resolve every module configuration in STRICT mode (no --write-locks in a release build). This
# custom task fails on drift; Gradle's diagnostic `dependencies` report can print FAILED entries
+18 -15
View File
@@ -26,10 +26,10 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
| `qualityCheck` | 모든 leaf의 SpotBugs + FindSecBugs를 실행 |
| `configContractCheck` | `:app-bootstrap:verifyEnvKeys`로 환경 설정 계약을 검사 |
| `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 |
| `integrationCheck` | 명시적으로 선언된 strict integration lane을 실행. 일부 lane은 container runtime이 필요 |
| `ci` | PR 게이트: 모든 leaf `check` + `architectureCheck` + `qualityCheck` |
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + sample web 계약 + `verifyPublicPathSnapshot` + API surface + 전송·메시징 qualification 레인 + JPA readiness registry |
| `releaseCheck` | `ci`에 release provenance/archive 관련 검증을 추가 |
| `integrationCheck` | 선언된 strict integration lane(sample 포함)을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 |
| `ci` | PR 게이트: 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` |
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + sample web 계약 + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
| `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) |
따라서 로컬에서 한 모듈만 수정했다면 `./gradlew :domain-core:check`처럼 focused task를
먼저 사용합니다. 전체 기동 qualification은 일반 leaf `check`나 `:app-bootstrap:build`에
@@ -44,8 +44,9 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
### Local bootstrap
`./gradlew bootstrap`은 `bootstrapCompile` → `bootstrapDependencies` →
`bootstrapMigrateAndStart` → `bootstrapSmoke`를 순서대로 실행합니다.
`scripts/bootstrap-local.sh [profile]`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 →
app 기동(Flyway 포함) → health smoke를 순서대로 실행합니다(예전 `./gradlew bootstrap`, 리뷰
BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김).
DB와 app lifecycle은 저장소 루트의 base/local Compose 조합이 소유하며, app startup Flyway가
끝나 public health endpoint가 준비되어야 다음 단계로 넘어갑니다. `src/.env.example`은 커밋된
env 계약이고 `src/.env`는 로컬 실행 입력입니다. `verifyEnvKeys`는 example/registry/shipped YAML을
@@ -53,13 +54,14 @@ env 계약이고 `src/.env`는 로컬 실행 입력입니다. `verifyEnvKeys`는
### Traceable version + dependency locking
- 추적 가능한 checkout에서는 project version이 `<MAJOR>.<MINOR>.<PATCH>+<12자리 git sha>`가 됩니다.
base version은 `-PreleaseVersion`/`RELEASE_VERSION`, revision은 `-PgitRevision`/`GIT_SHA`/
`GITHUB_SHA` 순으로 주입하고, 로컬에서는 현재 Git commit을 읽습니다.
- Git metadata와 revision property가 모두 없는 일반 source archive build는 configuration 단계에서
실패하지 않고 `<MAJOR>.<MINOR>.<PATCH>-SNAPSHOT`으로 동작합니다. 다만 `releaseCheck`가 실행하는
`verifyReleaseProvenance`는 source revision이 없으면 실패하므로 추적 불가능한 산출물을 release로
취급할 수 없습니다.
- leaf version은 release version뿐입니다(`-PreleaseVersion`/`RELEASE_VERSION`, 기본 `0.0.1`).
revision(`-PgitRevision`/`GIT_SHA`/`GITHUB_SHA`)을 모르면 `-SNAPSHOT`이 붙습니다. revision은 jar
이름에 넣지 않고 각 jar manifest의 `Build-Revision`과 app-bootstrap의
`META-INF/build-info.properties`(`build.revision`)에 남깁니다. 예전에는 version이
`<MAJOR>.<MINOR>.<PATCH>+<sha>`라 커밋마다 새 jar 이름이 생겼고 그 잔여물을 `ca.archive-hygiene`이
치웠는데, 둘 다 없앴습니다(리뷰 BUILD-O3-5).
- `releaseCheck`가 실행하는 `verifyReleaseProvenance`는 source revision이 없으면 실패하므로 추적
불가능한 산출물을 release로 취급할 수 없습니다.
- 모든 subproject가 `lockAllConfigurations()` + `LockMode.STRICT`를 사용하고, lock state는 Gradle
기본 `<module>/gradle.lockfile`에 둡니다. 이 경로는 Renovate Gradle manager 기본 인식 경로와
같습니다.
@@ -121,7 +123,8 @@ Checkstyle은 파싱된 파일에 같은 질문을 하고, leaf 단위로 돕니
- **소유.** app-bootstrap. 이 질문("이 애플리케이션의 배포에 무엇을 줘야 하는가")은 composition
root의 것이고, `./gradlew :domain-core:check`가 알아야 할 사항이 아닙니다. 루트 집계 이름은
`configContractCheck`이고 구현은 `build-tools`의 `ca.config-contract` plugin입니다.
`configContractCheck`이고 구현은 `build-logic`의 `ca.config-contract` plugin입니다(소유자 결정 4:
태스크는 app-bootstrap에 유지, `build-tools` included build는 비워서 삭제).
- **하는 일.** `docs/registries/env-keys.yaml`, app-bootstrap의 `application*.yml` + `config/*.yml`,
capability 모듈이 싣는 `config/*.yml`·`config/module-defaults/*.yml`(기본 조립에 없어도 검사한다),
`src/.env.example`을 lock-step(서로 어긋나지 않게) 으로 유지합니다. `env-keys.yaml` 이 `APP_` 키의 SSOT 이고, drift 가 생기면 빌드를
@@ -532,7 +535,7 @@ migration/vendor 계약의 증거로 사용하지 않습니다. 멱등성 provid
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --wait db
```
컨테이너로 띄우는 `./gradlew bootstrap` 경로는 이 호스트 포트를 쓰지 않습니다. compose 가 app
컨테이너로 띄우는 `scripts/bootstrap-local.sh` 경로는 이 호스트 포트를 쓰지 않습니다. compose 가 app
컨테이너의 `APP_DATASOURCE_URL` 을 내부 네트워크 주소 `jdbc:postgresql://db:5432/...` 로 덮어씁니다.
`ca-skeleton.persistence.vendor`(`postgresql` | `h2`)가 어느 vendor 구성을 조립할지 고르는 단일
@@ -11,8 +11,11 @@ import dev.caskeleton.adapter.outbound.httpclient.testkit.ClientProfiles;
import dev.caskeleton.adapter.outbound.httpclient.testkit.TestGateways;
import dev.caskeleton.adapter.outbound.httpclient.testkit.ToxiproxyFixture;
import eu.rekawek.toxiproxy.Proxy;
import java.net.InetAddress;
import java.net.ServerSocket;
import java.net.URI;
import java.util.Map;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.GenericContainer;
@@ -37,27 +40,32 @@ class FailureInjectionContractTest {
System.getProperty("httpclient.fault.httpbin.image", "kennethreitz/httpbin:latest"))
.asCompatibleSubstituteFor("kennethreitz/httpbin");
/**
* A refused connect is the one fault that must be classified before anything is written.
*
* <p>This used to disable a Toxiproxy listener and call its published port. With Docker's
* userland proxy ({@code docker-proxy}, the default) the host port stays open and accepts the
* connect before closing it, so the client really did write the request and the evidence was
* {@code SENT_NO_RESPONSE}: the test measured the Docker network mode, not the adapter (review
* P11-new-3, NEW-16). A loopback port nobody listens on refuses the connect on every Docker
* configuration and without Docker at all.
*/
@Test
@SuppressWarnings("resource")
void disabledProxyFailsBeforeARequestCanBeSent() throws Exception {
ToxiproxyFixture.requireAvailable();
try (Network network = Network.newNetwork();
GenericContainer<?> upstream =
new GenericContainer<>(UPSTREAM_IMAGE)
.withNetwork(network)
.withNetworkAliases("upstream")
.withExposedPorts(80)) {
upstream.start();
try (ToxiproxyFixture toxiproxy = ToxiproxyFixture.start(network)) {
Proxy proxy = toxiproxy.proxyTo("connect-refused", "upstream", 80);
proxy.disable();
HttpClientException failure = callThrough(toxiproxy, "/get", ResponseType.of(byte[].class));
assertThat(failure.metadata().evidence()).isEqualTo(ExecutionEvidence.NOT_SENT);
assertThat(failure.getMessage()).doesNotContain("http://");
}
@DisplayName("연결이 거부되면 요청을 쓰기 전에 NOT_SENT 증거로 실패한다")
void refusedConnectionFailsBeforeARequestCanBeSent() throws Exception {
// given
int closedPort;
try (ServerSocket reserved = new ServerSocket(0, 1, InetAddress.getLoopbackAddress())) {
closedPort = reserved.getLocalPort();
}
URI refusing = URI.create("http://127.0.0.1:" + closedPort + "/");
// when
HttpClientException failure = call(refusing, "/get", ResponseType.of(byte[].class));
// then
assertThat(failure.metadata().evidence()).isEqualTo(ExecutionEvidence.NOT_SENT);
assertThat(failure.getMessage()).doesNotContain("http://");
}
@Test
@@ -87,8 +95,14 @@ class FailureInjectionContractTest {
private static <T> HttpClientException callThrough(
ToxiproxyFixture toxiproxy, String path, ResponseType<T> responseType) throws Exception {
URI baseUrl =
URI.create("http://" + toxiproxy.proxiedHost() + ":" + toxiproxy.proxiedPort() + "/");
return call(
URI.create("http://" + toxiproxy.proxiedHost() + ":" + toxiproxy.proxiedPort() + "/"),
path,
responseType);
}
private static <T> HttpClientException call(
URI baseUrl, String path, ResponseType<T> responseType) throws Exception {
try (TestGateways.Harness harness =
TestGateways.forProfile(ClientProfiles.builder("faulty").baseUrl(baseUrl).build())) {
return org.assertj.core.api.Assertions.catchThrowableOfType(
+12 -15
View File
@@ -75,19 +75,16 @@ apiSurface {
]
}
// NotificationEvidenceVerifierTest holds docs/notification/evidence-manifest.json, the support
// matrix it grades and the evidence files it names to each other. Those files are inputs of `test`,
// or Gradle would call it up to date after an edit to any of them.
def repositoryRoot = rootProject.projectDir.parentFile
tasks.named('test') {
inputs.files(
new File(repositoryRoot, 'docs/notification/evidence-manifest.json'),
new File(repositoryRoot, 'docs/notification/support-matrix.md'),
rootProject.file('adapter/outbound/persistence-jpa/build.gradle'))
.withPathSensitivity(PathSensitivity.RELATIVE)
inputs.files(fileTree(rootProject.projectDir) {
include 'adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/**'
include 'adapter/outbound/notification/src/test/java/**'
include 'application-notification/src/test/java/**'
}).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`
// (review 2026-09-24 BUILD-계획-B4-27). The verifier's fixture cases stay in `test`. A lane never
// reports up to date, so it needs no inputs declared for the files it reads.
strictTestLanes {
lane('notificationDocumentContractTest') {
tag = 'document-contract'
description = 'Holds the notification support matrix to the evidence manifest and the evidence it names.'
rejectSkipped = true
mainStage()
}
}
@@ -8,12 +8,16 @@ import dev.caskeleton.adapter.outbound.notification.evidence.NotificationEvidenc
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Path;
import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
class NotificationEvidenceVerifierTest {
// The repository's own documents, not a fixture: a main-stage lane
// (notificationDocumentContractTest).
@Test
@Tag("document-contract")
void repositorySupportMatrixClaimsNoMoreThanTheManifestProves() throws Exception {
// given
File repository = new File("../../../..").getCanonicalFile();
@@ -89,9 +89,18 @@ strictTestLanes {
requires 'dev.caskeleton.adapter.outbound.objectstorage.qualification.AwsS3QualificationPreconditionsTest'
rejectSkipped = true
jvmArgs '-Duser.timezone=UTC'
// 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
// 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'
}
}
}
tasks.named('check') {
// The MinIO lanes start a container, so they are the main-branch stage of this leaf, not its
// pull-request `check` (review BUILD-계획-B3); object-storage-qualification.yml runs them on pull
// requests that touch object storage, and integrationCheck runs them with every integration lane.
tasks.named('mainCheck') {
dependsOn 'objectStorageMinioContractTest', 'objectStorageMinioFaultTest'
}
+16 -45
View File
@@ -383,57 +383,28 @@ base task 외에 다음 candidate task가 Docker 부재 시 skip이 아니라
postgresqlIdempotencyIntegrationTest
```
### evidence manifest와 R2 gate
### readiness card 검사 (evidence manifest 폐기)
`readiness-cards.yaml`의 `evidence.scenarios`와 `evidence.task-claims`가 required evidence를 실제
JUnit selector/Gradle task에 연결한다. `verifyJpaReadinessRegistryContract`는 unknown claim,
duplicate selector와 다른 card task 차용을 mutation test로 거절한다.
테스트와 task에 연결한다. build-tools의 JPA evidence manifest(`ca.jpa-evidence`,
`ca.jpa-qualification`, `verifyJpaCandidateEvidence`, `verifyJpaPrimaryFoundationEvidence`,
`jpa-r2-evidence.yml`)는 소유자 결정 4(2026-09-25)로 폐기했다. 그 manifest가 증명하던 사실은
이제 두 곳에서 확인한다.
- `JpaReadinessRegistryTest`(이 leaf의 `test`): 카드 상태·선행 관계(순환 없음), 구현된 카드가
가리키는 이 leaf의 task가 `build.gradle`에 선언된 lane인지, 인용한 scenario 메서드가
`src/postgresqlIntegrationTest`에 있는지, required evidence가 모두 덮이는지, 소유 schema
stream의 location·history table이 고유하고 존재하는지.
- readiness lane 자체: 카드가 인용한 scenario마다 lane의 required test가 되고(`requires`),
lane은 skip을 거절한다(`rejectSkipped`). 실제 PostgreSQL이 없으면 skip이 아니라 실패한다.
```bash
./gradlew :adapter:outbound:persistence-jpa:verifyJpaCandidateEvidence --console=plain
./gradlew :adapter:outbound:persistence-jpa:test --tests '*JpaReadinessRegistryTest' --console=plain
./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck --console=plain # 모든 readiness·platform lane
```
위 task는 active card의 producer를 실행하고 JUnit XML에서 exact selector와
executed/skipped/failure/error 수를 읽는다. 각 manifest는 source revision/dirty digest,
prerequisite manifest ID, PostgreSQL image digest, pgjdbc/Hibernate/Flyway version, topology와
migration/dispatch metadata를 담고 다음 위치에 canonical JSON SHA-256 이름으로 생성된다.
```text
build/jpa-evidence/manifests/<card-id>/<sha256>.json
```
후보 검증은 zero-skip, schema, content hash와 prerequisite link가 맞으면 성공하지만
`attainedReadiness=R1`을 유지한다. 로컬 후보 lane은 다음 E2/E3 동작을 실제 PostgreSQL에서
검증한다.
- bounded pool saturation과 shutdown 뒤 connection 거부
- runtime/migration role 분리, trusted namespace, TLS `verify-full`의 정상·hostname mismatch·
untrusted CA·expired certificate 경로
- persistence failure의 HTTP/log/span redaction
- fresh/legacy adoption, interrupted migration forward recovery, N/N-1 additive rolling shape
- deadlock, action 실패 rollback, `inNew` 독립 commit, commit transport 단절(재시도 없음)
- idempotency 등 독립 stream의 disabled/first-enable/disable/re-enable/interrupted
lifecycle
각 manifest는 그래도 candidate profile, dirty source와 아직 R2가 아닌 prerequisite를
`readinessBlockers`에 보존하므로 후보 통과를 R2로 오인할 수 없다.
실제 aggregation gate는 별도 명령이다.
```bash
./gradlew \
:adapter:outbound:persistence-jpa:verifyJpaPrimaryFoundationEvidence \
-PjpaEvidenceProfile=r2 \
--console=plain
```
이 task는 clean revision, `JPA_EVIDENCE_CI_JOB`,
`JPA_EVIDENCE_ARTIFACT_LOCATION`, immutable PostgreSQL image digest, 모든 required evidence와
R2 prerequisite DAG가 있어야만 성공한다. `.github/workflows/ci-quality-gates.yml`의 candidate
job은 PR에서 zero-skip manifest를 보존하고, `.github/workflows/jpa-r2-evidence.yml`은 명시적으로
실행하는 production-profile lane이다. 로컬 dirty worktree 또는 unpublished 실행은
`worktree-is-dirty`/CI provenance blocker를 보고 실패하는 것이 정식 동작이다. R2 승격은 clean
revision에서 workflow를 실행하고 보존된 manifest artifact를 검토한 뒤에만 가능하다.
R2(운영 evidence) 승격은 더 이상 build가 판정하지 않는다. clean revision에서 위 lane을 돌린
CI 결과(`jpa-release` job의 JUnit XML artifact)를 검토해 결정한다.
stream migration이 중단되면 history/registry/object 상태를 먼저 확인하고 기존 migration을
임의 수정하거나 history를 바로 `repair`하지 않는다. 장애를 수정한 forward migration으로
@@ -2,7 +2,6 @@ plugins {
id 'ca.spring-library'
id 'ca.spring-config'
id 'java-test-fixtures'
id 'ca.jpa-evidence'
id 'ca.auxiliary-source-set'
id 'ca.api-surface'
}
@@ -140,7 +139,7 @@ dependencies {
// Real-PostgreSQL lanes. A readiness lane runs one named class (the security lane also names the
// runtime-role namespace-denial method), a platform lane selects a tag, and the pool lane has a
// source set of its own. jpa-release.yml and config/jpa/*.{json,yaml} name these tasks.
// source set of its own. release.yml (jpa-release-gate) and config/jpa/*.{json,yaml} name these tasks.
def jpaEvidenceImage = providers.gradleProperty('jpaPostgreSqlEvidenceImage').orElse('postgres:16-alpine').get()
def jpaMatrixVersions = providers.gradleProperty('jpa.matrix.versions').orElse('16').get()
def readinessLanes = [
@@ -169,6 +168,15 @@ def platformLanes = [
jpaPlatformQueryPlanTest: ['jpa-queryplan', 'Asserts query plan structure and planner estimate error (design §33).'],
jpaPlatformSecurityTest : ['jpa-security', 'Verifies runtime role privileges and search_path safety (design §36).'],
]
// Every scenario a readiness card cites (config/jpa/readiness-cards.yaml `evidence.scenarios`) is a
// required test of the lane that runs its class, and a readiness lane rejects skips. That is what the
// deleted JPA evidence manifest used to establish from JUnit XML after the fact; JpaReadinessRegistryTest
// checks the cards themselves.
def readinessScenarios = new groovy.json.JsonSlurper()
.parse(rootProject.file('config/jpa/readiness-cards.yaml'))
.cards.values()
.findAll { it.state != 'not-implemented' }
.collectMany { card -> (card.evidence?.scenarios ?: []).collect { it.selector } }
strictTestLanes {
readinessLanes.each { taskName, selection ->
String testClass = 'dev.caskeleton.adapter.outbound.persistence.readiness.' + selection[0]
@@ -178,6 +186,13 @@ strictTestLanes {
description = 'Runs the no-skip real PostgreSQL readiness scenario ' + testClass + '.'
requires testClass
selection.drop(1).each { method -> requires testClass + '.' + method }
readinessScenarios.findAll { it.startsWith(testClass + '#') }.each { selector ->
String method = testClass + '.' + selector.substring(selector.indexOf('#') + 1)
if (!selection.drop(1).contains(selector.substring(selector.indexOf('#') + 1))) {
requires method
}
}
rejectSkipped = true
jvmArgs '-Duser.timezone=UTC', '-Djpa.evidence.postgresql.image=' + jpaEvidenceImage
}
}
@@ -205,7 +220,7 @@ tasks.named('postgresqlSecurityBaselineIntegrationTest') {
dependsOn ':adapter:inbound:web:jpaPersistenceRedactionContractTest'
}
// Which JPA lanes block a release is declared by .github/workflows/jpa-release.yml.
// Which JPA lanes block a release is declared by config/jpa/release-registry.json (jpaReleaseQualification below).
// This leaf declares the lanes and how each runs; it does not own release orchestration.
// The unit lane reads three files that are not Java sources: the release registry and its two
@@ -217,6 +232,9 @@ tasks.named('postgresqlSecurityBaselineIntegrationTest') {
// exactly those edits never run on them.
tasks.named('test') {
inputs.file(rootProject.file('config/jpa/release-registry.json'))
// JpaReadinessRegistryTest: the readiness cards, the lanes they name and the scenarios they cite.
inputs.file(rootProject.file('config/jpa/readiness-cards.yaml'))
inputs.dir(file('src/postgresqlIntegrationTest/java')).withPropertyName('readinessScenarioSources')
inputs.file(new File(rootProject.projectDir.parentFile, 'docs/jpa/support-matrix.md'))
inputs.file(new File(rootProject.projectDir.parentFile, 'docs/jpa/repository-adaptation.md'))
// The whole directory, not the two named workflows: the Experimental-major check asks whether
@@ -225,12 +243,6 @@ tasks.named('test') {
inputs.dir(new File(rootProject.projectDir.parentFile, '.github/workflows'))
inputs.file(file('build.gradle'))
inputs.dir(file('src/jpaPlatformPerformanceTest/java'))
// JpaAdopterApiSurfaceTest: every other leaf's production sources and the adopter baseline.
inputs.file(new File(rootProject.projectDir.parentFile, 'docs/architecture/jpa-adopter-api-surface.txt'))
inputs.files(fileTree(rootProject.projectDir) {
include '**/src/main/java/**/*.java'
exclude '**/build/**', 'adapter/outbound/persistence-jpa/**', 'adapter/outbound/persistence-fileserver/**'
}).withPathSensitivity(PathSensitivity.RELATIVE).withPropertyName('adopterSources')
}
// verifyJpaApiSurface — every public type this leaf exposes is a committed decision.
@@ -255,13 +267,28 @@ apiSurface {
'surface; the rest is implementation that has not been moved under an internal',
'root yet.',
]
// The reviewed subset other leaves' production code may import. The two leaves that implement
// JPA persistence (this one and persistence-fileserver) are the implementation, not adopters.
// This used to be JpaAdopterApiSurfaceTest, a regular-expression import scan beside the
// convention (review 2026-09-24 BUILD-중복-3); the convention parses imports with javac now.
adopterBaseline = rootProject.file('../docs/architecture/jpa-adopter-api-surface.txt')
adopterSources = fileTree(rootProject.projectDir) {
include '*/**/src/main/java/**/*.java'
exclude '**/build/**', 'adapter/outbound/persistence-jpa/**', 'adapter/outbound/persistence-fileserver/**',
'build-logic/**', 'optional-platforms/**'
}
}
// The JPA readiness registry describes this platform's lanes and resolves their task paths. It runs
// in the main-branch stage (`mainCheck`), not in `check`. The task itself is registered by the
// ca.jpa-qualification plugin from build-tools, which the root applies.
tasks.named('mainCheck') {
dependsOn rootProject.tasks.named('verifyJpaReadinessRegistry')
// The release registry (config/jpa/release-registry.json) names the blocking release gates; this
// aggregate runs exactly those. It replaced the build-tools `ca.jpa-qualification` plugin (review
// 2026-09-24 BUILD-O3-2): a gate that names a task that does not exist fails when the task graph is
// built, which is the whole of what `verifyJpaReleaseGateTasks` used to check.
tasks.register('jpaReleaseQualification') {
group = 'verification'
description = 'Runs exactly the blocking JPA release gates declared by config/jpa/release-registry.json.'
dependsOn(new groovy.json.JsonSlurper()
.parse(rootProject.file('config/jpa/release-registry.json'))
.gates.findAll { it.blocking }.collect { it.task })
}
@@ -1,92 +0,0 @@
package dev.caskeleton.adapter.outbound.persistence;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.IOException;
import java.nio.file.FileVisitResult;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.SimpleFileVisitor;
import java.nio.file.attribute.BasicFileAttributes;
import java.util.ArrayList;
import java.util.List;
import java.util.Set;
import java.util.TreeSet;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.junit.jupiter.api.Test;
/**
* Production code outside this leaf imports only the persistence types the adopter baseline lists.
*
* <p>A language-level public type is not a compatibility promise; the baseline is. The leaves that
* own JPA persistence implementations (this one and persistence-fileserver) are the implementation
* rather than adopters of it. The build declares every production source and the baseline as inputs
* of {@code test}.
*/
class JpaAdopterApiSurfaceTest {
private static final Path SOURCE_ROOT = Path.of("../../..").toAbsolutePath().normalize();
private static final Path BASELINE =
SOURCE_ROOT.resolve("../docs/architecture/jpa-adopter-api-surface.txt");
private static final Pattern IMPORT =
Pattern.compile(
"^\\s*import\\s+(dev\\.caskeleton\\.adapter\\.outbound\\.persistence\\.[A-Za-z0-9_$.]+)\\s*;\\s*$");
private static final List<String> OWNERS =
List.of("adapter/outbound/persistence-jpa/", "adapter/outbound/persistence-fileserver/");
@Test
void productionCodeElsewhereImportsOnlyTheReviewedAdopterSurface() throws IOException {
// given
Set<String> allowed = new TreeSet<>();
for (String line : Files.readAllLines(BASELINE)) {
if (!line.isBlank() && !line.startsWith("#")) {
allowed.add(line.trim());
}
}
// when
Set<String> unreviewed = new TreeSet<>();
for (Path source : adopterSources()) {
for (String line : Files.readAllLines(source)) {
Matcher matcher = IMPORT.matcher(line);
if (matcher.matches() && !allowed.contains(matcher.group(1))) {
unreviewed.add(SOURCE_ROOT.relativize(source) + ": " + matcher.group(1));
}
}
}
// then
assertThat(unreviewed).isEmpty();
}
private static List<Path> adopterSources() throws IOException {
List<Path> sources = new ArrayList<>();
Files.walkFileTree(
SOURCE_ROOT,
new SimpleFileVisitor<>() {
@Override
public FileVisitResult preVisitDirectory(Path directory, BasicFileAttributes attributes) {
String name = directory.getFileName() == null ? "" : directory.getFileName().toString();
String path = SOURCE_ROOT.relativize(directory).toString().replace('\\', '/') + "/";
boolean skipped =
name.equals("build")
|| name.startsWith(".")
|| OWNERS.stream().anyMatch(path::startsWith);
return skipped && !directory.equals(SOURCE_ROOT)
? FileVisitResult.SKIP_SUBTREE
: FileVisitResult.CONTINUE;
}
@Override
public FileVisitResult visitFile(Path file, BasicFileAttributes attributes) {
String path = file.toString().replace('\\', '/');
if (path.endsWith(".java") && path.contains("/src/main/java/")) {
sources.add(file);
}
return FileVisitResult.CONTINUE;
}
});
return sources;
}
}
@@ -0,0 +1,262 @@
package dev.caskeleton.adapter.outbound.persistence.testkit;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
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 tools.jackson.databind.JsonNode;
import tools.jackson.databind.json.JsonMapper;
/**
* The JPA readiness cards ({@code src/config/jpa/readiness-cards.yaml}) against the lanes and tests
* they name.
*
* <p>This replaced the build-tools {@code ca.jpa-qualification}/{@code ca.jpa-evidence} plugins
* (review 2026-09-24 BUILD-O3-2, owner decision 4). The evidence manifest they generated is gone;
* what it proved is split between this test (the registry is well formed and every lane, scenario
* and migration stream it names exists) and the readiness lanes themselves, which require every
* scenario selector a card cites and reject skipped tests. The build declares the registry and the
* readiness sources as inputs of {@code test}.
*/
class JpaReadinessRegistryTest {
private static final Path SOURCE_ROOT = Path.of("../../..").toAbsolutePath().normalize();
private static final Path REGISTRY = SOURCE_ROOT.resolve("config/jpa/readiness-cards.yaml");
private static final Path LEAF = SOURCE_ROOT.resolve("adapter/outbound/persistence-jpa");
private static final String LEAF_PATH = ":adapter:outbound:persistence-jpa:";
private static final Set<String> STATES =
Set.of("selected", "implemented-candidate", "not-implemented");
private static final Set<String> LEAF_AGGREGATES = Set.of("test", "integrationTestLaneCheck");
private static final Pattern LANE_NAME =
Pattern.compile("^\\s*(?:lane\\('(\\w+)'\\)|(\\w+)\\s*:\\s*\\[)", Pattern.MULTILINE);
private final JsonNode registry = JsonMapper.builder().build().readTree(REGISTRY.toFile());
@Test
@DisplayName("모든 카드의 상태와 선행 카드가 유효하고 선행 관계에 순환이 없다")
void everyCardHasALegalStateAndAnAcyclicSetOfKnownPrerequisites() {
// given
Map<String, JsonNode> cards = cards();
// when
List<String> violations = new ArrayList<>();
cards.forEach(
(id, card) -> {
String state = card.path("state").asString();
if (!STATES.contains(state)) {
violations.add(id + ": unknown state " + state);
}
for (JsonNode prerequisite : card.path("prerequisites")) {
JsonNode target = cards.get(prerequisite.asString());
if (target == null) {
violations.add(id + ": unknown prerequisite " + prerequisite.asString());
} else if (state.equals("selected")
&& !target.path("state").asString().equals("selected")) {
violations.add(id + ": selected card requires non-selected " + prerequisite);
}
}
if (hasCycle(id, cards, new HashSet<>())) {
violations.add(id + ": prerequisite cycle");
}
});
// then
assertThat(violations).isEmpty();
}
@Test
@DisplayName("구현된 카드가 가리키는 이 leaf의 task는 build.gradle에 선언된 lane이다")
void everyImplementedCardNamesTasksThisLeafDeclares() throws IOException {
// given
Set<String> declared = declaredLaneNames();
// when
List<String> unknown = new ArrayList<>();
activeCards()
.forEach(
(id, card) -> {
List<String> tasks = new ArrayList<>();
tasks.add(card.path("readiness-task").asString());
card.path("support-tasks").forEach(task -> tasks.add(task.asString()));
for (String task : tasks) {
if (task.startsWith(LEAF_PATH)) {
String name = task.substring(LEAF_PATH.length());
if (!declared.contains(name) && !LEAF_AGGREGATES.contains(name)) {
unknown.add(id + ": " + task);
}
} else if (!task.startsWith(":")) {
unknown.add(id + ": not an absolute task path " + task);
}
}
});
// then
assertThat(unknown).isEmpty();
}
@Test
@DisplayName("구현된 카드의 evidence는 존재하는 테스트 메서드와 카드가 요구한 항목만 가리킨다")
void everyEvidenceScenarioNamesAnExistingTestMethodAndARequiredClaim() {
// given
Map<String, JsonNode> active = activeCards();
// when
List<String> violations = new ArrayList<>();
Set<String> selectors = new HashSet<>();
active.forEach(
(id, card) -> {
Set<String> allowed = new HashSet<>();
card.path("required-evidence").forEach(claim -> allowed.add(claim.asString()));
if (!allowed.remove("no-skip")) {
violations.add(id + ": required-evidence must include no-skip");
}
card.path("migration")
.path("lifecycle-evidence")
.forEach(stage -> allowed.add("migration-lifecycle:" + stage.asString()));
Set<String> covered = new HashSet<>();
for (JsonNode scenario : card.path("evidence").path("scenarios")) {
String selector = scenario.path("selector").asString();
if (!selectors.add(selector)) {
violations.add(id + ": duplicate selector " + selector);
}
if (!testMethodExists(selector)) {
violations.add(id + ": no such readiness test method " + selector);
}
scenario.path("covers").forEach(claim -> covered.add(claim.asString()));
}
for (JsonNode claim : card.path("evidence").path("task-claims")) {
claim.path("covers").forEach(cover -> covered.add(cover.asString()));
}
Set<String> unknownClaims = new HashSet<>(covered);
unknownClaims.removeAll(allowed);
if (!unknownClaims.isEmpty()) {
violations.add(id + ": covers requirements it does not declare " + unknownClaims);
}
Set<String> uncovered = new HashSet<>(allowed);
uncovered.removeAll(covered);
uncovered.removeIf(claim -> claim.startsWith("migration-lifecycle:"));
if (!uncovered.isEmpty()) {
violations.add(id + ": required evidence nothing covers " + uncovered);
}
});
// then
assertThat(violations).isEmpty();
}
@Test
@DisplayName("소유 schema stream마다 고유한 migration 위치와 history table이 있고 구현된 stream의 위치는 존재한다")
void everyOwnedSchemaStreamHasAUniqueExistingLocationAndHistoryTable() {
// given
Map<String, JsonNode> cards = cards();
// when
List<String> violations = new ArrayList<>();
Map<String, String> locations = new HashMap<>();
Map<String, String> historyTables = new HashMap<>();
cards.forEach(
(id, card) -> {
boolean owned = card.path("schema-stream").asString().equals("owned");
JsonNode migration = card.path("migration");
if (owned != !migration.isMissingNode()) {
violations.add(id + ": an owned schema stream and a migration go together");
return;
}
if (!owned) {
return;
}
String location = migration.path("location").asString();
String history = migration.path("history-table").asString();
if (locations.put(location, id) != null) {
violations.add(id + ": duplicate migration location " + location);
}
if (historyTables.put(history, id) != null) {
violations.add(id + ": duplicate history table " + history);
}
if (!card.path("state").asString().equals("not-implemented")
&& !migrationLocationExists(location)) {
violations.add(id + ": no persistence leaf ships " + location);
}
});
// then
assertThat(violations).isEmpty();
}
private Map<String, JsonNode> cards() {
Map<String, JsonNode> cards = new HashMap<>();
registry
.path("cards")
.properties()
.forEach(entry -> cards.put(entry.getKey(), entry.getValue()));
return cards;
}
private Map<String, JsonNode> activeCards() {
Map<String, JsonNode> active = new HashMap<>(cards());
active.values().removeIf(card -> card.path("state").asString().equals("not-implemented"));
return active;
}
private static boolean hasCycle(String id, Map<String, JsonNode> cards, Set<String> path) {
if (!path.add(id)) {
return true;
}
JsonNode card = cards.get(id);
if (card != null) {
for (JsonNode prerequisite : card.path("prerequisites")) {
if (hasCycle(prerequisite.asString(), cards, path)) {
return true;
}
}
}
path.remove(id);
return false;
}
private static Set<String> declaredLaneNames() throws IOException {
Set<String> names = new HashSet<>();
Matcher matcher = LANE_NAME.matcher(Files.readString(LEAF.resolve("build.gradle")));
while (matcher.find()) {
names.add(matcher.group(1) != null ? matcher.group(1) : matcher.group(2));
}
return names;
}
private static boolean testMethodExists(String selector) {
int hash = selector.indexOf('#');
if (hash < 0) {
return false;
}
Path source =
LEAF.resolve("src/postgresqlIntegrationTest/java")
.resolve(selector.substring(0, hash).replace('.', '/') + ".java");
try {
return Files.isRegularFile(source)
&& Files.readString(source).contains("void " + selector.substring(hash + 1) + "(");
} catch (IOException unreadable) {
return false;
}
}
private static boolean migrationLocationExists(String location) {
try (Stream<Path> leaves = Files.list(SOURCE_ROOT.resolve("adapter/outbound"))) {
return leaves.anyMatch(
leaf -> Files.isDirectory(leaf.resolve("src/main/resources").resolve(location)));
} catch (IOException unreadable) {
return false;
}
}
}
@@ -31,7 +31,7 @@ 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/jpa-release.yml");
private final String releaseWorkflow = read(".github/workflows/release.yml");
private final String nightlyWorkflow = read(".github/workflows/jpa-nightly.yml");
@Test
@@ -226,12 +226,17 @@ tasks.named('check') {
dependsOn 'mongoStableContractTest'
}
// MongoTestLaneContractTest reads the integration sources' lane tags and the release-contract
// manifest; both are inputs here, or Gradle would call `test` up to date after editing either.
tasks.named('test') {
inputs.dir('src/mongoIntegrationTest/java').withPathSensitivity(PathSensitivity.RELATIVE)
inputs.file(rootProject.file('config/mongodb/release-contracts.json'))
.withPathSensitivity(PathSensitivity.RELATIVE)
// MongoTestLaneContractTest compares the integration sources' lane tags with the release-contract
// manifest. A comparison with a repository document, so it runs in this leaf's `mainCheck`, not in
// the pull-request `test` (review 2026-09-24 BUILD-계획-B4-30). A lane never reports up to date, so
// it needs no inputs declared for the files it reads.
strictTestLanes {
lane('mongoDocumentContractTest') {
tag = 'document-contract'
description = 'Holds the Mongo lane tags to config/mongodb/release-contracts.json.'
rejectSkipped = true
mainStage()
}
}
@@ -23,9 +23,10 @@ import tools.jackson.databind.json.JsonMapper;
/**
* The Mongo lanes are defined by tags, so a tag mistake moves a test between lanes without any
* build failure. These two rules read the files the lanes are built from; the build declares both
* as inputs of this leaf's {@code test} task.
* build failure. These two rules read the files the lanes are built from. They run in the
* main-stage lane {@code mongoDocumentContractTest}, which always executes, not in {@code test}.
*/
@Tag("document-contract")
class MongoTestLaneContractTest {
private static final Path INTEGRATION_SOURCES = Path.of("src/mongoIntegrationTest/java");
+37 -1
View File
@@ -110,7 +110,8 @@ sourceSets {
// Every capability a service can select — the commented runtimeOnly lines below — listed once.
// Two consumers read it: the whole-repository ArchUnit import (spec §7: the architecture suite sees
// every module, the shipped runtime only the selected ones) and the qualification artifact the
// every module of this build and the sample, the shipped runtime only the selected ones; the
// optional-platforms build is held by its own Gradle direction gate instead) and the qualification artifact the
// Compose lanes boot (qualificationBootJar, below). Neither reaches `bootJar`, `test` or
// `systemTest`, because a capability on a classpath is switched on there by its mere presence.
// A new capability leaf is added here and as a commented line below; nowhere else.
@@ -154,6 +155,14 @@ dependencies {
// runtimeOnly project(':composition:notification-platform') // 알림 (persistence-jpa 줄도 함께 푼다)
capabilityProjects.each { architectureTestRuntimeOnly project(it) }
// The sample is the reference adopters copy, so the whole-repository rules read it too (review
// BUILD-중복-8). Architecture-test runtime only: no production configuration reaches it.
//
// What this import does NOT see: the optional-platforms build (`grpc:*`, `grpc-advanced:*`).
// It is a separate Gradle build, so its classes cannot be on this classpath; its registered
// leaves are held by the Gradle direction gate (`-p optional-platforms ci` runs
// verifyCleanArchitectureDependencies), which is the whole of what the owner decided it needs.
architectureTestRuntimeOnly project(':sample-portfolio')
// The capability integration lane selects Fileserver and object storage together, as a service
// would, and turns off whichever one a test is not about.
@@ -311,6 +320,33 @@ bootJar {
mainClass = 'dev.caskeleton.bootstrap.CaSkeletonApplication'
}
// The deployable artifact names the release and the commit it was built from in
// META-INF/build-info.properties (review BUILD-O3-5: provenance through Spring Boot's build info
// rather than a revision in every leaf's jar name). `time` is excluded so an unchanged commit still
// produces an unchanged resource and cached tasks stay cached.
springBoot {
buildInfo {
excludes = ['time']
properties {
additional = ['revision': rootProject.releaseProvenance.sourceRevision]
}
}
}
// The deny-by-default public path baseline (docs/security/public-paths-snapshot.txt) is an approval
// test beside the security configuration it pins, not a build-logic plugin (review BUILD-O3-5). The
// root `verifyPublicPathSnapshot` names this lane; `-PapprovePublicPathChange` rewrites the baseline
// after review instead of comparing it.
strictTestLanes {
lane('publicPathSnapshotTest') {
tag = 'public-path-snapshot'
description = 'Compares the shipped public path default with the reviewed baseline.'
rejectSkipped = true
mainStage()
systemProperty 'publicpath.snapshot.write', project.hasProperty('approvePublicPathChange') ? 'true' : 'false'
}
}
tasks.register('stageDockerJar', Sync) {
dependsOn tasks.named('bootJar')
from(tasks.named('bootJar').flatMap { it.archiveFile })
+1
View File
@@ -20,6 +20,7 @@ com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,architectureTes
com.github.docker-java:docker-java-api:3.7.1=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,systemTestCompileClasspath,testCompileClasspath,testRuntimeClasspath
com.github.docker-java:docker-java-transport-zerodep:3.7.1=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,systemTestCompileClasspath,testCompileClasspath,testRuntimeClasspath
com.github.docker-java:docker-java-transport:3.7.1=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,systemTestCompileClasspath,testCompileClasspath,testRuntimeClasspath
com.github.f4b6a3:uuid-creator:6.1.1=architectureTestRuntimeClasspath
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,architectureTestAnnotationProcessor,conditionalTransportBuildContractTestAnnotationProcessor,integrationTestAnnotationProcessor,systemTestAnnotationProcessor,testAnnotationProcessor
com.github.luben:zstd-jni:1.5.6-10=architectureTestRuntimeClasspath,qualificationRuntimeClasspath
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
@@ -159,7 +159,7 @@ ca-skeleton:
presentation:
# Pinned even though application.yml has an inline default, because the default is /v1 and
# src/.env says /api. Everything that names a URL in this repository — SECURITY_PUBLIC_PATHS,
# the compose healthchecks, bootstrapSmoke, the README curl — assumes /api, so a launcher that
# the compose healthchecks, scripts/bootstrap-local.sh, the README curl — assumes /api, so a launcher that
# missed src/.env served /v1/healthcheck and answered 401 on the address the docs give.
api-base-path: /api
privacy:
@@ -11,6 +11,7 @@ import java.util.List;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.yaml.snakeyaml.LoaderOptions;
import org.yaml.snakeyaml.Yaml;
@@ -33,21 +34,26 @@ class DeveloperExperienceContractTest {
}
@Test
void bootstrapEntrypointIsOwnedByDeveloperBootstrapPlugin() throws IOException {
String build = read("src/build.gradle");
@DisplayName("로컬 기동 진입점은 네 단계를 순서대로 밟는 scripts/bootstrap-local.sh 하나다")
void theLocalBootstrapEntrypointIsOneScriptWithFourOrderedStages() throws IOException {
// given
Path script = REPOSITORY_ROOT.resolve("scripts/bootstrap-local.sh");
// Registration and ordering are executable behavior and are covered by
// DeveloperBootstrapPluginFunctionalTest. The repository contract only fixes ownership: the
// root applies one Java convention and must not duplicate the bootstrap implementation in
// Groovy.
assertThat(build)
.contains("id 'ca.developer-bootstrap'")
.doesNotContain("tasks.register('bootstrapCompile')")
.doesNotContain("tasks.register('bootstrapDockerPreflight')")
.doesNotContain("tasks.register('bootstrapDependencies')")
.doesNotContain("tasks.register('bootstrapMigrateAndStart')")
.doesNotContain("tasks.register('bootstrapSmoke')")
.doesNotContain("tasks.register('bootstrap')");
// when
String body = Files.readString(script);
// then
// It replaced the build-logic ca.developer-bootstrap plugin (review BUILD-O3-5); starting
// containers and probing a port is not a build rule. `set -e` is what makes the order a
// contract: a stage runs only when the one before it succeeded.
assertThat(Files.isExecutable(script)).isTrue();
assertThat(body).contains("set -euo pipefail");
assertThat(body.indexOf("bootstrap 1/4"))
.isPositive()
.isLessThan(body.indexOf("bootstrap 2/4"));
assertThat(body.indexOf("bootstrap 2/4")).isLessThan(body.indexOf("bootstrap 3/4"));
assertThat(body.indexOf("bootstrap 3/4")).isLessThan(body.indexOf("bootstrap 4/4"));
assertThat(read("src/build.gradle")).doesNotContain("ca.developer-bootstrap");
}
@Test
@@ -110,7 +116,7 @@ class DeveloperExperienceContractTest {
String readme = read("README.md");
assertThat(readme)
.contains("./gradlew bootstrap")
.contains("scripts/bootstrap-local.sh")
.contains("GET /api/healthcheck")
.contains("## 퀵스타트")
.contains("첫 실행 진입점은 하나입니다.");
@@ -255,15 +261,19 @@ 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). The fileserver workflow's filtered second run was removed (review
// BUILD-중복-6), 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 execute architecture tests through their source-set"
+ " task")
.contains(":app-bootstrap:architectureTest")
.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 delegates repository architecture policy to releaseCheck")
.as("the release workflow runs the tag-only checks through releaseCheck")
.contains("./gradlew :releaseCheck")
.doesNotContain(staleSelector);
@@ -0,0 +1,153 @@
package dev.caskeleton.bootstrap.security;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
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.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
/**
* The deny-by-default public path surface against its committed, reviewed baseline.
*
* <p>An approval test rather than the build-logic {@code ca.public-path-snapshot} plugin it
* replaced (review 2026-09-24 BUILD-O3-5): the rule is about this composition root's shipped
* security configuration, so it lives beside it. The repository comparison runs in the main-stage
* lane {@code publicPathSnapshotTest} (root alias {@code verifyPublicPathSnapshot}); approving a
* reviewed change is {@code ./gradlew verifyPublicPathSnapshot -PapprovePublicPathChange}, which
* rewrites the baseline instead of comparing. The rendering cases run in {@code test}.
*/
class PublicPathSnapshotTest {
private static final Path SECURITY_CONFIGURATION =
Path.of("src/main/resources/config/security.yml");
private static final Path SNAPSHOT = Path.of("../../docs/security/public-paths-snapshot.txt");
private static final Pattern BINDING = Pattern.compile("^\\s*public-paths:\\s*(\\S.*?)\\s*$");
private static final Pattern DEFAULTED_PLACEHOLDER =
Pattern.compile("\\$\\{[A-Za-z0-9_.]+:([^{}]*)}");
private static final String HEADER =
"""
# feature-security-operational-baseline D5 — deny-by-default public path snapshot.
# SSOT: ca-skeleton.security.public-paths default in app-bootstrap/src/main/resources/config/security.yml
# -> SecurityConfig permitAll(); anyRequest authenticated. An operator's own SECURITY_PUBLIC_PATHS
# overrides it at run time and is outside this snapshot.
# Update only after review with: ./gradlew verifyPublicPathSnapshot -PapprovePublicPathChange
""";
@Test
@Tag("public-path-snapshot")
@DisplayName("배포되는 public path 기본값이 검토된 기준선과 같다")
void theShippedPublicPathDefaultMatchesTheReviewedBaseline() throws IOException {
// given
String rendered = render(Files.readAllLines(SECURITY_CONFIGURATION, StandardCharsets.UTF_8));
if (Boolean.getBoolean("publicpath.snapshot.write")) {
Files.writeString(SNAPSHOT, rendered, StandardCharsets.UTF_8);
}
// when
String committed =
Files.isRegularFile(SNAPSHOT) ? Files.readString(SNAPSHOT, StandardCharsets.UTF_8) : "";
// then
assertThat(committed)
.as(
"the deny-by-default public path surface changed, so a protected endpoint may now be"
+ " public. Review it, then run ./gradlew verifyPublicPathSnapshot"
+ " -PapprovePublicPathChange")
.isEqualTo(rendered);
}
@Test
@DisplayName("중첩된 기본값 placeholder를 풀어 정렬된 경로 목록으로 만든다")
void nestedDefaultedPlaceholdersUnwindToASortedPathList() {
// given
List<String> configuration =
List.of(
"ca-skeleton:",
" security:",
" public-paths: ${SECURITY_PUBLIC_PATHS:${API_BASE:/v1}/z,${API_BASE:/v1}/a}");
// when
String rendered = render(configuration);
// then
assertThat(rendered).isEqualTo(HEADER + "/v1/a\n/v1/z\n");
}
@Test
@DisplayName("기본값 없는 placeholder가 남으면 기준선을 만들지 않고 실패한다")
void aPlaceholderWithoutADefaultCannotBeSnapshotted() {
// given
List<String> configuration = List.of(" public-paths: ${SECURITY_PUBLIC_PATHS}");
// when
Throwable failure = catchThrowable(() -> render(configuration));
// then
assertThat(failure)
.isInstanceOf(IllegalStateException.class)
.hasMessageContaining("still holds a placeholder with no default");
}
@Test
@DisplayName("public-paths 바인딩이 정확히 하나가 아니면 실패한다")
void aConfigurationWithoutExactlyOneBindingIsRefused() {
// given
List<String> configuration = List.of("ca-skeleton:", " security: {}");
// when
Throwable failure = catchThrowable(() -> render(configuration));
// then
assertThat(failure)
.isInstanceOf(IllegalStateException.class)
.hasMessageContaining("expected exactly one 'public-paths:' binding, found 0");
}
private static String render(List<String> configuration) {
List<String> bindings = new ArrayList<>();
for (String line : configuration) {
Matcher matcher = BINDING.matcher(line);
if (matcher.matches()) {
bindings.add(matcher.group(1));
}
}
if (bindings.size() != 1) {
throw new IllegalStateException(
"expected exactly one 'public-paths:' binding, found "
+ bindings.size()
+ " — the snapshot cannot say which surface it pins");
}
String raw = bindings.getFirst();
for (int depth = 0; depth < 16; depth++) {
Matcher matcher = DEFAULTED_PLACEHOLDER.matcher(raw);
if (!matcher.find()) {
break;
}
raw = raw.substring(0, matcher.start()) + matcher.group(1) + raw.substring(matcher.end());
}
if (raw.contains("${")) {
throw new IllegalStateException(
"'public-paths' resolves to '"
+ raw
+ "', which still holds a placeholder with no default — the deployed surface is not"
+ " determined by the repository");
}
List<String> paths =
Pattern.compile(",")
.splitAsStream(raw)
.map(String::trim)
.filter(value -> !value.isEmpty())
.sorted()
.toList();
return HEADER + (paths.isEmpty() ? "" : String.join("\n", paths) + "\n");
}
}
+3
View File
@@ -7,6 +7,9 @@ plugins {
// composition and diagnostic rendering belong to adapters/bootstrap.
dependencies {
// The direction the registry, AGENTS.md and the layer workflow all state: a use case orchestrates
// the domain (review S1-#16). modules.json has allowed this edge all along; the build had lost it.
implementation project(':domain-core')
implementation project(':shared-contract')
// Port contracts (`*Contract`) are abstract JUnit classes that fakes and adapters both extend.
+11 -4
View File
@@ -15,12 +15,13 @@ capability, and the files it reads are declared as that test task's inputs.
| `ca.quality-conventions` | Spotless, Checkstyle, Error Prone, SpotBugs/FindSecBugs wiring shared by Java leaves |
| `ca.java-library` / `ca.spring-library` / `ca.spring-config` | leaf-level composition of the Java/quality conventions for plain and Spring libraries |
| `ca.platform-module` / `ca.grpc-platform-module` | what a vendored platform leaf (`messaging:*`, `grpc:*`, `grpc-advanced:*`) is: `java-library`, plus the gRPC BOM for the leaves that had it |
| `ca.strict-test-lane` | the one "named tests ran, none skipped" mechanism: tagged / named / own-source-set `Test` lanes that fail when they execute nothing, miss a `requires` class, or (with `rejectSkipped`) skip anything |
| `ca.strict-test-lane` | the one "named tests ran, none skipped" mechanism: tagged / named / own-source-set `Test` lanes that fail when they execute nothing, miss a `requires` class, or (with `rejectSkipped`) skip anything. `mainStage()` moves a tagged lane out of `test` into the leaf's `mainCheck`; `explicitOnly(reason)` keeps a lane that needs an outside input out of every aggregate, and the aggregate prints the reason |
| `ca.redis-topology-lane` | the Redis topology lane (mode selection, `-P` property validation, per-mode required classes) the redis-sdk-topology workflow drives |
| `ca.auxiliary-source-set` | extra test source sets |
| `ca.api-surface` | read-only public API surface verification with a separate update task, wired into `mainCheck` |
| `ca.public-path-snapshot`, `ca.archive-hygiene`, `ca.release-provenance` | the permitAll baseline, stale traceable jars, release version and revision |
| `ca.developer-bootstrap`, `ca.bootrun-dotenv` | the ordered local start-up and `bootRun`'s `.env` |
| `ca.api-surface` | read-only public API surface verification with a separate update task, wired into the leaf's `check` (owner decision 20); optionally holds other leaves' imports to a reviewed adopter subset (`adopterBaseline`) |
| `ca.release-provenance` | release version and revision (`verifyReleaseProvenance`); leaf versions carry the release version only |
| `ca.config-contract` | app-bootstrap's `verifyEnvKeys` (moved from the deleted build-tools included build; owner decision 4 keeps the task in app-bootstrap) |
| `ca.bootrun-dotenv` | `bootRun`'s `.env` |
Plain classes rather than plugins, because settings and projects load plugins through different
mechanisms and more than one caller needs each:
@@ -45,6 +46,12 @@ Error Prone, `-Werror`, SpotBugs and Checkstyle off for benchmark and generated
| `ca.jpa-test-lanes` | the lanes declared in `adapter/outbound/persistence-jpa/build.gradle` |
| `ca.test-jvm-agents`, `quarantineTest` | `ca.java-conventions`; the quarantine bucket had no tests |
| `ca.jmh-benchmarks` | `me.champeau.jmh` |
| build-tools `ca.jpa-evidence`, `ca.jpa-qualification` (+ `junit` evidence reader) | owner decision 4: persistence-jpa `JpaReadinessRegistryTest`, readiness lanes that require every cited scenario and reject skips, the leaf's `jpaReleaseQualification` aggregate over `config/jpa/release-registry.json` |
| build-tools `ca.config-contract` | moved here unchanged |
| `ca.public-path-snapshot` | app-bootstrap `PublicPathSnapshotTest` (lane `publicPathSnapshotTest`, root alias `verifyPublicPathSnapshot`) |
| `ca.archive-hygiene` | nothing to clean: leaf versions no longer carry the revision, so no stale traceable jar is produced |
| `ca.developer-bootstrap` | `scripts/bootstrap-local.sh` |
| `JpaAdopterApiSurfaceTest` (a regex import scan in persistence-jpa) | `ca.api-surface` `adopterBaseline` |
## Testing a convention
+4 -12
View File
@@ -35,14 +35,6 @@ dependencies {
gradlePlugin {
plugins {
publicPathSnapshot {
id = 'ca.public-path-snapshot'
implementationClass = 'dev.caskeleton.buildlogic.publicpath.PublicPathSnapshotPlugin'
}
archiveHygiene {
id = 'ca.archive-hygiene'
implementationClass = 'dev.caskeleton.buildlogic.archive.ArchiveHygienePlugin'
}
auxiliarySourceSet {
id = 'ca.auxiliary-source-set'
implementationClass = 'dev.caskeleton.buildlogic.auxiliary.AuxiliarySourceSetPlugin'
@@ -63,10 +55,6 @@ gradlePlugin {
id = 'ca.java-conventions'
implementationClass = 'dev.caskeleton.buildlogic.java.JavaConventionsPlugin'
}
developerBootstrap {
id = 'ca.developer-bootstrap'
implementationClass = 'dev.caskeleton.buildlogic.bootstrap.DeveloperBootstrapPlugin'
}
bootRunDotenv {
id = 'ca.bootrun-dotenv'
implementationClass = 'dev.caskeleton.buildlogic.bootstrap.BootRunDotenvPlugin'
@@ -107,6 +95,10 @@ gradlePlugin {
id = 'ca.platform-module'
implementationClass = 'dev.caskeleton.buildlogic.convention.PlatformModuleConventionPlugin'
}
configContract {
id = 'ca.config-contract'
implementationClass = 'dev.caskeleton.buildlogic.config.ConfigContractPlugin'
}
grpcPlatformModuleConvention {
id = 'ca.grpc-platform-module'
implementationClass = 'dev.caskeleton.buildlogic.convention.GrpcPlatformModuleConventionPlugin'
@@ -12,6 +12,8 @@ public class ApiSurfaceExtension {
private List<String> rationale = new ArrayList<>();
private String sourceRoot = "src/main/java";
private List<String> additionalSourceRoots = new ArrayList<>();
private File adopterBaseline;
private Object adopterSources;
public String getLabel() { return label; }
public void setLabel(String label) { this.label = label; }
@@ -30,4 +32,14 @@ public class ApiSurfaceExtension {
this.additionalSourceRoots =
additionalSourceRoots == null ? new ArrayList<>() : new ArrayList<>(additionalSourceRoots);
}
/**
* The reviewed subset of the surface other leaves' production code may import. Optional: without
* it, every public type is fair game to an adopter, which is what the surface alone says.
*/
public File getAdopterBaseline() { return adopterBaseline; }
public void setAdopterBaseline(File adopterBaseline) { this.adopterBaseline = adopterBaseline; }
/** The adopter sources whose imports are held to {@link #getAdopterBaseline()}; any {@code files()} notation. */
public Object getAdopterSources() { return adopterSources; }
public void setAdopterSources(Object adopterSources) { this.adopterSources = adopterSources; }
}
@@ -87,6 +87,55 @@ public final class ApiSurfacePolicy {
+ approvalProperty);
}
/**
* Holds other leaves' imports of this surface to the reviewed adopter subset.
*
* <p>The surface says what is public; the adopter baseline says which of those public types other
* leaves' production code may depend on. An import of a surface type the adopter baseline does not
* list fails, and so does an adopter entry the surface no longer has.
*/
public static void verifyAdopters(
String verifyTaskName, String rendered, File adopterBaseline, List<String> adopterImports) {
if (!adopterBaseline.isFile()) {
throw new IllegalStateException(
verifyTaskName + ": missing committed adopter baseline " + adopterBaseline);
}
java.util.Set<String> surface = new java.util.HashSet<>(surfaceLines(rendered));
java.util.Set<String> allowed = new java.util.TreeSet<>();
for (String line : read(adopterBaseline).lines().toList()) {
if (!line.isBlank() && !line.startsWith("#")) {
allowed.add(line.trim());
}
}
List<String> stale = allowed.stream().filter(type -> !surface.contains(type)).toList();
List<String> unreviewed =
adopterImports.stream()
.filter(entry -> {
String type = entry.substring(entry.indexOf(": ") + 2);
return surface.contains(type) && !allowed.contains(type);
})
.toList();
if (stale.isEmpty() && unreviewed.isEmpty()) {
return;
}
throw new IllegalStateException(
verifyTaskName
+ ": the adopter surface ("
+ adopterBaseline.getName()
+ ") does not match what other leaves import.\n"
+ (unreviewed.isEmpty()
? ""
: " imported but not in the adopter baseline:\n "
+ String.join("\n ", unreviewed)
+ "\n")
+ (stale.isEmpty()
? ""
: " in the adopter baseline but not in the public surface:\n "
+ String.join("\n ", stale)
+ "\n")
+ "Add a reviewed type to the adopter baseline, or stop importing it.");
}
public static void requireNoUnapprovedGrowth(
String updateTaskName,
String owningProjectPath,
@@ -2,6 +2,7 @@ package dev.caskeleton.buildlogic;
import com.sun.source.tree.ClassTree;
import com.sun.source.tree.CompilationUnitTree;
import com.sun.source.tree.ImportTree;
import com.sun.source.tree.Tree;
import com.sun.source.util.JavacTask;
import java.io.File;
@@ -44,6 +45,47 @@ public final class JavaPublicTypes {
}
}
}
Set<String> types = new TreeSet<>();
for (CompilationUnitTree unit : parse(sources, "The public API surface")) {
if (unit.getPackageName() == null) {
continue;
}
String packageName = unit.getPackageName().toString();
for (Tree declaration : unit.getTypeDecls()) {
if (declaration instanceof ClassTree type
&& type.getModifiers().getFlags().contains(Modifier.PUBLIC)) {
types.add(packageName + "." + type.getSimpleName());
}
}
}
return List.copyOf(types);
}
/**
* Every single-type, non-static import in {@code sources}, as {@code "<file name>: <import>"}.
* Wildcard and static imports are not listed; a leaf whose adopters need them is declaring a
* surface this check does not model.
*/
public static List<String> imports(Collection<File> sources) {
List<File> files =
sources == null
? List.of()
: sources.stream().filter(file -> file.getName().endsWith(".java")).toList();
Set<String> imports = new TreeSet<>();
for (CompilationUnitTree unit : parse(files, "The adopter sources")) {
String file = new File(unit.getSourceFile().toUri()).getName();
for (ImportTree declaration : unit.getImports()) {
String name = declaration.getQualifiedIdentifier().toString();
if (!declaration.isStatic() && !name.endsWith(".*")) {
imports.add(file + ": " + name);
}
}
}
return List.copyOf(imports);
}
private static List<CompilationUnitTree> parse(Collection<File> files, String subject) {
List<File> sources = new ArrayList<>(files);
if (sources.isEmpty()) {
return List.of();
}
@@ -58,7 +100,6 @@ public final class JavaPublicTypes {
}
DiagnosticCollector<JavaFileObject> diagnostics = new DiagnosticCollector<>();
Set<String> types = new TreeSet<>();
try (StandardJavaFileManager fileManager =
compiler.getStandardFileManager(diagnostics, null, StandardCharsets.UTF_8)) {
JavacTask task =
@@ -70,7 +111,8 @@ public final class JavaPublicTypes {
List.of("-proc:none"),
null,
fileManager.getJavaFileObjectsFromFiles(sources));
Iterable<? extends CompilationUnitTree> units = task.parse();
List<CompilationUnitTree> units = new ArrayList<>();
task.parse().forEach(units::add);
List<Diagnostic<? extends JavaFileObject>> errors =
diagnostics.getDiagnostics().stream()
.filter(diagnostic -> diagnostic.getKind() == Diagnostic.Kind.ERROR)
@@ -79,27 +121,11 @@ public final class JavaPublicTypes {
String first =
errors.stream().limit(5).map(Object::toString).reduce((a, b) -> a + "\n " + b).orElse("");
String more = errors.size() > 5 ? "\n (" + (errors.size() - 5) + " more)" : "";
throw new IllegalStateException(
"The public API surface could not be parsed:\n " + first + more);
}
for (CompilationUnitTree unit : units) {
if (unit.getPackageName() == null) {
continue;
}
String packageName = unit.getPackageName().toString();
for (Tree declaration : unit.getTypeDecls()) {
if (!(declaration instanceof ClassTree type)) {
continue;
}
if (type.getModifiers().getFlags().contains(Modifier.PUBLIC)) {
types.add(packageName + "." + type.getSimpleName());
}
}
throw new IllegalStateException(subject + " could not be parsed:\n " + first + more);
}
return units;
} catch (IOException exception) {
throw new IllegalStateException("Could not parse Java source files", exception);
}
return List.copyOf(types);
}
}
@@ -67,6 +67,12 @@ public final class ApiSurfacePlugin implements Plugin<Project> {
task.getUpdateTaskName().set(updateTaskName);
task.getApprovalProperty().set(approvalProperty);
task.getUpdateApproved().set(approved);
if (extension.getAdopterBaseline() != null) {
task.getAdopterBaseline().fileValue(extension.getAdopterBaseline());
if (extension.getAdopterSources() != null) {
task.getAdopterSources().from(extension.getAdopterSources());
}
}
});
project
@@ -93,11 +99,12 @@ public final class ApiSurfacePlugin implements Plugin<Project> {
task.getCeilingRaiseApproved().set(ceilingApproved);
});
// Main-branch stage (mainCheck), not the pull-request `check`; the verify task runs on its own
// for anyone changing a public type.
// The leaf's `check`, so a pull request that changes a public type fails there (owner
// decision 20, 2026-09-25). It used to run only in `mainCheck`, which reported the change
// after it had merged.
project
.getTasks()
.matching(task -> task.getName().equals("mainCheck"))
.matching(task -> task.getName().equals("check"))
.configureEach(task -> task.dependsOn(verify));
});
}
@@ -1,6 +1,7 @@
package dev.caskeleton.buildlogic.apisurface;
import dev.caskeleton.buildlogic.ApiSurfacePolicy;
import dev.caskeleton.buildlogic.JavaPublicTypes;
import java.io.File;
import java.util.List;
import org.gradle.api.DefaultTask;
@@ -10,8 +11,12 @@ import org.gradle.api.file.RegularFileProperty;
import org.gradle.api.provider.ListProperty;
import org.gradle.api.provider.Property;
import org.gradle.api.tasks.Input;
import org.gradle.api.tasks.InputFile;
import org.gradle.api.tasks.InputFiles;
import org.gradle.api.tasks.Internal;
import org.gradle.api.tasks.Optional;
import org.gradle.api.tasks.PathSensitive;
import org.gradle.api.tasks.PathSensitivity;
import org.gradle.api.tasks.TaskAction;
import org.gradle.work.DisableCachingByDefault;
@@ -36,6 +41,15 @@ public abstract class VerifyApiSurfaceTask extends DefaultTask {
@Input public abstract Property<String> getApprovalProperty();
@Input public abstract Property<Boolean> getUpdateApproved();
/** Other leaves' production sources, held to the adopter baseline when one is declared. */
@InputFiles
@PathSensitive(PathSensitivity.RELATIVE)
public abstract ConfigurableFileCollection getAdopterSources();
@Optional
@InputFile
public abstract RegularFileProperty getAdopterBaseline();
@TaskAction
public void verifySurface() {
if (getUpdateApproved().get()) {
@@ -63,6 +77,13 @@ public abstract class VerifyApiSurfaceTask extends DefaultTask {
getApprovalProperty().get(),
getBaseline().get().getAsFile(),
rendered);
if (getAdopterBaseline().isPresent()) {
ApiSurfacePolicy.verifyAdopters(
getName(),
rendered,
getAdopterBaseline().get().getAsFile(),
JavaPublicTypes.imports(getAdopterSources().getFiles()));
}
} catch (IllegalStateException invalidSurface) {
throw new GradleException(invalidSurface.getMessage(), invalidSurface);
}
@@ -1,65 +0,0 @@
package dev.caskeleton.buildlogic.archive;
import java.util.ArrayList;
import java.util.List;
import org.gradle.api.Plugin;
import org.gradle.api.Project;
import org.gradle.api.tasks.TaskProvider;
import org.gradle.api.tasks.bundling.Jar;
public final class ArchiveHygienePlugin implements Plugin<Project> {
@Override
public void apply(Project project) {
TaskProvider<CleanStaleTraceableJarsTask> cleanTask =
project
.getTasks()
.register(
"cleanStaleTraceableJars",
CleanStaleTraceableJarsTask.class,
task -> {
task.setGroup("build");
task.setDescription(
"Explicitly deletes older git-revision JARs from leaf build/libs directories.");
});
TaskProvider<VerifyNoStaleTraceableJarsTask> verifyTask =
project
.getTasks()
.register(
"verifyNoStaleTraceableJars",
VerifyNoStaleTraceableJarsTask.class,
task -> {
task.setGroup("verification");
task.setDescription(
"Fails without mutation when leaf build/libs directories retain old traceable JARs.");
});
project
.getGradle()
.projectsEvaluated(
ignored -> {
List<ArchiveTarget> targets = collectTargets(project);
cleanTask.configure(task -> task.setTargets(targets));
verifyTask.configure(task -> task.setTargets(targets));
});
}
private static List<ArchiveTarget> collectTargets(Project rootProject) {
List<ArchiveTarget> targets = new ArrayList<>();
for (Project subproject : rootProject.getSubprojects()) {
subproject
.getTasks()
.withType(Jar.class)
.forEach(
jar ->
targets.add(
new ArchiveTarget(
jar.getPath(),
jar.getDestinationDirectory().get().getAsFile(),
jar.getArchiveBaseName().get(),
jar.getArchiveClassifier().getOrElse(""),
jar.getArchiveFileName().get())));
}
return List.copyOf(targets);
}
}
@@ -1,39 +0,0 @@
package dev.caskeleton.buildlogic.archive;
import java.io.File;
import java.util.Arrays;
import java.util.Comparator;
import java.util.List;
import java.util.regex.Pattern;
public final class ArchiveHygienePolicy {
private ArchiveHygienePolicy() {}
public static List<File> staleArchives(ArchiveTarget target) {
File outputDirectory = target.outputDirectory();
if (!outputDirectory.isDirectory()) {
return List.of();
}
String classifierPart =
target.classifier().isBlank() ? "" : "-" + Pattern.quote(target.classifier());
Pattern traceableArchive =
Pattern.compile(
"^"
+ Pattern.quote(target.baseName())
+ "-\\d+\\.\\d+\\.\\d+\\+[0-9a-f]{7,40}"
+ classifierPart
+ "\\.jar$");
File[] matches =
outputDirectory.listFiles(
file ->
file.isFile()
&& traceableArchive.matcher(file.getName()).matches()
&& !file.getName().equals(target.currentArchiveName()));
if (matches == null || matches.length == 0) {
return List.of();
}
return Arrays.stream(matches).sorted(Comparator.comparing(File::getName)).toList();
}
}
@@ -1,22 +0,0 @@
package dev.caskeleton.buildlogic.archive;
import java.io.File;
import java.io.Serializable;
import java.util.Objects;
public record ArchiveTarget(
String taskPath,
File outputDirectory,
String baseName,
String classifier,
String currentArchiveName)
implements Serializable {
public ArchiveTarget {
Objects.requireNonNull(taskPath, "taskPath");
Objects.requireNonNull(outputDirectory, "outputDirectory");
Objects.requireNonNull(baseName, "baseName");
classifier = classifier == null ? "" : classifier;
Objects.requireNonNull(currentArchiveName, "currentArchiveName");
}
}
@@ -1,38 +0,0 @@
package dev.caskeleton.buildlogic.archive;
import java.io.File;
import java.util.List;
import org.gradle.api.DefaultTask;
import org.gradle.api.GradleException;
import org.gradle.work.DisableCachingByDefault;
import org.gradle.api.tasks.Internal;
import org.gradle.api.tasks.TaskAction;
@DisableCachingByDefault(because = "Explicit cleanup task mutates existing archives")
public abstract class CleanStaleTraceableJarsTask extends DefaultTask {
private List<ArchiveTarget> targets = List.of();
@Internal
public final List<ArchiveTarget> getTargets() {
return targets;
}
public final void setTargets(List<ArchiveTarget> targets) {
this.targets = List.copyOf(targets);
}
@TaskAction
public void cleanArchives() {
int deleted = 0;
for (ArchiveTarget target : targets) {
for (File stale : ArchiveHygienePolicy.staleArchives(target)) {
if (!stale.delete()) {
throw new GradleException("cleanStaleTraceableJars: failed to delete " + stale);
}
deleted++;
getLogger().lifecycle("cleanStaleTraceableJars: deleted {}", stale);
}
}
getLogger().lifecycle("cleanStaleTraceableJars: deleted {} stale archive(s).", deleted);
}
}
@@ -1,52 +0,0 @@
package dev.caskeleton.buildlogic.archive;
import java.io.File;
import java.util.ArrayList;
import java.util.List;
import org.gradle.api.DefaultTask;
import org.gradle.api.GradleException;
import org.gradle.work.DisableCachingByDefault;
import org.gradle.api.tasks.Internal;
import org.gradle.api.tasks.TaskAction;
@DisableCachingByDefault(because = "Verification task has no outputs")
public abstract class VerifyNoStaleTraceableJarsTask extends DefaultTask {
private List<ArchiveTarget> targets = List.of();
@Internal
public final List<ArchiveTarget> getTargets() {
return targets;
}
public final void setTargets(List<ArchiveTarget> targets) {
this.targets = List.copyOf(targets);
}
@TaskAction
public void verifyArchives() {
List<String> violations = new ArrayList<>();
for (ArchiveTarget target : targets) {
List<String> staleJars =
ArchiveHygienePolicy.staleArchives(target).stream().map(File::getName).toList();
if (!staleJars.isEmpty()) {
violations.add(
target.taskPath()
+ ": stale JAR(s) "
+ staleJars
+ "; current archive is "
+ target.currentArchiveName());
}
}
if (!violations.isEmpty()) {
throw new GradleException(
"verifyNoStaleTraceableJars: "
+ violations.size()
+ " archive task(s) retain old traceable JARs. Run cleanStaleTraceableJars explicitly "
+ "if removal is intended.\n "
+ String.join("\n ", violations));
}
getLogger()
.lifecycle("verifyNoStaleTraceableJars: OK — no stale traceable JARs in build/libs.");
}
}
@@ -1,75 +0,0 @@
package dev.caskeleton.buildlogic.bootstrap;
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.TimeUnit;
import org.gradle.api.DefaultTask;
import org.gradle.api.GradleException;
import org.gradle.api.provider.Property;
import org.gradle.api.tasks.Input;
import org.gradle.api.tasks.TaskAction;
import org.gradle.work.DisableCachingByDefault;
@DisableCachingByDefault(because = "Probes a live local application endpoint")
public abstract class BootstrapSmokeTask extends DefaultTask {
@Input
public abstract Property<String> getEndpoint();
@Input
public abstract Property<Integer> getTimeoutSeconds();
@TaskAction
public void verifyHealth() {
URI endpoint = URI.create(getEndpoint().get());
long deadline =
System.nanoTime() + TimeUnit.SECONDS.toNanos(getTimeoutSeconds().get().longValue());
String lastFailure = "no response";
while (System.nanoTime() < deadline) {
HttpURLConnection connection = null;
try {
connection = (HttpURLConnection) endpoint.toURL().openConnection();
connection.setConnectTimeout(2_000);
connection.setReadTimeout(2_000);
connection.setRequestMethod("GET");
int status = connection.getResponseCode();
byte[] bodyBytes =
status >= 200 && status < 400
? connection.getInputStream().readAllBytes()
: connection.getErrorStream() == null
? new byte[0]
: connection.getErrorStream().readAllBytes();
String body = new String(bodyBytes, StandardCharsets.UTF_8);
if (status == 200 && body.contains("\"status\":\"UP\"")) {
getLogger()
.lifecycle(
"bootstrapSmoke: OK — GET /api/healthcheck returned HTTP 200 and status=UP.");
return;
}
lastFailure = "HTTP " + status + ": " + body;
} catch (IOException exception) {
lastFailure = exception.getMessage();
} finally {
if (connection != null) {
connection.disconnect();
}
}
try {
Thread.sleep(1_000L);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw new GradleException("bootstrapSmoke: interrupted while waiting for healthcheck", interrupted);
}
}
throw new GradleException(
"bootstrapSmoke: /api/healthcheck did not become healthy within "
+ getTimeoutSeconds().get()
+ "s; last result: "
+ lastFailure);
}
}
@@ -1,199 +0,0 @@
package dev.caskeleton.buildlogic.bootstrap;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.util.ArrayList;
import java.util.List;
import org.gradle.api.GradleException;
import org.gradle.api.Plugin;
import org.gradle.api.Project;
import org.gradle.api.tasks.Exec;
import org.gradle.api.tasks.TaskProvider;
public final class DeveloperBootstrapPlugin implements Plugin<Project> {
private static final String GROUP = "developer experience";
/** Selects the compose overlay merged onto docker-compose.yml. */
public static final String PROFILE_PROPERTY = "bootstrapProfile";
private static final String DEFAULT_PROFILE = "local";
@Override
public void apply(Project project) {
if (project != project.getRootProject()) {
throw new GradleException("ca.developer-bootstrap must be applied to the root project.");
}
File repositoryDirectory = project.getProjectDir().getParentFile();
// Which environment this bootstrap brings up. `local` stays the default, so the four-stage
// contract a developer already knows is unchanged when nothing is passed.
//
// A property rather than a `scripts/run <env>` wrapper: the ordered lifecycle — compile, Docker
// preflight, dependency wait, migrate-and-start, health smoke — already lives here, and a shell
// script would either duplicate it or become a second entry point that drifts from it. The only
// thing the environment decides is which overlay merges onto the base compose file.
String profile = String.valueOf(project.findProperty(PROFILE_PROPERTY));
if ("null".equals(profile)) {
profile = DEFAULT_PROFILE;
}
// The overlay is checked when a bootstrap task runs, not here: the Docker image build copies only
// src/ into its context, where no compose file exists, and a check at configuration time would
// stop every task in that build — not only the bootstrap ones.
File overlay = new File(repositoryDirectory, "docker-compose." + profile + ".yml");
File baseComposeFile = new File(repositoryDirectory, "docker-compose.yml");
List<String> composeCommand =
List.of(
"docker",
"compose",
"-f",
baseComposeFile.getAbsolutePath(),
"-f",
overlay.getAbsolutePath());
String bootstrapProfile = profile;
TaskProvider<?> compile =
project
.getTasks()
.register(
"bootstrapCompile",
task -> {
task.setGroup(GROUP);
task.setDescription(
"Stage 1/4: compiles the default application composition and its required upstream projects.");
task.dependsOn(":app-bootstrap:compileTestJava");
});
ByteArrayOutputStream dockerInfoOutput = new ByteArrayOutputStream();
ByteArrayOutputStream dockerInfoError = new ByteArrayOutputStream();
TaskProvider<Exec> dockerPreflight =
project
.getTasks()
.register(
"bootstrapDockerPreflight",
Exec.class,
task -> {
task.setGroup(GROUP);
task.setDescription("Checks that the Docker CLI can reach a running Docker daemon.");
task.dependsOn(compile);
task.doFirst(
ignored -> requireOverlay(overlay, bootstrapProfile, repositoryDirectory));
task.commandLine("docker", "info");
task.setIgnoreExitValue(true);
task.setStandardOutput(dockerInfoOutput);
task.setErrorOutput(dockerInfoError);
task.doLast(
ignored -> {
if (task.getExecutionResult().get().getExitValue() != 0) {
throw new GradleException(
"bootstrap: Docker가 필요합니다. Docker Desktop/daemon을 시작한 뒤 "
+ "`docker info`가 성공하는지 확인하세요.\n"
+ dockerInfoError);
}
});
});
TaskProvider<Exec> dependencies =
project
.getTasks()
.register(
"bootstrapDependencies",
Exec.class,
task -> {
task.setGroup(GROUP);
task.setDescription(
"Stage 2/4: starts the "
+ bootstrapProfile
+ " PostgreSQL dependency and waits for readiness.");
task.dependsOn(dockerPreflight);
task.commandLine(command(composeCommand, "up", "-d", "--wait", "db"));
});
TaskProvider<Exec> migrateAndStart =
project
.getTasks()
.register(
"bootstrapMigrateAndStart",
Exec.class,
task -> {
task.setGroup(GROUP);
task.setDescription(
"Stage 3/4: builds/starts the app; startup Flyway must finish before health is ready.");
task.dependsOn(dependencies);
task.commandLine(
command(composeCommand, "up", "-d", "--build", "--wait", "app"));
});
TaskProvider<BootstrapSmokeTask> smoke =
project
.getTasks()
.register(
"bootstrapSmoke",
BootstrapSmokeTask.class,
task -> {
task.setGroup(GROUP);
task.setDescription(
"Stage 4/4: requires HTTP 200 and status=UP from GET /api/healthcheck.");
task.dependsOn(migrateAndStart);
task.getEndpoint().set("http://localhost:8080/api/healthcheck");
task.getTimeoutSeconds().set(60);
});
project
.getTasks()
.register(
"bootstrap",
task -> {
task.setGroup(GROUP);
task.setDescription(
"Runs the complete four-stage bootstrap contract for the "
+ bootstrapProfile
+ " environment. Select another with -P"
+ PROFILE_PROPERTY
+ "=<name>.");
task.dependsOn(smoke);
});
}
private static void requireOverlay(File overlay, String profile, File repositoryDirectory) {
if (!overlay.isFile()) {
throw new GradleException(
"bootstrap: -P"
+ PROFILE_PROPERTY
+ "="
+ profile
+ " names no overlay; expected "
+ overlay.getName()
+ " beside docker-compose.yml. Available: "
+ availableProfiles(repositoryDirectory));
}
}
/** The overlay names that exist beside the base compose file, for the failure message. */
private static List<String> availableProfiles(File repositoryDirectory) {
File[] files = repositoryDirectory.listFiles();
if (files == null) {
return List.of();
}
List<String> profiles = new ArrayList<>();
for (File file : files) {
String name = file.getName();
// The base file is `docker-compose.yml`, which matches both affixes and names no profile.
int start = "docker-compose.".length();
int end = name.length() - ".yml".length();
if (file.isFile() && name.startsWith("docker-compose.") && name.endsWith(".yml")
&& end > start) {
profiles.add(name.substring(start, end));
}
}
profiles.sort(String::compareTo);
return List.copyOf(profiles);
}
private static List<String> command(List<String> prefix, String... arguments) {
List<String> command = new ArrayList<>(prefix.size() + arguments.length);
command.addAll(prefix);
command.addAll(List.of(arguments));
return List.copyOf(command);
}
}
@@ -1,4 +1,4 @@
package dev.caskeleton.buildtools.config;
package dev.caskeleton.buildlogic.config;
import java.io.File;
import org.gradle.api.Plugin;
@@ -1,4 +1,4 @@
package dev.caskeleton.buildtools.config;
package dev.caskeleton.buildlogic.config;
import java.util.List;
@@ -1,4 +1,4 @@
package dev.caskeleton.buildtools.config;
package dev.caskeleton.buildlogic.config;
import java.io.File;
import java.io.IOException;
@@ -1,4 +1,4 @@
package dev.caskeleton.buildtools.config;
package dev.caskeleton.buildlogic.config;
import java.util.Objects;
import java.util.Optional;
@@ -1,4 +1,4 @@
package dev.caskeleton.buildtools.config;
package dev.caskeleton.buildlogic.config;
import java.io.File;
import java.util.Objects;
@@ -1,4 +1,4 @@
package dev.caskeleton.buildtools.config;
package dev.caskeleton.buildlogic.config;
import java.util.List;
import org.gradle.api.DefaultTask;
@@ -35,7 +35,14 @@ public final class JavaConventionsPlugin implements Plugin<Project> {
project.setGroup("dev.caskeleton");
ReleaseProvenanceExtension provenance =
project.getRootProject().getExtensions().findByType(ReleaseProvenanceExtension.class);
project.setVersion(provenance == null ? "0.0.1-SNAPSHOT" : provenance.getTraceableVersion());
// The release version alone, never the revision: a revision in the version put a new jar name in
// every leaf's build/libs on every commit, which is what the deleted archive-hygiene plugin
// existed to clean up (review BUILD-O3-5). The revision stays in each jar's manifest
// (Build-Revision) and in app-bootstrap's build-info.properties.
project.setVersion(
provenance == null
? "0.0.1-SNAPSHOT"
: provenance.getReleaseVersion() + (provenance.isComplete() ? "" : "-SNAPSHOT"));
String buildRevision = provenance == null ? "unknown" : provenance.getSourceRevision();
JavaPluginExtension javaExtension = project.getExtensions().getByType(JavaPluginExtension.class);
@@ -65,6 +72,18 @@ public final class JavaConventionsPlugin implements Plugin<Project> {
"Implementation-Version", project.getVersion().toString(),
"Build-Revision", buildRevision)));
// Both attributes change on every commit, and every test and SpotBugs task has this jar on its
// runtime classpath: without the normalization a CI build never reuses a cached test result
// (review O-4c). They describe the build, not the classes, so a runtime classpath ignores them.
project
.getNormalization()
.getRuntimeClasspath()
.metaInf(
metaInf -> {
metaInf.ignoreAttribute("Implementation-Version");
metaInf.ignoreAttribute("Build-Revision");
});
project
.getTasks()
.withType(JavaCompile.class)
@@ -1,9 +0,0 @@
package dev.caskeleton.buildlogic.publicpath;
import java.util.List;
public record PublicPathSnapshot(List<String> publicPaths, String canonicalText) {
public PublicPathSnapshot {
publicPaths = List.copyOf(publicPaths);
}
}
@@ -1,56 +0,0 @@
package dev.caskeleton.buildlogic.publicpath;
import org.gradle.api.Plugin;
import org.gradle.api.Project;
import org.gradle.api.provider.Provider;
public final class PublicPathSnapshotPlugin implements Plugin<Project> {
static final String APPROVAL_PROPERTY = "approvePublicPathChange";
@Override
public void apply(Project project) {
var source =
project
.getLayout()
.getProjectDirectory()
.file("app-bootstrap/src/main/resources/config/security.yml");
var snapshot =
project
.getLayout()
.getProjectDirectory()
.file("../docs/security/public-paths-snapshot.txt");
Provider<Boolean> approvalRequested =
project.getProviders().gradleProperty(APPROVAL_PROPERTY).map(ignored -> true).orElse(false);
project
.getTasks()
.register(
"verifyPublicPathSnapshot",
VerifyPublicPathSnapshotTask.class,
task -> {
task.setGroup("verification");
task.setDescription(
"Fails without mutation when the committed deny-by-default public path baseline drifts.");
task.getSecurityConfigFile().set(source);
task.getSnapshotFile().set(snapshot);
task.getApprovalRequested().convention(approvalRequested);
task.getTrackedFiles().from(source, snapshot);
});
project
.getTasks()
.register(
"updatePublicPathSnapshot",
UpdatePublicPathSnapshotTask.class,
task -> {
task.setGroup("build setup");
task.setDescription(
"Explicitly updates the committed public path baseline after security review.");
task.getSecurityConfigFile().set(source);
task.getSnapshotFile().set(snapshot);
task.getApproved().convention(approvalRequested);
task.getTrackedFiles().from(source);
task.getOutputs().upToDateWhen(ignored -> false);
});
}
}
@@ -1,89 +0,0 @@
package dev.caskeleton.buildlogic.publicpath;
import java.io.File;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
public final class PublicPathSnapshotRenderer {
private static final Pattern BINDING_PATTERN =
Pattern.compile("^\\s*public-paths:\\s*(\\S.*?)\\s*$");
private static final Pattern DEFAULTED_PLACEHOLDER =
Pattern.compile("\\$\\{[A-Za-z0-9_.]+:([^{}]*)}");
private static final int MAX_PLACEHOLDER_DEPTH = 16;
private static final String HEADER =
"# feature-security-operational-baseline D5 — deny-by-default public path snapshot.\n"
+ "# SSOT: ca-skeleton.security.public-paths default in "
+ "app-bootstrap/src/main/resources/config/security.yml\n"
+ "# -> SecurityConfig permitAll(); anyRequest authenticated. An operator's own "
+ "SECURITY_PUBLIC_PATHS\n"
+ "# overrides it at run time and is outside this snapshot.\n"
+ "# Update only after review with: ./gradlew updatePublicPathSnapshot "
+ "-PapprovePublicPathChange\n";
private PublicPathSnapshotRenderer() {}
public static PublicPathSnapshot render(File securityConfigFile) {
if (!securityConfigFile.isFile()) {
throw new IllegalStateException(
"missing public-path security configuration " + securityConfigFile);
}
List<String> bindings = new ArrayList<>();
for (String line : readLines(securityConfigFile)) {
Matcher matcher = BINDING_PATTERN.matcher(line);
if (matcher.matches()) {
bindings.add(matcher.group(1));
}
}
if (bindings.size() != 1) {
throw new IllegalStateException(
"expected exactly one 'public-paths:' binding in "
+ securityConfigFile
+ ", found "
+ bindings.size()
+ " — the snapshot cannot say which surface it pins");
}
String raw = bindings.getFirst();
for (int guard = 0; guard < MAX_PLACEHOLDER_DEPTH; guard++) {
Matcher matcher = DEFAULTED_PLACEHOLDER.matcher(raw);
if (!matcher.find()) {
break;
}
raw = raw.substring(0, matcher.start()) + matcher.group(1) + raw.substring(matcher.end());
}
if (raw.contains("${")) {
throw new IllegalStateException(
"'public-paths' in "
+ securityConfigFile
+ " resolves to '"
+ raw
+ "', which still holds a placeholder with no default — the deployed public path "
+ "surface is not determined by the repository and cannot be snapshotted");
}
List<String> publicPaths =
Pattern.compile(",")
.splitAsStream(raw)
.map(String::trim)
.filter(value -> !value.isEmpty())
.sorted()
.toList();
String canonical = HEADER + (publicPaths.isEmpty() ? "" : String.join("\n", publicPaths) + "\n");
return new PublicPathSnapshot(publicPaths, canonical);
}
private static List<String> readLines(File file) {
try {
return Files.readAllLines(file.toPath(), StandardCharsets.UTF_8);
} catch (IOException exception) {
throw new UncheckedIOException("failed to read " + file, exception);
}
}
}
@@ -1,60 +0,0 @@
package dev.caskeleton.buildlogic.publicpath;
import java.io.File;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import org.gradle.api.DefaultTask;
import org.gradle.api.GradleException;
import org.gradle.api.file.ConfigurableFileCollection;
import org.gradle.api.file.RegularFileProperty;
import org.gradle.api.provider.Property;
import org.gradle.api.tasks.Input;
import org.gradle.api.tasks.InputFiles;
import org.gradle.api.tasks.Internal;
import org.gradle.api.tasks.OutputFile;
import org.gradle.api.tasks.TaskAction;
public abstract class UpdatePublicPathSnapshotTask extends DefaultTask {
@Internal
public abstract RegularFileProperty getSecurityConfigFile();
@OutputFile
public abstract RegularFileProperty getSnapshotFile();
@Input
public abstract Property<Boolean> getApproved();
@InputFiles
public abstract ConfigurableFileCollection getTrackedFiles();
@TaskAction
public void updateSnapshot() {
if (!getApproved().get()) {
throw new GradleException(
"updatePublicPathSnapshot requires -PapprovePublicPathChange");
}
File source = getSecurityConfigFile().get().getAsFile();
PublicPathSnapshot rendered;
try {
rendered = PublicPathSnapshotRenderer.render(source);
} catch (IllegalStateException invalidSource) {
throw new GradleException("updatePublicPathSnapshot: " + invalidSource.getMessage(), invalidSource);
}
File snapshot = getSnapshotFile().get().getAsFile();
File parent = snapshot.getParentFile();
if (!parent.isDirectory() && !parent.mkdirs()) {
throw new GradleException(
"updatePublicPathSnapshot: failed to create " + parent);
}
try {
Files.writeString(snapshot.toPath(), rendered.canonicalText(), StandardCharsets.UTF_8);
} catch (IOException exception) {
throw new UncheckedIOException("failed to write " + snapshot, exception);
}
getLogger().lifecycle("updatePublicPathSnapshot: wrote reviewed baseline {}", snapshot);
}
}
@@ -1,74 +0,0 @@
package dev.caskeleton.buildlogic.publicpath;
import java.io.File;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import org.gradle.api.DefaultTask;
import org.gradle.api.GradleException;
import org.gradle.api.file.ConfigurableFileCollection;
import org.gradle.api.file.RegularFileProperty;
import org.gradle.api.provider.Property;
import org.gradle.api.tasks.Input;
import org.gradle.api.tasks.InputFiles;
import org.gradle.api.tasks.Internal;
import org.gradle.api.tasks.TaskAction;
public abstract class VerifyPublicPathSnapshotTask extends DefaultTask {
@Internal
public abstract RegularFileProperty getSecurityConfigFile();
@Internal
public abstract RegularFileProperty getSnapshotFile();
@Input
public abstract Property<Boolean> getApprovalRequested();
@InputFiles
public abstract ConfigurableFileCollection getTrackedFiles();
@TaskAction
public void verifySnapshot() {
if (getApprovalRequested().get()) {
throw new GradleException(
"verifyPublicPathSnapshot is read-only; use updatePublicPathSnapshot "
+ "-PapprovePublicPathChange for an intentional update.");
}
File source = getSecurityConfigFile().get().getAsFile();
File snapshot = getSnapshotFile().get().getAsFile();
PublicPathSnapshot rendered;
try {
rendered = PublicPathSnapshotRenderer.render(source);
} catch (IllegalStateException invalidSource) {
throw new GradleException("verifyPublicPathSnapshot: " + invalidSource.getMessage(), invalidSource);
}
if (!snapshot.isFile()) {
throw new GradleException(
"verifyPublicPathSnapshot: missing committed baseline " + snapshot);
}
String existing = read(snapshot);
if (!existing.equals(rendered.canonicalText())) {
throw new GradleException(
"verifyPublicPathSnapshot: the deny-by-default public path surface changed.\n"
+ " expected (snapshot):\n"
+ existing
+ "\n"
+ " actual (security.yml public-paths default):\n"
+ rendered.canonicalText()
+ "\nA protected endpoint may now be public. Review the change, then run:\n"
+ " ./gradlew updatePublicPathSnapshot -PapprovePublicPathChange");
}
getLogger().lifecycle("verifyPublicPathSnapshot: OK — committed public paths are unchanged.");
}
private static String read(File file) {
try {
return Files.readString(file.toPath(), StandardCharsets.UTF_8);
} catch (IOException exception) {
throw new UncheckedIOException("failed to read " + file, exception);
}
}
}
@@ -59,6 +59,14 @@ public final class RedisTopologyLanePlugin implements Plugin<Project> {
"redisTopologyTest",
lane -> {
lane.integration();
if ("unset".equals(declaredMode)) {
// The lane needs a running topology from infra/redis-sdk and its coordinates; without
// them it can only fail, so the repository's integrationCheck leaves it out and says
// so rather than failing on an input it was never given (review NEW-16).
lane.explicitOnly(
"it needs -Predis.topology.mode=<standalone|sentinel|cluster|tls> and the topology"
+ " coordinates from infra/redis-sdk (redis-sdk-topology.yml passes them)");
}
lane.setTag("redis-topology & lane-" + declaredMode);
lane.setDescription(
"Runs this leaf's Redis contracts against a real topology declared in infra/redis-sdk.");
@@ -67,6 +67,32 @@ public final class StrictTestLanePlugin implements Plugin<Project> {
project.afterEvaluate(
ignored -> lanes.forEach(lane -> validateLane(project, lane)));
lanes.all(
lane ->
project.afterEvaluate(
ignored -> {
if (!lane.isMainStage()) {
return;
}
String tag = lane.getTag();
if (tag == null || tag.isBlank()) {
throw new GradleException(
"strict test lane '"
+ lane.getName()
+ "' in "
+ ownerPath
+ " is a main-stage lane without a tag; the tag is what keeps its tests out of `test`.");
}
project
.getTasks()
.named("test", Test.class)
.configure(test -> test.useJUnitPlatform(options -> options.excludeTags(tag)));
project
.getTasks()
.matching(task -> task.getName().equals("mainCheck"))
.configureEach(task -> task.dependsOn(lane.getName()));
}));
registerAggregate(
project,
extension,
@@ -122,9 +148,30 @@ public final class StrictTestLanePlugin implements Plugin<Project> {
project.provider(
() ->
extension.getLanes().stream()
.filter(lane -> lane.getExplicitOnlyReason() == null)
.filter(selection)
.map(lane -> project.getTasks().named(lane.getName()))
.toList()));
// An explicit-only lane is left out, and the aggregate says so when it runs, so a
// green aggregate is never read as covering it.
var leftOut =
project.provider(
() ->
extension.getLanes().stream()
.filter(lane -> lane.getExplicitOnlyReason() != null)
.filter(selection)
.map(
lane ->
"strict test lane '"
+ lane.getName()
+ "' in "
+ project.getPath()
+ " runs only when named: "
+ lane.getExplicitOnlyReason()
+ ".")
.toList());
task.doLast(
running -> leftOut.get().forEach(note -> running.getLogger().lifecycle(note)));
});
}
@@ -18,6 +18,8 @@ public class StrictTestLaneSpec implements Named {
private String sourceSet = "test";
private String maxHeapSize;
private boolean rejectSkipped;
private boolean mainStage;
private String explicitOnlyReason;
private TestLaneCategory category = TestLaneCategory.TEST;
private final List<String> requiredTests = new ArrayList<>();
private final List<String> jvmArgs = new ArrayList<>();
@@ -84,6 +86,33 @@ public class StrictTestLaneSpec implements Named {
this.rejectSkipped = rejectSkipped;
}
public boolean isMainStage() {
return mainStage;
}
/**
* Runs this lane in the leaf's {@code mainCheck} instead of its {@code test}: the lane's tag is
* excluded from {@code test}. For checks that compare a leaf with documents or registries, which
* are not worth a pull request's wait (review 2026-09-24 BUILD-계획-B4-27).
*/
public void mainStage() {
mainStage = true;
}
public String getExplicitOnlyReason() {
return explicitOnlyReason;
}
/**
* Keeps this lane out of every aggregate ({@code strictTestLaneCheck}, {@code
* integrationTestLaneCheck}, ...): it runs only when named. For a lane that cannot pass without
* an input the aggregate's caller does not have — protected credentials, an external topology —
* so that the aggregate states the gap instead of failing on it (review NEW-16).
*/
public void explicitOnly(String reason) {
explicitOnlyReason = Objects.requireNonNull(reason, "reason");
}
public TestLaneCategory getCategory() {
return category;
}
@@ -1,265 +0,0 @@
package dev.caskeleton.bootstrap.contract;
import static java.nio.charset.StandardCharsets.UTF_8;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import org.gradle.testkit.runner.BuildResult;
import org.gradle.testkit.runner.GradleRunner;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
final class BuildVerificationPurityContractTest {
/**
* What the renderer produces for the fixture's {@code security.yml}.
*
* <p>These five tests were red on main. The snapshot's input moved from {@code src/.env} to the
* committed {@code app-bootstrap/src/main/resources/config/security.yml} — because {@code
* src/.env*} is gitignored, so the old gate took its expected value from a file no CI checkout
* has — but the fixture below kept writing a {@code .env}, and this constant kept the header and
* the paths that file used to produce. The script was right and its test was describing the
* previous contract.
*/
private static final String CANONICAL_PUBLIC_PATH_SNAPSHOT =
"""
# feature-security-operational-baseline D5 — deny-by-default public path snapshot.
# SSOT: ca-skeleton.security.public-paths default in app-bootstrap/src/main/resources/config/security.yml
# -> SecurityConfig permitAll(); anyRequest authenticated. An operator's own SECURITY_PUBLIC_PATHS
# overrides it at run time and is outside this snapshot.
# Update only after review with: ./gradlew updatePublicPathSnapshot -PapprovePublicPathChange
/v1/healthcheck
""";
@Test
void jarTaskLeavesStaleTraceableArchivesUntouched(@TempDir Path temporaryDirectory)
throws IOException {
ArchiveFixture fixture = archiveFixture(temporaryDirectory);
run(fixture.projectDirectory(), ":family:module:jar");
assertThat(fixture.staleArchive()).exists().hasContent("stale");
assertThat(fixture.currentArchive()).exists();
assertThat(fixture.nonmatchingArchive()).exists().hasContent("local");
}
@Test
void staleArchiveVerificationFailsWithoutDeleting(@TempDir Path temporaryDirectory)
throws IOException {
ArchiveFixture fixture = archiveFixture(temporaryDirectory);
BuildResult result =
runAndFail(fixture.projectDirectory(), ":family:module:jar", "verifyNoStaleTraceableJars");
assertThat(result.getOutput())
.contains("verifyNoStaleTraceableJars")
.contains(":family:module:jar")
.contains(fixture.staleArchive().getFileName().toString());
assertThat(fixture.staleArchive()).exists().hasContent("stale");
assertThat(fixture.currentArchive()).exists();
assertThat(fixture.nonmatchingArchive()).exists().hasContent("local");
}
@Test
void explicitStaleArchiveCleanupDeletesOnlyStaleArchive(@TempDir Path temporaryDirectory)
throws IOException {
ArchiveFixture fixture = archiveFixture(temporaryDirectory);
BuildResult result =
run(fixture.projectDirectory(), ":family:module:jar", "cleanStaleTraceableJars");
assertThat(result.getOutput()).contains("deleted 1 stale archive(s)");
assertThat(fixture.staleArchive()).doesNotExist();
assertThat(fixture.currentArchive()).exists();
assertThat(fixture.nonmatchingArchive()).exists().hasContent("local");
}
@Test
void missingPublicPathConfigurationFailsWithoutCreatingSnapshot(@TempDir Path temporaryDirectory)
throws IOException {
PublicPathFixture fixture = publicPathFixture(temporaryDirectory);
Files.delete(fixture.securityConfiguration());
BuildResult result = runAndFail(fixture.projectDirectory(), "verifyPublicPathSnapshot");
assertThat(result.getOutput()).contains("missing public-path security configuration");
assertThat(fixture.snapshot()).doesNotExist();
}
@Test
void missingPublicPathSnapshotFailsWithoutCreatingIt(@TempDir Path temporaryDirectory)
throws IOException {
PublicPathFixture fixture = publicPathFixture(temporaryDirectory);
BuildResult result = runAndFail(fixture.projectDirectory(), "verifyPublicPathSnapshot");
assertThat(result.getOutput()).contains("missing committed baseline");
assertThat(fixture.snapshot()).doesNotExist();
}
@Test
void driftedPublicPathSnapshotFailsWithoutChangingBytes(@TempDir Path temporaryDirectory)
throws IOException {
PublicPathFixture fixture = publicPathFixture(temporaryDirectory);
Files.createDirectories(fixture.snapshot().getParent());
Files.writeString(fixture.snapshot(), "reviewed-old-baseline\n", UTF_8);
byte[] before = Files.readAllBytes(fixture.snapshot());
BuildResult result = runAndFail(fixture.projectDirectory(), "verifyPublicPathSnapshot");
assertThat(result.getOutput()).contains("public path surface changed");
assertThat(Files.readAllBytes(fixture.snapshot())).containsExactly(before);
}
@Test
void verifierRejectsUpdateApprovalWithoutChangingSnapshot(@TempDir Path temporaryDirectory)
throws IOException {
PublicPathFixture fixture = publicPathFixture(temporaryDirectory);
Files.createDirectories(fixture.snapshot().getParent());
Files.writeString(fixture.snapshot(), "reviewed-old-baseline\n", UTF_8);
byte[] before = Files.readAllBytes(fixture.snapshot());
BuildResult result =
runAndFail(
fixture.projectDirectory(), "verifyPublicPathSnapshot", "-PapprovePublicPathChange");
assertThat(result.getOutput()).contains("updatePublicPathSnapshot");
assertThat(Files.readAllBytes(fixture.snapshot())).containsExactly(before);
}
@Test
void updaterRequiresExplicitApproval(@TempDir Path temporaryDirectory) throws IOException {
PublicPathFixture fixture = publicPathFixture(temporaryDirectory);
BuildResult result = runAndFail(fixture.projectDirectory(), "updatePublicPathSnapshot");
assertThat(result.getOutput()).contains("requires -PapprovePublicPathChange");
assertThat(fixture.snapshot()).doesNotExist();
}
@Test
void approvedUpdaterWritesCanonicalSnapshot(@TempDir Path temporaryDirectory) throws IOException {
PublicPathFixture fixture = publicPathFixture(temporaryDirectory);
run(fixture.projectDirectory(), "updatePublicPathSnapshot", "-PapprovePublicPathChange");
assertThat(fixture.snapshot()).hasContent(CANONICAL_PUBLIC_PATH_SNAPSHOT);
run(fixture.projectDirectory(), "verifyPublicPathSnapshot");
assertThat(fixture.snapshot()).hasContent(CANONICAL_PUBLIC_PATH_SNAPSHOT);
}
@Test
void unapprovedUpdaterPreservesExistingSnapshot(@TempDir Path temporaryDirectory)
throws IOException {
PublicPathFixture fixture = publicPathFixture(temporaryDirectory);
Files.createDirectories(fixture.snapshot().getParent());
Files.writeString(fixture.snapshot(), "reviewed-old-baseline\n", UTF_8);
byte[] before = Files.readAllBytes(fixture.snapshot());
BuildResult result = runAndFail(fixture.projectDirectory(), "updatePublicPathSnapshot");
assertThat(result.getOutput()).contains("requires -PapprovePublicPathChange");
assertThat(Files.readAllBytes(fixture.snapshot())).containsExactly(before);
}
@Test
void approvedUpdaterReplacesDriftedSnapshot(@TempDir Path temporaryDirectory) throws IOException {
PublicPathFixture fixture = publicPathFixture(temporaryDirectory);
Files.createDirectories(fixture.snapshot().getParent());
Files.writeString(fixture.snapshot(), "reviewed-old-baseline\n", UTF_8);
run(fixture.projectDirectory(), "updatePublicPathSnapshot", "-PapprovePublicPathChange");
assertThat(fixture.snapshot()).hasContent(CANONICAL_PUBLIC_PATH_SNAPSHOT);
}
private static ArchiveFixture archiveFixture(Path temporaryDirectory) throws IOException {
Path projectDirectory = temporaryDirectory.resolve("archive-fixture");
Path moduleDirectory = projectDirectory.resolve("family/module");
Files.createDirectories(moduleDirectory.resolve("src/main/java/example"));
Files.writeString(
projectDirectory.resolve("settings.gradle"), "include 'family:module'\n", UTF_8);
Files.writeString(
projectDirectory.resolve("build.gradle"),
"""
plugins {
id 'base'
id 'ca.archive-hygiene'
}
allprojects { version = '1.0.0+abcdef1' }
project(':family:module') { apply plugin: 'java' }
""",
UTF_8);
Files.writeString(
moduleDirectory.resolve("src/main/java/example/Sample.java"),
"package example; public final class Sample {}\n",
UTF_8);
Path archiveDirectory = moduleDirectory.resolve("build/libs");
Files.createDirectories(archiveDirectory);
Path staleArchive = archiveDirectory.resolve("module-1.0.0+1234567.jar");
Files.writeString(staleArchive, "stale", UTF_8);
Path currentArchive = archiveDirectory.resolve("module-1.0.0+abcdef1.jar");
Path nonmatchingArchive = archiveDirectory.resolve("module-local.jar");
Files.writeString(nonmatchingArchive, "local", UTF_8);
return new ArchiveFixture(projectDirectory, staleArchive, currentArchive, nonmatchingArchive);
}
private static PublicPathFixture publicPathFixture(Path temporaryDirectory) throws IOException {
Path repositoryDirectory = temporaryDirectory.resolve("public-path-fixture");
Path projectDirectory = repositoryDirectory.resolve("src");
Files.createDirectories(projectDirectory);
Files.writeString(
projectDirectory.resolve("settings.gradle"), "rootProject.name='fixture'\n", UTF_8);
Files.writeString(
projectDirectory.resolve("build.gradle"),
"plugins { id 'ca.public-path-snapshot' }\n",
UTF_8);
// The committed binding default, spelled exactly as the real file spells it — nested Spring
// placeholders and all, because unwinding them to `/v1/healthcheck` is what the renderer does
// and therefore what these tests are about.
Path securityConfig =
projectDirectory.resolve("app-bootstrap/src/main/resources/config/security.yml");
Files.createDirectories(securityConfig.getParent());
Files.writeString(
securityConfig,
"""
ca-skeleton:
security:
public-paths: ${SECURITY_PUBLIC_PATHS:${PRESENTATION_API_BASE_PATH:/v1}/healthcheck}
""",
UTF_8);
return new PublicPathFixture(
projectDirectory,
securityConfig,
repositoryDirectory.resolve("docs/security/public-paths-snapshot.txt"));
}
private static BuildResult run(Path projectDirectory, String... arguments) {
return runner(projectDirectory, arguments).build();
}
private static BuildResult runAndFail(Path projectDirectory, String... arguments) {
return runner(projectDirectory, arguments).buildAndFail();
}
private static GradleRunner runner(Path projectDirectory, String... arguments) {
String[] fullArguments = new String[arguments.length + 2];
fullArguments[0] = "--console=plain";
fullArguments[1] = "--stacktrace";
System.arraycopy(arguments, 0, fullArguments, 2, arguments.length);
return GradleRunner.create()
.withProjectDir(projectDirectory.toFile())
.withPluginClasspath()
.withArguments(fullArguments);
}
private record ArchiveFixture(
Path projectDirectory, Path staleArchive, Path currentArchive, Path nonmatchingArchive) {}
private record PublicPathFixture(
Path projectDirectory, Path securityConfiguration, Path snapshot) {}
}
@@ -98,6 +98,81 @@ class ApiSurfaceConventionTest {
assertFalse(result.getOutput().contains("ApiSurface"), result.getOutput());
}
@Test
void theLeafCheckRunsTheSurfaceVerification() throws Exception {
// given
runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").build();
// when
BuildResult result = runner("check", "--dry-run").build();
// then
assertTrue(result.getOutput().contains(":verifyFixtureApiSurface"), result.getOutput());
}
@Test
void anAdopterImportOutsideTheAdopterBaselineFailsTheVerification() throws Exception {
// given
runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").build();
writeAdopter("package consumer;\nimport app.Visible;\npublic final class Consumer {}\n");
Files.writeString(projectDir.resolve("adopters.txt"), "# reviewed adopter surface\n");
// when
BuildResult result = runner("verifyFixtureApiSurface").buildAndFail();
// then
assertTrue(result.getOutput().contains("Consumer.java: app.Visible"), result.getOutput());
}
@Test
void anAdopterImportTheAdopterBaselineListsPasses() throws Exception {
// given
runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").build();
writeAdopter("package consumer;\nimport app.Visible;\npublic final class Consumer {}\n");
Files.writeString(projectDir.resolve("adopters.txt"), "app.Visible\n");
// when
BuildResult result = runner("verifyFixtureApiSurface").build();
// then
assertTrue(result.getOutput().contains("OK"), result.getOutput());
}
@Test
void anAdopterBaselineEntryTheSurfaceNoLongerHasFailsTheVerification() throws Exception {
// given
runner("updateFixtureApiSurface", "-PapproveFixtureApiSurfaceChange").build();
writeAdopter("package consumer;\npublic final class Consumer {}\n");
Files.writeString(projectDir.resolve("adopters.txt"), "app.Gone\n");
// when
BuildResult result = runner("verifyFixtureApiSurface").buildAndFail();
// then
assertTrue(result.getOutput().contains("app.Gone"), result.getOutput());
}
private void writeAdopter(String source) throws Exception {
Path adopter = projectDir.resolve("adopter/src/consumer");
Files.createDirectories(adopter);
Files.writeString(adopter.resolve("Consumer.java"), source);
Files.writeString(
projectDir.resolve("build.gradle"),
"""
plugins {
id 'java'
id 'ca.api-surface'
}
apiSurface {
label = 'Fixture'
baseline = file('surface.txt')
description = 'The fixture leaf public surface.'
adopterBaseline = file('adopters.txt')
adopterSources = fileTree('adopter/src') { include '**/*.java' }
}
""");
}
private void writeConfiguredBuild(String sourceRoot) throws Exception {
Files.writeString(
projectDir.resolve("build.gradle"),
@@ -1,46 +0,0 @@
package dev.caskeleton.buildlogic.archive;
import static org.assertj.core.api.Assertions.assertThat;
import java.nio.file.Files;
import java.nio.file.Path;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
class ArchiveHygienePolicyTest {
@Test
void findsOnlyOldTraceableArchivesForTheSameJar(@TempDir Path temp) throws Exception {
Files.writeString(temp.resolve("module-1.0.0+1234567.jar"), "stale");
Files.writeString(temp.resolve("module-1.0.0+abcdef1.jar"), "current");
Files.writeString(temp.resolve("module-local.jar"), "local");
Files.writeString(temp.resolve("other-1.0.0+1234567.jar"), "other");
ArchiveTarget target =
new ArchiveTarget(
":module:jar", temp.toFile(), "module", "", "module-1.0.0+abcdef1.jar");
assertThat(ArchiveHygienePolicy.staleArchives(target))
.extracting(file -> file.getName())
.containsExactly("module-1.0.0+1234567.jar");
}
@Test
void classifierIsPartOfTraceableArchiveIdentity(@TempDir Path temp) throws Exception {
Files.writeString(temp.resolve("module-1.0.0+1234567-sources.jar"), "stale");
Files.writeString(temp.resolve("module-1.0.0+abcdef1-sources.jar"), "current");
Files.writeString(temp.resolve("module-1.0.0+1234567.jar"), "main");
ArchiveTarget target =
new ArchiveTarget(
":module:sourcesJar",
temp.toFile(),
"module",
"sources",
"module-1.0.0+abcdef1-sources.jar");
assertThat(ArchiveHygienePolicy.staleArchives(target))
.extracting(file -> file.getName())
.containsExactly("module-1.0.0+1234567-sources.jar");
}
}
@@ -1,143 +0,0 @@
package dev.caskeleton.buildlogic.bootstrap;
import static java.nio.charset.StandardCharsets.UTF_8;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import org.gradle.testkit.runner.BuildResult;
import org.gradle.testkit.runner.GradleRunner;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
final class DeveloperBootstrapPluginFunctionalTest {
@Test
void registersTheFourStageBootstrapLifecycle(@TempDir Path temporaryDirectory) throws IOException {
Path projectDirectory = fixture(temporaryDirectory);
BuildResult result = run(projectDirectory, "tasks", "--group=developer experience");
assertThat(result.getOutput())
.contains("bootstrapCompile")
.contains("bootstrapDockerPreflight")
.contains("bootstrapDependencies")
.contains("bootstrapMigrateAndStart")
.contains("bootstrapSmoke")
.contains("bootstrap - Runs the complete four-stage bootstrap contract for the local")
.contains("-PbootstrapProfile=<name>");
}
@Test
void theEnvironmentIsSelectableAndTheDefaultIsLocal(@TempDir Path temporaryDirectory)
throws IOException {
Path projectDirectory = fixture(temporaryDirectory);
BuildResult devRun =
run(projectDirectory, "tasks", "--group=developer experience", "-PbootstrapProfile=dev");
assertThat(devRun.getOutput())
.contains("bootstrap contract for the dev")
.contains("starts the dev PostgreSQL dependency");
}
@Test
void aProfileWithNoOverlayIsRefusedAndTheMessageListsTheRealOnes(
@TempDir Path temporaryDirectory) throws IOException {
// The failure a developer is most likely to hit is a typo, and the answer they need is which
// names exist — read off the directory rather than from a list somebody has to maintain.
Path projectDirectory = fixture(temporaryDirectory);
BuildResult failure =
runAndFail(projectDirectory, "bootstrapDockerPreflight", "-PbootstrapProfile=staging");
assertThat(failure.getOutput())
.contains("names no overlay")
.contains("docker-compose.staging.yml")
.contains("[dev, local]");
}
@Test
void configurationDoesNotRequireComposeFiles(@TempDir Path temporaryDirectory)
throws IOException {
// The Docker image build copies only src/ into its context, so the repository root and its
// compose files do not exist there. Configuring the root project must still succeed; only the
// bootstrap tasks themselves need an overlay.
Path projectDirectory = fixtureWithoutComposeFiles(temporaryDirectory);
BuildResult result = run(projectDirectory, "help");
assertThat(result.getOutput()).contains("BUILD SUCCESSFUL");
}
@Test
void bootstrapTaskKeepsTheRequiredStageOrder(@TempDir Path temporaryDirectory) throws IOException {
Path projectDirectory = fixture(temporaryDirectory);
BuildResult result = run(projectDirectory, "bootstrap", "--dry-run");
String output = result.getOutput();
assertThat(output.indexOf(":bootstrapCompile SKIPPED")).isLessThan(output.indexOf(":bootstrapDockerPreflight SKIPPED"));
assertThat(output.indexOf(":bootstrapDockerPreflight SKIPPED")).isLessThan(output.indexOf(":bootstrapDependencies SKIPPED"));
assertThat(output.indexOf(":bootstrapDependencies SKIPPED")).isLessThan(output.indexOf(":bootstrapMigrateAndStart SKIPPED"));
assertThat(output.indexOf(":bootstrapMigrateAndStart SKIPPED")).isLessThan(output.indexOf(":bootstrapSmoke SKIPPED"));
assertThat(output.indexOf(":bootstrapSmoke SKIPPED")).isLessThan(output.indexOf(":bootstrap SKIPPED"));
}
private static Path fixture(Path temporaryDirectory) throws IOException {
Path projectDirectory = fixtureWithoutComposeFiles(temporaryDirectory);
Path repositoryRoot = projectDirectory.getParent();
// The bootstrap merges an overlay onto the base compose file and refuses a profile that names
// none, so the fixture has to carry the two the repository carries.
Files.writeString(repositoryRoot.resolve("docker-compose.yml"), "services: {}\n", UTF_8);
Files.writeString(repositoryRoot.resolve("docker-compose.local.yml"), "services: {}\n", UTF_8);
Files.writeString(repositoryRoot.resolve("docker-compose.dev.yml"), "services: {}\n", UTF_8);
return projectDirectory;
}
private static Path fixtureWithoutComposeFiles(Path temporaryDirectory) throws IOException {
Path repositoryRoot = temporaryDirectory.resolve("repository");
Path projectDirectory = repositoryRoot.resolve("src");
Files.createDirectories(projectDirectory.resolve("app-bootstrap"));
Files.writeString(
projectDirectory.resolve("settings.gradle"),
"rootProject.name='fixture'\ninclude 'app-bootstrap'\n",
UTF_8);
Files.writeString(
projectDirectory.resolve("build.gradle"),
"plugins { id 'ca.developer-bootstrap' }\n",
UTF_8);
Files.writeString(
projectDirectory.resolve("app-bootstrap/build.gradle"),
"plugins { id 'java' }\n",
UTF_8);
return projectDirectory;
}
private static BuildResult runAndFail(Path projectDirectory, String... arguments) {
return GradleRunner.create()
.withProjectDir(projectDirectory.toFile())
.withPluginClasspath()
.withArguments(withConsole(arguments))
.buildAndFail();
}
private static String[] withConsole(String... arguments) {
String[] fullArguments = new String[arguments.length + 1];
fullArguments[0] = "--console=plain";
System.arraycopy(arguments, 0, fullArguments, 1, arguments.length);
return fullArguments;
}
private static BuildResult run(Path projectDirectory, String... arguments) {
String[] fullArguments = new String[arguments.length + 1];
fullArguments[0] = "--console=plain";
System.arraycopy(arguments, 0, fullArguments, 1, arguments.length);
return GradleRunner.create()
.withProjectDir(projectDirectory.toFile())
.withPluginClasspath()
.withArguments(fullArguments)
.build();
}
}
@@ -1,4 +1,4 @@
package dev.caskeleton.buildtools.config;
package dev.caskeleton.buildlogic.config;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
@@ -1,4 +1,4 @@
package dev.caskeleton.buildtools.config;
package dev.caskeleton.buildlogic.config;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
@@ -1,37 +0,0 @@
package dev.caskeleton.buildlogic.publicpath;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.nio.file.Files;
import java.nio.file.Path;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
class PublicPathSnapshotRendererTest {
@Test
void resolvesNestedSpringDefaultsAndSortsPaths(@TempDir Path temp) throws Exception {
Path security = temp.resolve("security.yml");
Files.writeString(
security,
"ca-skeleton:\n security:\n public-paths: ${SECURITY_PUBLIC_PATHS:${PRESENTATION_API_BASE_PATH:/v1}/healthcheck,/actuator/info}\n");
PublicPathSnapshot rendered = PublicPathSnapshotRenderer.render(security.toFile());
assertThat(rendered.publicPaths()).containsExactly("/actuator/info", "/v1/healthcheck");
assertThat(rendered.canonicalText())
.contains("# feature-security-operational-baseline D5")
.endsWith("/actuator/info\n/v1/healthcheck\n");
}
@Test
void unresolvedPlaceholderFailsClosed(@TempDir Path temp) throws Exception {
Path security = temp.resolve("security.yml");
Files.writeString(security, "public-paths: ${SECURITY_PUBLIC_PATHS}\n");
assertThatThrownBy(() -> PublicPathSnapshotRenderer.render(security.toFile()))
.isInstanceOf(IllegalStateException.class)
.hasMessageContaining("still holds a placeholder with no default");
}
}
@@ -56,6 +56,38 @@ class RedisTopologyLanePluginFunctionalTest {
}
@Test
void withoutADeclaredModeTheLaneStaysOutOfTheIntegrationAggregate() {
// given
String[] arguments = {"integrationTestLaneCheck", "--console=plain"};
// when
BuildResult result = runner(arguments).build();
// then
assertTrue(!result.getOutput().contains("> Task :redisTopologyTest"), result.getOutput());
assertTrue(
result.getOutput().contains("'redisTopologyTest' in : runs only when named"),
result.getOutput());
}
@Test
void aDeclaredModePutsTheLaneInTheIntegrationAggregate() throws Exception {
// given
Path testSource = projectDir.resolve("src/test/java");
Files.createDirectories(testSource);
Files.writeString(testSource.resolve("FixtureTest.java"), "class FixtureTest {}\n");
String[] arguments = {
"integrationTestLaneCheck", "-Predis.topology.mode=standalone", "--dry-run", "--console=plain"
};
// when
BuildResult result = runner(arguments).build();
// then
assertTrue(result.getOutput().contains(":redisTopologyTest"), result.getOutput());
}
private GradleRunner runner(String... arguments) {
return GradleRunner.create()
.withProjectDir(projectDir.toFile())
@@ -385,6 +385,79 @@ class StrictTestLaneConventionTest {
assertTrue(result.getOutput().contains("performanceLane"), result.getOutput());
}
@Test
void aMainStageLaneLeavesTheLeafTestTaskAndJoinsMainCheck() throws Exception {
// given
buildFile(
junitDependencies()
+ """
tasks.register('mainCheck')
strictTestLanes {
lane('documentContractTest') {
tag = 'document-contract'
description = 'Compares the leaf with its documents.'
rejectSkipped = true
mainStage()
}
}
""");
writeTest(
"DocumentTest.java",
"""
import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
class DocumentTest {
@Test @Tag("document-contract") void comparesDocuments() {
throw new AssertionError("document lane test ran in the pull-request test task");
}
@Test void ordinary() {}
}
""");
// when
BuildResult test = runner("test").build();
BuildResult mainCheck = runner("mainCheck", "--dry-run").build();
// then
assertTrue(test.getOutput().contains("BUILD SUCCESSFUL"), test.getOutput());
assertTrue(mainCheck.getOutput().contains(":documentContractTest"), mainCheck.getOutput());
}
@Test
void anExplicitOnlyLaneStaysOutOfEveryAggregate() throws Exception {
// given
buildFile(
"""
sourceSets { integration }
strictTestLanes {
lane('credentialLane') {
sourceSet = 'integration'
description = 'Needs protected credentials.'
integration()
explicitOnly 'the protected credentials are not set'
}
}
tasks.register('reportAggregates') {
doLast {
['strictTestLaneCheck', 'integrationTestLaneCheck'].each { name ->
def aggregate = tasks.named(name).get()
logger.lifecycle(name + '=' + aggregate.taskDependencies.getDependencies(aggregate)*.name.sort())
}
}
}
""");
// when
BuildResult result =
runner("reportAggregates", "integrationTestLaneCheck", "--console=plain").build();
// then
assertTrue(result.getOutput().contains("strictTestLaneCheck=[]"), result.getOutput());
assertTrue(result.getOutput().contains("integrationTestLaneCheck=[]"), result.getOutput());
assertTrue(
result.getOutput().contains("the protected credentials are not set"), result.getOutput());
}
private void buildFile(String laneBlock) throws Exception {
Files.writeString(
projectDir.resolve("build.gradle"),
-39
View File
@@ -1,39 +0,0 @@
plugins {
id 'java-gradle-plugin'
}
// Repository verification tooling lives here, physically separate from compilation conventions.
// Precompiled plugins in this build should stay thin: task wiring here, verification algorithms in normal classes.
// Locked like build-logic and every leaf (gradle.lockfile beside this file). Regenerate with
// `./gradlew -p build-tools dependencies --write-locks` after a catalog version change.
dependencyLocking {
lockAllConfigurations()
lockMode = LockMode.STRICT
}
dependencies {
implementation libs.jackson3.databind
testImplementation libs.junit.jupiter
testRuntimeOnly libs.junit.platform.launcher
}
gradlePlugin {
plugins {
jpaEvidence {
id = 'ca.jpa-evidence'
implementationClass = 'dev.caskeleton.buildtools.jpa.JpaEvidencePlugin'
}
configContract {
id = 'ca.config-contract'
implementationClass = 'dev.caskeleton.buildtools.config.ConfigContractPlugin'
}
jpaQualification {
id = 'ca.jpa-qualification'
implementationClass = 'dev.caskeleton.buildtools.jpa.JpaQualificationPlugin'
}
}
}
tasks.named('test') { useJUnitPlatform() }
-18
View File
@@ -1,18 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.fasterxml.jackson.core:jackson-annotations:2.20=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.junit.jupiter:junit-jupiter-api:5.11.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:5.11.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:5.11.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:5.11.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:1.11.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:1.11.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:1.11.3=testRuntimeClasspath
org.junit:junit-bom:5.11.3=testCompileClasspath,testRuntimeClasspath
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
tools.jackson.core:jackson-core:3.0.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
tools.jackson.core:jackson-databind:3.0.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
tools.jackson:jackson-bom:3.0.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
empty=annotationProcessor,testAnnotationProcessor
-4
View File
@@ -1,4 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
empty=incomingCatalogForLibs0
-14
View File
@@ -1,14 +0,0 @@
dependencyResolutionManagement {
versionCatalogs {
libs {
from(files('../gradle/libs.versions.toml'))
}
}
repositories {
mavenCentral()
gradlePluginPortal()
}
}
rootProject.name = 'build-tools'
@@ -1,372 +0,0 @@
package dev.caskeleton.buildtools.jpa;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.time.Instant;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.TreeSet;
import javax.inject.Inject;
import org.gradle.api.DefaultTask;
import org.gradle.api.GradleException;
import org.gradle.api.file.DirectoryProperty;
import org.gradle.api.file.FileSystemOperations;
import org.gradle.api.file.RegularFileProperty;
import org.gradle.api.provider.MapProperty;
import org.gradle.api.provider.Property;
import org.gradle.api.tasks.Input;
import org.gradle.api.tasks.InputFile;
import org.gradle.api.tasks.OutputDirectory;
import org.gradle.api.tasks.TaskAction;
import org.gradle.api.services.ServiceReference;
import org.gradle.process.ExecOperations;
import org.gradle.process.ExecResult;
import org.gradle.work.DisableCachingByDefault;
@DisableCachingByDefault(because = "Evidence contains execution state and a generation timestamp")
public abstract class GenerateJpaEvidenceManifestsTask extends DefaultTask {
private final ExecOperations execOperations;
private final FileSystemOperations fileSystemOperations;
@Inject
public GenerateJpaEvidenceManifestsTask(
ExecOperations execOperations, FileSystemOperations fileSystemOperations) {
this.execOperations = execOperations;
this.fileSystemOperations = fileSystemOperations;
}
@InputFile
public abstract RegularFileProperty getRegistryFile();
@OutputDirectory
public abstract DirectoryProperty getEvidenceOutputDirectory();
@Input
public abstract Property<String> getPostgreSqlImage();
@Input
public abstract Property<String> getEvidenceProfile();
@Input
public abstract Property<String> getCiJob();
@Input
public abstract Property<String> getArtifactLocation();
@Input
public abstract Property<String> getTopology();
@Input
public abstract Property<String> getSourceRevision();
@Input
public abstract Property<String> getTraceableVersion();
@Input
public abstract Property<String> getPgjdbcVersion();
@Input
public abstract Property<String> getHibernateVersion();
@Input
public abstract Property<String> getFlywayVersion();
@Input
public abstract Property<String> getRepositoryRootPath();
@Input
public abstract MapProperty<String, String> getJUnitResultDirectories();
@ServiceReference("jpaEvidenceExecution")
public abstract Property<JpaEvidenceExecutionService> getExecutionService();
@TaskAction
public void generate() {
JpaReadinessRegistry registry =
JpaEvidenceTaskSupport.loadRegistry(getRegistryFile().get().getAsFile());
List<JpaReadinessCard> activeCards = registry.activeCards();
String profile = getEvidenceProfile().get();
if (!profile.equals("candidate") && !profile.equals("r2")) {
throw new GradleException(
"jpaEvidenceProfile must be candidate or r2; got '" + profile + "'");
}
String ciJob = getCiJob().get();
String configuredArtifactLocation = getArtifactLocation().get();
String topology = getTopology().get();
String worktreeStatus =
runCommand(
List.of("git", "status", "--porcelain=v1", "--untracked-files=all"), true);
boolean worktreeDirty = !worktreeStatus.isBlank();
String worktreeStatusDigest = JpaEvidenceVerifier.sha256(worktreeStatus);
String image = getPostgreSqlImage().get();
String imageDigest =
runCommand(
List.of(
"docker", "image", "inspect", "--format={{index .RepoDigests 0}}", image),
false);
JpaDependencyVersions dependencyVersions =
new JpaDependencyVersions(
getPgjdbcVersion().get(), getHibernateVersion().get(), getFlywayVersion().get());
JpaEvidenceTestResultLocator testResultsByTask =
new JpaEvidenceTestResultLocator(
java.nio.file.Path.of(getRepositoryRootPath().get()), getJUnitResultDirectories().get());
JpaEvidenceExecutionService executionService = getExecutionService().get();
List<String> productionMetadataBlockers = new ArrayList<>();
if (profile.equals("r2")) {
if (worktreeDirty) {
productionMetadataBlockers.add("worktree-is-dirty");
}
if (ciJob.isBlank()) {
productionMetadataBlockers.add("missing-JPA_EVIDENCE_CI_JOB");
}
if (configuredArtifactLocation.isBlank()) {
productionMetadataBlockers.add("missing-JPA_EVIDENCE_ARTIFACT_LOCATION");
} else if (!configuredArtifactLocation.matches("(?i)(https|s3|gs)://\\S+")) {
productionMetadataBlockers.add("artifact-location-is-not-externally-retained");
}
}
if (!imageDigest.matches(".+@sha256:[0-9a-f]{64}")) {
productionMetadataBlockers.add("missing-immutable-postgresql-image-digest");
}
if (dependencyVersions.pgjdbc().isBlank()) {
productionMetadataBlockers.add("missing-pgjdbc-version");
}
if (dependencyVersions.hibernate().isBlank()) {
productionMetadataBlockers.add("missing-hibernate-version");
}
if (dependencyVersions.flyway().isBlank()) {
productionMetadataBlockers.add("missing-flyway-version");
}
File outputDirectory = getEvidenceOutputDirectory().get().getAsFile();
fileSystemOperations.delete(spec -> spec.delete(outputDirectory));
if (!outputDirectory.mkdirs() && !outputDirectory.isDirectory()) {
throw new GradleException("Could not create JPA evidence directory " + outputDirectory);
}
Map<String, JpaGeneratedEvidenceManifest> manifests = new HashMap<>();
Map<String, String> manifestIds = new HashMap<>();
for (JpaReadinessCard card : activeCards) {
String cardId = card.id();
List<JpaGeneratedTestResult> testResults = new ArrayList<>();
if (cardId.equals("jpa-primary-foundation")) {
for (String prerequisite : card.prerequisites()) {
JpaGeneratedEvidenceManifest prerequisiteManifest = manifests.get(prerequisite);
if (prerequisiteManifest != null) {
testResults.add(prerequisiteManifest.testResult());
}
}
} else {
testResults.add(testResultsByTask.read(card.readinessTask()));
for (String supportPath : card.supportTasks()) {
if (getJUnitResultDirectories().get().containsKey(supportPath)) {
testResults.add(testResultsByTask.read(supportPath));
}
}
}
Set<String> executedSelectors = new TreeSet<>();
testResults.forEach(result -> executedSelectors.addAll(result.executedSelectors()));
Set<String> covered = new TreeSet<>();
JpaCardEvidence cardEvidence =
card.evidence()
.orElseThrow(
() -> new GradleException(cardId + ": active card has no typed evidence declaration"));
for (JpaEvidenceScenario scenario : cardEvidence.scenarios()) {
if (executedSelectors.contains(scenario.selector())) {
covered.addAll(scenario.covers());
}
}
for (JpaEvidenceTaskClaim taskClaim : cardEvidence.taskClaims()) {
if (executionService.completedSuccessfully(taskClaim.task())) {
covered.addAll(taskClaim.covers());
}
}
int executedTestCount = JpaEvidenceTaskSupport.sumExecuted(testResults);
int skippedOrAbortedCount = JpaEvidenceTaskSupport.sumSkipped(testResults);
int failureCount = JpaEvidenceTaskSupport.sumFailures(testResults);
int errorCount = JpaEvidenceTaskSupport.sumErrors(testResults);
boolean noSkipResult =
executedTestCount > 0
&& skippedOrAbortedCount == 0
&& failureCount == 0
&& errorCount == 0;
if (noSkipResult) {
covered.add("no-skip");
}
if (cardId.equals("jpa-primary-foundation")
&& card.prerequisites().stream().allMatch(manifestIds::containsKey)) {
covered.add("base-card-manifests");
}
List<String> required = JpaEvidenceVerifier.requiredEvidence(card);
List<String> coveredList =
covered.stream().filter(required::contains).sorted().toList();
List<String> missing = new ArrayList<>(required);
missing.removeAll(coveredList);
missing.sort(String::compareTo);
List<JpaPrerequisiteEvidence> prerequisites = new ArrayList<>();
for (String prerequisiteId : card.prerequisites()) {
JpaGeneratedEvidenceManifest prerequisiteManifest = manifests.get(prerequisiteId);
String prerequisiteManifestId = manifestIds.get(prerequisiteId);
if (prerequisiteManifest == null || prerequisiteManifestId == null) {
throw new GradleException(
cardId
+ ": prerequisite manifest '"
+ prerequisiteId
+ "' was not produced first");
}
prerequisites.add(
new JpaPrerequisiteEvidence(
prerequisiteId,
prerequisiteManifest.cardVersion(),
prerequisiteManifestId,
prerequisiteManifest.attainedReadiness()));
}
List<String> readinessBlockers = new ArrayList<>();
if (profile.equals("candidate")) {
readinessBlockers.add("candidate-profile-is-not-release-evidence");
}
readinessBlockers.addAll(productionMetadataBlockers);
for (String requirement : missing) {
readinessBlockers.add("missing-evidence:" + requirement);
}
for (JpaPrerequisiteEvidence prerequisite : prerequisites) {
if (!prerequisite.attainedReadiness().equals("R2")) {
readinessBlockers.add("prerequisite-not-R2:" + prerequisite.cardId());
}
}
List<String> sortedReadinessBlockers =
JpaEvidenceTaskSupport.sortedDistinct(readinessBlockers);
boolean attainedR2 =
profile.equals("r2") && sortedReadinessBlockers.isEmpty() && missing.isEmpty();
String generatedAt = Instant.now().toString();
String cardVersion =
card.migration()
.map(migration -> Integer.toString(migration.featureRevision()))
.orElse(getTraceableVersion().get());
String evidenceGrade =
cardId.equals("jpa-primary-foundation")
? "E1"
: covered.stream()
.anyMatch(
claim ->
Set.of(
"concurrency",
"fault",
"publish-fault",
"migration",
"query-plan",
"optimistic-conflict")
.contains(claim))
? "E3"
: "E2";
JpaGeneratedMigrationEvidence migration =
card.migration()
.map(
spec ->
new JpaGeneratedMigrationEvidence(
spec.location(),
spec.historyTable(),
spec.requiredCoreEpoch(),
spec.featureRevision(),
spec.lifecycleEvidence()))
.orElse(null);
JpaGeneratedTestResult combinedTestResult =
new JpaGeneratedTestResult(
JpaEvidenceTaskSupport.allTasks(testResults),
JpaEvidenceTaskSupport.allResultDirectories(testResults),
executedTestCount,
skippedOrAbortedCount,
failureCount,
errorCount,
noSkipResult,
List.copyOf(executedSelectors));
JpaGeneratedEvidenceManifest manifest =
new JpaGeneratedEvidenceManifest(
1,
cardId,
cardVersion,
card.state().externalValue(),
attainedR2 ? "R2" : "R1",
evidenceGrade,
profile,
prerequisites,
new JpaGeneratedSourceEvidence(
getSourceRevision().get(), worktreeDirty, worktreeStatusDigest),
new JpaGeneratedProducerEvidence(card.readinessTask(), ciJob),
combinedTestResult,
required,
coveredList,
missing,
sortedReadinessBlockers,
new JpaGeneratedPostgresqlEvidence(image, imageDigest, "16"),
dependencyVersions,
generatedAt,
generatedAt.substring(0, 10),
topology,
configuredArtifactLocation,
migration,
card.dispatchModes());
String contentHash =
JpaEvidenceVerifier.sha256(JpaEvidenceVerifier.canonicalJson(manifest));
File cardDirectory = new File(outputDirectory, cardId);
if (!cardDirectory.mkdirs() && !cardDirectory.isDirectory()) {
throw new GradleException("Could not create JPA evidence card directory " + cardDirectory);
}
File manifestFile = new File(cardDirectory, contentHash + ".json");
try {
Files.writeString(
manifestFile.toPath(), JpaEvidenceVerifier.prettyJson(manifest), StandardCharsets.UTF_8);
} catch (IOException exception) {
throw new UncheckedIOException("failed to write " + manifestFile, exception);
}
manifests.put(cardId, manifest);
manifestIds.put(cardId, "sha256:" + contentHash);
}
getLogger()
.lifecycle(
"generateJpaEvidenceManifests: wrote {} {} content-addressed card manifests to {}",
manifests.size(),
profile,
outputDirectory);
}
private String runCommand(List<String> command, boolean requireSuccess) {
ByteArrayOutputStream output = new ByteArrayOutputStream();
ExecResult result =
execOperations.exec(
spec -> {
spec.setCommandLine(command);
spec.setIgnoreExitValue(true);
spec.setStandardOutput(output);
});
String text = output.toString(StandardCharsets.UTF_8).trim();
if (requireSuccess && result.getExitValue() != 0) {
throw new GradleException(
"JPA evidence: `"
+ String.join(" ", command)
+ "` exited "
+ result.getExitValue()
+ ". Its result is a precondition of the evidence, not an optional detail — an unavailable command must not be read as a satisfied condition.");
}
return text;
}
}
@@ -1,11 +0,0 @@
package dev.caskeleton.buildtools.jpa;
import java.util.List;
public record JpaCardEvidence(
List<JpaEvidenceScenario> scenarios, List<JpaEvidenceTaskClaim> taskClaims) {
public JpaCardEvidence {
scenarios = List.copyOf(scenarios);
taskClaims = List.copyOf(taskClaims);
}
}
@@ -1,26 +0,0 @@
package dev.caskeleton.buildtools.jpa;
public enum JpaCardState {
SELECTED("selected"),
IMPLEMENTED_CANDIDATE("implemented-candidate"),
NOT_IMPLEMENTED("not-implemented");
private final String externalValue;
JpaCardState(String externalValue) {
this.externalValue = externalValue;
}
public String externalValue() {
return externalValue;
}
public static JpaCardState parse(String value) {
for (JpaCardState state : values()) {
if (state.externalValue.equals(value)) {
return state;
}
}
throw new IllegalStateException("invalid JPA card state '" + value + "'");
}
}
@@ -1,11 +0,0 @@
package dev.caskeleton.buildtools.jpa;
import java.util.Objects;
public record JpaDependencyVersions(String pgjdbc, String hibernate, String flyway) {
public JpaDependencyVersions {
Objects.requireNonNull(pgjdbc, "pgjdbc");
Objects.requireNonNull(hibernate, "hibernate");
Objects.requireNonNull(flyway, "flyway");
}
}
@@ -1,45 +0,0 @@
package dev.caskeleton.buildtools.jpa;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
import org.gradle.api.services.BuildService;
import org.gradle.api.services.BuildServiceParameters;
import org.gradle.tooling.events.FinishEvent;
import org.gradle.tooling.events.OperationCompletionListener;
import org.gradle.tooling.events.task.TaskFailureResult;
import org.gradle.tooling.events.task.TaskFinishEvent;
import org.gradle.tooling.events.task.TaskSkippedResult;
import org.gradle.tooling.events.task.TaskSuccessResult;
public abstract class JpaEvidenceExecutionService
implements BuildService<BuildServiceParameters.None>, OperationCompletionListener {
private final Map<String, JpaEvidenceTaskOutcome> outcomes = new ConcurrentHashMap<>();
@Override
public void onFinish(FinishEvent event) {
if (!(event instanceof TaskFinishEvent taskEvent)) {
return;
}
String taskPath = taskEvent.getDescriptor().getTaskPath();
if (taskEvent.getResult() instanceof TaskSuccessResult) {
record(taskPath, JpaEvidenceTaskOutcome.SUCCESS);
} else if (taskEvent.getResult() instanceof TaskFailureResult) {
record(taskPath, JpaEvidenceTaskOutcome.FAILED);
} else if (taskEvent.getResult() instanceof TaskSkippedResult) {
record(taskPath, JpaEvidenceTaskOutcome.SKIPPED);
}
}
void record(String taskPath, JpaEvidenceTaskOutcome outcome) {
outcomes.put(taskPath, outcome);
}
Optional<JpaEvidenceTaskOutcome> outcome(String taskPath) {
return Optional.ofNullable(outcomes.get(taskPath));
}
public boolean completedSuccessfully(String taskPath) {
return outcomes.get(taskPath) == JpaEvidenceTaskOutcome.SUCCESS;
}
}
@@ -1,33 +0,0 @@
package dev.caskeleton.buildtools.jpa;
import java.util.List;
import java.util.Objects;
public record JpaEvidenceManifest(
String cardId,
String attainedReadiness,
String profile,
String evidenceGrade,
List<String> missingEvidence,
List<String> readinessBlockers,
JpaTestResult testResult,
JpaPostgresqlEvidence postgresql,
JpaDependencyVersions dependencies,
JpaSourceEvidence source,
JpaProducerEvidence producer,
String artifactLocation) {
public JpaEvidenceManifest {
Objects.requireNonNull(cardId, "cardId");
Objects.requireNonNull(attainedReadiness, "attainedReadiness");
Objects.requireNonNull(profile, "profile");
Objects.requireNonNull(evidenceGrade, "evidenceGrade");
missingEvidence = List.copyOf(missingEvidence);
readinessBlockers = List.copyOf(readinessBlockers);
Objects.requireNonNull(testResult, "testResult");
Objects.requireNonNull(postgresql, "postgresql");
Objects.requireNonNull(dependencies, "dependencies");
Objects.requireNonNull(source, "source");
Objects.requireNonNull(producer, "producer");
Objects.requireNonNull(artifactLocation, "artifactLocation");
}
}
@@ -1,216 +0,0 @@
package dev.caskeleton.buildtools.jpa;
import java.io.File;
import java.util.LinkedHashMap;
import java.util.Map;
import javax.inject.Inject;
import org.gradle.api.GradleException;
import org.gradle.api.Plugin;
import org.gradle.api.Project;
import org.gradle.api.Task;
import org.gradle.api.provider.Provider;
import org.gradle.api.tasks.TaskProvider;
import org.gradle.api.tasks.testing.Test;
import org.gradle.build.event.BuildEventsListenerRegistry;
public final class JpaEvidencePlugin implements Plugin<Project> {
private final BuildEventsListenerRegistry buildEventsListenerRegistry;
@Inject
public JpaEvidencePlugin(BuildEventsListenerRegistry buildEventsListenerRegistry) {
this.buildEventsListenerRegistry = buildEventsListenerRegistry;
}
@Override
public void apply(Project project) {
Project root = project.getRootProject();
File registryFile = root.file("config/jpa/readiness-cards.yaml");
var outputDirectory = project.getLayout().getBuildDirectory().dir("jpa-evidence/manifests");
Provider<JpaEvidenceExecutionService> executionService =
project
.getGradle()
.getSharedServices()
.registerIfAbsent(
"jpaEvidenceExecution", JpaEvidenceExecutionService.class, ignored -> {});
buildEventsListenerRegistry.onTaskCompletion(executionService);
TaskProvider<GenerateJpaEvidenceManifestsTask> generate =
project
.getTasks()
.register(
"generateJpaEvidenceManifests",
GenerateJpaEvidenceManifestsTask.class,
task -> {
task.setGroup("verification");
task.setDescription(
"Runs active JPA card producers and writes content-addressed candidate/R2 manifests.");
task.dependsOn(root.getTasks().named("verifyJpaReadinessRegistry"));
task.getRegistryFile().fileValue(registryFile);
task.getEvidenceOutputDirectory().set(outputDirectory);
task.getPostgreSqlImage()
.convention(
project
.getProviders()
.gradleProperty("jpaPostgreSqlEvidenceImage")
.orElse("postgres:16-alpine"));
var profile =
project
.getProviders()
.gradleProperty("jpaEvidenceProfile")
.orElse(project.getProviders().environmentVariable("JPA_EVIDENCE_PROFILE"))
.orElse("candidate");
task.getEvidenceProfile().convention(profile);
task.getCiJob()
.convention(
project
.getProviders()
.environmentVariable("JPA_EVIDENCE_CI_JOB")
.orElse(
profile.map(
value ->
value.equals("candidate")
? "local-unpublished"
: "")));
String candidateArtifactLocation =
root.relativePath(outputDirectory.get().getAsFile());
task.getArtifactLocation()
.convention(
project
.getProviders()
.environmentVariable("JPA_EVIDENCE_ARTIFACT_LOCATION")
.orElse(
profile.map(
value ->
value.equals("candidate")
? candidateArtifactLocation
: "")));
task.getTopology()
.convention(
project
.getProviders()
.environmentVariable("JPA_EVIDENCE_TOPOLOGY")
.orElse("single-postgresql-testcontainer"));
task.getSourceRevision().set(configurationString(root, "sourceRevision"));
task.getTraceableVersion().set(configurationString(root, "traceableVersion"));
task.getRepositoryRootPath().set(root.getProjectDir().getAbsolutePath());
task.getExecutionService().set(executionService);
task.usesService(executionService);
var runtimeClasspath =
project
.getConfigurations()
.getByName("postgresqlIntegrationTestRuntimeClasspath");
Provider<JpaDependencyVersions> dependencyVersions =
project
.getProviders()
.provider(
() -> JpaEvidenceTaskSupport.resolvedVersions(runtimeClasspath));
task.getPgjdbcVersion().set(dependencyVersions.map(JpaDependencyVersions::pgjdbc));
task.getHibernateVersion()
.set(dependencyVersions.map(JpaDependencyVersions::hibernate));
task.getFlywayVersion().set(dependencyVersions.map(JpaDependencyVersions::flyway));
Map<String, String> junitResultDirectories = new LinkedHashMap<>();
JpaReadinessRegistry registry =
JpaEvidenceTaskSupport.loadRegistry(registryFile);
for (JpaReadinessCard card : registry.activeCards()) {
if (!card.id().equals("jpa-primary-foundation")) {
Task readinessTask =
JpaEvidenceTaskSupport.taskAtPath(root, card.readinessTask());
task.dependsOn(readinessTask);
if (!(readinessTask instanceof Test readinessTest)) {
throw new GradleException(
card.id()
+ ": readiness task "
+ readinessTask.getPath()
+ " must be a Test task");
}
junitResultDirectories.put(
readinessTask.getPath(), junitResultDirectory(readinessTest));
}
for (String supportPath : card.supportTasks()) {
Task supportTask = JpaEvidenceTaskSupport.taskAtPath(root, supportPath);
task.dependsOn(supportTask);
if (supportTask instanceof Test supportTest) {
junitResultDirectories.put(
supportTask.getPath(), junitResultDirectory(supportTest));
}
}
}
task.getJUnitResultDirectories().set(junitResultDirectories);
task.getOutputs().upToDateWhen(ignored -> false);
});
project
.getGradle()
.getTaskGraph()
.whenReady(
graph -> {
if (!graph.hasTask(generate.get())) {
return;
}
project
.getTasks()
.named("test", Test.class)
.get()
.getOutputs()
.upToDateWhen(ignored -> false);
Project appBootstrap = root.findProject(":app-bootstrap");
if (appBootstrap != null) {
appBootstrap
.getTasks()
.named("test", Test.class)
.get()
.getOutputs()
.upToDateWhen(ignored -> false);
}
});
project
.getTasks()
.register(
"verifyJpaCandidateEvidence",
VerifyJpaCandidateEvidenceTask.class,
task -> {
task.setGroup("verification");
task.setDescription(
"Validates hashes, schema, exact JUnit selectors, no-skip, and prerequisite links without claiming R2.");
task.dependsOn(generate);
task.getRegistryFile().fileValue(registryFile);
task.getEvidenceOutputDirectory().set(outputDirectory);
task.getOutputs().upToDateWhen(ignored -> false);
});
project
.getTasks()
.register(
"verifyJpaPrimaryFoundationEvidence",
VerifyJpaPrimaryFoundationEvidenceTask.class,
task -> {
task.setGroup("verification");
task.setDescription(
"Requires complete immutable base-card manifests from a clean, retained CI R2 evidence lane.");
task.dependsOn(generate);
task.getRegistryFile().fileValue(registryFile);
task.getEvidenceOutputDirectory().set(outputDirectory);
task.getOutputs().upToDateWhen(ignored -> false);
});
}
private static String configurationString(Project project, String name) {
var extra = project.getExtensions().getExtraProperties();
return extra.has(name) ? String.valueOf(extra.get(name)) : "";
}
private static String junitResultDirectory(Test test) {
return test
.getReports()
.getJunitXml()
.getOutputLocation()
.get()
.getAsFile()
.getAbsolutePath();
}
}
@@ -1,11 +0,0 @@
package dev.caskeleton.buildtools.jpa;
import java.util.List;
import java.util.Objects;
public record JpaEvidenceScenario(String selector, List<String> covers) {
public JpaEvidenceScenario {
Objects.requireNonNull(selector, "selector");
covers = List.copyOf(covers);
}
}
@@ -1,11 +0,0 @@
package dev.caskeleton.buildtools.jpa;
import java.util.List;
import java.util.Objects;
public record JpaEvidenceTaskClaim(String task, List<String> covers) {
public JpaEvidenceTaskClaim {
Objects.requireNonNull(task, "task");
covers = List.copyOf(covers);
}
}
@@ -1,7 +0,0 @@
package dev.caskeleton.buildtools.jpa;
enum JpaEvidenceTaskOutcome {
SUCCESS,
FAILED,
SKIPPED
}
@@ -1,100 +0,0 @@
package dev.caskeleton.buildtools.jpa;
import java.io.File;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.util.ArrayList;
import java.util.List;
import java.util.TreeSet;
import org.gradle.api.GradleException;
import org.gradle.api.Project;
import org.gradle.api.Task;
import org.gradle.api.artifacts.Configuration;
import org.gradle.api.artifacts.component.ModuleComponentIdentifier;
import org.gradle.api.artifacts.result.ResolvedComponentResult;
final class JpaEvidenceTaskSupport {
private JpaEvidenceTaskSupport() {}
static JpaReadinessRegistry loadRegistry(File registryFile) {
try {
return JpaReadinessRegistryParser.parse(
Files.readString(registryFile.toPath(), StandardCharsets.UTF_8));
} catch (IOException exception) {
throw new UncheckedIOException("failed to read " + registryFile, exception);
}
}
static Task taskAtPath(Project rootProject, String absoluteTaskPath) {
int separator = absoluteTaskPath.lastIndexOf(':');
if (separator < 0 || separator == absoluteTaskPath.length() - 1) {
throw new GradleException("Invalid absolute Gradle task path '" + absoluteTaskPath + "'");
}
String projectPath = separator == 0 ? ":" : absoluteTaskPath.substring(0, separator);
String taskName = absoluteTaskPath.substring(separator + 1);
Project owner = rootProject.findProject(projectPath);
if (owner == null) {
throw new GradleException("Unknown project for JPA evidence task '" + absoluteTaskPath + "'");
}
Task task = owner.getTasks().findByName(taskName);
if (task == null) {
throw new GradleException("Missing JPA evidence task '" + absoluteTaskPath + "'");
}
return task;
}
static JpaDependencyVersions resolvedVersions(Configuration configuration) {
String pgjdbc = "";
String hibernate = "";
String flyway = "";
for (ResolvedComponentResult component :
configuration.getIncoming().getResolutionResult().getAllComponents()) {
if (!(component.getId() instanceof ModuleComponentIdentifier id)) {
continue;
}
String coordinate = id.getGroup() + ":" + id.getModule();
if (coordinate.equals("org.postgresql:postgresql")) {
pgjdbc = id.getVersion();
} else if (coordinate.equals("org.hibernate.orm:hibernate-core")) {
hibernate = id.getVersion();
} else if (coordinate.equals("org.flywaydb:flyway-core")) {
flyway = id.getVersion();
}
}
return new JpaDependencyVersions(pgjdbc, hibernate, flyway);
}
static List<String> sortedDistinct(List<String> values) {
return new TreeSet<>(values).stream().toList();
}
static int sumExecuted(List<JpaGeneratedTestResult> values) {
return values.stream().mapToInt(JpaGeneratedTestResult::executedTestCount).sum();
}
static int sumSkipped(List<JpaGeneratedTestResult> values) {
return values.stream().mapToInt(JpaGeneratedTestResult::skippedOrAbortedCount).sum();
}
static int sumFailures(List<JpaGeneratedTestResult> values) {
return values.stream().mapToInt(JpaGeneratedTestResult::failureCount).sum();
}
static int sumErrors(List<JpaGeneratedTestResult> values) {
return values.stream().mapToInt(JpaGeneratedTestResult::errorCount).sum();
}
static List<String> allTasks(List<JpaGeneratedTestResult> results) {
List<String> values = new ArrayList<>();
results.forEach(result -> values.addAll(result.tasks()));
return sortedDistinct(values);
}
static List<String> allResultDirectories(List<JpaGeneratedTestResult> results) {
List<String> values = new ArrayList<>();
results.forEach(result -> values.addAll(result.resultDirectories()));
return sortedDistinct(values);
}
}

Some files were not shown because too many files have changed in this diff Show More