reflection-check 0.0.1

package/dist/contracts/browser/route-runner.d.ts

@@ -0,0 +1,21 @@
+import type { Browser } from 'playwright';
+import type { ArtifactStore } from '../../core/artifact-store.js';
+import type { CheckResult } from '../../core/report-schema.js';
+import { type BrowserExpectation } from './assertions.js';
+export type BrowserRoute = {
+    id: string;
+    name?: string | undefined;
+    path: string;
+    viewports: string[];
+    expects: BrowserExpectation[];
+};
+export type RouteRunInput = {
+    browser: Browser;
+    store: ArtifactStore;
+    baseUrl: string;
+    route: BrowserRoute;
+    viewport: string;
+    blocking: boolean;
+    maskSelectors?: string[];
+};
+export declare function runBrowserRoute(input: RouteRunInput): Promise<CheckResult>;

package/dist/contracts/browser/route-runner.js

@@ -0,0 +1,98 @@
+import { createBrowserContext } from '../../integrations/playwright/context-factory.js';
+import { evaluateExpectation, shouldCaptureScreenshot } from './assertions.js';
+import { observeConsoleErrors } from './console-observer.js';
+export async function runBrowserRoute(input) {
+    const context = await createBrowserContext(input.browser, input.viewport);
+    const page = await context.newPage();
+    const consoleObserver = observeConsoleErrors(page);
+    const failures = [];
+    const artifacts = [];
+    const maskSelectors = input.maskSelectors ?? [];
+    let maskedSelectors = [];
+    try {
+        await page.goto(new URL(input.route.path, input.baseUrl).toString(), { waitUntil: 'domcontentloaded' });
+        await page.waitForLoadState('networkidle', { timeout: 2_000 }).catch(() => undefined);
+        for (const expectation of input.route.expects) {
+            const failure = await evaluateExpectation(page, expectation, consoleObserver.errors);
+            if (failure) {
+                failures.push(failure);
+            }
+        }
+        if (shouldCaptureScreenshot(input.route.expects)) {
+            maskedSelectors = await applyMaskSelectors(page, maskSelectors);
+            const screenshotPath = `browser/${input.route.id}/${input.viewport}/actual.png`;
+            const screenshot = await page.screenshot({ fullPage: true });
+            artifacts.push(await input.store.writeBuffer(screenshotPath, screenshot));
+        }
+        const metadataPath = `browser/${input.route.id}/${input.viewport}/metadata.json`;
+        artifacts.push(await input.store.writeJson(metadataPath, {
+            route: input.route.path,
+            viewport: input.viewport,
+            url: page.url(),
+            consoleErrors: consoleObserver.errors,
+            failures,
+            privacyWarning: shouldCaptureScreenshot(input.route.expects) ? 'Screenshots may contain private UI data. Use maskSelectors for sensitive regions.' : undefined,
+            maskSelectors,
+            maskedSelectors
+        }));
+    }
+    catch (error) {
+        failures.push({
+            classification: 'route-failure',
+            summary: `Route failed to render: ${error instanceof Error ? error.message : String(error)}`
+        });
+    }
+    finally {
+        consoleObserver.dispose();
+        await context.close();
+    }
+    const firstFailure = failures[0];
+    const status = failures.length > 0 ? 'fail' : 'pass';
+    const target = `${input.route.path} ${input.viewport}`;
+    return {
+        id: `browser.${input.route.id}.${input.viewport}`,
+        suite: 'browser',
+        target,
+        status,
+        severity: input.blocking ? 'blocking' : 'review',
+        summary: status === 'pass'
+            ? `${input.route.name ?? input.route.id} rendered on ${input.viewport}.`
+            : firstFailure?.summary ?? `${input.route.name ?? input.route.id} failed on ${input.viewport}.`,
+        ...(failures.length > 0 ? { details: failures.map((failure) => failure.details ?? failure.summary).join('\n') } : {}),
+        artifacts,
+        metadata: {
+            route: input.route.path,
+            routeId: input.route.id,
+            viewport: input.viewport,
+            classification: firstFailure?.classification,
+            failures,
+            ...(shouldCaptureScreenshot(input.route.expects)
+                ? {
+                    privacyWarning: 'Screenshots may contain private UI data. Use maskSelectors for sensitive regions.',
+                    maskSelectors,
+                    maskedSelectors
+                }
+                : {})
+        },
+        ...(failures.length > 0 ? { suggestedNextStep: 'Inspect screenshot and browser metadata, then fix the rendered UI contract failure.' } : {})
+    };
+}
+async function applyMaskSelectors(page, selectors) {
+    const applied = [];
+    for (const selector of selectors) {
+        const count = await page.locator(selector).count().catch(() => 0);
+        if (count === 0) {
+            continue;
+        }
+        await page.locator(selector).evaluateAll((elements) => {
+            for (const element of elements) {
+                const target = element;
+                const previousStyle = target.getAttribute('style') ?? '';
+                target.setAttribute('style', `${previousStyle}; visibility: hidden !important;`);
+            }
+        });
+        applied.push(selector);
+    }
+    return applied;
+}
+//# sourceMappingURL=route-runner.js.map

