Skip to content

Refactor (slice 1, #242): extract diagnostics projection into DiagnosticsCollector #243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chubes4 merged 1 commit into from
Jun 27, 2026
+159 −104
Merged

Refactor (slice 1, #242): extract diagnostics projection into DiagnosticsCollector #243

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 148 additions & 0 deletions php-transformer/src/HtmlToBlocks/Diagnostics/DiagnosticsCollector.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
<?php
declare(strict_types=1);

namespace Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Diagnostics;

use Automattic\BlocksEngine\PhpTransformer\WordPress\Runtime;

/**
* Projects already-computed conversion signals (fallbacks, runtime islands,
* static script metadata, block-validity findings, and semantic-parity
* findings) into the flat diagnostics array carried by TransformerResult.
*
* This is a behavior-preserving extraction of the inline projection that
* previously lived in HtmlTransformer::transform(). It performs no DOM work and
* no logic decisions — it only reshapes data the transformer already produced —
* so the diagnostics output is byte-identical to the inline implementation.
*/
final class DiagnosticsCollector
{
/**
* Build the success-path diagnostics array from the transformer's computed
* signals.
*
* @param string $transformerSource Source attribution for transformer-owned diagnostics (HtmlTransformer::class).
* @param array<int, array<string, mixed>> $scriptMetadata Static script metadata preserved as bounded data.
* @param array<int, array<string, mixed>> $fallbacks Fallback diagnostics emitted during conversion.
* @param array<int, array<string, mixed>> $runtimeIslands Preserved runtime islands.
* @param array<string, mixed> $blockValidityReport Block serialization validity report.
* @param array<string, mixed> $semanticParityReport Semantic parity report.
* @return array<int, array<string, mixed>>
*/
public function collect(
string $transformerSource,
array $scriptMetadata,
array $fallbacks,
array $runtimeIslands,
array $blockValidityReport,
array $semanticParityReport
): array {
$diagnostics = array(
array(
'code' => 'html_to_blocks_core_slice',
'message' => 'Converted supported core text, layout, media, gallery, embed, file, table, button, shortcode, spacer, definition-list, details, navigation, safe inline SVG images, and wrapper elements; unsupported elements are reported as fallbacks.',
'source' => $transformerSource,
),
);

foreach ( $scriptMetadata as $metadata ) {
$diagnostics[] = array(
'code' => 'html_static_script_metadata',
'message' => 'Static script data was preserved as bounded metadata and does not require client script execution.',
'source' => $transformerSource,
'reason' => 'script_static_metadata',
'tag' => 'script',
'selector' => $metadata['selector'] ?? null,
'script_role' => $metadata['script_role'] ?? null,
);
}

foreach ( $fallbacks as $fallback ) {
if ( ! empty($fallback['diagnostic_code']) ) {
$diagnostics[] = array(
'code' => $fallback['diagnostic_code'],
'message' => $fallback['message'] ?? 'HTML element preserved as fallback metadata.',
'source' => $transformerSource,
'reason' => $fallback['reason'] ?? null,
'severity' => $fallback['severity'] ?? null,
'conversion_classification' => $fallback['conversion_classification'] ?? null,
'loss_class' => $fallback['loss_class'] ?? null,
'diagnostic_class' => $fallback['diagnostic_class'] ?? null,
'preservation_strategy' => $fallback['preservation_strategy'] ?? null,
'runtime_requirement' => $fallback['runtime_requirement'] ?? null,
'recoverability' => $fallback['recoverability'] ?? null,
'actionability' => $fallback['actionability'] ?? null,
'suggested_repair_class' => $fallback['suggested_repair_class'] ?? null,
'suggested_primitive' => $fallback['suggested_primitive'] ?? null,
'materialization_hint' => $fallback['materialization_hint'] ?? null,
'tag' => $fallback['tag'] ?? null,
'selector' => $fallback['selector'] ?? null,
'pattern_family' => $fallback['pattern_family'] ?? null,
'pattern_family_detail' => $fallback['pattern_family_detail'] ?? null,
'source_selector' => $fallback['source_selector'] ?? null,
'source_selector_specificity' => $fallback['source_selector_specificity'] ?? null,
'parent_reason' => $fallback['parent_reason'] ?? null,
'ancestor_reason' => $fallback['ancestor_reason'] ?? null,
'suggested_generic_repair_class' => $fallback['suggested_generic_repair_class'] ?? null,
);
}
}

foreach ( $runtimeIslands as $island ) {
$diagnostics[] = array_filter(array(
'code' => 'preserved_runtime_island',
'message' => 'Runtime-dependent source markup was preserved as a bounded runtime island.',
'source' => $transformerSource,
'severity' => 'info',
'conversion_classification' => 'runtime_island_preserved',
'loss_class' => 'runtime_island_preserved',
'diagnostic_class' => 'runtime_island_preserved',
'suggested_repair_class' => 'preserve_runtime_island',
'preservation_strategy' => $island['preservation_strategy'] ?? 'bounded_raw_html_runtime_island',
'runtime_requirement' => $island['runtime_requirement'] ?? null,
'kind' => $island['kind'] ?? null,
'reason' => $island['preservation_reason'] ?? null,
'tag' => $island['tag'] ?? null,
'selector' => $island['selector'] ?? null,
'pattern_family' => $island['pattern_family'] ?? null,
'pattern_family_detail' => $island['pattern_family_detail'] ?? null,
'source_selector' => $island['source_selector'] ?? null,
'source_selector_specificity' => $island['source_selector_specificity'] ?? null,
'parent_reason' => $island['parent_reason'] ?? null,
'ancestor_reason' => $island['ancestor_reason'] ?? null,
'suggested_generic_repair_class' => $island['suggested_generic_repair_class'] ?? null,
), static fn (mixed $value): bool => null !== $value && '' !== $value);
}

foreach ( $blockValidityReport['findings'] ?? array() as $finding ) {
if ( ! is_array($finding) ) {
continue;
}

$diagnostics[] = array(
'code' => 'wp_block_validity_' . (string) ($finding['code'] ?? 'warning'),
'message' => (string) ($finding['summary'] ?? 'Generated block serialization may trigger WordPress block invalidity warnings.'),
'source' => Runtime::class,
'severity' => $finding['severity'] ?? 'warning',
'block_name' => $finding['block_name'] ?? null,
'path' => $finding['path'] ?? null,
);
}

foreach ( $semanticParityReport['findings'] ?? array() as $finding ) {
if ( ! is_array($finding) ) {
continue;
}

$diagnostics[] = array(
'code' => 'html_semantic_parity_' . (string) ($finding['code'] ?? 'warning'),
'message' => (string) ($finding['summary'] ?? 'Generated blocks differ from source semantic structure.'),
'source' => $transformerSource,
'severity' => $finding['severity'] ?? 'warning',
'selector' => $finding['selector'] ?? null,
);
}

return $diagnostics;
}
}
115 changes: 11 additions & 104 deletions php-transformer/src/HtmlToBlocks/HtmlTransformer.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
use Automattic\BlocksEngine\PhpTransformer\Contract\ConversionReportProjection;
use Automattic\BlocksEngine\PhpTransformer\Contract\TransformationOptions;
use Automattic\BlocksEngine\PhpTransformer\Contract\TransformerResult;
use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Diagnostics\DiagnosticsCollector;
use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Patterns\AccordionPattern;
use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Patterns\ButtonsPattern;
use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Patterns\DetailsPattern;
Expand Down Expand Up @@ -68,6 +69,8 @@ final class HtmlTransformer

private readonly PatternRecognizerRegistry $patternRecognizers;

private readonly DiagnosticsCollector $diagnosticsCollector;

/**
* @var array<string, string>
*/
Expand Down Expand Up @@ -145,6 +148,7 @@ public function __construct(private readonly Runtime $runtime = new Runtime())
new AccordionPattern(),
new NavigationPattern(),
));
$this->diagnosticsCollector = new DiagnosticsCollector();
}

