@penpair/core 0.1.3 → 0.3.0

package/dist/baseline-coverage.js

@@ -0,0 +1,248 @@
+import { open } from "node:fs/promises";
+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 { 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 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);
+        if (unsupported) {
+            rows.push({
+                requirement,
+                status: "unsupported",
+                frameIds,
+                reason: unsupported.reason,
+            });
+            continue;
+        }
+        if (!frames.length) {
+            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,
+                    },
+                ]
+                : [];
+        });
+        if (!captures.length || captures.every(({ result }) => !result.approved)) {
+            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()))));
+        });
+        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 fields = [];
+        if (!frame.case) {
+            fields.push("viewport", "theme", "state", "fixture", "font environment");
+        }
+        else {
+            if (frame.case.fonts === undefined) {
+                fields.push("declared fonts absent");
+            }
+            else if (frame.case.fonts.length) {
+                fields.push("font loading/version not observed");
+            }
+            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) {
+            fields.push("renderer environment not observed");
+        }
+        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",
+    };
+}
+async function boundedRead(file, maximum) {
+    const handle = await open(file, "r");
+    try {
+        const info = await handle.stat();
+        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 {
+        await handle.close();
+    }
+}
+/** 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);
+    });
+    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") {
+            throw error;
+        }
+    }
+    if (!manifest) {
+        return baselineCoverage(config);
+    }
+    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) {
+        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) {
+            throw new Error("Malformed baseline frame records");
+        }
+        ids.add(value.id);
+    }
+    const results = manifest.frames.map((value) => ({
+        ...value,
+    }));
+    for (const result of results) {
+        if (!result.approved) {
+            continue;
+        }
+        try {
+            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) {
+                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);
+            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),
+            ];
+        }
+    }
+    return baselineCoverage(config, results);
+}

package/dist/baselines-config.d.ts

@@ -1,3 +1,25 @@
+/** Declared design intent. It does not switch themes or establish browser behavior. */
+export interface BaselineCase {
+    viewport: {
+        width: number;
+        height: number;
+    };
+    theme: string;
+    state: string;
+    fixture: string;
+    fonts?: string[];
+    /** Optional exact active native theme IDs expected during capture. */
+    activeThemeIds?: string[];
+}
+export interface CoverageRequirement extends Pick<BaselineCase, "viewport" | "theme" | "state" | "fixture"> {
+    route: string;
+}
+export interface CoverageConfig {
+    required: CoverageRequirement[];
+    unsupported?: (CoverageRequirement & {
+        reason: string;
+    })[];
+}
 /** One frame of a Penpot page that becomes an approved reference image. */
 export interface BaselineFrame {
     /** The exact name of a top-level frame on the page. */
@@ -6,6 +28,7 @@ export interface BaselineFrame {
     id: string;
     /** The route in the implementation this frame is the design of. Frames without one are exported but not given a check. */
     route?: string;
+    case?: BaselineCase;
 }
 /** What `penpair baselines` exports: the frames of one page, as images in a folder of the project. */
 export interface BaselinesConfig {
@@ -15,5 +38,7 @@ export interface BaselinesConfig {
     frames: BaselineFrame[];
     /** Allowed share of differing pixels in the generated checks (default 0.05). */
     threshold?: number;
+    coverage?: CoverageConfig;
 }
 export declare function validateBaselines(value: unknown, fail: (message: string) => never): BaselinesConfig;
+export declare function validateBaselineCase(value: unknown, fail: (message: string) => never, extraKeys?: string[]): BaselineCase;

package/dist/baselines-config.js

@@ -1,31 +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)
-        fail("baselines.frames must list at least one frame");
+    }
+    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.route !== undefined && (typeof f.route !== "string" || f.route.length === 0))
+        if (f.case !== undefined) {
+            validateBaselineCase(f.case, fail);
+            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)) {
             fail("baselines.frames route must be a non-empty string");
+        }
     }
