@crvouga/atlas 1.1.0 → 1.2.0

package/packages/visualizer/src/explorer/ArtifactsView.tsx

@@ -0,0 +1,162 @@
+/**
+ * @module Artifacts view
+ *
+ * Every recorded result that carries evidence (recordings, screenshots, traces) across the project's history, newest first,
+ * found by artifact tag, media type, label, feature, environment, branch, outcome and time. A result is listed with the
+ * run, commit and status it was recorded with, so a recording tagged `demo` is found even when a later attempt is
+ * untagged. Each row opens that exact result in the test detail. An empty answer for a filter says nothing matches and
+ * offers to clear it; it never says the project has nothing recorded.
+ */
+import { IconVideo } from '@tabler/icons-react';
+import { Alert, Anchor, Box, Button, Code, Stack, Table, Text } from '@mantine/core';
+import { videoCounts } from '@crvouga/atlas/reports/evidence-detail';
+import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
+import { Link } from '@tanstack/react-router';
+import { useMemo, useState } from 'react';
+
+import { ago, exactTime, plural, shortSha, statusWord, useNow } from '../evidence/format';
+import { StatusMark } from '../evidence/marks';
+import { useArtifactList } from './catalog';
+import { FilterBar } from './filters';
+import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
+import { runName } from './parts';
+import { filtered, filterOf, NO_FILTERS } from './search';
+
+const ARTIFACT_ROWS = 50;
+
+/** The Artifacts tab: recorded results that carry evidence, filtered by the address. */
+export function ArtifactsView() {
+  const search = useExplorerSearch();
+  const go = useExplorerNavigate();
+  const filter = useMemo(() => filterOf(search), [search]);
+  const narrow = filtered(search);
+  const answer = useArtifactList(filter);
+  const now = useNow();
+  const [shown, setShown] = useState(ARTIFACT_ROWS);
+  if (answer.isPending)
+    return (
+      <Text role="status" component="div" c="dimmed">
+        Reading the artifacts…
+      </Text>
+    );
+  if (answer.isError)
+    return (
+      <Alert role="alert" color="red" my="sm">
+        The artifacts could not be read. {answer.error.message}
+      </Alert>
+    );
+  if (answer.data.unsupported)
+    return (
+      <Alert role="status" color="blue" my="sm" data-unsupported>
+        This server cannot search artifacts, so nothing is shown here rather than a list that looks narrowed. Update the server to find recordings by tag, type and label; the Tests tab still filters by artifact tag.
+      </Alert>
+    );
+  const { list } = answer.data;
+  return (
+    <Box aria-label="Artifacts" component="section" mb="lg">
+      {(narrow || list.results.length > 0) && <FilterBar facets={list.facets} search={search} tab="artifacts" />}
+      {!list.results.length && !narrow && (
+        <Text component="div" c="dimmed">
+          No recorded result carries evidence yet. Recordings, screenshots and traces published with a result are listed here.
+        </Text>
+      )}
+      {list.results.length > 0 && (
+        <Text role="status" component="div">
+          {list.total > list.results.length
+            ? `The newest ${list.results.length} of ${plural(list.total, 'result', 'results')}${narrow ? ' matching' : ''}`
+            : `${plural(list.results.length, 'result', 'results')}${narrow ? ' matching' : ''}`}
+        </Text>
+      )}
+      {!list.results.length && narrow && (
+        <Stack gap="xs" align="flex-start" role="status" data-no-match>
+          <Text component="div" c="dimmed">
+            Nothing matches these filters.
+          </Text>
+          <Button type="button" variant="light" onClick={() => go(NO_FILTERS)}>
+            Clear filters
+          </Button>
+        </Stack>
+      )}
+      {list.results.length > 0 && (
+        <Table.ScrollContainer minWidth={700}>
+          <Table data-artifacts>
+            <Table.Thead>
+              <Table.Tr>
+                <Table.Th scope="col">Recorded</Table.Th>
+                <Table.Th scope="col">Test</Table.Th>
+                <Table.Th scope="col">Outcome</Table.Th>
+                <Table.Th scope="col">Environment</Table.Th>
+                <Table.Th scope="col">Branch</Table.Th>
+                <Table.Th scope="col">Commit</Table.Th>
+                <Table.Th scope="col">Run</Table.Th>
+                <Table.Th scope="col">Evidence</Table.Th>
+                <Table.Th scope="col">Tags</Table.Th>
+              </Table.Tr>
+            </Table.Thead>
+            <Table.Tbody>
+              {list.results.slice(0, shown).map((result) => {
+                const videos = videoCounts(result.videos);
+                return (
+                  <Table.Tr key={`${result.layer}|${result.key}|${result.kind}|${result.producer}|${result.environment}`} data-status={result.status}>
+                    <Table.Td title={exactTime(result.at)}>{ago(result.at, now)}</Table.Td>
+                    <Table.Td>
+                      <Anchor
+                        aria-label={`Open ${result.title} as recorded in run ${runName(result.run)}`}
+                        renderRoot={(props) => (
+                          <Link
+                            {...props}
+                            to="/"
+                            search={patched({ tab: undefined, openRun: undefined, test: result.key, layer: result.layer })}
+                            resetScroll={false}
+                            activeOptions={{ exact: true }}
+                          />
+                        )}
+                      >
+                        {result.title}
+                      </Anchor>
+                      <Text c="dimmed" fz="xs">
+                        {result.producer}
+                      </Text>
+                    </Table.Td>
+                    <Table.Td>
+                      <StatusMark status={result.status} size={14} /> {statusWord(result.status)}
+                    </Table.Td>
+                    <Table.Td>{environmentLabel(result.environment)}</Table.Td>
+                    <Table.Td c="dimmed">{result.branch ?? '—'}</Table.Td>
+                    <Table.Td>
+                      <Code>{shortSha(result.sha) ?? '—'}</Code>
+                    </Table.Td>
+                    <Table.Td>
+                      <Anchor
+                        aria-label={`Open run ${runName(result.run)}`}
+                        renderRoot={(props) => (
+                          <Link {...props} to="/" search={patched({ tab: 'runs', openRun: result.run, test: undefined, layer: undefined, video: undefined })} resetScroll={false} activeOptions={{ exact: true }} />
+                        )}
+                      >
+                        {runName(result.run)}
+                      </Anchor>
+                    </Table.Td>
+                    <Table.Td>
+                      {result.types.join(', ') || '—'}
+                      {videos && videos.recordings > 0 && (
+                        <Text component="div" size="xs" c="dimmed" data-video="available">
+                          <IconVideo size={16} aria-hidden="true" /> {plural(videos.recordings, 'video', 'videos')}
+                        </Text>
+                      )}
+                    </Table.Td>
+                    <Table.Td data-tags>{result.artifactTags.map((tag) => `#${tag}`).join(' ') || '—'}</Table.Td>
+                  </Table.Tr>
+                );
+              })}
+            </Table.Tbody>
+          </Table>
+        </Table.ScrollContainer>
+      )}
+      {list.results.length > shown && (
+        <Button type="button" onClick={() => setShown(shown + ARTIFACT_ROWS)} variant="subtle">
+          Show more ({list.results.length - shown} more)
+        </Button>
+      )}
+    </Box>
+  );
+}

