@recursica/adapter-tester 3.0.0 → 5.0.0

package/dist/testing.js

@@ -1,95 +1,148 @@
-import { test as I, expect as M } from "@playwright/test";
-import { existsSync as l, readFileSync as g, mkdirSync as w, writeFileSync as y } from "node:fs";
-import L from "pixelmatch";
-import { PNG as O } from "pngjs";
-import { join as P } from "node:path";
-import { a as R, i as U } from "./index-DqQzFSAH.js";
-function G(e, t) {
-  const r = O.sync.read(e), s = O.sync.read(t);
-  if (r.width !== s.width || r.height !== s.height)
-    return 1 / 0;
-  const o = new O({ width: r.width, height: r.height });
-  return L(r.data, s.data, o.data, r.width, r.height, {
-    threshold: 0.1
-  });
-}
-const V = "http://json-schema.org/draft-07/schema#", _ = "https://github.com/borderux/recursica/tree/main/packages/adapter-tester/src/golden/manifest.schema.json", J = "test/golden/manifest.json", W = "Tracks golden (baseline) image metadata for @recursica/adapter-tester's golden-image visual regression checks. One manifest lives alongside its adapter's test/golden/<story-id>.png files, keyed by story id.", H = "object", K = { type: "object", additionalProperties: !1, required: ["createdAt"], properties: { createdAt: { type: "string", format: "date-time", description: "When this story's own golden PNG was last captured, via --update-golden, --approve-divergence, or first-run auto-create." }, sourceOfTruthCreatedAt: { type: "string", format: "date-time", description: "The source-of-truth adapter's (mantine) manifest `createdAt` for this story at the time this adapter's divergence from it was last reviewed via --approve-divergence. Omitted on the source-of-truth adapter's own manifest, and omitted here until the first approval. If mantine's current `createdAt` for this story is newer than this value, the divergence is flagged again for re-review." } } }, X = {
-  $schema: V,
-  $id: _,
-  title: J,
-  description: W,
-  type: H,
-  additionalProperties: K
-}, q = U, C = new R.Ajv({ allErrors: !0, strict: !0 });
-q(C);
-const N = C.compile(X);
-function S(e, t) {
-  if (N(e)) return;
-  const r = (N.errors ?? []).map((s) => {
-    var c;
-    const o = (c = s.params) != null && c.additionalProperty ? ` '${s.params.additionalProperty}'` : "";
-    return `  - ${s.instancePath || "root"} ${s.message}${o}`;
+import { expect as J } from "@playwright/test";
+import { existsSync as v, unlinkSync as Y, readFileSync as x, mkdirSync as b, writeFileSync as E, closeSync as Q, openSync as Z, renameSync as ee, rmSync as te } from "node:fs";
+import re from "pixelmatch";
+import { PNG as P } from "pngjs";
+import { join as G } from "node:path";
+import { a as oe, i as ne } from "./index-DqQzFSAH.js";
+function R(e, t) {
+  const o = P.sync.read(e), r = P.sync.read(t);
+  if (o.width !== r.width || o.height !== r.height)
+    return { diffPixels: 1 / 0, diffImage: null };
+  const s = new P({ width: o.width, height: o.height });
+  return { diffPixels: re(
+    o.data,
+    r.data,
+    s.data,
+    o.width,
+    o.height,
+    { threshold: 0.1 }
+  ), diffImage: P.sync.write(s) };
+}
+const se = "http://json-schema.org/draft-07/schema#", ie = "https://github.com/borderux/recursica/tree/main/packages/adapter-tester/src/golden/manifest.schema.json", ae = "test/golden/manifest.json", ce = "Tracks golden (baseline) image metadata for @recursica/adapter-tester's golden-image visual regression checks. One manifest lives alongside its adapter's test/golden/<story-id>.png files, keyed by story id.", de = "object", he = { type: "object", additionalProperties: !1, required: ["createdAt"], properties: { createdAt: { type: "string", format: "date-time", description: "When this story's own golden PNG was last captured, via --update-golden, --approve-divergence, or first-run auto-create." }, sourceOfTruthCreatedAt: { type: "string", format: "date-time", description: "The source-of-truth adapter's (mantine) manifest `createdAt` for this story at the time this adapter's divergence from it was last reviewed via --approve-divergence. Omitted on the source-of-truth adapter's own manifest, and omitted here until the first approval. If mantine's current `createdAt` for this story is newer than this value, the divergence is flagged again for re-review." } } }, ue = {
+  $schema: se,
+  $id: ie,
+  title: ae,
+  description: ce,
+  type: de,
+  additionalProperties: he
+}, le = ne, V = new oe.Ajv({ allErrors: !0, strict: !0 });
+le(V);
+const U = V.compile(ue);
+function F(e, t) {
+  if (U(e)) return;
+  const o = (U.errors ?? []).map((r) => {
+    var i;
+    const s = (i = r.params) != null && i.additionalProperty ? ` '${r.params.additionalProperty}'` : "";
+    return `  - ${r.instancePath || "root"} ${r.message}${s}`;
   }).join(`
 `);
   throw new Error(`Invalid ${t}:
-${r}`);
-}
-function v(e) {
-  return P(e, "manifest.json");
-}
-function $(e, t) {
-  return P(e, `${t}.png`);
-}
-function b(e) {
-  const t = v(e);
-  if (!l(t)) return {};
-  const r = JSON.parse(g(t, "utf8"));
-  return S(r, t), r;
-}
-function z(e, t) {
-  const r = v(e);
-  S(t, r);
-  const s = {};
-  for (const o of Object.keys(t).sort())
-    s[o] = t[o];
-  w(e, { recursive: !0 }), y(r, JSON.stringify(s, null, 2) + `
-`);
+${o}`);
+}
+function A(e) {
+  return G(e, "manifest.json");
+}
+function W(e) {
+  return G(e, "manifest.json.lock");
+}
+function S(e, t) {
+  return G(e, `${t}.png`);
+}
+function j(e) {
+  const t = A(e);
+  if (!v(t)) return {};
+  const o = JSON.parse(x(t, "utf8"));
+  return F(o, t), o;
 }
-function Q(e, t, r) {
-  w(e, { recursive: !0 }), y($(e, t), r);
+function fe(e, t) {
+  const o = A(e);
+  F(t, o);
+  const r = {};
+  for (const i of Object.keys(t).sort())
+    r[i] = t[i];
+  b(e, { recursive: !0 });
+  const s = `${o}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  E(s, JSON.stringify(r, null, 2) + `
+`), ee(s, o);
+}
+const pe = 25, ge = 15e3;
+function me(e) {
+  return new Promise((t) => setTimeout(t, e));
+}
+async function we(e) {
+  b(e, { recursive: !0 });
+  const t = W(e), o = Date.now() + ge;
+  for (; ; )
+    try {
+      Q(Z(t, "wx"));
+      return;
+    } catch (r) {
+      if (r.code !== "EEXIST") throw r;
+      if (Date.now() >= o)
+        throw new Error(
+          `Timed out waiting for the manifest lock at "${t}" — delete it if a previous run crashed while holding it.`
+        );
+      await me(pe);
+    }
+}
+function ye(e) {
+  te(W(e), { force: !0 });
+}
+async function X(e, t, o) {
+  await we(e);
+  try {
+    const r = j(e), s = o(r[t]);
+    return s === void 0 ? delete r[t] : r[t] = s, fe(e, r), s;
+  } finally {
+    ye(e);
+  }
 }
-const Y = "borderux/recursica";
-async function Z(e, t) {
-  var c, u;
-  const r = await fetch(`https://registry.npmjs.org/${e}`);
-  if (!r.ok)
+function ve(e, t, o) {
+  b(e, { recursive: !0 }), E(S(e, t), o);
+}
+async function Te(e, t) {
+  const o = j(e), r = Object.keys(o).filter(
+    (s) => !t.has(s)
+  );
+  for (const s of r) {
+    const i = S(e, s);
+    v(i) && Y(i), await X(e, s, () => {
+    });
+  }
+  return r;
+}
+const $e = "borderux/recursica";
+async function Oe(e, t) {
+  var i, d;
+  const o = await fetch(`https://registry.npmjs.org/${e}`);
+  if (!o.ok)
     throw new Error(
-      `Could not reach npm registry for ${e}: ${r.statusText}`
+      `Could not reach npm registry for ${e}: ${o.statusText}`
     );
-  const s = await r.json(), o = ((c = s["dist-tags"]) == null ? void 0 : c[t]) ?? ((u = s.versions) != null && u[t] ? t : void 0);
-  if (!o)
+  const r = await o.json(), s = ((i = r["dist-tags"]) == null ? void 0 : i[t]) ?? ((d = r.versions) != null && d[t] ? t : void 0);
+  if (!s)
     throw new Error(
       `${e} has no version or dist-tag "${t}" on the npm registry.`
     );
-  return o;
+  return s;
 }
-function ee(e) {
+function ke(e) {
   return `packages/${e.split("/").pop()}`;
 }
-async function te(e) {
+async function xe(e) {
   if (e.type === "local")
-    return l(v(e.dir)) ? {
-      manifest: b(e.dir),
-      async readImage(i) {
-        const d = $(e.dir, i);
-        return l(d) ? g(d) : null;
+    return v(A(e.dir)) ? {
+      manifest: j(e.dir),
+      async readImage(h) {
+        const c = S(e.dir, h);
+        return v(c) ? x(c) : null;
       }
     } : (console.warn(
       `No golden baseline found yet at ${e.dir} — source-of-truth divergence check skipped for this run.`
     ), null);
   let t;
   try {
-    t = await Z(
+    t = await Oe(
       e.packageName,
       e.versionSpec
     );
@@ -99,143 +152,202 @@ async function te(e) {
       a
     ), null;
   }
-  const r = P(e.cacheDir, t), s = `${e.packageName}@${t}`, o = `https://raw.githubusercontent.com/${Y}/${s}/${ee(e.packageName)}/test/golden`;
-  let c;
-  const u = v(r);
-  if (l(u))
-    c = b(r);
+  const o = G(e.cacheDir, t), r = `${e.packageName}@${t}`, s = `https://raw.githubusercontent.com/${$e}/${r}/${ke(e.packageName)}/test/golden`;
+  let i;
+  const d = A(o);
+  if (v(d))
+    i = j(o);
   else {
     let a;
     try {
-      a = await fetch(`${o}/manifest.json`);
-    } catch (n) {
+      a = await fetch(`${s}/manifest.json`);
+    } catch (f) {
       return console.warn(
-        `Could not reach GitHub to fetch ${s}'s golden baseline — source-of-truth divergence check skipped for this run.`,
-        n
+        `Could not reach GitHub to fetch ${r}'s golden baseline — source-of-truth divergence check skipped for this run.`,
+        f
       ), null;
     }
     if (!a.ok)
       return console.warn(
-        `No golden baseline published for ${s} — source-of-truth divergence check skipped for this run.`
+        `No golden baseline published for ${r} — source-of-truth divergence check skipped for this run.`
       ), null;
-    const i = await a.text(), d = JSON.parse(i);
-    S(d, `${o}/manifest.json`), w(r, { recursive: !0 }), y(u, i), c = d;
+    const h = await a.text(), c = JSON.parse(h);
+    F(c, `${s}/manifest.json`), b(o, { recursive: !0 }), E(d, h), i = c;
   }
   return {
-    manifest: c,
+    manifest: i,
     async readImage(a) {
-      const i = $(r, a);
-      if (l(i)) return g(i);
-      const d = await fetch(`${o}/${a}.png`);
-      if (!d.ok) return null;
-      const n = Buffer.from(await d.arrayBuffer());
-      return w(r, { recursive: !0 }), y(i, n), n;
+      const h = S(o, a);
+      if (v(h)) return x(h);
+      const c = await fetch(`${s}/${a}.png`);
+      if (!c.ok) return null;
+      const f = Buffer.from(await c.arrayBuffer());
+      return b(o, { recursive: !0 }), E(h, f), f;
     }
   };
 }
-const re = ["Theme", "Tokens", "Introduction"];
-function D(e, t) {
+const be = ["Theme", "Tokens", "Introduction"];
+function B(e, t) {
   return e === t || e.startsWith(t);
 }
-async function se(e, t, r) {
-  let s;
+async function Se(e, t) {
+  let o;
   try {
-    const o = await fetch(`${e.url}/index.json`);
-    if (!o.ok)
+    const r = await fetch(`${e.url}/index.json`);
+    if (!r.ok)
       throw new Error(
-        `Failed to fetch Storybook index: ${o.statusText}`
+        `Failed to fetch Storybook index: ${r.statusText}`
       );
-    const u = (await o.json()).entries || {};
-    s = Object.values(u).filter(
-      (a) => a.type === "story" && !t.some(
-        (i) => a.title === i || a.title.startsWith(`${i}/`)
-      ) && !r.some((i) => D(a.id, i))
-    ), s.sort((a, i) => a.id.localeCompare(i.id));
-  } catch (o) {
+    const i = (await r.json()).entries || {};
+    o = Object.values(i).filter(
+      (d) => d.type === "story" && !t.some(
+        (a) => d.title === a || d.title.startsWith(`${a}/`)
+      )
+    ), o.sort((d, a) => d.id.localeCompare(a.id));
+  } catch (r) {
     throw console.error(
       "Failed to load Storybook index from",
       `${e.url}/index.json`,
-      o
+      r
     ), new Error(
       `Storybook target "${e.name}" is not responsive or index.json is missing. Please ensure its Storybook is running.`
     );
   }
-  return s;
+  return o;
 }
-function oe(e, t, r) {
-  let s;
-  for (const o of Object.keys(t))
-    D(e, o) && (!s || o.length > s.length) && (s = o);
-  return s !== void 0 ? t[s] : r;
+function K(e, t, o) {
+  let r;
+  for (const s of Object.keys(t))
+    B(e, s) && (!r || s.length > r.length) && (r = s);
+  return r !== void 0 ? t[r] : o;
 }
-async function le(e) {
+async function Ie(e) {
   const t = e.isSourceOfTruthAdapter ? e.targets[0] : e.targets.find((n) => !n.sourceOfTruth);
   if (!t)
     throw new Error(
       "adapter-tester config has no non-sourceOfTruth target to run the golden check against."
     );
-  const r = e.excludeTitlePrefixes ?? re, s = e.excludeStoryIds ?? [], o = e.storyThresholds ?? {}, c = e.goldenDir, u = e.goldenMode, a = await se(
-    t,
-    r,
-    s
-  ), i = b(c), d = e.isSourceOfTruthAdapter || !e.sourceOfTruthGolden ? null : await te(e.sourceOfTruthGolden);
-  I.describe(`${t.name} — Golden Image Visual Regression`, () => {
-    for (const n of a)
-      I(`Golden regression for: ${n.title} - ${n.name} (${n.id})`, async ({
-        browser: B
-      }, T) => {
-        const p = await B.newPage();
-        await p.setViewportSize({ width: 800, height: 600 }), await p.goto(
-          `${t.url}/iframe.html?id=${n.id}&viewMode=story`,
-          { waitUntil: "networkidle" }
-        ), await p.waitForSelector("#storybook-root"), await p.waitForTimeout(300);
-        const j = await p.screenshot(), k = $(c, n.id), f = i[n.id];
-        if (u !== "check" || !f || !l(k))
-          Q(c, n.id, j), i[n.id] = f != null && f.sourceOfTruthCreatedAt ? {
-            createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-            sourceOfTruthCreatedAt: f.sourceOfTruthCreatedAt
-          } : { createdAt: (/* @__PURE__ */ new Date()).toISOString() }, f || T.annotations.push({
-            type: "golden-created",
-            description: `No golden existed yet for "${n.id}" — captured one from this run.`
-          });
-        else {
-          const h = g(k), m = G(j, h);
-          await T.attach("Live vs Golden Diff", {
-            body: `${m} mismatched pixels`,
-            contentType: "text/plain"
-          });
-          const x = oe(
-            n.id,
-            o,
-            e.diffThresholdPixels
-          );
-          M.soft(
-            m,
-            `"${n.id}" has drifted from its own golden image`
-          ).toBeLessThan(x);
-        }
-        const A = i[n.id];
-        if (d) {
-          const h = d.manifest[n.id], m = h ? await d.readImage(n.id) : null;
-          if (h && m)
-            if (u === "approve-divergence")
-              i[n.id] = {
-                ...A,
-                sourceOfTruthCreatedAt: h.createdAt
-              };
-            else {
-              const x = g(k), F = G(x, m), E = A.sourceOfTruthCreatedAt;
-              F === 0 || E !== void 0 && E >= h.createdAt || T.annotations.push({
-                type: "source-of-truth-divergence",
-                description: `"${n.id}" differs from the source of truth's golden and hasn't been reviewed — run with --approve-divergence if this is intentional, or fix the adapter styling.`
-              });
-            }
-        }
-        z(c, i);
-      });
-  });
+  const o = e.excludeTitlePrefixes ?? be, r = e.stories ?? {}, s = Object.keys(r).filter(
+    (n) => r[n].exclude
+  ), i = Object.fromEntries(
+    Object.entries(r).filter(([, n]) => n.goldenThreshold !== void 0).map(([n, u]) => [n, u.goldenThreshold])
+  ), d = Object.fromEntries(
+    Object.entries(r).filter(([, n]) => n.sourceOfTruthThreshold !== void 0).map(([n, u]) => [n, u.sourceOfTruthThreshold])
+  ), a = e.goldenDir, h = e.goldenMode, c = e.checkMode, f = await Se(t, o), M = f.filter(
+    (n) => !s.some((u) => B(n.id, u))
+  );
+  if (h === "update-golden") {
+    const n = await Te(
+      a,
+      new Set(M.map((u) => u.id))
+    );
+    n.length > 0 && console.warn(
+      `Pruned ${n.length} orphaned golden(s) no longer in Storybook: ${n.join(", ")}`
+    );
+  }
+  const p = c !== "divergence" || e.isSourceOfTruthAdapter || !e.sourceOfTruthGolden ? null : await xe(e.sourceOfTruthGolden), q = new Set(f.map((n) => n.id)), T = p ? Object.keys(p.manifest).filter(
+    (n) => !q.has(n) && !s.some((u) => B(n, u))
+  ).sort() : [];
+  T.length > 0 && console.error(
+    `[adapter-tester] ${T.length} stor(y/ies) exist in the source of truth but are missing here: ${T.join(", ")}. Add the missing story, or mark it \`exclude: true\` under \`stories\` in adapter-tester.config.json if intentional.`
+  ), console.log(
+    [
+      `[adapter-tester] target: "${t.name}" (${t.url})`,
+      `[adapter-tester] checkMode: "${c}" (${c === "divergence" ? "this project's golden vs source-of-truth's golden" : "live render vs this project's own golden"})`,
+      `[adapter-tester] goldenMode: "${h}"`,
+      `[adapter-tester] goldenThresholdPixels: ${e.goldenThresholdPixels}`,
+      `[adapter-tester] sourceOfTruthThresholdPixels: ${e.sourceOfTruthThresholdPixels}`,
+      c === "divergence" ? e.isSourceOfTruthAdapter ? "[adapter-tester] sourceOfTruthGolden: skipped — this is the source-of-truth adapter, nothing to diverge from" : e.sourceOfTruthGolden ? p ? `[adapter-tester] sourceOfTruthGolden: resolved, ${Object.keys(p.manifest).length} golden(s) available (config: ${JSON.stringify(e.sourceOfTruthGolden)})` : `[adapter-tester] sourceOfTruthGolden: unavailable — no baseline found or unreachable (config: ${JSON.stringify(e.sourceOfTruthGolden)}); divergence check will skip every story` : "[adapter-tester] sourceOfTruthGolden: skipped — no sourceOfTruthGolden configured" : '[adapter-tester] sourceOfTruthGolden: not used in "own" checkMode',
+      `[adapter-tester] stories: ${M.length} to check (excluded: ${s.length}, title prefixes excluded: ${o.join(", ") || "none"})`,
+      `[adapter-tester] story parity with source of truth: ${T.length === 0 ? "OK" : `${T.length} missing (see error above)`}`
+    ].join(`
+`)
+  );
+  const H = c === "divergence" ? "Source-of-Truth Divergence Check" : "Own-Drift Golden Image Check";
+  return {
+    ownTargetName: t.name,
+    suiteLabel: H,
+    stories: M,
+    missingFromSourceOfTruth: T,
+    checkStory: async (n, u, l) => {
+      const O = await u.newPage();
+      await O.setViewportSize({ width: 800, height: 600 }), await O.goto(
+        `${t.url}/iframe.html?id=${n.id}&viewMode=story`,
+        { waitUntil: "networkidle" }
+      ), await O.waitForSelector("#storybook-root"), await O.waitForTimeout(300);
+      const I = await O.screenshot(), C = S(a, n.id), g = j(a)[n.id], z = h !== "check" || !g || !v(C);
+      let $;
+      if (z)
+        ve(a, n.id, I), $ = g != null && g.sourceOfTruthCreatedAt ? {
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          sourceOfTruthCreatedAt: g.sourceOfTruthCreatedAt
+        } : { createdAt: (/* @__PURE__ */ new Date()).toISOString() }, g || l.annotations.push({
+          type: "golden-created",
+          description: `No golden existed yet for "${n.id}" — captured one from this run.`
+        });
+      else if ($ = g, c === "own") {
+        const m = x(C), { diffPixels: w, diffImage: k } = R(
+          I,
+          m
+        ), y = K(
+          n.id,
+          i,
+          e.goldenThresholdPixels
+        );
+        w >= y && (await l.attach("expected", {
+          body: m,
+          contentType: "image/png"
+        }), await l.attach("actual", {
+          body: I,
+          contentType: "image/png"
+        }), k && await l.attach("diff", {
+          body: k,
+          contentType: "image/png"
+        })), J.soft(
+          w,
+          `"${n.id}" has drifted from its own golden image (${w} mismatched pixels, threshold ${y})`
+        ).toBeLessThan(y);
+      }
+      if (p) {
+        const m = p.manifest[n.id], w = m ? await p.readImage(n.id) : null;
+        if (m && w)
+          if (h === "approve-divergence")
+            $ = {
+              ...$,
+              sourceOfTruthCreatedAt: m.createdAt
+            };
+          else {
+            const k = x(C), { diffPixels: y, diffImage: L } = R(
+              k,
+              w
+            ), N = K(
+              n.id,
+              d,
+              e.sourceOfTruthThresholdPixels
+            ), _ = $.sourceOfTruthCreatedAt, D = y < N || _ !== void 0 && _ >= m.createdAt;
+            D || (await l.attach("expected", {
+              body: w,
+              contentType: "image/png"
+            }), await l.attach("actual", {
+              body: k,
+              contentType: "image/png"
+            }), L && await l.attach("diff", {
+              body: L,
+              contentType: "image/png"
+            }), l.annotations.push({
+              type: "source-of-truth-divergence",
+              description: `"${n.id}" differs from the source of truth's golden by ${y} mismatched pixels (threshold ${N}) and hasn't been reviewed — run with --approve-divergence if this is intentional, or fix the adapter styling.`
+            })), J.soft(
+              D,
+              `"${n.id}" differs from the source of truth's golden by ${y} mismatched pixels (threshold ${N}) and hasn't been reviewed — run with --approve-divergence if this is intentional, or fix the adapter styling.`
+            ).toBe(!0);
+          }
+      }
+      await X(a, n.id, () => $);
+    }
+  };
 }
 export {
-  le as runVisualRegression
+  Ie as resolveVisualRegressionPlan
 };
 //# sourceMappingURL=testing.js.map