Files
clean-architecture-backend-…/build-logic/src/main/java/dev/caskeleton/buildlogic/apisurface/ApiSurfacePlugin.java
T
DongHyeonka cbfa776270 build!: 시험 classpath·이미지 고정·카탈로그·API surface 입력을 정본대로 맞춘다
문제:
- ca.spring-library가 모든 spring leaf(30)의 testImplementation에
  spring-boot-starter-webmvc-test를 넣어, MockMvc를 쓰지 않는 23 leaf가 Tomcat을
  시험 classpath에 resolve하고 lock했다.
- container-images.properties 머리말은 「digest로 고정」이라는데 postgres-17·18이
  tag만이었다. 머리말은 「쓰는 lane만 다시 돈다」고 했지만 파일 전체가 모든 Test
  task의 입력이라 이미지 하나만 바꿔도 모든 lane이 다시 돈다. postgres-16-4는
  아무도 읽지 않았다.
- libs.versions.toml에 아무도 읽지 않는 칸이 있었다(라이브러리 9, 버전 4,
  루트에 적용하지 않는 플러그인 4).
- config/spotbugs/exclude.xml에 없는 클래스의 항목이 있었다(exclude-test.xml에
  이미 있다).
- notification의 API surface가 상대 경로로 application-notification 소스를
  가리켰고, ApiSurface 플러그인은 없는 추가 root를 말없이 건너뛰어 승인 update가
  줄어든 표면을 기록할 수 있었다.
- verify-mongodb-platform.sh가 고르는 클래스가 없는 :app-bootstrap:test
  --tests '*CleanArchitectureTest'를 불러 늘 실패했고, 이미지 기록이 카탈로그와
  다른 tag였다.

고친 것:
- 규약은 spring-boot-starter-test만 준다. 시험이 실제로 쓰는 것을 leaf가 직접
  선언한다. MockMvc를 쓰는 web·web-advanced·web-fileserver·web-notification·
  app-bootstrap은 webmvc-test starter, graphql은 TestRestTemplate의
  spring-boot-resttestclient, durable-operation은 WebApplicationContextRunner의
  spring-web, 시험이 JSON을 읽는 objectstorage·persistence-jpa·persistence-mongo·
  notification-platform은 jackson-databind, redis-runtime은 jackson-annotations
  (compileOnly, 본 코드와 같은 이유)다. 모든 Java source set을 한 빌드에서 컴파일해
  빠진 곳이 없음을 확인하고 lockfile을 다시 만들었다(Tomcat·webmvc 시험 자동설정이
  빠짐). graphql·persistence-mongo AGENTS의 허용·시험 목록을 같이 고쳤다.
- postgres 17·18을 desktop runner에서 받은 digest로 고정했다(17.11, 18.6). 목록을
  읽을 때 digest 없는 값을 GradleException으로 거절한다(ContainerImageCatalogTest).
  머리말을 실제 캐시 동작으로 고쳤고 postgres-16-4를 지웠다. persistence-jpa
  release registry의 PostgreSQL tag는 아무도 읽지 않아 지우고, 이미지는 카탈로그가
  정한다고 적었다.
- 카탈로그의 미사용 칸을 지우고 머리말을 지금 쓰임에 맞췄다.
- 죽은 spotbugs 항목을 지웠다.
- notification은 project(':application-notification')로 root를 잡고, 없는 추가
  root는 설정 단계에서 실패한다(ApiSurfaceConventionTest).
- mongo 스크립트는 :app-bootstrap:architectureTest를 부르고, 이미지 기록은
  카탈로그 mongo-8 값을 읽는다.
- graphql build.gradle에 앞 커밋의 document-contract lane을 함께 둔다. 저장소 루트
  (ca.repository.root)와 읽는 registry 파일은 그 lane만 받고, 시험은 그 속성으로만
  루트를 읽는다(cwd에서 거슬러 찾지 않는다).
버린 대안: 이미지마다 쓰는 lane을 선언해 입력을 나누기 — lane 수십 개에 키
목록을 다시 적어야 하고 빠뜨리면 캐시가 거짓 통과한다.

검증: 아래 PR 본문(desktop resolveAndLockAll·build-logic test·모든 source set 컴파일·
leaf check).

BREAKING CHANGE: ca.spring-library가 시험 classpath에 spring-boot-starter-webmvc-test를
넣지 않는다. MockMvc·TestRestTemplate·Jackson을 그 starter로 받던 파생 leaf는 의존을
직접 선언해야 시험이 컴파일된다. 카탈로그의 digest 없는 이미지와 없는 API surface 추가
root는 설정 단계에서 실패한다. version catalog의 미사용 칸을 지웠다. 할 일은
docs/upgrade/2026-11-round9-build.md다.