package/dist/contracts/browser/route-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-runner.js","sourceRoot":"","sources":["../../../src/contracts/browser/route-runner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kDAAkD,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAkD,MAAM,iBAAiB,CAAC;AAC/H,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAoB7D,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAAoB;IACxD,MAAM,OAAO,GAAG,MAAM,oBAAoB,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1E,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IACrC,MAAM,eAAe,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAuB,EAAE,CAAC;IACxC,MAAM,SAAS,GAAG,EAAE,CAAC;IACrB,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC;IAChD,IAAI,eAAe,GAAa,EAAE,CAAC;IAEnC,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACxG,MAAM,IAAI,CAAC,gBAAgB,CAAC,aAAa,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAEtF,KAAK,MAAM,WAAW,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;YAC9C,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,IAAI,EAAE,WAAW,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;YACrF,IAAI,OAAO,EAAE,CAAC;gBACZ,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,IAAI,uBAAuB,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACjD,eAAe,GAAG,MAAM,kBAAkB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;YAChE,MAAM,cAAc,GAAG,WAAW,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,QAAQ,aAAa,CAAC;YAChF,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7D,SAAS,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC;QAC5E,CAAC;QAED,MAAM,YAAY,GAAG,WAAW,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,QAAQ,gBAAgB,CAAC;QACjF,SAAS,CAAC,IAAI,CACZ,MAAM,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,YAAY,EAAE;YACxC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI;YACvB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE;YACf,aAAa,EAAE,eAAe,CAAC,MAAM;YACrC,QAAQ;YACR,cAAc,EAAE,uBAAuB,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,mFAAmF,CAAC,CAAC,CAAC,SAAS;YAC9J,aAAa;YACb,eAAe;SAChB,CAAC,CACH,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,QAAQ,CAAC,IAAI,CAAC;YACZ,cAAc,EAAE,eAAe;YAC/B,OAAO,EAAE,2BAA2B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;SAC7F,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,eAAe,CAAC,OAAO,EAAE,CAAC;QAC1B,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;IAED,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IACrD,MAAM,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;IAEvD,OAAO;QACL,EAAE,EAAE,WAAW,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,QAAQ,EAAE;QACjD,KAAK,EAAE,SAAS;QAChB,MAAM;QACN,MAAM;QACN,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ;QAChD,OAAO,EACL,MAAM,KAAK,MAAM;YACf,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,EAAE,gBAAgB,KAAK,CAAC,QAAQ,GAAG;YACxE,CAAC,CAAC,YAAY,EAAE,OAAO,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,EAAE,cAAc,KAAK,CAAC,QAAQ,GAAG;QACnG,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrH,SAAS;QACT,QAAQ,EAAE;YACR,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI;YACvB,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE;YACvB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,cAAc,EAAE,YAAY,EAAE,cAAc;YAC5C,QAAQ;YACR,GAAG,CAAC,uBAAuB,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;gBAC9C,CAAC,CAAC;oBACE,cAAc,EAAE,mFAAmF;oBACnG,aAAa;oBACb,eAAe;iBAChB;gBACH,CAAC,CAAC,EAAE,CAAC;SACR;QACD,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,qFAAqF,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7I,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,kBAAkB,CAAC,IAAU,EAAE,SAAmB;IAC/D,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QAClE,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,SAAS;QACX,CAAC;QAED,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,EAAE;YACpD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,MAAM,MAAM,GAAG,OAAoH,CAAC;gBACpI,MAAM,aAAa,GAAG,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;gBACzD,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,GAAG,aAAa,kCAAkC,CAAC,CAAC;YACnF,CAAC;QACH,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

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

