@crvouga/atlas 0.0.0-stage → 0.2.0

package/dist/reports/src/phone.js

@@ -0,0 +1,18 @@
+export const PHONE_W = 390;
+export const PHONE_H = 844;
+const SHELL_LINK_RE = /<link\b[^>]*href=["'][^"']*snapshot-shell\.css["'][^>]*>\s*/gi;
+const SCRIPT_RE = /<script\b[^>]*>[\s\S]*?<\/script>/gi;
+export function zoomScale(mode, wrapW, wrapH) {
+    if (mode === '50')
+        return 0.5;
+    if (mode === '75')
+        return 0.75;
+    if (mode === '100')
+        return 1;
+    const s = Math.min(1, (wrapW - 8) / PHONE_W, (wrapH - 8) / PHONE_H);
+    return !Number.isFinite(s) || s <= 0 ? 0.4 : s;
+}
+/** Drop scripts and the external shell stylesheet (frameCss replaces it). */
+export function cleanSnapshotHtml(html) {
+    return html.replace(SCRIPT_RE, '').replace(SHELL_LINK_RE, '');
+}

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

@@ -0,0 +1,78 @@
+/**
+ * What the shared reports store holds and what a reports API streams from it.
+ * Types only plus a Server-Sent Events codec: safe in a Worker, a CLI and a
+ * browser alike.
+ */
+import type { HtmlReportBlob } from './recording-bundle.js';
+import type { ReportTestStatus, RunReport, RunReportMeta } from './report-types.js';
+import type { ReportPartOutput, WorkspaceVersion } from './explorer-types.js';
+/** `running` until the run that publishes the commit closes it. */
+export type CommitState = 'running' | 'complete';
+/** `commits/<sha>/commit.json`: one published run of every spec of a commit. */
+export type CommitRecord = {
+    readonly sha: string;
+    readonly branch: string;
+    readonly runUrl: string | null;
+    readonly state: CommitState;
+    readonly startedAtMs: number;
+    readonly endedAtMs: number | null;
+    /** Worst status over every source; null while running. */
+    readonly status: ReportTestStatus | null;
+};
+/** `commits/<sha>/sources/<source>.json`: one package bucket's tests. */
+export type SourceRecord = {
+    /** Producer measurements travel with reusable source content. */
+    readonly evidence?: readonly ReportPartOutput[];
+    readonly source: string;
+    /** Repo-relative package dir (`libs/chess`). */
+    readonly packageDir: string;
+    /** The bucket under the package's report dir (`part-2`, `all`). */
+    readonly bucket: string;
+    readonly status: ReportTestStatus;
+    readonly updatedAtMs: number;
+    /** Each test's meta, test-runner outcomes already applied. */
+    readonly tests: readonly RunReportMeta[];
+};
+export type CommitPage = {
+    readonly commits: readonly CommitRecord[];
+    /** Pass back as `?cursor=` for the next, older page; null on the last. */
+    readonly cursor: string | null;
+    readonly workspace?: WorkspaceVersion;
+    readonly notice?: string;
+    readonly evidenceVersions?: readonly string[];
+};
+/** `GET …/:sha/events`: the commit, then each source as it is read. */
+export type CommitEvent = {
+    readonly type: 'commit';
+    readonly commit: CommitRecord | null;
+} | {
+    readonly type: 'source';
+    readonly source: SourceRecord;
+} | {
+    readonly type: 'end';
+    readonly state: CommitState | 'missing';
+};
+/** `GET …/:sha/tests/:source/:testId/events`: a test, then its frame files. */
+export type TestEvent = {
+    readonly type: 'report';
+    readonly report: RunReport;
+} | {
+    readonly type: 'blob';
+    readonly file: string;
+    readonly blob: HtmlReportBlob;
+} | {
+    readonly type: 'end';
+    readonly found: boolean;
+};
+export declare const EVENT_STREAM_CONTENT_TYPE = "text/event-stream; charset=utf-8";
+/** One SSE message: `event:` is the event's `type`, `data:` its JSON. */
+export declare function encodeSseEvent(event: CommitEvent | TestEvent): string;
+/**
+ * Incremental SSE decoder: feed it text as it arrives, get back each
+ * complete message's parsed `data`. Only `data:` lines matter here (every
+ * event repeats its type in its JSON); comments and other fields are skipped.
+ */
+export declare class SseDecoder<T> {
+    #private;
+    push(chunk: string): T[];
+}

