@crvouga/atlas 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",

package/packages/schema/schemas/check-detail.schema.json

@@ -1645,6 +1645,30 @@
       "additionalProperties": {},
       "description": "What the run as a whole carries: its logs, links, labels, annotations, scope and extensions"
     },
+    "parts": {
+      "description": "Without `check` only: the parts of the layer that carry files or links of their own, each with what it carries. Absent when none",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "kind",
+          "id",
+          "title"
+        ],
+        "additionalProperties": {}
+      }
+    },
     "inheritedScope": {
       "description": "The scope the check inherits: its part's declaration, else its layer's. Absent when neither declared one: unknown, not live or physical",
       "type": "object",

package/packages/schema/schemas/report-run.schema.json

@@ -171,6 +171,12 @@
           ],
           "additionalProperties": {}
         },
+        "attachments": {
+          "description": "Files attached to the run itself, in its layers, not to a check. Absent when there are none",
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
         "artifactTags": {
           "description": "The normalized tags of the attachments of its results, sorted and distinct. Absent when none is tagged, and in reports of older servers",
           "type": "array",
@@ -431,6 +437,85 @@
         ],
         "additionalProperties": {}
       }
+    },
+    "layers": {
+      "description": "Every layer of the run, oldest first. Absent from an older server",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The layer id; read its files with `/api/reports/evidence/detail/{backend}/{id}`"
+          },
+          "backend": {
+            "type": "string"
+          },
+          "producer": {
+            "type": "string"
+          },
+          "environment": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "recordedAtMs": {
+            "type": "number"
+          },
+          "checks": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "How many checks the layer recorded. Zero means evidence only, not a pass"
+          },
+          "attachments": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "Files the layer carries as a whole, not those of its checks"
+          },
+          "videos": {
+            "type": "object",
+            "properties": {
+              "references": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Every reference to a video; identical bytes referenced twice count twice"
+              },
+              "recordings": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Distinct playable recordings"
+              },
+              "unavailable": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "References that name no bytes"
+              }
+            },
+            "required": [
+              "references",
+              "recordings",
+              "unavailable"
+            ],
+            "additionalProperties": {}
+          }
+        },
+        "required": [
+          "id",
+          "backend",
+          "producer",
+          "environment",
+          "recordedAtMs",
+          "checks",
+          "attachments"
+        ],
+        "additionalProperties": {}
+      }
     }
   },
   "required": [

package/packages/schema/schemas/report-runs.schema.json

@@ -179,6 +179,12 @@
             ],
             "additionalProperties": {}
           },
