chore(engine): deprecate the legacy ECS engine packages (F11)#148
Merged
Conversation
engine.core, engine.layout (+ container), and engine.pagination are the original Entity-based layout/pagination engine -- a parallel second engine that no public API reaches (the canonical GraphCompose.document() pipeline imports nothing from them, and GraphCompose.pdf(...) was already removed). They survive only to back the legacy engine regression tests. Mark the three packages @deprecated at package level (no deprecation-warning cascade) and rewrite their misleading 'shared' / 'normal PDF pipeline' docs to point at the canonical com.demcha.compose.document.layout pipeline, so contributors stop optimizing a dead engine. The genuinely shared engine packages (engine.components / measurement / font / render) are NOT deprecated. No runtime or behaviour change; binary-compatible (japicmp green).
PR review of #148 found the engine.core package doc overstated isolation: the canonical TextMeasurementSystem still extends engine.core.SystemECS with a no-op process(EntityManager), so SystemECS/EntityManager are referenced from live code — they do not 'survive only to back the legacy engine regression tests'. Reword the package-info and CHANGELOG to say the ECS *execution* engine is dead while noting the vestigial SystemECS base as a tracked decoupling follow-up. engine.layout/pagination docs were already accurate. Docs-only.
This was referenced Jun 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Finding 11 — mark the dead legacy ECS engine deprecated
engine.core,engine.layout(+engine.layout.container), andengine.paginationare the originalEntity-based layout/pagination engine. The audit flagged them as a parallel second engine that no public API reaches:GraphCompose.document() → DocumentSession → LayoutCompiler → LayoutGraph → PdfFixedLayoutBackend) imports nothing from them (verified);GraphCompose.pdf(...)/PdfComposer/com.demcha.templates.*surface has already been removed — so they're reachable only from the legacy engine regression tests (64 test files).Their package docs actively misdirected contributors ("shared layout systems", "the normal PDF pipeline").
Change
@Deprecatedon the 3 pure-legacy packages (+ container subpackage) and rewritten, accurate package docs pointing atcom.demcha.compose.document.layout.engine.components,engine.measurement,engine.font,engine.render) are not deprecated, and are explicitly called out as such in the corrected docs.Scope note
engine.render.pdfis intentionally out of scope: it's a canonical-mixed package (PdfFont/GlyphFallbackLogger+handlers/helperssubpackages) with simple-name collisions vsdocument.backend.fixed.pdf(PdfRenderSessionetc.). Deprecating its legacy ECS classes cleanly needs a package split first — a follow-up.Verification
Full
verifygreen: 1152 tests, japicmp binary-compatible (adding @deprecated is compatible), architecture guards + visual-regression all pass. No runtime or behaviour change.