package dev.caskeleton.buildlogic; import java.io.File; import java.io.IOException; import java.io.UncheckedIOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.util.ArrayList; import java.util.Collection; import java.util.List; /** Policy and rendering semantics for committed public Java API surfaces. */ public final class ApiSurfacePolicy { private ApiSurfacePolicy() {} public static String render( Collection roots, String label, String description, Collection rationale, String owningProjectPath, String updateTaskName, String approvalProperty) { List types; try { types = JavaPublicTypes.render(roots); } catch (IllegalStateException unparseable) { throw new IllegalStateException( owningProjectPath + " " + label + " API surface: " + unparseable.getMessage(), unparseable); } if (types.isEmpty()) { throw new IllegalStateException( owningProjectPath + ": found no public types under " + String.join(", ", roots.stream().map(File::toString).toList()) + ". The source roots moved; fix the paths rather than accepting an empty surface."); } StringBuilder header = new StringBuilder(); header.append("# ").append(description).append('\n'); if (rationale != null) { rationale.forEach(line -> header.append("# ").append(line).append('\n')); } header.append("# Update only after review with:\n"); header .append("# ./gradlew ") .append(owningProjectPath) .append(':') .append(updateTaskName) .append(" -P") .append(approvalProperty) .append('\n'); header.append("# types: ").append(types.size()).append('\n'); return header + String.join("\n", types) + "\n"; } public static void verify( String verifyTaskName, String updateTaskName, String owningProjectPath, String approvalProperty, File baseline, String rendered) { if (!baseline.isFile()) { throw new IllegalStateException( verifyTaskName + ": missing committed baseline " + baseline); } String committed = read(baseline); if (committed.equals(rendered)) { return; } List committedTypes = surfaceLines(committed); List renderedTypes = surfaceLines(rendered); List added = difference(renderedTypes, committedTypes); List removed = difference(committedTypes, renderedTypes); throw new IllegalStateException( verifyTaskName + ": the public API surface changed.\n" + (added.isEmpty() ? "" : " added:\n " + String.join("\n ", added) + "\n") + (removed.isEmpty() ? "" : " removed:\n " + String.join("\n ", removed) + "\n") + "Review the change, then record it with:\n" + " ./gradlew " + owningProjectPath + ":" + updateTaskName + " -P" + approvalProperty); } /** * Holds other leaves' imports of this surface to the reviewed adopter subset. * *

The surface says what is public; the adopter baseline says which of those public types other * leaves' production code may depend on. An import of a surface type the adopter baseline does not * list fails, and so does an adopter entry the surface no longer has. */ public static void verifyAdopters( String verifyTaskName, String rendered, File adopterBaseline, List adopterImports) { if (!adopterBaseline.isFile()) { throw new IllegalStateException( verifyTaskName + ": missing committed adopter baseline " + adopterBaseline); } java.util.Set surface = new java.util.HashSet<>(surfaceLines(rendered)); java.util.Set allowed = new java.util.TreeSet<>(); for (String line : read(adopterBaseline).lines().toList()) { if (!line.isBlank() && !line.startsWith("#")) { allowed.add(line.trim()); } } List stale = allowed.stream().filter(type -> !surface.contains(type)).toList(); List unreviewed = adopterImports.stream() .filter(entry -> { String type = entry.substring(entry.indexOf(": ") + 2); return surface.contains(type) && !allowed.contains(type); }) .toList(); if (stale.isEmpty() && unreviewed.isEmpty()) { return; } throw new IllegalStateException( verifyTaskName + ": the adopter surface (" + adopterBaseline.getName() + ") does not match what other leaves import.\n" + (unreviewed.isEmpty() ? "" : " imported but not in the adopter baseline:\n " + String.join("\n ", unreviewed) + "\n") + (stale.isEmpty() ? "" : " in the adopter baseline but not in the public surface:\n " + String.join("\n ", stale) + "\n") + "Add a reviewed type to the adopter baseline, or stop importing it."); } public static void requireNoUnapprovedGrowth( String updateTaskName, String owningProjectPath, String approvalProperty, String ceilingProperty, int committedCount, String rendered, boolean ceilingRaiseApproved) { if (ceilingRaiseApproved) { return; } int renderedCount = countTypes(rendered); if (renderedCount > committedCount) { throw new IllegalStateException( updateTaskName + ": the public surface would grow from " + committedCount + " to " + renderedCount + " types.\n" + "Approving additions one at a time is how this leaf got too big to split without anybody deciding to make it so.\n" + "Either land the addition together with a removal that pays for it, or raise the ceiling deliberately:\n" + " ./gradlew " + owningProjectPath + ":" + updateTaskName + " -P" + approvalProperty + " -P" + ceilingProperty); } } public static int countTypes(String surface) { return (int) surface.lines() .filter(line -> !line.startsWith("#") && !line.trim().isEmpty()) .count(); } private static List surfaceLines(String surface) { return surface.lines().filter(line -> !line.startsWith("#")).toList(); } private static List difference(List left, List right) { ArrayList result = new ArrayList<>(left); result.removeAll(right); result.sort(String::compareTo); return List.copyOf(result); } private static String read(File file) { try { return Files.readString(file.toPath(), StandardCharsets.UTF_8); } catch (IOException exception) { throw new UncheckedIOException("failed to read " + file, exception); } } }