@crvouga/atlas 0.0.0-stage → 0.2.0

package/dist/reports/src/report-parts.js

@@ -0,0 +1,112 @@
+import { publishLayer } from './layer-store.js';
+import { readCommit } from './read.js';
+import { readInventory } from './spec-inventory.js';
+import { readUtf8, writeUtf8 } from './object-io.js';
+import { inCompletionOrder } from './completion-order.js';
+import { recordExplorerVersion } from './explorer-versions.js';
+import { isCommitSha, isKeySegment } from './keys.js';
+const STATUSES = new Set(['passed', 'failed', 'running', 'not-run']);
+export function partStatus(part) {
+    const statuses = part.checks.map((check) => check.status);
+    if (statuses.includes('failed'))
+        return 'failed';
+    if (statuses.includes('running'))
+        return 'running';
+    if (statuses.length === 0 || statuses.includes('not-run'))
+        return 'not-run';
+    return 'passed';
+}
+export function validatePart(part) {
+    if (!isCommitSha(part.sha) ||
+        !isKeySegment(part.id) ||
+        typeof part.kind !== 'string' ||
+        !part.kind ||
+        typeof part.title !== 'string' ||
+        !part.title ||
+        !Number.isSafeInteger(part.recordedAtMs) ||
+        part.recordedAtMs < 0 ||
+        !Array.isArray(part.checks))
+        throw new Error('Invalid report part');
+    if (part.parameters && Object.values(part.parameters).some(value => typeof value !== 'string'))
+        throw new Error('Invalid report parameters');
+    const ids = new Set();
+    for (const check of part.checks) {
+        if (typeof check.id !== 'string' ||
+            !check.id ||
+            ids.has(check.id) ||
+            typeof check.title !== 'string' ||
+            !check.title ||
+            typeof check.detail !== 'string' ||
+            !STATUSES.has(check.status) ||
+            !Array.isArray(check.measurements))
+            throw new Error('Invalid evidence check');
+        ids.add(check.id);
+        for (const measurement of check.measurements) {
+            if (typeof measurement.name !== 'string' ||
+                !measurement.name ||
+                typeof measurement.unit !== 'string' ||
+                !measurement.unit ||
+                !Number.isFinite(measurement.value) ||
+                (measurement.limit !== undefined && !Number.isFinite(measurement.limit)))
+                throw new Error('Invalid evidence measurement');
+        }
+    }
+}
+function partsPrefix(sha) {
+    if (!isCommitSha(sha))
+        throw new Error('Invalid commit');
+    return `commits/${sha}/parts/`;
+}
+/** Each producer owns a separate key, independent of the spec-run attempt. */
+export async function publishPart(store, part) {
+    validatePart(part);
+    const json = JSON.stringify(part);
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(json)));
+    const hash = [...digest]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+    await writeUtf8(store, `${partsPrefix(part.sha)}${part.id}/${part.recordedAtMs}-${hash}.json`, json, 'application/json');
+    await recordExplorerVersion(store, part.sha);
+    const commit = await readCommit(store, part.sha);
+    await publishLayer(store, {
+        ...(part.freshness ? { freshness: part.freshness } : {}), producer: part.id, recordedAtMs: part.recordedAtMs, sha: part.sha, branch: commit?.branch ?? null, runUrl: commit?.runUrl ?? null,
+        parameters: part.parameters ?? {}, specs: (await readInventory(store, part.sha))?.entries ?? [], parts: [part], source: null, recording: null,
+    }, (async function* () { })());
+}
+/** Latest result per producer, sorted stably; corrupt evidence fails visibly. */
+export async function readParts(store, sha) {
+    const keys = await store.listKeys(partsPrefix(sha));
+    const parts = [];
+    const tasks = keys.map((key) => async () => {
+        const raw = await readUtf8(store, key);
+        if (raw === null)
+            throw new Error('Report part disappeared');
+        const part = JSON.parse(raw);
+        validatePart(part);
+        if (part.sha !== sha || !key.startsWith(`${partsPrefix(sha)}${part.id}/`))
+            throw new Error('Report part belongs to another commit');
+        return part;
+    });
+    for await (const part of inCompletionOrder(tasks, 16))
+        parts.push(part);
+    return latestParts(parts);
+}
+/** Ties are conservative and independent of write/list order. */
+export function latestParts(parts) {
+    const latest = new Map();
+    const rank = { passed: 0, 'not-run': 1, running: 2, failed: 3 };
+    for (const part of parts) {
+        const previous = latest.get(part.id);
+        if (!previous ||
+            part.recordedAtMs > previous.recordedAtMs ||
+            (part.recordedAtMs === previous.recordedAtMs &&
+                (rank[partStatus(part)] > rank[partStatus(previous)] ||
+                    (rank[partStatus(part)] === rank[partStatus(previous)] &&
+                        JSON.stringify(part) > JSON.stringify(previous)))))
+            latest.set(part.id, part);
+    }
+    return [...latest.values()].sort((a, b) => compare(a.kind, b.kind) || compare(a.id, b.id));
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/dist/reports/src/report-types.d.ts

@@ -0,0 +1,194 @@
+import type { Clock } from './clock.js';
+import type { ObjectStore } from './object-store.js';
+/** Observed elapsed work, independent of the simulation clock. */
+export type ReportStepPerformance = {
+    readonly executionMs: number;
+    readonly selfMs: number;
+    readonly snapshotMs: number;
+};
+export type ReportPerformanceSummary = {
+    readonly executionMs: number;
+    readonly snapshotMs: number;
+    readonly measuredSteps: number;
+    readonly slowSteps: number;
+    readonly slowStepMs: number;
+};
+export type ReportPerformanceOptions = {
+    readonly clock: Clock;
+    /** Diagnostic threshold, not a portable CPU or paint-time assertion. */
+    readonly slowStepMs: number;
+};
+/** How a captured value is encoded on disk and rendered in the report. */
+export type SnapshotMedia = 'json' | 'html' | 'png' | 'text' | 'bytes';
+export type ReportStepStatus = 'passed' | 'failed';
+/** Test outcome after the harness (e.g. the test runner) has weighed in. */
+export type ReportTestStatus = 'passed' | 'failed' | 'skipped';
+/**
+ * One blob produced by a snapshotter at a point in time.
+ * Multi-actor UI maps become one entry per nodeId.
+ */
+export type ReportSnapshotBlob = {
+    readonly name: string;
+    readonly media: SnapshotMedia;
+    /** Relative path under the test dir, e.g. `frames/f-00001.html.alice.html`. */
+    readonly file: string;
+    readonly nodeId?: string;
+};
+/** Discrete visual/state capture within a report step. */
+export type ReportFrame = {
+    readonly index: number;
+    readonly capturedAtMs: number;
+    readonly durationMs?: number;
+    readonly snapshots: readonly ReportSnapshotBlob[];
+    /**
+     * Gesture target, set only on the frame captured right before a UI step
+     * acts (the target is still mounted). Viewers highlight it on this frame.
+     */
+    readonly hit?: ReportStepHit;
+};
+/**
+ * Where a UI gesture landed — test-id path (chained first-match, as the
+ * driver resolves it) + optional tap point relative to the target box.
+ * Viewers resolve the path against the snapshot DOM for real geometry.
+ */
+export type ReportStepHit = {
+    readonly path: readonly string[];
+    readonly point?: {
+        readonly xRatio: number;
+        readonly yRatio: number;
+    };
+};
+/**
+ * One labeled entry on the report timeline. Steps nest: an `apply` step
+ * holds the UI ops recorded while its action ran.
+ */
+export type ReportStep = {
+    readonly index: number;
+    readonly kind: string;
+    readonly title: string;
+    readonly status: ReportStepStatus;
+    readonly startedAtMs: number;
+    readonly endedAtMs: number;
+    readonly durationMs: number;
+    readonly performance?: ReportStepPerformance;
+    readonly actorId?: string;
+    readonly selector?: string;
+    readonly detail?: string;
+    readonly action?: string;
+    readonly args?: readonly unknown[];
+    readonly error?: string;
+    readonly errorStack?: string;
+    readonly frames: readonly ReportFrame[];
+    readonly steps: readonly ReportStep[];
+};
+export type RunReportMeta = {
+    readonly system: string;
+    readonly runtime: string;
+    readonly seed: string;
+    readonly startedAtMs: number;
+    readonly endedAtMs: number;
+    readonly durationMs: number;
+    readonly performance?: ReportPerformanceSummary;
+    readonly status: ReportTestStatus;
+    readonly runId: string;
+    readonly testId: string;
+    /** Human title (defaults to `testId`). */
+    readonly title: string;
+    readonly actorIds: readonly string[];
+    readonly sourceFile?: string;
+    /** 1-based line of the call that opened this run, when known. */
+    readonly sourceLine?: number;
+    /** First failure message (step, property, or harness). */
+    readonly error?: string;
+    readonly errorStack?: string;
+};
+/** In-memory / persisted timeline for one test run. */
+export type RunReport = {
+    readonly meta: RunReportMeta;
+    readonly steps: readonly ReportStep[];
+};
+export type SuiteTestSummary = {
+    readonly testId: string;
+    readonly title: string;
+    readonly seed: string;
+    readonly status: ReportTestStatus;
+    readonly durationMs: number;
+    readonly stepCount: number;
+    readonly frameCount: number;
+    readonly system: string;
+    readonly runtime: string;
+    readonly sourceFile?: string;
+    readonly error?: string;
+};
+export type SuiteManifest = {
+    readonly tests: readonly SuiteTestSummary[];
+    readonly updatedAtMs: number;
+};
+export type RunSummary = {
+    readonly id: string;
+    readonly updatedAtMs: number;
+    readonly status: ReportTestStatus;
+    readonly testCount: number;
+    readonly frameCount: number;
+};
+export type RunsIndex = {
+    readonly runs: readonly RunSummary[];
+};
+/** Metadata for an open `run.record(...)` call. */
+export type RecordStepMeta = {
+    readonly kind: string;
+    readonly title: string;
+    readonly actorId?: string;
+    readonly selector?: string;
+    readonly detail?: string;
+    /** Press / gesture target; persisted onto the step's pre-action frame. */
+    readonly hit?: ReportStepHit;
+    /** Capture snapshots before `fn` (e.g. before close unmounts). */
+    readonly snapshotBefore?: boolean;
+    /** Skip registered snapshotters for this step. */
+    readonly skipSnapshot?: boolean;
+};
+export type ReportCaptureMode = 'apply' | 'none';
+export type RunReportOptions = {
+    /** Enable elapsed work measurement with a separate monotonic clock. */
+    readonly performance?: ReportPerformanceOptions;
+    /** When false, reporting is disabled even if options object is passed. */
+    readonly enabled?: boolean;
+    /** Object store for this report bucket (required for persistence). */
+    readonly store?: ObjectStore;
+    /**
+     * Run id under `runs/<runId>/`. Default: `YYYYMMDDTHHmmss` UTC from `now`.
+     */
+    readonly runId?: string;
+    /**
+     * Stable id for this test under the run (`tests/<testId>/`).
+     * Default: sanitized system name.
+     */
+    readonly testId?: string;
+    /** Human title shown in reports. Default: `testId`. */
+    readonly title?: string;
+    /**
+     * Epoch-ms clock for step timestamps. Default: session clock.
+     */
+    readonly now?: () => number;
+    /**
+     * When to auto-open a report step. Default `apply` (each `s.apply`).
+     * `advanceTime` never opens a step (avoids poll spam).
+     */
+    readonly capture?: ReportCaptureMode;
+    /**
+     * Capture the registered snapshotters (UI frames, state) onto each step.
+     * Default true. False keeps the timeline — every step, its outcome and
+     * error — without the frames, which are what make a report expensive.
+     */
+    readonly frames?: boolean;
+    /** Repo-relative path to the test source file when known. */
+    readonly sourceFile?: string;
+    /** 1-based source line of the call that opened the run, when known. */
+    readonly sourceLine?: number;
+};
+export declare function sanitizeTestId(raw: string): string;
+export declare function sanitizeRunId(raw: string): string;
+/** Mint `YYYYMMDDTHHmmss` UTC from epoch ms. */
+export declare function mintRunId(nowMs: number): string;
+export declare function resolveReportOptions(report: boolean | RunReportOptions | undefined): RunReportOptions | null;

package/dist/reports/src/report-types.js

@@ -0,0 +1,29 @@
+export function sanitizeTestId(raw) {
+    const cleaned = raw.replace(/[^a-zA-Z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
+    return cleaned.length > 0 ? cleaned : 'test';
+}
+export function sanitizeRunId(raw) {
+    const cleaned = raw.replace(/[^a-zA-Z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
+    return cleaned.length > 0 ? cleaned : 'run';
+}
+/** Mint `YYYYMMDDTHHmmss` UTC from epoch ms. */
+export function mintRunId(nowMs) {
+    const d = new Date(nowMs);
+    const y = d.getUTCFullYear();
+    const mo = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(d.getUTCDate()).padStart(2, '0');
+    const h = String(d.getUTCHours()).padStart(2, '0');
+    const mi = String(d.getUTCMinutes()).padStart(2, '0');
+    const s = String(d.getUTCSeconds()).padStart(2, '0');
+    return `${y}${mo}${day}T${h}${mi}${s}`;
+}
+export function resolveReportOptions(report) {
+    if (report === undefined || report === false)
+        return null;
+    if (report === true)
+        return { enabled: true };
+    if (report.enabled === false)
+        return null;
+    const { enabled: _enabled, ...rest } = report;
+    return { enabled: true, ...rest };
+}

package/dist/reports/src/reports-explorer-route.d.ts

@@ -0,0 +1,90 @@
+import type { WorkspaceReports } from './explorer-types.js';
+import type { ReportsStores } from './reports-store.js';
+export type ReportsExplorerDeps = ReportsStores & {
+    readonly workspace?: () => Promise<WorkspaceReports>;
+};
+export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): import("hono/hono-base").HonoBase<import("hono/types").BlankEnv, {
+    "/:sha/explorer": {
+        $get: {
+            input: {
+                param: {
+                    sha: string;
+                };
+            };
+            output: {
+                error: string;
+            };
+            outputFormat: "json";
+            status: 404;
+        } | {
+            input: {
+                param: {
+                    sha: string;
+                };
+            };
+            output: {
+                error: string;
+            };
+            outputFormat: "json";
+            status: 503;
+        } | {
+            input: {
+                param: {
+                    sha: string;
+                };
+            };
+            output: {
+                notice?: string | undefined;
+                inventory: {
+                    readonly sha: string;
+                    readonly entries: readonly {
+                        readonly path: string;
+                        readonly domain: string;
+                        readonly kind: string;
+                        readonly title: string;
+                        readonly fingerprint?: string | undefined;
+                    }[];
+                } | null;
+                parts: readonly {
+                    readonly freshness?: "unknown" | "modified" | undefined;
+                    readonly parameters?: {
+                        readonly [x: string]: string;
+                    } | undefined;
+                    readonly sha: string;
+                    readonly id: string;
+                    readonly kind: string;
+                    readonly title: string;
+                    readonly recordedAtMs: number;
+                    readonly checks: readonly {
+                        readonly id: string;
+                        readonly title: string;
+                        readonly status: import('./explorer-types.js').EvidenceStatus;
+                        readonly detail: string;
+                        readonly specPath?: string | undefined;
+                        readonly measurements: readonly {
+                            readonly name: string;
+                            readonly value: number;
+                            readonly unit: string;
+                            readonly limit?: number | undefined;
+                        }[];
+                    }[];
+                }[];
+            };
+            outputFormat: "json";
+            status: 200;
+        };
+    };
+} & {
+    "/:sha/spec": {
+        $get: {
+            input: {
+                param: {
+                    sha: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+}, "/", "/:sha/spec">;

package/dist/reports/src/reports-explorer-route.js

@@ -0,0 +1,65 @@
+import { isCommitSha } from './keys.js';
+import { latestParts, readParts, } from './report-parts.js';
+import { isSpecPath, readInventory, readSpecDocument, } from './spec-inventory.js';
+import { Hono } from 'hono';
+const NO_STORE = { 'cache-control': 'no-store' };
+export function createReportsExplorerApp(deps) {
+    return new Hono()
+        .get('/:sha/explorer', async (c) => {
+        const sha = c.req.param('sha');
+        if (!isCommitSha(sha))
+            return c.json({ error: 'not_found' }, 404, NO_STORE);
+        const workspace = await deps.workspace?.();
+        const local = workspace?.version.sha === sha ? workspace : null;
+        const { inventory, parts, notice } = await explorerData(deps, sha, local);
+        if (deps.store === null && inventory === null && parts.length === 0)
+            return c.json({ error: 'reports_unavailable' }, 503, NO_STORE);
+        return c.json({ inventory, parts: latestParts(parts), ...(notice ? { notice } : {}) }, 200, NO_STORE);
+    })
+        .get('/:sha/spec', async (c) => {
+        const sha = c.req.param('sha');
+        const path = c.req.query('path') ?? '';
+        if (!isCommitSha(sha) || !isSpecPath(path))
+            return c.json({ error: 'not_found' }, 404, NO_STORE);
+        const workspace = await deps.workspace?.();
+        const localBody = deps.localStore
+            ? await readSpecDocument(deps.localStore, sha, path)
+            : null;
+        const body = workspace?.version.sha === sha
+            ? await workspace.readSpec(path)
+            : localBody !== null
+                ? localBody
+                : deps.store === null
+                    ? null
+                    : await readSpecDocument(deps.store, sha, path);
+        return body === null
+            ? c.json({ error: 'not_found' }, 404, NO_STORE)
+            : new Response(body, {
+                headers: {
+                    ...NO_STORE,
+                    'content-type': 'text/plain; charset=utf-8',
+                },
+            });
+    });
+}
+async function explorerData(deps, sha, local) {
+    let inventory = local?.inventory ??
+        (deps.localStore ? await readInventory(deps.localStore, sha) : null);
+    const localParts = local?.parts ??
+        (deps.localStore ? await readParts(deps.localStore, sha) : []);
+    let parts = [...localParts];
+    let notice;
+    try {
+        if (deps.store !== null) {
+            inventory ??= await readInventory(deps.store, sha);
+            parts = [...(await readParts(deps.store, sha)), ...localParts];
+        }
+    }
+    catch (error) {
+        if (inventory === null && parts.length === 0)
+            throw error;
+        notice =
+            'Published evidence could not be read. Available specs and evidence remain readable. Refresh to try again.';
+    }
+    return { inventory, parts, notice };
+}

package/dist/reports/src/reports-list-route.d.ts

@@ -0,0 +1,23 @@
+import type { Context } from 'hono';
+import type { ReportsExplorerDeps } from './reports-explorer-route.js';
+export declare function reportsListRoute(deps: ReportsExplorerDeps): (c: Context) => Promise<(Response & import("hono").TypedResponse<{
+    error: string;
+}, 503, "json">) | (Response & import("hono").TypedResponse<{
+    notice?: string | undefined;
+    workspace?: {
+        readonly sha: string;
+        readonly branch: string;
+        readonly dirty: boolean;
+    } | undefined;
+    evidenceVersions?: readonly string[] | undefined;
+    commits: readonly {
+        readonly sha: string;
+        readonly branch: string;
+        readonly runUrl: string | null;
+        readonly state: import('./protocol.js').CommitState;
+        readonly startedAtMs: number;
+        readonly endedAtMs: number | null;
+        readonly status: import('./report-types.js').ReportTestStatus | null;
+    }[];
+    cursor: string | null;
+}, 200, "json">)>;

package/dist/reports/src/reports-list-route.js

@@ -0,0 +1,55 @@
+import { listExplorerVersions } from './explorer-versions.js';
+import { listCommits } from './read.js';
+const NO_STORE = { 'cache-control': 'no-store' };
+export function reportsListRoute(deps) {
+    return async (c) => {
+        const workspace = await deps.workspace?.();
+        if (deps.store === null &&
+            workspace === undefined &&
+            deps.localStore === undefined)
+            return c.json({ error: 'reports_unavailable' }, 503, NO_STORE);
+        try {
+            const page = deps.store === null
+                ? { commits: [], cursor: null }
+                : await listCommits(deps.store, {
+                    limit: 30,
+                    cursor: c.req.query('cursor') ?? null,
+                });
+            const evidenceVersions = c.req.query('cursor')
+                ? []
+                : await explorerVersions(deps);
+            return c.json({
+                ...page,
+                ...(evidenceVersions.length ? { evidenceVersions } : {}),
+                ...(workspace === undefined ? {} : { workspace: workspace.version }),
+                ...(deps.store === null
+                    ? {
+                        notice: 'Published reports are unavailable because this environment has no reports read credential. The current checkout specs and collected local evidence are available.',
+                    }
+                    : {}),
+            }, 200, NO_STORE);
+        }
+        catch (error) {
+            if (workspace === undefined)
+                throw error;
+            return localFallback(c, deps, workspace);
+        }
+    };
+}
+async function localFallback(c, deps, workspace) {
+    return c.json({
+        commits: [],
+        cursor: null,
+        workspace: workspace.version,
+        evidenceVersions: deps.localStore
+            ? await listExplorerVersions(deps.localStore)
+            : [],
+        notice: 'The published reports store could not be reached. The current checkout specs and collected local evidence are available; try refreshing published reports.',
+    }, 200, NO_STORE);
+}
+async function explorerVersions(deps) {
+    const stores = [deps.store, deps.localStore].filter((store) => store != null);
+    return [
+        ...new Set((await Promise.all(stores.map((store) => listExplorerVersions(store)))).flat()),
+    ];
+}