package/dist/reports/src/protocol.js

@@ -0,0 +1,36 @@
+/**
+ * What the shared reports store holds and what a reports API streams from it.
+ * Types only plus a Server-Sent Events codec: safe in a Worker, a CLI and a
+ * browser alike.
+ */
+export const EVENT_STREAM_CONTENT_TYPE = 'text/event-stream; charset=utf-8';
+/** One SSE message: `event:` is the event's `type`, `data:` its JSON. */
+export function encodeSseEvent(event) {
+    return `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+/**
+ * Incremental SSE decoder: feed it text as it arrives, get back each
+ * complete message's parsed `data`. Only `data:` lines matter here (every
+ * event repeats its type in its JSON); comments and other fields are skipped.
+ */
+export class SseDecoder {
+    #buffer = '';
+    push(chunk) {
+        this.#buffer += chunk.replace(/\r\n?/g, '\n');
+        const out = [];
+        for (;;) {
+            const end = this.#buffer.indexOf('\n\n');
+            if (end < 0)
+                return out;
+            const message = this.#buffer.slice(0, end);
+            this.#buffer = this.#buffer.slice(end + 2);
+            const data = message
+                .split('\n')
+                .filter((line) => line.startsWith('data:'))
+                .map((line) => line.slice(line.startsWith('data: ') ? 6 : 5))
+                .join('\n');
+            if (data.length > 0)
+                out.push(JSON.parse(data));
+        }
+    }
+}

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

@@ -0,0 +1,4 @@
+/** Attempt-local commit records; immutable successful content remains shared. */
+import type { ObjectStore } from './object-store.js';
+export declare function publicationStore(store: ObjectStore, publicationId: string): ObjectStore;
+export declare function reportStore(store: ObjectStore, sha: string): Promise<ObjectStore>;

package/dist/reports/src/publication.js

@@ -0,0 +1,35 @@
+/** Attempt-local commit records; immutable successful content remains shared. */
+import { readUtf8 } from './object-io.js';
+import { ObjectStoreWithPrefix } from './store-prefix.js';
+import { commitKey } from './keys.js';
+export function publicationStore(store, publicationId) {
+    if (!/^[a-zA-Z0-9._:-]+$/.test(publicationId) ||
+        publicationId === '.' ||
+        publicationId === '..')
+        throw new Error('Invalid report publication id');
+    const root = `attempts/${publicationId}/`;
+    const keyOf = (key) => key.startsWith('commits/') && !/^commits\/[^/]+\/(?:inventory\.json$|specs\/)/.test(key) ? root + key : key;
+    const scoped = {
+        get: (key) => store.get(keyOf(key)),
+        head: (key) => store.head(keyOf(key)),
+        put: (key, bytes, type) => store.put(keyOf(key), bytes, type),
+        delete: (key) => store.delete(keyOf(key)),
+        deleteMany: (keys) => store.deleteMany(keys.map(keyOf)),
+        getUri: (key) => store.getUri(keyOf(key)),
+        async listKeys(prefix = '') {
+            const keys = await store.listKeys(keyOf(prefix));
+            return keys.map((key) => key.startsWith(root) ? key.slice(root.length) : key);
+        },
+        withPrefix: (prefix) => new ObjectStoreWithPrefix(scoped, prefix),
+    };
+    return scoped;
+}
+export async function reportStore(store, sha) {
+    const text = await readUtf8(store, commitKey(sha));
+    if (text === null)
+        return store;
+    const stored = JSON.parse(text);
+    return 'publicationId' in stored
+        ? publicationStore(store, stored.publicationId)
+        : store;
+}

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

@@ -0,0 +1,52 @@
+import type { LayerParameters } from './layer-types.js';
+import type { ReportTestStatus } from './report-types.js';
+import type { ObjectStore } from './object-store.js';
+import type { CommitRecord, SourceRecord } from './protocol.js';
+import type { SourceIdentity } from './source-content.js';
+/** The run id every spec suite writes its bucket under. */
+export declare const SPEC_RUN_ID = "latest";
+export type OpenCommitArgs = {
+    readonly sha: string;
+    readonly branch: string;
+    readonly runUrl: string | null;
+    readonly startedAtMs: number;
+    /** Stylesheet the commit's HTML snapshots render with. */
+    readonly frameCss: string;
+    /** Concurrent CI attempts own independent commit-local files. */
+    readonly publicationId?: string;
+};
+/**
+ * Mark a commit's run as started and list it (newest first). Its snapshot
+ * stylesheet goes up first, so a test is viewable the moment it lands.
+ */
+export declare function openCommit(store: ObjectStore, args: OpenCommitArgs): Promise<CommitRecord>;
+export type PublishSourceArgs = {
+    /** Execution completion time, separate from a virtual timeline clock. */
+    readonly recordedAtMs?: number;
+    readonly freshness?: 'unknown' | 'modified';
+    readonly parameters?: LayerParameters;
+    readonly sha: string;
+    readonly packageDir: string;
+    readonly bucket: string;
+    /** The package's local report bucket (`.cache/harness-report/<bucket>`). */
+    readonly local: ObjectStore;
+    readonly runId?: string;
+    /** Only a passing execution is reusable under its exact task hash. */
+    readonly identity?: SourceIdentity;
+    readonly status?: ReportTestStatus;
+};
+/**
+ * Copy one package bucket into the store: every test (runner outcomes
+ * applied) and its frame files, then the source record, last, so a reader
+ * that sees the record can read every test it names. Null when the bucket
+ * recorded no test.
+ */
+export declare function publishSource(store: ObjectStore, args: PublishSourceArgs): Promise<SourceRecord | null>;
+export type CloseCommitArgs = {
+    readonly sha: string;
+    readonly endedAtMs: number;
+    readonly publicationId?: string;
+    readonly status?: ReportTestStatus;
+};
+/** Mark a commit's run complete, with the worst status of its sources. */
+export declare function closeCommit(store: ObjectStore, args: CloseCommitArgs): Promise<CommitRecord>;

package/dist/reports/src/publish.js

@@ -0,0 +1,189 @@
+import { archiveSourceLayer } from './layer-source.js';
+import { performancePart } from './performance-part.js';
+import { applyJunitOutcomes, parseJunit, } from './junit.js';
+import { testFrameKey, testPrefix, testReportKey, } from './recording-keys.js';
+import { suiteStatus } from './status.js';
+import { readUtf8, writeUtf8 } from './object-io.js';
+import { bundleIndexKey, writeBundle } from './bundle.js';
+import { eachLimited } from './completion-order.js';
+import { commitIndexKey, commitKey, frameCssKey, sourceId, sourceKey, sourceOfKey, sourcesPrefix, } from './keys.js';
+import { publicationStore } from './publication.js';
+import { readCommit } from './read.js';
+import { validatePart } from './report-parts.js';
+import { publishSnapshotBundle } from './snapshot-bundle.js';
+import { attachSource, readStoredSource, sourceContentPrefix, } from './source-content.js';
+import { sourceEntries } from './source-entries.js';
+/** The run id every spec suite writes its bucket under. */
+export const SPEC_RUN_ID = 'latest';
+/** Parallel uploads per source. */
+const WRITE_WIDTH = 32;
+const JSON_TYPE = 'application/json; charset=utf-8';
+/**
+ * Mark a commit's run as started and list it (newest first). Its snapshot
+ * stylesheet goes up first, so a test is viewable the moment it lands.
+ */
+export async function openCommit(store, args) {
+    const { frameCss, publicationId, ...fields } = args;
+    const target = publicationId === undefined
+        ? store
+        : publicationStore(store, publicationId);
+    await writeUtf8(target, frameCssKey(args.sha), frameCss, 'text/css; charset=utf-8');
+    const commit = {
+        ...fields,
+        state: 'running',
+        endedAtMs: null,
+        status: null,
+    };
+    await writeUtf8(target, commitKey(args.sha), JSON.stringify(commit), JSON_TYPE);
+    await writeUtf8(store, commitIndexKey(args.sha, args.startedAtMs), JSON.stringify({ sha: args.sha }), JSON_TYPE);
+    if (publicationId !== undefined)
+        await writeUtf8(store, commitKey(args.sha), JSON.stringify({ publicationId }), JSON_TYPE);
+    return commit;
+}
+/** `runs/<runId>/tests/<testId>/report.json` → `<testId>`, else null. */
+function reportTestId(runId, key) {
+    const head = testPrefix(runId, '');
+    const tail = '/report.json';
+    if (!key.startsWith(head) || !key.endsWith(tail))
+        return null;
+    const testId = key.slice(head.length, key.length - tail.length);
+    return testId.length > 0 && !testId.includes('/') ? testId : null;
+}
+async function readTests(bucket, runId) {
+    const ids = (await bucket.listKeys(testPrefix(runId, '')))
+        .map((key) => reportTestId(runId, key))
+        .filter((id) => id !== null);
+    const tests = [];
+    for (const id of ids) {
+        const text = await readUtf8(bucket, testReportKey(runId, id));
+        if (text === null)
+            continue;
+        tests.push({ report: JSON.parse(text), blobs: {} });
+    }
+    const junit = await readUtf8(bucket, 'junit.xml');
+    if (junit === null)
+        return tests;
+    return [
+        ...applyJunitOutcomes({ runId, status: 'passed', updatedAtMs: 0, tests }, parseJunit(junit)).tests,
+    ];
+}
+function frameFiles(steps, out) {
+    for (const step of steps) {
+        for (const frame of step.frames) {
+            for (const blob of frame.snapshots)
+                out.add(blob.file);
+        }
+        frameFiles(step.steps, out);
+    }
+}
+async function publishSnapshots(store, args, tests, contentPrefix) {
+    const runId = args.runId ?? SPEC_RUN_ID;
+    await eachLimited(tests, 8, async ({ report }) => {
+        const files = new Set();
+        frameFiles(report.steps, files);
+        await publishSnapshotBundle({
+            local: args.local,
+            remote: store,
+            localPrefix: testFrameKey(runId, report.meta.testId, ''),
+            remotePrefix: `${contentPrefix}${report.meta.testId}/`,
+            files: [...files],
+        });
+    });
+}
+/**
+ * Copy one package bucket into the store: every test (runner outcomes
+ * applied) and its frame files, then the source record, last, so a reader
+ * that sees the record can read every test it names. Null when the bucket
+ * recorded no test.
+ */
+export async function publishSource(store, args) {
+    const runId = args.runId ?? SPEC_RUN_ID;
+    const source = sourceId(args.packageDir, args.bucket);
+    const tests = await readTests(args.local, runId);
+    if (tests.length === 0 &&
+        args.identity === undefined &&
+        args.status === undefined)
+        return null;
+    const metas = tests
+        .map((t) => t.report.meta)
+        .sort((a, b) => (a.testId < b.testId ? -1 : a.testId > b.testId ? 1 : 0));
+    const status = args.status === 'failed' ? 'failed' : suiteStatus(metas);
+    const contentPrefix = args.identity !== undefined && status === 'passed'
+        ? sourceContentPrefix(args.identity, source)
+        : null;
+    let bundle;
+    if (contentPrefix === null) {
+        bundle = await writeBundle(store, sourceEntries(args, source, tests, runId), 'layers/blobs/');
+        await writeUtf8(store, bundleIndexKey(args.sha, source), JSON.stringify(bundle), JSON_TYPE);
+    }
+    else {
+        await publishSnapshots(store, args, tests, contentPrefix);
+        await eachLimited(tests, WRITE_WIDTH, async ({ report }) => {
+            await writeUtf8(store, `${contentPrefix}${report.meta.testId}/report.json`, JSON.stringify(report), JSON_TYPE);
+        });
+    }
+    const record = {
+        source,
+        packageDir: args.packageDir,
+        bucket: args.bucket,
+        status,
+        updatedAtMs: args.recordedAtMs ?? metas.reduce((latest, meta) => Math.max(latest, meta.endedAtMs), 0),
+        tests: metas,
+        ...(await sourceEvidence(args.local, args.sha, source, tests)),
+    };
+    if (contentPrefix !== null) {
+        await writeUtf8(store, `${contentPrefix}complete.json`, JSON.stringify(record), JSON_TYPE);
+        await attachSource(store, { sha: args.sha, record, contentPrefix });
+    }
+    else {
+        await writeUtf8(store, sourceKey(args.sha, source), JSON.stringify(record), JSON_TYPE);
+    }
+    await archiveSourceLayer(store, args, record, tests, bundle);
+    return record;
+}
+async function sourceEvidence(local, sha, source, tests) {
+    const raw = await readUtf8(local, 'part.json');
+    const evidence = raw === null ? [] : [JSON.parse(raw)];
+    if (!evidence.some((part) => part.kind === 'ui-quality' || part.kind === 'performance')) {
+        const { kind, title, checks } = performancePart({
+            sha,
+            recordedAtMs: 0,
+            allowanceMs: 50,
+            reports: tests.map((test) => test.report),
+        });
+        evidence.push({ kind, title, checks });
+    }
+    for (const part of evidence)
+        validatePart({ ...part, sha, id: source, recordedAtMs: 0 });
+    return { evidence };
+}
+/** Mark a commit's run complete, with the worst status of its sources. */
+export async function closeCommit(store, args) {
+    if (args.publicationId !== undefined)
+        store = publicationStore(store, args.publicationId);
+    const open = await readCommit(store, args.sha);
+    if (open === null) {
+        throw new Error(`no open report for ${args.sha}; openCommit runs first`);
+    }
+    const sources = (await store.listKeys(sourcesPrefix(args.sha)))
+        .map((key) => sourceOfKey(args.sha, key))
+        .filter((s) => s !== null);
+    const statuses = [];
+    for (const s of sources) {
+        const stored = await readStoredSource(store, args.sha, s);
+        if (stored !== null)
+            statuses.push(stored.record);
+    }
+    const closed = {
+        ...open,
+        state: 'complete',
+        endedAtMs: args.endedAtMs,
+        status: args.status === 'failed'
+            ? 'failed'
+            : statuses.length === 0
+                ? 'skipped'
+                : suiteStatus(statuses),
+    };
+    await writeUtf8(store, commitKey(args.sha), JSON.stringify(closed), JSON_TYPE);
+    return closed;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Read side of the shared reports store: what a reports API serves. Pure over
+ * an injected {@link ObjectStore}, {@link Clock} and {@link Timers}; nothing
+ * here imports a runtime or an HTTP framework.
+ */
+import type { Clock, Timers } from './clock.js';
+import type { RunReport } from './report-types.js';
+import type { ObjectStore, StoredObject } from './object-store.js';
+import type { CommitEvent, CommitPage, CommitRecord, SourceRecord, TestEvent } from './protocol.js';
+export declare function readCommit(store: ObjectStore, sha: string): Promise<CommitRecord | null>;
+export declare function readFrameCss(store: ObjectStore, sha: string): Promise<StoredObject | null>;
+/**
+ * Newest commits first, `limit` per page. A commit published twice (a rerun)
+ * has two index entries; only the newer one is ever listed, on any page.
+ */
+export declare function listCommits(store: ObjectStore, options: {
+    readonly limit: number;
+    readonly cursor: string | null;
+}): Promise<CommitPage>;
+export type CommitEventsOptions = {
+    readonly clock: Clock;
+    readonly timers: Timers;
+    /** Sources the client already holds (a reconnect): never sent again. */
+    readonly have?: ReadonlySet<string>;
+    /** How often a running commit is re-listed for new sources. */
+    readonly pollMs: number;
+    /** A running commit's stream ends after this long; the client reconnects. */
+    readonly tailMs: number;
+};
+/**
+ * The commit, then every source in the order its read finishes. While the
+ * commit is running, its sources are re-listed every `pollMs` and each new
+ * one is sent as it lands, until the commit completes or `tailMs` passes.
+ * The state is read before each listing, so a listing after `complete` is
+ * the final one.
+ */
+export declare function commitEvents(store: ObjectStore, sha: string, options: CommitEventsOptions): AsyncGenerator<CommitEvent>;
+/** One test's timeline, without its frame files. */
+export declare function readTestReport(store: ObjectStore, args: {
+    readonly sha: string;
+    readonly source: string;
+    readonly testId: string;
+}): Promise<RunReport | null>;
+export type FrameBody = {
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+};
+/** One frame file's bytes, or null when the test never wrote it. */
+export declare function readFrameBody(store: ObjectStore, args: {
+    readonly sha: string;
+    readonly source: string;
+    readonly testId: string;
+    readonly file: string;
+}): Promise<FrameBody | null>;
+/** Every source record of a commit, in the order each read finishes. */
+export declare function listSourceRecords(store: ObjectStore, sha: string): Promise<SourceRecord[]>;
+/** A test's report, then each of its frame files as its read finishes. */
+export declare function testEvents(store: ObjectStore, args: {
+    readonly sha: string;
+    readonly source: string;
+    readonly testId: string;
+}): AsyncGenerator<TestEvent>;