@crvouga/atlas 1.0.0 → 1.2.0

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

@@ -10,7 +10,9 @@
  *   always the report's winner (`combineEvidence`), and history only describes how it got there.
  * - `testCatalog` turns the report's winners (plus a history, when there is one) into a `TestCatalog`: a summary with
  *   insights (slowest, flaky, failing), facets to filter by, and the tests that match a `TestQuery`.
- * - `testHistory`, `runList` and `runDetail` answer for one test, every run, and one run.
+ * - `testHistory`, `runList` and `runDetail` answer for one test, every run, and one run. `runList` and `artifactList`
+ *   narrow by tag, label, media type, environment, branch, outcome and time (see `artifact-query.ts`); `artifactList` finds
+ *   the recorded results that carry evidence across the whole history, not only the latest winners.
  * - `catalogMarkdown`, `historyMarkdown`, `runsMarkdown` and `runMarkdown` say the same in Markdown, for an agent or a
  *   terminal.
  *
@@ -21,6 +23,7 @@
  * @see docs/server.md#reading-the-report-as-an-agent
  */
 import { displayTag, normalizeTag, normalizeTags } from './artifact-tags.js';
+import { facetsOf, forRuns, labelList, matchesFilter, outcomeOfCounts, splitList, usedFilters } from './artifact-query.js';
 import { videoCounts } from './evidence-detail.js';
 import { checkSlots } from './evidence-view.js';
 import { combineEvidence, emptyCounts, slotKey, specPath as normalSpecPath } from './layer-merge.js';
@@ -101,6 +104,7 @@ export class TestHistory {
     #seen = new Set();
     #rev = 0;
     #cells = null;
+    #evidence = null;
     /** Changes each time a layer is added. */
     get rev() {
         return this.#rev;
@@ -127,7 +131,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, videos: [] };
+            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: [], evidence: { tags: new Set(), artifactTags: new Set(), roles: new Set(), labels: new Set() } };
             this.#runs.set(key, run);
         }
         // A run is told by its first layer (by time, then id), whatever order its layers arrive in.
@@ -156,6 +160,8 @@ export class TestHistory {
         run.layers += 1;
         if (layer.evidence?.videos)
             run.videos.push(...layer.evidence.videos);
+        if (layer.evidence)
+            takeEvidence(run.evidence, layer.evidence);
         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.
@@ -248,13 +254,75 @@ export class TestHistory {
         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 };
     }
