docs: condense migration divergence log

This commit is contained in:
Algent committed 2026-09-02 17:13:53 +02:00
1 parent b992d9fbb2
commit 785991f270
3 files changed
+202 -3138

No files matched your search

+8 -1
View File
@@ -768,7 +768,10 @@ generated-trait compatibility work. Scala-runtime removal remains a later projec
- Found that `IMicroMaterialRender` is implemented for every part solely by `TMultiPart`'s Scala-style `world`/`x`/`y`/`z`/`getRenderBounds` accessors. Renaming any of them to a bean accessor would silently unimplement the interface, so the names are now pinned by a characterization test rather than left to reviewer attention.
- Established that for interfaces carrying no implementation, the characterization is the shape: every member abstract and public, no superinterface, and the exact member set. That is enough to catch the two realistic failure modes, a stray default and a renamed accessor.
- Noted that `IRedstonePart.scala` is misleadingly named and is not a marker-trait file. It carries six traits plus `RedstoneInteractions`, whose `MODULE$` is load-bearing, and was moved out of the low-risk group.
- Noted a documentation gap, not addressed here: this log was last appended for the `TItemMultiPart` port. The eight ports between it and this entry — `TEdgePart`, `Saw`, both registries, `TileMultipart`, `TMultiPart`, `TickScheduler` and `BlockMultipart` — are recorded in `JAVA_MIGRATION_DIVERGENCES.md` but never made it here, so the "Current status" section above should be read with that in mind.
- Historical documentation gap: the ports between `TItemMultiPart` and this entry — `TEdgePart`, `Saw`, both
registries, `TileMultipart`, `TMultiPart`, `TickScheduler` and `BlockMultipart` — did not receive dated findings
here. Use the handoff for their current status and git history for the original validation narrative; the divergence
ledger now records only their effective compatibility differences.
- Ported `MultipartHelper`, `MultipartHelper$` and `MultipartHelper$IPartTileConverter` to Java. All three are public-member- and descriptor-identical to the reference and the full emitted class list is unchanged, so this port neither added nor removed a class.
- Kept `MultipartHelper$` on the strength of a reflective string constant alone. It is not among the 17 `MODULE$` singletons read from bytecode and no jar links against it, but guidenh names it, and the inventory warns that removing a companion breaks such consumers invisibly. This is the opposite call to `IconHitEffects$`, which was dropped because nothing referenced it in bytecode or by name, and it establishes that the `MODULE$` list alone is not sufficient grounds to delete a companion.
- Found a reusable characterization technique: a class that cannot class-initialize headless is a probe for control flow. `MultipartSaveLoad` reflects into `TileEntity`'s static maps through `ObfMapping` and always throws under a plain JVM, so `createTileFromNBT` returning null rather than raising proves the id guard short-circuits before the `loadingWorld` assignment. Assert `LinkageError` rather than the exact type, because the first attempt raises `ExceptionInInitializerError` and later ones raise `NoClassDefFoundError`.
@@ -1230,3 +1233,7 @@ generated-trait compatibility work. Scala-runtime removal remains a later projec
- A clean build passes all 266 plain-JVM tests and the Java 8 Forge server passes all 116 tests. The two-type ABI and
both generator companions' disassembly match the reference. `multipart/asm/ByteCodecs.scala` is next as an isolated
codec port, leaving signature parsing and trait compilation for separate targets.
- Condensed `JAVA_MIGRATION_DIVERGENCES.md` from 3,134 to 189 lines, keeping effective runtime, binary and source
differences plus one shared classfile section. Removed repeated preservation claims, validation histories and
superseded intermediate decisions; the original narrative remains in git history. The workflow now records test
results here and updates the divergence ledger only for a genuinely new difference.
File diff suppressed because it is too large. Load diff
+5 -3
View File
@@ -8,7 +8,7 @@ what breaks, and what is left. The other documents hold the reasoning.
| `JAVA_MIGRATION.md` | The plan, phase state, and a running findings log |
| `JAVA_MIGRATION_ABI_INVENTORY.md` | Which downstream mods use what. **The authority on whether anything is load-bearing** |
| `JAVA_MIGRATION_CONSUMER_AUDIT.md` | How every consumer uses FMP at runtime: data, lifecycle, reflection, and generated tiles |
| `JAVA_MIGRATION_DIVERGENCES.md` | Every intentional difference from the reference, one entry per port |
| `JAVA_MIGRATION_DIVERGENCES.md` | Current intentional compatibility differences; shared compiler changes recorded once |
| `JAVA_MIGRATION_MANUAL_CHECKS.md` | What no automated test can cover, and must be checked by hand in a client |
| `JAVA_MIGRATION_PROFILE.md` | The focused baseline, first measured result, findings, and exact rerun command |
@@ -29,7 +29,8 @@ Followed for every port so far. It has caught three real ABI breaks that inspect
2. **Freeze a binary consumer** if the inventory shows a load-bearing `$class` or singleton. Recipe below.
3. **Port.** Delete the `.scala`, add the `.java`.
4. **Verify.** Same tests must pass unchanged, plus the ABI diff below.
5. **Document** in `JAVA_MIGRATION_DIVERGENCES.md`, then commit as `refactor: port X to Java`.
5. **Document** results in `JAVA_MIGRATION.md` and update this handoff. Add to `JAVA_MIGRATION_DIVERGENCES.md` only
for a new effective difference not already covered there, then commit as `refactor: port X to Java`.
If a characterization test will not compile after the port, that is a signal, not an inconvenience. Twice it was a real
ABI change (`MissingMicroMaterial` forwarders, the `ACC_SYNTHETIC` super accessor). Investigate before adjusting the
@@ -90,7 +91,8 @@ diff <(javap -p -cp /tmp/ref.jar codechicken.multipart.X | grep " public" | sor
diff <(javap -p -s -cp /tmp/ref.jar codechicken.multipart.X | grep descriptor | sort) <(javap -p -s -cp "$NEW" codechicken.multipart.X | grep descriptor | sort)
```
Also diff the emitted class list, to catch removed `$$anonfun$` artifacts that belong in the divergence log:
Also diff the emitted class list. Routine unreferenced closure removal is covered once in the divergence ledger;
record the specific comparison in the findings log, and investigate any removed named API or reflective type:
```bash
diff <(unzip -Z1 /tmp/ref.jar | grep X | sort) <(unzip -Z1 "$NEW" | grep X | sort)