Automattic / Automattic/blocks-engine
[Epic] Refactor for maintainability + parallel-safe swarm: decompose HtmlTransformer, formalize finding contract, modularize matrix
- Dominant language
- PHP
- Stars
- 14
- Forks
- 2
- Avg merge
- 2h 10m
- Merged PRs (30d)
- 561
Description
## Why now
`HtmlTransformer.php` is a ~3k-line god-object (pattern dispatch + menu-toggle suppression + button/style resolution + fallback diagnostics + semantic parity + runtime islands). Every transformer change this session had to edit it, forcing agents to be *serialized* instead of parallel. Decomposing it is the **precondition for the mass pattern-recognition swarm** (modular files → parallel agents → no collisions) and just good maintenance.
## Safety net
128 parity fixtures + the contract suite make **behavior-preserving** refactors verifiable: identical green before/after, zero block-output diff. Every refactor slice must prove this.
## Workstreams
1. **Decompose `HtmlTransformer`** into focused modules — `Patterns/` (exists) + a `Diagnostics/` layer (fallback / behavior-loss / semantic-parity emission) + a `Style/` layer (generalize `ButtonStyleResolver` into element-agnostic CSS→native-attribute resolution) + nav-chrome / runtime-island units. `HtmlTransformer` becomes a thin orchestrator. (multi-slice)
2. **Formalize the cross-repo finding/diagnostic contract** — the finding schema is implicit across blocks-engine (FallbackDiagnostic / RuntimeDependencyParityReport / VisualParity), SSI (loss-classes / report-diagnostics), homeboy-rigs (matrix acceptance). Make it one explicit versioned contract.
3. **Modularize `fixture-matrix.mjs`** (homeboy-rigs) — split accreted freshness / acceptance / editor-validation / visual-parity / metrics steps into composable step + collector modules.
## Rules
- Behavior-preserving; green parity+contract before and after each slice.
- Refactor on a QUIET base — never race feature/swarm agents on the same files.
- Pure extraction/move per slice; no logic changes smuggled in.
Contributor guide
Research direction
Start by reading HtmlTransformer.php, the existing Patterns/ area, and the parity fixtures and contract suite described in the issue; also inspect fixture-matrix.mjs for the homeboy-rigs workstream. Choose and scope one extraction slice before changing anything. Done means a focused module or collector exists, behavior is preserved, and parity plus contract checks remain green with zero block-output diff.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, php
- Domain
- backend, tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100