refactor(php-transformer): make layer direction one-way and enforceable - #1564
Merged
Conversation
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.
Closes #1563
What
Breaks the dependency cycle inside
php-transformerand adds a contract test that keeps it broken.HtmlToBlocks/Style/into a sharedCss/namespace:CssStylesheetTransformer,CssValueSplitter,CssRuleAnalyzer,CssSyntaxScanner,CssSelectorMatcher,CssSelectorMatchCache,CssSelectorTokenizer,AdminBarAccommodation.ShellLandmarkPolicyintoSupport/.Contract\EmittedCoreBlockContracts, soWordPress\CoreBlockCapabilityMatrixno longer depends on theHtmlTransformerfacade to report capabilities.tests/contract/layer-direction.phptocomposer test.Result
The layer model the contract now enforces:
Css/,Support/,Contract/,AssetAnalysis/) depend on nothing above themWordPress/is Gutenberg block grammar, which a Gutenberg-targeting translator may legitimately useHtmlToBlocks/is translationWordPressSitePlan/,StaticSite/are WordPress materialization and may not import translationArtifactCompiler/is the composition root and may import anything, because composing the two halves is its jobWhy not split the package
The package boundary is already correct. Static Site Importer imports
ArtifactCompiler(27),WordPressSitePlan(6),AssetAnalysis(4),WordPress(2),StaticSite(2),Contract(1), and zeroHtmlToBlocksclasses — conversion runs insideArtifactCompiler. No consumer wants one half without the other, so a second package would add a release train and a second version pin while buying no isolation. The defect was internal layering, and that is what this fixes.Consumer impact
None. No class in a downstream consumer surface moved —
Contract\ConversionFindingContract,StaticSite\FontMaterialization\FontMaterializationPlanBuilder, andWordPress\Runtimeare all untouched. Every moved class was internal to conversion.Known remaining edge
HtmlToBlocksstill importsStaticSite\FontMaterializationin three places. That class is in SSI's import surface, so relocating it is a coordinated release rather than a move. The contract test pins the exact allowed set and fails if an unpinned materialization dependency is added — or if a pinned one disappears, so the allowance cannot rot.Verification
composer testgreen, exit 0 — includes 297 parity fixtures, the canonical contract suite, unit suites, and the dist shape contract (267 files).namespace-resolution.php, the repo's existing guard for exactly this class of move, passes: 255 class-likes declared, no unresolvable references. It caught 27 bare references during the work.AI assistance
OpenAI
gpt-5.6-solrunning in OpenCode mapped the cycle, performed the moves, wrote the contract test, and ran the verification above. A human directed the work and reviewed the result.