Automattic / Automattic/blocks-engine
Extract the transform() result-assembly tail into a result-composition collaborator
- Dominant language
- PHP
- Stars
- 14
- Forks
- 2
- Avg merge
- 2h 10m
- Merged PRs (30d)
- 561
Description
Parent: #242
## Problem
The epic audit named `transform()` the second worst offender after `convertElement()`. On `trunk` (`f8e12d04`) `transform()` spans lines 814–1089 of `HtmlTransformer.php` — 276 lines — and **136 of them, exactly half, are result assembly rather than transformation**.
Lines 954–1089 do nothing but compose the return value: `blockValidityReport`, `semanticParityReport`, `contentRoundTripReport`, the `diagnostics` array plus four inline `$diagnostics[] = array(...)` append blocks (responsive geometry, head metadata, author layout topology, description-list gap), the 30-key `$sourceReports` map with a nested 13-key `html` sub-map, the `coverage` array, and the `TransformerResult` construction. Not one line converts a DOM node.
That block is also the reason the god object keeps attracting edits from unrelated concerns. Any feature that wants to surface a new signal has to reach into `transform()`, which is precisely the serialization this epic exists to remove.
## Scope
A collaborator, not a trait — same model as `TextLeafElementConverter` in #1310, which takes an explicit operation context and has no `$this` access to the transformer.
- Introduce a result-composition collaborator that receives explicit inputs (blocks, serialized blocks, fallbacks, provenance, options, session state, metrics) and returns the diagnostics array, the source-reports map, and the coverage array.
- Move the four inline diagnostic append blocks into the collaborator as named methods.
- Pure extraction. No logic changes, no key renames, no reordering of the emitted maps.
## Acceptance
- Behavior preservation proven by corpus hash diff, not a green suite alone: `serializedBlocks` SHA-256 captured for every fixture HTML file on clean `trunk` and recaptured after — 0 differing, 0 throwing.
- Full `TransformerResult` array equality on a representative multi-page fixture set, since this refactor moves report keys rather than block output.
- `composer test` exit 0.
- `transform()` lands near 140 lines; the collaborator is unit-testable without constructing an `HtmlTransformer`.
## Why this slice
It is the largest contiguous non-conversion block left in the file, it is a pure move, and it is the natural seam for #1360 — with the tail in one place, gating the evidence surface is a single branch instead of eight scattered call sites.
---
*AI assistance disclosure: this issue was investigated and drafted by Claude Sonnet 4.6 running in Claude Code, operated by @chubes4. The AI read `HtmlTransformer.php` at `trunk` (`f8e12d04`) and computed the method spans and line counts quoted above by brace-depth analysis. Reviewed by a human before posting.*
Contributor guide
Research direction
Start in HtmlTransformer.php at transform() lines 814–1089, focusing on the result-assembly tail from lines 954–1089 and the TextLeafElementConverter pattern from #1310. Extract the four diagnostic append blocks and report construction into a collaborator with explicit inputs, preserving keys and ordering. Run composer test and compare serializedBlocks SHA-256 hashes plus TransformerResult arrays against clean trunk.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- backend
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100