Automattic / Automattic/wp-codebox

Visual compare emits a Blocks Engine report schema

Offen
#2,399 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
TypeScript
Sterne
17
Forks
4
Ø Merge
59 Min.
Gemergte PRs (30 T.)
131

Beschreibung

Follow-up to #732.

## The boundary

#732 built the visual-compare primitive with an explicit split: WP Codebox owns the generic evidence substrate, downstream products own policy. Its acceptance criteria state:

> No downstream-specific thresholds, Static Site Importer semantics, Data Liberation semantics, or pass/fail policy are encoded in WP Codebox.

## What shipped

`browser-visual-compare` exports `blocksEngineVisualParityReportFromVisualCompare()`, returning a `BlocksEngineVisualParityReport` with `schema: "blocks-engine/php-transformer/visual-parity-report/v1"`.

That type carries verdicts, not evidence:

```ts
status: "pass" | "warning" | "fail" | "unknown";
severity: "none" | "info" | "warning" | "error" | "critical";
```

It is also not opt-in. The adapter is called in four places inside `browser-visual-compare.js`, and each writes two things:

```js
await artifactSession.writeJson("visualDiff", "visual-diff.json", summaryWithBlocksEngineVisualParity);
await artifactSession.writeJson("blocksEngineVisualParity", "blocks-engine-visual-parity-report.json", blocksEngineVisualParity);
```

So the downstream report is written as its own artifact **and embedded inside the generic one**. Every consumer of `visual-diff.json` receives a `blocksEngineVisualParity` field carrying another product's schema and its pass/fail verdict, whether or not it has anything to do with Blocks Engine.

## Why it matters beyond naming

The status mapping is policy. `identical → pass`, `different → fail`, `partial → warning` is one product's threshold decision, made inside the substrate that was specified not to make it.

It also sets a precedent. #732 names `wp-site-generator`, `data-liberation-agent`, and `static-site-importer` as consumers. If one gets a bespoke report shape in the shared artifact, the others have a reasonable claim to theirs, and the generic artifact becomes a union of downstream schemas.

## Where it should live

The schema is owned and consumed by `blocks-engine`'s php-transformer — its parity test fixtures are the readers. `static-site-importer` sees it only transitively through the vendored figma transformer. `data-liberation-agent` does not reference it at all.

So the mapping belongs next to the schema that defines it, in `blocks-engine`, consuming Codebox's generic `visual-diff.json`.

## Suggested shape

- Stop embedding `blocksEngineVisualParity` in `visual-diff.json`.
- Move `blocksEngineVisualParityReportFromVisualCompare` and `BlocksEngineVisualParityReport` to the consumer that owns the schema.
- Keep `visual-diff.json` as the normalized generic evidence #732 specified: mismatch ratio, diff pixels, dimensions, viewport/profile metadata, source/candidate metadata, pairing strategy, explicit missing-capture and decode failures.

The coupling is small — two declaration files, one schema string, one function and its interface — so this is a contained change rather than a redesign.

## AI assistance

Claude via OpenCode inspected the shipped `runtime-playground` visual-compare surface, traced the adapter's call sites and artifact writes, and identified the consuming repositories. Chris Huber directed and reviewed the finding.

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Rechercherichtung

Beginne in browser-visual-compare.js und untersuche die vier Aufrufstellen der Adapter und die Artefaktschreibvorgänge; prüfe anschließend die beiden Deklarationsdateien und die Paritäts-Fixtures von blocks-engine php-transformer, die das Schema verwenden. Verschiebe das Schema und das Mapping zum zuständigen Consumer, bette seinen Bericht nicht mehr in visual-diff.json ein und verifiziere, dass das generische Artefakt nur die in #732 beschriebene normalisierte Evidenz enthält.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
javascript, typescript
Bereich
testing, tooling
Issue-Typ
Refactoring
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Aktiv
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
58/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.