@@ -0,0 +1,30 @@
+import type { ArtifactStore } from '../../core/artifact-store.js';
+import type { CheckResult } from '../../core/report-schema.js';
+import type { ServerConfig } from '../../core/server-manager.js';
+import type { VisualThreshold } from '../visual/thresholds.js';
+export type ComponentVisualCase = {
+    id: string;
+    storyId: string;
+    baseline: string;
+    baselineRoot?: string | undefined;
+    viewport?: string | undefined;
+    threshold?: VisualThreshold | undefined;
+    blocking?: boolean | undefined;
+    strict?: boolean | undefined;
+    stateNote?: string | undefined;
+    browserState?: ComponentBrowserState | undefined;
+};
+export type ComponentBrowserState = {
+    kind: 'hover' | 'focus';
+    selector: string;
+    animationStabilization: {
+        disableAnimations?: boolean | undefined;
+        waitMs?: number | undefined;
+    };
+};
+export type ComponentVisualContractConfig = {
+    enabled?: boolean | undefined;
+    storybook: ServerConfig;
+    cases: ComponentVisualCase[];
+};
+export declare function runComponentVisualContract(config: ComponentVisualContractConfig | undefined, store: ArtifactStore): Promise<CheckResult[]>;

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

@@ -0,0 +1,147 @@
+import { access, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createBaselineStore, createMissingBaselineCheck } from '../../core/baseline-store.js';
+import { createBrowserContext } from '../../integrations/playwright/context-factory.js';
+import { launchBrowser } from '../../integrations/playwright/browser-manager.js';
+import { startStorybookServer } from '../../integrations/storybook/server.js';
+import { resolveStoryUrl } from '../../integrations/storybook/story-url.js';
+import { comparePngImages } from '../visual/image-diff.js';
+export async function runComponentVisualContract(config, store) {
+    if (!config || config.enabled === false || config.cases.length === 0) {
+        return [];
+    }
+    const storybook = await startStorybookServer(config.storybook, {
+        cwd: process.cwd(),
+        logPath: store.resolveRunPath('server/storybook.log')
+    });
+    const browser = await launchBrowser();
+    try {
+        const checks = [];
+        for (const visualCase of config.cases) {
+            const storyUrl = resolveStoryUrl(storybook.index, storybook.baseUrl, visualCase.storyId);
+            checks.push(await runComponentVisualCase({ visualCase, storyUrl, store, browser }));
+        }
+        return checks;
+    }
+    finally {
+        await browser.close();
+        await storybook.server.stop();
+    }
+}
+async function runComponentVisualCase(input) {
+    const viewport = input.visualCase.viewport ?? 'component';
+    const target = `${input.visualCase.storyId} ${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 (!(await pathExists(baselinePath))) {
+        return createMissingBaselineCheck({
+            id: `visual.${input.visualCase.id}`,
+            target,
+            baselinePath: input.visualCase.baseline,
+            blocking,
+            metadata: createComponentStateMetadata(input.visualCase)
+        });
+    }
+    const artifactBase = `visual/${input.visualCase.id}`;
+    const expectedArtifact = await input.store.writeBuffer(`${artifactBase}/expected.png`, await readFile(baselinePath));
+    const actualArtifact = await captureComponentScreenshot({
+        browser: input.browser,
+        store: input.store,
+        path: `${artifactBase}/actual.png`,
+        storyUrl: input.storyUrl,
+        viewport,
+        browserState: input.visualCase.browserState
+    });
+    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(actualArtifact.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: createComponentVisualSummary(input.visualCase.id, result),
+        artifacts: [expectedArtifact, actualArtifact, ...(diffArtifact ? [diffArtifact] : [])],
+        metadata: {
+            ...result,
+            storyId: input.visualCase.storyId,
+            storyUrl: input.storyUrl,
+            viewport,
+            baselinePath: input.visualCase.baseline,
+            ...createComponentStateMetadata(input.visualCase)
+        },
+        ...(result.status === 'pass'
+            ? {}
+            : { suggestedNextStep: 'Inspect expected, actual, and diff artifacts. If intentional, update only this component visual baseline.' })
+    };
+}
+async function captureComponentScreenshot(input) {
+    const context = await createBrowserContext(input.browser, input.viewport);
+    try {
+        const page = await context.newPage();
+        await page.goto(input.storyUrl, { waitUntil: 'domcontentloaded' });
+        await page.waitForLoadState('networkidle', { timeout: 2_000 }).catch(() => undefined);
+        if (input.browserState) {
+            await applyBrowserState(page, input.browserState);
+        }
+        return input.store.writeBuffer(input.path, await page.screenshot());
+    }
+    finally {
+        await context.close();
+    }
+}
+async function applyBrowserState(page, browserState) {
+    if (browserState.animationStabilization.disableAnimations !== false) {
+        await page.addStyleTag({ content: '*, *::before, *::after { animation: none !important; transition: none !important; }' });
+    }
+    if (browserState.kind === 'hover') {
+        await page.locator(browserState.selector).hover();
+    }
+    else {
+        await page.locator(browserState.selector).focus();
+    }
+    if (browserState.animationStabilization.waitMs && browserState.animationStabilization.waitMs > 0) {
+        await page.waitForTimeout(browserState.animationStabilization.waitMs);
+    }
+}
+function createComponentStateMetadata(visualCase) {
+    return {
+        statePolicy: visualCase.browserState ? 'browser-forced-with-stabilization' : 'story-controlled',
+        ...(visualCase.stateNote ? { stateNote: visualCase.stateNote } : {}),
+        ...(visualCase.browserState ? { browserState: visualCase.browserState } : {})
+    };
+}
+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 createComponentVisualSummary(id, result) {
+    if (result.classification === 'visual-match') {
+        return `${id} matches approved component visual baseline.`;
+    }
+    if (result.classification === 'visual-dimension-mismatch') {
+        return `${id} component screenshot dimensions differ from approved baseline.`;
+    }
+    return `${id} differs from approved component visual baseline by ${(result.diffRatio * 100).toFixed(2)}% (${result.diffPixels} pixels)${result.thresholdReason ? `, exceeding ${result.thresholdReason}` : ''}.`;
+}
+//# sourceMappingURL=component-visual-contract.js.map

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

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

package/dist/contracts/design/command-adapter.d.ts

@@ -0,0 +1,17 @@
+import type { ArtifactStore } from '../../core/artifact-store.js';
+import type { ArtifactRef } from '../../core/report-schema.js';
+export type DesignCommandConfig = {
+    id: string;
+    command: string;
+    cwd?: string | undefined;
+    blocking?: boolean | undefined;
+};
+export type DesignCommandResult = {
+    command: DesignCommandConfig;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    artifact: ArtifactRef;
+};
+export declare function runDesignCommand(command: DesignCommandConfig, store: ArtifactStore): Promise<DesignCommandResult>;

package/dist/contracts/design/command-adapter.js

@@ -0,0 +1,60 @@
+import { spawn } from 'node:child_process';
+export async function runDesignCommand(command, store) {
+    const result = await executeShellCommand(command);
+    const artifact = await store.writeText(`design/${safeArtifactName(command.id)}.log`, renderCommandLog(command, result));
+    return {
+        command,
+        ...result,
+        artifact: { ...artifact, type: 'log', role: 'debug' }
+    };
+}
+function executeShellCommand(command) {
+    return new Promise((resolve) => {
+        const child = spawn(command.command, {
+            cwd: command.cwd ?? process.cwd(),
+            shell: true,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        child.on('close', (exitCode, signal) => {
+            resolve({
+                exitCode,
+                signal,
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8')
+            });
+        });
+        child.on('error', (error) => {
+            resolve({ exitCode: 1, signal: null, stdout: '', stderr: error.message });
+        });
+    });
+}
+function renderCommandLog(command, result) {
+    return [
+        `# Reflection design command log`,
+        ``,
+        `Command: ${command.command}`,
+        `CWD: ${command.cwd ?? process.cwd()}`,
+        `Exit code: ${result.exitCode ?? 'signal'}`,
+        result.signal ? `Signal: ${result.signal}` : undefined,
+        ``,
+        `## stdout`,
+        ``,
+        result.stdout || '(empty)',
+        ``,
+        `## stderr`,
+        ``,
+        result.stderr || '(empty)',
+        ``
+    ]
+        .filter((line) => line !== undefined)
+        .join('\n');
+}
+function safeArtifactName(id) {
+    return id.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'command';
+}
+//# sourceMappingURL=command-adapter.js.map

