reflection-check 0.0.1

package/dist/contracts/visual/baseline-compare.js

@@ -0,0 +1,94 @@
+import { access, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createBaselineStore, createMissingBaselineCheck } from '../../core/baseline-store.js';
+import { comparePngImages } from './image-diff.js';
+export async function compareRouteVisualBaseline(input) {
+    const actualArtifact = input.routeCheck.artifacts.find((artifact) => artifact.role === 'actual' && artifact.path.endsWith('.png'));
+    const target = `${String(input.routeCheck.metadata.route ?? input.visualCase.route)} ${input.visualCase.viewport}`;
+    const baselinePath = resolveCaseBaselinePath(input.visualCase);
+    const blocking = input.visualCase.blocking === true || input.visualCase.strict === true;
+    const strict = input.visualCase.strict === true || input.visualCase.blocking === true;
+    if (!actualArtifact) {
+        return {
+            id: `visual.${input.visualCase.id}`,
+            suite: 'visual',
+            target,
+            status: blocking ? 'fail' : 'warn',
+            severity: blocking ? 'blocking' : 'review',
+            summary: `Missing actual screenshot for visual baseline case ${input.visualCase.id}.`,
+            artifacts: [],
+            metadata: {
+                classification: 'missing-actual-screenshot',
+                routeId: input.visualCase.route,
+                viewport: input.visualCase.viewport,
+                baselinePath: input.visualCase.baseline
+            },
+            suggestedNextStep: 'Add a screenshot expectation to the matching browser route before enabling this visual case.'
+        };
+    }
+    if (!(await pathExists(baselinePath))) {
+        return createMissingBaselineCheck({
+            id: `visual.${input.visualCase.id}`,
+            target,
+            baselinePath: input.visualCase.baseline,
+            blocking
+        });
+    }
+    const artifactBase = `visual/${input.visualCase.id}`;
+    const expectedArtifact = await input.store.writeBuffer(`${artifactBase}/expected.png`, await readFile(baselinePath));
+    const actualRunPath = input.store.resolveRunPath(actualArtifact.path);
+    const actualVisualArtifact = await input.store.writeBuffer(`${artifactBase}/actual.png`, await readFile(actualRunPath));
+    const diffRelativePath = `${artifactBase}/diff.png`;
+    const diffPath = input.store.resolveRunPath(diffRelativePath);
+    await mkdir(dirname(diffPath), { recursive: true });
+    const result = await comparePngImages({
+        expectedPath: baselinePath,
+        actualPath: input.store.resolveRunPath(actualVisualArtifact.path),
+        diffPath,
+        ...(input.visualCase.threshold ? { threshold: input.visualCase.threshold } : {}),
+        strict
+    });
+    const diffArtifact = result.diffPath ? await input.store.describeArtifact(diffRelativePath, 'visual-diff', 'diff') : undefined;
+    const severity = result.status === 'fail' && blocking ? 'blocking' : 'review';
+    return {
+        id: `visual.${input.visualCase.id}`,
+        suite: 'visual',
+        target,
+        status: result.status,
+        severity,
+        summary: createVisualSummary(input.visualCase.id, result),
+        artifacts: [expectedArtifact, actualVisualArtifact, ...(diffArtifact ? [diffArtifact] : [])],
+        metadata: {
+            ...result,
+            routeId: input.visualCase.route,
+            viewport: input.visualCase.viewport,
+            baselinePath: input.visualCase.baseline
+        },
+        ...(result.status === 'pass'
+            ? {}
+            : { suggestedNextStep: 'Inspect expected, actual, and diff artifacts. If intentional, update only this visual baseline.' })
+    };
+}
+function resolveCaseBaselinePath(visualCase) {
+    const store = createBaselineStore(visualCase.baselineRoot ? { rootDir: visualCase.baselineRoot } : {});
+    return store.resolveBaselinePath(visualCase.baseline);
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function createVisualSummary(id, result) {
+    if (result.classification === 'visual-match') {
+        return `${id} matches approved visual baseline.`;
+    }
+    if (result.classification === 'visual-dimension-mismatch') {
+        return `${id} screenshot dimensions differ from approved baseline.`;
+    }
+    return `${id} differs from approved visual baseline by ${(result.diffRatio * 100).toFixed(2)}% (${result.diffPixels} pixels)${result.thresholdReason ? `, exceeding ${result.thresholdReason}` : ''}.`;
+}
+//# sourceMappingURL=baseline-compare.js.map

package/dist/contracts/visual/baseline-compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-compare.js","sourceRoot":"","sources":["../../../src/contracts/visual/baseline-compare.ts"],"names":[],"mappings":"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"}

package/dist/contracts/visual/image-diff.d.ts

@@ -0,0 +1,27 @@
+import { type VisualThreshold } from './thresholds.js';
+export type ComparePngImagesInput = {
+    expectedPath: string;
+    actualPath: string;
+    diffPath?: string;
+    threshold?: VisualThreshold;
+    strict?: boolean;
+};
+export type ImageDimensions = {
+    width: number;
+    height: number;
+};
+export type ImageDiffResult = {
+    status: 'pass' | 'warn' | 'fail';
+    classification: 'visual-match' | 'visual-diff' | 'visual-dimension-mismatch';
+    width?: number;
+    height?: number;
+    expected: ImageDimensions;
+    actual: ImageDimensions;
+    diffPixels: number;
+    diffRatio: number;
+    dimensionMismatch: boolean;
+    threshold?: VisualThreshold;
+    thresholdReason?: 'maxDiffPixels' | 'maxDiffPixelRatio';
+    diffPath?: string;
+};
+export declare function comparePngImages(input: ComparePngImagesInput): Promise<ImageDiffResult>;

package/dist/contracts/visual/image-diff.js

@@ -0,0 +1,58 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+import { evaluateVisualThreshold } from './thresholds.js';
+export async function comparePngImages(input) {
+    const [expected, actual] = await Promise.all([readPng(input.expectedPath), readPng(input.actualPath)]);
+    const expectedDimensions = { width: expected.width, height: expected.height };
+    const actualDimensions = { width: actual.width, height: actual.height };
+    if (expected.width !== actual.width || expected.height !== actual.height) {
+        return {
+            status: 'fail',
+            classification: 'visual-dimension-mismatch',
+            expected: expectedDimensions,
+            actual: actualDimensions,
+            diffPixels: 0,
+            diffRatio: 1,
+            dimensionMismatch: true,
+            ...(input.threshold ? { threshold: input.threshold } : {})
+        };
+    }
+    const diff = new PNG({ width: expected.width, height: expected.height });
+    const diffPixels = pixelmatch(expected.data, actual.data, diff.data, expected.width, expected.height, { threshold: 0.1 });
+    const thresholdInput = input.threshold
+        ? {
+            diffPixels,
+            totalPixels: expected.width * expected.height,
+            threshold: input.threshold
+        }
+        : {
+            diffPixels,
+            totalPixels: expected.width * expected.height
+        };
+    const evaluation = evaluateVisualThreshold(thresholdInput);
+    if (input.diffPath) {
+        await writeFile(input.diffPath, PNG.sync.write(diff));
+    }
+    const classification = diffPixels === 0 ? 'visual-match' : 'visual-diff';
+    const status = evaluation.passed ? 'pass' : input.strict === true ? 'fail' : 'warn';
+    return {
+        status,
+        classification,
+        width: expected.width,
+        height: expected.height,
+        expected: expectedDimensions,
+        actual: actualDimensions,
+        diffPixels,
+        diffRatio: evaluation.diffRatio,
+        dimensionMismatch: false,
+        ...(input.threshold ? { threshold: input.threshold } : {}),
+        ...(evaluation.reason ? { thresholdReason: evaluation.reason } : {}),
+        ...(input.diffPath ? { diffPath: input.diffPath } : {})
+    };
+}
+async function readPng(path) {
+    const content = await readFile(path);
+    return PNG.sync.read(content);
+}
+//# sourceMappingURL=image-diff.js.map

package/dist/contracts/visual/image-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-diff.js","sourceRoot":"","sources":["../../../src/contracts/visual/image-diff.ts"],"names":[],"mappings":"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"}

package/dist/contracts/visual/thresholds.d.ts

@@ -0,0 +1,15 @@
+export type VisualThreshold = {
+    maxDiffPixels?: number | undefined;
+    maxDiffPixelRatio?: number | undefined;
+};
+export type ThresholdEvaluationInput = {
+    diffPixels: number;
+    totalPixels: number;
+    threshold?: VisualThreshold;
+};
+export type ThresholdEvaluation = {
+    passed: boolean;
+    diffRatio: number;
+    reason?: 'maxDiffPixels' | 'maxDiffPixelRatio';
+};
+export declare function evaluateVisualThreshold(input: ThresholdEvaluationInput): ThresholdEvaluation;

package/dist/contracts/visual/thresholds.js

@@ -0,0 +1,11 @@
+export function evaluateVisualThreshold(input) {
+    const diffRatio = input.totalPixels === 0 ? 0 : input.diffPixels / input.totalPixels;
+    if (input.threshold?.maxDiffPixels !== undefined && input.diffPixels > input.threshold.maxDiffPixels) {
+        return { passed: false, diffRatio, reason: 'maxDiffPixels' };
+    }
+    if (input.threshold?.maxDiffPixelRatio !== undefined && diffRatio > input.threshold.maxDiffPixelRatio) {
+        return { passed: false, diffRatio, reason: 'maxDiffPixelRatio' };
+    }
+    return { passed: true, diffRatio };
+}
+//# sourceMappingURL=thresholds.js.map

package/dist/contracts/visual/thresholds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thresholds.js","sourceRoot":"","sources":["../../../src/contracts/visual/thresholds.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,uBAAuB,CAAC,KAA+B;IACrE,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,WAAW,CAAC;IAErF,IAAI,KAAK,CAAC,SAAS,EAAE,aAAa,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,aAAa,EAAE,CAAC;QACrG,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC/D,CAAC;IAED,IAAI,KAAK,CAAC,SAAS,EAAE,iBAAiB,KAAK,SAAS,IAAI,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,iBAAiB,EAAE,CAAC;QACtG,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACnE,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AACrC,CAAC"}

package/dist/contracts/visual/visual-contract.d.ts

@@ -0,0 +1,11 @@
+import type { ArtifactStore } from '../../core/artifact-store.js';
+import type { CheckResult } from '../../core/report-schema.js';
+import { type RouteVisualBaselineCase } from './baseline-compare.js';
+export type VisualContractConfig = {
+    smoke?: RouteVisualBaselineCase[];
+};
+export declare function runRouteVisualSmoke(input: {
+    visualSmoke?: RouteVisualBaselineCase[] | undefined;
+    browserChecks: CheckResult[];
+    store: ArtifactStore;
+}): Promise<CheckResult[]>;

package/dist/contracts/visual/visual-contract.js

@@ -0,0 +1,32 @@
+import { compareRouteVisualBaseline } from './baseline-compare.js';
+export async function runRouteVisualSmoke(input) {
+    if (!input.visualSmoke || input.visualSmoke.length === 0) {
+        return [];
+    }
+    const checks = [];
+    for (const visualCase of input.visualSmoke) {
+        const routeCheck = input.browserChecks.find((check) => check.metadata.routeId === visualCase.route && check.metadata.viewport === visualCase.viewport);
+        if (!routeCheck) {
+            checks.push({
+                id: `visual.${visualCase.id}`,
+                suite: 'visual',
+                target: `${visualCase.route} ${visualCase.viewport}`,
+                status: visualCase.blocking === true || visualCase.strict === true ? 'fail' : 'warn',
+                severity: visualCase.blocking === true || visualCase.strict === true ? 'blocking' : 'review',
+                summary: `Missing browser route result for visual case ${visualCase.id}.`,
+                artifacts: [],
+                metadata: {
+                    classification: 'missing-browser-route-result',
+                    routeId: visualCase.route,
+                    viewport: visualCase.viewport,
+                    baselinePath: visualCase.baseline
+                },
+                suggestedNextStep: 'Add a matching browser route and viewport before enabling this visual case.'
+            });
+            continue;
+        }
+        checks.push(await compareRouteVisualBaseline({ visualCase, routeCheck, store: input.store }));
+    }
+    return checks;
+}
+//# sourceMappingURL=visual-contract.js.map

package/dist/contracts/visual/visual-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-contract.js","sourceRoot":"","sources":["../../../src/contracts/visual/visual-contract.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,0BAA0B,EAAgC,MAAM,uBAAuB,CAAC;AAMjG,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,KAIzC;IACC,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,UAAU,GAAG,KAAK,CAAC,aAAa,CAAC,IAAI,CACzC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,KAAK,UAAU,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,KAAK,UAAU,CAAC,QAAQ,CAC1G,CAAC;QAEF,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,CAAC,IAAI,CAAC;gBACV,EAAE,EAAE,UAAU,UAAU,CAAC,EAAE,EAAE;gBAC7B,KAAK,EAAE,QAAQ;gBACf,MAAM,EAAE,GAAG,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,QAAQ,EAAE;gBACpD,MAAM,EAAE,UAAU,CAAC,QAAQ,KAAK,IAAI,IAAI,UAAU,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;gBACpF,QAAQ,EAAE,UAAU,CAAC,QAAQ,KAAK,IAAI,IAAI,UAAU,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ;gBAC5F,OAAO,EAAE,gDAAgD,UAAU,CAAC,EAAE,GAAG;gBACzE,SAAS,EAAE,EAAE;gBACb,QAAQ,EAAE;oBACR,cAAc,EAAE,8BAA8B;oBAC9C,OAAO,EAAE,UAAU,CAAC,KAAK;oBACzB,QAAQ,EAAE,UAAU,CAAC,QAAQ;oBAC7B,YAAY,EAAE,UAAU,CAAC,QAAQ;iBAClC;gBACD,iBAAiB,EAAE,6EAA6E;aACjG,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,MAAM,0BAA0B,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAChG,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/artifact-store.d.ts

@@ -0,0 +1,18 @@
+import type { ArtifactRef } from './report-schema.js';
+export type ArtifactStore = {
+    rootDir: string;
+    runId: string;
+    runDir: string;
+    ensureRunDir(): Promise<void>;
+    resolveRunPath(relativePath: string): string;
+    writeText(relativePath: string, content: string): Promise<ArtifactRef>;
+    writeBuffer(relativePath: string, content: Buffer): Promise<ArtifactRef>;
+    writeJson(relativePath: string, value: unknown): Promise<ArtifactRef>;
+    describeArtifact(relativePath: string, type: ArtifactRef['type'], role?: ArtifactRef['role']): Promise<ArtifactRef>;
+    updateLatestPointer(): Promise<void>;
+};
+export type CreateArtifactStoreOptions = {
+    rootDir?: string;
+    runId: string;
+};
+export declare function createArtifactStore(options: CreateArtifactStoreOptions): Promise<ArtifactStore>;

package/dist/core/artifact-store.js

@@ -0,0 +1,105 @@
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+function assertSafeRelativePath(relativePath) {
+    if (relativePath.length === 0 || isAbsolute(relativePath) || relativePath.split(/[\\/]/).includes('..')) {
+        throw new Error(`Refusing to write artifact outside run directory: ${relativePath}`);
+    }
+}
+function ensureInside(parent, child) {
+    const relation = relative(parent, child);
+    if (relation.startsWith('..') || isAbsolute(relation)) {
+        throw new Error(`Refusing to write artifact outside run directory: ${child}`);
+    }
+}
+export async function createArtifactStore(options) {
+    const rootDir = resolve(options.rootDir ?? '.reflection');
+    const runDir = resolve(rootDir, 'runs', options.runId);
+    ensureInside(resolve(rootDir, 'runs'), runDir);
+    const resolveRunPath = (relativePath) => {
+        assertSafeRelativePath(relativePath);
+        const resolved = resolve(runDir, relativePath);
+        ensureInside(runDir, resolved);
+        return resolved;
+    };
+    const describeArtifact = async (relativePath, type, role) => {
+        const path = resolveRunPath(relativePath);
+        const [stats, bytes] = await Promise.all([stat(path), readFile(path)]);
+        return {
+            type,
+            ...(role ? { role } : {}),
+            path: relativePath,
+            bytes: stats.size,
+            sha256: createHash('sha256').update(bytes).digest('hex')
+        };
+    };
+    const writeText = async (relativePath, content) => {
+        const path = resolveRunPath(relativePath);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content, 'utf8');
+        return describeArtifact(relativePath, inferArtifactType(relativePath), inferArtifactRole(relativePath));
+    };
+    const writeBuffer = async (relativePath, content) => {
+        const path = resolveRunPath(relativePath);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content);
+        return describeArtifact(relativePath, inferArtifactType(relativePath), inferArtifactRole(relativePath));
+    };
+    return {
+        rootDir,
+        runId: options.runId,
+        runDir,
+        async ensureRunDir() {
+            await mkdir(runDir, { recursive: true });
+        },
+        resolveRunPath,
+        writeText,
+        writeBuffer,
+        async writeJson(relativePath, value) {
+            return writeText(relativePath, `${JSON.stringify(value, null, 2)}\n`);
+        },
+        describeArtifact,
+        async updateLatestPointer() {
+            const runsDir = resolve(rootDir, 'runs');
+            await mkdir(runsDir, { recursive: true });
+            await writeFile(join(runsDir, 'latest'), `${options.runId}\n`, 'utf8');
+        }
+    };
+}
+function inferArtifactType(relativePath) {
+    if (relativePath.endsWith('.json')) {
+        return 'metadata';
+    }
+    if (relativePath.endsWith('.md') || relativePath.endsWith('.html')) {
+        return 'report';
+    }
+    if (relativePath.endsWith('.log')) {
+        return 'log';
+    }
+    if (relativePath.endsWith('/diff.png')) {
+        return 'visual-diff';
+    }
+    if (relativePath.endsWith('.png')) {
+        return relativePath.startsWith('visual/') ? 'image' : 'screenshot';
+    }
+    return 'metadata';
+}
+function inferArtifactRole(relativePath) {
+    if (relativePath.startsWith('report.')) {
+        return 'evidence';
+    }
+    if (relativePath.endsWith('.log')) {
+        return 'debug';
+    }
+    if (relativePath.endsWith('/expected.png')) {
+        return 'expected';
+    }
+    if (relativePath.endsWith('/actual.png')) {
+        return 'actual';
+    }
+    if (relativePath.endsWith('/diff.png')) {
+        return 'diff';
+    }
+    return undefined;
+}
+//# sourceMappingURL=artifact-store.js.map

