@luigisbox/luma 0.0.0-stage → 0.2.0

package/parity/alignment.mjs

@@ -0,0 +1,109 @@
+// Alignment relations (docs/PARITY.md, "Alignment"): each component's box is
+// compared relative to itself, so ours can match theirs element by element
+// and still not line up across components (their sort right-aligned with
+// the product grid, ours not). From their page, the edges their mapped
+// components and key parts share within `px` (left, right, top or bottom
+// edges equal, or centred on one another), and on ours the same required:
+// a relation ours breaks is MAJOR, named by both elements and the offset.
+// A required relation needs no theirs: our autocomplete panel against their
+// visible search field (the wrapper that draws it), even when the panel is a
+// house design of ours (`excluded` with a decision). Pure,
+// unit-tested.
+import { decide } from './owner.mjs';
+import { WEIGHT, aggregate, round, scoreOf } from './compare.mjs';
+
+export const EDGES = Object.freeze(['left', 'right', 'top', 'bottom', 'center-x', 'center-y']);
+/** The search field's key among the boxes (edgesOf's `field` item). */
+export const FIELD = 'search-field';
+
+/** An edge of a box (page coordinates: { x, y, width, height }). @param {{ x: number, y: number, width: number, height: number }} b @param {string} e */
+export const edgeOf = (b, e) =>
+  e === 'left' ? b.x : e === 'right' ? b.x + b.width : e === 'top' ? b.y : e === 'bottom' ? b.y + b.height : e === 'center-x' ? b.x + b.width / 2 : b.y + b.height / 2;
+
+/** The component a box's key belongs to: `grid`, `facets.facetGroup` -> `facets`; the search field its own. @param {string} k */
+const groupOf = (k) => (k === FIELD ? FIELD : k.split('.')[0]);
+
+/**
+ * The relations their page holds: every pair of boxes of two different
+ * components (or a component and the search field) whose edge (left, right,
+ * top, bottom) is the same within `px`, or that are centred on one another
+ * (only when not both of that axis's edges are already equal). Sorted, so a
+ * run is repeatable. `ignore`: relations the map leaves out (`"grid~sort
+ * align-right"`, or `"grid~sort"` for every edge of the pair).
+ * @param {Record<string, { x: number, y: number, width: number, height: number } | null>} boxes
+ * @param {{ px?: number, ignore?: string[] }} [o]
+ * @returns {{ a: string, b: string, edge: string }[]}
+ */
+export const relationsOf = (boxes, { px = 1, ignore = [] } = {}) => {
+  const keys = Object.keys(boxes).filter((k) => boxes[k] && boxes[k].width > 0 && boxes[k].height > 0).sort();
+  const out = [];
+  for (let i = 0; i < keys.length; i++)
+    for (let j = i + 1; j < keys.length; j++) {
+      const [a, b] = [keys[i], keys[j]];
+      if (groupOf(a) === groupOf(b)) continue;
+      const [A, B] = [boxes[a], boxes[b]];
+      const same = (e) => Math.abs(edgeOf(A, e) - edgeOf(B, e)) <= px;
+      const holds = EDGES.filter((e) => {
+        if (e === 'center-x') return !(same('left') && same('right')) && same(e);
+        if (e === 'center-y') return !(same('top') && same('bottom')) && same(e);
+        return same(e);
+      });
+      for (const edge of holds) {
+        const pair = `${a}~${b}`;
+        if (ignore.includes(pair) || ignore.includes(`${pair} align-${edge}`)) continue;
+        out.push({ a, b, edge });
+      }
+    }
+  return out;
+};
+
+/**
+ * The relations on ours: each of theirs (and the required ones) held within
+ * `px`, else MAJOR with both elements and the offset (ours' `a` edge minus
+ * `b`'s: + is right of it, or below). A relation whose boxes ours lacks is
+ * not compared (the element's presence is its component's check).
+ * @param {{ a: string, b: string, edge: string, required?: string }[]} relations
+ * @param {Record<string, { x: number, y: number, width: number, height: number } | null>} ours
+ * @param {{ px?: number, theirs?: Record<string, any> }} [o]
+ */
+export const compareAlignment = (relations, ours, { px = 1, theirs = {} } = {}) => {
+  const out = { checks: 0, weight: 0, diffs: /** @type {any[]} */ ([]), relations: /** @type {string[]} */ ([]) };
+  for (const r of relations) {
+    const [A, B] = [ours[r.a], ours[r.b]];
+    if (!A || !B) continue;
+    out.checks += WEIGHT.check;
+    out.relations.push(`${r.a}.${r.edge} = ${r.b}.${r.edge}`);
+    const d = round(edgeOf(A, r.edge) - edgeOf(B, r.edge), 2);
+    if (Math.abs(d) <= px) continue;
+    const dir = r.edge === 'top' || r.edge === 'bottom' || r.edge === 'center-y' ? (d > 0 ? 'below' : 'above') : d > 0 ? 'right of' : 'left of';
+    const t = theirs[r.a] && theirs[r.b] ? round(edgeOf(theirs[r.a], r.edge) - edgeOf(theirs[r.b], r.edge), 2) : 0;
+    out.weight += WEIGHT.check;
+    out.diffs.push({
+      part: `${r.a}~${r.b}`,
+      prop: `align-${r.edge}`,
+      theirs: `${r.a}.${r.edge} = ${r.b}.${r.edge}${r.required ? ` (${r.required})` : t ? ` (${t > 0 ? '+' : ''}${t}px)` : ''}`,
+      ours: `${r.a}.${r.edge} is ${Math.abs(d)}px ${dir} ${r.b}.${r.edge}`,
+      delta: `${r.a}.${r.edge} ${d > 0 ? '+' : ''}${d}px off ${r.b}.${r.edge}`,
+      offset: d,
+      severity: 'major',
+      group: 'alignment',
+      weight: WEIGHT.check,
+      hint: `${r.a} and ${r.b} line up on their ${r.edge === 'center-x' || r.edge === 'center-y' ? 'centres' : `${r.edge} edges`} on their page; on ours ${r.a}'s is ${Math.abs(d)}px ${dir} ${r.b}'s: the margin, width or justify-content that places ${r.a} (or ${r.b}) in the integration's CSS`,
+    });
+  }
+  return out;
+};
+
+/**
+ * The alignment of one page as a result (compareComponent's shape):
+ * component `alignment` (`alignment@<state>`), its relations in `relations`.
+ * @param {{ page: string, viewport: number, state?: string | null }} at @param {ReturnType<typeof compareAlignment>} r @param {{ decided?: Record<string, any> }} [o]
+ */
+export const alignmentResult = (at, r, { decided = {} } = {}) => {
+  const component = at.state ? `alignment@${at.state}` : 'alignment';
+  const diffs = decide(r.diffs.map((d) => ({ ...d, owner: 'template' })), { component: 'alignment', decided });
+  const templateWeight = diffs.filter((d) => d.owner === 'template').reduce((s, d) => s + d.weight, 0);
+  const score = scoreOf(r);
+  const templateScore = scoreOf({ checks: r.checks, weight: templateWeight });
+  return { component, page: at.page, viewport: at.viewport, state: at.state ?? null, score, templateScore, instances: r.checks ? [{ key: 'page', score, templateScore, checks: r.checks, weight: r.weight, pixels: null }] : [], diffs: aggregate([diffs]), relations: r.relations };
+};