Refs: RR9-04-06, RR9-04-11, RR9-04-12, RR9-04-13, RR9-04-14, RR9-04-15, RR9-04-16
2026-11-13 06:34:32 +09:00

124 lines
5.7 KiB
Java

package dev.caskeleton.buildlogic.apisurface;
import dev.caskeleton.buildlogic.ApiSurfaceExtension;
import java.io.File;
import java.util.ArrayList;
import java.util.List;
import org.gradle.api.GradleException;
import org.gradle.api.Plugin;
import org.gradle.api.Project;
public final class ApiSurfacePlugin implements Plugin<Project> {
@Override
public void apply(Project project) {
ApiSurfaceExtension extension =
project.getExtensions().create("apiSurface", ApiSurfaceExtension.class);
project.afterEvaluate(
ignored -> {
String label = extension.getLabel();
File baseline = extension.getBaseline();
if ((label == null || label.isBlank()) && baseline == null) {
return;
}
if (label == null || label.isBlank()) {
throw new GradleException(
project.getPath() + " declares an apiSurface baseline without a label");
}
if (baseline == null) {
throw new GradleException(
project.getPath() + " declares an apiSurface label without a baseline");
}
List<String> sourcePaths = new ArrayList<>();
if (extension.getSourceRoot() != null && !extension.getSourceRoot().isBlank()) {
sourcePaths.add(extension.getSourceRoot());
}
List<File> additional =
extension.getAdditionalSourceRoots().stream()
.filter(path -> path != null && !path.isBlank())
.map(project::file)
.toList();
// A missing additional root used to be skipped without a word, so an approved update
// recorded a surface with a whole module's types gone (2026-11-12 review).
List<File> missing = additional.stream().filter(root -> !root.isDirectory()).toList();
if (!missing.isEmpty()) {
throw new GradleException(
project.getPath()
+ " apiSurface.additionalSourceRoots names a folder that does not exist: "
+ missing);
}
List<File> roots = new ArrayList<>(sourcePaths.stream().map(project::file).toList());
roots.addAll(additional);
String verifyTaskName = "verify" + label + "ApiSurface";
String updateTaskName = "update" + label + "ApiSurface";
String approvalProperty = "approve" + label + "ApiSurfaceChange";
String ceilingProperty = "raise" + label + "ApiSurfaceCeiling";
boolean approved = project.hasProperty(approvalProperty);
boolean ceilingApproved = project.hasProperty(ceilingProperty);
var verify =
project
.getTasks()
.register(
verifyTaskName,
VerifyApiSurfaceTask.class,
task -> {
task.setGroup("verification");
task.setDescription(
"Fails without mutation when the committed "
+ label
+ " public API surface drifts.");
task.getSourceRoots().from(roots);
task.getBaseline().fileValue(baseline);
task.getLabel().set(label);
task.getSurfaceDescription()
.set(extension.getDescription() == null ? "" : extension.getDescription());
task.getRationale().set(extension.getRationale());
task.getOwningProjectPath().set(project.getPath());
task.getUpdateTaskName().set(updateTaskName);
task.getApprovalProperty().set(approvalProperty);
task.getUpdateApproved().set(approved);
if (extension.getAdopterBaseline() != null) {
task.getAdopterBaseline().fileValue(extension.getAdopterBaseline());
if (extension.getAdopterSources() != null) {
task.getAdopterSources().from(extension.getAdopterSources());
}
}
});
project
.getTasks()
.register(
updateTaskName,
UpdateApiSurfaceTask.class,
task -> {
task.setGroup("verification");
task.setDescription(
"Rewrites the committed "
+ label
+ " public API surface baseline after review.");
task.getSourceRoots().from(roots);
task.getBaseline().fileValue(baseline);
task.getLabel().set(label);
task.getSurfaceDescription()
.set(extension.getDescription() == null ? "" : extension.getDescription());
task.getRationale().set(extension.getRationale());
task.getOwningProjectPath().set(project.getPath());
task.getApprovalProperty().set(approvalProperty);
task.getCeilingProperty().set(ceilingProperty);
task.getApproved().set(approved);
task.getCeilingRaiseApproved().set(ceilingApproved);
});
// The leaf's `check`, so a pull request that changes a public type fails there (owner
// decision 20, 2026-09-25). It used to run only in `mainCheck`, which reported the change
// after it had merged.
project
.getTasks()
.matching(task -> task.getName().equals("check"))
.configureEach(task -> task.dependsOn(verify));
});
}
}