Automattic / Automattic/blocks-engine

[Epic] Refactor for maintainability + parallel-safe swarm: decompose HtmlTransformer, formalize finding contract, modularize matrix

Open
#242 4 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.