+          "attachments": {
+            "description": "Files attached to the run itself, in its layers, not to a check. Absent when there are none",
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
           "artifactTags": {
             "description": "The normalized tags of the attachments of its results, sorted and distinct. Absent when none is tagged, and in reports of older servers",
             "type": "array",

package/packages/server/openapi.json

@@ -5299,7 +5299,7 @@
           "Report"
         ],
         "summary": "Every test one run recorded",
-        "description": "One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.\n\nRole needed: `read`.",
+        "description": "One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer's files with `/api/reports/evidence/detail/{backend}/{id}`. Send `format=markdown` for Markdown.\n\nRole needed: `read`.",
         "x-atlas-role": "read",
         "security": [
           {
@@ -5409,7 +5409,7 @@
           "Report"
         ],
         "summary": "Every test one run recorded",
-        "description": "One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.\n\nScoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.\n\nRole needed: `read`.",
+        "description": "One run and its last result for every test, environment and producer it recorded, failures first, and `layers`: each layer of the run with its backend, how many checks it recorded (zero means evidence only, never a pass) and how many files it carries as a whole. Open a layer's files with `/api/reports/evidence/detail/{backend}/{id}`. Send `format=markdown` for Markdown.\n\nScoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.\n\nRole needed: `read`.",
         "x-atlas-role": "read",
         "security": [
           {
@@ -6093,7 +6093,7 @@
           "Report"
         ],
         "summary": "Everything one result carries",
-        "description": "The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.\n\nRole needed: `read`.",
+        "description": "The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.\n\nRole needed: `read`.",
         "x-atlas-role": "read",
         "security": [
           {
@@ -6195,7 +6195,7 @@
           "Report"
         ],
         "summary": "Everything one result carries",
-        "description": "The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.\n\nScoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.\n\nRole needed: `read`.",
+        "description": "The timeline, annotations, retries, attachments and extensions of one check, and what its run carries as a whole. Without `check`, only the run's, and `parts`: what each part of the layer that carries files or links of its own holds. Attachment bytes are fetched from `/api/reports/layers/{id}/blobs/{bundleKey}`.\n\nScoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.\n\nRole needed: `read`.",
         "x-atlas-role": "read",
         "security": [
           {
@@ -15767,6 +15767,30 @@
             "additionalProperties": {},
             "description": "What the run as a whole carries: its logs, links, labels, annotations, scope and extensions"
           },
+          "parts": {
+            "description": "Without `check` only: the parts of the layer that carry files or links of their own, each with what it carries. Absent when none",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "kind": {
+                  "type": "string"
+                },
+                "id": {
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "kind",
+                "id",
+                "title"
+              ],
+              "additionalProperties": {}
+            }
+          },
           "inheritedScope": {
             "description": "The scope the check inherits: its part's declaration, else its layer's. Absent when neither declared one: unknown, not live or physical",
             "type": "object",
@@ -18974,6 +18998,12 @@
                   ],
                   "additionalProperties": {}
                 },
+                "attachments": {
+                  "description": "Files attached to the run itself, in its layers, not to a check. Absent when there are none",
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "maximum": 9007199254740991
+                },
                 "artifactTags": {
                   "description": "The normalized tags of the attachments of its results, sorted and distinct. Absent when none is tagged, and in reports of older servers",
                   "type": "array",
@@ -19928,6 +19958,12 @@
                 ],
                 "additionalProperties": {}
               },
+              "attachments": {
+                "description": "Files attached to the run itself, in its layers, not to a check. Absent when there are none",
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              },
               "artifactTags": {
                 "description": "The normalized tags of the attachments of its results, sorted and distinct. Absent when none is tagged, and in reports of older servers",
                 "type": "array",
@@ -20188,6 +20224,85 @@
               ],
               "additionalProperties": {}
             }
+          },
+          "layers": {
+            "description": "Every layer of the run, oldest first. Absent from an older server",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "The layer id; read its files with `/api/reports/evidence/detail/{backend}/{id}`"
+                },
+                "backend": {
+                  "type": "string"
+                },
+                "producer": {
+                  "type": "string"
+                },
+                "environment": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "recordedAtMs": {
+                  "type": "number"
+                },
+                "checks": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991,
+                  "description": "How many checks the layer recorded. Zero means evidence only, not a pass"
+                },
+                "attachments": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991,
+                  "description": "Files the layer carries as a whole, not those of its checks"
+                },
+                "videos": {
+                  "type": "object",
+                  "properties": {
+                    "references": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991,
+                      "description": "Every reference to a video; identical bytes referenced twice count twice"
+                    },
+                    "recordings": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991,
+                      "description": "Distinct playable recordings"
+                    },
+                    "unavailable": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991,
+                      "description": "References that name no bytes"
+                    }
+                  },
+                  "required": [
+                    "references",
+                    "recordings",
+                    "unavailable"
+                  ],
+                  "additionalProperties": {}
+                }
+              },
+              "required": [
+                "id",
+                "backend",
+                "producer",
+                "environment",
+                "recordedAtMs",
+                "checks",
+                "attachments"
+              ],
+              "additionalProperties": {}
+            }
           }
         },
         "required": [

package/packages/visualizer/src/evidence/artifacts.tsx

@@ -4,9 +4,9 @@ import { effectiveScope } from '@crvouga/atlas/reports/evidence-scope';
 import type { LayerHeader, LayerRow } from '@crvouga/atlas/reports/evidence-types';
 import { contentTypeOf } from '@crvouga/atlas/reports/media-types';
 import type { Annotation, Attachment, Attempt, Step } from '@crvouga/atlas/schema';
-import { Accordion, Alert, Anchor, Box, Code, Flex, Image, List, Stack, Text, Title } from '@mantine/core';
+import { Accordion, Alert, Anchor, Badge, Box, Code, Flex, Image, List, Stack, Text, Title } from '@mantine/core';
 import { useQuery } from '@tanstack/react-query';
-import { useMemo, type ReactNode } from 'react';
+import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { ArtifactTagList, ArtifactTagsProvider, TagFilterBar, useFilteredAttachments } from './artifact-tags';
 import { reportAssetUrl, reportJson, reportText } from './api';
 import { ScopeNotice, ScopeProvider, useScope } from './evidence-scope';
@@ -35,6 +35,23 @@ export type ArtifactRenderer = {
 const mediaType = (attachment: Attachment) =>
   (attachment.contentType ?? contentTypeOf(attachment.name)).split(';')[0]!.trim().toLowerCase();
 const label = (attachment: Attachment) => attachment.description ?? attachment.name;
+/** A video that plays inline; when the file cannot be loaded or this browser cannot play it, it says so and offers the file, instead of an empty player. */
+function VideoPlayer({ attachment, url }: { attachment: Attachment; url: string }) {
+  const [failed, setFailed] = useState(false);
+  if (failed)
+    return (
+      <Alert role="alert" color="orange" title="This video cannot be played">
+        <Text component="div">
+          {label(attachment)} could not be loaded, or this browser cannot play its format. Nothing is wrong with the report: the file may be missing from the
+          store or in an unsupported codec.{' '}
+          <Anchor href={url} download={attachment.name} target="_blank" rel="noreferrer">
+            Download {attachment.name}
+          </Anchor>
+        </Text>
+      </Alert>
+    );
+  return <Box src={url} controls preload="metadata" aria-label={label(attachment)} component="video" maw="100%" w="100%" onError={() => setFailed(true)} />;
+}
 function TextValue({ attachment, path }: { attachment: Attachment; path: string | null }) {
   const stored = useQuery({
     queryKey: ['artifact-text', path ?? ''],
@@ -92,8 +109,7 @@ export const artifactRenderers: ArtifactRenderer[] = [
     id: 'video',
     wide: true,
     matches: (_, type) => type.startsWith('video/'),
-    render: (a, { url }) =>
-      url ? <Box src={url} controls preload="metadata" aria-label={label(a)} component="video" maw="100%" w="100%" /> : null
+    render: (a, { url }) => (url ? <VideoPlayer attachment={a} url={url} /> : null)
   },
   {
     id: 'audio',
@@ -130,7 +146,13 @@ function sizeOf(bytes: number | undefined) {
   if (bytes < 1024) return `${bytes} B`;
   return bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(0)} KiB` : `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
 }
-function Artifact({ attachment, layer }: { attachment: Attachment; layer: string }) {
+/**
+ * One attachment as a card: it plays or shows itself when it can, and always says what it is (name, role, type, size,
+ * duration, tags) and how to get it. A file that has no address, has an address that is not a web address, or that
+ * nothing can preview says so in words. Pass `link` for a control that opens this one artifact, `note` for how it
+ * relates to the rest of the report, and `selected` to mark the one a link pointed at (it scrolls into view).
+ */
+export function ArtifactCard({ attachment, layer, link, note, selected }: { attachment: Attachment; layer: string; link?: ReactNode; note?: ReactNode; selected?: boolean }) {
   const type = mediaType(attachment);
   const path = attachment.bundleKey
     ? `/layers/${encodeURIComponent(layer)}/blobs/${attachment.bundleKey.split('/').map(encodeURIComponent).join('/')}`
@@ -138,17 +160,28 @@ function Artifact({ attachment, layer }: { attachment: Attachment; layer: string
   const url = path ? reportAssetUrl(path) : safeUri(attachment.uri);
   const renderer = artifactRenderers.find((candidate) => candidate.matches(attachment, type));
   const body = renderer?.render(attachment, { url, path, type });
+  const item = useRef<HTMLLIElement>(null);
+  useEffect(() => {
+    if (selected) item.current?.scrollIntoView?.({ block: 'center' });
+  }, [selected]);
   const scope = effectiveScope(attachment.scope, useScope());
   // A recording says what it shows before it is played; evidence that declared a scope of its own says so too.
   const scoped = isVideoAttachment(attachment) || attachment.scope !== undefined;
   return (
-    <List.Item data-wide={renderer?.wide || undefined} data-role={attachment.role ?? roleOfType(type)}>
+    <List.Item
+      ref={item}
+      data-wide={renderer?.wide || undefined}
+      data-role={attachment.role ?? roleOfType(type)}
+      data-selected={selected || undefined}
+      {...(selected ? { bg: 'blue.0', p: 'sm', bd: '2px solid var(--mantine-color-blue-6)' } : {})}
+    >
       {scoped && <ScopeNotice scope={scope} name={attachment.name} />}
       {body}
       <Box component="figcaption">
         <Text span inherit fw={600}>
           {attachment.name}
         </Text>
+        {selected && <Badge variant="light">Selected</Badge>}
         {attachment.role && (
           <Text span inherit>
             {attachment.role}
@@ -162,12 +195,21 @@ function Artifact({ attachment, layer }: { attachment: Attachment; layer: string
             {body ? 'Download' : 'Open'}
           </Anchor>
         )}
-        {!url && attachment.text === undefined && (
-          <Text span inherit>
-            No file to show
-          </Text>
-        )}
+        {link}
       </Box>
+      {!url && attachment.text === undefined && (
+        <Alert role={selected ? 'alert' : undefined} color="orange" data-unavailable my="xs">
+          {attachment.uri
+            ? 'No file to show. This file is only given by an address that is not a web address, so Atlas will not follow it. Ask the producer for a web address or to upload the file.'
+            : 'No file to show. The report lists this file, but it was never stored, so it cannot be shown or downloaded. Publish it again with the file attached.'}
+        </Alert>
+      )}
+      {url && !renderer && (
+        <Text component="div" c="dimmed" data-no-preview>
+          Atlas has no preview for this kind of file. Open or download it to inspect it.
+        </Text>
+      )}
+      {note}
       <ArtifactTagList attachment={attachment} />
     </List.Item>
   );
@@ -182,7 +224,7 @@ export function Attachments({ attachments: all, layer }: { attachments: readonly
       </Title>
       <List spacing="xs" listStyleType="none">
         {attachments.map((attachment, index) => (
-          <Artifact key={`${attachment.id ?? attachment.name}:${index}`} attachment={attachment} layer={layer} />
+          <ArtifactCard key={`${attachment.id ?? attachment.name}:${index}`} attachment={attachment} layer={layer} />
         ))}
       </List>
     </Box>

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

@@ -142,10 +142,10 @@ export function Explorer() {
           <Title order={1} mb="sm">
             {projectTitle()}
           </Title>
-          {model && model.tests.length > 0 && (
+          {model && (model.tests.length > 0 || model.summary.runs > 0) && (
             <Tabs
               value={search.tab ?? 'tests'}
-              onChange={(value) => go({ tab: value === 'runs' || value === 'artifacts' ? value : undefined, test: undefined, openRun: undefined, layer: undefined })}
+              onChange={(value) => go({ tab: value === 'runs' || value === 'artifacts' ? value : undefined, test: undefined, openRun: undefined, layer: undefined, artifact: undefined })}
             >
               <Tabs.List aria-label="Explorer view">
                 <Tabs.Tab
@@ -212,7 +212,12 @@ export function Explorer() {
             Loading tests…
           </Text>
         )}
-        {empty && !kinds.length && (
+        {empty && model && model.summary.runs > 0 && search.tab !== 'runs' && (
+          <Text component="div" c="dimmed">
+            No test results recorded, but {model.summary.runs === 1 ? '1 run carries' : `${model.summary.runs} runs carry`} files. Open the Runs tab to see them.
+          </Text>
+        )}
+        {empty && !kinds.length && !(model && model.summary.runs > 0) && (
           <Text component="div" c="dimmed">
             No reports yet. Publish tests and specs to this project to populate its report.
           </Text>
@@ -223,13 +228,12 @@ export function Explorer() {
           </Text>
         )}
         {model &&
-          !empty &&
           listing &&
           (search.tab === 'runs' ? (
             <RunsView />
           ) : search.tab === 'artifacts' ? (
             <ArtifactsView />
-          ) : (
+          ) : empty ? null : (
             <>
               <InsightStrip model={model} scope={listing.scope} search={search} />
               <Toolbar