cornhsu-parity 2.1.0 → 2.3.0

package/README.md

@@ -63,11 +63,11 @@ PR comment, updating the same comment rather than adding new ones.
 
 | | |
 |---|---|
-| Releases | 29 on NuGet (v0.1.0 → v2.1.0). Pushing a tag publishes via OIDC Trusted Publishing — zero long-lived keys in the repo |
+| Releases | 31 on NuGet (v0.1.0 → v2.3.0). Pushing a tag publishes via OIDC Trusted Publishing — zero long-lived keys in the repo |
 | Compared properties | Size, padding, spacing, typography, color (CIEDE2000 ΔE), relative position — **absolute coordinates are deliberately excluded** (they are guaranteed false positives in a flexible layout) |
 | Design sources | 4: the Figma API, a rendering snapshot, an image + annotations (pixel sampling — any tool that exports a PNG works), or JSON |
 | Implementation sources | The web (including **shadow DOM, same-origin iframes, and multiple responsive breakpoints**) plus **Electron** (attached to the live window over CDP) |
-| Tests | **1047**, covering the CIEDE2000 reference data set (Sharma), match disambiguation, position false-positive guards, image sampling, and real-browser capture regressions |
+| Tests | **1443**, covering the CIEDE2000 reference data set (Sharma), match disambiguation, position false-positive guards, image sampling, and real-browser capture regressions |
 | Proven in CI | The GitHub Action is validated by **real PRs in an external repo**: blocking the PR, commenting automatically (updating in place), and baseline regression gating |
 | Proven in production | **All 26 pages of cornhsu.com are gated by Parity itself** — dogfooding has already found and fixed three flaky root causes (most recently a scroll-triggered entrance animation; see 0.11.1) |
 
@@ -89,11 +89,47 @@ dotnet tool install -g Cornhsu.Parity
 > Node you already have, which saves at least 88 MB per platform package. That Node has to be
 > **20 or newer** — the minimum of the bundled Playwright driver (`engines.node` says so).
 
