@crvouga/atlas 1.19.0 → 1.20.0

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

@@ -1,4 +1,4 @@
-import { IconAlertTriangle, IconArrowLeft, IconPlayerPlay, IconVideo } from '@tabler/icons-react';
+import { IconAlertTriangle, IconArrowLeft, IconCheck, IconPlayerPlay, IconVideo } from '@tabler/icons-react';
 import { Alert, Anchor, Badge, Box, Button, Code, Flex, Group, List, NativeSelect, Stack, Table, Text, TextInput, Title, VisuallyHidden } from '@mantine/core';
 /**
  * @module Runs view
@@ -23,7 +23,8 @@ import { hasFilters, passesFilters, type ParsedSearch, type SearchFilters } from
 import type { FindDoc, Ranked } from '../find/rank';
 import { ago, exactTime, plural, shortSha, statusWord, useNow } from '../evidence/format';
 import { Meter, StatusMark } from '../evidence/marks';
-import { useRunDetail, useRunList, useTestCatalog } from './catalog';
+import { useRecordingVerification, useRunDetail, useRunList, useTestCatalog } from './catalog';
+import { allStoredVideosGone, verificationOfRun, type RunVerification } from './recording-verification';
 import { RunArtifacts } from './RunArtifacts';
 import { entriesFromRun } from './playlist-entries';
 import { WatchPlaylist } from './playlist';
@@ -126,9 +127,30 @@ function RunRecordings({ run }: { run: RunSummary }) {
     </Badge>
   );
 }
+/**
+ * What the server's read-back says about a run's stored videos, apart from its test outcomes: some are gone or damaged
+ * (an orange mark that names the problems), or all were read back and are as published. Nothing when they were never
+ * read back: an unverified run is not shown as verified.
+ */
+function StoredVideos({ verification }: { verification: RunVerification | null }) {
+  if (!verification) return null;
+  const at = `Read back from storage ${exactTime(verification.atMs)}. This checks the stored files, not playback in a browser. The test outcomes are unaffected.`;
+  if (verification.gaps === 0)
+    return (
+      <Text component="div" size="xs" c="dimmed" title={at} data-stored-videos="verified">
+        <IconCheck size={16} aria-hidden="true" /> {verification.checked > 0 ? `${plural(verification.ok, 'stored video', 'stored videos')} verified` : 'No stored videos to verify'}
+      </Text>
+    );
+  return (
+    <Text component="div" size="xs" c="orange.9" title={at} data-stored-videos="unavailable">
+      <IconAlertTriangle size={16} aria-hidden="true" /> Recording unavailable: {verification.gaps} of {plural(verification.checked, 'stored video', 'stored videos')} failed the read-back ({verification.problems.join(', ')}).
+    </Text>
+  );
+}
 /** A run's videos in its row: a link to the recordings, how many references they come from, and what cannot be played. */
