@bejamas/bench 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @bejamas/bench
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Compare an original site with its ported version. Built for checking framework
+migrations, such as a React + shadcn/ui site ported to Astro + b/ui, but it
+works with any two URLs.
+
+```bash
+npx @bejamas/bench --original http://localhost:3000 --ported http://localhost:4321
+# or through the Bejamas CLI
+npx bejamas bench --original http://localhost:3000 --ported http://localhost:4321
+```
+
+The URLs can also be passed positionally (`<original> <ported>`), but swapping
+them silently inverts every comparison, so the named flags are preferred and the
+positional form prints which URL it read as which.
+
+Requires Node.js 22.19+ and Google Chrome. Set `CHROME_PATH` or pass
+`--chrome-path` if Chrome is installed in a nonstandard location.
+
+## What it measures
+
+| Stage        | What it compares                                                                                                                                                                                                                 |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `lighthouse` | Median performance score, FCP, LCP, TBT, CLS and Speed Index. Runs alternate between the two URLs (original first, then ported first) so drift affects both equally.                                                             |
+| `assets`     | Every response of a cold load at 412×823: JavaScript, CSS, HTML, fonts, images and other requests. HTML, CSS and JavaScript are recompressed with gzip level 9, so a local server without compression and a CDN compare equally. |
+| `quality`    | Visible text, title, description and `lang`, heading outline, axe-core violations, console and page errors, failed requests, DOM size and nested interactive controls.                                                           |
+| `visual`     | Visible `data-slot` components matched by slot name, text and order, then compared by size. Top-level header, main, section and footer regions are compared by position and size. Full-page screenshots are pixel-diffed.        |
+
+Accessibility violations, browser errors and failed requests only fail the run
+when they are new in the ported page. Problems that the original already has are
+reported as warnings.
+
+Each broken resource is reported once, with its HTTP status, a CORS block or
+Chrome's network error. Loads the browser cancels, such as link prefetches, are
+not failures. Generic `data-slot` part names (`root`, `outer`, `inner`) are left
+out of component matching because they don't identify a component.
+
+## Production builds only
+
+Development servers ship unminified code and HMR clients. When a Vite, Astro,
+Next.js or webpack dev server is detected, the `assets` and `lighthouse` stages
+are skipped. Pass `--allow-dev` to measure anyway.
+
+Lighthouse timings are reported as not comparable when one URL is local and the
+other is remote, and timing budgets are skipped. Asset budgets still apply
+because their compression is recomputed locally.
+
+## Budgets
+
+`--fail-on` takes comma-separated budgets, and can be repeated. Size and timing
+budgets compare the change from original to ported:
+
+| Budget       | Fails when                                                       |
+| ------------ | ---------------------------------------------------------------- |
+| `lcp>10%`    | LCP grows by more than 10%                                       |
+| `tbt>50ms`   | TBT grows by more than 50 ms                                     |
+| `score<-5`   | The performance score drops by more than 5 points                |
+| `js>0`       | Route JavaScript (gzip) grows at all                             |
+| `total>20kb` | HTML + CSS + JS (gzip) + fonts grow by more than 20 KiB          |
+| `requests>0` | The page makes more requests                                     |
+| `pixels>1%`  | More than 1% of screenshot pixels differ at any width (absolute) |
+
+Metrics: `score`, `fcp`, `lcp`, `tbt`, `cls`, `si`, `js`, `css`, `html`,
+`fonts`, `total`, `requests`, `pixels`.
+
+## Output
+
+The summary is printed to the terminal: checks, budgets, Lighthouse, route
+assets, visual parity and page quality. Nothing is written to disk unless you
+pass `--out <dir>`, which adds:
+
+- `report.md`: the readable report
+- `report.json`: every measurement, including per-run Lighthouse values and per-request assets
+- `screenshots/`: `original-<width>.png`, `ported-<width>.png` and `diff-<width>.png`
+- `lighthouse/`: the full Lighthouse JSON for every run
+
+Exit codes: `0` when all checks and budgets pass, `1` when any fail, `2` when
+the run cannot complete. Use `--report-only` to always exit with `0` for
+checks and budgets. Use `--json` to print the report to stdout for scripts and
+agents.
+
+## Options
+
+```
+--original <url>        URL of the original site
+--ported <url>          URL of the ported site
+-o, --out <dir>         also write report files to this directory
+-r, --runs <count>      Lighthouse runs per URL (default: 5)
+-w, --widths <list>     viewport widths for visual parity (default: 412,1280)
+--form-factor <type>    mobile or desktop Lighthouse emulation (default: mobile)
+--only <stages>         run only these stages
+--skip <stages>         skip these stages
+--tolerance <px>        allowed size difference (default: 0.5)
+--fail-on <budgets>     budgets, see above
+--report-only           exit with 0 even when checks or budgets fail
+--allow-dev             measure assets and Lighthouse on dev servers
+--chrome-path <path>    Chrome executable
+--timeout <ms>          navigation timeout (default: 60000)
+--json                  print the JSON report to stdout
+```
+
+## Programmatic use
+
+```ts
+import { runBench } from "@bejamas/bench";
+
+const { report } = await runBench({
+  original: "http://localhost:3000",
+  ported: "http://localhost:4321",
+  outDir: "bench-report", // optional; omit to skip writing files
+  runs: 5,
+  widths: [412, 1280],
+  formFactor: "mobile",
+  stages: ["assets", "quality", "visual", "lighthouse"],
+  tolerance: 0.5,
+  budgets: ["lcp>10%"],
+  allowDev: false,
+  timeout: 60_000,
+});
+```
+
+## Limitations
+
+- Lab measurements of one route, not field Core Web Vitals.
+- Assets are those loaded without interaction. Code loaded only after a click is not counted.
+- Interaction latency is not measured yet.
+- Pages with randomized or time-based content will report text and pixel differences.

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { c as BUDGET_HELP, d as BenchError, f as version, n as runBench, s as STAGES, t as renderSummary } from "./summary-DD9dfSgQ.js";
+import { relative } from "node:path";
+import kleur from "kleur";
+import { Command, InvalidArgumentError, Option } from "commander";
+
+//#region src/args.ts
+function positiveInteger(value) {
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed < 1) throw new InvalidArgumentError("Expected a positive integer.");
+	return parsed;
+}
+function nonNegativeNumber(value) {
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed < 0) throw new InvalidArgumentError("Expected a non-negative number.");
+	return parsed;
+}
+function widthList(value) {
+	const widths = value.split(",").map((part) => Number(part.trim()));
+	if (widths.length === 0 || widths.some((width) => !Number.isInteger(width) || width < 200 || width > 3840)) throw new InvalidArgumentError("Expected comma-separated widths between 200 and 3840.");
+	return [...new Set(widths)];
+}
+const isStageName = (value) => STAGES.includes(value);
+function stageList(value) {
+	const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
+	const stages = parts.filter(isStageName);
+	if (stages.length === 0 || stages.length !== parts.length) throw new InvalidArgumentError(`Expected a comma-separated list of: ${STAGES.join(", ")}.`);
+	return stages;
+}
+function collect(value, previous) {
+	return [...previous, value];
+}
+/** Stages to run, in their fixed order, after --only and --skip. */
+function selectStages(only = STAGES, skip = []) {
+	const stages = only.filter((stage) => !skip.includes(stage));
+	if (stages.length === 0) throw new BenchError("No stages left to run.");
+	return stages;
+}
+/**
+* Resolve which URL is which. Named flags are preferred because positional
+* URLs are easy to swap, which silently inverts every comparison.
+*/
+function resolveTargetUrls(flags, positional) {
+	const named = flags.original !== void 0 || flags.ported !== void 0;
+	if (named && positional.length > 0) throw new BenchError(`Pass the URLs either as --original and --ported or positionally, not both (got ${positional.join(" ")}).`);
+	if (named) {
+		const { original, ported } = flags;
+		if (original === void 0 || ported === void 0) {
+			const missing = [original === void 0 && "--original <url>", ported === void 0 && "--ported <url>"].filter(Boolean);
+			throw new BenchError(`Missing ${missing.join(" and ")}.`);
+		}
+		return {
+			original,
+			ported
+		};
+	}
+	if (positional.length !== 2) throw new BenchError("Pass both URLs: --original <url> --ported <url>.");
+	const [original, ported] = positional;
+	return {
+		original,
+		ported,
+		warning: `Reading ${original} as the original and ${ported} as the port. Use --original and --ported to avoid swapping them.`
+	};
+}
+
+//#endregion
+//#region src/cli.ts
+function createProgram() {
+	return new Command().name("bejamas-bench").description("Compare an original site with its ported version: Lighthouse, route assets, accessibility, text and visual parity.").version(version, "-v, --version", "output the version number").usage("--original <url> --ported <url> [options]").option("--original <url>", "URL of the original site, e.g. https://example.com").option("--ported <url>", "URL of the ported site, e.g. http://localhost:4321").argument("[urls...]", "positional <original> <ported>; prefer the named flags so the URLs cannot be swapped").option("-o, --out <dir>", "also write report.md, report.json, screenshots and Lighthouse reports to this directory").option("-r, --runs <count>", "Lighthouse runs per URL; medians are reported", positiveInteger, 5).addOption(new Option("-w, --widths <list>", "viewport widths for visual parity").argParser(widthList).default([412, 1280], "412,1280")).addOption(new Option("--form-factor <type>", "Lighthouse device emulation").choices(["mobile", "desktop"]).default("mobile")).option("--only <stages>", `run only these stages (${STAGES.join(", ")})`, stageList).option("--skip <stages>", "skip these stages", stageList).option("--tolerance <px>", "allowed size difference for matched components and regions", nonNegativeNumber, .5).addOption(new Option("--fail-on <budgets>", "fail when the ported URL exceeds these budgets, e.g. lcp>10%,js>0 (repeatable)").argParser(collect).default([], "none")).option("--report-only", "always exit with 0 unless the run itself fails").option("--allow-dev", "measure assets and Lighthouse even when a dev server is detected").option("--chrome-path <path>", "Chrome executable (defaults to CHROME_PATH or an installed Chrome)").option("--timeout <ms>", "navigation timeout", positiveInteger, 6e4).option("--json", "print the JSON report to stdout instead of the summary").addHelpText("after", `
+Exit codes: 0 when all checks and budgets pass, 1 when any fail, 2 when the run cannot complete.
+
+${BUDGET_HELP}
+
+Examples:
+  $ bejamas-bench --original http://localhost:3000 --ported http://localhost:4321
+  $ bejamas-bench --original http://localhost:3000 --ported http://localhost:4321 --out bench-report
+  $ bejamas-bench --original https://example.com --ported https://new.example.com --fail-on "lcp>10%,js>0,pixels>1%"
+  $ bejamas-bench --original localhost:3000 --ported localhost:4321 --only visual,quality --widths 375,768,1440`).action(async (positional, opts) => {
+		const warn = (message) => process.stderr.write(`${kleur.yellow("warning")} ${message}\n`);
+		const { original, ported, warning } = resolveTargetUrls(opts, positional);
+		if (warning) warn(warning);
+		const { report, files } = await runBench({
+			original,
+			ported,
+			outDir: opts.out,
+			runs: opts.runs,
+			widths: opts.widths,
+			formFactor: opts.formFactor,
+			stages: selectStages(opts.only, opts.skip),
+			tolerance: opts.tolerance,
+			budgets: opts.failOn,
+			allowDev: opts.allowDev ?? false,
+			chromePath: opts.chromePath,
+			timeout: opts.timeout
+		}, (message) => process.stderr.write(`${kleur.dim("›")} ${message}\n`));
+		if (opts.json) {
+			for (const reason of report.comparability.reasons) warn(reason);
+			process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		} else process.stdout.write(`\n${renderSummary(report)}\n`);
+		if (files) {
+			const shown = relative(process.cwd(), files.markdown);
+			process.stderr.write(`\nReport written to ${shown.startsWith("..") ? files.markdown : shown}\n`);
+		}
+		if (!report.passed && !opts.reportOnly) process.exitCode = 1;
+		if (report.errors.length > 0) process.exitCode = 2;
+	});
+}
+async function main(argv = process.argv) {
+	const program = createProgram();
+	program.exitOverride((error) => {
+		process.exit(error.exitCode === 0 ? 0 : 2);
+	});
+	try {
+		await program.parseAsync(argv);
+	} catch (error) {
+		const message = error instanceof BenchError ? error.message : error instanceof Error ? error.stack ?? error.message : String(error);
+		process.stderr.write(`${kleur.red("error")} ${message}\n`);
+		process.exitCode = 2;
+	}
+}
+await main();
+
+//#endregion
+export {  };
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":["pkg.version"],"sources":["../src/args.ts","../src/cli.ts"],"sourcesContent":["import { InvalidArgumentError } from \"commander\";\nimport { BenchError } from \"./errors\";\nimport { STAGES, type StageName } from \"./types\";\n\nexport function positiveInteger(value: string) {\n  const parsed = Number(value);\n  if (!Number.isInteger(parsed) || parsed < 1)\n    throw new InvalidArgumentError(\"Expected a positive integer.\");\n  return parsed;\n}\n\nexport function nonNegativeNumber(value: string) {\n  const parsed = Number(value);\n  if (!Number.isFinite(parsed) || parsed < 0)\n    throw new InvalidArgumentError(\"Expected a non-negative number.\");\n  return parsed;\n}\n\nexport function widthList(value: string) {\n  const widths = value.split(\",\").map((part) => Number(part.trim()));\n  if (\n    widths.length === 0 ||\n    widths.some(\n      (width) => !Number.isInteger(width) || width < 200 || width > 3840,\n    )\n  ) {\n    throw new InvalidArgumentError(\n      \"Expected comma-separated widths between 200 and 3840.\",\n    );\n  }\n  return [...new Set(widths)];\n}\n\nconst isStageName = (value: string): value is StageName =>\n  (STAGES as readonly string[]).includes(value);\n\nexport function stageList(value: string): StageName[] {\n  const parts = value\n    .split(\",\")\n    .map((part) => part.trim())\n    .filter(Boolean);\n  const stages = parts.filter(isStageName);\n  if (stages.length === 0 || stages.length !== parts.length) {\n    throw new InvalidArgumentError(\n      `Expected a comma-separated list of: ${STAGES.join(\", \")}.`,\n    );\n  }\n  return stages;\n}\n\nexport function collect(value: string, previous: string[]) {\n  return [...previous, value];\n}\n\n/** Stages to run, in their fixed order, after --only and --skip. */\nexport function selectStages(\n  only: readonly StageName[] = STAGES,\n  skip: readonly StageName[] = [],\n) {\n  const stages = only.filter((stage) => !skip.includes(stage));\n  if (stages.length === 0) throw new BenchError(\"No stages left to run.\");\n  return stages;\n}\n\n/**\n * Resolve which URL is which. Named flags are preferred because positional\n * URLs are easy to swap, which silently inverts every comparison.\n */\nexport function resolveTargetUrls(\n  flags: { original?: string; ported?: string },\n  positional: readonly string[],\n): { original: string; ported: string; warning?: string } {\n  const named = flags.original !== undefined || flags.ported !== undefined;\n  if (named && positional.length > 0) {\n    throw new BenchError(\n      `Pass the URLs either as --original and --ported or positionally, not both (got ${positional.join(\" \")}).`,\n    );\n  }\n  if (named) {\n    const { original, ported } = flags;\n    if (original === undefined || ported === undefined) {\n      const missing = [\n        original === undefined && \"--original <url>\",\n        ported === undefined && \"--ported <url>\",\n      ].filter(Boolean);\n      throw new BenchError(`Missing ${missing.join(\" and \")}.`);\n    }\n    return { original, ported };\n  }\n  if (positional.length !== 2) {\n    throw new BenchError(\"Pass both URLs: --original <url> --ported <url>.\");\n  }\n  const [original, ported] = positional as [string, string];\n  return {\n    original,\n    ported,\n    warning: `Reading ${original} as the original and ${ported} as the port. Use --original and --ported to avoid swapping them.`,\n  };\n}\n","#!/usr/bin/env node\nimport { relative } from \"node:path\";\nimport { Command, Option } from \"commander\";\nimport kleur from \"kleur\";\nimport pkg from \"../package.json\" with { type: \"json\" };\nimport {\n  collect,\n  nonNegativeNumber,\n  positiveInteger,\n  resolveTargetUrls,\n  selectStages,\n  stageList,\n  widthList,\n} from \"./args\";\nimport { BUDGET_HELP } from \"./budgets\";\nimport { BenchError } from \"./errors\";\nimport { renderSummary } from \"./summary\";\nimport { runBench } from \"./run\";\nimport { STAGES, type FormFactor, type StageName } from \"./types\";\n\n/** Parsed options, as the parsers and defaults below produce them. */\ninterface CliOptions {\n  original?: string;\n  ported?: string;\n  out?: string;\n  runs: number;\n  widths: number[];\n  formFactor: FormFactor;\n  only?: StageName[];\n  skip?: StageName[];\n  tolerance: number;\n  failOn: string[];\n  reportOnly?: true;\n  allowDev?: true;\n  chromePath?: string;\n  timeout: number;\n  json?: true;\n}\n\nfunction createProgram() {\n  return new Command()\n    .name(\"bejamas-bench\")\n    .description(\n      \"Compare an original site with its ported version: Lighthouse, route assets, accessibility, text and visual parity.\",\n    )\n    .version(pkg.version, \"-v, --version\", \"output the version number\")\n    .usage(\"--original <url> --ported <url> [options]\")\n    .option(\n      \"--original <url>\",\n      \"URL of the original site, e.g. https://example.com\",\n    )\n    .option(\n      \"--ported <url>\",\n      \"URL of the ported site, e.g. http://localhost:4321\",\n    )\n    .argument(\n      \"[urls...]\",\n      \"positional <original> <ported>; prefer the named flags so the URLs cannot be swapped\",\n    )\n    .option(\n      \"-o, --out <dir>\",\n      \"also write report.md, report.json, screenshots and Lighthouse reports to this directory\",\n    )\n    .option(\n      \"-r, --runs <count>\",\n      \"Lighthouse runs per URL; medians are reported\",\n      positiveInteger,\n      5,\n    )\n    .addOption(\n      new Option(\"-w, --widths <list>\", \"viewport widths for visual parity\")\n        .argParser(widthList)\n        .default([412, 1280], \"412,1280\"),\n    )\n    .addOption(\n      new Option(\"--form-factor <type>\", \"Lighthouse device emulation\")\n        .choices([\"mobile\", \"desktop\"])\n        .default(\"mobile\"),\n    )\n    .option(\n      \"--only <stages>\",\n      `run only these stages (${STAGES.join(\", \")})`,\n      stageList,\n    )\n    .option(\"--skip <stages>\", \"skip these stages\", stageList)\n    .option(\n      \"--tolerance <px>\",\n      \"allowed size difference for matched components and regions\",\n      nonNegativeNumber,\n      0.5,\n    )\n    .addOption(\n      new Option(\n        \"--fail-on <budgets>\",\n        \"fail when the ported URL exceeds these budgets, e.g. lcp>10%,js>0 (repeatable)\",\n      )\n        .argParser(collect)\n        .default([], \"none\"),\n    )\n    .option(\"--report-only\", \"always exit with 0 unless the run itself fails\")\n    .option(\n      \"--allow-dev\",\n      \"measure assets and Lighthouse even when a dev server is detected\",\n    )\n    .option(\n      \"--chrome-path <path>\",\n      \"Chrome executable (defaults to CHROME_PATH or an installed Chrome)\",\n    )\n    .option(\"--timeout <ms>\", \"navigation timeout\", positiveInteger, 60_000)\n    .option(\"--json\", \"print the JSON report to stdout instead of the summary\")\n    .addHelpText(\n      \"after\",\n      `\nExit codes: 0 when all checks and budgets pass, 1 when any fail, 2 when the run cannot complete.\n\n${BUDGET_HELP}\n\nExamples:\n  $ bejamas-bench --original http://localhost:3000 --ported http://localhost:4321\n  $ bejamas-bench --original http://localhost:3000 --ported http://localhost:4321 --out bench-report\n  $ bejamas-bench --original https://example.com --ported https://new.example.com --fail-on \"lcp>10%,js>0,pixels>1%\"\n  $ bejamas-bench --original localhost:3000 --ported localhost:4321 --only visual,quality --widths 375,768,1440`,\n    )\n    .action(async (positional: string[], opts: CliOptions) => {\n      const warn = (message: string) =>\n        process.stderr.write(`${kleur.yellow(\"warning\")} ${message}\\n`);\n      const { original, ported, warning } = resolveTargetUrls(opts, positional);\n      if (warning) warn(warning);\n\n      const { report, files } = await runBench(\n        {\n          original,\n          ported,\n          outDir: opts.out,\n          runs: opts.runs,\n          widths: opts.widths,\n          formFactor: opts.formFactor,\n          stages: selectStages(opts.only, opts.skip),\n          tolerance: opts.tolerance,\n          budgets: opts.failOn,\n          allowDev: opts.allowDev ?? false,\n          chromePath: opts.chromePath,\n          timeout: opts.timeout,\n        },\n        (message) => process.stderr.write(`${kleur.dim(\"›\")} ${message}\\n`),\n      );\n\n      if (opts.json) {\n        // The summary shows comparability; JSON consumers get it on stderr.\n        for (const reason of report.comparability.reasons) warn(reason);\n        process.stdout.write(`${JSON.stringify(report, null, 2)}\\n`);\n      } else {\n        process.stdout.write(`\\n${renderSummary(report)}\\n`);\n      }\n      if (files) {\n        const shown = relative(process.cwd(), files.markdown);\n        process.stderr.write(\n          `\\nReport written to ${shown.startsWith(\"..\") ? files.markdown : shown}\\n`,\n        );\n      }\n      if (!report.passed && !opts.reportOnly) process.exitCode = 1;\n      if (report.errors.length > 0) process.exitCode = 2;\n    });\n}\n\nasync function main(argv = process.argv) {\n  const program = createProgram();\n  program.exitOverride((error) => {\n    // Commander errors (usage) exit with 2; help and version exit with 0.\n    process.exit(error.exitCode === 0 ? 0 : 2);\n  });\n  try {\n    await program.parseAsync(argv);\n  } catch (error) {\n    const message =\n      error instanceof BenchError\n        ? error.message\n        : error instanceof Error\n          ? (error.stack ?? error.message)\n          : String(error);\n    process.stderr.write(`${kleur.red(\"error\")} ${message}\\n`);\n    process.exitCode = 2;\n  }\n}\n\nawait main();\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,289 @@
+//#region src/types.d.ts
+export type Side = "original" | "ported";
+export declare const SIDES: readonly Side[];
+/** One value per side. */
+export type Paired<T> = Record<Side, T>;
+export type StageName = "assets" | "quality" | "visual" | "lighthouse";
+export declare const STAGES: readonly StageName[];
+export type FormFactor = "mobile" | "desktop";
+export interface BenchOptions {
+  original: string;
+  ported: string;
+  /** Write report files here. Nothing is written when omitted. */
+  outDir?: string;
+  runs: number;
+  widths: number[];
+  formFactor: FormFactor;
+  stages: StageName[];
+  tolerance: number;
+  budgets: string[];
+  allowDev: boolean;
+  chromePath?: string;
+  timeout: number;
+}
+export interface Target {
+  side: Side;
+  input: string;
+  url: string;
+  finalUrl: string;
+  status: number;
+  local: boolean;
+  devServer: string | null;
+}
+export interface Comparability {
+  comparable: boolean;
+  reasons: string[];
+}
+export type AssetCategory = "html" | "css" | "js" | "fonts" | "images" | "other";
+export declare const ASSET_CATEGORIES: readonly AssetCategory[];
+export interface AssetEntry {
+  url: string;
+  category: AssetCategory;
+  thirdParty: boolean;
+  /** Encoded body bytes received over the network. */
+  transfer: number;
+  /** Decoded body bytes. */
+  raw: number;
+  /** Deterministic gzip level 9 estimate, compressible categories only. */
+  gzip: number | null;
+}
+export interface AssetSummary {
+  count: number;
+  transfer: number;
+  raw: number;
+  /** Comparable size: the gzip estimate for HTML, CSS and JS, transferred bytes otherwise. */
+  size: number;
+}
+export interface SideAssets {
+  finalUrl: string;
+  viewport: {
+    width: number;
+    height: number;
+  };
+  categories: Record<AssetCategory, AssetSummary>;
+  /** Comparable size of HTML + CSS + JS + fonts. */
+  coreSize: number;
+  requests: number;
+  transfer: number;
+  entries: AssetEntry[];
+}
+export type AssetsResult = Paired<SideAssets>;
+export interface AxeViolation {
+  id: string;
+  impact: string | null;
+  help: string;
+  nodes: number;
+}
+export interface Heading {
+  level: number;
+  text: string;
+}
+export interface FailedRequest {
+  url: string;
+  /** An HTTP status, "blocked by CORS" or Chrome's network error. */
+  reason: string;
+}
+export interface SideQuality {
+  finalUrl: string;
+  title: string;
+  description: string | null;
+  lang: string | null;
+  text: string;
+  headings: Heading[];
+  domElements: number;
+  domBytes: number;
+  nestedInteractiveControls: number;
+  violations: AxeViolation[];
+  errors: string[];
+  failedRequests: FailedRequest[];
+}
+export interface TextDifference {
+  identical: boolean;
+  originalWords: number;
+  portedWords: number;
+  /** Context around the first differing region, when the text differs. */
+  original?: string;
+  ported?: string;
+}
+export interface QualityResult extends Paired<SideQuality> {
+  viewport: {
+    width: number;
+    height: number;
+  };
+  text: TextDifference;
+}
+export interface Box {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+export interface SlotElement {
+  slot: string;
+  text: string;
+  width: number;
+  height: number;
+}
+export interface Landmark extends Box {
+  tag: string;
+}
+export interface Capture {
+  side: Side;
+  width: number;
+  /** Screenshot file, when report files are written. */
+  screenshot: string | null;
+  pageHeight: number;
+  elements: SlotElement[];
+  landmarks: Landmark[];
+}
+export interface SlotDifference {
+  slot: string;
+  text: string;
+  original: [number, number];
+  ported: [number, number];
+}
+export interface LandmarkDifference {
+  index: number;
+  tag: string;
+  original: Box | null;
+  ported: Box | null;
+}
+export interface GeometryComparison {
+  /** Named `data-slot` elements on each side; generic part names are left out. */
+  originalElements: number;
+  portedElements: number;
+  matchedElements: number;
+  differences: SlotDifference[];
+  unmatchedOriginal: Record<string, number>;
+  unmatchedPorted: Record<string, number>;
+  landmarkDifferences: LandmarkDifference[];
+}
+export interface PixelComparison {
+  /** Diff image file, when report files are written. */
+  diff: string | null;
+  comparedWidth: number;
+  comparedHeight: number;
+  heightDelta: number;
+  mismatchedPixels: number;
+  /** Percentage of compared pixels that differ. */
+  mismatch: number;
+}
+export interface VisualWidthResult extends GeometryComparison {
+  width: number;
+  pixels: PixelComparison;
+}
+export interface VisualResult {
+  tolerance: number;
+  captures: Capture[];
+  widths: VisualWidthResult[];
+}
+export type LighthouseMetric = "score" | "fcp" | "lcp" | "tbt" | "cls" | "si";
+export declare const LIGHTHOUSE_METRICS: readonly LighthouseMetric[];
+export type LighthouseValues = Record<LighthouseMetric, number | null>;
+export interface LighthouseRun extends LighthouseValues {
+  run: number;
+  /** Full Lighthouse report file, when report files are written. */
+  report: string | null;
+}
+export interface LighthouseSide {
+  runs: LighthouseRun[];
+  median: LighthouseValues;
+}
+export interface LighthouseResult extends Paired<LighthouseSide> {
+  formFactor: FormFactor;
+  version: string;
+  runs: number;
+  order: string;
+}
+export type CheckStatus = "pass" | "fail" | "warn" | "skip";
+export interface Check {
+  id: string;
+  label: string;
+  status: CheckStatus;
+  detail: string;
+}
+export interface BudgetResult {
+  budget: string;
+  status: "pass" | "fail" | "skip";
+  detail: string;
+}
+export interface SkippedStage {
+  stage: StageName;
+  reason: string;
+}
+export interface StageError {
+  stage: StageName;
+  message: string;
+}
+export interface BenchReport {
+  schemaVersion: 1;
+  tool: {
+    name: string;
+    version: string;
+  };
+  measuredAt: string;
+  environment: {
+    node: string;
+    platform: string;
+    arch: string;
+    browser: string | null;
+  };
+  options: Omit<BenchOptions, "original" | "ported">;
+  targets: Paired<Target>;
+  comparability: Comparability;
+  skipped: SkippedStage[];
+  errors: StageError[];
+  assets?: AssetsResult;
+  quality?: QualityResult;
+  visual?: VisualResult;
+  lighthouse?: LighthouseResult;
+  checks: Check[];
+  budgets: BudgetResult[];
+  passed: boolean;
+}
+//#endregion
+//#region src/run.d.ts
+interface RunResult {
+  report: BenchReport;
+  /** Report files, when `outDir` is set. */
+  files?: {
+    json: string;
+    markdown: string;
+  };
+}
+export declare function runBench(options: BenchOptions, log?: (message: string) => void): Promise<RunResult>;
+//#endregion
+//#region src/report.d.ts
+export declare function renderMarkdown(report: BenchReport, outDir: string): string;
+//#endregion
+//#region src/summary.d.ts
+/** Everything a reader needs from the report, formatted for a terminal. */
+export declare function renderSummary(report: BenchReport, width?: number): string;
+//#endregion
+//#region src/budgets.d.ts
+type BudgetMetric = LighthouseMetric | "js" | "css" | "html" | "fonts" | "total" | "requests" | "pixels";
+interface Budget {
+  source: string;
+  metric: BudgetMetric;
+  op: ">" | "<";
+  value: number;
+  /** Compare the relative change in percent instead of the absolute change. */
+  relative: boolean;
+}
+interface BudgetInputs {
+  assets?: AssetsResult;
+  lighthouse?: LighthouseResult;
+  visual?: VisualResult;
+  comparability: Comparability;
+}
+export declare function parseBudgets(inputs: readonly string[]): Budget[];
+export declare function evaluateBudgets(budgets: readonly Budget[], inputs: BudgetInputs): BudgetResult[];
+//#endregion
+//#region src/errors.d.ts
+/** An expected failure with a message that is safe to print without a stack. */
+export declare class BenchError extends Error {
+  name: string;
+}
+//#endregion
+export type { Budget, BudgetMetric, RunResult };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/run.ts","../src/report.ts","../src/summary.ts","../src/budgets.ts","../src/errors.ts"],"mappings":";YAAY;qBACC,gBAAgB;;YAGjB,OAAO,KAAK,OAAO,MAAM;YAEzB;qBACC,iBAAiB;YAOlB;iBAEK;EACf;EACA;;EAEA;EACA;EACA;EACA,YAAY;EACZ,QAAQ;EACR;EACA;EACA;EACA;EACA;;iBAGe;EACf,MAAM;EACN;EACA;EACA;EACA;EACA;EACA;;iBAGe;EACf;EACA;;YAGU;qBAEC,2BAA2B;iBASvB;EACf;EACA,UAAU;EACV;;EAEA;;EAEA;;EAEA;;iBAGe;EACf;EACA;EACA;;EAEA;;iBAGe;EACf;EACA;IAAY;IAAe;;EAC3B,YAAY,OAAO,eAAe;;EAElC;EACA;EACA;EACA,SAAS;;YAGC,eAAe,OAAO;iBAEjB;EACf;EACA;EACA;EACA;;iBAGe;EACf;EACA;;iBAGe;EACf;;EAEA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA,UAAU;EACV;EACA;EACA;EACA,YAAY;EACZ;EACA,gBAAgB;;iBAGD;EACf;EACA;EACA;;EAEA;EACA;;iBAGe,sBAAsB,OAAO;EAC5C;IAAY;IAAe;;EAC3B,MAAM;;iBAGS;EACf;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;;iBAGe,iBAAiB;EAChC;;iBAGe;EACf,MAAM;EACN;;EAEA;EACA;EACA,UAAU;EACV,WAAW;;iBAGI;EACf;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA,UAAU;EACV,QAAQ;;iBAGO;;EAEf;EACA;EACA;EACA,aAAa;EACb,mBAAmB;EACnB,iBAAiB;EACjB,qBAAqB;;iBAGN;;EAEf;EACA;EACA;EACA;EACA;;EAEA;;iBAGe,0BAA0B;EACzC;EACA,QAAQ;;iBAGO;EACf;EACA,UAAU;EACV,QAAQ;;YAGE;qBACC,6BAA6B;YAS9B,mBAAmB,OAAO;iBAErB,sBAAsB;EACrC;;EAEA;;iBAGe;EACf,MAAM;EACN,QAAQ;;iBAGO,yBAAyB,OAAO;EAC/C,YAAY;EACZ;EACA;EACA;;YAGU;iBAEK;EACf;EACA;EACA,QAAQ;EACR;;iBAGe;EACf;EACA;EACA;;iBAGe;EACf,OAAO;EACP;;iBAGe;EACf,OAAO;EACP;;iBAGe;EACf;EACA;IAAQ;IAAc;;EACtB;EACA;IACE;IACA;IACA;IACA;;EAEF,SAAS,KAAK;EACd,SAAS,OAAO;EAChB,eAAe;EACf,SAAS;EACT,QAAQ;EACR,SAAS;EACT,UAAU;EACV,SAAS;EACT,aAAa;EACb,QAAQ;EACR,SAAS;EACT;;;;UC3Qe;EACf,QAAQ;;EAER;IAAU;IAAc;;;wBAMJ,SACpB,SAAS,cACT,OAAM,2BACL,QAAQ;;;wBC2BK,eAAe,QAAQ,aAAa;;;;wBCiCpC,cACd,QAAQ,aACR;;;KClFU,eACR;UASa;EACf;EACA,QAAQ;EACR;EACA;;EAEA;;UAGe;EACf,SAAS;EACT,aAAa;EACb,SAAS;EACT,eAAe;;wBA6FD,aAAa,4BAA4B;wBAwFzC,gBACd,kBAAkB,UAClB,QAAQ,eACP;;;;qBC5NU,mBAAmB;EACrB"}

package/dist/index.js

@@ -0,0 +1,3 @@
+import { a as LIGHTHOUSE_METRICS, d as BenchError, i as ASSET_CATEGORIES, l as evaluateBudgets, n as runBench, o as SIDES, r as renderMarkdown, s as STAGES, t as renderSummary, u as parseBudgets } from "./summary-DD9dfSgQ.js";
+
+export { ASSET_CATEGORIES, BenchError, LIGHTHOUSE_METRICS, SIDES, STAGES, evaluateBudgets, parseBudgets, renderMarkdown, renderSummary, runBench };