package/dist/core/artifact-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-store.js","sourceRoot":"","sources":["../../src/core/artifact-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBzE,SAAS,sBAAsB,CAAC,YAAoB;IAClD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,YAAY,CAAC,IAAI,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxG,MAAM,IAAI,KAAK,CAAC,qDAAqD,YAAY,EAAE,CAAC,CAAC;IACvF,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,KAAa;IACjD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACzC,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,qDAAqD,KAAK,EAAE,CAAC,CAAC;IAChF,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAmC;IAC3E,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,aAAa,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACvD,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;IAE/C,MAAM,cAAc,GAAG,CAAC,YAAoB,EAAU,EAAE;QACtD,sBAAsB,CAAC,YAAY,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC/C,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC/B,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;IAEF,MAAM,gBAAgB,GAAG,KAAK,EAC5B,YAAoB,EACpB,IAAyB,EACzB,IAA0B,EACJ,EAAE;QACxB,MAAM,IAAI,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;QAC1C,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvE,OAAO;YACL,IAAI;YACJ,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzB,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,KAAK,CAAC,IAAI;YACjB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SACzD,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,KAAK,EAAE,YAAoB,EAAE,OAAe,EAAwB,EAAE;QACtF,MAAM,IAAI,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;QAC1C,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,MAAM,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACvC,OAAO,gBAAgB,CAAC,YAAY,EAAE,iBAAiB,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC;IAC1G,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,KAAK,EAAE,YAAoB,EAAE,OAAe,EAAwB,EAAE;QACxF,MAAM,IAAI,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;QAC1C,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,MAAM,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC/B,OAAO,gBAAgB,CAAC,YAAY,EAAE,iBAAiB,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC;IAC1G,CAAC,CAAC;IAEF,OAAO;QACL,OAAO;QACP,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM;QACN,KAAK,CAAC,YAAY;YAChB,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,cAAc;QACd,SAAS;QACT,WAAW;QACX,KAAK,CAAC,SAAS,CAAC,YAAoB,EAAE,KAAc;YAClD,OAAO,SAAS,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACxE,CAAC;QACD,gBAAgB;QAChB,KAAK,CAAC,mBAAmB;YACvB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACzC,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1C,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,MAAM,CAAC,CAAC;QACzE,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,YAAoB;IAC7C,IAAI,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,IAAI,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACnE,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACvC,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,IAAI,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,OAAO,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC;IACrE,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,iBAAiB,CAAC,YAAoB;IAC7C,IAAI,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACvC,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,IAAI,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,YAAY,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAC3C,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,IAAI,YAAY,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QACzC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACvC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/core/baseline-store.d.ts