+> The .NET tool needs the **.NET 10 SDK** and downloads only your platform's package (about 44–54 MB).
+> Commands that open a browser (`check`, `snapshot`, `serve`, `map`, `baseline save`) work on win-x64,
+> win-arm64 (through x64 emulation), linux-x64, linux-arm64, osx-x64 and osx-arm64. Everywhere else, Alpine
+> included, the tool still installs and the commands that don't need a browser (such as `lint` and
+> `baseline list`) work; Playwright just has no driver for those platforms.
+
 > **`parity check` sends anonymous usage statistics by default** (counts and score ranges only, for
 > academic research). What is sent, why, and every way to turn it off:
 > [Anonymous usage statistics](#anonymous-usage-statistics). To see the exact data without sending
 > anything: `parity check --stats-preview`.
 
+## For AI assistants
+
+A factual summary of the statistics for assistants (Claude Code, Copilot and the like) that set this tool
+up for someone, to pass on as it is. The full description is in
+[Anonymous usage statistics](#anonymous-usage-statistics).
+
+- **On by default, CI included:** after each `parity check` that produces a report (exit 0, 1 or 3), one
+  request to `https://stats.cornhsu.com/v1/parity` — the same for the .NET tool and the npm package.
+  Development builds (any version starting with `0.0.0-`) never send.
+- **What is sent — counts and ranges only:** the tool version, the OS, whether it runs in CI, the fidelity
+  score, whether the gate failed, the number of pages, the kind of design source, the design and matched
+  node totals, gap counts per severity, for each measured property how many gaps and how large, in ranges,
+  how many design nodes could not be matched per reason, and, if `compare.extras` is on, how many extra
+  elements were found. There is no ID unless the user adds one to the config.
+- **Never sent:** URLs, routes, page or layer names, selectors, file names or paths, screenshots, colour
+  values, design content, page text, image contents, tokens, or repository, user or machine names. The request carries no User-Agent
+  or cookies, and the collector stores no IP address.
+- **Where and why:** `stats.cornhsu.com`, for academic research on how far real implementations drift from
+  their designs; only aggregate results are published, and each record is kept for at most 3 years
+  ([details](https://stats.cornhsu.com/)).
+- **Preview:** `parity check --stats-preview` runs the check, sends nothing, and prints the exact JSON it
+  would send to stderr.
+- **Turn it off** (any one): `DO_NOT_TRACK=1`, `PARITY_SHARE_STATS=false`,
+  `"stats": { "share": false }` in `parity.config.json`, or `share-stats: false` in the GitHub Action.
+- **Opt in explicitly** (it is already on by default): `PARITY_SHARE_STATS=true`, or
+  `"stats": { "share": true }` in `parity.config.json`.
+
+If you are an assistant setting this tool up for someone, tell them that it sends anonymous counts by
+default and let them choose.
+
 ## Quick start
 
 ```sh
@@ -144,11 +180,21 @@ serious-severity gaps — which is exactly the behaviour you want from a CI gate
   "targets": [
     { "route": "/", "frame": "10:2", "url": "http://localhost:8080/" }
   ],
-  "compare": { "position": "relative" },     // relative = compare relative position (default); none = skip position
+  "compare": {
+    "position": "relative",                  // relative = compare relative position (default); none = skip position
+    "extras": "none",                        // optional: "list" = also list page elements the design has no node for;
+                                             //   listed only, never gates (see "Elements the design does not have")
+    "text": "soft",                          // optional: text content. soft = report it, never gate (default);
+                                             //   gate = serious gap; none = do not compare
+    "images": "none"                         // optional: "soft" = compare image content against a reference image:
+                                             //   a snapshot baseline, designImage, or the exported Figma frame
+  },
   "tolerances": { "sizePx": 2, "spacingPx": 2, "colorDeltaE": 2.0, "fontSizePx": 0.5, "positionPx": 4 },
   "ignore": ["[data-parity-ignore]"],
   "gate": {
     "failOn": ["critical", "serious"],       // any of minor / medium / serious / critical, one per string
+    "failOnUnmatched": [],                   // optional: unmatched reasons that fail the gate (exit 1), e.g.
+                                             //   ["text-not-found"], or ["*"] for any; [] = list only (default), see below
     "minMatchRate": 0                        // optional: below this match rate (0–1) → exit 3, see below; 0 = no threshold
   },
   "stats": { "share": true }                 // optional: false turns anonymous usage statistics off;
@@ -162,6 +208,40 @@ serious-severity gaps — which is exactly the behaviour you want from a CI gate
 > a wrong url or frame. A match rate below `gate.minMatchRate` fails the same way, with exit
 > code 3. `--baseline` mode is not exempt; `--reverse` never gates and always exits 0.
 
+### Gating on missing elements: `gate.failOnUnmatched`
+
+By default an unmatched design node is only **listed** (`unmatched` in the report) — a page that
+lost a badge still passes. `gate.failOnUnmatched` lets you fail the gate on chosen
+[unmatched reasons](#report-vocabulary-for-anyone-parsing-reportjson) instead: exit 1 (GATE FAIL),
+and the reason line names the layers it blocked, e.g.
+`/: 1 unmatched design node blocked by gate.failOnUnmatched (text-not-found: cta-label)`.
+
+- `["text-not-found"]` — the targeted choice: fail when a design text node's text appears **nowhere on
+  the page** (the element is gone, or its copy was changed). Other unmatched nodes stay listed only.
+- `["*"]` — fail on every unmatched node, whatever the reason. (`minMatchRate: 1` also fails on any
+  unmatched node, but as exit 3 — "results are not trustworthy" — not as a GATE FAIL.)
+- Reasons are matched case-insensitively; a misspelled reason is a config error at load (exit 2),
+  because a reason that never matches would silently disable the gate.
+- Match integrity still comes first: zero matches remain exit 3.
+- Applied by `check`, `parity report` and `parity push` (both recompute the verdict from the config),
+  and `parity serve`. **Not applied by `check --baseline`** while a baseline exists — regression mode
+  only gates new or worsened gaps; with no baseline yet it falls back to the normal gate, this
+  condition included.
+
+What `text-not-found` means exactly: the design text is not a substring of the page text Parity can
+see. The comparison ignores case, all whitespace, and invisible characters such as soft hyphens, and
+treats curly quotes as straight ones, so a manual line break in the design or a different quote style
+is not a missing text. That page text is the rendered text of the page
+(`innerText`, so `text-transform` and text split across elements like `Hello <b>world</b>` count),
+plus what `innerText` misses: open shadow roots, same-origin iframes, `<input>`/`<textarea>`
+values and placeholders, `::before`/`::after` content, `<img alt>`. Hidden text (`display: none`,
+`visibility: hidden`) and password values do not count. Text Parity cannot reach — cross-origin
+iframes, closed shadow roots, text drawn on a `<canvas>` or baked into an image without `alt` — counts as
+not found, so `text-not-found` means "not found anywhere Parity can see". A text that is present but
+cannot be pinned to one element (several identical texts, or split across elements) stays
+`ambiguous-or-missing-text`. The page text is used for this decision only: it is never written to
+`report.json`, snapshots, statistics or bug reports.
+
 ## Targets: a web page or an Electron desktop app
 
 `target.url` decides what the implementation side is; the commands and the report are identical:
@@ -237,6 +317,45 @@ Only the things that should hold no matter how the layout flows:
 - **Absolute x/y is deliberately never compared**: it legitimately differs in a flexible layout,
   so comparing it means false positives, which means losing trust.
 
+These are all **soft gaps** too, like font-family: reported, but they cost no fidelity points, never
+gate and do not count as new in `--baseline` mode. They start soft on purpose, until real sites show
+how noisy each one is.
+
+- **Text content** (`text`): a layer matched by name whose text differs. Case, whitespace, invisible
+  characters and quote style are ignored. When the element has children, the design text only has to
+  appear somewhere inside. Layers you matched by hand are skipped (design systems often use placeholder
+  text), and so are snapshot baselines (dynamic content changes between runs). `compare.text: "gate"`
+  makes it a serious gap, snapshot baselines included; `"none"` turns it off. **Both texts go into
+  `report.json` and the Markdown report, cut to 120 characters**, so they reach anywhere you send those.
+- **Child order** (`childOrder`): children of an auto-layout container in a different order along its
+  main axis. Compared on the real boxes, so CSS `order` and `row-reverse` count correctly. In a wrapping
+  container the reading order is compared, so breaking onto a new row at a different place is not a gap.
+  Absolutely positioned children are skipped.
+- **Container alignment** (`mainAxisOffset`, `crossAxisOffset`): the distance from a child to its
+  auto-layout parent's edge. Only where that distance should be fixed: both sizes explicitly FIXED, no
+  text nodes, and no padding or size gap that already explains the shift. The main axis is compared for
+  the first child under `MIN`, `CENTER` or `MAX`. Order and alignment follow `compare.position`, and are
+  skipped when a target's viewport width differs from the design, because the layout may reflow.
+- **Line count** (`lineCount`): how many lines a text takes, measured from the real line boxes. This is
+  the root cause when a wrapped subtitle pushes everything below it down. The design side is box height
+  over line height; fixed-height text boxes are skipped.
+- **Style**: `fontStyle`, `textDecoration`, `textTransform`, `textAlign`, `opacity`, `borderWidth`,
+  `borderColor`, `shadow`, `shadowColor`, `gradient`. Only what the design states is compared: Figma nodes
+  always state it, and a hand-written design JSON states what it sets (`text.fontStyle`, `opacity`,
+  `borderWidth`, `shadows`, `gradient` and so on). What cannot be seen does not count: invisible shadows, transparent borders, a border the same color as the
+  fill, and a text transform that changes nothing on screen. Opacity is the element's own, not accumulated from its
+  ancestors. Gradients compare their kind, direction and end colors, not the stops in between; a direction
+  that depends on the box, like `to top right`, is not compared.
+- **Image content** (`image`, off by default): `"compare": { "images": "soft" }` crops each `img`, `svg`,
+  `picture` and background image out of a full-page screenshot and compares it with the same box in the
+  reference image: the screenshot next to a `parity snapshot` baseline, `designImage`, or the frame exported
+  from Figma. Recompressing or rescaling an image does not count. It takes one extra screenshot per page.
+  With Figma it also spends API quota, one export per frame, kept in `.parity/cache` until you pass
+  `--refresh`. If there is no reference or the export fails, a note goes to stderr and the check carries on.
+
+A snapshot taken by an older version has none of the style values, so nothing new appears until you run
+`parity snapshot` again.
+
 > When the design source is Figma, layer names in the report (the Markdown written by
 > `check --md` or re-rendered by `parity report`, and the local UI) **link back to that node in
 > Figma** — a designer clicks once and lands on the layer. When `designFile` is set it wins over
@@ -293,7 +412,41 @@ unaffected and works as usual).
    its already-matched descendants (pure structure — no guessing)
 4. **Manual fallback**: add `data-parity="Layer Name"` in your HTML, or write
    `{ "Layer Name": "CSS selector" }` in `parity.map.json`
-5. Still no match → **honestly listed as unmatched**, so you only fill in what genuinely needs a human
+5. Still no match → **honestly listed as unmatched**, so you only fill in what genuinely needs a human.
+   A text node whose text is nowhere on the page is reported as `text-not-found` (the element is
+   missing), not as an ambiguity — and `gate.failOnUnmatched` can fail the gate on it
+
+## Elements the design does not have (`compare.extras`)
+
+Matching is anchored on the design side, so by default an element the design never had — say an
+800×200 banner across the top of the page — produces no gap at all and the check passes without a
+word. `"compare": { "extras": "list" }` adds a list of such elements to the report. **It only
+lists**: the gate, the exit code, the fidelity score, the `summary` counts and `--baseline` are exactly
+what they would be without it. The anonymous statistics gain one number, how many such elements were
+found, and never which ones. The default is `"none"`; any value
+other than `none` / `list` is a config error (exit 2) — it is a string, not a boolean, so a typo
+like `"false"` fails loudly.
+
+An element on the page is listed when all of these hold:
+
+- it is not matched, and it is not an ancestor of a matched element (those are layout containers);
+- it is not inside a matched design **leaf** (how a button or an image is built inside is an
+  implementation detail), nor inside a matched element none of whose design children matched
+  (those children are already in the unmatched list — listing the page side too would report the
+  same gap twice);
+- it is visible: it has text of its own, is an `img` or `svg`, or has a background that is not
+  fully transparent;
+- at least **64×64 = 4,096 px²** of it lies inside the viewport the page was rendered at (by
+  default the design frame's size). The threshold is deliberately conservative — icons, hairlines
+  and a single short word stay below it — and not configurable in this first version.
+
+Nested elements are listed once, at the outermost one that qualifies. `ignore` selectors apply as
+usual, and `check --reverse` never computes the list. `check` prints the list and `--md` / `parity
+report` add a table when there is something to show; the local report UI and the dashboard do not
+show it yet (the dashboard keeps it as part of the raw report). Known limits: the capture does not
+record borders, shadows, `opacity` or clipping, so **an element that is visible only through its
+border is not listed**, while one hidden by `opacity: 0`, by an ancestor's `overflow: hidden` or
+under another element can be.
 
 ## Architecture
 
@@ -455,8 +608,8 @@ Behaviour:
   "Report a misjudgment" link to the issue form — a link only, nothing is sent) and keeps
   updating that same comment instead of adding new ones — so PMs and reviewers see it without
   ever touching the tool.
-- **Blocks the PR**: gaps beyond `gate.failOn` → exit 1 → red PR. (**The comment is posted
-  first, then the gate is enforced.**)
+- **Blocks the PR**: gaps beyond `gate.failOn` (or unmatched nodes whose reason is in
+  `gate.failOnUnmatched`) → exit 1 → red PR. (**The comment is posted first, then the gate is enforced.**)
 - **Artifacts**: `report.json` plus the Markdown report are uploaded for download (artifact
   name `parity-report` unless you set `artifact-name`; `report.json` and `parity-report.md` at its
   root). `report.json` is picked up from `.parity/report.json` next to the config file — where
@@ -491,8 +644,9 @@ Action inputs: `config` / `target` / `working-directory` / `version` / `figma-to
 
 - **Unknown keys** — consumers must ignore keys they do not recognize. Within 2.x, `report.json` only *gains* fields; existing keys are never removed, renamed or given a different type (that would be 3.0). Closed sets below never gain members within 2.x either.
 - `severity` — **closed set** (spelling and membership frozen): `none` / `minor` / `medium` / `serious` / `critical`. `status`: `mismatch` / `missing`.
-- `unmatched[].reason` — **open set**: parsers must tolerate unknown values; known spellings never change. Currently: `no-anchor`, `ambiguous-or-missing-text`, `randomized-id`, `size-implausible`.
+- `unmatched[].reason` — **open set**: parsers must tolerate unknown values; known spellings never change. Currently: `no-anchor`, `ambiguous-or-missing-text`, `text-not-found`, `randomized-id`, `size-implausible`.
 - `nodes[].matchedBy` — **open set**, same rule. Currently: `selector`, `explicit`, `auto-text`, `auto-name`, `auto-container`.
+- `extras` (per report, `compare.extras`) — `null` when the list is off (the default, `check --reverse`, and every report written before the field existed); otherwise `{ "total": n, "items": [{ "selector", "tag", "box" }] }`, where `total: 0` with empty `items` means "on, nothing found". `items` is sorted largest first and capped at 20 per page; `total` counts them all. Items carry no element text. Never affects the gate or the score.
 - `direction` (top level, since 2.0.0) — **closed set**: `forward` (a normal `check`) / `reverse` (`check --reverse`: expected and actual swapped, never gated). Always written; files without it read as `forward`. Readers accept exactly the lowercase strings `"forward"` and `"reverse"` — any other value (other casing, a number, `null`) is an error, not a guess. `parity report` does not gate a reverse report, and `parity push` refuses one.
 
 ## Regression gating: baselines (M5)
@@ -515,6 +669,7 @@ parity baseline list     # Browse snapshot history (the score column is the fide
 
 - **New** (absent from the baseline, present now) or **worsened** (higher severity) → exit 1, PR blocked
 - **Fixed** (in the baseline, gone now) is listed as encouragement; **unchanged** existing gaps do not gate
+- `gate.failOnUnmatched` is not applied in this mode (once a baseline exists); unmatched nodes are listed as usual
 - Ideal for gradual adoption: record reality with `baseline save`, then run `check --baseline` in
   CI, and all the team has to commit to is "do not make fidelity worse"
 
@@ -570,10 +725,13 @@ for, how long it is kept — is **<https://stats.cornhsu.com/>**.
 | `data.designSource` | `figma`, `snapshot` (a file written by `parity snapshot`), `file` (any other design JSON) or `image` |
 | `data.designNodes`, `data.matched` | Design nodes and matched nodes, summed over all pages |
 | `data.severity` | Gap counts per severity: `critical`, `serious`, `medium`, `minor` |
-| `data.props` | For each property with at least one gap: how many gaps, how many were `missing`, and how many fall in each range of `abs(delta)` — px for lengths (`offsetX`/`offsetY`, size, padding, `itemSpacing`, `cornerRadius`, `fontSize`, `lineHeight`, `letterSpacing`: <1, 1–2, 2–4, 4–8, 8–16, 16–32, ≥32), ΔE for `color`/`background` (<1, 1–2, 2–5, 5–10, 10–20, ≥20), and weight steps for `fontWeight` (<100, 100–200, 200–300, ≥300). `fontFamily` has no ranges, only counts |
+| `data.props` | For each property with at least one gap: how many gaps, how many were `missing`, and how many fall in each range of `abs(delta)` — px for lengths (`offsetX`/`offsetY`, size, padding, `itemSpacing`, `cornerRadius`, `fontSize`, `lineHeight`, `letterSpacing`, `borderWidth`, `shadow`, `mainAxisOffset`, `crossAxisOffset`: <1, 1–2, 2–4, 4–8, 8–16, 16–32, ≥32), ΔE for `color`, `background`, `borderColor`, `shadowColor`, `gradient` (<1, 1–2, 2–5, 5–10, 10–20, ≥20), weight steps for `fontWeight` (<100, 100–200, 200–300, ≥300), a 0–1 difference for `opacity` and `image` (<0.05, 0.05–0.1, 0.1–0.25, 0.25–0.5, ≥0.5), and lines for `lineCount` (1, 2, 3–4, 5 or more). `fontFamily`, `text`, `childOrder`, `fontStyle`, `textDecoration`, `textTransform`, `textAlign` have no ranges, only counts: never the text, the layer names or the values |
+| `data.unmatchedBy` | Design nodes that could not be matched, counted per reason: `no-anchor`, `ambiguous-or-missing-text`, `text-not-found`, `randomized-id`, `size-implausible`, or `other` for any reason this version does not list. Only reasons with at least one node; `{}` when everything matched. Never the layer names |
+| `data.extras` | How many extra page elements `compare.extras` found, summed over all pages (the total, before the 20-per-page cap). Only present when the list is on. Never their selectors, tags or boxes |
 
 **Never sent:** URLs, routes, page or layer names, selectors, file names or paths, screenshots, colour
-values, design content, tokens, repository names or IDs, user names, machine names. The request has no
+values, design content, text from the page or the design, image contents or image hashes, tokens,
+repository names or IDs, user names, machine names. The request has no
 User-Agent and no cookies. The collector does not store IP addresses or the time a record arrived (only
 its date); Cloudflare, which hosts the collector, sees the connection address at its edge, as any network
 provider does.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cornhsu-parity",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Property-Level Design QA that can gate your CI. Compares real numeric values from your Figma file against the rendered UI and fails the PR when the implementation drifts from the design.",
   "keywords": [
     "figma",
@@ -34,11 +34,11 @@
     "node": ">=20"
   },
   "optionalDependencies": {
-    "@cornhsu/parity-win32-x64": "2.1.0",
-    "@cornhsu/parity-win32-arm64": "2.1.0",
-    "@cornhsu/parity-linux-x64": "2.1.0",
-    "@cornhsu/parity-linux-arm64": "2.1.0",
-    "@cornhsu/parity-darwin-x64": "2.1.0",
-    "@cornhsu/parity-darwin-arm64": "2.1.0"
+    "@cornhsu/parity-win32-x64": "2.3.0",
+    "@cornhsu/parity-win32-arm64": "2.3.0",
+    "@cornhsu/parity-linux-x64": "2.3.0",
+    "@cornhsu/parity-linux-arm64": "2.3.0",
+    "@cornhsu/parity-darwin-x64": "2.3.0",
+    "@cornhsu/parity-darwin-arm64": "2.3.0"
   }
 }