package/dist/contracts/design/command-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-adapter.js","sourceRoot":"","sources":["../../../src/contracts/design/command-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAoB3C,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAA4B,EAAE,KAAoB;IACvF,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,UAAU,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IAExH,OAAO;QACL,OAAO;QACP,GAAG,MAAM;QACT,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE;KACtD,CAAC;AACJ,CAAC;AASD,SAAS,mBAAmB,CAAC,OAA4B;IACvD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE;YACnC,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;YACjC,KAAK,EAAE,IAAI;YACX,WAAW,EAAE,IAAI;YACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;QACH,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAa,EAAE,CAAC;QAE5B,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC/D,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC/D,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;YACrC,OAAO,CAAC;gBACN,QAAQ;gBACR,MAAM;gBACN,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;aAC/C,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5E,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,gBAAgB,CAAC,OAA4B,EAAE,MAAmB;IACzE,OAAO;QACL,iCAAiC;QACjC,EAAE;QACF,YAAY,OAAO,CAAC,OAAO,EAAE;QAC7B,QAAQ,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE;QACtC,cAAc,MAAM,CAAC,QAAQ,IAAI,QAAQ,EAAE;QAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS;QACtD,EAAE;QACF,WAAW;QACX,EAAE;QACF,MAAM,CAAC,MAAM,IAAI,SAAS;QAC1B,EAAE;QACF,WAAW;QACX,EAAE;QACF,MAAM,CAAC,MAAM,IAAI,SAAS;QAC1B,EAAE;KACH;SACE,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC;SACpD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAS,gBAAgB,CAAC,EAAU;IAClC,OAAO,EAAE,CAAC,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC;AACnF,CAAC"}

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