@@ -0,0 +1,18 @@
+import type { CheckResult } from './report-schema.js';
+export type BaselineStore = {
+    rootDir: string;
+    resolveBaselinePath(relativePath: string): string;
+};
+export type CreateBaselineStoreOptions = {
+    rootDir?: string;
+};
+export type MissingBaselineCheckOptions = {
+    id: string;
+    target: string;
+    baselinePath: string;
+    blocking: boolean;
+    metadata?: Record<string, unknown> | undefined;
+};
+export declare function createBaselineStore(options?: CreateBaselineStoreOptions): BaselineStore;
+export declare function readBaselineMetadata(store: BaselineStore, relativePath: string): Promise<Record<string, unknown>>;
+export declare function createMissingBaselineCheck(options: MissingBaselineCheckOptions): CheckResult;

package/dist/core/baseline-store.js

@@ -0,0 +1,56 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+function assertSafeRelativePath(relativePath) {
+    if (relativePath.length === 0 || isAbsolute(relativePath) || relativePath.split(/[\\/]/).includes('..')) {
+        throw new Error(`Refusing to resolve baseline outside baseline directory: ${relativePath}`);
+    }
+}
+function ensureInside(parent, child) {
+    const relation = relative(parent, child);
+    if (relation.startsWith('..') || isAbsolute(relation)) {
+        throw new Error(`Refusing to resolve baseline outside baseline directory: ${child}`);
+    }
+}
+export function createBaselineStore(options = {}) {
+    const rootDir = resolve(options.rootDir ?? '.reflection/baselines');
+    return {
+        rootDir,
+        resolveBaselinePath(relativePath) {
+            assertSafeRelativePath(relativePath);
+            const resolved = resolve(rootDir, relativePath);
+            ensureInside(rootDir, resolved);
+            return resolved;
+        }
+    };
+}
+export async function readBaselineMetadata(store, relativePath) {
+    const path = store.resolveBaselinePath(relativePath);
+    const raw = await readFile(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Invalid baseline metadata: ${relativePath}`);
+    }
+    return parsed;
+}
+export function createMissingBaselineCheck(options) {
+    const status = options.blocking ? 'fail' : 'warn';
+    const severity = options.blocking ? 'blocking' : 'review';
+    return {
+        id: options.id,
+        suite: 'visual',
+        target: options.target,
+        status,
+        severity,
+        summary: `Missing approved visual baseline: ${options.baselinePath}.`,
+        artifacts: [],
+        metadata: {
+            ...(options.metadata ?? {}),
+            classification: 'missing-baseline',
+            baselinePath: options.baselinePath
+        },
+        suggestedNextStep: options.blocking
+            ? 'Add an approved baseline or mark this visual case as review-only until stable.'
+            : 'Review the current screenshot and run reflection update for this specific case if the change is intentional.'
+    };
+}
+//# sourceMappingURL=baseline-store.js.map

package/dist/core/baseline-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-store.js","sourceRoot":"","sources":["../../src/core/baseline-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoB1D,SAAS,sBAAsB,CAAC,YAAoB;IAClD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,YAAY,CAAC,IAAI,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxG,MAAM,IAAI,KAAK,CAAC,4DAA4D,YAAY,EAAE,CAAC,CAAC;IAC9F,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,KAAa;IACjD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACzC,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,4DAA4D,KAAK,EAAE,CAAC,CAAC;IACvF,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAAsC,EAAE;IAC1E,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,uBAAuB,CAAC,CAAC;IAEpE,OAAO;QACL,OAAO;QACP,mBAAmB,CAAC,YAAoB;YACtC,sBAAsB,CAAC,YAAY,CAAC,CAAC;YACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;YAChD,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAChC,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,KAAoB,EAAE,YAAoB;IACnF,MAAM,IAAI,GAAG,KAAK,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;IAE1C,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,8BAA8B,YAAY,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,MAAiC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,OAAoC;IAC7E,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAClD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;IAE1D,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,KAAK,EAAE,QAAQ;QACf,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM;QACN,QAAQ;QACR,OAAO,EAAE,qCAAqC,OAAO,CAAC,YAAY,GAAG;QACrE,SAAS,EAAE,EAAE;QACb,QAAQ,EAAE;YACR,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;YAC3B,cAAc,EAAE,kBAAkB;YAClC,YAAY,EAAE,OAAO,CAAC,YAAY;SACnC;QACD,iBAAiB,EAAE,OAAO,CAAC,QAAQ;YACjC,CAAC,CAAC,gFAAgF;YAClF,CAAC,CAAC,8GAA8G;KACnH,CAAC;AACJ,CAAC"}

package/dist/core/config.d.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+export declare const runModes: readonly ["smoke", "design", "visual", "full"];
+export type RunMode = (typeof runModes)[number];
+declare const ReflectionConfigSchema: z.ZodObject<{
+    project: z.ZodString;
+    run: z.ZodDefault<z.ZodObject<{
+        defaultMode: z.ZodDefault<z.ZodEnum<{
+            smoke: "smoke";
+            design: "design";
+            visual: "visual";
+            full: "full";
+        }>>;
+        ciMode: z.ZodDefault<z.ZodEnum<{
+            smoke: "smoke";
+            design: "design";
+            visual: "visual";
+            full: "full";
+        }>>;
+    }, z.core.$strip>>;
+    contracts: z.ZodObject<{
+        browser: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            blocking: z.ZodDefault<z.ZodBoolean>;
+            baseUrl: z.ZodString;
+            server: z.ZodOptional<z.ZodObject<{
+                command: z.ZodString;
+                readyUrl: z.ZodString;
+                reuseExisting: z.ZodDefault<z.ZodBoolean>;
+                timeoutMs: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+            routes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                viewports: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                expects: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                    urlIncludes: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    urlEquals: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    role: z.ZodString;
+                    name: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>, z.ZodObject<{
+                    label: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    text: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    noText: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    selector: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    elementVisible: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    elementNotVisible: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    noHorizontalOverflow: z.ZodLiteral<true>;
+                }, z.core.$strip>, z.ZodObject<{
+                    noConsoleErrors: z.ZodLiteral<true>;
+                }, z.core.$strip>, z.ZodObject<{
+                    screenshot: z.ZodString;
+                }, z.core.$strip>]>>>;
+            }, z.core.$strip>>>;
+            maskSelectors: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            visualSmoke: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                route: z.ZodString;
+                viewport: z.ZodString;
+                baseline: z.ZodString;
+                baselineRoot: z.ZodOptional<z.ZodString>;
+                threshold: z.ZodOptional<z.ZodObject<{
+                    maxDiffPixels: z.ZodOptional<z.ZodNumber>;
+                    maxDiffPixelRatio: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
+                blocking: z.ZodOptional<z.ZodBoolean>;
+                strict: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        design: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            commands: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                command: z.ZodString;
+                cwd: z.ZodOptional<z.ZodString>;
+                blocking: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        component: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            storybook: z.ZodObject<{
+                command: z.ZodString;
+                readyUrl: z.ZodString;
+                reuseExisting: z.ZodDefault<z.ZodBoolean>;
+                timeoutMs: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>;
+            cases: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                storyId: z.ZodString;
+                viewport: z.ZodDefault<z.ZodString>;
+                baseline: z.ZodString;
+                baselineRoot: z.ZodOptional<z.ZodString>;
+                threshold: z.ZodOptional<z.ZodObject<{
+                    maxDiffPixels: z.ZodOptional<z.ZodNumber>;
+                    maxDiffPixelRatio: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
+                blocking: z.ZodOptional<z.ZodBoolean>;
+                strict: z.ZodOptional<z.ZodBoolean>;
+                stateNote: z.ZodOptional<z.ZodString>;
+                browserState: z.ZodOptional<z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        hover: "hover";
+                        focus: "focus";
+                    }>;
+                    selector: z.ZodString;
+                    animationStabilization: z.ZodObject<{
+                        disableAnimations: z.ZodOptional<z.ZodBoolean>;
+                        waitMs: z.ZodOptional<z.ZodNumber>;
+                    }, z.core.$strip>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        visual: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ReflectionConfigInput = z.input<typeof ReflectionConfigSchema>;
+export type ReflectionConfig = z.output<typeof ReflectionConfigSchema>;
+export declare function isRunMode(value: string): value is RunMode;
+export declare function validateReflectionConfig(input: unknown): ReflectionConfig;
+export declare function loadReflectionConfig(configPath: string): Promise<ReflectionConfig>;
+export {};