reg-cli 0.18.16 → 0.19.0-rc0

package/README.md

@@ -1,16 +1,20 @@
-![reg-cli](./docs/reg-cli.jpg)
+![reg-cli](./.github/assets/reg-cli.jpg)
 
-![[Build Status](https://travis-ci.org/reg-viz/reg-cli)](https://travis-ci.org/reg-viz/reg-cli.svg?branch=master)
-![[Build Status](https://ci.appveyor.com/project/bokuweb/reg-cli)](https://ci.appveyor.com/api/projects/status/ir907qbc633q9na4?svg=true)
-![[npm package](https://www.npmjs.com/package/reg-cli)](https://img.shields.io/npm/v/reg-cli.svg)
-![[npm package downloads](https://www.npmjs.com/package/reg-cli)](https://img.shields.io/npm/dm/reg-cli.svg)
+[![CI](https://github.com/reg-viz/reg-cli/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/reg-viz/reg-cli/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/reg-cli.svg)](https://www.npmjs.com/package/reg-cli)
+[![npm downloads](https://img.shields.io/npm/dm/reg-cli.svg)](https://www.npmjs.com/package/reg-cli)
 
-> Visual regression test tool with html reporter.
+> Visual regression testing CLI with HTML reporter — **Wasm-backed**. Drop-in compatible with classic `reg-cli`'s flags, `reg.json` schema, JUnit XML output, and the `compare()` EventEmitter API used by [reg-suit](https://github.com/reg-viz/reg-suit).
+
+The diff engine is now **Rust → WebAssembly (WASI threads)** instead of pure JS, giving 1.1×–2.9× wall-clock speedups (see [Performance](#performance) below) while keeping the user-facing surface bit-for-bit compatible.
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [Usage](#usage)
+- [Performance](#performance)
+- [Architecture](#architecture)
+- [Building from source](#building-from-source)
 - [Test](#test)
 - [Contribute](#contribute)
 - [License](#license)
@@ -19,11 +23,9 @@
 
 ### Requirements
 
- - Node.js v18+
-
-`reg-cli` support Node.js v18+
+ - Node.js v20+
 
-``` sh
+```sh
 $ npm i -D reg-cli
 ```
 
@@ -31,65 +33,173 @@ $ npm i -D reg-cli
 
 ### CLI
 
-``` sh
+```sh
 $ reg-cli /path/to/actual-dir /path/to/expected-dir /path/to/diff-dir -R ./report.html
 ```
 
 ####  Options
 
-  * `-U`, `--update` Update expected images.(Copy \`actual images\` to \`expected images\`).
-  * `-R`, `--report` Output html report to specified directory.
-  * `-J`, `--json` Specified json report path. If omitted `./reg.json`
+  * `-U`, `--update` Update expected images. (Copy `actual` images to `expected` images.)
+  * `-R`, `--report` Output HTML report to specified path.
+  * `-J`, `--json` JSON report path. If omitted: `./reg.json`.
+  * `--junit` JUnit XML report path.
   * `-I`, `--ignoreChange` If true, error will not be thrown when image change detected.
   * `-E`, `--extendedErrors` If true, also added/deleted images will throw an error.
-  * `-P`, `--urlPrefix` Add prefix to all image src.
-  * `-M`, `--matchingThreshold` Matching threshold, ranges from 0 to 1. Smaller values make the comparison more sensitive. 0 by default. Specifically, you can set how much of a difference in the YIQ difference metric should be considered a different pixel. If there is a difference between pixels, it will be treated as "same pixel" if it is within this threshold.
-  * `-T`, `--thresholdRate` Rate threshold for detecting change. When the difference ratio of the image is larger than the set rate detects the change. Applied after `matchingThreshold`. 0 by default.
-  * `-S`, `--thresholdPixel` Pixel threshold for detecting change. When the difference pixel of the image is larger than the set pixel detects the change. This value takes precedence over `thresholdRate`. Applied after `matchingThreshold`. 0 by default.
-  * `-C`, `--concurrency` How many processes launches in parallel. If omitted 4.
-  * `-A`, `--enableAntialias` Enable antialias. If omitted false.
-  * `-X`, `--additionalDetection`. Enable additional difference detection(highly experimental). Select "none" or "client" (default: "none").
-  * `-F`, `--from` Generate report from json. Please specify json file. If set, only report will be output without comparing images.
-
-### html report
-
-If `-R` option set, output html report to specified directory.
+  * `-P`, `--urlPrefix` Add prefix to all image src in `reg.json`.
+  * `-M`, `--matchingThreshold` Matching threshold, ranges from 0 to 1. Smaller values make the comparison more sensitive. 0 by default. Tunes the YIQ pixel-difference threshold inside the diff lib.
+  * `-T`, `--thresholdRate` Rate threshold for detecting change. When the difference ratio of the image is larger than the set rate, change is reported. Applied after `matchingThreshold`. 0 by default.
+  * `-S`, `--thresholdPixel` Pixel threshold for detecting change. When the difference pixel count is larger than the set value, change is reported. This value takes precedence over `thresholdRate`. Applied after `matchingThreshold`. 0 by default.
+  * `-C`, `--concurrency` How many threads run the per-image diff in parallel. Default: 4. The Wasm version uses Rayon inside the WASI thread pool; below 20 images we fall back to single-threaded to avoid spin-up cost (matches classic reg-cli).
+  * `-A`, `--enableAntialias` Enable antialias-tolerant comparison. Off by default.
+  * `--diffFormat` Output diff image format: `webp` (default) or `png`. Use `png` for byte-for-byte parity with classic reg-cli's diff images.
+  * `-X`, `--additionalDetection` Enable additional difference detection (highly experimental). Select `none` (default) or `client` for the in-browser second-pass detector.
+  * `-F`, `--from` Generate report from an existing `reg.json` instead of running the comparison.
+  * `-D`, `--diffMessage` Custom diff message printed when a comparison fails.
+
+### HTML report
+
+If `-R` is set, an HTML report is written to the specified path.
 https://reg-viz.github.io/reg-cli/
 
-![open](./docs/open.png)
-![close](./docs/close.png)
-![viewer](./docs/viewer.png)
+![open](./.github/assets/open.png)
+![close](./.github/assets/close.png)
+![viewer](./.github/assets/viewer.png)
 
-### from json
+### From JSON
 
-If `-F` option set, only report will be output without comparing images.
+If `-F` is set, only the report is rendered — no image comparison runs.
 
-``` sh
-reg-cli.js -F ./sample/reg.json -R ./sample/index.html"
+```sh
+$ reg-cli -F ./sample/reg.json -R ./sample/index.html
 ```
 
-- json format
-``` json
+JSON format:
+
+```json
 {
     "failedItems": ["sample.png"],
-    "newItems":[],
-    "deletedItems":[],
-    "passedItems":[],
-    "expectedItems":["sample.png"],
-    "actualItems":["sample.png"],
-    "diffItems":["sample.png"],
-    "actualDir":"./actual",
-    "expectedDir":"./expected",
-    "diffDir":"./diff"
+    "newItems": [],
+    "deletedItems": [],
+    "passedItems": [],
+    "expectedItems": ["sample.png"],
+    "actualItems": ["sample.png"],
+    "diffItems": ["sample.png"],
+    "actualDir": "./actual",
+    "expectedDir": "./expected",
+    "diffDir": "./diff"
 }
 ```
 
+### Library
+
+```js
+import { compare } from 'reg-cli';
+
+const emitter = compare({
+  actualDir: './actual',
+  expectedDir: './expected',
+  diffDir: './diff',
+  json: './reg.json',
+  report: './report.html',
+  threshold: 0,
+});
+
+emitter.on('start', () => console.log('start'));
+emitter.on('compare', ({ type, path }) => console.log(type, path));
+emitter.on('error', (e) => console.error(e));
+emitter.on('complete', (data) => {
+  console.log(data.failedItems, data.newItems, data.deletedItems, data.passedItems);
+});
+```
+
+The full option set, event surface, and `CompareOutput` shape match what [`reg-suit`'s `processor.ts`](https://github.com/reg-viz/reg-suit/blob/main/packages/reg-suit-core/src/processor.ts) expects — a regression test in this repo locks that in (`test/library.test.mjs`).
+
+## Performance
+
+Apples-to-apples vs `reg-cli@0.18.16` (last legacy JS release), `--diffFormat png` on both sides, 5 timed runs after 1 warmup, median wall-clock on macOS (Apple Silicon) / Node v20.19.0:
+
+| Workload | JS reg-cli@0.18.16 | reg-cli@0.19.0-rc0 | Wasm speedup |
+|---|---:|---:|---:|
+| 20 × 1280×720 | 0.56 s | 0.49 s | **1.14×** |
+| 100 × 1280×720 | 1.94 s | 1.44 s | **1.35×** |
+| 1 × 3840×2160 (4K) | 1.89 s | 0.66 s | **2.86×** |
+
+The gap widens with image size and count: small fixtures are dominated by JS startup, but per-image compute is where the Rust + Rayon path shines. Wasm also has lower run-to-run variance than the JS version (±5% vs ±10% at 4K).
+
+The default `--diffFormat` is **webp**, which is a few % slower than PNG (the encoder is heavier) but produces ~5× smaller diff artefacts. Pass `--diffFormat png` for parity with classic reg-cli.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Node.js host (src/index.ts, src/cli.ts, src/entry.ts)      │
+│                                                             │
+│  • CLI argv parsing, EventEmitter API (`compare()`)         │
+│  • -U (update mode), -F (re-render from reg.json),          │
+│    -X client asset staging, -P urlPrefix application        │
+│  • Spawns the WASM entry as a worker_thread, then           │
+│    additional thread workers per Rayon thread spawn         │
+└──────────────────────────┬──────────────────────────────────┘
+                           │  worker_threads + WASI preopens
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Wasm32-WASIp1-threads bundle (reg.wasm, ~2.5 MB)           │
+│  Compiled from `crates/reg_cli` + `crates/reg_core`         │
+│                                                             │
+│  • clap CLI layer (crates/reg_cli/src/main.rs)              │
+│  • Image walker (crates/reg_core/src/dir.rs) — walks the    │
+│    actual/expected dirs, intersects, classifies new/del.    │
+│  • Per-image diff in a Rayon thread pool                    │
+│    (image-diff-rs → pixelmatch-rs port)                     │
+│  • Per-file errors are logged + folded into failedItems     │
+│    rather than aborting the run (matches classic reg-cli's  │
+│    fork-per-image tolerance).                               │
+│  • reg.json + JUnit XML + HTML report writers               │
+│    (templates: template/template.html, report/assets/*)     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Why Wasm instead of native?
+- **Portable** — the same `reg.wasm` runs on Linux, macOS, Windows. No prebuilds, no node-gyp.
+- **Sandboxed** — file I/O is constrained to WASI preopens declared from the JS host's positional dirs. A misbehaving image can't escape into your filesystem.
+- **Threading** — `wasm32-wasip1-threads` exposes `pthread`, so Rayon's `par_iter` works inside the sandbox; image diffs run in parallel across CPU cores.
+
+The `compare-event` channel from Rust to JS is implemented as a stderr-tagged line protocol (`__REG_CLI_EVT__\t{...}`) parsed by `src/progress.ts` and re-emitted on the EventEmitter. That's how live per-file `compare` events fire before `complete`.
+
+## Building from source
+
+`reg.wasm` is committed so most contributors don't need to install the Rust + wasi-sdk toolchain. To rebuild it (and the report-ui assets that `reg_core` embeds via `include_str!`):
+
+```sh
+# 1. Build report-ui (clones reg-cli-report-ui at v0.5.0, builds with pnpm)
+sh ./scripts/build-ui.sh v0.5.0
+
+# 2. Build reg.wasm (downloads wasi-sdk on first run, then cargo build --release)
+bash ./scripts/build-wasm.sh
+# or:  pnpm build:wasm
+
+# 3. Bundle everything into dist/
+pnpm build
+```
+
+One-shot publish prep (the same chain plus `npm pack`):
+
+```sh
+pnpm release:prep   # → npm pack --dry-run
+pnpm release:pack   # → writes the .tgz
+```
+
+`scripts/build-wasm.sh` works on macOS (arm64 / x86_64) and Linux (x86_64 / arm64). It auto-installs the `wasm32-wasip1-threads` rustup target if `rustup` is available.
+
 ## Test
 
 ```sh
-$ npm t
+$ pnpm test                              # → 50 node:test cases (CLI + library)
+$ cargo test -p reg_core --lib --locked  # → 12 Rust unit tests (Linux / macOS)
 ```
 
+CI runs both the JS tests and `cargo test` on Ubuntu and macOS. **Windows is not in the matrix:** Node's built-in WASI runtime returns `EINVAL` when the wasm bin writes to preopened relative paths (`reg.json` / `report.html` / `diff/*.png`) — a bug in Node's WASI path translation, not in `reg.wasm` itself. Until that's fixed upstream, Windows users should run reg-cli under WSL or git-bash; the wasm bin itself is OS-independent.
+
 ## Contribute
 
 PRs welcome.
@@ -107,4 +217,3 @@ The above copyright notice and this permission notice shall be included in all c
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ![reg-viz](https://raw.githubusercontent.com/reg-viz/artwork/master/repository/footer.png)
-

package/dist/cli.cjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+require("./rolldown-runtime-D_mwlA32.cjs");
+const require_index = require("./index.cjs");
+const require_ximgdiff = require("./ximgdiff-wmW1BH1H.cjs");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let node_module = require("node:module");
+let node_util = require("node:util");
+//#region src/cli.ts
+const HELP = `
+  Usage
+    $ reg-cli /path/to/actual-dir /path/to/expected-dir /path/to/diff-dir
+  Options
+    -U, --update              Update expected images (copy actual → expected).
+    -R, --report              Output html report to specified path.
+    -J, --json                Output json report to specified path (default ./reg.json).
+    -I, --ignoreChange        Exit 0 even when image changes are detected.
+    -E, --extendedErrors      Also treat added/deleted images as failures.
+    -F, --from                Render HTML report from an existing reg.json (no diff).
+    -X, --additionalDetection "none" | "client" — enable browser-side second-pass detection.
+    -P, --urlPrefix           Prefix for image src in html report.
+    -M, --matchingThreshold   YIQ threshold (0-1). Default 0.
+    -T, --thresholdRate       Ratio of pixels that may differ before failing.
+    -S, --thresholdPixel      Absolute pixel count that may differ before failing.
+    -C, --concurrency         Parallel worker count. Default 4.
+    -A, --enableAntialias     Count anti-aliased pixels as different.
+    -D, --customDiffMessage   Trailing message printed on diff.
+        --junit               Path to write a JUnit XML test report.
+        --diffFormat          webp (default) | png
+`;
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+	process.stdout.write(HELP);
+	process.exit(0);
+}
+if (process.argv.includes("--version")) {
+	try {
+		const pkg = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("../package.json");
+		process.stdout.write(`${pkg.version ?? "unknown"}\n`);
+	} catch {
+		process.stdout.write("unknown\n");
+	}
+	process.exit(0);
+}
+let parsed;
+try {
+	parsed = (0, node_util.parseArgs)({
+		args: process.argv.slice(2),
+		options: {
+			update: {
+				type: "boolean",
+				short: "U"
+			},
+			json: {
+				type: "string",
+				short: "J"
+			},
+			ignoreChange: {
+				type: "boolean",
+				short: "I"
+			},
+			extendedErrors: {
+				type: "boolean",
+				short: "E"
+			},
+			report: {
+				type: "string",
+				short: "R"
+			},
+			urlPrefix: {
+				type: "string",
+				short: "P"
+			},
+			matchingThreshold: {
+				type: "string",
+				short: "M"
+			},
+			thresholdRate: {
+				type: "string",
+				short: "T"
+			},
+			thresholdPixel: {
+				type: "string",
+				short: "S"
+			},
+			concurrency: {
+				type: "string",
+				short: "C"
+			},
+			enableAntialias: {
+				type: "boolean",
+				short: "A"
+			},
+			customDiffMessage: {
+				type: "string",
+				short: "D"
+			},
+			diffFormat: { type: "string" },
+			junit: { type: "string" },
+			from: {
+				type: "string",
+				short: "F"
+			},
+			additionalDetection: {
+				type: "string",
+				short: "X"
+			}
+		},
+		allowPositionals: true
+	});
+} catch (err) {
+	process.stderr.write(`reg-cli: ${err.message}\n`);
+	process.stderr.write(HELP);
+	process.exit(1);
+}
+const { values, positionals } = parsed;
+const [actualDir, expectedDir, diffDir] = positionals;
+const fromPath = typeof values.from === "string" ? values.from : void 0;
+if (!fromPath && (!actualDir || !expectedDir || !diffDir)) {
+	process.stderr.write("reg-cli: please specify actual, expected and diff directories.\n");
+	process.stderr.write(HELP);
+	process.exit(1);
+}
+const update = !!values.update;
+const ignoreChange = !!values.ignoreChange;
+const extendedErrors = !!values.extendedErrors;
+const diffFormat = typeof values.diffFormat === "string" ? values.diffFormat : "png";
+const jsonPath = typeof values.json === "string" ? values.json : "./reg.json";
+const customDiffMessage = typeof values.customDiffMessage === "string" ? values.customDiffMessage : `\nInspect your code changes, re-run with \`-U\` to update them. `;
+const wasmArgv = ["--"];
+if (actualDir) wasmArgv.push(actualDir);
+if (expectedDir) wasmArgv.push(expectedDir);
+if (diffDir) wasmArgv.push(diffDir);
+const pushFlag = (name, v) => {
+	if (v == null || v === false) return;
+	if (v === true) wasmArgv.push(`--${name}`);
+	else wasmArgv.push(`--${name}`, String(v));
+};
+pushFlag("report", values.report);
+pushFlag("json", jsonPath);
+pushFlag("junit", values.junit);
+pushFlag("extendedErrors", values.extendedErrors);
+pushFlag("from", fromPath);
+pushFlag("additionalDetection", values.additionalDetection);
+pushFlag("matchingThreshold", values.matchingThreshold);
+pushFlag("thresholdRate", values.thresholdRate);
+pushFlag("thresholdPixel", values.thresholdPixel);
+pushFlag("urlPrefix", values.urlPrefix);
+pushFlag("concurrency", values.concurrency);
+pushFlag("enableAntialias", values.enableAntialias);
+pushFlag("diffFormat", diffFormat);
+const CHECK = "✔";
+const CROSS = "✘";
+const PLUS = "✚";
+const MINUS = "−";
+const formatPath = (p) => actualDir ? (0, node_path.join)(actualDir, p) : p;
+const emitter = require_index.run(wasmArgv);
+emitter.once("complete", async (data) => {
+	const failed = data.failedItems ?? [];
+	const passed = data.passedItems ?? [];
+	const added = data.newItems ?? [];
+	const deleted = data.deletedItems ?? [];
+	if (values.additionalDetection === "client" && typeof values.report === "string") try {
+		await require_ximgdiff.writeXimgdiffAssets({
+			reportPath: values.report,
+			urlPrefix: typeof values.urlPrefix === "string" ? values.urlPrefix : "",
+			distDir: require_index.dir()
+		});
+	} catch (e) {
+		process.stderr.write(`reg-cli: failed to write ximgdiff assets — ${e.message}\n`);
+		process.exitCode = 1;
+	}
+	for (const img of passed) process.stdout.write(`${CHECK} pass    ${formatPath(img)}\n`);
+	for (const img of added) process.stdout.write(`${PLUS} append  ${formatPath(img)}\n`);
+	for (const img of deleted) process.stdout.write(`${MINUS} delete  ${formatPath(img)}\n`);
+	for (const img of failed) process.stdout.write(`${CROSS} change  ${formatPath(img)}\n`);
+	process.stdout.write("\n");
+	if (failed.length) process.stdout.write(`${CROSS} ${failed.length} file(s) changed.\n`);
+	if (deleted.length) process.stdout.write(`${MINUS} ${deleted.length} file(s) deleted.\n`);
+	if (added.length) process.stdout.write(`${PLUS} ${added.length} file(s) appended.\n`);
+	if (passed.length) process.stdout.write(`${CHECK} ${passed.length} file(s) passed.\n`);
+	if (update) {
+		if (!actualDir || !expectedDir) {
+			process.stderr.write(`reg-cli: --update requires actual/expected dirs (incompatible with --from).\n`);
+			process.exitCode = 1;
+			return;
+		}
+		try {
+			await updateExpected(actualDir, expectedDir, {
+				newItems: added,
+				failedItems: failed,
+				deletedItems: deleted
+			});
+			process.stdout.write("✨ your expected images are updated ✨\n");
+		} catch (e) {
+			process.stderr.write(`reg-cli: failed to update expected — ${e.message}\n`);
+			process.exitCode = 1;
+		}
+		return;
+	}
+	if (failed.length > 0 || extendedErrors && (added.length > 0 || deleted.length > 0)) {
+		process.stdout.write(`${customDiffMessage}\n`);
+		if (!ignoreChange) process.exitCode = 1;
+	}
+});
+emitter.once("error", (err) => {
+	process.stderr.write(`reg-cli: ${err?.message ?? String(err)}\n`);
+	process.exitCode = 1;
+});
+async function updateExpected(actualDir, expectedDir, items) {
+	const { rm } = await import("node:fs/promises");
+	const toRemove = [...items.deletedItems, ...items.failedItems];
+	for (const img of toRemove) await rm((0, node_path.join)(expectedDir, img), { force: true });
+	const toCopy = [...items.newItems, ...items.failedItems];
+	for (const img of toCopy) {
+		const src = (0, node_path.join)(actualDir, img);
+		const dst = (0, node_path.join)(expectedDir, img);
+		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(dst), { recursive: true });
+		await (0, node_fs_promises.copyFile)(src, dst);
+	}
+}
+//#endregion

package/dist/cli.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };