Automattic / Automattic/wp-codebox

Visual compare emits a Blocks Engine report schema

Aperta
#2,399 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
TypeScript
Stelle
16
Fork
4
Merge medio
59m
PR unite (30g)
131

Descrizione

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.

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Direzione di ricerca

Inizia da browser-visual-compare.js e ispeziona i quattro punti di chiamata dell’adapter e le scritture degli artefatti, poi esamina i due file di dichiarazione e i fixture di parità di blocks-engine php-transformer che consumano lo schema. Sposta lo schema e il mapping nel consumer proprietario, smetti di incorporare il suo report in visual-diff.json e verifica che l’artefatto generico conservi solo l’evidenza normalizzata descritta in #732.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
javascript, typescript
Ambito
testing, tooling
Tipo di issue
Refactoring
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Attiva
Chiarezza
Abbastanza chiara
Idoneità per principianti
58/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.