refactor(layout)!: Gradle 루트와 계층 폴더를 옮긴다(옮기기만)

문제: Gradle 루트가 src/라서 빌드 도구(build-logic, gradle, config, 빌드
파일)가 계층 코드 폴더 옆에 섞여 있다. composition과 app-bootstrap은 같은
조립 계층인데 폴더가 따로이고, application 모듈 넷은 최상위에 흩어져 있다.
「Gradle은 src/에서 실행」이라는 예외 규칙이 모든 문서와 스크립트에 퍼졌다.

고른 방법: 저장소 루트를 Gradle 루트로 하고 src/에는 계층 코드만 둔다
(design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3, 소유자
승인 2026-11-07). 이 커밋은 git mv만 한다. 이름 바꾸기 감지가 1541개
파일 모두를 R100으로 잡도록 내용을 바꾸지 않았다. 바뀐 곳은 둘뿐이다:
src/.gitignore의 줄을 루트 .gitignore로 옮겼다.

- 빌드 파일, gradle/, build-logic/ → 저장소 루트
- config/checkstyle·spotbugs → config/ (코드 검사 도구 설정만)
- registry config/architecture/modules.json → gradle/modules.json,
  시험 이미지 config/testing/container-images.properties
  → gradle/container-images.properties, registry 설명 → gradle/README.md