@@ -0,0 +1,8 @@
+import type { ArtifactStore } from '../../core/artifact-store.js';
+import { type CheckResult } from '../../core/report-schema.js';
+import { type DesignCommandConfig } from './command-adapter.js';
+export type DesignContractConfig = {
+    enabled?: boolean | undefined;
+    commands?: DesignCommandConfig[] | undefined;
+};
+export declare function runDesignContract(config: DesignContractConfig | undefined, store: ArtifactStore): Promise<CheckResult[]>;

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

@@ -0,0 +1,149 @@
+import { CheckSeveritySchema, CheckStatusSchema } from '../../core/report-schema.js';
+import { runDesignCommand } from './command-adapter.js';
+import { z } from 'zod';
+export async function runDesignContract(config, store) {
+    if (!config || config.enabled === false) {
+        return [];
+    }
+    const commands = config.commands ?? [];
+    const checks = [];
+    for (const command of commands) {
+        const result = await runDesignCommand(command, store);
+        checks.push(...normalizeDesignCommandResult(result));
+    }
+    return checks;
+}
+const StructuredDesignCheckSchema = z.object({
+    id: z.string().min(1),
+    family: z.string().min(1).optional(),
+    target: z.string().min(1),
+    status: CheckStatusSchema,
+    severity: CheckSeveritySchema.optional(),
+    summary: z.string().min(1),
+    details: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional()
+});
+const StructuredDesignOutputSchema = z.object({
+    reflection: z.literal('design-checks-v1'),
+    checks: z.array(StructuredDesignCheckSchema).min(1)
+});
+function normalizeDesignCommandResult(result) {
+    const structured = parseStructuredDesignOutput(result.stdout);
+    if (structured) {
+        const checks = structured.checks.map((check) => normalizeStructuredDesignCheck(check, result));
+        const commandFailure = normalizeStructuredCommandFailure(result);
+        return commandFailure ? [...checks, commandFailure] : checks;
+    }
+    return [normalizeGlobalDesignCheck(result)];
+}
+function normalizeStructuredDesignCheck(check, result) {
+    const severity = check.severity ?? defaultDesignSeverity(check.status, result.command.blocking ?? true);
+    return {
+        id: `design.${stripDesignPrefix(check.id)}`,
+        suite: 'design',
+        target: check.target,
+        status: check.status,
+        severity,
+        summary: check.summary,
+        details: check.details,
+        artifacts: [result.artifact],
+        metadata: {
+            ...(check.metadata ?? {}),
+            ...(check.family ? { family: check.family } : {}),
+            commandId: result.command.id,
+            command: result.command.command,
+            cwd: result.command.cwd ?? process.cwd(),
+            exitCode: result.exitCode,
+            signal: result.signal,
+            classification: 'token-source-contract'
+        },
+        suggestedNextStep: check.status === 'pass' || check.status === 'skipped'
+            ? undefined
+            : 'Review the full command log artifact and update the token/source contract or implementation.'
+    };
+}
+function normalizeStructuredCommandFailure(result) {
+    if (result.exitCode === 0 && !result.signal) {
+        return undefined;
+    }
+    const blocking = result.command.blocking ?? true;
+    const status = blocking ? 'fail' : 'warn';
+    const severity = blocking ? 'blocking' : 'review';
+    return {
+        id: `design.${result.command.id}.command`,
+        suite: 'design',
+        target: result.command.id,
+        status,
+        severity,
+        summary: `Design token/source contract command "${result.command.id}" exited ${result.exitCode ?? `with signal ${result.signal}`}.`,
+        details: summarizeOutput(result.stdout, result.stderr),
+        artifacts: [result.artifact],
+        metadata: {
+            command: result.command.command,
+            cwd: result.command.cwd ?? process.cwd(),
+            exitCode: result.exitCode,
+            signal: result.signal,
+            classification: 'token-source-contract',
+            structuredOutput: true
+        },
+        suggestedNextStep: 'Review the full command log artifact and fix the validator command failure.'
+    };
+}
+function normalizeGlobalDesignCheck(result) {
+    const passed = result.exitCode === 0;
+    const blocking = result.command.blocking ?? true;
+    const status = passed ? 'pass' : blocking ? 'fail' : 'warn';
+    const severity = blocking ? 'blocking' : 'review';
+    return {
+        id: `design.${result.command.id}`,
+        suite: 'design',
+        target: result.command.id,
+        status,
+        severity,
+        summary: passed
+            ? `Design token/source contract command "${result.command.id}" passed.`
+            : `Design token/source contract command "${result.command.id}" exited ${result.exitCode ?? `with signal ${result.signal}`}.`,
+        details: summarizeOutput(result.stdout, result.stderr),
+        artifacts: [result.artifact],
+        metadata: {
+            command: result.command.command,
+            cwd: result.command.cwd ?? process.cwd(),
+            exitCode: result.exitCode,
+            signal: result.signal,
+            classification: 'token-source-contract'
+        },
+        suggestedNextStep: passed ? undefined : 'Review the full command log artifact and update the token/source contract or implementation.'
+    };
+}
+function defaultDesignSeverity(status, blocking) {
+    if (status === 'pass' || status === 'skipped') {
+        return 'review';
+    }
+    return blocking ? 'blocking' : 'review';
+}
+function parseStructuredDesignOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        const result = StructuredDesignOutputSchema.safeParse(parsed);
+        return result.success ? result.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function stripDesignPrefix(id) {
+    return id.startsWith('design.') ? id.slice('design.'.length) : id;
+}
+function summarizeOutput(stdout, stderr) {
+    const output = `${stdout}\n${stderr}`.trim();
+    if (!output) {
+        return 'No command output.';
+    }
+    const lines = output.split(/\r?\n/).filter(Boolean);
+    return lines.slice(0, 6).join('\n');
+}
+//# sourceMappingURL=design-contract.js.map

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

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

package/dist/contracts/visual/baseline-compare.d.ts

@@ -0,0 +1,19 @@
+import type { ArtifactStore } from '../../core/artifact-store.js';
+import type { CheckResult } from '../../core/report-schema.js';
+import type { VisualThreshold } from './thresholds.js';
+export type RouteVisualBaselineCase = {
+    id: string;
+    route: string;
+    viewport: string;
+    baseline: string;
+    baselineRoot?: string | undefined;
+    threshold?: VisualThreshold | undefined;
+    blocking?: boolean | undefined;
+    strict?: boolean | undefined;
+};
+export type CompareRouteVisualBaselineInput = {
+    visualCase: RouteVisualBaselineCase;
+    routeCheck: CheckResult;
+    store: ArtifactStore;
+};
+export declare function compareRouteVisualBaseline(input: CompareRouteVisualBaselineInput): Promise<CheckResult>;