package/parity/archive.mjs

@@ -0,0 +1,223 @@
+// Record and replay for `yarn luma parity`: the site's pages, their assets and
+// the API answers, captured once into a local folder, so later runs replay
+// them offline and byte for byte (CI-safe, and no load on the client's site).
+//
+//   <dir>/index.json      request key -> { status, headers, body (sha1) }, sorted
+//   <dir>/bodies/<sha1>   response bodies, content-addressed (shared by every page)
+//
+// Recording listens to the browser's own responses (nothing is fetched
+// beside the browser: no extra requests to the site). The key
+// is the method, the URL without its volatile params (cache busters) and,
+// for a POST, the body's hash. Replay answers every request from the index;
+// a GET whose exact key is missing gets the recording of the same path with
+// the most equal params (deterministic: ties go to the earliest recorded),
+// anything else is aborted and counted. Luigi's Box auth is never recorded
+// (a token, a proof of work): replay answers it with a fixed challenge and
+// token. Cookies and auth headers are never stored.
+//
+// A page can be given a scope (`scope(page, tag)`: an interaction's page on
+// one side, docs/PARITY.md "Behaviour"): its requests are recorded under
+// `[tag] <key>`, the n-th of one key as `[tag] <key> ~n` (a page reloaded
+// after a click: the same URL, another answer), and replayed from there in
+// the same order, else from the plain recording. What an action changes on
+// the server (a compare list, a cart) replays as it was recorded.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const VOLATILE = ['_', 'cb', 'cachebuster', 'ts', 'timestamp', 't', 'rnd', 'random', 'nocache', '_t', 'v', 'gclid', 'fbclid'];
+const KEEP_HEADERS = /^(content-type|location|access-control-[a-z-]+|vary|content-language|link)$/i;
+const AUTH = /^https:\/\/auth\.[a-z0-9-]+\.luigisbox\.ai\//;
+export const sha1 = (b) => createHash('sha1').update(b).digest('hex');
+
+/**
+ * The request key: method, URL without fragment and volatile params (the rest sorted), the POST body's hash.
+ * @param {string} method @param {string} url @param {string | Buffer | null} [body] @param {string[]} [ignore]
+ */
+export const keyOf = (method, url, body = null, ignore = VOLATILE) => {
+  const u = new URL(url);
+  u.hash = '';
+  const params = [...u.searchParams].filter(([k]) => !ignore.includes(k)).sort(([a, x], [b, y]) => (a < b ? -1 : a > b ? 1 : x < y ? -1 : x > y ? 1 : 0));
+  u.search = new URLSearchParams(params).toString();
+  const m = method.toUpperCase();
+  return `${m} ${u.href}${m !== 'GET' && m !== 'HEAD' && body ? ` #${sha1(body).slice(0, 16)}` : ''}`;
+};
+
+export class Archive {
+  /**
+   * @param {string} dir
+   * @param {{ mode: 'record' | 'replay' | 'off', ignore?: string[], skip?: (url: string) => boolean, merge?: boolean }} opts
+   */
+  constructor(dir, opts) {
+    this.dir = dir;
+    this.mode = opts.mode;
+    this.ignore = opts.ignore ?? VOLATILE;
+    this.skip = opts.skip ?? (() => false);
+    /** @type {Record<string, { status: number, headers: Record<string, string>, body: string | null, n: number }>} */
+    this.entries = {};
+    this.meta = {};
+    this.pending = new Set();
+    /** Keys recorded in this session: the first response wins. */
+    this.seen = new Set();
+    this.stats = { served: 0, fuzzy: 0, missed: /** @type {string[]} */ ([]), recorded: 0 };
+    this.n = 0;
+    /** Pages' scopes (scope()), the scope and occurrence of each request recorded in one, the occurrences served. */
+    this.scopes = new WeakMap();
+    this.reqScope = new WeakMap();
+    this.counts = new Map();
+    if (opts.mode === 'replay') {
+      const file = join(dir, 'index.json');
+      if (!existsSync(file)) throw new Error(`no recording in ${dir}: record one first (yarn luma parity --record)`);
+      const idx = JSON.parse(readFileSync(file, 'utf8'));
+      this.entries = idx.entries ?? {};
+      this.meta = idx.meta ?? {};
+      this.byPath = new Map();
+      for (const [k, e] of Object.entries(this.entries)) {
+        if (k.startsWith('[')) continue;
+        const [m, href] = k.split(' ');
+        if (m !== 'GET') continue;
+        const u = new URL(href);
+        const p = `${u.origin}${u.pathname}`;
+        if (!this.byPath.has(p)) this.byPath.set(p, []);
+        this.byPath.get(p).push({ key: k, params: new URLSearchParams(u.search), n: e.n });
+      }
+      for (const l of this.byPath.values()) l.sort((a, b) => a.n - b.n);
+    }
+    if (opts.mode === 'record') {
+      // A partial recording (--only) adds to the one there; a whole one starts afresh.
+      const file = join(dir, 'index.json');
+      if (opts.merge && existsSync(file)) {
+        const idx = JSON.parse(readFileSync(file, 'utf8'));
+        this.entries = idx.entries ?? {};
+        this.meta = idx.meta ?? {};
+        this.n = Math.max(0, ...Object.values(this.entries).map((e) => e.n + 1));
+      } else rmSync(dir, { recursive: true, force: true });
+      mkdirSync(join(dir, 'bodies'), { recursive: true });
+    }
+  }
+
+  /** Recording: every response the page gets. Replay: every request answered from the recording. @param {import('playwright-core').Page} page */
+  async attach(page) {
+    if (this.mode === 'record') {
+      // A scoped page: each request's scope and occurrence, at the time it is made (responses come in any order).
+      page.on('request', (req) => {
+        const scope = this.scopes.get(page);
+        if (!scope) return;
+        const url = req.url();
+        if (!/^https?:/.test(url)) return;
+        const k = `[${scope}] ${keyOf(req.method(), url, req.postDataBuffer(), this.ignore)}`;
+        const n = (this.counts.get(k) ?? 0) + 1;
+        this.counts.set(k, n);
+        this.reqScope.set(req, n > 1 ? `${k} ~${n}` : k);
+      });
+      page.on('response', (res) => {
+        const p = this.record(res).catch(() => {});
+        this.pending.add(p);
+        p.finally(() => this.pending.delete(p));
+      });
+    } else if (this.mode === 'replay') {
+      await page.route('**/*', (route) => this.replay(route, page));
+    }
+  }
+
+  /**
+   * A scope for a page's requests from now on (null: none): recorded under it, replayed from it first.
+   * @param {import('playwright-core').Page} page @param {string | null} tag
+   */
+  scope(page, tag) {
+    if (tag) this.scopes.set(page, tag);
+    else this.scopes.delete(page);
+  }
+
+  /** @param {import('playwright-core').Response} res */
+  async record(res) {
+    const req = res.request();
+    const url = req.url();
+    if (!/^https?:/.test(url) || AUTH.test(url) || this.skip(url) || req.method() === 'OPTIONS') return;
+    const scoped = this.reqScope.get(req);
+    const key = scoped ?? keyOf(req.method(), url, req.postDataBuffer(), this.ignore);
+    if (this.seen.has(key)) return;
+    this.seen.add(key);
+    const status = res.status();
+    let body = null;
+    if (status < 300 || status >= 400) {
+      const buf = await res.body().catch(() => null);
+      if (buf == null) return;
+      body = sha1(buf);
+      const file = join(this.dir, 'bodies', body);
+      if (!existsSync(file)) writeFileSync(file, buf);
+    }
+    const headers = Object.fromEntries(Object.entries(await res.allHeaders().catch(() => res.headers())).filter(([k]) => KEEP_HEADERS.test(k)));
+    this.entries[key] = { status, headers, body, n: this.n++ };
+    this.stats.recorded++;
+  }
+
+  /** @param {import('playwright-core').Route} route @param {import('playwright-core').Page} [page] */
+  async replay(route, page) {
+    try {
+      return await this.answer(route, page);
+    } catch {
+      // A page gone meanwhile, an unreadable body: never a request left hanging.
+      return route.abort('failed').catch(() => {});
+    }
+  }
+
+  /** @param {import('playwright-core').Route} route @param {import('playwright-core').Page} [page] */
+  async answer(route, page) {
+    const req = route.request();
+    const url = req.url();
+    const origin = req.headers()['origin'];
+    const cors = origin ? { 'access-control-allow-origin': origin, 'access-control-allow-credentials': 'true', 'access-control-allow-headers': '*', 'access-control-allow-methods': 'GET, POST, OPTIONS' } : {};
+    if (req.method() === 'OPTIONS') return route.fulfill({ status: 204, headers: cors });
+    if (AUTH.test(url)) {
+      if (url.includes('/browser-challenge')) return route.fulfill({ status: 200, contentType: 'application/json', headers: cors, body: JSON.stringify({ nonce: 'parity', difficulty: 0 }) });
+      return route.fulfill({ status: 200, contentType: 'application/json', headers: cors, body: JSON.stringify({ access_token: 'parity-replay', expires_in: 86400, token_type: 'Bearer' }) });
+    }
+    const key = keyOf(req.method(), url, req.postDataBuffer(), this.ignore);
+    let e = null;
+    // A scoped page: the n-th answer of this key in its scope (or the last one before it), else the plain recording.
+    const scope = page ? this.scopes.get(page) : null;
+    if (scope) {
+      const k = `[${scope}] ${key}`;
+      const n = (this.counts.get(k) ?? 0) + 1;
+      this.counts.set(k, n);
+      for (let i = n; i >= 1 && !e; i--) e = this.entries[i > 1 ? `${k} ~${i}` : k] ?? null;
+    }
+    e ??= this.entries[key];
+    if (!e && req.method() === 'GET') {
+      const u = new URL(url);
+      const cands = this.byPath.get(`${u.origin}${u.pathname}`) ?? [];
+      let best = null;
+      let bestScore = -1;
+      for (const c of cands) {
+        let s = 0;
+        for (const [k, v] of u.searchParams) if (c.params.get(k) === v) s++;
+        if (s > bestScore) [best, bestScore] = [c, s];
+      }
+      if (best) {
+        e = this.entries[best.key];
+        this.stats.fuzzy++;
+      }
+    }
+    if (!e) {
+      this.stats.missed.push(key);
+      return route.abort('internetdisconnected');
+    }
+    this.stats.served++;
+    const body = e.body ? readFileSync(join(this.dir, 'bodies', e.body)) : Buffer.alloc(0);
+    return route.fulfill({ status: e.status, headers: { ...e.headers, ...cors }, body });
+  }
+
+  /** Waits for the bodies being written. */
+  async flush() {
+    while (this.pending.size) await Promise.all([...this.pending]);
+  }
+
+  /** Writes the index (sorted: a re-recording diffs cleanly). @param {Record<string, unknown>} meta */
+  async save(meta = {}) {
+    if (this.mode !== 'record') return;
+    await this.flush();
+    const entries = Object.fromEntries(Object.entries(this.entries).sort(([a], [b]) => (a < b ? -1 : 1)));
+    writeFileSync(join(this.dir, 'index.json'), `${JSON.stringify({ meta, entries }, null, 1)}\n`);
+  }
+}