/**
Expand Down Expand Up @@ -239,112 +243,15 @@ public function transform(string $html, array $options = array()): TransformerRe
$serializedBlocks = $this->runtime->serializeBlocks($blocks);
$blockValidityReport = $this->runtime->validateBlockSerialization($blocks);
$semanticParityReport = $this->semanticParityReport($body, $blocks, $sourceProvenance, $html, (string) ($options['static_css'] ?? ''));
$diagnostics = array(
array(
'code' => 'html_to_blocks_core_slice',
'message' => 'Converted supported core text, layout, media, gallery, embed, file, table, button, shortcode, spacer, definition-list, details, navigation, safe inline SVG images, and wrapper elements; unsupported elements are reported as fallbacks.',
'source' => self::class,
),
$diagnostics = $this->diagnosticsCollector->collect(
self::class,
$this->scriptMetadata,
$fallbacks,
$this->runtimeIslands,
$blockValidityReport,
$semanticParityReport
);

foreach ( $this->scriptMetadata as $metadata ) {
$diagnostics[] = array(
'code' => 'html_static_script_metadata',
'message' => 'Static script data was preserved as bounded metadata and does not require client script execution.',
'source' => self::class,
'reason' => 'script_static_metadata',
'tag' => 'script',
'selector' => $metadata['selector'] ?? null,
'script_role' => $metadata['script_role'] ?? null,
);
}

foreach ( $fallbacks as $fallback ) {
if ( ! empty($fallback['diagnostic_code']) ) {
$diagnostics[] = array(
'code' => $fallback['diagnostic_code'],
'message' => $fallback['message'] ?? 'HTML element preserved as fallback metadata.',
'source' => self::class,
'reason' => $fallback['reason'] ?? null,
'severity' => $fallback['severity'] ?? null,
'conversion_classification' => $fallback['conversion_classification'] ?? null,
'loss_class' => $fallback['loss_class'] ?? null,
'diagnostic_class' => $fallback['diagnostic_class'] ?? null,
'preservation_strategy' => $fallback['preservation_strategy'] ?? null,
'runtime_requirement' => $fallback['runtime_requirement'] ?? null,
'recoverability' => $fallback['recoverability'] ?? null,
'actionability' => $fallback['actionability'] ?? null,
'suggested_repair_class' => $fallback['suggested_repair_class'] ?? null,
'suggested_primitive' => $fallback['suggested_primitive'] ?? null,
'materialization_hint' => $fallback['materialization_hint'] ?? null,
'tag' => $fallback['tag'] ?? null,
'selector' => $fallback['selector'] ?? null,
'pattern_family' => $fallback['pattern_family'] ?? null,
'pattern_family_detail' => $fallback['pattern_family_detail'] ?? null,
'source_selector' => $fallback['source_selector'] ?? null,
'source_selector_specificity' => $fallback['source_selector_specificity'] ?? null,
'parent_reason' => $fallback['parent_reason'] ?? null,
'ancestor_reason' => $fallback['ancestor_reason'] ?? null,
'suggested_generic_repair_class' => $fallback['suggested_generic_repair_class'] ?? null,
);
}
}

foreach ( $this->runtimeIslands as $island ) {
$diagnostics[] = array_filter(array(
'code' => 'preserved_runtime_island',
'message' => 'Runtime-dependent source markup was preserved as a bounded runtime island.',
'source' => self::class,
'severity' => 'info',
'conversion_classification' => 'runtime_island_preserved',
'loss_class' => 'runtime_island_preserved',
'diagnostic_class' => 'runtime_island_preserved',
'suggested_repair_class' => 'preserve_runtime_island',
'preservation_strategy' => $island['preservation_strategy'] ?? 'bounded_raw_html_runtime_island',
'runtime_requirement' => $island['runtime_requirement'] ?? null,
'kind' => $island['kind'] ?? null,
'reason' => $island['preservation_reason'] ?? null,
'tag' => $island['tag'] ?? null,
'selector' => $island['selector'] ?? null,
'pattern_family' => $island['pattern_family'] ?? null,
'pattern_family_detail' => $island['pattern_family_detail'] ?? null,
'source_selector' => $island['source_selector'] ?? null,
'source_selector_specificity' => $island['source_selector_specificity'] ?? null,
'parent_reason' => $island['parent_reason'] ?? null,
'ancestor_reason' => $island['ancestor_reason'] ?? null,
'suggested_generic_repair_class' => $island['suggested_generic_repair_class'] ?? null,
), static fn (mixed $value): bool => null !== $value && '' !== $value);
}

foreach ( $blockValidityReport['findings'] ?? array() as $finding ) {
if ( ! is_array($finding) ) {
continue;
}

$diagnostics[] = array(
'code' => 'wp_block_validity_' . (string) ($finding['code'] ?? 'warning'),
'message' => (string) ($finding['summary'] ?? 'Generated block serialization may trigger WordPress block invalidity warnings.'),
'source' => Runtime::class,
'severity' => $finding['severity'] ?? 'warning',
'block_name' => $finding['block_name'] ?? null,
'path' => $finding['path'] ?? null,
);
}

foreach ( $semanticParityReport['findings'] ?? array() as $finding ) {
if ( ! is_array($finding) ) {
continue;
}

$diagnostics[] = array(
'code' => 'html_semantic_parity_' . (string) ($finding['code'] ?? 'warning'),
'message' => (string) ($finding['summary'] ?? 'Generated blocks differ from source semantic structure.'),
'source' => self::class,
'severity' => $finding['severity'] ?? 'warning',
'selector' => $finding['selector'] ?? null,
);
}

$metrics = $this->metrics($html, $blocks, $serializedBlocks, $fallbacks, $diagnostics, $startedAt);
$nativeTargetBlocks = $this->runtime->availableCoreBlockNames();
$sourceReports = array(
Expand Down
Loading