@penpair/core 0.2.0 → 0.3.1

package/dist/baseline-coverage.js

@@ -3,61 +3,158 @@ import path from "node:path";
 import { createHash } from "node:crypto";
 import { resolveProjectOutput } from "./project-input.js";
 import { pngSize } from "./png.js";
-import { validateBaselines } from "./baselines-config.js";
+import { validateBaselines, } from "./baselines-config.js";
 import { observationHash } from "./journal.js";
-export const designCaseKey = (route, value) => observationHash({ route, viewport: { width: value.viewport.width, height: value.viewport.height }, theme: value.theme, state: value.state, fixture: value.fixture });
+export const designCaseKey = (route, value) => observationHash({
+    route,
+    viewport: {
+        width: value.viewport.width,
+        height: value.viewport.height,
+    },
+    theme: value.theme,
+    state: value.state,
+    fixture: value.fixture,
+});
 export function baselineCoverage(config, results = []) {
     const rows = [];
     for (const requirement of config.coverage?.required ?? []) {
         const key = designCaseKey(requirement.route, requirement);
-        const unsupported = config.coverage?.unsupported?.find(value => designCaseKey(value.route, value) === key);
-        const frames = config.frames.filter(frame => frame.route && frame.case && designCaseKey(frame.route, frame.case) === key);
-        const frameIds = frames.map(frame => frame.id);
+        const unsupported = config.coverage?.unsupported?.find((value) => designCaseKey(value.route, value) === key);
+        const frames = config.frames.filter((frame) => frame.route && frame.case && designCaseKey(frame.route, frame.case) === key);
+        const frameIds = frames.map((frame) => frame.id);
         if (unsupported) {
-            rows.push({ requirement, status: "unsupported", frameIds, reason: unsupported.reason });
+            rows.push({
+                requirement,
+                status: "unsupported",
+                frameIds,
+                reason: unsupported.reason,
+            });
             continue;
         }
         if (!frames.length) {
-            rows.push({ requirement, status: "missing-case", frameIds });
+            rows.push({
+                requirement,
+                status: "missing-case",
+                frameIds,
+            });
             continue;
         }
-        const captures = frames.flatMap(frame => { const found = results.find(result => result.id === frame.id); return found ? [{ frame, result: found }] : []; });
+        const captures = frames.flatMap((frame) => {
+            const found = results.find((result) => result.id === frame.id);
+            return found
+                ? [
+                    {
+                        frame,
+                        result: found,
+                    },
+                ]
+                : [];
+        });
         if (!captures.length || captures.every(({ result }) => !result.approved)) {
-            rows.push({ requirement, status: "missing-capture", frameIds });
+            rows.push({
+                requirement,
+                status: "missing-capture",
+                frameIds,
+            });
             continue;
         }
         const approved = captures.some(({ frame, result }) => {
             const evidence = result.approved && "case" in result.approved ? result.approved : undefined;
-            return evidence?.approval?.kind !== "forced-reference" && !["missing", "unstable", "case-mismatch"].includes(result.status) && evidence?.case && observationHash(evidence.case) === observationHash(frame.case) && result.sha256 === evidence.sha256 && evidence.frameId === result.frameId && evidence.file === result.file && (!result.captured || evidence.fileId === result.captured.fileId && evidence.pageId === result.captured.pageId) && evidence.designSize?.width === frame.case.viewport.width && evidence.designSize?.height === frame.case.viewport.height && result.imageWidth === Math.round(frame.case.viewport.width * evidence.scale) && result.imageHeight === Math.round(frame.case.viewport.height * evidence.scale) && (!frame.case.activeThemeIds || evidence.activeThemeIds && observationHash([...frame.case.activeThemeIds].sort()) === observationHash([...evidence.activeThemeIds].sort()));
+            return (evidence?.approval?.kind !== "forced-reference" &&
+                ![
+                    "missing",
+                    "unstable",
+                    "case-mismatch",
+                ].includes(result.status) &&
+                evidence?.case &&
+                observationHash(evidence.case) === observationHash(frame.case) &&
+                result.sha256 === evidence.sha256 &&
+                evidence.frameId === result.frameId &&
+                evidence.file === result.file &&
+                (!result.captured ||
+                    (evidence.fileId === result.captured.fileId &&
+                        evidence.pageId === result.captured.pageId)) &&
+                evidence.designSize?.width === frame.case.viewport.width &&
+                evidence.designSize?.height === frame.case.viewport.height &&
+                result.imageWidth === Math.round(frame.case.viewport.width * evidence.scale) &&
+                result.imageHeight === Math.round(frame.case.viewport.height * evidence.scale) &&
+                (!frame.case.activeThemeIds ||
+                    (evidence.activeThemeIds &&
+                        observationHash([
+                            ...frame.case.activeThemeIds,
+                        ].sort()) ===
+                            observationHash([
+                                ...evidence.activeThemeIds,
+                            ].sort()))));
+        });
+        const changed = approved &&
+            captures.some(({ result }) => result.status === "changed" &&
+                result.captured &&
+                result.approved &&
+                result.captured.sha256 !== result.approved.sha256);
+        rows.push({
+            requirement,
+            status: changed
+                ? "changed-unapproved"
+                : approved
+                    ? "approved-design-intent"
+                    : "unapproved-metadata",
+            frameIds,
+            ...(!approved
+                ? {
+                    reason: captures.flatMap(({ result }) => result.problems ?? []).join("; ") ||
+                        "Approved case/viewport/theme evidence is absent or mismatched",
+                }
+                : {}),
         });
-        const changed = approved && captures.some(({ result }) => result.status === "changed" && result.captured && result.approved && result.captured.sha256 !== result.approved.sha256);
-        rows.push({ requirement, status: changed ? "changed-unapproved" : approved ? "approved-design-intent" : "unapproved-metadata", frameIds, ...(!approved ? { reason: captures.flatMap(({ result }) => result.problems ?? []).join("; ") || "Approved case/viewport/theme evidence is absent or mismatched" } : {}) });
     }
-    const unknown = config.frames.flatMap(frame => {
+    const unknown = config.frames.flatMap((frame) => {
         const fields = [];
-        if (!frame.case)
+        if (!frame.case) {
             fields.push("viewport", "theme", "state", "fixture", "font environment");
+        }
         else {
-            if (frame.case.fonts === undefined)
+            if (frame.case.fonts === undefined) {
                 fields.push("declared fonts absent");
-            else if (frame.case.fonts.length)
+            }
+            else if (frame.case.fonts.length) {
                 fields.push("font loading/version not observed");
-            if (frame.case.activeThemeIds === undefined)
+            }
+            if (frame.case.activeThemeIds === undefined) {
                 fields.push("theme activation not asserted; label is design intent");
+            }
         }
-        const result = results.find(result => result.id === frame.id);
-        if (frame.case && !result?.captured?.renderEnvironment)
+        const result = results.find((result) => result.id === frame.id);
+        if (frame.case && !result?.captured?.renderEnvironment) {
             fields.push("renderer environment not observed");
-        return fields.length ? [{ id: frame.id, fields }] : [];
+        }
+        return fields.length
+            ? [
+                {
+                    id: frame.id,
+                    fields,
+                },
+            ]
+            : [];
     });
-    return { schemaVersion: 1, kind: "baseline-coverage", configured: Boolean(config.coverage), designCasesComplete: rows.length > 0 && rows.every(row => row.status === "approved-design-intent"), rows, unknown, browserVerification: "not-run", accessibility: "not-assessed" };
+    return {
+        schemaVersion: 1,
+        kind: "baseline-coverage",
+        configured: Boolean(config.coverage),
+        designCasesComplete: rows.length > 0 && rows.every((row) => row.status === "approved-design-intent"),
+        rows,
+        unknown,
+        browserVerification: "not-run",
+        accessibility: "not-assessed",
+    };
 }
 async function boundedRead(file, maximum) {
     const handle = await open(file, "r");
     try {
         const info = await handle.stat();
-        if (!info.isFile() || info.size > maximum)
+        if (!info.isFile() || info.size > maximum) {
             throw new Error("Artifact exceeds the coverage read budget or is not a regular file");
+        }
         return await handle.readFile();
     }
     finally {
@@ -67,47 +164,84 @@ async function boundedRead(file, maximum) {
 /** Offline coverage validates the approved image bytes, never only a manifest's claims. */
 export async function readBaselineCoverage(root, config, expectedFileId) {
     config = structuredClone(config);
-    validateBaselines(config, message => { throw new Error(message); });
+    validateBaselines(config, (message) => {
+        throw new Error(message);
+    });
     const file = await resolveProjectOutput(root, path.join(config.root, "penpair-baselines.json"));
     let manifest;
     try {
         manifest = JSON.parse((await boundedRead(file, 16 * 1024 * 1024)).toString("utf8"));
     }
     catch (error) {
-        if (error.code !== "ENOENT")
+        if (error.code !== "ENOENT") {
             throw error;
+        }
     }
-    if (!manifest)
+    if (!manifest) {
         return baselineCoverage(config);
-    if (manifest.schemaVersion !== 2 || !Array.isArray(manifest.frames) || manifest.frames.length > 1000)
+    }
+    if (manifest.schemaVersion !== 2 ||
+        !Array.isArray(manifest.frames) ||
+        manifest.frames.length > 1000) {
         throw new Error("Coverage needs a bounded schema-2 baseline manifest; regenerate a reviewed capture");
-    if (expectedFileId && manifest.fileId !== expectedFileId)
+    }
+    if (expectedFileId && manifest.fileId !== expectedFileId) {
         throw new Error("Coverage manifest belongs to a different pinned file");
+    }
     const ids = new Set();
     for (const value of manifest.frames) {
-        if (!value || typeof value.id !== "string" || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(value.id) || ids.has(value.id) || !["new", "same", "changed", "missing", "unstable", "case-mismatch"].includes(value.status) || typeof value.file !== "string" || !value.file)
+        if (!value ||
+            typeof value.id !== "string" ||
+            !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(value.id) ||
+            ids.has(value.id) ||
+            ![
+                "new",
+                "same",
+                "changed",
+                "missing",
+                "unstable",
+                "case-mismatch",
+            ].includes(value.status) ||
+            typeof value.file !== "string" ||
+            !value.file) {
             throw new Error("Malformed baseline frame records");
+        }
         ids.add(value.id);
     }
-    const results = manifest.frames.map(value => ({ ...value }));
+    const results = manifest.frames.map((value) => ({
+        ...value,
+    }));
     for (const result of results) {
-        if (!result.approved)
+        if (!result.approved) {
             continue;
+        }
         try {
-            if (typeof result.file !== "string" || path.isAbsolute(result.file) || result.file.split(/[\\/]/).includes(".."))
+            if (typeof result.file !== "string" ||
+                path.isAbsolute(result.file) ||
+                result.file.split(/[\\/]/).includes("..")) {
                 throw new Error("Approved image path leaves its baseline folder");
-            if ("fileId" in result.approved && result.approved.fileId !== manifest.fileId)
+            }
+            if ("fileId" in result.approved && result.approved.fileId !== manifest.fileId) {
                 throw new Error("Approved image provenance belongs to a different file");
+            }
             const target = await resolveProjectOutput(root, path.join(config.root, result.file));
-            const bytes = await boundedRead(target, 64 * 1024 * 1024), size = pngSize(bytes);
-            if (!size || size.width < 1 || size.height < 1 || createHash("sha256").update(bytes).digest("hex") !== result.approved.sha256 || result.sha256 !== result.approved.sha256)
+            const bytes = await boundedRead(target, 64 * 1024 * 1024);
+            const size = pngSize(bytes);
+            if (!size ||
+                size.width < 1 ||
+                size.height < 1 ||
+                createHash("sha256").update(bytes).digest("hex") !== result.approved.sha256 ||
+                result.sha256 !== result.approved.sha256) {
                 throw new Error("Approved PNG bytes do not match their manifest");
+            }
             result.imageWidth = size.width;
             result.imageHeight = size.height;
         }
         catch (error) {
             result.status = "case-mismatch";
-            result.problems = [error instanceof Error ? error.message : String(error)];
+            result.problems = [
+                error instanceof Error ? error.message : String(error),
+            ];
         }
     }
     return baselineCoverage(config, results);

package/dist/baselines-config.js

@@ -1,80 +1,170 @@
 import path from "node:path";
 const idPattern = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 export function validateBaselines(value, fail) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
         return fail("baselines must be an object");
+    }
     const v = value;
-    if (typeof v.page !== "string" || v.page.length === 0)
+    if (typeof v.page !== "string" || v.page.length === 0) {
         fail("baselines.page must be the name of a page");
-    if (typeof v.root !== "string" || v.root.length === 0 || path.isAbsolute(v.root) || v.root.split(/[\\/]/).includes(".."))
+    }
+    if (typeof v.root !== "string" ||
+        v.root.length === 0 ||
+        path.isAbsolute(v.root) ||
+        v.root.split(/[\\/]/).includes("..")) {
         fail("baselines.root must be a relative folder that stays inside the project");
-    if (!Array.isArray(v.frames) || v.frames.length === 0 || v.frames.length > 1000)
+    }
+    if (!Array.isArray(v.frames) || v.frames.length === 0 || v.frames.length > 1000) {
         fail("baselines.frames must list at least one frame, at most 1000");
+    }
     const seen = new Set();
     for (const entry of v.frames) {
         const f = entry;
-        if (typeof f !== "object" || f === null)
+        if (typeof f !== "object" || f === null) {
             fail("every entry in baselines.frames must be an object");
-        if (typeof f.frame !== "string" || f.frame.length === 0)
+        }
+        if (typeof f.frame !== "string" || f.frame.length === 0) {
             fail("every baselines.frames entry needs a frame name");
-        if (typeof f.id !== "string" || !idPattern.test(f.id))
+        }
+        if (typeof f.id !== "string" || !idPattern.test(f.id)) {
             fail(`baselines.frames id ${JSON.stringify(f.id)} must be lowercase letters, digits, hyphens or underscores`);
-        if (seen.has(f.id))
+        }
+        if (seen.has(f.id)) {
             fail(`baselines.frames id ${JSON.stringify(f.id)} is used twice`);
+        }
         seen.add(f.id);
         if (f.case !== undefined) {
             validateBaselineCase(f.case, fail);
-            if (typeof f.route !== "string" || !f.route)
+            if (typeof f.route !== "string" || !f.route) {
                 fail("baseline case metadata requires an implementation route");
+            }
         }
-        if (f.route !== undefined && (typeof f.route !== "string" || f.route.length === 0))
+        if (f.route !== undefined && (typeof f.route !== "string" || f.route.length === 0)) {
             fail("baselines.frames route must be a non-empty string");
+        }
     }
     if (v.coverage !== undefined) {
         const coverage = v.coverage;
-        if (!coverage || typeof coverage !== "object" || Array.isArray(coverage) || !Array.isArray(coverage.required) || !coverage.required.length || coverage.required.length > 1000 || coverage.unsupported !== undefined && (!Array.isArray(coverage.unsupported) || coverage.unsupported.length > 1000))
+        if (!coverage ||
+            typeof coverage !== "object" ||
+            Array.isArray(coverage) ||
+            !Array.isArray(coverage.required) ||
+            !coverage.required.length ||
+            coverage.required.length > 1000 ||
+            (coverage.unsupported !== undefined &&
+                (!Array.isArray(coverage.unsupported) || coverage.unsupported.length > 1000))) {
             fail("baselines.coverage needs 1–1000 required cases and bounded unsupported cases");
+        }
         const required = new Set();
-        const key = (value) => JSON.stringify([value.route, value.viewport.width, value.viewport.height, value.theme, value.state, value.fixture]);
+        const key = (value) => JSON.stringify([
+            value.route,
+            value.viewport.width,
+            value.viewport.height,
+            value.theme,
+            value.state,
+            value.fixture,
+        ]);
         for (const value of coverage.required) {
-            validateBaselineCase(value, fail, ["route"]);
-            if (typeof value.route !== "string" || !value.route)
+            validateBaselineCase(value, fail, [
+                "route",
+            ]);
+            if (typeof value.route !== "string" || !value.route) {
                 fail("coverage cases need a route");
-            if (required.has(key(value)))
+            }
+            if (required.has(key(value))) {
                 fail("Duplicate required coverage case");
+            }
             required.add(key(value));
         }
         const unsupported = new Set();
         for (const value of coverage.unsupported ?? []) {
-            validateBaselineCase(value, fail, ["route", "reason"]);
-            if (typeof value.route !== "string" || !value.route || typeof value.reason !== "string" || !value.reason.trim())
+            validateBaselineCase(value, fail, [
+                "route",
+                "reason",
+            ]);
+            if (typeof value.route !== "string" ||
+                !value.route ||
+                typeof value.reason !== "string" ||
+                !value.reason.trim()) {
                 fail("unsupported cases need route and reason");
-            if (!required.has(key(value)) || unsupported.has(key(value)))
+            }
+            if (!required.has(key(value)) || unsupported.has(key(value))) {
                 fail("unsupported cases must uniquely reference required cases");
+            }
             unsupported.add(key(value));
         }
     }
-    if (v.threshold !== undefined && (typeof v.threshold !== "number" || !Number.isFinite(v.threshold) || v.threshold < 0 || v.threshold > 1))
+    if (v.threshold !== undefined &&
+        (typeof v.threshold !== "number" ||
+            !Number.isFinite(v.threshold) ||
+            v.threshold < 0 ||
+            v.threshold > 1)) {
         fail("baselines.threshold must be a number from 0 to 1");
+    }
     return v;
 }
 export function validateBaselineCase(value, fail, extraKeys = []) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
         return fail("baseline case must be an object");
+    }
     const entry = value;
-    const allowed = new Set(["viewport", "theme", "state", "fixture", ...(extraKeys.length ? [] : ["fonts", "activeThemeIds"]), ...extraKeys]);
-    if (Object.keys(entry).some(key => !allowed.has(key)))
+    const allowed = new Set([
+        "viewport",
+        "theme",
+        "state",
+        "fixture",
+        ...(extraKeys.length
+            ? []
+            : [
+                "fonts",
+                "activeThemeIds",
+            ]),
+        ...extraKeys,
+    ]);
+    if (Object.keys(entry).some((key) => !allowed.has(key))) {
         fail("Unknown baseline case field; capture constraints belong on frame cases");
-    if (entry.viewport && Object.keys(entry.viewport).some(key => !["width", "height"].includes(key)))
+    }
+    if (entry.viewport &&
+        Object.keys(entry.viewport).some((key) => ![
+            "width",
+            "height",
+        ].includes(key))) {
         fail("Viewport accepts width and height only");
-    for (const key of ["theme", "state", "fixture"])
-        if (typeof entry[key] !== "string" || !entry[key].trim() || entry[key].length > 200 || /[\x00-\x1f]/.test(entry[key]))
+    }
+    for (const key of [
+        "theme",
+        "state",
+        "fixture",
+    ]) {
+        if (typeof entry[key] !== "string" ||
+            !entry[key].trim() ||
+            entry[key].length > 200 ||
+            /[\x00-\x1f]/.test(entry[key])) {
             fail(`baseline case ${key} needs a short explicit label`);
-    for (const key of ["width", "height"])
-        if (!entry.viewport || !Number.isInteger(entry.viewport[key]) || entry.viewport[key] < 1 || entry.viewport[key] > 16384)
+        }
+    }
+    for (const key of [
+        "width",
+        "height",
+    ]) {
+        if (!entry.viewport ||
+            !Number.isInteger(entry.viewport[key]) ||
+            entry.viewport[key] < 1 ||
+            entry.viewport[key] > 16384) {
             fail("baseline case viewport dimensions must be integers from 1 to 16384");
-    for (const key of ["fonts", "activeThemeIds"])
-        if (entry[key] !== undefined && (!Array.isArray(entry[key]) || entry[key].length > 100 || entry[key].some(value => typeof value !== "string" || !value.trim()) || new Set(entry[key]).size !== entry[key].length))
+        }
+    }
+    for (const key of [
+        "fonts",
+        "activeThemeIds",
+    ]) {
+        if (entry[key] !== undefined &&
+            (!Array.isArray(entry[key]) ||
+                entry[key].length > 100 ||
+                entry[key].some((value) => typeof value !== "string" || !value.trim()) ||
+                new Set(entry[key]).size !== entry[key].length)) {
             fail(`baseline case ${key} must contain at most 100 unique nonempty strings`);
+        }
+    }
     return entry;
 }