@penpair/reflection-check 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niklas Westman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @penpair/reflection-check
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An optional adapter for explicit implementation-case evidence against approved penpair baselines. Add it to `adapters` and install it alongside one command package at the same reviewed version. It depends on the neutral core; the core does not load or depend on this adapter.
+
+The existing generated Reflection `visualSmoke` configuration remains the simple route for legacy cases. This adapter addresses the missing setup hook for rich theme/state/fixture/font cases. It does not bundle a browser or assume a version-specific Reflection API. A trusted project provider owns actual application activation, capture and comparison using the project's pinned browser/checker stack.
+
+```sh
+penpair reflection plan --map design/implementation-cases.json
+penpair reflection check --map design/implementation-cases.json --provider design/reflection-provider.mjs
+```
+
+Mapping: `{"schemaVersion":1,"cases":[{"id":"dashboard-empty-dark","setup":"dark-empty"}]}`. A case must have current exact approved provenance, matching file pin and an explicit setup name. Missing mappings, legacy approvals and changed case metadata remain pending. No setup is silently replaced by the default route state. Baselines remain owned by the core; this adapter neither captures nor approves design references.
+
+The provider module exports `async runCase(test)` and receives the immutable case ID, route, setup key, declared intent, baseline relative path/hash/scale and threshold. It must activate the route/theme/state/data fixture, verify actual browser state and fonts independently, capture a new PNG at the requested scale, and use the installed checker to compare it with the approved image. It returns:
+
+```json
+{
+  "schemaVersion":1,"id":"dashboard-empty-dark","route":"/dashboard","setup":"dark-empty",
+  "observed":{"viewport":{"width":1280,"height":900},"theme":"dark","state":"empty","fixture":"no-items"},
+  "fonts":["Expected Font"],"fontsReady":true,"baselineHash":"EXACT_SHA256",
+  "screenshot":".penpair/comparison/dashboard.png","diffPixelRatio":0.01,
+  "provider":{"name":"PROJECT_PINNED_CHECKER","version":"ACTUAL_VERSION"}
+}
+```
+
+Observed context must come from browser readback, not copied test inputs. The adapter checks context/font evidence, independent screenshot path, PNG dimensions, byte hashes and unchanged baseline bytes. A trusted provider can lie: this interface is an evidence contract, not a sandbox or cryptographic attestation of browser work. Modules and transitive imports execute project code. Pixel ratios are checker evidence, never a visual verdict, accessibility assessment or owner approval. Exit 0 means complete evidence within thresholds; 2 means measured drift; 3 means missing/incomplete evidence. Every result still says `owner-review-required`.
+
+No real consumer was modified and no live implementation route was run here. The offline integration test uses a named stub; replace it with a real provider and record the I12 human trial before claiming adoption. Release/publishing is the owner's act and all six packages remain in lockstep.

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+import { type AdapterContext, type BaselineCase, type BaselineResult, type BaselinesConfig } from "@penpair/core";
+export interface ImplementationMapping {
+    schemaVersion: 1;
+    cases: Array<{
+        id: string;
+        setup: string;
+    }>;
+}
+export interface ImplementationCase {
+    id: string;
+    route: string;
+    intent: BaselineCase;
+    setup: string;
+    baseline: {
+        path: string;
+        sha256: string;
+        scale: number;
+    };
+    threshold: number;
+}
+export interface CasePlan {
+    schemaVersion: 1;
+    kind: "implementation-case-plan";
+    cases: ImplementationCase[];
+    pending: Array<{
+        id: string;
+        reason: string;
+    }>;
+    complete: boolean;
+    visualApproval: false;
+}
+export interface ProviderEvidence {
+    schemaVersion: 1;
+    id: string;
+    route: string;
+    setup: string;
+    observed: Pick<BaselineCase, "viewport" | "theme" | "state" | "fixture">;
+    fonts: string[];
+    fontsReady: boolean;
+    baselineHash: string;
+    screenshot: string;
+    diffPixelRatio: number;
+    provider: {
+        name: string;
+        version: string;
+    };
+}
+export interface ImplementationProvider {
+    runCase(test: ImplementationCase): Promise<ProviderEvidence>;
+}
+export declare function planImplementationCases(config: BaselinesConfig, results: BaselineResult[], mapping: ImplementationMapping): CasePlan;
+export declare function runImplementationCases(root: string, plan: CasePlan, provider: ImplementationProvider): Promise<{
+    schemaVersion: number;
+    kind: string;
+    complete: boolean;
+    cases: {
+        id: string;
+        complete: boolean;
+        withinThreshold?: boolean;
+        evidence?: ProviderEvidence;
+        screenshotHash?: string;
+        reason?: string;
+    }[];
+    pending: {
+        id: string;
+        reason: string;
+    }[];
+    visualApproval: boolean;
+    verdict: string;
+    accessibility: string;
+}>;
+declare function command(context: AdapterContext, args: string[]): Promise<number>;
+declare const _default: {
+    name: string;
+    commands: {
+        name: string;
+        summary: string;
+        usage: string[];
+        run: typeof command;
+    }[];
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { createJiti } from "jiti";
+import { defineAdapter, observationHash, parseCommandArgs, readDesignJson, resolveProjectInput, validateBaselineCase } from "@penpair/core";
+const sha = (b) => createHash("sha256").update(b).digest("hex");
+export function planImplementationCases(config, results, mapping) {
+    if (!mapping || mapping.schemaVersion !== 1 || !Array.isArray(mapping.cases) || mapping.cases.length > 1000)
+        throw new Error("Unsupported implementation mapping");
+    const names = new Set();
+    for (const entry of mapping.cases)
+        if (!entry || typeof entry.id !== "string" || !entry.id || names.has(entry.id) || typeof entry.setup !== "string" || !/^[a-zA-Z][\w.-]{0,100}$/.test(entry.setup))
+            throw new Error("Duplicate/invalid explicit setup mapping");
+        else
+            names.add(entry.id);
+    const cases = [], pending = [];
+    for (const wanted of config.frames) {
+        if (!wanted.route)
+            continue;
+        const result = results.find(r => r.id === wanted.id), setup = mapping.cases.find(c => c.id === wanted.id)?.setup;
+        const approved = result?.approved && !("legacy" in result.approved) ? result.approved : undefined;
+        if (approved?.approval?.kind === "forced-reference" || !wanted.case || !result || !approved?.case || !setup || !["same", "new", "changed"].includes(result.status) || !result.captured || approved.sha256 !== result.captured.sha256 || observationHash(approved.case) !== observationHash(wanted.case) || approved.frameId !== result.frameId || approved.fileId !== result.captured.fileId || approved.pageId !== result.captured.pageId || approved.revision !== result.captured.revision || approved.file !== result.file) {
+            pending.push({ id: wanted.id, reason: "Requires current exact approved case provenance and an explicit implementation setup; legacy cases keep the existing generated Reflection path" });
+            continue;
+        }
+        validateBaselineCase(wanted.case, message => { throw new Error(message); });
+        cases.push({ id: wanted.id, route: wanted.route, intent: structuredClone(wanted.case), setup, baseline: { path: path.join(config.root, result.file), sha256: approved.sha256, scale: approved.scale }, threshold: config.threshold ?? 0.05 });
+    }
+    for (const entry of mapping.cases)
+        if (!config.frames.some(f => f.id === entry.id))
+            pending.push({ id: entry.id, reason: "Mapping refers to no configured baseline" });
+    return { schemaVersion: 1, kind: "implementation-case-plan", cases, pending, complete: pending.length === 0 && cases.length > 0, visualApproval: false };
+}
+async function png(root, file) {
+    const input = await resolveProjectInput(root, file);
+    if ((await stat(input)).size > 64 * 1024 * 1024)
+        throw new Error("Image exceeds 64 MiB");
+    const bytes = await readFile(input);
+    if (bytes.length < 24 || bytes.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a" || bytes.subarray(12, 16).toString() !== "IHDR")
+        throw new Error("Provider evidence must reference PNG bytes");
+    return { bytes, width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+export async function runImplementationCases(root, plan, provider) {
+    const reports = [];
+    for (const c of plan.cases) {
+        try {
+            if (!(Number.isFinite(c.baseline.scale) && c.baseline.scale > 0))
+                throw new Error("Missing capture scale");
+            const before = await png(root, c.baseline.path);
+            if (sha(before.bytes) !== c.baseline.sha256)
+                throw new Error("Approved baseline bytes changed");
+            const evidence = await provider.runCase(structuredClone(c));
+            const desired = { viewport: c.intent.viewport, theme: c.intent.theme, state: c.intent.state, fixture: c.intent.fixture };
+            if (!evidence || evidence.schemaVersion !== 1 || evidence.id !== c.id || evidence.route !== c.route || evidence.setup !== c.setup || observationHash(evidence.observed) !== observationHash(desired) || evidence.baselineHash !== c.baseline.sha256 || evidence.fontsReady !== true || !Array.isArray(evidence.fonts) || (c.intent.fonts ?? []).some(font => !evidence.fonts.includes(font)) || !evidence.provider?.name || !evidence.provider.version || !Number.isFinite(evidence.diffPixelRatio) || evidence.diffPixelRatio < 0 || evidence.diffPixelRatio > 1)
+                throw new Error("Provider did not independently observe the exact requested state, fixture, viewport, fonts and baseline");
+            const shot = await png(root, evidence.screenshot);
+            if (await resolveProjectInput(root, evidence.screenshot) === await resolveProjectInput(root, c.baseline.path))
+                throw new Error("Screenshot must be independently captured, not the baseline path");
+            if (shot.width !== Math.round(c.intent.viewport.width * c.baseline.scale) || shot.height !== Math.round(c.intent.viewport.height * c.baseline.scale) || before.width !== shot.width || before.height !== shot.height)
+                throw new Error("Provider PNG scale/viewport differs from the design case");
+            if (sha((await png(root, c.baseline.path)).bytes) !== c.baseline.sha256)
+                throw new Error("Baseline changed during provider execution");
+            reports.push({ id: c.id, complete: true, withinThreshold: evidence.diffPixelRatio <= c.threshold, evidence, screenshotHash: sha(shot.bytes) });
+        }
+        catch (error) {
+            reports.push({ id: c.id, complete: false, reason: String(error.message) });
+        }
+    }
+    return { schemaVersion: 1, kind: "implementation-case-evidence", complete: plan.complete && reports.length > 0 && reports.every(r => r.complete), cases: reports, pending: plan.pending, visualApproval: false, verdict: "owner-review-required", accessibility: "not-assessed" };
+}
+async function command(context, args) {
+    const [sub, ...rest] = args;
+    const { values, positionals } = parseCommandArgs({ args: rest, allowPositionals: true, options: { map: { type: "string" }, provider: { type: "string" }, json: { type: "boolean" } } });
+    if (!["plan", "check"].includes(sub ?? "") || positionals.length || !values.map || sub === "plan" && values.provider || sub === "check" && !values.provider)
+        throw new Error("Usage: reflection plan --map FILE | reflection check --map FILE --provider FILE");
+    const config = context.config.baselines;
+    if (!config)
+        throw new Error("Configure baselines first");
+    const manifest = await readDesignJson(context.root, path.join(config.root, "penpair-baselines.json"));
+    if (manifest.schemaVersion !== 2 || !Array.isArray(manifest.frames) || !context.config.file || manifest.fileId !== context.config.file.id)
+        throw new Error("A schema-2 baseline manifest matching the configured file pin is required");
+    const plan = planImplementationCases(config, manifest.frames, await readDesignJson(context.root, values.map, 1024 * 1024));
+    let report = plan, code = plan.complete ? 0 : 3;
+    if (sub === "check") {
+        const file = await resolveProjectInput(context.root, values.provider);
+        const provider = await createJiti(file, { moduleCache: false, tryNative: false }).evalModule(await readFile(file, "utf8"), { filename: file, async: true, forceTranspile: true });
+        if (typeof provider.runCase !== "function")
+            throw new Error("Trusted project provider must export async runCase(test)");
+        const result = await runImplementationCases(context.root, plan, provider);
+        report = result;
+        code = !result.complete ? 3 : result.cases.some(c => c.withinThreshold === false) ? 2 : 0;
+    }
+    context.output?.result(report);
+    (context.output?.log ?? console.log)(JSON.stringify(report, null, 2));
+    return code;
+}
+export default defineAdapter({ name: "@penpair/reflection-check", commands: [{ name: "reflection", summary: "Plan explicit implementation cases and collect provider evidence", usage: ["penpair reflection plan --map FILE", "penpair reflection check --map FILE --provider FILE"], run: command }] });

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@penpair/reflection-check",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Explicit design case planning and verified implementation evidence for penpair baselines.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/niklas-westman/penpair.git",
+    "directory": "packages/reflection-check"
+  },
+  "homepage": "https://github.com/niklas-westman/penpair#readme",
+  "bugs": {
+    "url": "https://github.com/niklas-westman/penpair/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "penpot",
+    "reflection",
+    "design-verification"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jiti": "^2.4.2",
+    "@penpair/core": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }