@penpair/core 0.2.0 → 0.3.1

package/dist/baselines.js

@@ -20,8 +20,9 @@ async function readIfExists(file) {
         return await readFile(file);
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (error.code === "ENOENT") {
             return undefined;
+        }
         throw error;
     }
 }
@@ -31,22 +32,43 @@ async function readIfExists(file) {
  * the design never silently becomes the new reference.
  */
 export async function exportBaselines(client, projectRoot, config, options = {}) {
-    if (options.forceReason !== undefined && (!options.update || !options.apply || !options.forceReason.trim() || options.forceReason.length > 2000))
+    if (options.forceReason !== undefined &&
+        (!options.update ||
+            !options.apply ||
+            !options.forceReason.trim() ||
+            options.forceReason.length > 2000)) {
         throw new Error("A nonempty force reason requires apply and update");
+    }
     config = structuredClone(config);
-    validateBaselines(config, message => { throw new Error(message); });
-    const listing = await runOnPage(client, frames({ page: config.page }), config.page, options);
-    if (listing.ok !== true || typeof listing.fileId !== "string" || !listing.fileId || typeof listing.pageId !== "string" || !listing.pageId || !Number.isInteger(listing.revn) || !Array.isArray(listing.frames))
+    validateBaselines(config, (message) => {
+        throw new Error(message);
+    });
+    const listing = await runOnPage(client, frames({
+        page: config.page,
+    }), config.page, options);
+    if (listing.ok !== true ||
+        typeof listing.fileId !== "string" ||
+        !listing.fileId ||
+        typeof listing.pageId !== "string" ||
+        !listing.pageId ||
+        !Number.isInteger(listing.revn) ||
+        !Array.isArray(listing.frames)) {
         throw new Error("Baseline listing lacks file/page/revision evidence");
+    }
     const found = listing.frames;
     const results = [];
     const wrote = [];
     const folder = await resolveProjectOutput(projectRoot, config.root);
     const manifestPath = await resolveProjectOutput(projectRoot, path.join(config.root, "penpair-baselines.json"));
     const previousBytes = await readIfExists(manifestPath);
-    const previous = previousBytes ? JSON.parse(previousBytes.toString("utf8")) : undefined;
-    if (previous && (previous.schemaVersion !== undefined && previous.schemaVersion !== 2 || !Array.isArray(previous.frames)))
+    const previous = previousBytes
+        ? JSON.parse(previousBytes.toString("utf8"))
+        : undefined;
+    if (previous &&
+        ((previous.schemaVersion !== undefined && previous.schemaVersion !== 2) ||
+            !Array.isArray(previous.frames))) {
         throw new Error("Existing baseline manifest is invalid; preserve and inspect it");
+    }
     const runId = randomUUID();
     const generation = `captures/${runId}`;
     const captures = new Map();
@@ -54,79 +76,213 @@ export async function exportBaselines(client, projectRoot, config, options = {})
         options.signal?.throwIfAborted();
         const old = previous?.frames?.find((entry) => entry.id === wanted.id);
         const file = old?.file ?? `${wanted.id}.png`;
-        if (path.isAbsolute(file) || file.split(/[\\/]/).includes(".."))
+        if (path.isAbsolute(file) || file.split(/[\\/]/).includes("..")) {
             throw new Error("Existing baseline path leaves its folder");
+        }
         const matches = found.filter((f) => f.name === wanted.frame);
         if (!matches.length) {
-            results.push({ ...(wanted.case ? { case: wanted.case } : {}), id: wanted.id, frame: wanted.frame, file, status: "missing", written: false });
+            results.push({
+                ...(wanted.case
+                    ? {
+                        case: wanted.case,
+                    }
+                    : {}),
+                id: wanted.id,
+                frame: wanted.frame,
+                file,
+                status: "missing",
+                written: false,
+            });
             continue;
         }
-        if (matches.length > 1)
+        if (matches.length > 1) {
             throw new Error(`more than one top-level frame on ${config.page} is named ${JSON.stringify(wanted.frame)}; rename one so the design reference is unambiguous`);
+        }
         const frame = matches[0];
         options.onStep?.(`exporting ${wanted.frame}`);
-        const exported = await exportShapePng(client, frame.id, { ...options, page: config.page, stable: true });
-        const base = { ...(wanted.case ? { case: wanted.case } : {}), id: wanted.id, frame: wanted.frame, frameId: frame.id, width: frame.width, height: frame.height, file };
-        if (exported.capture.fileId !== listing.fileId || exported.capture.pageId !== listing.pageId || exported.capture.revision !== listing.revn)
+        const exported = await exportShapePng(client, frame.id, {
+            ...options,
+            page: config.page,
+            stable: true,
+        });
+        const base = {
+            ...(wanted.case
+                ? {
+                    case: wanted.case,
+                }
+                : {}),
+            id: wanted.id,
+            frame: wanted.frame,
+            frameId: frame.id,
+            width: frame.width,
+            height: frame.height,
+            file,
+        };
+        if (exported.capture.fileId !== listing.fileId ||
+            exported.capture.pageId !== listing.pageId ||
+            exported.capture.revision !== listing.revn) {
             throw new Error("Baseline source changed during capture; nothing was published");
+        }
         if (!exported.stable) {
-            results.push({ ...base, status: "unstable", written: false });
+            results.push({
+                ...base,
+                status: "unstable",
+                written: false,
+            });
             continue;
         }
-        if (!pngSize(exported.png))
+        if (!pngSize(exported.png)) {
             throw new Error("Baseline export is not a PNG with dimensions");
+        }
         const existing = await readIfExists(await resolveProjectOutput(projectRoot, path.join(config.root, file)));
-        if (old && (!existing || old.sha256 !== sha(existing) || old.approved && old.approved.sha256 !== old.sha256))
+        if (old &&
+            (!existing ||
+                old.sha256 !== sha(existing) ||
+                (old.approved && old.approved.sha256 !== old.sha256))) {
             throw new Error("Approved baseline bytes no longer match their manifest; inspect before replacing");
-        const captured = { ...(wanted.case ? { case: wanted.case } : {}), layout: exported.layout, ...exported.capture, sha256: sha(exported.png), capturedAt: new Date().toISOString(), toolVersion: version, file: `${generation}/${wanted.id}.png` };
+        }
+        const captured = {
+            ...(wanted.case
+                ? {
+                    case: wanted.case,
+                }
+                : {}),
+            layout: exported.layout,
+            ...exported.capture,
+            sha256: sha(exported.png),
+            capturedAt: new Date().toISOString(),
+            toolVersion: version,
+            file: `${generation}/${wanted.id}.png`,
+        };
         const caseProblems = [];
         if (wanted.case) {
-            const viewport = wanted.case.viewport, size = pngSize(exported.png);
-            if (!exported.capture.designSize || exported.capture.designSize.width !== viewport.width || exported.capture.designSize.height !== viewport.height)
+            const viewport = wanted.case.viewport;
+            const size = pngSize(exported.png);
+            if (!exported.capture.designSize ||
+                exported.capture.designSize.width !== viewport.width ||
+                exported.capture.designSize.height !== viewport.height) {
                 caseProblems.push("Observed frame dimensions do not match the declared viewport");
-            if (size.width !== Math.round(viewport.width * exported.capture.scale) || size.height !== Math.round(viewport.height * exported.capture.scale))
+            }
+            if (size.width !== Math.round(viewport.width * exported.capture.scale) ||
+                size.height !== Math.round(viewport.height * exported.capture.scale)) {
                 caseProblems.push("PNG dimensions do not match declared viewport and capture scale");
-            if (wanted.case.activeThemeIds && (!exported.capture.activeThemeIds || observationHash([...wanted.case.activeThemeIds].sort()) !== observationHash([...exported.capture.activeThemeIds].sort())))
+            }
+            if (wanted.case.activeThemeIds &&
+                (!exported.capture.activeThemeIds ||
+                    observationHash([
+                        ...wanted.case.activeThemeIds,
+                    ].sort()) !==
+                        observationHash([
+                            ...exported.capture.activeThemeIds,
+                        ].sort()))) {
                 caseProblems.push("Active native theme IDs do not match the capture assertion");
+            }
         }
         if (caseProblems.length) {
-            results.push({ ...base, status: "case-mismatch", written: false, captured, approved: old?.approved, sha256: old?.sha256, problems: caseProblems });
+            results.push({
+                ...base,
+                status: "case-mismatch",
+                written: false,
+                captured,
+                approved: old?.approved,
+                sha256: old?.sha256,
+                problems: caseProblems,
+            });
             continue;
         }
         const oldCase = old?.approved && "case" in old.approved ? old.approved.case : undefined;
-        const status = !existing ? "new" : sha(existing) === captured.sha256 && observationHash(oldCase ?? null) === observationHash(wanted.case ?? null) && (!old?.approved || "legacy" in old.approved || old.approved.fileId === captured.fileId && old.approved.pageId === captured.pageId && old.approved.frameId === captured.frameId) ? "same" : "changed";
-        const promoteWaiver = status === "same" && old?.approved && "approval" in old.approved && old.approved.approval?.kind === "forced-reference" && options.update === true;
+        const status = !existing
+            ? "new"
+            : sha(existing) === captured.sha256 &&
+                observationHash(oldCase ?? null) === observationHash(wanted.case ?? null) &&
+                (!old?.approved ||
+                    "legacy" in old.approved ||
+                    (old.approved.fileId === captured.fileId &&
+                        old.approved.pageId === captured.pageId &&
+                        old.approved.frameId === captured.frameId))
+                ? "same"
+                : "changed";
+        const promoteWaiver = status === "same" &&
+            old?.approved &&
+            "approval" in old.approved &&
+            old.approved.approval?.kind === "forced-reference" &&
+            options.update === true;
         if ((status === "changed" || promoteWaiver) && options.update && options.apply) {
             const record = await matchingApproval(projectRoot, exported.capture, captured.sha256, wanted.case);
-            if (record)
-                captured.approval = { kind: "owner-words", id: record.id, recordHash: record.hash };
-            else if (options.forceReason)
-                captured.approval = { kind: "forced-reference", reason: options.forceReason };
-            else
+            if (record) {
+                captured.approval = {
+                    kind: "owner-words",
+                    id: record.id,
+                    recordHash: record.hash,
+                };
+            }
+            else if (options.forceReason) {
+                captured.approval = {
+                    kind: "forced-reference",
+                    reason: options.forceReason,
+                };
+            }
+            else {
                 throw new Error("Changed baseline requires matching exact-artifact owner words (penpair approve), or an explicit --force-reason waiver; previous artifacts preserved");
+            }
         }
-        const approve = status === "new" || status === "changed" && options.update === true || Boolean(promoteWaiver);
-        const approved = approve ? captured : old?.approved ?? { legacy: true, sha256: sha(existing) };
+        const approve = status === "new" ||
+            (status === "changed" && options.update === true) ||
+            Boolean(promoteWaiver);
+        const approved = approve
+            ? captured
+            : (old?.approved ?? {
+                legacy: true,
+                sha256: sha(existing),
+            });
         const image = approve ? exported.png : existing;
         const size = pngSize(image);
-        results.push({ ...base, file: approve && options.apply ? captured.file : file, status, written: false, captured,
-            approved: options.apply || !approve ? approved : undefined, sha256: sha(image), bytes: image.length, imageWidth: size?.width, imageHeight: size?.height });
+        results.push({
+            ...base,
+            file: approve && options.apply ? captured.file : file,
+            status,
+            written: false,
+            captured,
+            approved: options.apply || !approve ? approved : undefined,
+            sha256: sha(image),
+            bytes: image.length,
+            imageWidth: size?.width,
+            imageHeight: size?.height,
+        });
         captures.set(wanted.id, exported.png);
     }
-    const after = await runOnPage(client, frames({ page: config.page }), config.page, options);
-    const source = (value) => ({ fileId: value.fileId, pageId: value.pageId, revision: value.revn, frames: value.frames });
-    if (observationHash(source(listing)) !== observationHash(source(after)))
+    const after = await runOnPage(client, frames({
+        page: config.page,
+    }), config.page, options);
+    const source = (value) => ({
+        fileId: value.fileId,
+        pageId: value.pageId,
+        revision: value.revn,
+        frames: value.frames,
+    });
+    if (observationHash(source(listing)) !== observationHash(source(after))) {
         throw new Error("Baseline source changed before publication; previous artifacts were preserved");
-    const complete = results.length === config.frames.length && results.every((result) => result.status !== "missing" && result.status !== "unstable" && result.status !== "case-mismatch");
+    }
+    const complete = results.length === config.frames.length &&
+        results.every((result) => result.status !== "missing" &&
+            result.status !== "unstable" &&
+            result.status !== "case-mismatch");
     if (options.apply && complete) {
-        const evidence = JSON.stringify({ config, results, forceReason: options.forceReason });
-        if (options.redact && options.redact(evidence) !== evidence)
+        const evidence = JSON.stringify({
+            config,
+            results,
+            forceReason: options.forceReason,
+        });
+        if (options.redact && options.redact(evidence) !== evidence) {
             throw new Error("Baseline evidence requires credential redaction; previous artifacts preserved");
+        }
         options.signal?.throwIfAborted();
         options.onStep?.("publishing complete capture");
         options.signal?.throwIfAborted();
         const captureFolder = await resolveProjectOutput(projectRoot, path.join(config.root, "captures"));
-        await mkdir(captureFolder, { recursive: true });
+        await mkdir(captureFolder, {
+            recursive: true,
+        });
         const staged = path.join(folder, `.stage-${runId}`);
         await mkdir(staged);
         try {
@@ -136,29 +292,72 @@ export async function exportBaselines(client, projectRoot, config, options = {})
                 options.onStep?.(`staging ${id}`);
             }
             const cases = reflectionCases(config, results);
-            await writeFile(path.join(staged, "reflection-cases.json"), `${JSON.stringify({ ...cases, captureId: runId }, null, 2)}\n`, { flag: "wx" });
+            await writeFile(path.join(staged, "reflection-cases.json"), `${JSON.stringify({
+                ...cases,
+                captureId: runId,
+            }, null, 2)}\n`, {
+                flag: "wx",
+            });
             options.signal?.throwIfAborted();
             await rename(staged, path.join(captureFolder, runId));
             // Immutable generation first. The canonical manifest is the commit point and is published last.
-            await atomicWriteFile(path.join(folder, "reflection-cases.json"), `${JSON.stringify({ ...cases, captureId: runId }, null, 2)}\n`, { replace: true });
+            await atomicWriteFile(path.join(folder, "reflection-cases.json"), `${JSON.stringify({
+                ...cases,
+                captureId: runId,
+            }, null, 2)}\n`, {
+                replace: true,
+            });
             options.signal?.throwIfAborted();
-            for (const result of results)
-                result.written = result.file === result.captured?.file && (result.status === "new" || options.update === true);
-            const manifest = { schemaVersion: 2, complete: true, captureId: runId, penpotFile: listing.file, fileId: listing.fileId, page: config.page, pageId: listing.pageId,
-                coverage: baselineCoverage(config, results), capturedRevision: listing.revn, casesFile: `${generation}/reflection-cases.json`, note: "Capture provenance and approved provenance are separate. Changed references require exact-artifact owner words or a recorded forced-reference waiver.", frames: results };
-            await atomicWriteFile(path.join(folder, "penpair-baselines.json"), `${JSON.stringify(manifest, null, 2)}\n`, { replace: true });
             for (const result of results) {
-                result.written = result.file === result.captured?.file && (result.status === "new" || options.update === true);
-                if (result.written)
+                result.written =
+                    result.file === result.captured?.file &&
+                        (result.status === "new" || options.update === true);
+            }
+            const manifest = {
+                schemaVersion: 2,
+                complete: true,
+                captureId: runId,
+                penpotFile: listing.file,
+                fileId: listing.fileId,
+                page: config.page,
+                pageId: listing.pageId,
+                coverage: baselineCoverage(config, results),
+                capturedRevision: listing.revn,
+                casesFile: `${generation}/reflection-cases.json`,
+                note: "Capture provenance and approved provenance are separate. Changed references require exact-artifact owner words or a recorded forced-reference waiver.",
+                frames: results,
+            };
+            await atomicWriteFile(path.join(folder, "penpair-baselines.json"), `${JSON.stringify(manifest, null, 2)}\n`, {
+                replace: true,
+            });
+            for (const result of results) {
+                result.written =
+                    result.file === result.captured?.file &&
+                        (result.status === "new" || options.update === true);
+                if (result.written) {
                     wrote.push(path.join(config.root, result.file));
+                }
             }
             wrote.push(path.join(config.root, "reflection-cases.json"), path.join(config.root, "penpair-baselines.json"));
         }
         finally {
-            await rm(staged, { recursive: true, force: true });
+            await rm(staged, {
+                recursive: true,
+                force: true,
+            });
         }
     }
