refactor: 리펙토링 진행중 의존성 gradle은 얇게 유지, 각 모듈에서 처리하고 있는 부분에 대해서 리펙토링

This commit is contained in:
donghyeon-ka
2026-09-24 11:15:10 +09:00
parent 9da00eb782
commit 208077fddf
438 changed files with 5815 additions and 1528 deletions
@@ -0,0 +1,272 @@
# App Bootstrap Build Composition — implementation plan
Design authority: the 2026-09-23 "App Bootstrap Build Composition 설계 작업 문서".
Review authority: `docs/reviews/2026-09-18-techlead-review/` §00, §12, §13 and
`docs/reviews/2026-09-23-techlead-review-application-closure.md`.
This plan is the §17 deliverable. It settles the three decisions the design document deliberately
left open — what "selection" *is* mechanically, where the contract is enforced, and what a
composition module is allowed to be — and then splits the work into the task units §17 names. It
does not restate the design.
## 0. Measured baseline
Re-measured on the current tree rather than quoted (design §15 forbids reusing an old log).
The design document's named gate is green:
./gradlew verifyCleanArchitectureDependencies :adapter:outbound:persistence-jpa:test \
:app-bootstrap:test :app-bootstrap:architectureTest --continue # exit 0, 0 FAILED
`:app-bootstrap:runtimeClasspath` resolves **33 project edges**. Every optional capability is among
them, including the three the earlier pass lowered to `runtimeOnly`:
graphql httpclient persistence-mongo <- runtimeOnly, still on the classpath
fileserver notification cache-redis redis-runtime
messaging-spring-boot-starter + 16 further messaging leaves
This is the design document's §2.3 claim, confirmed: `runtimeOnly` moved these off the *compile*
classpath and left them in the artifact. Nothing about the shipped jar changed.
## 1. Decision — selection is a Gradle edge, and the repository already has one
The design document asks for a mechanism without naming one. It does not need a new one: **object
storage is already in the target state**, and `docs/capability-status.md` already documents it that
way — WIRED **no**, "The leaf is not an `app-bootstrap` dependency … A fork that wants it adds the
edge", with `integrationTestImplementation project(':adapter:outbound:objectstorage')` supplying it
to the lane that proves it assembles.
So the work is not to invent Build Composition. It is to move the other capabilities to the shape
one capability already has.
**Selection = the presence of a project dependency in `app-bootstrap/build.gradle`.** Not a Gradle
property, not a feature variant, not a capability DSL. Reasons, in the order design §9 ranks them:
- it is the existing Gradle model, and it is already how object storage works;
- a property would make the shipped artifact depend on how the build was invoked, so two builds of
the same commit could ship different jars — the opposite of what a composition contract is for;
- the thing a fork edits is one line in one file, which is what a template should ask of an adopter.
Rejected alternative, recorded because it is the obvious one: `-PcaCapabilities=fileserver,...`. It
reads well and it is worse — it moves the answer to "does this build ship Fileserver?" out of the
repository and into the invocation, and no test can pin an invocation.
## 2. Decision — the contract is enforced by the verifier that already exists
Design §7.1 requires a RED test proving an unselected capability is absent from
`runtimeClasspath`, and design §9 forbids adding a bespoke verifier for it.
Both are satisfiable at once. `ca.dependency-policy` already resolves a named configuration and
fails on forbidden or missing coordinates (`dependencyPolicy { absent … required … }`,
`VerifyDependencyPolicyTask`, wired into `check`). A project dependency resolves to a real
`ModuleVersionIdentifier` — `dev.caskeleton:<project name>` — so an absence on `runtimeClasspath` is
expressible today, with no new task, no new source set and no string scanning.
// app-bootstrap/build.gradle
dependencyPolicy {
absent 'dev.caskeleton:fileserver',
'Fileserver is an optional capability; the minimal composition does not ship it.'
}
That is the Phase 1 RED: it fails on the current tree, because the edge is there.
Two things this deliberately does **not** replace:
- the Runtime Activation tests. Design §3.1 is the whole point — `absent` answers "is it in the
artifact", the existing OFF-state guards answer "is it assembled". Neither is evidence for the
other, and the plan keeps them in different files so they cannot be confused.
- the boot artifact evidence design §7.5 asks for. `runtimeClasspath` is what `bootJar` packages, so
the two agree by construction — but "by construction" is an argument, not a measurement. One
`bootJar` content assertion is added once, in Step 7, as a check *of the argument*, not per
capability.
## 3. Decision — what a composition module may contain
A `composition:<capability>` module exists only when a capability genuinely spans adapters that must
not depend on each other. It contains cross-adapter wiring and nothing else: no business rule, no
transport surface, no settings that a single leaf could own. If a capability turns out to be
self-contained after the leaf-ownership pass, **no composition module is created for it** — the leaf
is selected directly, exactly as object storage is.
This matters because the fileserver work in the 2026-09-23 closure §3-B.5 already found that the
package which looked like one cross-adapter assembly was two assemblies merged. The same question is
asked before each composition module is created, not after.
Registry: each new module gets a `modules.json` entry with explicit `allowed_dependencies`.
`settings.gradle` includes registered projects automatically, so registration *is* inclusion. A
composition module is **not** a composition root: it composes a capability, it does not run.
## 4. Task units
Ordered. A unit is done when its own focused command is green; no unit starts before the previous
one is.
| # | Unit | Done when |
| --- | --- | --- |
| 1 | Fileserver Build Composition RED test | `:app-bootstrap:verifyDependencyPolicy` fails naming `dev.caskeleton:fileserver`, and the failure text is the contract |
| 2 | Fileserver composition extraction | the 4 cross-adapter configurations left in bootstrap by closure §3-B.5 move to `composition:fileserver`; bootstrap's fileserver edges are gone; unit 1 is green |
| 3 | Fileserver ON/OFF regression | OFF-state and ON-state tests unchanged in meaning and green, from the source set that selects the composition |
| 4 | Notification composition extraction | same shape, same three units collapsed into one because the pattern is proven |
| 5 | Persistence/JPA ownership review | per-file verdict against design §11 Q1–Q4, recorded; only files that answer Q1 or Q2 move |
| 6 | Messaging / Redis residual ownership | broker selection becomes a build edge; Redis keeps only the two application-wide files closure §3-B.5 already justified |
| 7 | Mongo / HTTP client / GraphQL actual optionalization | `runtimeOnly` → absent; one `bootJar` assertion proves the classpath argument |
| 8 | Minimal + full composition certification | minimal = `:app-bootstrap` main; full = the app-bootstrap `systemTest` source set selecting every capability. No new application module unless a source set proves insufficient |
| 9 | Registry / docs / comment alignment | `modules.json`, `capability-status.md` WIRED column, and the "shipped so an operator can enable it" comments in `app-bootstrap/build.gradle` all say the same thing |
| 10 | Focused → repository-wide gates | design §15 command, then `ci`, dependency locks, public-path snapshot, optional-platforms |
Unit 8 uses a source set rather than a new module because `app-bootstrap:integrationTest` already
does exactly this for object storage. Design §6.2 warns against forcing `sample-portfolio` to carry
every capability, and this avoids it without adding a module.
## 5. What this plan does not do
Taken from design §10, repeated here because a plan that omits them invites them:
- no mechanical removal of every `dev.caskeleton.adapter.*` import; ownership is argued per file
- no new platform layer, no new build DSL, no per-capability verifier
- no change to provider behaviour, no feature work, no unrelated test cleanup
- no staging, commit or push — repository policy is `human-only`
- no working-tree cleanup; the tree carries 36 tracked deletions and 54 untracked additions from the
previous pass, and closure §5 records how they must be committed
## 6. Regression guard
Design §14's list is the non-negotiable set. Each unit's focused command includes whichever of these
it can break:
JPA boundary gate :adapter:outbound:persistence-jpa:test
Redis composition unit isolation :adapter:outbound:cache-redis:test
app-bootstrap architecture test :app-bootstrap:architectureTest
runtime activation OFF guards :app-bootstrap:test, :app-bootstrap:systemTest
configuration cache ci/integrationCheck/releaseCheck --dry-run --configuration-cache
gRPC operation-ledger CI caller -p optional-platforms integrationCheck
Leaf ownership already moved for Redis and Fileserver (closure §3-B.5) is a floor, not a starting
point: this work extends it and must not walk it back.
## 7. Progress — units 1 and 2
### Unit 1 is done
`app-bootstrap/build.gradle` declares the contract as a `dependencyPolicy` absence on
`runtimeClasspath`. It was checked for vacuity before it was trusted: a temporary `required` on the
same coordinate passed, which is what proves `dev.caskeleton:fileserver` is the shape a project
dependency actually resolves to. Without that probe an `absent` rule with a misspelled coordinate
would have been green from the first day and meant nothing.
### Unit 2 is done except for one measured blocker
Moved, in this order, because each step unblocked the next:
1. **`RuntimeProfileSnapshot` → `adapter:outbound:support`.** It was the real coupling. A capability
configuration that has a production-only rule had to ask app-bootstrap what the profile was, so
the configuration could not leave app-bootstrap. BOOT-002 said "one composition-root owner"; it
now says one owner for the repository, which is strictly stronger and is what lets a composition
module ask the question at all.
2. **`composition:fileserver-platform` created and registered.** Named for the capability rather
than the directory: `:composition:fileserver` resolves to `dev.caskeleton:fileserver`, the same
coordinate as `adapter:outbound:fileserver`, and Gradle silently substituted the module for
itself. The messaging family already prefixes its leaves for this reason.
3. **The 13 cross-adapter configurations moved**, with the auto-configuration and management-context
registration files that name them. `StartupFailures` became
`CapabilityStartupValidationException`, the same seam the Redis and Fileserver leaf moves used.
4. **app-bootstrap's fileserver edges removed**; the lanes that verify the capability select it.
5. **BOOT-007 moved to the module it governs**, with `allowEmptyShould(false)`. Left where it was it
would have analysed an empty package and passed for having nothing to check — and BOOT-012 caught
the rule leaving the pinned set, which is that guard working rather than an obstacle.
Result: `adapter:outbound:fileserver` is off the minimal runtime classpath. Project edges on
`:app-bootstrap:runtimeClasspath` went from 33 to 32.
**The blocker, measured rather than estimated.** `application-fileserver` is still there, and not
through the composition. It arrives through three leaves every application needs, because the
capability's code is inside them:
| leaf | fileserver files |
| --- | --- |
| `adapter:inbound:web` (`web.fileserver.*`) | 62 |
| `adapter:outbound:persistence-jpa` (`persistence.fileserver.*`) | 25 |
| `adapter:outbound:identifier` | 1 |
So Fileserver was never only "assembled by the composition root". It is embedded in required leaves,
and no composition module can express selecting it out until those 88 files move to leaves of their
own. The coupling was measured and is one-directional and small — `web.fileserver` reaches
`web.{core, observability, auth}` nine times, and exactly one non-fileserver web class
(`WebModuleBoundary`) reaches back — so the split is tractable. It is unit 2b, and it is the next
thing to do.
The contract line stays RED. Softening it to make the gate green would record the opposite of what
was measured, and design §7.1 asks for this test to be RED before the structure changes, not after
it is convenient.
### Verification at this point
./gradlew verifyCleanArchitectureDependencies :adapter:outbound:persistence-jpa:test \
:app-bootstrap:test :app-bootstrap:architectureTest \
:composition:fileserver-platform:check :adapter:outbound:support:test --continue # green
./gradlew ci --continue # 1,276 tasks, exactly one failure:
# :app-bootstrap:verifyDependencyPolicy, the intended RED
One failing task out of 1,276, and it is the one this unit deliberately left failing. Nothing else
in the repository regressed.
## 8. Unit 2 is complete — the Fileserver vertical slice
The blocker recorded above was right about the cause and wrong about the size. `application-fileserver`
arrived through three required leaves, and all three turned out to be clean extractions:
| Extracted | Into | Why it was clean |
| --- | --- | --- |
| 1 file — the upload identifier factory | `adapter:outbound:fileserver` | It implements one Fileserver port and nothing else. One class is why every application that needed an identifier also resolved the Fileserver use cases. |
| 25 files + 4 migrations | `adapter:outbound:persistence-fileserver` (new leaf) | The package imported `application.fileserver`, JPA, Hibernate, Spring Data and JDBC — and not one type from any other `persistence.*` package. No seam was needed. |
| 62 files | `adapter:inbound:web-fileserver` (new leaf) | `web.fileserver` imports `web.{core, auth, observability}` nine times; exactly one non-fileserver class referenced it back, and only in a javadoc sentence. |
The web platform's module map did **not** move. `WebStableModule` still declares the twelve fileserver
modules and their edges, and `WebBuildModel.platformSourceRoots()` now returns two roots — which is
what that method's plural has meant since it was written. A second copy of the map in the second leaf
would have been a second answer to "is this edge declared", and the map is the one thing a platform
must not have two of.
Result: `:app-bootstrap:runtimeClasspath` went from **33 project edges to 31**, and the contract now
names the whole capability rather than the part that was easy to remove:
absent 'dev.caskeleton:fileserver'
absent 'dev.caskeleton:application-fileserver'
absent 'dev.caskeleton:web-fileserver'
absent 'dev.caskeleton:persistence-fileserver'
### What the repository's own guards caught
Every move was stopped first by a guard already in the tree, and every one was the same shape — a
rule still pointing at something that had moved:
- `JpaModuleBoundaryTest`: *"a rule about a package that does not exist passes by finding nothing"*
- `ArchRuleDiscoveryContractTest` (BOOT-012): a rule leaving the pinned set is a decision, not a deletion
- `verifyJpaApiSurface` / `verifyJpaAdopterApiSurface`: surface change promoted to a review decision
- `PersistenceEntityScanCoverageTest`: an opt-in package that is no longer opt-in because it is no longer here
`verifyJpaAdopterApiSurface` was **not** widened by allowlist (design §28). Its scan excludes the
directory that *owns* the implementation; there are two such leaves now, so the exclusion was
corrected, and the baseline file still governs every other module's imports.
### One regression this introduced and then removed
The new web leaf first declared `spring-boot-starter-webflux`. The web leaf's own build file says in
a comment why it declares `spring-webflux` instead: the starter puts reactor-netty — a second
embedded server — on the runtime classpath of an application that already has Tomcat. The new leaf
now matches, and the lock files record the difference.
### Verification
./gradlew ci verifyDependencyLocks --continue # exit 0, 0 FAILED
Repository-wide, everything green, including `:app-bootstrap:verifyDependencyPolicy` — the RED that
opened this unit.
### Next
Unit 4, the Notification composition. Unit 3's ON/OFF regressions are covered by the tests that moved
with the code (`FileserverRuntimeAssemblyTest`, `FileserverPlatformAutoConfigurationTest` in the
composition module, `FileserverCompositionIntegrationTest` in app-bootstrap's integration lane) and
all are green in the run above.