package/packages/visualizer/src/explorer/Explorer.tsx

@@ -12,6 +12,7 @@ import {
   Flex,
   Group,
   List,
+  MultiSelect,
   NativeSelect,
   Paper,
   SimpleGrid,
@@ -53,8 +54,9 @@ import { useRunDetail, useTestCatalog } from './catalog';
 import { groupTests, tally, type TestGroupView } from './groups';
 import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
 import { Badges, EnvironmentChips, projectTitle, runName } from './parts';
+import { ArtifactsView } from './ArtifactsView';
 import { RunsView } from './RunsView';
-import { narrowed, queryOf, TEST_GROUPS, toggled, values, type ExplorerSearch, type TestGroup } from './search';
+import { joined, narrowed, queryOf, TEST_GROUPS, toggled, values, type ExplorerSearch, type TestGroup } from './search';
 import { TestDetail } from './TestDetail';
 /** Groups start closed when there are more of them than this, unless the list is short. */
 const OPEN_GROUPS = 40;
@@ -132,7 +134,7 @@ export function Explorer() {
   const model = catalog.model;
   const selected = search.test ? (model?.byKey.get(search.test) ?? null) : null;
   const empty = model !== null && model.tests.length === 0;
-  const split = !!search.test && search.tab !== 'runs';
+  const split = !!search.test && search.tab !== 'runs' && search.tab !== 'artifacts';
   return (
     <Container size="xl" py="xl">
       <Box aria-label="Test explorer" component="article" miw={0}>
@@ -143,7 +145,7 @@ export function Explorer() {
           {model && model.tests.length > 0 && (
             <Tabs
               value={search.tab ?? 'tests'}
-              onChange={(value) => go({ tab: value === 'runs' ? 'runs' : undefined, test: undefined, openRun: undefined, layer: undefined })}
+              onChange={(value) => go({ tab: value === 'runs' || value === 'artifacts' ? value : undefined, test: undefined, openRun: undefined, layer: undefined })}
             >
               <Tabs.List aria-label="Explorer view">
                 <Tabs.Tab
@@ -166,6 +168,7 @@ export function Explorer() {
                 >
                   Runs
                 </Tabs.Tab>
+                <Tabs.Tab value="artifacts">Artifacts</Tabs.Tab>
               </Tabs.List>
             </Tabs>
           )}
@@ -224,6 +227,8 @@ export function Explorer() {
           listing &&
           (search.tab === 'runs' ? (
             <RunsView />
+          ) : search.tab === 'artifacts' ? (
+            <ArtifactsView />
           ) : (
             <>
               <InsightStrip model={model} scope={listing.scope} search={search} />
@@ -506,6 +511,7 @@ function Toolbar({
   const chips = [
     ...values(search.spec).map((path) => ({ label: `Spec: ${specTitle(path)}`, clear: { spec: toggled(search.spec, path) } })),
     ...values(search.tag).map((tag) => ({ label: `Tag: ${tag}`, clear: { tag: toggled(search.tag, tag) } })),
+    ...values(search.artifactTag).map((tag) => ({ label: `Artifact tag: #${tag}`, clear: { artifactTag: toggled(search.artifactTag, tag) } })),
     ...(search.inRun ? [{ label: `Run: ${runName(search.inRun)}`, clear: { inRun: undefined } }] : [])
   ];
   return (
@@ -614,6 +620,23 @@ function Toolbar({
             </NativeSelect>
           </Box>
         )}
+        {((model.facets.artifactTags?.length ?? 0) > 0 || values(search.artifactTag).length > 0) && (
+          <MultiSelect
+            aria-label="Artifact tag"
+            placeholder={values(search.artifactTag).length ? undefined : 'Any artifact tag'}
+            data={[
+              ...(model.facets.artifactTags ?? []).map(({ value, count }) => ({ value, label: `#${value} (${count})` })),
+              ...values(search.artifactTag)
+                .filter((tag) => !model.facets.artifactTags?.some((facet) => facet.value === tag))
+                .map((tag) => ({ value: tag, label: `#${tag} (0)` }))
+            ]}
+            value={values(search.artifactTag)}
+            searchable
+            clearable
+            nothingFoundMessage="Nothing found"
+            onChange={(next) => go({ artifactTag: joined(next) })}
+          />
+        )}
         {model.facets.domains.length > 1 && (
           <Box component="label">
             <VisuallyHidden>Domain</VisuallyHidden>
@@ -659,6 +682,8 @@ function Toolbar({
                 domain: undefined,
                 spec: undefined,
                 tag: undefined,
+                artifactTag: undefined,
+                inherited: undefined,
                 inRun: undefined
               });
             }}

package/packages/visualizer/src/explorer/RunsView.tsx

@@ -12,14 +12,17 @@ import { Alert, Anchor, Box, Button, Code, Flex, Group, List, Stack, Table, Text
 import { videoCounts } from '@crvouga/atlas/reports/evidence-detail';
 import type { VideoCounts, VideoRef } from '@crvouga/atlas/reports/evidence-types';
 import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
+import type { FilterName } from '@crvouga/atlas/reports/artifact-query';
 import { formatMs, type RunResult, type RunSummary } from '@crvouga/atlas/reports/test-catalog';
 import { Link } from '@tanstack/react-router';
 import { useMemo, useState } from 'react';
 import { ago, exactTime, plural, shortSha, statusWord, useNow } from '../evidence/format';
 import { Meter, StatusMark } from '../evidence/marks';
 import { useRunDetail, useRunList } from './catalog';
+import { FilterBar } from './filters';
 import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
 import { runName } from './parts';
+import { filtered, filterOf, NO_FILTERS } from './search';
 const RUN_ROWS = 50;
 const RESULT_ROWS = 200;
 /** The Runs tab: the run list, or the run opened in it. */
@@ -118,11 +121,25 @@ function HasVideo({ count, pressed, noun, onToggle }: { count: number; pressed:
     </Button>
   );
 }
+/** What a filter is called when a page says a server could not apply it. */
+const FILTER_WORDS: Partial<Record<FilterName, string>> = { artifactTag: 'tag', type: 'media type', label: 'label', domain: 'domain', spec: 'spec' };
+/** Says which filters the list is not narrowed by, because the server that answered ignored them. */
+export function NotApplied({ names, noun }: { names: readonly FilterName[]; noun: string }) {
+  if (!names.length) return null;
+  return (
+    <Alert role="status" color="blue" my="sm" data-not-applied>
+      This server cannot filter {noun} by {names.map((name) => FILTER_WORDS[name] ?? name).join(', ')}, so the list below is not narrowed by {names.length > 1 ? 'them' : 'it'}. Update the server to use{' '}
+      {names.length > 1 ? 'these filters' : 'this filter'}.
+    </Alert>
+  );
+}
 function RunTable() {
   const search = useExplorerSearch();
   const go = useExplorerNavigate();
   const video = search.video === true;
-  const runs = useRunList(true, video);
+  const filter = useMemo(() => filterOf(search), [search]);
+  const narrow = filtered(search);
+  const runs = useRunList(true, filter);
   const now = useNow();
   const [shown, setShown] = useState(RUN_ROWS);
   if (runs.isPending)
@@ -139,29 +156,34 @@ function RunTable() {
     );
   const list = runs.data.runs;
   const withVideo = runs.data.withVideo;
-  if (!list.length && !video)
-    return (
-      <Text component="div" c="dimmed">
-        No runs recorded yet.
-      </Text>
-    );
-  const noun = video ? 'with a video' : '';
+  const noun = narrow ? 'matching' : '';
   return (
     <Box aria-label="Runs" component="section" mb="lg">
-      <Flex gap="xs" align="center" wrap="wrap">
-        {runs.data.total > list.length
-          ? `The newest ${list.length} of ${plural(runs.data.total, 'run', 'runs')} ${noun}`.trim()
-          : `${plural(list.length, 'run', 'runs')} ${noun}`.trim()}
-        {(withVideo !== undefined || video) && (
-          <HasVideo count={withVideo ?? list.length} pressed={video} noun={['run', 'runs']} onToggle={() => go({ video: video ? undefined : true })} />
-        )}
-      </Flex>
-      {!list.length && (
+      {(narrow || list.length > 0) && <FilterBar facets={runs.data.facets} search={search} tab="runs" extra={withVideo !== undefined || video ? <HasVideo count={withVideo ?? list.length} pressed={video} noun={['run', 'runs']} onToggle={() => go({ video: video ? undefined : true })} /> : undefined} />}
+      <NotApplied names={runs.data.notApplied} noun="runs" />
+      {!list.length && !narrow && (
         <Text component="div" c="dimmed">
-          No run has a playable video recording.{' '}
-          {runs.data.withVideo === undefined && 'This server does not report which runs have recordings.'}
+          No runs recorded yet.
+        </Text>
+      )}
+      {list.length > 0 && (
+        <Text role="status" component="div">
+          {runs.data.total > list.length
+            ? `The newest ${list.length} of ${plural(runs.data.total, 'run', 'runs')} ${noun}`.trim()
+            : `${plural(list.length, 'run', 'runs')} ${noun}`.trim()}
         </Text>
       )}
+      {!list.length && narrow && (
+        <Stack gap="xs" align="flex-start" role="status" data-no-match>
+          <Text component="div" c="dimmed">
+            No run matches these filters.
+            {video && withVideo === undefined && ' This server does not report which runs have recordings.'}
+          </Text>
+          <Button type="button" variant="light" onClick={() => go(NO_FILTERS)}>
+            Clear filters
+          </Button>
+        </Stack>
+      )}
       <Table.ScrollContainer minWidth={600}>
         <Table data-runs>
           <Table.Thead>
@@ -174,6 +196,7 @@ function RunTable() {
               <Table.Th scope="col">Outcomes</Table.Th>
               <Table.Th scope="col">Span</Table.Th>
               <Table.Th scope="col">Video</Table.Th>
+              <Table.Th scope="col">Tags</Table.Th>
               <Table.Th scope="col">
                 <VisuallyHidden>CI run</VisuallyHidden>
               </Table.Th>
@@ -215,6 +238,7 @@ function RunTable() {
                 <Table.Td>
                   <RunVideos run={run} />
                 </Table.Td>
+                <Table.Td data-tags>{run.artifactTags?.map((tag) => `#${tag}`).join(' ') || '—'}</Table.Td>
                 <Table.Td>
                   {run.runUrl ? (
                     <Anchor href={run.runUrl} target="_blank" rel="noreferrer">

package/packages/visualizer/src/explorer/catalog.tsx

@@ -17,13 +17,25 @@ import type { EvidenceStatus } from '@crvouga/atlas/reports/explorer-types';
 import type { LayerEvidence, LayerRows, StatusCounts } from '@crvouga/atlas/reports/evidence-types';
 import type { CheckSlot, EvidenceView } from '@crvouga/atlas/reports/evidence-view';
 import {
+  facetsOf,
+  filterParams,
+  forRuns,
+  matchesFilter,
+  usedFilters,
+  type ArtifactFilter,
+  type FilterName,
+  type QueryFacets
+} from '@crvouga/atlas/reports/artifact-query';
+import {
+  artifactList,
   catalogModel,
+  fieldsOfRun,
   haystackOf,
-  hasVideo,
   runDetail,
   runList,
   testHistory,
   TestHistory,
+  type ArtifactList,
   type CatalogModel,
   type RunDetail,
   type RunList,
@@ -40,6 +52,8 @@ import { useEvidence } from '../evidence/evidence-context';
 
 /** How many runs the Runs tab lists. */
 export const RUNS_SHOWN = 500;
+/** How many recorded results the Artifacts tab lists. */
+export const ARTIFACTS_SHOWN = 200;
 /** The server's catalog is read again at most this often while results keep arriving. */
 const SERVER_REREAD_MS = 5_000;
 /** Layers read one after another are folded into the page's catalog at most this often. */
@@ -234,24 +248,95 @@ export function useTestHistory(key: string | undefined) {
   });
 }
 
+/** The runs a query matched, and what this server could not do about it. */
+export type RunsAnswer = RunList & {
+  /** What the viewer's query asks for that the answer does not reflect: filters an older server ignores and the viewer cannot apply itself (tags, types, labels need data it does not send). Say so; never present the list as narrowed by them. */
+  readonly notApplied: readonly FilterName[];
+  /** The values each dimension offers, from the server or worked out from the runs it sent. */
+  readonly facets: QueryFacets;
+};
+
+/** What an older server's run summary can answer by itself: the viewer filters its complete list for these. */
+const ANSWERABLE_HERE: ReadonlySet<FilterName> = new Set(['q', 'environment', 'producer', 'branch', 'sha', 'outcome', 'since', 'until', 'video']);
+
 /**
- * CI runs, newest first. With `video`, only the runs that have a playable video recording: the server filters every run
- * before it pages them, so the count is the whole dataset's. A server that does not know the parameter answers with
- * every run (and no video information), which is filtered here.
+ * Makes a server's answer honest about the filters it did not apply (an older server ignores parameters it does not know
+ * and answers with every run). Those the run summary can answer are applied here, to the complete list; the rest are
+ * reported in `notApplied` so the page can say the list is not narrowed by them.
  */
-export function useRunList(enabled = true, video = false) {
+export function runsAnswer(list: RunList, filter: ArtifactFilter): RunsAnswer {
+  const asked = usedFilters(forRuns(filter)).filter((name) => name !== 'inherited');
+  // A server that predates `filters` but has `withVideo` already filtered by `video`.
+  const applied = new Set<FilterName>(list.filters ?? (list.withVideo !== undefined ? ['video'] : []));
+  const missing = asked.filter((name) => !applied.has(name));
+  if (!missing.length && list.facets) return { ...list, facets: list.facets, notApplied: [] };
+  const here = missing.filter((name) => ANSWERABLE_HERE.has(name));
+  const sub = Object.fromEntries(here.map((name) => [name, filter[name]])) as ArtifactFilter;
+  const runs = here.length ? list.runs.filter((run) => matchesFilter(fieldsOfRun(run), sub)) : list.runs;
+  return {
+    ...list,
+    total: here.length ? runs.length : list.total,
+    runs,
+    facets: list.facets ?? facetsOf(list.runs.map(fieldsOfRun), sub),
+    notApplied: missing.filter((name) => !ANSWERABLE_HERE.has(name))
+  };
+}
+
+/**
+ * CI runs, newest first, narrowed by a query (see `artifact-query.ts`). The server filters every run before it pages
+ * them, so counts are the whole dataset's; a server that does not know a filter is handled by {@link runsAnswer}.
+ */
+export function useRunList(enabled = true, filter: ArtifactFilter = {}) {
   const catalog = useTestCatalog();
+  const query = forRuns(filter);
+  const key = filterParams(query).toString();
   return useQuery({
-    queryKey: ['test-runs', catalog.version, video],
-    queryFn: async ({ signal }): Promise<RunList> => {
+    queryKey: ['test-runs', catalog.version, key],
+    queryFn: async ({ signal }): Promise<RunsAnswer> => {
       if (catalog.source === 'server') {
-        const list = await reportJson<RunList>(`/runs?limit=${RUNS_SHOWN}${video ? '&video=true' : ''}`, signal);
-        if (!video || list.withVideo !== undefined) return list;
-        const runs = list.runs.filter(hasVideo);
-        return { ...list, total: runs.length, runs };
+        const params = filterParams(query);
+        params.set('limit', String(RUNS_SHOWN));
+        return runsAnswer(await reportJson<RunList>(`/runs?${params}`, signal), query);
       }
       const history = catalog.model?.history;
-      return history ? runList(history, catalog.version, RUNS_SHOWN, { video }) : { schemaVersion: 1, version: catalog.version, total: 0, runs: [] };
+      const list = history ? runList(history, catalog.version, RUNS_SHOWN, query) : { schemaVersion: 1 as const, version: catalog.version, total: 0, runs: [] };
+      return runsAnswer(list, query);
+    },
+    enabled: enabled && catalog.model !== null,
+    placeholderData: keepPreviousData,
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false
+  });
+}
+
+/** The recorded results that carry evidence and match a query, or `unsupported` when the server has no artifact search. */
+export type ArtifactsAnswer = { readonly unsupported: false; readonly list: ArtifactList } | { readonly unsupported: true };
+
+/**
+ * Recorded results that carry evidence (recordings, screenshots, traces) across the whole history, newest first. A
+ * server without `/artifacts` (an older one) answers `unsupported`, and the page says so instead of showing an empty list.
+ */
+export function useArtifactList(filter: ArtifactFilter, enabled = true) {
+  const catalog = useTestCatalog();
+  const key = filterParams(filter).toString();
+  return useQuery({
+    queryKey: ['test-artifacts', catalog.version, key],
+    queryFn: async ({ signal }): Promise<ArtifactsAnswer> => {
+      if (catalog.source === 'server') {
+        const params = filterParams(filter);
+        params.set('limit', String(ARTIFACTS_SHOWN));
+        try {
+          return { unsupported: false, list: await reportJson<ArtifactList>(`/artifacts?${params}`, signal) };
+        } catch (error) {
+          if (notFound(error)) return { unsupported: true };
+          throw error;
+        }
+      }
+      const model = catalog.model!;
+      const domains = new Map(model.facets.specs.map((spec) => [spec.path, spec.domain]));
+      const history = model.history;
+      if (!history) return { unsupported: true };
+      return { unsupported: false, list: artifactList(history, catalog.version, filter, { limit: ARTIFACTS_SHOWN, domainOf: (path) => domains.get(path) }) };
     },
     enabled: enabled && catalog.model !== null,
     placeholderData: keepPreviousData,