-    if (v.threshold !== undefined && (typeof v.threshold !== "number" || v.threshold < 0 || v.threshold > 1))
+    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))) {
+            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,
+        ]);
+        for (const value of coverage.required) {
+            validateBaselineCase(value, fail, [
+                "route",
+            ]);
+            if (typeof value.route !== "string" || !value.route) {
+                fail("coverage cases need a route");
+            }
+            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()) {
+                fail("unsupported cases need route and reason");
+            }
+            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)) {
         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)) {
+        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))) {
+        fail("Unknown baseline case field; capture constraints belong on frame cases");
+    }
+    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])) {
+            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) {
+            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)) {
+            fail(`baseline case ${key} must contain at most 100 unique nonempty strings`);
+        }
+    }
+    return entry;
+}

package/dist/baselines.d.ts

@@ -1,6 +1,9 @@
+export { pngSize } from "./png.js";
 import type { PenpotToolClient } from "./client.js";
-import type { BaselinesConfig } from "./baselines-config.js";
-import { type ExportOptions } from "./export.js";
+import { type BaselineCoverage } from "./baseline-coverage.js";
+import { type BaselineCase, type BaselinesConfig } from "./baselines-config.js";
+import type { LayoutResult } from "./layout.js";
+import { type CaptureIdentity, type ExportOptions } from "./export.js";
 export * from "./baselines-config.js";
 export type BaselineStatus = 
 /** No image in the folder yet. */
@@ -12,8 +15,31 @@ export type BaselineStatus =
 /** The export never settled (two identical renders in a row), so it is not trusted. */
  | "unstable"
 /** The page has no top-level frame with that name. */
- | "missing";
+ | "missing" | "case-mismatch";
+export interface ArtifactProvenance extends CaptureIdentity {
+    approval?: {
+        kind: "owner-words";
+        id: string;
+        recordHash: string;
+    } | {
+        kind: "forced-reference";
+        reason: string;
+    };
+    case?: BaselineCase;
+    layout?: LayoutResult;
+    sha256: string;
+    capturedAt: string;
+    toolVersion: string;
+    file: string;
+}
 export interface BaselineResult {
+    case?: BaselineCase;
+    problems?: string[];
+    captured?: ArtifactProvenance;
+    approved?: ArtifactProvenance | {
+        legacy: true;
+        sha256: string;
+    };
     id: string;
     frame: string;
     frameId?: string;
@@ -30,6 +56,10 @@ export interface BaselineResult {
     imageHeight?: number;
 }
 export interface BaselinesReport {
+    coverage: BaselineCoverage;
+    complete: boolean;
+    fileId: string;
+    pageId: string;
     page: string;
     penpotFile: string;
     revn: number;
@@ -38,16 +68,14 @@ export interface BaselinesReport {
     wrote: string[];
 }
 export interface BaselinesOptions extends ExportOptions {
+    signal?: AbortSignal;
     /** Write images that are new. Without it nothing is written, whatever is found. */
     apply?: boolean;
     /** Also replace images whose design has changed. This is the act of approving the new design as the reference; it is the owner's call. */
     update?: boolean;
+    /** Explicit waiver for a changed baseline; retained as a forced reference, never an owner approval. */
+    forceReason?: string;
 }
-/** Pixel size from a PNG's header (the IHDR chunk), or nothing when the bytes are not a PNG. */
-export declare function pngSize(buffer: Buffer): {
-    width: number;
-    height: number;
-} | undefined;
 /**
  * Exports the configured frames of a page as images into the project's folder: the approved design that an implementation is
  * checked against. Looks first; writes only with `apply`, and replaces an image that differs only with `update`, so a change of
@@ -69,4 +97,5 @@ export declare function reflectionCases(config: BaselinesConfig, results: Baseli
         }[];
     }>;
     visualSmoke: Record<string, unknown>[];
+    pendingCases: Record<string, unknown>[];
 };