-    return { coverage: baselineCoverage(config, results), complete, fileId: listing.fileId, pageId: listing.pageId, page: config.page, penpotFile: String(listing.file), revn: Number(listing.revn), results, wrote };
+    return {
+        coverage: baselineCoverage(config, results),
+        complete,
+        fileId: listing.fileId,
+        pageId: listing.pageId,
+        page: config.page,
+        penpotFile: String(listing.file),
+        revn: Number(listing.revn),
+        results,
+        wrote,
+    };
 }
 /**
  * Visual cases for Reflection, one per frame that names a route: the image's exact size is the viewport (so the capture and the
@@ -171,24 +370,48 @@ export function reflectionCases(config, results) {
     const pendingCases = [];
     for (const wanted of config.frames) {
         const result = results.find((r) => r.id === wanted.id);
-        if (!wanted.route || !result || result.imageWidth === undefined || result.imageHeight === undefined)
+        if (!wanted.route ||
+            !result ||
+            result.imageWidth === undefined ||
+            result.imageHeight === undefined) {
             continue;
+        }
         if (wanted.case) {
             const approvedCase = result.approved && "case" in result.approved ? result.approved.case : undefined;
-            pendingCases.push({ id: wanted.id, route: wanted.route, case: approvedCase ?? wanted.case, baseline: result.file, ref: `penpair:${wanted.id}`, approvedProvenance: result.approved ?? null, captured: result.captured ?? null, approvedMetadata: Boolean(approvedCase && observationHash(approvedCase) === observationHash(wanted.case)), reason: "Explicit theme/state/fixture/font setup requires an implementation provider mapping", browserVerification: "not-run" });
+            pendingCases.push({
+                id: wanted.id,
+                route: wanted.route,
+                case: approvedCase ?? wanted.case,
+                baseline: result.file,
+                ref: `penpair:${wanted.id}`,
+                approvedProvenance: result.approved ?? null,
+                captured: result.captured ?? null,
+                approvedMetadata: Boolean(approvedCase && observationHash(approvedCase) === observationHash(wanted.case)),
+                reason: "Explicit theme/state/fixture/font setup requires an implementation provider mapping",
+                browserVerification: "not-run",
+            });
             continue;
         }
-        const viewport = { name: `design-${result.imageWidth}x${result.imageHeight}`, width: result.imageWidth, height: result.imageHeight };
-        const entry = (routes[wanted.route] ??= { viewports: [] });
-        if (!entry.viewports.some((v) => v.name === viewport.name))
+        const viewport = {
+            name: `design-${result.imageWidth}x${result.imageHeight}`,
+            width: result.imageWidth,
+            height: result.imageHeight,
+        };
+        const entry = (routes[wanted.route] ??= {
+            viewports: [],
+        });
+        if (!entry.viewports.some((v) => v.name === viewport.name)) {
             entry.viewports.push(viewport);
+        }
         visualSmoke.push({
             id: wanted.id,
             route: wanted.route,
             viewport: viewport.name,
             baselineRoot: config.root,
             baseline: result.file,
-            threshold: { maxDiffPixelRatio: config.threshold ?? 0.05 },
+            threshold: {
+                maxDiffPixelRatio: config.threshold ?? 0.05,
+            },
             strict: false,
             ref: `penpair:${wanted.id}`,
         });

package/dist/cli-arguments.js

@@ -4,11 +4,16 @@ export class CommandArgumentError extends Error {
     remedy = "Use the command's supported flags and required values; see penpair --help.";
 }
 function distance(a, b) {
-    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    let previous = Array.from({
+        length: b.length + 1,
+    }, (_, index) => index);
     for (let i = 1; i <= a.length; i++) {
-        const next = [i];
-        for (let j = 1; j <= b.length; j++)
+        const next = [
+            i,
+        ];
+        for (let j = 1; j <= b.length; j++) {
             next[j] = Math.min(next[j - 1] + 1, previous[j] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
         previous = next;
     }
     return previous[b.length];
@@ -20,15 +25,22 @@ export function parseCommandArgs(config) {
     }
     catch (error) {
         const value = error;
-        if (!value.code?.startsWith("ERR_PARSE_ARGS"))
+        if (!value.code?.startsWith("ERR_PARSE_ARGS")) {
             throw error;
+        }
         const unknown = /Unknown option ['"]--([^'"]+)['"]/.exec(value.message ?? "")?.[1];
         let hint = "";
         if (unknown && unknown.length <= 100) {
-            const candidates = Object.keys(config.options ?? {}).map((name) => ({ name, distance: distance(unknown.toLowerCase(), name.toLowerCase()) })).sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+            const candidates = Object.keys(config.options ?? {})
+                .map((name) => ({
+                name,
+                distance: distance(unknown.toLowerCase(), name.toLowerCase()),
+            }))
+                .sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
             const best = candidates[0];
-            if (best && best.distance <= Math.max(2, Math.ceil(unknown.length / 2)))
+            if (best && best.distance <= Math.max(2, Math.ceil(unknown.length / 2))) {
                 hint = ` Did you mean --${best.name}?`;
+            }
         }
         throw new CommandArgumentError((value.message ?? "Invalid command arguments") + hint);
     }