-function RunVideos({ run }: { run: RunSummary }) {
+function RunVideos({ run, verification }: { run: RunSummary; verification: RunVerification | null }) {
   const videos = run.videos;
+  const gone = videos !== undefined && allStoredVideosGone(verification, videos.recordings);
   const files = run.attachments ? (
     <Anchor
       aria-label={`Open the ${plural(run.attachments, 'file', 'files')} of run ${runName(run.key)}`}
@@ -151,9 +173,9 @@ function RunVideos({ run }: { run: RunSummary }) {
       </Stack>
     );
   return (
-    <Stack gap={0} data-video={videos.recordings > 0 ? 'available' : 'unavailable'}>
+    <Stack gap={0} data-video={videos.recordings > 0 && !gone ? 'available' : 'unavailable'}>
       {files}
-      {videos.recordings > 0 && (
+      {videos.recordings > 0 && !gone && (
         <Anchor
           aria-label={`Watch ${plural(videos.recordings, 'recording', 'recordings')} in run ${runName(run.key)}`}
           renderRoot={(props) => (
@@ -169,6 +191,7 @@ function RunVideos({ run }: { run: RunSummary }) {
         </Text>
       )}
       <Unavailable videos={videos} />
+      <StoredVideos verification={verification} />
     </Stack>
   );
 }
@@ -258,6 +281,7 @@ function RunTable() {
   }, [search]);
   const narrow = filtered(search);
   const runs = useRunList(true, filter, searching);
+  const stored = useRecordingVerification();
   const now = useNow();
   const [shown, setShown] = useState(RUN_ROWS);
   const docs = useMemo(() => (runs.data?.runs ?? []).map((run) => runDoc(run, runLabel(run))), [runs.data]);
@@ -406,7 +430,7 @@ function RunTable() {
                 </Table.Td>
                 <Table.Td>{formatMs(run.spanMs)}</Table.Td>
                 <Table.Td>
-                  <RunVideos run={run} />
+                  <RunVideos run={run} verification={verificationOfRun(stored.data, run.key)} />
                   <RunRecordings run={run} />
                 </Table.Td>
                 <Table.Td data-tags>{run.artifactTags?.map((tag) => `#${tag}`).join(' ') || '—'}</Table.Td>
@@ -461,6 +485,7 @@ function RunDetailView({ runKey }: { runKey: string }) {
   const go = useExplorerNavigate();
   const video = search.video === true;
   const detail = useRunDetail(runKey);
+  const stored = useRecordingVerification();
   const now = useNow();
   const [status, setStatus] = useState('');
   const [shown, setShown] = useState(RESULT_ROWS);
@@ -598,6 +623,7 @@ function RunDetailView({ runKey }: { runKey: string }) {
           <Unavailable videos={run.videos} />
         </Text>
       )}
+      <StoredVideos verification={verificationOfRun(stored.data, run.key)} />
       <RunArtifacts detail={detail.data} />
       <Flex gap="xs" align="center" wrap="wrap">
         <Anchor

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

@@ -44,7 +44,7 @@ import {
   type TestHistoryDocument,
   type TestSummary
 } from '@crvouga/atlas/reports/test-catalog';
-import { isStatechartFile } from '@crvouga/atlas/schema';
+import { isStatechartFile, type RecordingVerification } from '@crvouga/atlas/schema';
 import { keepPreviousData, useQuery } from '@tanstack/react-query';
 import { createContext, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 
@@ -373,6 +373,29 @@ export function useRunDetail(key: string | undefined) {
   });
 }
 
+/**
+ * What the server last read back of the stored videos, per layer (`GET /recordings/verification`; see
+ * `recording-verification.ts`). The question is only asked of a server, never reads a blob, and an older server (no route)
+ * or an unanswered request means nothing is known: `null`, which is never shown as verified.
+ */
+export function useRecordingVerification() {
+  const catalog = useTestCatalog();
+  return useQuery({
+    queryKey: ['recording-verification', catalog.version],
+    queryFn: async ({ signal }): Promise<RecordingVerification | null> => {
+      try {
+        return await reportJson<RecordingVerification>('/recordings/verification', signal);
+      } catch (error) {
+        if (signal.aborted) throw error;
+        return null;
+      }
+    },
+    enabled: catalog.source === 'server',
+    staleTime: 30_000,
+    retry: false
+  });
+}
+
 /** What the Catalog health tab reads: the diagnostics, or that this server is too old to give them. */
 export type HealthAnswer = { readonly unsupported: false; readonly health: CatalogHealth } | { readonly unsupported: true };
 

package/packages/visualizer/src/explorer/recording-verification.ts

@@ -0,0 +1,58 @@
+/**
+ * @module Recording verification of a run
+ *
+ * What the server's read-back of stored videos says about one run, for the Runs tab: how many of its stored videos were
+ * read back, how many passed, and which problems the others have. It is evidence about storage, kept apart from the run's
+ * test outcomes: it never changes how a run is counted, and "never read back" is `null`, not "verified".
+ */
+import type { RecordingVerification } from '@crvouga/atlas/schema';
+
+/** The words for each way a stored recording can be wrong; an unknown problem is still a gap and is named as it came. */
+const PROBLEMS: Readonly<Record<string, string>> = {
+  'blob-missing': 'file gone from storage',
+  'not-in-bundle': 'file missing from the run’s bundle',
+  unreadable: 'storage could not be read',
+  'size-mismatch': 'size differs from what was published',
+  'checksum-mismatch': 'content differs from what was published',
+  undecodable: 'not the video format it claims to be'
+};
+
+/** What was read back of one run's stored recordings. */
+export type RunVerification = {
+  /** Videos read back: those that name a stored file. */
+  readonly checked: number;
+  readonly ok: number;
+  /** Each problem in words, with how many videos have it, most common first. */
+  readonly problems: readonly string[];
+  readonly gaps: number;
+  /** When the server last read the run's layers back, epoch milliseconds (the oldest of them). */
+  readonly atMs: number;
+};
+
+/**
+ * What the read-back found for the run with this key, or `null` when none of its layers was read back (the page then says
+ * nothing about its stored files). A run is as unavailable as its worst layer: gaps add up across its layers.
+ */
+export function verificationOfRun(document: RecordingVerification | null | undefined, runKey: string): RunVerification | null {
+  const layers = document?.layers.filter((layer) => layer.run === runKey) ?? [];
+  if (!layers.length) return null;
+  const counts = new Map<string, number>();
+  let checked = 0, ok = 0, gaps = 0, atMs = Infinity;
+  for (const layer of layers) {
+    checked += layer.checked;
+    ok += layer.ok;
+    atMs = Math.min(atMs, layer.verifiedAtMs);
+    for (const gap of layer.gaps) {
+      gaps += 1;
+      const word = PROBLEMS[gap.problem] ?? gap.problem;
+      counts.set(word, (counts.get(word) ?? 0) + 1);
+    }
+  }
+  const problems = [...counts].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).map(([word, count]) => `${count} ${word}`);
+  return { checked, ok, problems, gaps, atMs };
+}
+
+/** Whether a run's stored videos were read back and none of them can be played: its Watch action would lead nowhere. */
+export function allStoredVideosGone(verification: RunVerification | null, playable: number): boolean {
+  return verification !== null && verification.gaps > 0 && verification.ok === 0 && verification.checked >= playable;
+}