@crvouga/atlas 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog: @crvouga/atlas
 
+## 0.16.0 (2026-10-28)
+
+### Features
+
+- show video availability and filter runs with recordings ([dece195](https://github.com/crvouga/atlas/commit/dece195ef419a3fc6eaedb643544be29ffb341c3))
+
 ## 0.15.0 (2026-10-28)
 
 ### Features

package/dist/reports/src/evidence-detail.d.ts

@@ -10,7 +10,7 @@
  * @see docs/report-contract.md (evidence)
  */
 import type { Annotation, Attachment, Attempt, Check, Step } from '../../schema/src/layer.js';
-import type { EvidenceSummary } from './evidence-types.js';
+import type { EvidenceSummary, VideoCounts, VideoRef } from './evidence-types.js';
 /** Anything that may carry evidence: a layer, a part or a check. */
 export type EvidenceHolder = {
     readonly tags?: readonly string[];
@@ -34,9 +34,26 @@ export type EvidenceHolder = {
  * Several holders (for example a check and its layer) are summed: `attachments` also counts those on steps and
  * attempts, `steps` counts only each holder's own top-level steps, tags are de-duplicated, and for a repeated
  * label the later holder wins. `artifactTags` are the attachments' own normalized tags and are never inherited. `roles` are the attachments' roles (or, without one, what their media type or file
- * name implies), sorted and distinct.
+ * name implies), sorted and distinct. `videos` lists every attachment whose effective media type is video, with the
+ * check, retry attempt or step that holds it (see {@link isVideoAttachment}).
  */
 export declare function summarizeEvidence(...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined;
+/**
+ * Like {@link summarizeEvidence} for a layer and its parts: the same summary, but a video attached to the layer or a
+ * part is owned by the `layer`, not by a check.
+ */
+export declare function summarizeLayerEvidence(...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined;
+/**
+ * Whether an attachment is a video, by its effective media type: the producer's `contentType`, else the one its file
+ * name implies. A role never decides this on its own (`demo` on a PNG is not a video), except that a `video` role
+ * settles a file whose type nothing says (`application/octet-stream`).
+ */
+export declare function isVideoAttachment(attachment: Pick<Attachment, 'name' | 'role' | 'contentType'>): boolean;
+/**
+ * Counts references, distinct playable recordings and unplayable references. Undefined when there is no reference, so
+ * "no video" and "nothing known about video" look the same on the wire.
+ */
+export declare function videoCounts(videos: readonly VideoRef[] | undefined): VideoCounts | undefined;
 /** A role to show when a producer gave none, from the media type: `image`, `video`, `audio`, `snapshot` (text/html), `text` (text, JSON, XML) or `file`. Roles are an open vocabulary; a producer's own role always wins. */
 export declare function roleOfType(contentType: string | undefined): string;
 /** All of one result's evidence, read when someone opens it. */

package/dist/reports/src/evidence-detail.js

@@ -11,31 +11,48 @@ function count(holder) {
  * Several holders (for example a check and its layer) are summed: `attachments` also counts those on steps and
  * attempts, `steps` counts only each holder's own top-level steps, tags are de-duplicated, and for a repeated
  * label the later holder wins. `artifactTags` are the attachments' own normalized tags and are never inherited. `roles` are the attachments' roles (or, without one, what their media type or file
- * name implies), sorted and distinct.
+ * name implies), sorted and distinct. `videos` lists every attachment whose effective media type is video, with the
+ * check, retry attempt or step that holds it (see {@link isVideoAttachment}).
  */
 export function summarizeEvidence(...holders) {
+    return summarize(holders, 'check');
+}
+/**
+ * Like {@link summarizeEvidence} for a layer and its parts: the same summary, but a video attached to the layer or a
+ * part is owned by the `layer`, not by a check.
+ */
+export function summarizeLayerEvidence(...holders) {
+    return summarize(holders, 'layer');
+}
+function summarize(holders, owner) {
     if (!holders.some(holder => count(holder) > 0))
         return undefined;
     const roles = new Set();
     const tags = new Set();
     const artifactTags = new Set();
     const labels = {};
+    const videos = [];
     let attachments = 0, steps = 0, annotations = 0, attempts = 0, links = 0;
-    const attachmentsOf = (list) => { for (const item of list ?? []) {
-        attachments += 1;
-        for (const tag of normalizeTags(item.tags))
-            artifactTags.add(tag);
-        roles.add(item.role ?? roleOfType(item.contentType ?? contentTypeOf(item.name)));
-    } };
+    const attachmentsOf = (list, by, where = {}) => {
+        for (const item of list ?? []) {
+            attachments += 1;
+            for (const tag of normalizeTags(item.tags))
+                artifactTags.add(tag);
+            roles.add(item.role ?? roleOfType(item.contentType ?? contentTypeOf(item.name)));
+            const video = videoOf(item, by, where);
+            if (video)
+                videos.push(video);
+        }
+    };
+    const stepsOf = (list, attempt) => { for (const step of list ?? [])
+        attachmentsOf(step.attachments, 'step', { ...(attempt === undefined ? {} : { attempt }), step: step.name }); };
     for (const holder of holders) {
-        attachmentsOf(holder.attachments);
+        attachmentsOf(holder.attachments, owner);
         // Attachments on steps and attempts are part of the check too.
-        for (const step of holder.steps ?? [])
-            attachmentsOf(step.attachments);
+        stepsOf(holder.steps);
         for (const attempt of holder.attempts ?? []) {
-            attachmentsOf(attempt.attachments);
-            for (const step of attempt.steps ?? [])
-                attachmentsOf(step.attachments);
+            attachmentsOf(attempt.attachments, 'attempt', { attempt: attempt.index });
+            stepsOf(attempt.steps, attempt.index);
         }
         steps += holder.steps?.length ?? 0;
         annotations += holder.annotations?.length ?? 0;
@@ -45,7 +62,39 @@ export function summarizeEvidence(...holders) {
             tags.add(tag);
         Object.assign(labels, holder.labels);
     }
-    return { attachments, steps, annotations, attempts, links, tags: [...tags], ...(artifactTags.size ? { artifactTags: [...artifactTags].sort() } : {}), labels, roles: [...roles].sort() };
+    return { attachments, steps, annotations, attempts, links, tags: [...tags], ...(artifactTags.size ? { artifactTags: [...artifactTags].sort() } : {}), labels, roles: [...roles].sort(), ...(videos.length ? { videos } : {}) };
+}
+/**
+ * Whether an attachment is a video, by its effective media type: the producer's `contentType`, else the one its file
+ * name implies. A role never decides this on its own (`demo` on a PNG is not a video), except that a `video` role
+ * settles a file whose type nothing says (`application/octet-stream`).
+ */
+export function isVideoAttachment(attachment) {
+    const type = (attachment.contentType ?? contentTypeOf(attachment.name)).toLowerCase();
+    return type.startsWith('video/') || (attachment.role === 'video' && type.startsWith('application/octet-stream'));
+}
+function videoOf(item, owner, where) {
+    if (!isVideoAttachment(item))
+        return undefined;
+    const recording = item.sha256 ? `sha256:${item.sha256}` : item.bundleKey ?? item.uri ?? (item.text === undefined ? undefined : `inline:${item.name}`);
+    return { name: item.name, owner, ...where, ...(recording === undefined ? {} : { recording }), available: recording !== undefined };
+}
+/**
+ * Counts references, distinct playable recordings and unplayable references. Undefined when there is no reference, so
+ * "no video" and "nothing known about video" look the same on the wire.
+ */
+export function videoCounts(videos) {
+    if (!videos?.length)
+        return undefined;
+    const distinct = new Set();
+    let unavailable = 0;
+    for (const video of videos) {
+        if (video.available && video.recording !== undefined)
+            distinct.add(video.recording);
+        else
+            unavailable += 1;
+    }
+    return { references: videos.length, recordings: distinct.size, unavailable };
 }
 /** A role to show when a producer gave none, from the media type: `image`, `video`, `audio`, `snapshot` (text/html), `text` (text, JSON, XML) or `file`. Roles are an open vocabulary; a producer's own role always wins. */
 export function roleOfType(contentType) {

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

@@ -36,6 +36,35 @@ export type BackendInfo = {
 };
 /** How many results have each status (`passed`, `failed`, `running`, `not-run`). */
 export type StatusCounts = Readonly<Record<EvidenceStatus, number>>;
+/** Who holds a recording: the whole layer (or one of its parts), one check, one retry attempt of a check, or one step. */
+export type VideoOwner = 'layer' | 'check' | 'attempt' | 'step';
+/**
+ * One reference to a video, found by its effective media type (the producer's `contentType`, else the one the file
+ * name implies; a `video` role alone counts only when nothing else says what the file is). A reference is not a
+ * recording: the same bytes referenced from three checks are three references and one recording.
+ */
+export type VideoRef = {
+    /** The attachment's name, for a person. */
+    readonly name: string;
+    readonly owner: VideoOwner;
+    /** The try that holds it, when `owner` is `attempt` or the step is inside one. */
+    readonly attempt?: number;
+    /** The name of the step that holds it, when `owner` is `step`. */
+    readonly step?: string;
+    /** What identifies the bytes (digest, bundle key or address); references with the same one are the same recording. Absent when `available` is false. */
+    readonly recording?: string;
+    /** False when the reference names no bytes at all (no bundle key, address or inline text), so it can never be played. */
+    readonly available: boolean;
+};
+/** Video availability as counts: references, distinct playable recordings (deduplicated), and references that cannot be played. */
+export type VideoCounts = {
+    /** Every reference to a video, playable or not. */
+    readonly references: number;
+    /** Distinct playable recordings: identical bytes referenced twice are one. */
+    readonly recordings: number;
+    /** References that name no bytes. A report that predates availability metadata has none of these and none of the others. */
+    readonly unavailable: number;
+};
 /**
  * What a result (or a run) carries beyond its outcome, as counts and short facts: attachments, steps,
  * annotations, retries, tags, labels, links. It is only there when there is something. The evidence itself
@@ -55,6 +84,8 @@ export type EvidenceSummary = {
     readonly labels: Readonly<Record<string, string>>;
     /** The distinct roles of its attachments (or what their media types say), to show what kind of evidence there is. */
     readonly roles: readonly string[];
+    /** Its references to videos, wherever they are held (layer, check, attempt, step). Only there when it has any. */
+    readonly videos?: readonly VideoRef[];
 };
 /** A report layer's origin and totals. Its checks are read separately, once. */
 export type LayerHeader = {

package/dist/reports/src/layer-merge.js

@@ -1,4 +1,4 @@
-import { summarizeEvidence } from './evidence-detail.js';
+import { summarizeEvidence, summarizeLayerEvidence } from './evidence-detail.js';
 import { layerPlace } from './layer-axes.js';
 /**
  * A short, deterministic fingerprint of a spec's text, shaped `<length>:<hash>:<hash>` (the length in UTF-16 code
@@ -94,7 +94,7 @@ export function layerEvidence(summary, backend) {
         }
     }
     const recording = summary.recording;
-    const layerSummaryEvidence = summarizeEvidence(summary, ...summary.parts);
+    const layerSummaryEvidence = summarizeLayerEvidence(summary, ...summary.parts);
     const layer = {
         ...(summary.freshness ? { freshness: summary.freshness } : {}),
         ...(summary.run ? { run: summary.run } : {}),

package/dist/reports/src/test-catalog.d.ts

@@ -1,5 +1,5 @@
 import type { EvidenceStatus, SpecEntry } from './explorer-types.js';
-import type { EvidenceSummary, LayerEvidence, LayerHeader, LayerRow, StatusCounts } from './evidence-types.js';
+import type { EvidenceSummary, LayerEvidence, LayerHeader, LayerRow, StatusCounts, VideoCounts, VideoRef } from './evidence-types.js';
 import { RecordedSpecs } from './recorded-specs.js';
 /** The version of the documents this module writes (`TestCatalog`, `TestHistoryDocument`, `RunList`, `RunDetail`). Only optional fields are added within it. */
 export declare const TEST_CATALOG_VERSION = 1;
@@ -258,13 +258,26 @@ export type RunSummary = {
         readonly environment: string | null;
         readonly detail: string;
     }[];
+    /**
+     * Its videos, from the run's layers and from the last result of each test: references, distinct playable recordings
+     * and references that cannot be played. Absent when it has none, and in a report that carries no video information.
+     */
+    readonly videos?: VideoCounts;
+};
+/** What `runList` can be asked. */
+export type RunQuery = {
+    /** Only runs that have at least one playable video recording. `total` then counts only those. */
+    readonly video?: boolean;
 };
 /** `GET /api/reports/runs`: runs, newest first. */
 export type RunList = {
     readonly schemaVersion: typeof TEST_CATALOG_VERSION;
     readonly version: string;
+    /** Runs that matched, before `limit`. */
     readonly total: number;
     readonly runs: readonly RunSummary[];
+    /** How many of all runs (whatever was asked, before `limit`) have a playable video recording. */
+    readonly withVideo?: number;
 };
 /** One test's last result within one run. */
 export type RunResult = {
@@ -279,6 +292,8 @@ export type RunResult = {
     readonly at: number;
     readonly layer: string;
     readonly detail: string;
+    /** Every video its evidence references, with who holds it (check, retry attempt or step). Absent when there is none. */
+    readonly videos?: readonly VideoRef[];
 };
 /** `GET /api/reports/runs/detail`: one run and every result it recorded. */
 export type RunDetail = {
@@ -380,8 +395,14 @@ export declare function matchesQuery(model: CatalogModel, test: TestSummary, que
 export declare function testCatalog(model: CatalogModel, query?: TestQuery): TestCatalog;
 /** One test and its recorded results, or null when the report has no test with that key. */
 export declare function testHistory(model: CatalogModel, key: string): TestHistoryDocument | null;
-/** Every run the history knows of, newest first, `limit` at most (default 100). */
-export declare function runList(history: TestHistory, version: string, limit?: number): RunList;
+/** Whether a run has at least one playable video recording. */
+export declare function hasVideo(run: Pick<RunSummary, 'videos'>): boolean;
+/**
+ * Every run the history knows of, newest first, `limit` at most (default 100). With `query.video` only the runs that
+ * have a playable video recording: the filter and `total` apply to every run before `limit`, and nothing is read from
+ * any recording's bytes. `withVideo` always counts every run that has one.
+ */
+export declare function runList(history: TestHistory, version: string, limit?: number, query?: RunQuery): RunList;
 /** One run with every result it recorded, or null when no run has that key. */
 export declare function runDetail(history: TestHistory, version: string, key: string): RunDetail | null;
 /** Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`, `artifactTag`, and `inherited=1`. */

package/dist/reports/src/test-catalog.js

@@ -21,6 +21,7 @@
  * @see docs/server.md#reading-the-report-as-an-agent
  */
 import { displayTag, normalizeTag, normalizeTags } from './artifact-tags.js';
+import { videoCounts } from './evidence-detail.js';
 import { checkSlots } from './evidence-view.js';
 import { combineEvidence, emptyCounts, slotKey, specPath as normalSpecPath } from './layer-merge.js';
 import { RecordedSpecs } from './recorded-specs.js';
@@ -126,7 +127,7 @@ export class TestHistory {
         const key = runKey(layer);
         let run = this.#runs.get(key);
         if (!run) {
-            run = { key, runUrl: layer.runUrl, branch: layer.branch, sha: layer.sha, start: layer.recordedAtMs, end: layer.recordedAtMs, firstAt: layer.recordedAtMs, first: layer.id, producers: new Set(), environments: new Set(), layers: 0, runId: layer.run?.id, title: undefined, titledAt: 0, titledBy: '', freshness: undefined };
+            run = { key, runUrl: layer.runUrl, branch: layer.branch, sha: layer.sha, start: layer.recordedAtMs, end: layer.recordedAtMs, firstAt: layer.recordedAtMs, first: layer.id, producers: new Set(), environments: new Set(), layers: 0, runId: layer.run?.id, title: undefined, titledAt: 0, titledBy: '', freshness: undefined, videos: [] };
             this.#runs.set(key, run);
         }
         // A run is told by its first layer (by time, then id), whatever order its layers arrive in.
@@ -153,6 +154,8 @@ export class TestHistory {
         if (layer.environment)
             run.environments.add(layer.environment);
         run.layers += 1;
+        if (layer.evidence?.videos)
+            run.videos.push(...layer.evidence.videos);
         const origin = originOf(layer, backend);
         for (const row of rows) {
             // "Still running" is progress, not history: a test running now shows it as its current outcome.
@@ -240,6 +243,7 @@ export class TestHistory {
         const results = cells.map(({ i, r }) => ({
             key: i.slot, id: i.id, title: i.title, specPath: i.specPath, environment: r.o.environment, producer: r.o.producer,
             status: r.s, durationMs: r.d, at: r.o.at, layer: r.o.layer, detail: shortDetail(r.t),
+            ...(r.e?.videos ? { videos: r.e.videos } : {}),
         }));
         results.sort((a, b) => FAILURE_RANK[b.status] - FAILURE_RANK[a.status] || compareText(a.specPath ?? '', b.specPath ?? '') || compareText(a.title, b.title) || compareText(a.environment ?? '', b.environment ?? '') || compareText(a.producer, b.producer) || compareText(a.key, b.key));
         return { run: runSummary(run, cells), results };
@@ -254,7 +258,10 @@ function runSummary(run, cells) {
     const tests = new Set();
     let total = 0, measured = false;
     const failed = [];
+    const videos = [...run.videos];
     for (const cell of cells) {
+        if (cell.r.e?.videos)
+            videos.push(...cell.r.e.videos);
         counts[cell.r.s] += 1;
         tests.add(cell.i.slot);
         if (cell.r.d !== null) {
@@ -265,6 +272,7 @@ function runSummary(run, cells) {
             failed.push(cell);
     }
     failed.sort((a, b) => compareText(a.i.slot, b.i.slot) || compareText(a.r.o.place, b.r.o.place) || compareText(a.r.k, b.r.k));
+    const video = videoCounts(videos);
     const failing = failed.slice(0, 20).map(cell => ({ key: cell.i.slot, title: cell.i.title, environment: cell.r.o.environment, detail: (cell.r.t.split('\n')[0] ?? '').slice(0, 500) }));
     return {
         key: run.key, ...(run.runId ? { runId: run.runId } : {}), ...(run.title ? { title: run.title } : {}), ...(run.freshness ? { freshness: run.freshness } : {}),
@@ -272,6 +280,7 @@ function runSummary(run, cells) {
         startedAtMs: run.start, endedAtMs: run.end, spanMs: run.end - run.start,
         producers: [...run.producers].sort(), environments: [...run.environments].sort(),
         layers: run.layers, tests: tests.size, counts, totalDurationMs: measured ? total : null, failing,
+        ...(video ? { videos: video } : {}),
     };
 }
 function compareText(a, b) {
@@ -571,10 +580,20 @@ export function testHistory(model, key) {
         return null;
     return { schemaVersion: TEST_CATALOG_VERSION, version: model.version, test, history: model.history?.of(key) ?? test.outcomes };
 }
-/** Every run the history knows of, newest first, `limit` at most (default 100). */
-export function runList(history, version, limit = 100) {
-    const runs = history.runs();
-    return { schemaVersion: TEST_CATALOG_VERSION, version, total: runs.length, runs: runs.slice(0, Math.max(0, limit)) };
+/** Whether a run has at least one playable video recording. */
+export function hasVideo(run) {
+    return (run.videos?.recordings ?? 0) > 0;
+}
+/**
+ * Every run the history knows of, newest first, `limit` at most (default 100). With `query.video` only the runs that
+ * have a playable video recording: the filter and `total` apply to every run before `limit`, and nothing is read from
+ * any recording's bytes. `withVideo` always counts every run that has one.
+ */
+export function runList(history, version, limit = 100, query = {}) {
+    const all = history.runs();
+    const withVideo = all.filter(hasVideo).length;
+    const runs = query.video ? all.filter(hasVideo) : all;
+    return { schemaVersion: TEST_CATALOG_VERSION, version, total: runs.length, runs: runs.slice(0, Math.max(0, limit)), withVideo };
 }
 /** One run with every result it recorded, or null when no run has that key. */
 export function runDetail(history, version, key) {
@@ -687,6 +706,12 @@ export function historyMarkdown(document) {
         ...document.history.map(e => `| ${iso(e.at)} | ${e.environment ?? '—'} | ${e.status} | ${formatMs(e.durationMs)} | ${cell(e.branch ?? '—')} | ${e.sha?.slice(0, 10) ?? '—'} | ${cell(e.detail.split('\n')[0] ?? '')} |`),
     ].join('\n')}\n`;
 }
+/** Video counts in a few words: `2 (3 references)`, with how many cannot be played, or `—` when there are none. */
+function videosText(videos) {
+    if (!videos)
+        return '—';
+    return `${videos.recordings}${videos.references !== videos.recordings ? ` (${videos.references} references)` : ''}${videos.unavailable ? `, ${videos.unavailable} unavailable` : ''}`;
+}
 /** What to say beside a commit that was not recorded from a clean checkout: nothing, ` (modified)` or ` (origin unknown)`. */
 function freshnessNote(freshness) {
     return freshness === 'modified' ? ' (modified: local changes)' : freshness === 'unknown' ? ' (origin unknown)' : '';
@@ -696,9 +721,9 @@ export function runsMarkdown(list) {
     return `${[
         `# Runs (${list.runs.length} of ${list.total})`,
         '',
-        '| Ended | Branch | Commit | Environments | Tests | Passed | Failed | Not run | Span | Run |',
-        '|---|---|---|---|---:|---:|---:|---:|---:|---|',
-        ...list.runs.map(r => `| ${iso(r.endedAtMs)} | ${cell(r.branch ?? '—')} | ${r.sha?.slice(0, 10) ?? '—'}${freshnessNote(r.freshness)} | ${r.environments.join(', ') || '—'} | ${r.tests} | ${r.counts.passed} | ${r.counts.failed} | ${r.counts['not-run']} | ${formatMs(r.spanMs)} | ${cell(r.title ? `${r.title} (${r.key})` : r.key)} |`),
+        '| Ended | Branch | Commit | Environments | Tests | Passed | Failed | Not run | Span | Videos | Run |',
+        '|---|---|---|---|---:|---:|---:|---:|---:|---|---|',
+        ...list.runs.map(r => `| ${iso(r.endedAtMs)} | ${cell(r.branch ?? '—')} | ${r.sha?.slice(0, 10) ?? '—'}${freshnessNote(r.freshness)} | ${r.environments.join(', ') || '—'} | ${r.tests} | ${r.counts.passed} | ${r.counts.failed} | ${r.counts['not-run']} | ${formatMs(r.spanMs)} | ${videosText(r.videos)} | ${cell(r.title ? `${r.title} (${r.key})` : r.key)} |`),
     ].join('\n')}\n`;
 }
 /** One run as Markdown. */
@@ -712,9 +737,10 @@ export function runMarkdown(detail) {
         `- ${iso(run.startedAtMs)} to ${iso(run.endedAtMs)} (${formatMs(run.spanMs)}); ${run.layers} layers from ${run.producers.join(', ')}`,
         `- Environments: ${run.environments.join(', ') || '—'}`,
         `- ${run.tests} tests: ${counted(run.counts)}${run.totalDurationMs === null ? '' : `; ${formatMs(run.totalDurationMs)} of test time`}`,
+        ...(run.videos ? [`- Videos: ${videosText(run.videos)}`] : []),
         '',
-        '| Status | Test | Spec | Environment | Duration | Detail |',
-        '|---|---|---|---|---:|---|',
-        ...detail.results.map(r => `| ${r.status} | ${cell(r.title)} | ${cell(r.specPath ?? '—')} | ${r.environment ?? '—'} | ${formatMs(r.durationMs)} | ${cell(r.detail.split('\n')[0] ?? '')} |`),
+        '| Status | Test | Spec | Environment | Duration | Videos | Detail |',
+        '|---|---|---|---|---:|---|---|',
+        ...detail.results.map(r => `| ${r.status} | ${cell(r.title)} | ${cell(r.specPath ?? '—')} | ${r.environment ?? '—'} | ${formatMs(r.durationMs)} | ${videosText(videoCounts(r.videos))} | ${cell(r.detail.split('\n')[0] ?? '')} |`),
     ].join('\n')}\n`;
 }