@crvouga/atlas 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,267 @@
+import type { LiveSource } from './evidence-live.js';
+import type { ReportOutline } from './layer-types.js';
+import { type ReportBackend } from './layers-route.js';
+/**
+ * The spec reports API: read-only views of the shared reports store (R2,
+ * keyed by commit sha; Atlas owns the layout), streamed to
+ * the reports screen as Server-Sent Events.
+ *
+ * - `GET /reports` — commits with a report, newest first (`?cursor=`)
+ * - `GET /reports/:sha` — one commit's run record
+ * - `GET /reports/:sha/events` — the commit, then each source as it is read;
+ *   a running commit stays open and sends new sources as CI publishes them
+ *   (`?have=a,b` skips the sources a reconnecting client holds)
+ * - `GET /reports/:sha/sources` — every source record of the selected attempt
+ * - `GET /reports/:sha/frame.css` — the stylesheet its snapshots render with
+ * - `GET /reports/:sha/tests/:source/:testId` — one test's timeline, no frames
+ * - `GET /reports/:sha/tests/:source/:testId/files/*` — one frame file
+ * - `GET /reports/:sha/tests/:source/:testId/events` — a test, then its frames
+ *
+ * Mounted ahead of the per-request database middleware: nothing here touches
+ * Postgres, and a long-lived stream must not hold a connection. Every
+ * environment reads the same store, so any deployment serves any commit.
+ */
+import type { Clock, Timers } from './clock.js';
+import type { ObjectStore } from './object-store.js';
+import { type ReportsExplorerDeps } from './reports-explorer-route.js';
+/** Commits per page of `GET /reports`. */
+export declare const REPORTS_PAGE_SIZE = 30;
+/** How often a running commit is re-listed for new sources. */
+export declare const REPORTS_POLL_MS = 2000;
+/** A running commit's stream ends after this long; the client reconnects. */
+export declare const REPORTS_TAIL_MS: number;
+export type ReportsAppDeps = ReportsExplorerDeps & {
+    readonly outline?: () => Promise<ReportOutline & {
+        readSpec: (path: string) => Promise<string | null>;
+    }>;
+    /** Further stores whose layers join the combined report beside `localStore` and `store`. */
+    readonly backends?: readonly ReportBackend[];
+    /** Results of spec runs that are still running on this machine. */
+    readonly live?: LiveSource;
+    /** The shared reports store; null when this deployment has no credential. */
+    readonly store: ObjectStore | null;
+    readonly clock: Clock;
+    readonly timers: Timers;
+};
+export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hono-base").HonoBase<{}, ((((((((import("hono/types").BlankSchema | import("hono/types").MergeSchemaPath<import("hono/types").BlankSchema, "/"> | import("hono/types").MergeSchemaPath<{
+    "/: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;
+        };
+    };
+}, "/">) & {
+    "/": {
+        $get: {
+            input: {};
+            output: {
+                error: string;
+            };
+            outputFormat: "json";
+            status: 503;
+        } | {
+            input: {};
+            output: {
+                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;
+            };
+            outputFormat: "json";
+            status: 200;
+        };
+    };
+}) & {
+    "/:sha": {
+        $get: {
+            input: {
+                param: {
+                    sha: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+}) & {
+    "/:sha/events": {
+        $get: {
+            input: {
+                param: {
+                    sha: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+}) & {
+    "/:sha/sources": {
+        $get: {
+            input: {
+                param: {
+                    sha: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+}) & {
+    "/:sha/frame.css": {
+        $get: {
+            input: {
+                param: {
+                    sha: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+}) & {
+    "/:sha/tests/:source/:testId": {
+        $get: {
+            input: {
+                param: {
+                    sha: string;
+                } & {
+                    source: string;
+                } & {
+                    testId: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+}) & {
+    "/:sha/tests/:source/:testId/files/*": {
+        $get: {
+            input: {
+                param: {
+                    sha: string;
+                } & {
+                    source: string;
+                } & {
+                    testId: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+}) & {
+    "/:sha/tests/:source/:testId/events": {
+        $get: {
+            input: {
+                param: {
+                    sha: string;
+                } & {
+                    source: string;
+                } & {
+                    testId: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+}, "/", "/:sha/tests/:source/:testId/events">;

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

@@ -0,0 +1,204 @@
+import { createLayersApp } from './layers-route.js';
+import { isCommitSha, isFramePath, isKeySegment, } from './keys.js';
+import { EVENT_STREAM_CONTENT_TYPE, encodeSseEvent, } from './protocol.js';
+import { commitEvents, readCommit, readFrameBody, readFrameCss, readTestReport, testEvents, } from './read.js';
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { createReportsExplorerApp, } from './reports-explorer-route.js';
+import { reportsListRoute } from './reports-list-route.js';
+import { reportsSources, reportsStoreForCommit, reportsStoreForSource, } from './reports-store.js';
+/** Commits per page of `GET /reports`. */
+export const REPORTS_PAGE_SIZE = 30;
+/** How often a running commit is re-listed for new sources. */
+export const REPORTS_POLL_MS = 2_000;
+/** A running commit's stream ends after this long; the client reconnects. */
+export const REPORTS_TAIL_MS = 5 * 60_000;
+const NO_STORE = { 'cache-control': 'no-store' };
+function eventStream(events) {
+    const encoder = new TextEncoder();
+    const body = new ReadableStream({
+        async pull(controller) {
+            const next = await events.next();
+            if (next.done === true)
+                controller.close();
+            else
+                controller.enqueue(encoder.encode(encodeSseEvent(next.value)));
+        },
+        async cancel() {
+            await events.return(undefined);
+        },
+    });
+    return new Response(body, {
+        status: 200,
+        headers: {
+            'content-type': EVENT_STREAM_CONTENT_TYPE,
+            'x-accel-buffering': 'no',
+            ...NO_STORE,
+        },
+    });
+}
+function bytesResponse(bytes, headers) {
+    const copy = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(copy).set(bytes);
+    return new Response(copy, { status: 200, headers });
+}
+function frameFileParam(raw) {
+    if (raw === undefined || raw.length === 0)
+        return null;
+    let file;
+    try {
+        file = decodeURIComponent(raw);
+    }
+    catch {
+        return null;
+    }
+    return isFramePath(file) ? file : null;
+}
+function haveSources(raw) {
+    return new Set((raw ?? '').split(',').filter(isKeySegment));
+}
+function unavailable() {
+    return Response.json({ error: 'reports_unavailable' }, { status: 503, headers: NO_STORE });
+}
+function notFound() {
+    return Response.json({ error: 'not_found' }, { status: 404, headers: NO_STORE });
+}
+async function storeOf(deps, sha, source) {
+    if (!isCommitSha(sha))
+        return notFound();
+    return ((await (source === undefined
+        ? reportsStoreForCommit(deps, sha)
+        : reportsStoreForSource(deps, sha, source))) ?? unavailable());
+}
+function testParams(c) {
+    const sha = c.req.param('sha');
+    const source = c.req.param('source');
+    const testId = c.req.param('testId');
+    if (sha === undefined ||
+        source === undefined ||
+        testId === undefined ||
+        !isCommitSha(sha) ||
+        !isKeySegment(source) ||
+        !isKeySegment(testId)) {
+        return notFound();
+    }
+    return { sha, source, testId };
+}
+function sourcesRoute(deps) {
+    return async (c) => {
+        const sha = c.req.param('sha') ?? '';
+        const store = await storeOf(deps, sha);
+        if (store instanceof Response)
+            return store;
+        const sources = await reportsSources(deps, sha);
+        return c.json({ sources }, 200, NO_STORE);
+    };
+}
+function testRoute(deps) {
+    return async (c) => {
+        const params = testParams(c);
+        if (params instanceof Response)
+            return params;
+        const store = await storeOf(deps, params.sha, params.source);
+        if (store instanceof Response)
+            return store;
+        const report = await readTestReport(store, params);
+        if (report === null)
+            return notFound();
+        return c.json(report, 200, NO_STORE);
+    };
+}
+/** Hono's tail `*` matches the rest of the path and does not expose it. */
+function frameFileOf(url, params) {
+    const marker = `/tests/${params.source}/${params.testId}/files/`;
+    const path = new URL(url).pathname;
+    const at = path.indexOf(marker);
+    if (at < 0)
+        return null;
+    return frameFileParam(path.slice(at + marker.length));
+}
+function fileRoute(deps) {
+    return async (c) => {
+        const params = testParams(c);
+        if (params instanceof Response)
+            return params;
+        const file = frameFileOf(c.req.url, params);
+        if (file === null)
+            return notFound();
+        const store = await storeOf(deps, params.sha, params.source);
+        if (store instanceof Response)
+            return store;
+        const body = await readFrameBody(store, { ...params, file });
+        if (body === null)
+            return notFound();
+        return bytesResponse(body.bytes, {
+            'content-type': body.contentType,
+            ...NO_STORE,
+        });
+    };
+}
+function testEventsRoute(deps) {
+    return async (c) => {
+        const params = testParams(c);
+        if (params instanceof Response)
+            return params;
+        const store = await storeOf(deps, params.sha, params.source);
+        if (store instanceof Response)
+            return store;
+        return eventStream(testEvents(store, params));
+    };
+}
+export function createReportsApp(deps) {
+    return new Hono()
+        .use('*', cors({ origin: (origin) => origin, allowMethods: ['GET', 'HEAD', 'OPTIONS'] }))
+        .route('/', createLayersApp(deps))
+        .route('/', createReportsExplorerApp(deps))
+        .get('/', reportsListRoute(deps))
+        .get('/:sha', async (c) => {
+        const sha = c.req.param('sha');
+        if (!isCommitSha(sha))
+            return notFound();
+        const store = await storeOf(deps, sha);
+        if (store instanceof Response)
+            return store;
+        const commit = await readCommit(store, sha);
+        return commit === null ? notFound() : c.json(commit, 200, NO_STORE);
+    })
+        .get('/:sha/events', async (c) => {
+        const sha = c.req.param('sha');
+        if (!isCommitSha(sha))
+            return notFound();
+        const store = await storeOf(deps, sha);
+        if (store instanceof Response)
+            return store;
+        return eventStream(commitEvents(store, sha, {
+            clock: deps.clock,
+            timers: deps.timers,
+            have: haveSources(c.req.query('have')),
+            pollMs: REPORTS_POLL_MS,
+            tailMs: REPORTS_TAIL_MS,
+        }));
+    })
+        .get('/:sha/sources', sourcesRoute(deps))
+        .get('/:sha/frame.css', async (c) => {
+        const sha = c.req.param('sha');
+        if (!isCommitSha(sha))
+            return notFound();
+        const store = await storeOf(deps, sha);
+        if (store instanceof Response)
+            return store;
+        const css = await readFrameCss(store, sha);
+        if (css === null)
+            return notFound();
+        return new Response(css.body, {
+            status: 200,
+            headers: {
+                'content-type': css.contentType,
+                ...NO_STORE,
+            },
+        });
+    })
+        .get('/:sha/tests/:source/:testId', testRoute(deps))
+        .get('/:sha/tests/:source/:testId/files/*', fileRoute(deps))
+        .get('/:sha/tests/:source/:testId/events', testEventsRoute(deps));
+}

package/dist/reports/src/reports-store.d.ts

@@ -0,0 +1,11 @@
+import type { SourceRecord } from './protocol.js';
+import type { ObjectStore } from './object-store.js';
+export type ReportsStores = {
+    readonly store: ObjectStore | null;
+    readonly localStore?: ObjectStore;
+};
+/** Collected local runs own their timelines; a remote outage cannot hide them. */
+export declare function reportsStoreForCommit(deps: ReportsStores, sha: string): Promise<ObjectStore | null>;
+export declare function reportsStoreForSource(deps: ReportsStores, sha: string, source: string): Promise<ObjectStore | null>;
+/** Merge independent producers; local output overrides only its own source. */
+export declare function reportsSources(deps: ReportsStores, sha: string): Promise<readonly SourceRecord[]>;

package/dist/reports/src/reports-store.js

@@ -0,0 +1,28 @@
+import { listSourceRecords, readCommit, } from './read.js';
+import { readStoredSource } from './source-content.js';
+/** Collected local runs own their timelines; a remote outage cannot hide them. */
+export async function reportsStoreForCommit(deps, sha) {
+    if (deps.localStore && (await readCommit(deps.localStore, sha)) !== null)
+        return deps.localStore;
+    return deps.store;
+}
+export async function reportsStoreForSource(deps, sha, source) {
+    if (deps.localStore &&
+        (await readStoredSource(deps.localStore, sha, source)) !== null)
+        return deps.localStore;
+    return deps.store;
+}
+/** Merge independent producers; local output overrides only its own source. */
+export async function reportsSources(deps, sha) {
+    const stores = [deps.store, deps.localStore].filter((store) => store != null);
+    const results = await Promise.allSettled(stores.map((store) => listSourceRecords(store, sha)));
+    const sources = new Map();
+    for (const result of results)
+        if (result.status === 'fulfilled')
+            for (const source of result.value)
+                sources.set(source.source, source);
+    const failure = results.find((result) => result.status === 'rejected');
+    if (sources.size === 0 && failure?.status === 'rejected')
+        throw failure.reason;
+    return [...sources.values()];
+}

package/dist/reports/src/resilient-cache.d.ts

@@ -0,0 +1,3 @@
+import type { ReportCache } from './fetcher.js';
+/** Storage is an optimization. A denied or corrupt persistent cache cannot block reports. */
+export declare function resilientReportCache(cache: ReportCache): ReportCache;

package/dist/reports/src/resilient-cache.js

@@ -0,0 +1,33 @@
+import { memoryReportCache } from './fetcher.js';
+/** Storage is an optimization. A denied or corrupt persistent cache cannot block reports. */
+export function resilientReportCache(cache) {
+    const fallback = memoryReportCache();
+    return {
+        async get(key) {
+            try {
+                return (await cache.get(key)) ?? (await fallback.get(key));
+            }
+            catch {
+                return fallback.get(key);
+            }
+        },
+        async set(key, value) {
+            await fallback.set(key, value);
+            try {
+                await cache.set(key, value);
+            }
+            catch {
+                /* memory remains usable */
+            }
+        },
+        async remove(key) {
+            await fallback.remove(key);
+            try {
+                await cache.remove(key);
+            }
+            catch {
+                /* optional persistent storage */
+            }
+        },
+    };
+}

package/dist/reports/src/retention.d.ts

@@ -0,0 +1,9 @@
+import type { ObjectStore } from './object-store.js';
+import type { CommitRecord } from './protocol.js';
+export type ReportRetentionPlan = {
+    readonly retained: readonly CommitRecord[];
+    readonly deleteKeys: readonly string[];
+};
+/** Report evidence outlives branch heads. Automatic cleanup never discards a layer. */
+export declare function planReportRetention(store: ObjectStore): Promise<ReportRetentionPlan>;
+export declare function pruneReports(store: ObjectStore): Promise<ReportRetentionPlan>;

package/dist/reports/src/retention.js

@@ -0,0 +1,16 @@
+import { readCommit } from './read.js';
+/** Report evidence outlives branch heads. Automatic cleanup never discards a layer. */
+export async function planReportRetention(store) {
+    const keys = await store.listKeys('index/');
+    const shas = new Set(keys.flatMap(key => /([0-9a-f]{40})\.json$/.exec(key)?.[1] ?? []));
+    const retained = [];
+    for (const sha of shas) {
+        const commit = await readCommit(store, sha);
+        if (commit)
+            retained.push(commit);
+    }
+    return { retained, deleteKeys: [] };
+}
+export async function pruneReports(store) {
+    return planReportRetention(store);
+}

package/dist/reports/src/scenario.d.ts

@@ -0,0 +1,15 @@
+import type { ReportStep } from './report-types.js';
+export type ScenarioLine = {
+    readonly step: ReportStep;
+    /** Nested harness steps: the actions taken while this line ran. */
+    readonly actions: readonly ReportStep[];
+};
+export declare function isGherkinStep(step: ReportStep): boolean;
+/** Title with the keyword removed, so the script can show the keyword once. */
+export declare function gherkinText(step: ReportStep): string;
+/**
+ * Top-level Gherkin lines and the actions nested under each. Null when the
+ * run is not a scenario (a model check, a property), so the step tree is
+ * the action log instead.
+ */
+export declare function scenarioScript(steps: readonly ReportStep[]): readonly ScenarioLine[] | null;

package/dist/reports/src/scenario.js

@@ -0,0 +1,35 @@
+const GHERKIN = new Set(['given', 'when', 'then', 'and', 'but', '*']);
+export function isGherkinStep(step) {
+    return GHERKIN.has(step.kind.trim().toLowerCase());
+}
+/** Title with the keyword removed, so the script can show the keyword once. */
+export function gherkinText(step) {
+    const kind = step.kind.trim();
+    const title = step.title.trim();
+    if (title.toLowerCase().startsWith(kind.toLowerCase())) {
+        return title.slice(kind.length).trim();
+    }
+    return title;
+}
+function walkActions(steps, out) {
+    for (const step of steps) {
+        out.push(step);
+        if (step.steps.length > 0)
+            walkActions(step.steps, out);
+    }
+}
+/**
+ * Top-level Gherkin lines and the actions nested under each. Null when the
+ * run is not a scenario (a model check, a property), so the step tree is
+ * the action log instead.
+ */
+export function scenarioScript(steps) {
+    const lines = steps.filter(isGherkinStep);
+    if (lines.length === 0)
+        return null;
+    return lines.map((step) => {
+        const actions = [];
+        walkActions(step.steps, actions);
+        return { step, actions };
+    });
+}

package/dist/reports/src/snapshot-bundle.d.ts

@@ -0,0 +1,18 @@
+import type { ObjectStore } from './object-store.js';
+export declare function publishSnapshotBundle(args: {
+    readonly local: ObjectStore;
+    readonly remote: ObjectStore;
+    readonly localPrefix: string;
+    readonly remotePrefix: string;
+    readonly files: readonly string[];
+}): Promise<void>;
+export declare function readBundledSnapshot(store: ObjectStore, prefix: string, file: string): Promise<{
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+} | null>;
+/** A streamed test reads each compressed chunk once even when it contains many frames. */
+export declare function readBundledSnapshots(store: ObjectStore, prefix: string, files: ReadonlySet<string>): AsyncGenerator<{
+    bytes: Uint8Array;
+    contentType: string;
+    file: string;
+}, void, unknown>;