package/parity/args.mjs

@@ -0,0 +1,137 @@
+// The command line of `yarn luma parity` (parity/run.mjs): its options, parsed
+// without side effects (unit-tested).
+import { TARGET } from './compare.mjs';
+
+export const USAGE = `usage: yarn luma parity [options]
+
+  (default)            replay the recording (--archive): offline, deterministic
+  --target <n>         the template score that ends the loop (default ${TARGET}): exit 0 only at or over it,
+                       with no CRITICAL or MAJOR template difference left and every mandatory component
+                       mapped or excluded; 1 otherwise; 2 nothing compared (or the run broke)
+  --record             the live site, recorded into the archive (replaces it; with --only, adds to it)
+  --live               the live site, nothing recorded
+  --init [file]        propose a draft map from the site's pages (default integration/parity.draft.json)
+  --their-plp <path>   with --init: their own search is disabled; our search page is drafted against this
+                       category listing of theirs (its tile, grid, facets, sort, count and pager)
+  --our-search <path>  with --init: our search page (default /search?q=<the fixtures' query>)
+  --map <file>         the map (default integration/parity.json)
+  --archive <dir>      the recording (default parity/recording)
+  --only <names>       components to compare (comma-separated)
+  --viewports <list>   widths, e.g. 390,1440 (default: the map's)
+  --out <dir>          the report folder: index.html, report.json, crops (default parity-report)
+  --json <file>        also write the JSON report there
+  --all                every difference in the terminal (default: the first 12 per component and width)
+  --headed             show the browser
+  --profile <dir>      a Chrome profile you use on the site (runs headed; copied first: Chrome locks one in use)
+  --dev [url|port]     the integration from the dev server (yarn dev) instead of building it: its URL or port
+                       (default https://localhost:8069; a URL with a path is the entry itself)
+  --block <patterns>   vendor scripts to block on both sides (comma-separated: hosts, or regular expressions
+                       on the URL); --init also blocks every *.luigisbox.{tech,com,ai} script
+  --no-build           use the integration's dist/ as it is
+  --host <name>        the storefront host (default: the map's, LBX_HOST)
+  --site-dir <dir>     the integration repository (default: the current directory, LBX_SITE_DIR)`;
+
+/**
+ * The options, or why they are wrong (`error`), or `help`.
+ * @param {string[]} args process.argv.slice(2)
+ */
+export const parseArgs = (args) => {
+  const opt = { mode: 'replay', init: /** @type {string | null} */ (null), map: '', archive: '', only: /** @type {string[]} */ ([]), viewports: /** @type {number[] | null} */ (null), out: 'parity-report', json: '', all: false, headed: false, profile: '', dev: /** @type {string | false} */ (false), block: /** @type {string[]} */ ([]), build: true, host: '', siteDir: '', paths: /** @type {string[]} */ ([]), theirPlp: '', ourSearch: '', target: TARGET };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    let missing = false;
+    const next = () => {
+      const v = args[++i];
+      if (v === undefined || v.startsWith('--')) {
+        missing = true;
+        return '';
+      }
+      return v;
+    };
+    if (a === '--help' || a === '-h') return { help: true, opt };
+    if (a === '--record') opt.mode = 'record';
+    else if (a === '--live') opt.mode = 'live';
+    else if (a === '--init') opt.init = args[i + 1] && !args[i + 1].startsWith('--') && /\.json$/.test(args[i + 1]) ? args[++i] : '';
+    else if (a === '--target') {
+      const v = next();
+      const n = Number(v);
+      if (!missing && (v.trim() === '' || !Number.isFinite(n) || n < 0 || n > 100)) return { error: `--target: a template score from 0 to 100 (got "${v}")`, opt };
+      opt.target = n;
+    } else if (a === '--their-plp' || a === '--our-search') {
+      const v = next();
+      if (!missing && !v.startsWith('/')) return { error: `${a}: a path starting with "/" (got "${v}")`, opt };
+      opt[a === '--their-plp' ? 'theirPlp' : 'ourSearch'] = v;
+    } else if (a === '--map') opt.map = next();
+    else if (a === '--archive') opt.archive = next();
+    else if (a === '--only') opt.only = next().split(',').map((s) => s.trim()).filter(Boolean);
+    else if (a === '--viewports') opt.viewports = next().split(',').map(Number);
+    else if (a === '--out') opt.out = next();
+    else if (a === '--json') opt.json = next();
+    else if (a === '--all') opt.all = true;
+    else if (a === '--headed') opt.headed = true;
+    else if (a === '--profile') opt.profile = next();
+    else if (a === '--dev') {
+      // The dev server's URL or port, when the next argument is one (else the default, https://localhost:8069).
+      const v = args[i + 1];
+      if (v && !v.startsWith('--') && !v.startsWith('/') && (/^\d{2,5}$/.test(v) || /^https?:\/\//.test(v) || /^[\w.-]+:\d{2,5}$/.test(v))) opt.dev = args[++i];
+      else opt.dev = 'https://localhost:8069';
+      if (!devBundle(opt.dev)) return { error: `--dev: the dev server's URL or port (got "${opt.dev}")`, opt };
+    } else if (a === '--block') {
+      for (const x of next().split(',').map((s) => s.trim()).filter(Boolean)) {
+        const re = blockPattern(x);
+        if (!re) return { error: `--block: "${x}" is neither a host nor a regular expression`, opt };
+        opt.block.push(re);
+      }
+    }
+    else if (a === '--no-build') opt.build = false;
+    else if (a === '--host') opt.host = next();
+    else if (a === '--site-dir') opt.siteDir = next();
+    else if (a.startsWith('/')) opt.paths.push(a);
+    else return { error: `unknown argument "${a}"`, opt };
+    if (missing) return { error: `${a} needs a value`, opt };
+  }
+  // A profile carries a site's cookies: it is for a session a person sees, never headless.
+  if (opt.profile) opt.headed = true;
+  if ((opt.theirPlp || opt.ourSearch) && opt.init == null) return { error: `${opt.theirPlp ? '--their-plp' : '--our-search'} drafts a map: use it with --init (the map's pages say it afterwards: docs/PARITY.md)`, opt };
+  return { opt };
+};
+
+/**
+ * The integration's entry on the dev server: `--dev` alone is
+ * https://localhost:8069; a port is https://localhost:<port>; a URL is that
+ * server (its path, when it has one, the entry itself: a server that serves
+ * it elsewhere). Null when it is neither.
+ * @param {string | false | null | undefined} dev
+ * @returns {{ origin: string, bundle: string } | null}
+ */
+export const devBundle = (dev) => {
+  if (!dev) return null;
+  const v = String(dev);
+  const raw = /^\d{2,5}$/.test(v) ? `https://localhost:${v}` : /^[\w.-]+:\d{2,5}$/.test(v) ? `https://${v}` : v;
+  try {
+    const u = new URL(raw);
+    if (!/^https?:$/.test(u.protocol)) return null;
+    const port = Number(u.port || (u.protocol === 'https:' ? 443 : 80));
+    if (!(port > 0 && port < 65536)) return null;
+    return { origin: u.origin, bundle: u.pathname.length > 1 ? `${u.origin}${u.pathname}` : `${u.origin}/integration/__integration.ts` };
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * A pattern of `--block` as a regular expression's source: a host
+ * (`cdn.vendor.com`: that host and its subdomains, any path), else the
+ * pattern itself when it is a valid regular expression; null otherwise.
+ * @param {string} x
+ */
+export const blockPattern = (x) => {
+  const host = /^(\*\.)?([a-z0-9-]+\.)+[a-z]{2,}$/i.exec(x);
+  if (host) return `^https?://([a-z0-9-]+\\.)*${x.replace(/^\*\./, '').replace(/[.]/g, '\\.')}(:\\d+)?/`;
+  try {
+    new RegExp(x);
+    return x;
+  } catch {
+    return null;
+  }
+};