- Dockerfile, .dockerignore, .env*.example → 저장소 루트
- src/README.md(빌드·env 참조) → docs/build.md
- src/domain-core → src/domain/core,
  src/application-* → src/application/*,
  src/app-bootstrap → src/bootstrap/app,
  src/composition/* → src/bootstrap/*
- 기능 생성 템플릿 scripts/feature-scaffold/{templates,probes}/src/ 아래도
  같은 모양으로(domain/core, application/core, bootstrap/app)

위험: 이 커밋만으로는 빌드되지 않는다. 경로를 부르는 곳은 다음 커밋이
고친다. 두 커밋을 나눈 것은 파생 서비스가 merge할 때 이름 바꾸기와 내용
변경을 따로 보게 하려는 것이다.

검증: git diff --cached -M --name-status 에서 R100 1541개, 그 밖은
.gitignore 수정과 src/.gitignore 삭제뿐.

BREAKING CHANGE: 모든 빌드 파일과 계층 폴더의 경로가 바뀐다. 옛 경로 →
새 경로 표와 받는 순서는 docs/upgrade/2026-11-relayout.md에 있다.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절
This commit is contained in:
DongHyeonka
2026-11-11 21:04:21 +09:00
parent 66eaa98202
commit 1388c06a9f
1543 changed files with 16 additions and 22 deletions
@@ -0,0 +1,429 @@
package dev.caskeleton.buildlogic.config;
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.HashSet;
import java.util.List;
import java.util.Optional;
import java.util.Set;
import java.util.TreeSet;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/** Repository policy for the operator-facing environment contract. No Gradle API. */
public final class EnvContractVerifier {
private static final Pattern ENV_LINE = Pattern.compile("^([A-Z][A-Z0-9_]*)=.*");
private static final Pattern PLACEHOLDER =
Pattern.compile("\\$\\{([A-Z][A-Z0-9_]*)(:[^}]*)?}");
private static final Pattern SECRET_REFERENCE =
Pattern.compile("secret://environment/(APP_[A-Z][A-Z0-9_]*)");
private static final Pattern REGISTRY_NAME =
Pattern.compile("^\\s*- name: (APP_[A-Z0-9_]+)");
private static final Pattern REGISTRY_FIELD =
Pattern.compile("^\\s*([a-z_]+):\\s*(\\S.*)?$");
private static final Pattern APP_KEY = Pattern.compile("APP_[A-Z][A-Z0-9_]*");
/** A variable a Compose service sets: an {@code APP_*} key of an {@code environment:} map. */
private static final Pattern COMPOSE_ENVIRONMENT_KEY =
Pattern.compile("(?m)^\\s+(APP_[A-Z][A-Z0-9_]*):");
/** A variable Logback reads directly: {@code <springProperty source="APP_*">}. */
private static final Pattern LOGBACK_SOURCE =
Pattern.compile("source=\"(APP_[A-Z][A-Z0-9_]*)\"");
/**
* A variable a JSON object sets: the {@code activationEnv} maps of the Compose lane contract, and
* the smoke wrapper's {@code CAPABILITIES_OFF} literal. An {@code "APP_X=value"} string (an
* argument the wrapper passes on) is not a key and is not matched.
*/
private static final Pattern JSON_KEY = Pattern.compile("\"(APP_[A-Z][A-Z0-9_]*)\"\\s*:");
/** Every variable a JSON object sets, {@code APP_} or not. */
private static final Pattern JSON_VARIABLE_KEY = Pattern.compile("\"([A-Z][A-Z0-9_]*)\"\\s*:");
/** The variable a credential reference names: the last segment of {@code secret://…/<VAR>}. */
private static final Pattern REFERENCED_VARIABLE =
Pattern.compile("secret://[^\\s\"']*/([A-Z][A-Z0-9_]*)");
/**
* Spring Boot's own namespaces: a variable under one is bound to its {@code spring.*}, {@code
* management.*} or {@code server.*} property by relaxed binding, so the framework reads it.
*/
private static final List<String> FRAMEWORK_VARIABLE_PREFIXES =
List.of("SPRING_", "MANAGEMENT_", "SERVER_");
/**
* A list element ({@code APP_HTTPCLIENT_CLIENTS_0_NAME}). Its field template is registered by the
* owning module's field registry ({@code docs/httpclient/env-fields.yaml}, held by that module's
* manifest test and strict binder), not as a row here.
*/
private static final Pattern INDEXED_KEY = Pattern.compile(".*_[0-9]+(_.*)?");
private EnvContractVerifier() {}
/**
* Verifies the contract, and also every {@code APP_*} name the operator-facing files set.
*
* <p>Operator files are what an operator edits or runs to supply values — the root Compose files
* that run the application, {@code logback-spring.xml}, the Compose lane contract and the smoke
* wrapper that drives it. A Compose file contributes the keys of its {@code environment:} maps,
* Logback its {@code springProperty} sources, a JSON file or a shell script the keys of its JSON
* objects (review 2026-11-03 RR-06-07). A name there must be registered, and something must read it:
* a shipped-configuration placeholder, a production source, or a typed property. A variable set
* in a Compose file that nothing reads is a setting the operator believes is in force and is not
* ({@code APP_LOG_JSON_ENABLED} in the prod-smoke file, 07-10).
*
* <p>An operator-file key whose registry row names a {@code property:} counts as read only when
* that property is declared — a registry row alone is what the operator file was already trusted
* for (review 2026-11-04 RR2-04-05). A non-{@code APP_} key of a JSON object counts as read only
* under a Spring Boot namespace or as the variable a {@code secret://…/<VAR>} reference names:
* the {@code CASKELETON_GRPC_ENABLED} switch that started RR-06-07 was neither, and nothing read
* it.
*
* <p>The typed properties under {@code typedPrefixes} and the declared properties an operator key
* may name are read once, from the same classpath, by {@link ConfigurationMetadataClasspath}. They
* used to be two computations — the task read the classpath, the tests a scope file — so the unit
* tests did not see the path the build runs (review 2026-11-04 RR3-04-04).
*
* @param metadataClasspath the composition's classpath with every capability a service can
* select, whose configuration metadata declares the properties
* @param typedPrefixes the property trees whose every typed property needs a registry row
* @param enforcedPrefixes the {@code APP_*} prefixes whose every registered key must be read
* @param operatorFiles the operator-facing files whose {@code APP_*} names are checked
*/
public static EnvContractResult verify(
File envFile,
Collection<File> configurationFiles,
File registryFile,
Collection<File> productionSources,
Collection<File> metadataClasspath,
Collection<String> typedPrefixes,
Collection<String> enforcedPrefixes,
Collection<File> operatorFiles) {
requireFile(
envFile,
"missing "
+ envFile
+ ". The tracked example is the contract an adopter copies; a real .env is operator "
+ "input and is never read here.");
if (configurationFiles.isEmpty()) {
throw new IllegalStateException(
"verifyEnvKeys: no shipped configuration files were supplied for verification");
}
for (File configurationFile : configurationFiles) {
requireFile(configurationFile, "missing shipped configuration " + configurationFile);
}
requireFile(registryFile, "missing " + registryFile);
Set<String> envKeys = new TreeSet<>();
for (String line : readLines(envFile)) {
Matcher matcher = ENV_LINE.matcher(line);
if (matcher.matches()) {
envKeys.add(matcher.group(1));
}
}
Set<String> requiredPlaceholders = new TreeSet<>();
Set<String> allPlaceholders = new TreeSet<>();
Set<String> environmentSecretReferences = new TreeSet<>();
for (File configurationFile : configurationFiles) {
String configuration = read(configurationFile);
Matcher placeholderMatcher = PLACEHOLDER.matcher(configuration);
while (placeholderMatcher.find()) {
allPlaceholders.add(placeholderMatcher.group(1));
if (placeholderMatcher.group(2) == null) {
requiredPlaceholders.add(placeholderMatcher.group(1));
}
}
Matcher secretMatcher = SECRET_REFERENCE.matcher(configuration);
while (secretMatcher.find()) {
environmentSecretReferences.add(secretMatcher.group(1));
}
}
Set<String> applicationAppReferences = new TreeSet<>();
allPlaceholders.stream()
.filter(name -> name.startsWith("APP_"))
.forEach(applicationAppReferences::add);
applicationAppReferences.addAll(environmentSecretReferences);
failUnlessEmpty(
difference(requiredPlaceholders, envKeys),
"shipped configuration references required env absent from src/.env.example: ");
List<EnvRegistryRow> registryRows = parseRegistryRows(registryFile);
Set<String> registryAppKeys = new TreeSet<>();
Set<String> registryProperties = new TreeSet<>();
for (EnvRegistryRow row : registryRows) {
registryAppKeys.add(row.name());
row.property().ifPresent(registryProperties::add);
}
failUnlessEmpty(
difference(registryAppKeys, envKeys),
"docs/registries/env-keys.yaml registers APP_ keys absent from src/.env.example, so an "
+ "adopter copying the example never sees them: ");
Set<String> envAppKeys = new TreeSet<>();
envKeys.stream().filter(name -> name.startsWith("APP_")).forEach(envAppKeys::add);
failUnlessEmpty(
difference(envAppKeys, registryAppKeys),
"src/.env.example declares APP_ keys absent from docs/registries/env-keys.yaml "
+ "(registry is the SSOT for APP_ keys): ");
failUnlessEmpty(
difference(applicationAppReferences, registryAppKeys),
"shipped configuration references APP_ keys absent from docs/registries/env-keys.yaml "
+ "(optional defaults and environment secret references are included): ");
Set<String> declared = ConfigurationMetadataClasspath.propertiesUnder(metadataClasspath, "");
Set<String> typedProperties = new TreeSet<>();
Set<String> undeclaredPrefixes = new TreeSet<>();
for (String prefix : typedPrefixes) {
List<String> underPrefix = declared.stream().filter(name -> name.startsWith(prefix)).toList();
if (underPrefix.isEmpty()) {
undeclaredPrefixes.add(prefix);
}
typedProperties.addAll(underPrefix);
}
if (!undeclaredPrefixes.isEmpty()) {
throw new IllegalStateException(
"verifyEnvKeys: no configuration metadata on the classpath declares a property under "
+ undeclaredPrefixes
+ " — put the owning module on the metadata classpath and run its compileJava (the"
+ " annotation processor writes the metadata), or the typed-property check silently"
+ " covers nothing.");
}
failUnlessEmpty(
difference(typedProperties, registryProperties),
"typed configuration properties absent from docs/registries/env-keys.yaml: ",
" — every bindable property needs a registry row carrying its official env name, type, "
+ "default, secret classification and required_when.");
Set<String> scopedRegistryProperties = new TreeSet<>();
for (String property : registryProperties) {
if (typedPrefixes.stream().anyMatch(property::startsWith)) {
scopedRegistryProperties.add(property);
}
}
failUnlessEmpty(
difference(scopedRegistryProperties, typedProperties),
"docs/registries/env-keys.yaml declares properties that no typed settings class binds any more: ",
" — remove the row or restore the property.");
Set<String> consumed = new TreeSet<>(applicationAppReferences);
consumed.addAll(scanProductionSourceConsumers(productionSources));
Set<String> operatorReferences = new TreeSet<>();
Set<String> unreadOperatorVariables = new TreeSet<>();
for (File operatorFile : operatorFiles) {
requireFile(operatorFile, "missing operator file " + operatorFile);
String content = read(operatorFile);
Matcher matcher = operatorKeyPattern(operatorFile.getName()).matcher(content);
while (matcher.find()) {
if (!INDEXED_KEY.matcher(matcher.group(1)).matches()) {
operatorReferences.add(matcher.group(1));
}
}
if (operatorKeyPattern(operatorFile.getName()) == JSON_KEY) {
unreadOperatorVariables.addAll(unreadNonApplicationVariables(content));
}
}
failUnlessEmpty(
difference(operatorReferences, registryAppKeys),
"operator files (Compose, logback-spring.xml, the Compose lane contract, the smoke wrapper)"
+ " set APP_ keys absent from docs/registries/env-keys.yaml: ");
Set<String> typedRows = new TreeSet<>();
registryRows.stream()
.filter(row -> row.property().filter(declared::contains).isPresent())
.forEach(row -> typedRows.add(row.name()));
Set<String> unreadOperatorReferences = new TreeSet<>();
for (String name : operatorReferences) {
if (!consumed.contains(name) && !typedRows.contains(name)) {
unreadOperatorReferences.add(name);
}
}
failUnlessEmpty(
unreadOperatorReferences,
"operator files (Compose, logback-spring.xml, the Compose lane contract, the smoke"
+ " wrapper) set APP_ keys nothing reads — no shipped configuration placeholder,"
+ " production source or typed property: ");
failUnlessEmpty(
unreadOperatorVariables,
"the Compose lane contract or the smoke wrapper sets variables outside APP_ that nothing"
+ " reads — not a Spring Boot namespace (SPRING_, MANAGEMENT_, SERVER_) and not named"
+ " by a secret://…/<VAR> reference: ",
" — a switch spelled this way changes nothing, and the lane can pass for another reason.");
Set<String> unconsumed = new TreeSet<>();
for (EnvRegistryRow row : registryRows) {
if (!consumed.contains(row.name()) && row.property().isEmpty() && !row.deprecatedOrphaned()) {
unconsumed.add(row.name());
}
}
Set<String> unconsumedOwned = new TreeSet<>();
for (String name : unconsumed) {
if (enforcedPrefixes.stream().anyMatch(name::startsWith)) {
unconsumedOwned.add(name);
}
}
if (!unconsumedOwned.isEmpty()) {
throw new IllegalStateException(
"verifyEnvKeys: registered Redis keys that nothing reads — no typed property, no "
+ "shipped-configuration reference, no production consumer, and not marked "
+ "deprecated_orphaned: "
+ unconsumedOwned
+ ". Wire the key to a consumer, or mark the row deprecated_orphaned with a "
+ "removal_deadline so a deployment still setting it is told rather than silently ignored.");
}
Set<String> unconsumedElsewhere = difference(unconsumed, unconsumedOwned);
List<String> warnings = new ArrayList<>();
if (!unconsumedElsewhere.isEmpty()) {
warnings.add(
"registered keys outside the Redis surface that nothing reads yet: "
+ unconsumedElsewhere
+ " — owned by the branch that registered them.");
}
return new EnvContractResult(
envKeys.size(),
requiredPlaceholders.size(),
applicationAppReferences.size(),
typedProperties.size(),
registryRows.size() - unconsumed.size(),
warnings);
}
/**
* The non-{@code APP_} variables a JSON object in {@code content} sets that nothing reads: outside
* Spring Boot's namespaces and named by no {@code secret://} reference in the same file.
*/
private static Set<String> unreadNonApplicationVariables(String content) {
Set<String> referenced = new TreeSet<>();
Matcher reference = REFERENCED_VARIABLE.matcher(content);
while (reference.find()) {
referenced.add(reference.group(1));
}
Set<String> unread = new TreeSet<>();
Matcher variable = JSON_VARIABLE_KEY.matcher(content);
while (variable.find()) {
String name = variable.group(1);
if (!name.startsWith("APP_")
&& FRAMEWORK_VARIABLE_PREFIXES.stream().noneMatch(name::startsWith)
&& !referenced.contains(name)) {
unread.add(name);
}
}
return unread;
}
private static Pattern operatorKeyPattern(String fileName) {
if (fileName.endsWith(".xml")) {
return LOGBACK_SOURCE;
}
if (fileName.endsWith(".json") || fileName.endsWith(".sh")) {
return JSON_KEY;
}
return COMPOSE_ENVIRONMENT_KEY;
}
private static List<EnvRegistryRow> parseRegistryRows(File registryFile) {
List<EnvRegistryRow> rows = new ArrayList<>();
RowBuilder current = null;
for (String line : readLines(registryFile)) {
Matcher nameMatcher = REGISTRY_NAME.matcher(line);
if (nameMatcher.find()) {
if (current != null) {
rows.add(current.build());
}
current = new RowBuilder(nameMatcher.group(1));
continue;
}
if (current == null) {
continue;
}
Matcher fieldMatcher = REGISTRY_FIELD.matcher(line);
if (!fieldMatcher.find()) {
continue;
}
String key = fieldMatcher.group(1);
String value = fieldMatcher.group(2) == null ? "" : fieldMatcher.group(2).trim();
if (key.equals("property")) {
current.property = value;
} else if (key.equals("deprecated_orphaned")) {
current.deprecatedOrphaned = Boolean.parseBoolean(value);
}
}
if (current != null) {
rows.add(current.build());
}
return List.copyOf(rows);
}
private static Set<String> scanProductionSourceConsumers(Collection<File> productionSources) {
Set<String> consumed = new TreeSet<>();
for (File source : productionSources) {
if (!source.isFile()) {
continue;
}
Matcher matcher = APP_KEY.matcher(read(source));
while (matcher.find()) {
consumed.add(matcher.group());
}
}
return consumed;
}
private static void requireFile(File file, String message) {
if (!file.exists()) {
throw new IllegalStateException("verifyEnvKeys: " + message);
}
}
private static void failUnlessEmpty(
Collection<String> values, String prefix) {
failUnlessEmpty(values, prefix, "");
}
private static void failUnlessEmpty(
Collection<String> values, String prefix, String suffix) {
if (!values.isEmpty()) {
throw new IllegalStateException("verifyEnvKeys: " + prefix + values + suffix);
}
}
private static Set<String> difference(Collection<String> left, Collection<String> right) {
Set<String> result = new TreeSet<>(left);
result.removeAll(new HashSet<>(right));
return 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);
}
}
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);
}
}
private static final class RowBuilder {
private final String name;
private String property;
private boolean deprecatedOrphaned;
private RowBuilder(String name) {
this.name = name;
}
private EnvRegistryRow build() {
return new EnvRegistryRow(name, Optional.ofNullable(property), deprecatedOrphaned);
}
}
}