swift-java-migration

Java to Swift Migration

The target is equivalent capability and behavior, not line-by-line resemblance. Compiling Swift is an intermediate checkpoint only.

Non-negotiable completion contract

• Record every in-scope Java class, interface, enum, record, annotation, nested type, constructor, method, and externally visible contract.
• Every record is IMPLEMENTED, ADAPTED with evidence, or explicitly excluded with approved rationale. Stubs, fatalError, empty bodies, placeholders, and silent omissions do not count.
• Preserve values, errors, ordering, state, concurrency, serialization, resources, and side effects unless an intentional change is approved.
• Swift-native architecture may replace Java mechanics but cannot reduce capability.
• Do not declare completion before swift-java-migration-testing passes full source-test and differential gates.

Workflow

1. Freeze scope and baselines

Record source/target commits, Java and Swift tools, modules/targets, generated sources, platforms, feature flags, external dependencies, and exclusions. Capture the Java build/test baseline first.

2. Build the source ledger

Track at least:

java_key | kind | target_path | target_symbol | status | evidence | notes

Use full method signatures for overloads. Track nested types, annotations with runtime meaning, and interface defaults independently. Reconcile the ledger in CI.

3. Design semantic adapters

• Map Java modules/packages to coherent SwiftPM targets and modules.
• Map interfaces to protocols only when associated types, existential use, identity, and default implementations remain valid.
• Map CompletableFuture/Reactor to async/await or AsyncSequence only after cancellation, ordering, backpressure, scheduling, and error semantics are specified.
• Replace reflection, annotations, service loading, proxies, synchronization, thread locals, and checked exceptions with explicit registries, generated metadata, actors/locks, task context, and typed errors.
• Preserve wire/storage schemas independent of the in-memory Swift representation.

Read Swift migration adapter before selecting mappings.

4. Implement vertical slices

Migrate contract, production behavior, Java tests, copied assets, differential cases, and Swift-specific tests together. Do not postpone parity testing until all source files are translated.

5. Preserve documentation

Translate semantic Javadoc, parameter/return/error contracts, thread-safety notes, lifecycle rules, and compatibility constraints into Swift documentation comments.

6. Run gates

swift build
swift test

Then run the dedicated <project>-test acceptance package/target and complete Java/Swift differential suite.

Status reporting

Report separate denominators for production objects, members, source test cases, assets, differential cases, and Swift-only obligations. Never collapse them into one percentage or substitute coverage for migration completeness.