visual-regression-compare 0.0.0 → 1.0.0-beta.1

package/dist/comparer.d.ts

@@ -0,0 +1,94 @@
+import { ManifestWriter, type Manifest, type ManifestEntry, type ManifestHeaderInput } from 'visual-regression-manifest';
+import type { CompareInput, CompareResult, DiffEngine, EngineOptions, ImagePart, Layout, Limits, Matcher, OnMissingBaseline, Plugin, Reporter, SizeMismatch, Store, UpdatePolicy } from './types';
+export declare const TOOL_NAME = "visual-regression-compare";
+export type ComparerOptions = {
+    /**
+     * A built-in engine name, a module id (`./my-engine.mjs`, a package) or an
+     * engine object. Names and ids run in worker threads; an object runs in the
+     * main thread. Default `pixelmatch`.
+     */
+    engine?: string | DiffEngine;
+    /** Passed to the engine factory; must be structured-cloneable. */
+    engineOptions?: EngineOptions;
+    limits?: Limits;
+    /** What a screenshot without a baseline becomes: `missing-baseline` (`fail`) or a created baseline. Default `fail`. */
+    onMissingBaseline?: OnMissingBaseline;
+    /** Default `fail`: no padding, the size change itself is the result. */
+    onSizeMismatch?: SizeMismatch;
+    /** Overwrite baselines: never (default), when the comparison failed, or whenever the pixels differ. */
+    update?: UpdatePolicy;
+    store: Store;
+    layout?: Layout;
+    matcher?: Matcher;
+    manifest: {
+        /**
+         * A manifest writer the caller owns, for a runner that builds the header
+         * (CI, run and reproduction metadata, one file per worker) itself. The
+         * other keys of this object are then ignored.
+         */
+        writer?: ManifestWriter;
+        /** Where the manifest is written; default `visual-regression-manifest.compare.json` in the project root. */
+        path?: string;
+        /** Absolute path every manifest path is relative to; default the working directory. */
+        projectRoot?: string;
+        tool?: ManifestHeaderInput['tool'];
+        runner?: ManifestHeaderInput['runner'];
+        /** Metadata recorded on every entry that does not state its own. */
+        platform?: CompareInput['platform'];
+        variant?: string;
+    };
+    plugins?: Plugin[];
+    reporters?: Reporter[];
+    /**
+     * Worker threads for decoding and comparing, and parallel reads in
+     * `compareAll`. Default `1`: everything runs in the calling thread, which is
+     * what a runner adapter wants (its own workers already use the CPUs). The
+     * command line passes the CPU count.
+     */
+    concurrency?: number;
+    /** The built worker module; found next to this file in the published package. */
+    workerFile?: URL | string;
+};
+export declare class Comparer {
+    private readonly options;
+    readonly writer: ManifestWriter;
+    private readonly projectRoot;
+    private readonly store;
+    private readonly layout;
+    private readonly matcher;
+    private readonly pool;
+    private readonly registry;
+    private readonly ready;
+    private readonly engines;
+    private closed;
+    constructor(options: ComparerOptions);
+    private createWriter;
+    /** The comparer's settings with the overrides of one call applied. */
+    private settings;
+    /** The engine as the main thread knows it: for its name and metric, and to run it when it is an object or came from a plugin. */
+    private resolveEngine;
+    private measure;
+    /** Compares one screenshot, decides, writes the files and records the manifest entry. */
+    compareImage(input: CompareInput): Promise<ManifestEntry>;
+    /**
+     * `compareImage` that can also hand back the compared images as PNG bytes,
+     * for a runner that shows them (a review UI). `include` names the parts;
+     * the diff is encoded anyway, the other two cost nothing when the sizes
+     * match.
+     */
+    compare(input: CompareInput, { include }?: {
+        include?: ImagePart[];
+    }): Promise<CompareResult>;
+    private compareAt;
+    private compareWith;
+    /** `maxDiffRatio` of the entry: the stricter of the ratio and the pixel count, for the size actually compared. */
+    private limitFor;
+    private decide;
+    private record;
+    /** Compares every incoming image of the store against its baseline. */
+    compareAll(): Promise<Manifest>;
+    private compareIncoming;
+    /** Flushes the manifest and ends the reporters. Call once, after the last comparison. */
+    close(): Promise<Manifest>;
+}
+export declare const createComparer: (options: ComparerOptions) => Comparer;

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+import type { ConfigFile } from './options';
+/** The config file named by `--config`, else the first `visual-regression.config.*` in `cwd`; `{}` when there is none. */
+export declare const loadConfig: (explicit: string | undefined, cwd?: string) => Promise<ConfigFile>;
+/** `--config <file>` from raw arguments, so the file can be read before the rest is parsed. */
+export declare const configArg: (argv: string[]) => string | undefined;

package/dist/engines/index.d.ts

@@ -0,0 +1,9 @@
+import type { DiffEngine, EngineOptions } from '../types';
+export { pixelmatchEngine, type PixelmatchOptions } from './pixelmatch';
+export declare const BUILT_IN_ENGINES: string[];
+/**
+ * Turns an engine id into an engine: a built-in name, a path to a module
+ * (`./my-engine.mjs`, resolved from `cwd`) or a package name. The module's
+ * default export is an engine or a function making one from the options.
+ */
+export declare const loadEngine: (id: string, options?: EngineOptions, cwd?: string) => Promise<DiffEngine>;

package/dist/engines/pixelmatch.d.ts

@@ -0,0 +1,9 @@
+import type { DiffEngine, EngineOptions } from '../types';
+export type PixelmatchOptions = {
+    /** Per-pixel color tolerance, 0..1 (YIQ distance). Default `0.1`. */
+    threshold?: number;
+    /** Count anti-aliased pixels as differences. Default `false`. */
+    includeAA?: boolean;
+};
+export declare const pixelmatchEngine: ({ threshold, includeAA, }?: PixelmatchOptions) => DiffEngine;
+export declare const pixelmatchFrom: (options: EngineOptions) => DiffEngine;

package/dist/image.d.ts

@@ -0,0 +1,8 @@
+import type { RgbaImage } from './types';
+/** Decodes a PNG. A Git LFS pointer file, which a checkout without `git lfs pull` leaves in place of an image, gets its own message. */
+export declare const decodePng: (bytes: Uint8Array) => RgbaImage;
+export declare const encodePng: ({ width, height, data }: RgbaImage) => Uint8Array;
+/** Grows both images to the larger size with transparent pixels. */
+export declare const padToSame: (a: RgbaImage, b: RgbaImage) => [RgbaImage, RgbaImage];
+/** Cuts both images to the smaller size. */
+export declare const cropToSame: (a: RgbaImage, b: RgbaImage) => [RgbaImage, RgbaImage];

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { Comparer, TOOL_NAME, createComparer, type ComparerOptions, } from './comparer';
+export { loadEngine, pixelmatchEngine, BUILT_IN_ENGINES, type PixelmatchOptions, } from './engines';
+export { fileStore, fsStore, type FsStoreOptions } from './store';
+export { manifestLayout, samePathMatcher, sanitizeName, templateMatcher, } from './layout';
+export { approve, type ApproveOptions, type ApproveResult, type Skipped, } from './approve';
+export { consoleReporter, ctrfReporter, githubSummaryReporter, parseReporters, summaryMarkdown, } from './reporters';
+export { decodePng, encodePng } from './image';
+export * from './types';