+    /**
+     * Every recorded result that carries an attachment, newest first, with the values a query looks at. Built once per
+     * layer added. The domain is left to the caller (`artifactList`), which may know more specs than the layers recorded.
+     */
+    evidenceResults() {
+        if (this.#evidence?.rev === this.#rev)
+            return this.#evidence.items;
+        const items = [];
+        for (const [slot, list] of this.#bySlot) {
+            const i = this.#idents.get(slot);
+            for (const held of list) {
+                const e = held.e;
+                if (!e || e.attachments < 1)
+                    continue;
+                const playable = (videoCounts(e.videos)?.recordings ?? 0) > 0;
+                const types = typesOf(e.roles, playable);
+                const artifactTags = [...(e.artifactTags ?? [])];
+                const o = held.o;
+                const result = {
+                    key: i.slot, id: i.id, title: i.title, specPath: i.specPath, domain: null, at: o.at, status: held.s, environment: o.environment, producer: o.producer, kind: held.k,
+                    parameters: o.parameters, branch: o.branch, sha: o.sha, run: o.run, runUrl: o.runUrl, layer: o.layer, backend: o.backend, attachments: e.attachments,
+                    artifactTags, tags: [...e.tags], types, labels: e.labels, ...(e.videos ? { videos: e.videos } : {}),
+                };
+                const media = [
+                    ...types.filter(type => type !== 'video').map(type => ({ type, tags: artifactTags })),
+                    ...(e.videos ?? []).filter(video => video.available).map(video => ({ type: 'video', tags: video.tags ?? [] })),
+                ];
+                const labels = labelList(e.labels);
+                items.push({
+                    result,
+                    fields: {
+                        text: [i.title, i.id, i.specPath ?? '', o.branch ?? '', o.producer, o.environment ?? '', ...artifactTags, ...e.tags, ...labels].join('\n').toLowerCase(),
+                        artifactTags, tags: [...new Set([...e.tags, ...artifactTags])], types, media, labels,
+                        environments: o.environment ? [o.environment] : [], producers: [o.producer], branches: o.branch ? [o.branch] : [], shas: o.sha ? [o.sha.toLowerCase()] : [],
+                        outcomes: [held.s], at: o.at,
+                    },
+                });
+            }
+        }
+        items.sort((a, b) => b.result.at - a.result.at || compareText(a.result.layer, b.result.layer) || compareText(a.result.key, b.result.key) || compareText(a.result.kind, b.result.kind) || compareText(a.result.producer, b.result.producer));
+        this.#evidence = { rev: this.#rev, items };
+        return items;
+    }
     /** The keys of the tests one run recorded. */
     testsIn(key) {
         return new Set((this.#runCells().get(key) ?? []).map(cell => cell.i.slot));
     }
 }
+function takeEvidence(into, evidence) {
+    for (const tag of evidence.tags)
+        into.tags.add(tag);
+    for (const tag of evidence.artifactTags ?? [])
+        into.artifactTags.add(tag);
+    for (const role of evidence.roles)
+        into.roles.add(role);
+    for (const label of labelList(evidence.labels))
+        into.labels.add(label);
+}
+/** The media types of an evidence summary: its roles, with `video` only when a recording can be played. */
+function typesOf(roles, playable) {
+    const types = new Set(roles);
+    types.delete('video');
+    if (playable)
+        types.add('video');
+    return [...types].sort();
+}
 function runSummary(run, cells) {
     const counts = emptyCounts();
+    const carried = { tags: new Set(run.evidence.tags), artifactTags: new Set(run.evidence.artifactTags), roles: new Set(run.evidence.roles), labels: new Set(run.evidence.labels) };
     const tests = new Set();
     let total = 0, measured = false;
     const failed = [];
@@ -262,6 +330,8 @@ function runSummary(run, cells) {
     for (const cell of cells) {
         if (cell.r.e?.videos)
             videos.push(...cell.r.e.videos);
+        if (cell.r.e)
+            takeEvidence(carried, cell.r.e);
         counts[cell.r.s] += 1;
         tests.add(cell.i.slot);
         if (cell.r.d !== null) {
@@ -281,6 +351,10 @@ function runSummary(run, cells) {
         producers: [...run.producers].sort(), environments: [...run.environments].sort(),
         layers: run.layers, tests: tests.size, counts, totalDurationMs: measured ? total : null, failing,
         ...(video ? { videos: video } : {}),
+        ...(carried.artifactTags.size ? { artifactTags: [...carried.artifactTags].sort() } : {}),
+        ...(carried.roles.size ? { types: typesOf(carried.roles, (video?.recordings ?? 0) > 0) } : {}),
+        ...(carried.labels.size ? { labels: [...carried.labels].sort() } : {}),
+        ...(carried.tags.size ? { tags: [...carried.tags].sort() } : {}),
     };
 }
 function compareText(a, b) {
@@ -592,8 +666,59 @@ export function hasVideo(run) {
 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 };
+    const filter = forRuns(query);
+    const fields = all.map(fieldsOfRun);
+    const runs = all.filter((_, at) => matchesFilter(fields[at], filter));
+    return {
+        schemaVersion: TEST_CATALOG_VERSION, version, total: runs.length, runs: runs.slice(0, Math.max(0, limit)), withVideo,
+        filters: usedFilters(filter), facets: facetsOf(fields, filter),
+    };
+}
+/** What a query looks at in a run: see {@link ArtifactFilter}. A run's outcome is `failed` when any result failed. */
+export function fieldsOfRun(run) {
+    const artifactTags = run.artifactTags ?? [];
+    // A run summary of an older server has no `types`, but it says whether it has a playable video.
+    const types = run.types ?? (hasVideo(run) ? ['video'] : []);
+    const labels = run.labels ?? [];
+    return {
+        text: [run.title ?? '', run.key, run.branch ?? '', run.sha ?? '', ...run.producers, ...run.environments, ...artifactTags, ...(run.tags ?? []), ...labels].join('\n').toLowerCase(),
+        artifactTags, tags: [...new Set([...(run.tags ?? []), ...artifactTags])], types, media: types.map(type => ({ type, tags: artifactTags })), labels,
+        environments: run.environments, producers: run.producers, branches: run.branch ? [run.branch] : [], shas: run.sha ? [run.sha.toLowerCase()] : [],
+        outcomes: [outcomeOfCounts(run.counts)], at: run.endedAtMs,
+    };
+}
+/**
+ * The recorded results that carry evidence and match a query, newest first, across the whole history (`limit` default
+ * 100). `total` and the facet counts apply to every match before `offset` and `limit`. `domainOf` tells the domain of a
+ * spec path when the caller knows more than the layers recorded (a server with a spec set); otherwise it is the
+ * recorded spec's domain, else the folder the path implies.
+ *
+ * @example
+ * ```ts
+ * const list = artifactList(history, 'v1', { artifactTag: ['demo'], type: ['video'], environment: ['ios'] });
+ * list.results.map(r => [r.title, r.run, r.sha, r.status]);
+ * ```
+ */
+export function artifactList(history, version, query = {}, page = {}) {
+    const domains = new Map();
+    const domainOf = (path) => {
+        if (path === null)
+            return null;
+        if (!domains.has(path))
+            domains.set(path, (page.domainOf?.(path) ?? catalogSpec(path, known => history.specs.get(known))?.domain) || null);
+        return domains.get(path);
+    };
+    const items = history.evidenceResults().map(({ result, fields }) => {
+        const domain = domainOf(result.specPath);
+        return { result: { ...result, domain }, fields: { ...fields, domains: domain ? [domain] : [], specs: result.specPath ? [normalSpecPath(result.specPath)] : [] } };
+    });
+    const matched = items.filter(item => matchesFilter(item.fields, query));
+    const limit = Math.max(0, page.limit ?? 100);
+    const offset = Math.max(0, page.offset ?? 0);
+    return {
+        schemaVersion: TEST_CATALOG_VERSION, version, total: matched.length, offset, limit,
+        results: matched.slice(offset, offset + limit).map(item => item.result), filters: usedFilters(query), facets: facetsOf(items.map(item => item.fields), query),
+    };
 }
 /** One run with every result it recorded, or null when no run has that key. */
 export function runDetail(history, version, key) {
@@ -602,7 +727,7 @@ export function runDetail(history, version, key) {
 }
 /** 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`. */
 export function parseTestQuery(params) {
-    const many = (name) => params.getAll(name).flatMap(value => value.split(',')).map(value => value.trim()).filter(Boolean);
+    const many = (name) => params.getAll(name).flatMap(splitList);
     const number = (name) => { const value = params.get(name); return value !== null && /^\d+$/.test(value) ? Number(value) : undefined; };
     const sort = params.get('sort');
     const query = {};
@@ -726,6 +851,16 @@ export function runsMarkdown(list) {
         ...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`;
 }
+/** The artifact results as Markdown, for an agent or a terminal. */
+export function artifactsMarkdown(list) {
+    return `${[
+        `# Artifacts (${list.results.length} of ${list.total})`,
+        '',
+        '| Recorded | Test | Status | Environment | Branch | Commit | Types | Tags | Videos | Run |',
+        '|---|---|---|---|---|---|---|---|---|---|',
+        ...list.results.map(r => `| ${iso(r.at)} | ${cell(r.title)} | ${r.status} | ${r.environment ?? '—'} | ${cell(r.branch ?? '—')} | ${r.sha?.slice(0, 10) ?? '—'} | ${r.types.join(', ') || '—'} | ${r.artifactTags.map(displayTag).join(' ') || '—'} | ${videosText(videoCounts(r.videos))} | ${cell(r.runUrl ?? r.run)} |`),
+    ].join('\n')}\n`;
+}
 /** One run as Markdown. */
 export function runMarkdown(detail) {
     const { run } = detail;

package/dist/schema/src/api.d.ts

@@ -86,6 +86,7 @@ export declare const VideoRefSchema: z.ZodObject<{
     owner: z.ZodString;
     attempt: z.ZodOptional<z.ZodNumber>;
     step: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     recording: z.ZodOptional<z.ZodString>;
     available: z.ZodBoolean;
 }, z.core.$loose>;
@@ -111,6 +112,7 @@ export declare const EvidenceSummarySchema: z.ZodObject<{
         owner: z.ZodString;
         attempt: z.ZodOptional<z.ZodNumber>;
         step: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         recording: z.ZodOptional<z.ZodString>;
         available: z.ZodBoolean;
     }, z.core.$loose>>>;
@@ -161,6 +163,7 @@ export declare const LayerHeaderSchema: z.ZodObject<{
             owner: z.ZodString;
             attempt: z.ZodOptional<z.ZodNumber>;
             step: z.ZodOptional<z.ZodString>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
         }, z.core.$loose>>>;
@@ -211,6 +214,7 @@ export declare const LayerRowSchema: z.ZodObject<{
             owner: z.ZodString;
             attempt: z.ZodOptional<z.ZodNumber>;
             step: z.ZodOptional<z.ZodString>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
         }, z.core.$loose>>>;
@@ -259,6 +263,7 @@ export declare const LayerRowsSchema: z.ZodObject<{
                 owner: z.ZodString;
                 attempt: z.ZodOptional<z.ZodNumber>;
                 step: z.ZodOptional<z.ZodString>;
+                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
             }, z.core.$loose>>>;
@@ -309,6 +314,7 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
                 owner: z.ZodString;
                 attempt: z.ZodOptional<z.ZodNumber>;
                 step: z.ZodOptional<z.ZodString>;
+                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
             }, z.core.$loose>>>;
@@ -364,6 +370,7 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
                 owner: z.ZodString;
                 attempt: z.ZodOptional<z.ZodNumber>;
                 step: z.ZodOptional<z.ZodString>;
+                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
             }, z.core.$loose>>>;
@@ -423,6 +430,7 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                     owner: z.ZodString;
                     attempt: z.ZodOptional<z.ZodNumber>;
                     step: z.ZodOptional<z.ZodString>;
+                    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                 }, z.core.$loose>>>;
@@ -478,6 +486,7 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                     owner: z.ZodString;
                     attempt: z.ZodOptional<z.ZodNumber>;
                     step: z.ZodOptional<z.ZodString>;
+                    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                 }, z.core.$loose>>>;
@@ -558,6 +567,7 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                     owner: z.ZodString;
                     attempt: z.ZodOptional<z.ZodNumber>;
                     step: z.ZodOptional<z.ZodString>;
+                    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                 }, z.core.$loose>>>;
@@ -613,6 +623,7 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                     owner: z.ZodString;
                     attempt: z.ZodOptional<z.ZodNumber>;
                     step: z.ZodOptional<z.ZodString>;
+                    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                 }, z.core.$loose>>>;
@@ -696,6 +707,7 @@ export declare const EvidencePageSchema: z.ZodObject<{
                 owner: z.ZodString;
                 attempt: z.ZodOptional<z.ZodNumber>;
                 step: z.ZodOptional<z.ZodString>;
+                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
             }, z.core.$loose>>>;
@@ -1096,6 +1108,7 @@ export declare const TestResultEntrySchema: z.ZodObject<{
             owner: z.ZodString;
             attempt: z.ZodOptional<z.ZodNumber>;
             step: z.ZodOptional<z.ZodString>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
         }, z.core.$loose>>>;
@@ -1156,6 +1169,7 @@ export declare const TestSummarySchema: z.ZodObject<{
                 owner: z.ZodString;
                 attempt: z.ZodOptional<z.ZodNumber>;
                 step: z.ZodOptional<z.ZodString>;
+                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
             }, z.core.$loose>>>;
@@ -1406,6 +1420,7 @@ export declare const TestCatalogSchema: z.ZodObject<{
                     owner: z.ZodString;
                     attempt: z.ZodOptional<z.ZodNumber>;
                     step: z.ZodOptional<z.ZodString>;
+                    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                 }, z.core.$loose>>>;
@@ -1587,6 +1602,7 @@ export declare const TestHistorySchema: z.ZodObject<{
                     owner: z.ZodString;
                     attempt: z.ZodOptional<z.ZodNumber>;
                     step: z.ZodOptional<z.ZodString>;
+                    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     recording: z.ZodOptional<z.ZodString>;
                     available: z.ZodBoolean;
                 }, z.core.$loose>>>;
@@ -1665,6 +1681,7 @@ export declare const TestHistorySchema: z.ZodObject<{
                 owner: z.ZodString;
                 attempt: z.ZodOptional<z.ZodNumber>;
                 step: z.ZodOptional<z.ZodString>;
+                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 recording: z.ZodOptional<z.ZodString>;
                 available: z.ZodBoolean;
             }, z.core.$loose>>>;
@@ -1708,6 +1725,50 @@ export declare const ReportRunSchema: z.ZodObject<{
         recordings: z.ZodNumber;
         unavailable: z.ZodNumber;
     }, z.core.$loose>>;
+    artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    types: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+/** A value of a filter dimension and how many records have it. */
+export declare const QueryFacetValueSchema: z.ZodObject<{
+    value: z.ZodString;
+    count: z.ZodNumber;
+}, z.core.$loose>;
+/** The facets of a runs or artifacts query: per dimension, its values with disjunctive counts (the list's count if that value were the only one chosen, every other dimension's filter applied). */
+export declare const QueryFacetsSchema: z.ZodObject<{
+    artifactTags: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$loose>>;
+    types: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$loose>>;
+    labels: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$loose>>;
+    environments: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$loose>>;
+    producers: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$loose>>;
+    branches: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$loose>>;
+    outcomes: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$loose>>;
+    domains: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;
 /** `GET /api/reports/runs`: runs, newest first. */
 export declare const RunListSchema: z.ZodObject<{
@@ -1750,8 +1811,167 @@ export declare const RunListSchema: z.ZodObject<{
             recordings: z.ZodNumber;
             unavailable: z.ZodNumber;
         }, z.core.$loose>>;
+        artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        types: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$loose>>;
     withVideo: z.ZodOptional<z.ZodNumber>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    facets: z.ZodOptional<z.ZodObject<{
+        artifactTags: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        types: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        labels: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        environments: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        producers: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        branches: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        outcomes: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        domains: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** One recorded result that carries evidence: where and when it was recorded and what it carries. */
+export declare const ArtifactResultSchema: z.ZodObject<{
+    key: z.ZodString;
+    id: z.ZodString;
+    title: z.ZodString;
+    specPath: z.ZodNullable<z.ZodString>;
+    domain: z.ZodNullable<z.ZodString>;
+    at: z.ZodNumber;
+    status: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        running: "running";
+        "not-run": "not-run";
+    }>;
+    environment: z.ZodNullable<z.ZodString>;
+    producer: z.ZodString;
+    kind: z.ZodString;
+    parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+    branch: z.ZodNullable<z.ZodString>;
+    sha: z.ZodNullable<z.ZodString>;
+    run: z.ZodString;
+    runUrl: z.ZodNullable<z.ZodString>;
+    layer: z.ZodString;
+    backend: z.ZodString;
+    attachments: z.ZodNumber;
+    artifactTags: z.ZodArray<z.ZodString>;
+    tags: z.ZodArray<z.ZodString>;
+    types: z.ZodArray<z.ZodString>;
+    labels: z.ZodRecord<z.ZodString, z.ZodString>;
+    videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        owner: z.ZodString;
+        attempt: z.ZodOptional<z.ZodNumber>;
+        step: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        recording: z.ZodOptional<z.ZodString>;
+        available: z.ZodBoolean;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+/** `GET /api/reports/artifacts`: recorded results that carry evidence, newest first, with the facets of the query. */
+export declare const ArtifactListSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    version: z.ZodString;
+    total: z.ZodNumber;
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+    results: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        id: z.ZodString;
+        title: z.ZodString;
+        specPath: z.ZodNullable<z.ZodString>;
+        domain: z.ZodNullable<z.ZodString>;
+        at: z.ZodNumber;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            running: "running";
+            "not-run": "not-run";
+        }>;
+        environment: z.ZodNullable<z.ZodString>;
+        producer: z.ZodString;
+        kind: z.ZodString;
+        parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+        branch: z.ZodNullable<z.ZodString>;
+        sha: z.ZodNullable<z.ZodString>;
+        run: z.ZodString;
+        runUrl: z.ZodNullable<z.ZodString>;
+        layer: z.ZodString;
+        backend: z.ZodString;
+        attachments: z.ZodNumber;
+        artifactTags: z.ZodArray<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        types: z.ZodArray<z.ZodString>;
+        labels: z.ZodRecord<z.ZodString, z.ZodString>;
+        videos: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            owner: z.ZodString;
+            attempt: z.ZodOptional<z.ZodNumber>;
+            step: z.ZodOptional<z.ZodString>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            recording: z.ZodOptional<z.ZodString>;
+            available: z.ZodBoolean;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+    filters: z.ZodArray<z.ZodString>;
+    facets: z.ZodObject<{
+        artifactTags: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        types: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        labels: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        environments: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        producers: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        branches: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        outcomes: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>;
+        domains: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>;
 }, z.core.$loose>;
 /** `GET /api/reports/runs/detail`: one run and its last result for every test, environment and producer it recorded. */
 export declare const RunDetailSchema: z.ZodObject<{
@@ -1793,6 +2013,10 @@ export declare const RunDetailSchema: z.ZodObject<{
             recordings: z.ZodNumber;
             unavailable: z.ZodNumber;
         }, z.core.$loose>>;
+        artifactTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        types: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$loose>;
     results: z.ZodArray<z.ZodObject<{
         key: z.ZodString;
@@ -1816,6 +2040,7 @@ export declare const RunDetailSchema: z.ZodObject<{
             owner: z.ZodString;
             attempt: z.ZodOptional<z.ZodNumber>;
             step: z.ZodOptional<z.ZodString>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             recording: z.ZodOptional<z.ZodString>;
             available: z.ZodBoolean;
         }, z.core.$loose>>>;

package/dist/schema/src/api.js

@@ -68,6 +68,7 @@ export const VideoRefSchema = z.looseObject({
     owner: z.string().describe('Who holds it: `layer`, `check`, `attempt` or `step`. An open vocabulary: treat an unknown owner as a check'),
     attempt: z.number().int().nonnegative().optional().describe('The retry attempt that holds it, or that holds the step that does'),
     step: z.string().optional().describe('The name of the step that holds it'),
+    tags: z.array(z.string()).optional().describe('The normalized tags of this attachment itself. Absent when it has none (and in documents of older servers)'),
     recording: z.string().optional().describe('What identifies the bytes; references with the same value are one recording. Absent when it cannot be played'),
     available: z.boolean().describe('False when the reference names no bytes (no bundle key, address or inline text)')
 });
@@ -396,7 +397,19 @@ export const ReportRunSchema = z.looseObject({
     layers: z.number().int().nonnegative(), tests: z.number().int().nonnegative(), counts: StatusCountsSchema,
     totalDurationMs: z.number().nullable(),
     failing: z.array(z.looseObject({ key: z.string(), title: z.string(), environment: z.string().nullable(), detail: z.string() })),
-    videos: VideoCountsSchema.optional().describe('Its videos, from its layers and the last result of each test. Absent when it has none or the report carries no video information')
+    videos: VideoCountsSchema.optional().describe('Its videos, from its layers and the last result of each test. Absent when it has none or the report carries no video information'),
+    artifactTags: z.array(z.string()).optional().describe('The normalized tags of the attachments of its results, sorted and distinct. Absent when none is tagged, and in reports of older servers'),
+    tags: z.array(z.string()).optional().describe('The tags of its checks and layers, which its attachments inherit (what `inherited=1` also matches). Absent when none'),
+    types: z.array(z.string()).optional().describe('The media types (roles) of its attachments, sorted and distinct; `video` only for a playable recording. Absent when it has no attachment'),
+    labels: z.array(z.string()).optional().describe('The `key=value` labels of its results and layers, sorted and distinct. Absent when it has none')
+});
+/** A value of a filter dimension and how many records have it. */
+export const QueryFacetValueSchema = z.looseObject({ value: z.string(), count: z.number().int().nonnegative() });
+/** The facets of a runs or artifacts query: per dimension, its values with disjunctive counts (the list's count if that value were the only one chosen, every other dimension's filter applied). */
+export const QueryFacetsSchema = z.looseObject({
+    artifactTags: z.array(QueryFacetValueSchema), types: z.array(QueryFacetValueSchema), labels: z.array(QueryFacetValueSchema).describe('Values are `key=value`'),
+    environments: z.array(QueryFacetValueSchema), producers: z.array(QueryFacetValueSchema), branches: z.array(QueryFacetValueSchema), outcomes: z.array(QueryFacetValueSchema),
+    domains: z.array(QueryFacetValueSchema).optional().describe('Only for artifacts: runs have no domain')
 });
 /** `GET /api/reports/runs`: runs, newest first. */
 export const RunListSchema = z.looseObject({
@@ -404,7 +417,33 @@ export const RunListSchema = z.looseObject({
     version: z.string(),
     total: z.number().int().nonnegative().describe('Runs that matched, before `limit`'),
     runs: z.array(ReportRunSchema),
-    withVideo: z.number().int().nonnegative().optional().describe('How many of all runs (before `video` and `limit`) have a playable video recording')
+    withVideo: z.number().int().nonnegative().optional().describe('How many of all runs (before `video` and `limit`) have a playable video recording'),
+    filters: z.array(z.string()).optional().describe('The filter parameters this server applied (`artifactTag`, `type`, `outcome`…). A viewer that asked for one that is missing here knows the server ignored it. Absent on servers that predate filtering'),
+    facets: QueryFacetsSchema.optional().describe('The values each filter dimension offers, counted over every run. Absent on servers that predate filtering')
+});
+/** One recorded result that carries evidence: where and when it was recorded and what it carries. */
+export const ArtifactResultSchema = z.looseObject({
+    key: z.string().describe('The test\'s key, as in `/api/reports/tests`'), id: z.string(), title: z.string(), specPath: z.string().nullable(), domain: z.string().nullable(),
+    at: z.number().describe('When it was recorded, epoch milliseconds'), status: EvidenceStatusSchema,
+    environment: z.string().nullable(), producer: z.string(), kind: z.string(), parameters: z.record(z.string(), z.string()),
+    branch: z.string().nullable(), sha: z.string().nullable(), run: z.string().describe('The run\'s key, as in `/api/reports/runs`'), runUrl: z.string().nullable(),
+    layer: z.string().describe('The id of the layer that recorded it. Pass it as the `layer` of the explorer to see exactly this result'), backend: z.string(),
+    attachments: z.number().int().nonnegative(),
+    artifactTags: z.array(z.string()).describe('Normalized tags of its attachments'),
+    tags: z.array(z.string()).describe('Tags of its check and run, which its attachments inherit'),
+    types: z.array(z.string()).describe('Media types (roles) of its attachments; `video` only for a playable recording'),
+    labels: z.record(z.string(), z.string()),
+    videos: z.array(VideoRefSchema).optional()
+});
+/** `GET /api/reports/artifacts`: recorded results that carry evidence, newest first, with the facets of the query. */
+export const ArtifactListSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    version: z.string(),
+    total: z.number().int().nonnegative().describe('Results that matched, before `offset` and `limit`'),
+    offset: z.number().int().nonnegative(), limit: z.number().int().nonnegative(),
+    results: z.array(ArtifactResultSchema),
+    filters: z.array(z.string()).describe('The filters of the query that were applied'),
+    facets: QueryFacetsSchema
 });
 /** `GET /api/reports/runs/detail`: one run and its last result for every test, environment and producer it recorded. */
 export const RunDetailSchema = z.looseObject({