blocks-engine: structured convert report (envelope + fallback inventory + metrics)#426
Merged
Conversation
Design for porting php-transformer's structured result envelope into packages/blocks-engine as item #1 of docs/to-port-to-js.md: a new canonical convertReport() returning { schema, status, blockMarkup, fallbacks, diagnostics, metrics }, with convert() projected to .blockMarkup. Covers the tolerant ConversionFinding shape, core/html-as-fallback-source inventory, metrics, a pure unit-testable buildReport core, and an assertConvertReport contract. Scopes ratchet integration and hallucination findings out to later items.
Incorporates the four decisions from the plan deep review: (1) block analysis moves into the worker (Approach A) so buildReport stays pure and WP-free and the no-wordpress-runtime-deps contract holds, reusing walkBlocks and adding blockCount/htmlIslands to FixResult; (2) conversion_degraded diagnostic when the pool sentinel fires; (3) unconverted_html inventory capped at 100 with a fallback_inventory_truncated diagnostic while metrics.fallbackCount keeps the true total; (4) snippet sanitized, char-based (multibyte-safe) truncation, documented as untrusted. Updates sections 3-8 and the testing matrix accordingly.
Capture the 6 review-deferred follow-ups (invalid-block severity, fallbackCount/length doc, inventory perf gate per council C, snippet render-safety, failed-status decision, purity import-graph guard) in the spec so nothing is lost after the branch lands. Docs only.
Declare ThemeDiagnostics.conversion optional so adding it is backward-compatible for external code that constructs a ThemeBuildResult/ThemeDiagnostics literal (e.g. downstream test fixtures), which would otherwise have to add the new field to compile. siteToTheme still always populates it, so readers are unaffected at runtime. Keeps the change purely additive for consumers like data-liberation-agent.
The root .gitignore pattern 'docs/superpowers/' is anchored to the repo root, so it did not cover 'packages/blocks-engine/docs/superpowers/' — which let a design spec get committed by mistake. Switch to '**/docs/superpowers/' so the path is ignored at any depth, and remove the spec doc that should not have been committed.
Root pattern 'docs/superpowers/' is anchored to the repo root and did not cover 'packages/blocks-engine/docs/superpowers/', which let a design spec get committed by mistake. Use '**/docs/superpowers/' so superpowers docs are ignored at any depth.
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
1 participant
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.
What
This adds better reporting in the blocks-engine package—an idea from the
php-transformer.Adds a structured conversion report to
@automattic/blocks-engineand wires it into the theme builder so HTML→blocks conversion fidelity is visible and measurable instead of a black box.convertReport(html, ctx?, opts?)returning a versioned envelope:{ schema, status, blockMarkup, fallbacks, diagnostics, metrics }.convert()is unchanged for callers (still returns the markup string) — it's now a thin projection ofconvertReport().blockMarkup, so the string and the envelope can never drift.fallbacksis a per-conversion inventory of everything that did not become a native block (each unconvertedcore/htmlisland with a location + bounded snippet), capped at 100 with a true total inmetrics.fallbackCount.metrics: input/output bytes, block count, fallback/diagnostic counts, duration.diagnostics:conversion_degraded(worker sentinel/internal-catch),content_dropped(non-empty input → empty output),fallback_inventory_truncated,normalized_markup.siteToThemenow aggregates per-page conversion fidelity intoThemeBuildResult— a typedThemeDiagnostics.conversionaggregate, human-readablewarnings("page X: N section(s) fell back to raw HTML" / "conversion degraded"), and afallbackstally.Why
successwhen content was dropped or the conversion degraded.Design notes
buildReportstays pure and@wordpress/*-free, preserving theno-wordpress-runtime-depscontract.packages/blocks-engine/docs/superpowers/specs/2026-06-30-convert-report-envelope-design.md.Testing
pnpm build→ exit 0pnpm test→ 100 files / 472 tests, 0 failures (baseline 439)pnpm typecheck→ 0 errors