Skip to content

chore(engine): deprecate the legacy ECS engine packages (F11)#148

Merged
DemchaAV merged 2 commits into
developfrom
chore/deprecate-legacy-ecs
Jun 9, 2026
Merged

chore(engine): deprecate the legacy ECS engine packages (F11)#148
DemchaAV merged 2 commits into
developfrom
chore/deprecate-legacy-ecs

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Jun 9, 2026

Copy link
Copy Markdown
Owner

Finding 11 — mark the dead legacy ECS engine deprecated

engine.core, engine.layout (+ engine.layout.container), and engine.pagination are the original Entity-based layout/pagination engine. The audit flagged them as a parallel second engine that no public API reaches:

  • the canonical pipeline (GraphCompose.document() → DocumentSession → LayoutCompiler → LayoutGraph → PdfFixedLayoutBackend) imports nothing from them (verified);
  • the legacy 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

  • Package-level @Deprecated on the 3 pure-legacy packages (+ container subpackage) and rewritten, accurate package docs pointing at com.demcha.compose.document.layout.
  • Package-level specifically so there is no deprecation-warning cascade across the 64 legacy test files — confirmed empirically: compile is clean, zero warnings reference these packages.
  • The genuinely shared engine packages (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.pdf is intentionally out of scope: it's a canonical-mixed package (PdfFont / GlyphFallbackLogger + handlers / helpers subpackages) with simple-name collisions vs document.backend.fixed.pdf (PdfRenderSession etc.). Deprecating its legacy ECS classes cleanly needs a package split first — a follow-up.

Verification

Full verify green: 1152 tests, japicmp binary-compatible (adding @deprecated is compatible), architecture guards + visual-regression all pass. No runtime or behaviour change.

DemchaAV added 2 commits June 9, 2026 11:16
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.
@DemchaAV DemchaAV merged commit cf840be into develop Jun 9, 2026
11 checks passed
@DemchaAV DemchaAV deleted the chore/deprecate-legacy-ecs branch June 9, 2026 10:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant