@crvouga/atlas 0.3.0 → 0.5.0

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

@@ -0,0 +1,156 @@
+/**
+ * @module The report gate
+ *
+ * Reduces a combined report to a pass or fail with reasons (`reportStatus`) and renders that result as text or
+ * markdown. The JSON of `ReportStatus` is a stable contract (`schemaVersion` 1); the text and markdown are for people
+ * and are not. The gate fails closed: no checks, a failed or still-running check, an unreadable layer or backend
+ * (a notice), a missing required environment, or (when asked) a spec with no result each make it fail.
+ *
+ * @see docs/report-contract.md#statuses-and-the-gate
+ */
+import { REPORT_STATUS_SCHEMA_VERSION } from '../../schema/src/layer.js';
+import { countResults } from './compose.js';
+import { normalizeEnvironment } from './layer-axes.js';
+import { isDiagnosticKind } from './layer-merge.js';
+/** Total string order by code unit. */
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * The gate. A report passes only when it has checks, none failed, none is still running, every
+ * layer and backend could be read, and every required environment is present. Unknown never passes.
+ *
+ * Returns a `ReportStatus` (schemaVersion 1): `ok` is true exactly when `reasons` is empty. Reasons name, in order: no
+ * checks (or none completed), failed checks, running checks, specs without results (only with `requireAllSpecs`),
+ * each required environment with no checks (the name is normalised, so `iOS` means `ios`), then every notice of the
+ * report (an unreadable layer or backend). `failing` lists each failed or running winner, in a fixed order that does
+ * not depend on read order; diagnostic `performance` checks are left out unless nothing else was recorded.
+ *
+ * @example
+ * const status = reportStatus(await combineBackends(backends), { requireEnvironments: ['ios'] });
+ * if (!status.ok) throw new Error(status.reasons.join('\n'));
+ *
+ * @see docs/report-contract.md#atlas-report-status
+ */
+export function reportStatus(report, options = {}) {
+    const results = [...report.combined.specs.flatMap(entry => entry.results), ...report.combined.unassigned];
+    const outcomes = results.some(result => !isDiagnosticKind(result.row.kind)) ? results.filter(result => !isDiagnosticKind(result.row.kind)) : results;
+    const failing = outcomes
+        .filter(result => result.row.status === 'failed' || result.row.status === 'running')
+        .map(result => ({
+        spec: result.row.specPath,
+        check: result.row.id,
+        title: result.row.title,
+        status: result.row.status,
+        environment: result.layer.environment,
+        producer: result.layer.producer,
+        branch: result.layer.branch,
+        sha: result.layer.sha,
+        layer: result.layer.id,
+        backend: result.layer.backend,
+        runUrl: result.layer.runUrl,
+        detail: result.row.detail
+    }))
+        // Total, so the output never depends on the order layers were read in.
+        .sort((a, b) => compare(a.spec ?? '', b.spec ?? '') || compare(a.check, b.check) || compare(a.environment ?? '', b.environment ?? '') || compare(a.producer, b.producer) || compare(a.layer, b.layer) || compare(a.backend, b.backend));
+    const reasons = [];
+    const { checks, byEnvironment } = report.summary;
+    if (checks.total === 0)
+        reasons.push('No checks were found in any layer');
+    else if (checks.passed + checks.failed === 0 && checks.running === 0)
+        reasons.push('No check has completed: everything was skipped or not run');
+    if (checks.failed)
+        reasons.push(`${checks.failed} check${checks.failed === 1 ? '' : 's'} failed`);
+    if (checks.running)
+        reasons.push(`${checks.running} check${checks.running === 1 ? ' is' : 's are'} still running`);
+    const missing = report.summary.specsWithoutEvidence;
+    if (options.requireAllSpecs && missing.length)
+        reasons.push(`${missing.length} spec${missing.length === 1 ? ' has' : 's have'} no results: ${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', …' : ''}`);
+    for (const required of options.requireEnvironments ?? []) {
+        // Layers carry normalized environments (`iOS` is `ios`), so a requirement is normalized the same way.
+        const environment = normalizeEnvironment(required) ?? required;
+        if (!byEnvironment[environment]?.total)
+            reasons.push(`No checks on required environment "${required}"`);
+    }
+    reasons.push(...report.notices);
+    return {
+        schemaVersion: REPORT_STATUS_SCHEMA_VERSION,
+        ok: reasons.length === 0,
+        reasons,
+        checks,
+        byEnvironment: { ...byEnvironment },
+        layers: report.layers.length,
+        backends: report.backends.map(({ id, label, available }) => ({ id, label, available })),
+        notices: [...report.notices],
+        specsWithoutEvidence: [...missing],
+        specs: [
+            ...report.combined.specs.map(entry => specOutcome(entry.spec.path, entry.spec.title, entry.spec.kind, entry.results)),
+            ...(report.combined.unassigned.length ? [specOutcome(null, 'No spec', 'unassigned', report.combined.unassigned)] : [])
+        ],
+        failing
+    };
+}
+/** `spec › check`, unless the check's id already starts with its spec. */
+const label = (item) => (item.spec && !item.check.startsWith(item.spec) ? `${item.spec} › ${item.check}` : item.check);
+function specOutcome(path, title, kind, results) {
+    const environments = new Map();
+    for (const result of results) {
+        const key = result.layer.environment ?? 'unspecified';
+        const group = environments.get(key);
+        if (group)
+            group.push(result);
+        else
+            environments.set(key, [result]);
+    }
+    return {
+        path, title, kind,
+        checks: countResults(results),
+        byEnvironment: Object.fromEntries([...environments].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([key, value]) => [key, countResults(value)]))
+    };
+}
+const row = (counts) => `${counts.passed} passed, ${counts.failed} failed, ${counts.running} running, ${counts['not-run']} not run`;
+/**
+ * Renders a status as plain text for a terminal: a `PASS`/`FAIL` line with totals, one line per environment, each
+ * failing or running check with where it ran and the first line of its detail, notices, reasons and specs with no
+ * results. Ends with a newline. For people: the layout is not a contract; parse `--format json` instead.
+ */
+export function formatStatusText(status) {
+    const lines = [`${status.ok ? 'PASS' : 'FAIL'}  ${row(status.checks)} — ${status.layers} layer${status.layers === 1 ? '' : 's'} from ${status.backends.length} backend${status.backends.length === 1 ? '' : 's'}`];
+    for (const [environment, counts] of Object.entries(status.byEnvironment))
+        lines.push(`  ${environment.padEnd(14)} ${row(counts)}`);
+    for (const item of status.failing) {
+        const where = [item.environment, item.branch, item.sha?.slice(0, 7)].filter(Boolean).join(' · ');
+        lines.push(`✗ ${item.status === 'running' ? '[running] ' : ''}${label(item)}${where ? `  (${where})` : ''}${item.detail ? `\n    ${item.detail.split('\n')[0]}` : ''}`);
+    }
+    for (const notice of status.notices)
+        lines.push(`! ${notice}`);
+    for (const reason of status.reasons)
+        if (!status.notices.includes(reason))
+            lines.push(`→ ${reason}`);
+    if (status.specsWithoutEvidence.length && !status.reasons.some(reason => reason.includes('no results')))
+        lines.push(`· ${status.specsWithoutEvidence.length} spec${status.specsWithoutEvidence.length === 1 ? '' : 's'} with no results yet: ${status.specsWithoutEvidence.slice(0, 5).join(', ')}${status.specsWithoutEvidence.length > 5 ? ', …' : ''}`);
+    return `${lines.join('\n')}\n`;
+}
+const cell = (value) => value.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+/**
+ * Renders a status as GitHub-flavoured markdown for a pull request comment or `$GITHUB_STEP_SUMMARY`: a heading with
+ * totals, a table per environment, a table of failing checks (`|` and newlines in cells are escaped) and the reasons.
+ * Ends with a newline. For people: the layout is not a contract.
+ */
+export function formatStatusMarkdown(status) {
+    const lines = [`### ${status.ok ? '✅' : '❌'} Atlas report: ${row(status.checks)}`, '', `${status.layers} layer${status.layers === 1 ? '' : 's'} from ${status.backends.length} backend${status.backends.length === 1 ? '' : 's'}.`, ''];
+    const environments = Object.entries(status.byEnvironment);
+    if (environments.length) {
+        lines.push('| Environment | Passed | Failed | Running | Not run |', '| --- | ---: | ---: | ---: | ---: |');
+        for (const [environment, counts] of environments)
+            lines.push(`| ${cell(environment)} | ${counts.passed} | ${counts.failed} | ${counts.running} | ${counts['not-run']} |`);
+        lines.push('');
+    }
+    if (status.failing.length) {
+        lines.push('| Check | Environment | Branch | Detail |', '| --- | --- | --- | --- |');
+        for (const item of status.failing)
+            lines.push(`| ${cell(label(item))} | ${cell(item.environment ?? '')} | ${cell(item.branch ?? '')} | ${cell(item.status === 'running' ? 'still running' : item.detail.split('\n')[0] ?? '')} |`);
+        lines.push('');
+    }
+    for (const reason of status.reasons)
+        lines.push(`- ${reason}`);
+    return `${lines.join('\n')}\n`;
+}

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

@@ -1,19 +1,38 @@
+/**
+ * @module Recorded test timeline types
+ *
+ * The shapes of a recorded test run as the harness persists it and the viewer renders it: a timeline of steps, each
+ * with frames (captured snapshots), plus per-run metadata, the suite and run indexes, and the options of a recording.
+ * All times are epoch milliseconds unless a name says otherwise. Mostly types; the few functions are small id helpers
+ * that keep ids safe to use as key segments.
+ */
 import type { Clock } from './clock.js';
 import type { ObjectStore } from './object-store.js';
 /** Observed elapsed work, independent of the simulation clock. */
 export type ReportStepPerformance = {
+    /** Observed elapsed time of the step, in milliseconds. */
     readonly executionMs: number;
+    /** Time attributed to the step's own work, nested steps counted once (see `performanceHotspots`), in milliseconds. */
     readonly selfMs: number;
+    /** Time spent capturing snapshots for the step, in milliseconds. */
     readonly snapshotMs: number;
 };
+/** Timing totals of a whole run. */
 export type ReportPerformanceSummary = {
+    /** Total observed elapsed work of the run, in milliseconds. */
     readonly executionMs: number;
+    /** Part of that spent capturing snapshots, in milliseconds. */
     readonly snapshotMs: number;
+    /** How many steps had a measurement. */
     readonly measuredSteps: number;
+    /** How many measured steps were over `slowStepMs`. */
     readonly slowSteps: number;
+    /** The allowance, in milliseconds, a step's own time is judged against. */
     readonly slowStepMs: number;
 };
+/** How to measure elapsed work while recording. */
 export type ReportPerformanceOptions = {
+    /** The monotonic clock to measure with; separate from the simulation clock. */
     readonly clock: Clock;
     /** Diagnostic threshold, not a portable CPU or paint-time assertion. */
     readonly slowStepMs: number;
@@ -24,6 +43,7 @@ export type ReportPerformanceOptions = {
  * A runner may record any mix. The viewer treats a still, a video, and a timeline of frames as the same kind of evidence.
  */
 export type SnapshotMedia = 'json' | 'html' | 'png' | 'text' | 'bytes' | 'video';
+/** The outcome of one step. */
 export type ReportStepStatus = 'passed' | 'failed';
 /** Test outcome after the harness (e.g. the test runner) has weighed in. */
 export type ReportTestStatus = 'passed' | 'failed' | 'skipped';
@@ -32,17 +52,24 @@ export type ReportTestStatus = 'passed' | 'failed' | 'skipped';
  * Multi-actor UI maps become one entry per nodeId.
  */
 export type ReportSnapshotBlob = {
+    /** The blob's name as its snapshotter gave it. */
     readonly name: string;
+    /** How `file` is encoded. */
     readonly media: SnapshotMedia;
     /** Relative path under the test dir, e.g. `frames/f-00001.html.alice.html`. */
     readonly file: string;
+    /** Which client (actor) the blob is of, when the snapshot has one per client. */
     readonly nodeId?: string;
 };
 /** Discrete visual/state capture within a report step. */
 export type ReportFrame = {
+    /** The frame's ordinal as the recorder assigned it. */
     readonly index: number;
+    /** When it was captured, epoch milliseconds. */
     readonly capturedAtMs: number;
+    /** How long the capture took, in milliseconds. */
     readonly durationMs?: number;
+    /** The captured blobs, one per snapshotter (and per client). */
     readonly snapshots: readonly ReportSnapshotBlob[];
     /**
      * Gesture target, set only on the frame captured right before a UI step
@@ -56,7 +83,9 @@ export type ReportFrame = {
  * Viewers resolve the path against the snapshot DOM for real geometry.
  */
 export type ReportStepHit = {
+    /** Chain of `data-testid` values, each looked up inside the previous match. */
     readonly path: readonly string[];
+    /** Where in the target box the gesture landed, as fractions from 0 to 1 of its width and height. */
     readonly point?: {
         readonly xRatio: number;
         readonly yRatio: number;
@@ -67,43 +96,65 @@ export type ReportStepHit = {
  * holds the UI ops recorded while its action ran.
  */
 export type ReportStep = {
+    /** The step's ordinal as the recorder assigned it. */
     readonly index: number;
+    /** An open category of step. Gherkin keywords (`given`, `when`, `then`, `and`, `but`) mark scenario lines. */
     readonly kind: string;
+    /** Human title. */
     readonly title: string;
     readonly status: ReportStepStatus;
     readonly startedAtMs: number;
     readonly endedAtMs: number;
+    /** `endedAtMs - startedAtMs`, in milliseconds. */
     readonly durationMs: number;
+    /** Observed elapsed work, when measurement was on. */
     readonly performance?: ReportStepPerformance;
+    /** Which client (actor) took the step, in a multi-client run. */
     readonly actorId?: string;
+    /** The UI selector the step acted on. */
     readonly selector?: string;
     readonly detail?: string;
+    /** The action performed, when the step is an applied action. */
     readonly action?: string;
     readonly args?: readonly unknown[];
+    /** The failure message when `status` is `failed`. */
     readonly error?: string;
     readonly errorStack?: string;
+    /** Captures taken during the step. */
     readonly frames: readonly ReportFrame[];
+    /** Steps nested in this one. */
     readonly steps: readonly ReportStep[];
 };
+/** Metadata of one recorded test run. */
 export type RunReportMeta = {
+    /** The system under test the run exercised. */
     readonly system: string;
+    /** The runtime it ran in. */
     readonly runtime: string;
+    /** The seed of a randomised run. */
     readonly seed: string;
     readonly startedAtMs: number;
     readonly endedAtMs: number;
+    /** `endedAtMs - startedAtMs`, in milliseconds. */
     readonly durationMs: number;
+    /** Timing totals, when measurement was on. */
     readonly performance?: ReportPerformanceSummary;
     readonly status: ReportTestStatus;
+    /** The run the test belongs to; see `sanitizeRunId`. */
     readonly runId: string;
+    /** The test's id within the run; see `sanitizeTestId`. */
     readonly testId: string;
     /** Human title (defaults to `testId`). */
     readonly title: string;
+    /** The clients (actors) that took part. */
     readonly actorIds: readonly string[];
+    /** Repo-relative path of the test's source file (a spec), when known. */
     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;
+    /** The stack of that failure. */
     readonly errorStack?: string;
 };
 /**
@@ -112,42 +163,59 @@ export type RunReportMeta = {
  * is for what the runner can attach when it cannot: a video of the test, a few screenshots, a log.
  */
 export type ReportArtifact = {
+    /** Display name. */
     readonly name: string;
+    /** How `file` is encoded. */
     readonly media: SnapshotMedia;
+    /** Path of the file relative to the test's directory. */
     readonly file: string;
+    /** For a video: path of a still to show before playing. */
     readonly poster?: string;
+    /** For a video: path of its captions (WebVTT). */
     readonly captions?: string;
 };
 /** In-memory / persisted timeline for one test run. */
 export type RunReport = {
     readonly meta: RunReportMeta;
+    /** The top-level steps, in order; nested steps hang off each. */
     readonly steps: readonly ReportStep[];
+    /** Whole-test files, for runners that cannot capture per step. */
     readonly artifacts?: readonly ReportArtifact[];
 };
+/** One test as a suite manifest lists it: the metadata without the timeline. */
 export type SuiteTestSummary = {
     readonly testId: string;
     readonly title: string;
     readonly seed: string;
     readonly status: ReportTestStatus;
     readonly durationMs: number;
+    /** How many steps the test recorded. */
     readonly stepCount: number;
+    /** How many frames the test captured. */
     readonly frameCount: number;
     readonly system: string;
     readonly runtime: string;
     readonly sourceFile?: string;
     readonly error?: string;
 };
+/** A listing of a suite's tests, with the time it was last written. */
 export type SuiteManifest = {
     readonly tests: readonly SuiteTestSummary[];
+    /** When the listing was last written, epoch milliseconds. */
     readonly updatedAtMs: number;
 };
+/** One run as `runs/index.json` lists it. */
 export type RunSummary = {
+    /** The run id; see `sanitizeRunId`. */
     readonly id: string;
+    /** When the run was last updated, epoch milliseconds. */
     readonly updatedAtMs: number;
+    /** The run's overall outcome. */
     readonly status: ReportTestStatus;
     readonly testCount: number;
     readonly frameCount: number;
 };
+/** The index of the runs in a report bucket (stored at `runs/index.json`). */
 export type RunsIndex = {
     readonly runs: readonly RunSummary[];
 };
@@ -165,7 +233,9 @@ export type RecordStepMeta = {
     /** Skip registered snapshotters for this step. */
     readonly skipSnapshot?: boolean;
 };
+/** When a recording auto-opens a report step: on each applied action (`apply`) or never (`none`). */
 export type ReportCaptureMode = 'apply' | 'none';
+/** Options that turn on and shape the recording of a test run. */
 export type RunReportOptions = {
     /** Enable elapsed work measurement with a separate monotonic clock. */
     readonly performance?: ReportPerformanceOptions;
@@ -204,8 +274,11 @@ export type RunReportOptions = {
     /** 1-based source line of the call that opened the run, when known. */
     readonly sourceLine?: number;
 };
+/** Makes a test id safe as a key segment: runs of characters outside `A-Za-z0-9._-` become one `_`, leading and trailing `_` are trimmed, and an empty result is `test`. */
 export declare function sanitizeTestId(raw: string): string;
+/** Makes a run id safe as a key segment: runs of characters outside `A-Za-z0-9._-` become one `_`, leading and trailing `_` are trimmed, and an empty result is `run`. */
 export declare function sanitizeRunId(raw: string): string;
 /** Mint `YYYYMMDDTHHmmss` UTC from epoch ms. */
 export declare function mintRunId(nowMs: number): string;
+/** Normalises the `report` option of a test: `undefined` or `false` is `null` (reporting off), `true` is `{ enabled: true }`, an options object with `enabled: false` is `null`, and any other object is returned with `enabled: true`. */
 export declare function resolveReportOptions(report: boolean | RunReportOptions | undefined): RunReportOptions | null;

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

@@ -1,7 +1,9 @@
+/** Makes a test id safe as a key segment: runs of characters outside `A-Za-z0-9._-` become one `_`, leading and trailing `_` are trimmed, and an empty result is `test`. */
 export function sanitizeTestId(raw) {
     const cleaned = raw.replace(/[^a-zA-Z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
     return cleaned.length > 0 ? cleaned : 'test';
 }
+/** Makes a run id safe as a key segment: runs of characters outside `A-Za-z0-9._-` become one `_`, leading and trailing `_` are trimmed, and an empty result is `run`. */
 export function sanitizeRunId(raw) {
     const cleaned = raw.replace(/[^a-zA-Z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
     return cleaned.length > 0 ? cleaned : 'run';
@@ -17,6 +19,7 @@ export function mintRunId(nowMs) {
     const s = String(d.getUTCSeconds()).padStart(2, '0');
     return `${y}${mo}${day}T${h}${mi}${s}`;
 }
+/** Normalises the `report` option of a test: `undefined` or `false` is `null` (reporting off), `true` is `{ enabled: true }`, an options object with `enabled: false` is `null`, and any other object is returned with `enabled: true`. */
 export function resolveReportOptions(report) {
     if (report === undefined || report === false)
         return null;

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

@@ -0,0 +1,67 @@
+/**
+ * @module Streaming reporter
+ *
+ * `createReporter` lets a suite report checks as they finish: each flush is one immutable layer of the checks since the last,
+ * so a run is visible while it is still going, and a check reported `running` then `passed` is two layers whose newer,
+ * completed one wins. A layer that cannot be sent is kept and sent again byte for byte the same (never a second layer), a
+ * layer the server permanently refuses is counted as lost without blocking the ones behind it, and nothing is ever thrown
+ * into the suite being reported on.
+ *
+ * @see docs/server.md#streaming-a-run-as-it-happens
+ */
+import { type PublishChecksInput } from '../../schema/src/layer.js';
+import type { ObjectStore } from './object-store.js';
+type Check = PublishChecksInput['checks'][number];
+/** What every layer of one stream shares: who is reporting, from where. Whatever `publishChecks` takes, except the checks and the time. */
+export type ReporterIdentity = Pick<PublishChecksInput, 'producer' | 'kind' | 'title' | 'sha' | 'branch' | 'runUrl' | 'environment' | 'parameters' | 'freshness' | 'specs' | 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions'>;
+/** How a reporter sends: the `store` (a folder, S3, or `httpStore` for a server), how often (`flushMs`, `batchSize`), how hard it tries (`attempts`, `backoffMs`), what it tells (`onError`, `onPublished`), and the clock and sleep for tests. */
+export type ReporterOptions = {
+    /** Where layers go: a directory, S3, or `httpStore` for an Atlas server. */
+    readonly store: ObjectStore;
+    /** Send what has been reported this often (ms). Default 1000. `0` sends only on `flush()` and `close()`. */
+    readonly flushMs?: number;
+    /** Send at once when this many checks are waiting. Default 100. */
+    readonly batchSize?: number;
+    /** Tries for one layer, in `close()`; the timer keeps trying on its own. Default 5. */
+    readonly attempts?: number;
+    /** First wait between tries (ms), doubled each time to at most 30 s. Default 500. */
+    readonly backoffMs?: number;
+    /** Told of each failed try. A reporter never throws into the test run it reports on. */
+    readonly onError?: (error: Error, willRetry: boolean) => void;
+    /** Told of each layer that arrived. */
+    readonly onPublished?: (layer: {
+        id: string;
+        checks: number;
+    }) => void;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+};
+/** What `close()` says happened: layers and checks that arrived, and checks `lost` (never arrived). `lost` is zero when everything did. */
+export type ReporterResult = {
+    /** Layers that arrived. */
+    readonly layers: number;
+    /** Checks that arrived. */
+    readonly checks: number;
+    /** Checks that could not be sent. Zero when everything arrived. */
+    readonly lost: number;
+};
+/** A running reporter. `check` adds a result, `flush` sends what is waiting, `close` sends the rest and stops. */
+export type Reporter = {
+    /** Report one check, finished or still running. Reporting the same `id` again replaces it, whatever its state. */
+    check(check: Check): void;
+    /** Send everything reported so far, now. Resolves once it has arrived or failed; never rejects. */
+    flush(): Promise<void>;
+    /** Send the rest and stop. Retries each layer up to `attempts` times. */
+    close(): Promise<ReporterResult>;
+};
+/**
+ * A suite that reports as it goes. Each flush is one immutable layer holding the checks reported since the
+ * last, so nothing is rewritten and a laptop, a CI job and a device lab can all be sending to the same
+ * server at once. A check reported as `running` and then as `passed` is two layers; the later, completed one
+ * wins, so the report follows the suite while it runs and agrees with it when it ends.
+ *
+ * A layer that cannot be sent is kept and sent again, unchanged (same time, so same content): a retry never
+ * makes a second layer. Time only moves forward within a reporter, so a later result always follows an earlier one.
+ */
+export declare function createReporter(identity: ReporterIdentity, options: ReporterOptions): Reporter;
+export {};

package/dist/reports/src/reporter.js

@@ -0,0 +1,128 @@
+/**
+ * @module Streaming reporter
+ *
+ * `createReporter` lets a suite report checks as they finish: each flush is one immutable layer of the checks since the last,
+ * so a run is visible while it is still going, and a check reported `running` then `passed` is two layers whose newer,
+ * completed one wins. A layer that cannot be sent is kept and sent again byte for byte the same (never a second layer), a
+ * layer the server permanently refuses is counted as lost without blocking the ones behind it, and nothing is ever thrown
+ * into the suite being reported on.
+ *
+ * @see docs/server.md#streaming-a-run-as-it-happens
+ */
+import { PublishChecksSchema } from '../../schema/src/layer.js';
+import { parseWith } from './parse-with.js';
+import { publishChecks } from './publish-checks.js';
+/**
+ * Trying again cannot help a layer the server refused (too large, not valid) or that cannot be made: it would
+ * stand in front of every later one for ever.
+ */
+function permanent(error) {
+    return error.retryable === false || /^publishChecks:/.test(error.message);
+}
+/**
+ * A suite that reports as it goes. Each flush is one immutable layer holding the checks reported since the
+ * last, so nothing is rewritten and a laptop, a CI job and a device lab can all be sending to the same
+ * server at once. A check reported as `running` and then as `passed` is two layers; the later, completed one
+ * wins, so the report follows the suite while it runs and agrees with it when it ends.
+ *
+ * A layer that cannot be sent is kept and sent again, unchanged (same time, so same content): a retry never
+ * makes a second layer. Time only moves forward within a reporter, so a later result always follows an earlier one.
+ */
+export function createReporter(identity, options) {
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const flushMs = options.flushMs ?? 1000;
+    const batchSize = Math.max(1, options.batchSize ?? 100);
+    const attempts = Math.max(1, options.attempts ?? 5);
+    const backoff = options.backoffMs ?? 500;
+    let pending = new Map();
+    const failed = [];
+    let lastTime = 0;
+    let layers = 0, sent = 0, lost = 0;
+    let queue = Promise.resolve();
+    let timer = null;
+    let closed = false;
+    let wait = backoff;
+    const nextTime = () => (lastTime = Math.max(now(), lastTime + 1));
+    async function send(batch) {
+        try {
+            const layer = await publishChecks(options.store, { ...identity, checks: batch.checks, recordedAtMs: batch.recordedAtMs });
+            layers += 1;
+            sent += batch.checks.length;
+            options.onPublished?.({ id: layer.id, checks: batch.checks.length });
+            return null;
+        }
+        catch (error) {
+            return error instanceof Error ? error : new Error(String(error));
+        }
+    }
+    /** Everything waiting, oldest first. Returns once each batch has arrived, or failed `tries` times. */
+    async function drain(tries) {
+        if (pending.size) {
+            failed.push({ checks: [...pending.values()], recordedAtMs: nextTime() });
+            pending = new Map();
+        }
+        while (failed.length) {
+            const batch = failed[0];
+            let error = null;
+            for (let attempt = 1; attempt <= tries; attempt++) {
+                error = await send(batch);
+                if (!error)
+                    break;
+                if (permanent(error))
+                    break;
+                options.onError?.(error, attempt < tries || !closed);
+                if (attempt < tries)
+                    await sleep(Math.min(wait * 2 ** (attempt - 1), 30_000));
+            }
+            if (error && permanent(error)) {
+                // Said once, counted as lost, and out of the way of the layers behind it.
+                options.onError?.(error, false);
+                lost += batch.checks.length;
+                failed.shift();
+                continue;
+            }
+            if (error) {
+                if (closed) {
+                    lost += failed.reduce((sum, item) => sum + item.checks.length, 0);
+                    failed.length = 0;
+                }
+                return;
+            }
+            failed.shift();
+        }
+    }
+    const run = (tries) => (queue = queue.then(() => drain(tries)).catch(() => undefined));
+    function schedule() {
+        if (closed || timer || flushMs <= 0)
+            return;
+        timer = setTimeout(() => {
+            timer = null;
+            // One try per tick: a server that is down is asked again at the next one, not hammered.
+            void run(1).then(() => { if (pending.size || failed.length)
+                schedule(); });
+        }, failed.length ? Math.min(flushMs * 2 ** Math.min(failed.length, 5), 30_000) : flushMs);
+        timer.unref?.();
+    }
+    return {
+        check(check) {
+            if (closed)
+                throw new Error('This reporter is closed. Create another to report more.');
+            // A check that cannot be a layer is a mistake of the caller, found here where it was made, and not as a layer that never arrives.
+            const valid = parseWith(PublishChecksSchema.shape.checks.element, check, 'reporter.check');
+            pending.set(valid.id, valid);
+            if (pending.size >= batchSize)
+                void run(1);
+            schedule();
+        },
+        flush: () => run(1),
+        async close() {
+            closed = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+            await run(attempts);
+            return { layers, checks: sent, lost };
+        }
+    };
+}