@crvouga/atlas 0.11.0 → 0.13.0

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

@@ -143,7 +143,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 })}
+              onChange={(value) => go({ tab: value === 'runs' ? 'runs' : undefined, test: undefined, openRun: undefined, layer: undefined })}
             >
               <Tabs.List aria-label="Explorer view">
                 <Tabs.Tab
@@ -247,7 +247,7 @@ export function Explorer() {
             </>
           ))}
       </Box>
-      <Drawer opened={split} onClose={() => go({ test: undefined })} title="Test detail" size="xl">
+      <Drawer opened={split} onClose={() => go({ test: undefined, layer: undefined })} title="Test detail" size="xl">
         <Box aria-label="Test detail" component="aside">
           {selected ? (
             <TestDetail test={selected} slot={slots.get(selected.key)} />
@@ -258,7 +258,7 @@ export function Explorer() {
               </Alert>
               <Anchor
                 renderRoot={(props) => (
-                  <Link {...props} to="/" search={patched({ test: undefined })} resetScroll={false} activeOptions={{ exact: true }} />
+                  <Link {...props} to="/" search={patched({ test: undefined, layer: undefined })} resetScroll={false} activeOptions={{ exact: true }} />
                 )}
               >
                 Close
@@ -358,7 +358,7 @@ function InsightStrip({ model, scope, search }: { model: CatalogModel; scope: re
                 <Link
                   {...props}
                   to="/"
-                  search={patched({ tab: 'runs', test: undefined })}
+                  search={patched({ tab: 'runs', test: undefined, layer: undefined })}
                   resetScroll={false}
                   activeOptions={{ exact: true }}
                 />
@@ -443,7 +443,7 @@ function MoreInsights({ scope }: { scope: readonly TestSummary[] }) {
             <List.Item key={test.key}>
               <Anchor
                 renderRoot={(props) => (
-                  <Link {...props} to="/" search={patched({ test: test.key })} resetScroll={false} activeOptions={{ exact: true }} />
+                  <Link {...props} to="/" search={patched({ test: test.key, layer: undefined })} resetScroll={false} activeOptions={{ exact: true }} />
                 )}
               >
                 <StatusMark status={test.status} size={12} />
@@ -819,7 +819,7 @@ function TestRow({ test, selected, now }: { test: TestSummary; selected: boolean
           <Link
             {...props}
             to="/"
-            search={patched({ test: selected ? undefined : test.key })}
+            search={patched({ test: selected ? undefined : test.key, layer: undefined })}
             resetScroll={false}
             activeOptions={{ exact: true }}
           />

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

@@ -262,7 +262,7 @@ function RunDetailView({ runKey }: { runKey: string }) {
             <Link
               {...props}
               to="/"
-              search={patched({ tab: undefined, openRun: undefined, inRun: run.key, test: undefined })}
+              search={patched({ tab: undefined, openRun: undefined, inRun: run.key, test: undefined, layer: undefined })}
               resetScroll={false}
               activeOptions={{ exact: true }}
             />
@@ -328,7 +328,7 @@ function RunDetailView({ runKey }: { runKey: string }) {
                     <Link
                       {...props}
                       to="/"
-                      search={patched({ tab: undefined, openRun: undefined, test: result.key })}
+                      search={patched({ tab: undefined, openRun: undefined, test: result.key, layer: result.layer })}
                       resetScroll={false}
                       activeOptions={{ exact: true }}
                     />

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

@@ -1,5 +1,5 @@
 import { IconX, IconCircleFilled } from '@tabler/icons-react';
-import { Alert, Anchor, Box, Button, Code, Flex, SimpleGrid, Stack, Table, Text, Title, VisuallyHidden } from '@mantine/core';
+import { Alert, Anchor, Badge, Box, Button, Code, Flex, SimpleGrid, Stack, Table, Text, Title, VisuallyHidden } from '@mantine/core';
 /**
  * @module Test detail
  *
@@ -10,27 +10,127 @@ import { Alert, Anchor, Box, Button, Code, Flex, SimpleGrid, Stack, Table, Text,
  */
 import type { CheckSlot } from '@crvouga/atlas/reports/evidence-view';
 import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
-import { formatMs, type TestResultEntry, type TestSummary } from '@crvouga/atlas/reports/test-catalog';
+import { formatMs, runKey, type TestResultEntry, type TestSummary } from '@crvouga/atlas/reports/test-catalog';
 import { Link } from '@tanstack/react-router';
 import { lazy, Suspense, useState } from 'react';
-import { CheckDetail, type CheckSelection } from '../evidence/check-detail';
+import { CheckDetail } from '../evidence/check-detail';
 import { ago, exactTime, plural, shortSha, statusWord, useNow } from '../evidence/format';
-import { StatusMark } from '../evidence/marks';
+import { useEvidence } from '../evidence/evidence-context';
+import { Origin, StatusMark } from '../evidence/marks';
 import { useTestHistory } from './catalog';
-import { patched } from './navigate';
-import { Badges } from './parts';
+import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
+import { Badges, runName } from './parts';
+import { usePinnedResult, type PinnedResult } from './pinned';
 const RecordingPage = lazy(() => import('../evidence/recording-page').then((module) => ({ default: module.RecordingPage })));
 /** Results the history table shows before "Show more". */
 const HISTORY_ROWS = 20;
 function percent(rate: number | null): string {
   return rate === null ? '—' : `${Math.round(rate * 100)}%`;
 }
+/** Switches the detail from one pinned result back to the latest combined evidence. */
+function LatestLink({ children }: { children: string }) {
+  return (
+    <Anchor
+      renderRoot={(props) => (
+        <Link {...props} to="/" search={patched({ layer: undefined })} resetScroll={false} activeOptions={{ exact: true }} />
+      )}
+    >
+      {children}
+    </Anchor>
+  );
+}
+
+/**
+ * Says which evidence the detail shows: this one run's result (pinned by the address), or the latest combined evidence.
+ * The change from one to the other is always an explicit link, so a result never turns into another silently.
+ */
+function Scope({ pinned, slot }: { pinned: PinnedResult; slot: CheckSlot | undefined }) {
+  const { backends } = useEvidence();
+  const now = useNow();
+  if (pinned.state === 'none')
+    return (
+      <Flex aria-label="Evidence scope" role="group" gap="xs" align="center" wrap="wrap" mb="lg">
+        <Badge variant="light">Latest combined evidence</Badge>
+        <Text span inherit c="dimmed">
+          The newest result of each environment, which can come from different runs. Open a run to see exactly what it recorded.
+        </Text>
+      </Flex>
+    );
+  if (pinned.state === 'loading')
+    return (
+      <Text role="status" component="div" c="dimmed" mb="lg">
+        Reading the result of the run you opened…
+      </Text>
+    );
+  if (pinned.state === 'missing')
+    return (
+      <Alert color="blue" title="That result is not available" mb="lg">
+        <Stack gap="xs">
+          <Text span inherit>
+            {pinned.reason} No other result is shown in its place.
+          </Text>
+          <LatestLink>Show latest combined evidence</LatestLink>
+        </Stack>
+      </Alert>
+    );
+  const { layer } = pinned.entry;
+  const newer = slot?.outcomes.find(
+    (outcome) =>
+      outcome.layer.id !== layer.id &&
+      outcome.layer.recordedAtMs > layer.recordedAtMs &&
+      outcome.layer.producer === layer.producer &&
+      outcome.layer.environment === layer.environment &&
+      JSON.stringify(outcome.parameters) === JSON.stringify(pinned.entry.row.variant)
+  );
+  const key = runKey(layer);
+  return (
+    <Alert color="blue" title={`This run: ${runName(key)}`} mb="lg">
+      <Stack gap="xs">
+        <Flex gap="xs" align="center" wrap="wrap">
+          <Text span inherit fw={600}>
+            {layer.producer}
+          </Text>
+          <Origin layer={layer} backends={backends} now={now} />
+        </Flex>
+        <Text span inherit>
+          The evidence below is what this run recorded. The current results, statistics and history are about the latest combined evidence
+          across runs.
+        </Text>
+        {newer && (
+          <Text span inherit role="status">
+            A newer result exists: {statusWord(newer.row.status)} {ago(newer.layer.recordedAtMs, now)}.
+          </Text>
+        )}
+        <Flex gap="md" align="center" wrap="wrap">
+          <LatestLink>Show latest combined evidence</LatestLink>
+          <Anchor
+            renderRoot={(props) => (
+              <Link
+                {...props}
+                to="/"
+                search={patched({ tab: 'runs', openRun: key, test: undefined, layer: undefined })}
+                resetScroll={false}
+                activeOptions={{ exact: true }}
+              />
+            )}
+          >
+            Back to run {runName(key)}
+          </Anchor>
+        </Flex>
+      </Stack>
+    </Alert>
+  );
+}
+
 /** The open test. `slot` is the report's check for it, when the page holds one, for its evidence. */
 export function TestDetail({ test, slot }: { test: TestSummary; slot: CheckSlot | undefined }) {
   const now = useNow();
   const history = useTestHistory(test.key);
-  const [selection, setSelection] = useState<CheckSelection>({});
+  const { layer } = useExplorerSearch();
+  const go = useExplorerNavigate();
+  const pinned = usePinnedResult(layer, test.key);
   const [recording, setRecording] = useState(false);
+  const [recordingLayer, setRecordingLayer] = useState<string | undefined>(undefined);
   const [moment, setMoment] = useState<number | null>(null);
   const [rows, setRows] = useState(HISTORY_ROWS);
   const entries = history.data?.history ?? [];
@@ -47,7 +147,8 @@ export function TestDetail({ test, slot }: { test: TestSummary; slot: CheckSlot
       >
         <RecordingPage
           slot={slot}
-          layerId={selection.layer}
+          layerId={recordingLayer ?? layer}
+          entry={pinned.state === 'ready' && (recordingLayer ?? layer) === pinned.entry.layer.id ? pinned.entry : undefined}
           label={test.title}
           back="Test detail"
           moment={moment}
@@ -63,7 +164,7 @@ export function TestDetail({ test, slot }: { test: TestSummary; slot: CheckSlot
         <Anchor
           aria-label="Close the test"
           renderRoot={(props) => (
-            <Link {...props} to="/" search={patched({ test: undefined })} resetScroll={false} activeOptions={{ exact: true }} />
+            <Link {...props} to="/" search={patched({ test: undefined, layer: undefined })} resetScroll={false} activeOptions={{ exact: true }} />
           )}
         >
           <IconX size={20} aria-hidden="true" />
@@ -123,6 +224,8 @@ export function TestDetail({ test, slot }: { test: TestSummary; slot: CheckSlot
         </Code>
       </Box>
 
+      <Scope pinned={pinned} slot={slot} />
+
       <Box aria-label="Current results" component="section" mb="lg">
         <Title order={3} mb="sm" c="dimmed">
           Current result per environment
@@ -314,21 +417,26 @@ export function TestDetail({ test, slot }: { test: TestSummary; slot: CheckSlot
 
       <Box aria-label="Evidence" component="section" mb="lg">
         <Title order={3} mb="sm" c="dimmed">
-          What the current result carries
+          {layer ? 'What this run recorded' : 'What the current result carries'}
         </Title>
-        {slot ? (
+        {slot && (!layer || pinned.state === 'ready') ? (
           <CheckDetail
             slot={slot}
-            layerId={selection.layer}
+            layerId={layer}
+            {...(pinned.state === 'ready' ? { pinned: pinned.entry, pin: true } : {})}
             reads="steps"
             select={(patch) => {
-              setSelection({ check: patch.check ?? slot.id, layer: patch.layer ?? undefined });
               if (patch.view === 'recording') {
+                setRecordingLayer(patch.layer ?? undefined);
                 setRecording(true);
                 setMoment(null);
-              }
+              } else go({ layer: patch.layer ?? undefined });
             }}
           />
+        ) : layer ? (
+          <Text component="div" c="dimmed">
+            {pinned.state === 'missing' ? 'There is no evidence to show for that run.' : 'Reading the evidence of that run…'}
+          </Text>
         ) : (
           <Text component="div" c="dimmed">
             The evidence of this result is not loaded in this page.
@@ -362,6 +470,9 @@ export function TestDetail({ test, slot }: { test: TestSummary; slot: CheckSlot
                   <Table.Th scope="col">Branch</Table.Th>
                   <Table.Th scope="col">Commit</Table.Th>
                   <Table.Th scope="col">Detail</Table.Th>
+                  <Table.Th scope="col">
+                    <VisuallyHidden>Evidence</VisuallyHidden>
+                  </Table.Th>
                 </Table.Tr>
               </Table.Thead>
               <Table.Tbody>
@@ -396,6 +507,23 @@ export function TestDetail({ test, slot }: { test: TestSummary; slot: CheckSlot
                     <Table.Td title={entry.detail} c="dimmed">
                       {entry.detail.split('\n')[0]}
                     </Table.Td>
+                    <Table.Td>
+                      <Anchor
+                        aria-label={`Open the ${statusWord(entry.status)} result recorded ${ago(entry.at, now)} in ${environmentLabel(entry.environment)}`}
+                        aria-current={entry.layer === layer ? 'true' : undefined}
+                        renderRoot={(props) => (
+                          <Link
+                            {...props}
+                            to="/"
+                            search={patched({ layer: entry.layer })}
+                            resetScroll={false}
+                            activeOptions={{ exact: true }}
+                          />
+                        )}
+                      >
+                        Open this result
+                      </Anchor>
+                    </Table.Td>
                   </Table.Tr>
                 ))}
               </Table.Tbody>

package/packages/visualizer/src/explorer/pinned.ts

@@ -0,0 +1,91 @@
+/**
+ * @module Pinned result
+ *
+ * Opening a test from a run, or choosing an earlier run in its history, pins the detail to one exact layer: the
+ * `layer` parameter of the explorer's address. This finds that layer's own record of the open check, wherever the
+ * viewer holds it: in the evidence it already read, or, on a server that sends only the winners, from the layer
+ * itself. A layer that cannot be found is reported as missing, never replaced by another result.
+ */
+import { checkHistory, type HistoryEntry } from '@crvouga/atlas/reports/evidence-view';
+import type { EvidencePage, LayerHeader, LayerRows } from '@crvouga/atlas/reports/evidence-types';
+import { isDiagnosticKind, slotKey } from '@crvouga/atlas/reports/layer-merge';
+import { useQuery } from '@tanstack/react-query';
+import { useMemo } from 'react';
+
+import { reportJson } from '../evidence/api';
+import { useEvidence } from '../evidence/evidence-context';
+
+/** What the viewer knows of the pinned result. `none` when nothing is pinned. */
+export type PinnedResult =
+  | { readonly state: 'none' }
+  | { readonly state: 'loading' }
+  | { readonly state: 'missing'; readonly reason: string }
+  | { readonly state: 'ready'; readonly entry: HistoryEntry };
+
+/** The most layer-header pages read looking for a pinned layer on a server. */
+const MAX_PAGES = 200;
+
+/** A test key (`TestSummary.key`) as the spec path and check id it names, or null when it is not one. */
+export function checkOfKey(key: string): { path: string | null; id: string } | null {
+  try {
+    const parsed: unknown = JSON.parse(key);
+    if (Array.isArray(parsed) && typeof parsed[0] === 'string' && typeof parsed[1] === 'string') return { path: parsed[0] || null, id: parsed[1] };
+  } catch {
+    /* not a check key */
+  }
+  return null;
+}
+
+/** One layer's record of one check, preferring a verdict over a timing, as `checkHistory` does. */
+function recordOf(layer: LayerHeader, rows: LayerRows, key: string): HistoryEntry | null {
+  const own = rows.rows.filter((row) => slotKey(row.specPath ?? '', row.id) === key);
+  const row = own.find((candidate) => !isDiagnosticKind(candidate.kind)) ?? own[0];
+  return row ? { layer, row } : null;
+}
+
+async function readLayer(layerId: string, key: string, signal: AbortSignal): Promise<HistoryEntry> {
+  let cursor: string | null = null;
+  let header: LayerHeader | undefined;
+  for (let page = 0; page < MAX_PAGES && !header; page++) {
+    const read: EvidencePage = await reportJson<EvidencePage>(`/evidence${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ''}`, signal);
+    header = read.layers.find((layer) => layer.id === layerId);
+    cursor = read.cursor;
+    if (!cursor) break;
+  }
+  if (!header) throw new Error('That run is not in the report any more. Its source may be switched off or have expired.');
+  const rows = await reportJson<LayerRows>(`/evidence/rows/${encodeURIComponent(header.backend)}/${encodeURIComponent(header.id)}`, signal);
+  const entry = recordOf(header, rows, key);
+  if (!entry) throw new Error('That run no longer holds a result for this test.');
+  return entry;
+}
+
+/**
+ * The record of the check `testKey` made by the layer `layerId`.
+ *
+ * @param layerId - The pinned layer (the `layer` address parameter), or undefined for the latest combined evidence.
+ * @param testKey - The open test's key.
+ * @returns `none` without a layer, `loading` while it is being found, `ready` with its entry, or `missing` with why.
+ */
+export function usePinnedResult(layerId: string | undefined, testKey: string): PinnedResult {
+  const { evidence, effective, ready, pending, unavailable } = useEvidence();
+  const check = useMemo(() => checkOfKey(testKey), [testKey]);
+  const local = useMemo(
+    () => (layerId && check ? checkHistory(evidence, check.path, check.id).find((entry) => entry.layer.id === layerId) : undefined),
+    [evidence, layerId, check]
+  );
+  const remote = useQuery({
+    queryKey: ['pinned-result', layerId ?? '', testKey],
+    queryFn: ({ signal }) => readLayer(layerId!, testKey, signal),
+    enabled: !!layerId && !local && effective && ready,
+    staleTime: 5 * 60_000,
+    retry: false
+  });
+  if (!layerId) return { state: 'none' };
+  if (local) return { state: 'ready', entry: local };
+  if (unavailable) return { state: 'missing', reason: unavailable };
+  if (!ready) return { state: 'loading' };
+  if (!effective) return pending > 0 ? { state: 'loading' } : { state: 'missing', reason: 'That run is not in the report any more. Its source may be switched off or have expired.' };
+  if (remote.data) return { state: 'ready', entry: remote.data };
+  if (remote.isError) return { state: 'missing', reason: remote.error.message };
+  return { state: 'loading' };
+}

package/packages/visualizer/src/explorer/search.ts

@@ -2,7 +2,7 @@
  * @module Explorer address
  *
  * Everything the test explorer shows is in the address of the `/` route, so a link reproduces the view: the open test,
- * the words searched, the filters, the grouping, the order, and the Runs tab with the run opened in it. Filters that
+ * the words searched, the filters, the grouping, the order, the Runs tab with the run opened in it, and the exact layer a test's detail is pinned to. Filters that
  * take several values are comma-separated (`status=failed,flaky`). Anything unreadable is dropped, never an error.
  */
 import { TEST_SORTS, type TestQuery, type TestSort } from '@crvouga/atlas/reports/test-catalog';
@@ -36,7 +36,9 @@ export const ExplorerSearchFields = {
   sort: z.enum(TEST_SORTS).optional().catch(undefined),
   tab: z.enum(['runs']).optional().catch(undefined),
   /** The run opened in the Runs tab. */
-  openRun: text
+  openRun: text,
+  /** Pins the open test's detail to one exact layer (a run's record of it), instead of the latest combined evidence. */
+  layer: text
 };
 
 /** The explorer's search parameters as the route holds them. */
@@ -54,6 +56,7 @@ export type ExplorerSearch = {
   readonly sort?: TestSort;
   readonly tab?: 'runs';
   readonly openRun?: string;
+  readonly layer?: string;
 };
 
 /** The values of a comma-separated filter, empty when it is not set. */