cornhsu-parity 2.0.0 → 2.2.0

package/README.md

@@ -63,11 +63,11 @@ PR comment, updating the same comment rather than adding new ones.
 
 | | |
 |---|---|
-| Releases | 28 on NuGet (v0.1.0 → v2.0.0). Pushing a tag publishes via OIDC Trusted Publishing — zero long-lived keys in the repo |
+| Releases | 30 on NuGet (v0.1.0 → v2.2.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 | **805**, covering the CIEDE2000 reference data set (Sharma), match disambiguation, position false-positive guards, image sampling, and real-browser capture regressions |
+| Tests | **1068**, 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,6 +89,46 @@ 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, and for each measured property how many gaps and how large, in
+  ranges. 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, 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
@@ -97,6 +137,7 @@ parity install-browser     # Download Playwright Chromium: on first run, and aga
                            #   upgrade if check says Chromium is not installed
 export FIGMA_TOKEN=...     # Only the file_content:read scope is needed
 parity check               # Compare; writes a report and sets the exit code
+                           #   (--stats-preview: print the anonymous statistics it would send, send nothing)
 parity report              # Re-render the Markdown report from an existing report.json
                            #   (no re-scan; --md writes a file, otherwise it prints to stdout)
 parity snapshot            # Freeze the currently rendered UI as the design baseline —
@@ -108,7 +149,7 @@ parity lint                # Design lint: are the design file's values inside th
 parity check --reverse     # Reverse view, for a designer redrawing an existing page:
                            #   how does my draft differ from what ships? (never gates)
 parity bug-report          # (experimental) Collect version / OS / Node / Chromium info and print
-                           #   it with a pre-filled GitHub issue link. Parity itself connects to nothing;
+                           #   it with a pre-filled GitHub issue link. bug-report itself connects to nothing;
                            #   opening the link sends the masked report to github.com (it rides in
                            #   the URL). No issue until you submit the form. --config adds a
                            #   structural summary without URLs, routes, keys, tokens or paths
@@ -144,7 +185,9 @@ serious-severity gaps — which is exactly the behaviour you want from a CI gate
   "gate": {
     "failOn": ["critical", "serious"],       // any of minor / medium / serious / critical, one per string
     "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;
+                                             //   see "Anonymous usage statistics" below (also projectId)
 }
 ```
 
@@ -337,6 +380,51 @@ There are three shells, and **the engine does not know that any of them exist**:
 > setting, and the integration tests inject one that a developer's `PARITY_SERVER_DB` must not
 > redirect.
 
+### One dashboard, two tools
+
+The same server also takes reports from **[XamlContrast](https://github.com/HSU-YU-MING/cornhsu-xamlcontrast)**
+(the static WCAG contrast audit for XAML apps): `xamlcontrast --push <report.json>` sends the file
+its `--json` option wrote, through the same `POST /api/runs`, marked with an `X-Parity-Tool: xamlcontrast`
+header (`parity push` sends no such header, which the server reads as `parity`). A project can hold runs
+from both tools. XamlContrast runs get their own overview card per project (pairs below AA, fail · warn,
+coverage), a fail/warn trend, and an issue list (file and line, element, foreground and background as
+written in the XAML, the ratio in each theme, the threshold). Each XamlContrast run also shows what changed
+since the previous XamlContrast run on the same branch — new, worse, fixed and improved pairs — compared the
+way XamlContrast's own `--baseline` does (a pair is file, element, foreground and background, without the line
+number; more places or a lower worst ratio is worse). Like `parity push`, the XamlContrast side is
+**experimental** until the dashboard is publicly deployed.
+
+### Hosting it yourself
+
+The repo root has a `Dockerfile`. The image contains the server, its data layer and the report types,
+and nothing else: no browser, no engine (CI checks this).
+
+```sh
+docker build -t parity-server .
+docker run -d --name parity -p 8080:8080 -v parity-data:/data \
+  -e Parity__PublicUrl=https://parity.example.com \
+  -e ASPNETCORE_FORWARDEDHEADERS_ENABLED=true \
+  parity-server
+docker exec parity dotnet Parity.Server.dll create-project my-site          # prints the CI token once
+docker exec parity dotnet Parity.Server.dll create-invite my-site you@example.com owner
+```
+
+| Setting | What it does |
+|---|---|
+| `Parity__PublicUrl` | The address people open. Invite links are built from it, not from the `Host` the server sees (behind a proxy that can be an internal name). It must be an absolute `http(s)` URL; a bad value stops the server and the admin commands. |
+| `Parity__KeysDirectory` | Where the keys that sign the login cookie live. Preset to `/data/keys` in the image. Without it, every redeploy of a container signs everyone out. |
+| `PARITY_SERVER_DB` | The SQLite database. Preset to `/data/parity-server.db` in the image. |
+| `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true` | Behind a reverse proxy, **required**, and only behind a proxy you trust (otherwise anyone can forge their client IP). Without it the server sees one IP for everybody, and a single person can lock all users out of login with 20 attempts a minute. |
+
+- **Everything lives in `/data`**: mount a volume there. TLS is the job of the proxy or platform in front.
+- **Run one instance.** The database is SQLite and login attempts are serialized inside one process;
+  more than one instance needs a different database first.
+- **Backups**: `docker exec parity dotnet Parity.Server.dll backup /data/backup-2026-10-26.db` writes a
+  consistent copy while the server keeps running (SQLite `VACUUM INTO`; it never overwrites a file and
+  never creates a missing database). Copy it off the machine. To restore: stop the server, put the copy
+  where the database was, start it again.
+- **Uptime**: `GET /healthz` is anonymous and answers `ok` only when the database answers, `503` otherwise.
+
 ### The iron rule: the cloud never runs a browser
 
 `Parity.Server`'s only endpoint that takes in scan results is `POST /api/runs` (its other
@@ -413,10 +501,13 @@ Behaviour:
   own artifact and keeps its own PR comment; two calls with the same name collide on the artifact upload.
   Two calls in **one job** work only while the first one passes: when its gate fails, the job stops at
   that call's last step and the second call never runs (no report, no comment, no artifact for it).
+- **Anonymous usage statistics**: on by default ([what and why](#anonymous-usage-statistics));
+  `share-stats: false` turns them off. The job summary gets one line saying whether they were sent, or why not.
 
 Action inputs: `config` / `target` / `working-directory` / `version` / `figma-token` /
 `baseline` (regression mode) / `comment` (turn off the PR comment) / `upload-report` /
-`artifact-name` (default `parity-report`; letters, digits, `.`, `_`, `-`, at most 100 characters, not starting with `-` and not only dots).
+`artifact-name` (default `parity-report`; letters, digits, `.`, `_`, `-`, at most 100 characters, not starting with `-` and not only dots) /
+`share-stats` (default `true`; exactly `true` or `false` — anything else stops the action before it installs Parity).
 
 > The action installs the tool with `dotnet tool install -g Cornhsu.Parity` (published on
 > nuget.org) — the latest 2.x when `version` is omitted, so `@v2` never jumps to a future 3.x,
@@ -480,15 +571,95 @@ file is released immediately), and the engine's `BaselineComparer` is a pure, un
   yet, so the command and its server protocol may change in a 2.x minor release and join the interface
   freeze once the server ships) sends a finished `report.json` to a server you host yourself; the dashboard renders the gaps as an engineering blueprint drawn from the
   measured coordinates (no screenshot upload), an overview and score trend per project and
-  route, and accounts / project roles / invite links. Its own internal M1–M4.6 are done; its
-  M5 (real external deployment: TLS, a domain, a hosted database) is not. **It receives
+  route, and accounts / project roles / invite links. It also takes XamlContrast reports
+  ([one dashboard, two tools](#one-dashboard-two-tools)). Its own internal M1–M4.6 are done; of its
+  M5, the deployment groundwork is done (a Docker image, the public URL, persisted sign-in keys,
+  online backups), the actual hosting (a host, a domain, TLS) is not. **It receives
   reports, it never scans** — see the iron rule above.
 
 > Open work, known blind spots and the next priorities are in [ROADMAP.md](ROADMAP.md);
 > version history is in [CHANGELOG.md](CHANGELOG.md).
 
+## Anonymous usage statistics
+
+From 2.1.0, `parity check` sends **anonymous usage statistics**, once per run — **on by default, in CI
+too**. They are counts and score ranges used for **academic research** on how far real
+implementations drift from their designs; only aggregate results are published. The public data page — what is collected, what it is used
+for, how long it is kept — is **<https://stats.cornhsu.com/>**.
+
+**When.** Only `parity check`, and only when it produced a report (exit 0, 1 or 3). `--reverse`,
+`--stats-preview`, every other command and any run that ends in exit 2 send nothing.
+
+**Everything that is sent:**
+
+| Field | Meaning |
+|---|---|
+| `schema`, `tool` | Always `1` and `"parity"` |
+| `toolVersion` | The Parity version, e.g. `2.1.0` (no commit hash) |
+| `os` | `windows`, `linux`, `macos` or `other` |
+| `ci` | Whether `CI` or `GITHUB_ACTIONS` is `true` |
+| `projectId` | `null`, unless you set `stats.projectId` yourself (see below) |
+| `data.score` | The fidelity score `check` printed (0–100) |
+| `data.gateFailed` | Whether `check`'s exit code was not 0 (so `--baseline` and exit 3 count as they did in your CI) |
+| `data.pages` | How many targets the report covers |
+| `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 |
+
+**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
+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.
+
+**No ID unless you add one.** Without `stats.projectId`, nothing links one run to another or to you —
+which also means a record cannot be picked out and deleted afterwards. If you want your runs counted as
+one project (and deletable on request), make up a random ID — for example `openssl rand -hex 12`, or
+`[guid]::NewGuid().ToString('N')` in PowerShell. Parity never derives one from your repository, paths or
+machine, and an ID that is not 16–64 characters of `A–Z a–z 0–9 _ -` is a config error (exit 2):
+
+```jsonc
+"stats": {
+  "share": true,                                  // false turns statistics off
+  "projectId": "REPLACE-with-your-own-random-id"  // optional; never copy someone else's
+}
+```
+
+**Preview.** `parity check --stats-preview` runs the check as usual, sends nothing, and prints the exact
+JSON to stderr, followed by whether it would be sent — or why not. The exit code, stdout and the report
+files are unchanged.
+
+**Turning it off.** Any one of these is enough; they are checked in this order, and the first that says
+no wins:
+
+1. `DO_NOT_TRACK` set to anything except `0` or `false` — always wins.
+2. `CORNHSU_SHARE_STATS` (shared with [XamlContrast](https://github.com/HSU-YU-MING/cornhsu-xamlcontrast))
+   or `PARITY_SHARE_STATS` set to `false` — in fact any value other than `1`, `true`, `yes` or `on`, so a
+   typo errs on the side of *not* sending.
+3. `"stats": { "share": false }` in `parity.config.json`.
+4. The GitHub Action's `share-stats: false` (it sets `PARITY_SHARE_STATS=false`).
+5. Builds from source and other non-release builds (any version starting with `0.0.0-`, such as `0.0.0-dev`) never send.
+
+Like every other key in the config, a misspelt one is ignored: `"stats": { "shrae": false }` turns
+nothing off. `--stats-preview` tells you whether a switch took effect.
+
+**Notice.** The first time `check` sends on a machine, it prints a short notice to stderr and leaves a
+marker file, `cornhsu/parity-stats-notice` in your user settings directory (`%APPDATA%` on Windows,
+`~/.config` elsewhere), so the notice is not repeated — delete the file to see it again. In CI it prints
+one line every time statistics were sent. Nothing is printed when nothing is sent, and nothing ever goes
+to stdout. The GitHub Action also writes one line to the job summary: sent, or why not.
+
+**Cost.** The request waits at most 1.5 s to connect and 3 s in total, is never retried and never follows
+a redirect. When it fails — offline, a firewall, the collector is down — nothing is printed and nothing
+else changes: the exit code, stdout, the report files and the PR comment are exactly what they would have
+been.
+
 ## Security
 
+- **What Parity connects to**: the Figma API (only with a Figma design source), the dashboard you name
+  for `parity push`, and `stats.cornhsu.com` for the [anonymous usage statistics](#anonymous-usage-statistics)
+  of `parity check` (unless turned off). The page under test is opened by the local browser. Nothing else.
 - The Figma token comes from an environment variable (`env:FIGMA_TOKEN`); it never reaches a log
   and never goes in a URL (it is sent as the `X-Figma-Token` header).
 - Fetched frames are cached in `.parity/cache` (add `.parity/` to your `.gitignore`), so re-runs do

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cornhsu-parity",
-  "version": "2.0.0",
+  "version": "2.2.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.0.0",
-    "@cornhsu/parity-win32-arm64": "2.0.0",
-    "@cornhsu/parity-linux-x64": "2.0.0",
-    "@cornhsu/parity-linux-arm64": "2.0.0",
-    "@cornhsu/parity-darwin-x64": "2.0.0",
-    "@cornhsu/parity-darwin-arm64": "2.0.0"
+    "@cornhsu/parity-win32-x64": "2.2.0",
+    "@cornhsu/parity-win32-arm64": "2.2.0",
+    "@cornhsu/parity-linux-x64": "2.2.0",
+    "@cornhsu/parity-linux-arm64": "2.2.0",
+    "@cornhsu/parity-darwin-x64": "2.2.0",
+    "@cornhsu/parity-darwin-arm64": "2.2.0"
   }
 }