reg-cli 0.18.16 → 0.19.0-rc1

package/dist/cli.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import { t as writeXimgdiffAssets } from "./ximgdiff-D8GAJaxA.mjs";
+import { dir, run } from "./index.mjs";
+import { createRequire } from "node:module";
+import { copyFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { parseArgs } from "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 = createRequire(import.meta.url)("../package.json");
+		process.stdout.write(`${pkg.version ?? "unknown"}\n`);
+	} catch {
+		process.stdout.write("unknown\n");
+	}
+	process.exit(0);
+}
+let parsed;
+try {
+	parsed = 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 ? join(actualDir, p) : p;
+const emitter = 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 writeXimgdiffAssets({
+			reportPath: values.report,
+			urlPrefix: typeof values.urlPrefix === "string" ? values.urlPrefix : "",
+			distDir: 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(join(expectedDir, img), { force: true });
+	const toCopy = [...items.newItems, ...items.failedItems];
+	for (const img of toCopy) {
+		const src = join(actualDir, img);
+		const dst = join(expectedDir, img);
+		await mkdir(dirname(dst), { recursive: true });
+		await copyFile(src, dst);
+	}
+}
+//#endregion
+export {};

package/dist/index.cjs

@@ -0,0 +1,212 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_tracing = require("./tracing-Cf9TNPXQ.cjs");
+let node_events = require("node:events");
+node_events = require_tracing.__toESM(node_events, 1);
+let node_worker_threads = require("node:worker_threads");
+let url = require("url");
+let node_path = require("node:path");
+//#region src/index.ts
+const dir = () => {
+	return require_tracing.isCJS ? __dirname : (0, node_path.dirname)((0, url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
+};
+const mainSpans = [];
+const recordMainSpan = (name, start_ms, attributes) => {
+	if (!require_tracing.isTracingEnabled()) return;
+	mainSpans.push({
+		name,
+		start_ms,
+		end_ms: Date.now(),
+		attributes,
+		worker_label: "main"
+	});
+};
+const run = (argv) => {
+	const emitter = new node_events.default();
+	setImmediate(() => emitter.emit("start"));
+	runInternal(argv, emitter);
+	return emitter;
+};
+const runInternal = async (argv, emitter) => {
+	const run_start_ms = Date.now();
+	const t_init = Date.now();
+	if (require_tracing.isTracingEnabled()) {
+		await require_tracing.initTracing();
+		recordMainSpan("main.init_tracing", t_init);
+	}
+	const traceContext = require_tracing.isTracingEnabled() ? require_tracing.startRootSpan("reg-cli") : null;
+	const t_new_entry = Date.now();
+	const worker = new node_worker_threads.Worker((0, node_path.join)(dir(), `./runner.${require_tracing.resolveExtention()}`), { workerData: {
+		argv,
+		mode: "entry"
+	} });
+	recordMainSpan("main.new_entry_worker", t_new_entry);
+	let nextTid = 1;
+	const workers = [worker];
+	const threadWorkerSpans = [];
+	const attachCommonHandlers = (w) => {
+		w.on("message", (msg) => {
+			switch (msg.cmd) {
+				case "compare-event":
+					if (msg.event) emitter.emit("compare", msg.event);
+					return;
+				case "thread-spawn":
+					spawn(msg.startArg, msg.threadId, msg.memory);
+					return;
+				case "worker-spans":
+					if (Array.isArray(msg.workerSpans)) threadWorkerSpans.push(...msg.workerSpans);
+					return;
+				case "loaded":
+					if (typeof w.unref === "function") w.unref();
+					return;
+			}
+		});
+		w.on("error", (e) => {
+			if (traceContext) require_tracing.endRootSpan(false);
+			workers.forEach((x) => x.terminate());
+			emitter.emit("error", e);
+		});
+	};
+	const spawn = (startArg, threadId, memory) => {
+		const t_new_worker = Date.now();
+		const w = new node_worker_threads.Worker((0, node_path.join)(dir(), `./runner.${require_tracing.resolveExtention()}`), { workerData: {
+			argv,
+			mode: "thread"
+		} });
+		const tid = nextTid++;
+		recordMainSpan("main.new_thread_worker", t_new_worker, { tid });
+		workers.push(w);
+		attachCommonHandlers(w);
+		if (threadId) {
+			Atomics.store(threadId, 0, tid);
+			Atomics.notify(threadId, 0);
+		}
+		w.postMessage({
+			startArg,
+			tid,
+			memory
+		});
+		return tid;
+	};
+	attachCommonHandlers(worker);
+	worker.on("message", async (msg) => {
+		if (msg.cmd !== "complete") return;
+		const { data, traceData, workerSpans } = msg;
+		const t_post_complete = Date.now();
+		if (require_tracing.isTracingEnabled()) {
+			if (Array.isArray(workerSpans)) require_tracing.processWorkerSpans(workerSpans, "entry");
+			if (threadWorkerSpans.length) require_tracing.processWorkerSpans(threadWorkerSpans, "thread");
+			if (traceData) require_tracing.processRustTraceData(traceData);
+			recordMainSpan("main.process_trace_and_spans", t_post_complete);
+			mainSpans.push({
+				name: "main.run_total",
+				start_ms: run_start_ms,
+				end_ms: Date.now(),
+				worker_label: "main"
+			});
+			require_tracing.processWorkerSpans(mainSpans, "main");
+			require_tracing.endRootSpan(true);
+			await require_tracing.shutdownTracing();
+		}
+		workers.forEach((w) => w.terminate());
+		emitter.emit("complete", data);
+	});
+};
+/** Flags that `compare()` handles itself in JS; they are NOT forwarded to
+*  the Wasm binary. `extendedErrors` WAS here but now also feeds the
+*  Rust-side junit generator, so it's forwarded below via KEY_REMAP.
+*
+*  `ignoreChange` and `enableCliAdditionalDetection` are stripped because
+*  reg-suit unconditionally passes them (see
+*  reg-viz/reg-suit `packages/reg-suit-core/src/processor.ts` `compare({…})`)
+*  and the Rust clap layer doesn't recognise them — forwarding would abort
+*  the binary with "unexpected argument". Semantically both are no-ops at
+*  the library-event layer:
+*    - `ignoreChange` only governs classic reg-cli's process exit code;
+*      the EventEmitter surface never needed it.
+*    - `enableCliAdditionalDetection` was classic's flag for running an
+*      extra CLI-side x-img-diff pass; the Wasm port's diff pipeline
+*      already produces the final pass/fail classification, so toggling
+*      it changes nothing. (The *client*-side variant is handled via
+*      `additionalDetection: 'client'` / the legacy
+*      `enableClientAdditionalDetection: true` alias further down.) */
+const CLI_ONLY_KEYS = new Set([
+	"update",
+	"ignoreChange",
+	"enableCliAdditionalDetection"
+]);
+/** Library option names that must be forwarded to the Wasm binary under a
+*  different flag name (Rust uses `--junit`, callers pass `junitReport`). */
+const KEY_REMAP = { junitReport: "junit" };
+const compare = (input) => {
+	const { actualDir, expectedDir, diffDir, threshold, update, ...rest } = input;
+	if (rest.diffFormat == null) rest.diffFormat = "png";
+	if (rest.json == null) rest.json = "./reg.json";
+	if (threshold != null && rest.thresholdRate == null) rest.thresholdRate = threshold;
+	const restAny = rest;
+	if (restAny.enableClientAdditionalDetection && restAny.additionalDetection == null) restAny.additionalDetection = "client";
+	delete restAny.enableClientAdditionalDetection;
+	for (const k of CLI_ONLY_KEYS) delete rest[k];
+	const inner = run([
+		"--",
+		actualDir,
+		expectedDir,
+		diffDir,
+		...Object.entries(rest).flatMap(([k, v]) => {
+			if (v == null || v === "") return [];
+			return [`--${KEY_REMAP[k] ?? k}`, String(v)];
+		})
+	]);
+	const outer = new node_events.default();
+	inner.on("start", () => outer.emit("start"));
+	inner.on("compare", (p) => outer.emit("compare", p));
+	inner.on("error", (e) => outer.emit("error", e));
+	inner.on("complete", async (data) => {
+		try {
+			if (restAny.additionalDetection === "client" && typeof input.report === "string") {
+				const { writeXimgdiffAssets } = await Promise.resolve().then(() => require("./ximgdiff-B16oe7EL.cjs")).then((n) => n.ximgdiff_exports);
+				await writeXimgdiffAssets({
+					reportPath: input.report,
+					urlPrefix: typeof input.urlPrefix === "string" ? input.urlPrefix : "",
+					distDir: dir()
+				});
+			}
+			if (update) {
+				await updateExpected(actualDir, expectedDir, {
+					newItems: data.newItems ?? [],
+					failedItems: data.failedItems ?? [],
+					deletedItems: data.deletedItems ?? []
+				});
+				outer.emit("update");
+			}
+		} catch (e) {
+			outer.emit("error", e);
+			return;
+		}
+		outer.emit("complete", data);
+	});
+	return outer;
+};
+async function writeRegJson(path, data) {
+	const { writeFile, mkdir } = await import("node:fs/promises");
+	const { dirname } = await import("node:path");
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+async function updateExpected(actualDir, expectedDir, items) {
+	const { mkdir, copyFile, rm } = await import("node:fs/promises");
+	const { dirname, join } = await import("node:path");
+	const toRemove = [...items.deletedItems, ...items.failedItems];
+	for (const img of toRemove) await rm(join(expectedDir, img), { force: true });
+	const toCopy = [...items.newItems, ...items.failedItems];
+	for (const img of toCopy) {
+		const src = join(actualDir, img);
+		const dst = join(expectedDir, img);
+		await mkdir(dirname(dst), { recursive: true });
+		await copyFile(src, dst);
+	}
+}
+//#endregion
+exports.compare = compare;
+exports.dir = dir;
+exports.run = run;
+exports.writeRegJson = writeRegJson;

package/dist/index.d.cts

@@ -0,0 +1,52 @@
+import EventEmitter from "node:events";
+
+//#region src/index.d.ts
+declare const dir: () => string;
+declare const run: (argv: string[]) => EventEmitter;
+type CompareInput = {
+  actualDir: string;
+  expectedDir: string;
+  diffDir: string;
+  report?: string;
+  junitReport?: string;
+  json?: string; /** Re-render HTML from an existing reg.json (classic `-F/--from`). */
+  from?: string;
+  /** "none" (default) | "client" — enable the report's browser-side
+   *  second-pass detector (classic `-X/--additionalDetection`). */
+  additionalDetection?: 'none' | 'client';
+  update?: boolean;
+  extendedErrors?: boolean;
+  /** Classic reg-cli's `-I/--ignoreChange` — governs the CLI's exit code
+   *  only. Accepted and silently dropped by `compare()` for drop-in
+   *  compat with reg-suit's `processor.ts:107`. */
+  ignoreChange?: boolean;
+  urlPrefix?: string;
+  matchingThreshold?: number;
+  threshold?: number;
+  thresholdRate?: number;
+  thresholdPixel?: number;
+  concurrency?: number;
+  enableAntialias?: boolean;
+  enableClientAdditionalDetection?: boolean;
+  /** Classic reg-cli's CLI-side x-img-diff extra detection pass. The
+   *  Wasm pipeline's diff already includes the equivalent classification,
+   *  so this is a no-op but accepted for drop-in compat with reg-suit's
+   *  `processor.ts:114`. */
+  enableCliAdditionalDetection?: boolean;
+};
+type CompareOutput = {
+  failedItems: string[];
+  newItems: string[];
+  deletedItems: string[];
+  passedItems: string[];
+  expectedItems: string[];
+  actualItems: string[];
+  diffItems: string[];
+  actualDir: string;
+  expectedDir: string;
+  diffDir: string;
+};
+declare const compare: (input: CompareInput) => EventEmitter;
+declare function writeRegJson(path: string, data: CompareOutput): Promise<void>;
+//#endregion
+export { CompareInput, CompareOutput, compare, dir, run, writeRegJson };

package/dist/index.d.mts

@@ -0,0 +1,52 @@
+import EventEmitter from "node:events";
+
+//#region src/index.d.ts
+declare const dir: () => string;
+declare const run: (argv: string[]) => EventEmitter;
+type CompareInput = {
+  actualDir: string;
+  expectedDir: string;
+  diffDir: string;
+  report?: string;
+  junitReport?: string;
+  json?: string; /** Re-render HTML from an existing reg.json (classic `-F/--from`). */
+  from?: string;
+  /** "none" (default) | "client" — enable the report's browser-side
+   *  second-pass detector (classic `-X/--additionalDetection`). */
+  additionalDetection?: 'none' | 'client';
+  update?: boolean;
+  extendedErrors?: boolean;
+  /** Classic reg-cli's `-I/--ignoreChange` — governs the CLI's exit code
+   *  only. Accepted and silently dropped by `compare()` for drop-in
+   *  compat with reg-suit's `processor.ts:107`. */
+  ignoreChange?: boolean;
+  urlPrefix?: string;
+  matchingThreshold?: number;
+  threshold?: number;
+  thresholdRate?: number;
+  thresholdPixel?: number;
+  concurrency?: number;
+  enableAntialias?: boolean;
+  enableClientAdditionalDetection?: boolean;
+  /** Classic reg-cli's CLI-side x-img-diff extra detection pass. The
+   *  Wasm pipeline's diff already includes the equivalent classification,
+   *  so this is a no-op but accepted for drop-in compat with reg-suit's
+   *  `processor.ts:114`. */
+  enableCliAdditionalDetection?: boolean;
+};
+type CompareOutput = {
+  failedItems: string[];
+  newItems: string[];
+  deletedItems: string[];
+  passedItems: string[];
+  expectedItems: string[];
+  actualItems: string[];
+  diffItems: string[];
+  actualDir: string;
+  expectedDir: string;
+  diffDir: string;
+};
+declare const compare: (input: CompareInput) => EventEmitter;
+declare function writeRegJson(path: string, data: CompareOutput): Promise<void>;
+//#endregion
+export { CompareInput, CompareOutput, compare, dir, run, writeRegJson };