@crvouga/atlas 1.2.0 → 1.3.0

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

@@ -1,5 +1,6 @@
 import type { CheckDetail, EvidenceHolder } from '@crvouga/atlas/reports/evidence-detail';
-import { roleOfType } from '@crvouga/atlas/reports/evidence-detail';
+import { isVideoAttachment, roleOfType } from '@crvouga/atlas/reports/evidence-detail';
+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';
@@ -8,7 +9,8 @@ import { useQuery } from '@tanstack/react-query';
 import { useMemo, type ReactNode } from 'react';
 import { ArtifactTagList, ArtifactTagsProvider, TagFilterBar, useFilteredAttachments } from './artifact-tags';
 import { reportAssetUrl, reportJson, reportText } from './api';
-import { duration, plural } from './format';
+import { ScopeNotice, ScopeProvider, useScope } from './evidence-scope';
+import { duration, plural, safeUri } from './format';
 import { StatusMark } from './marks';
 /**
  * How one kind of attachment is shown. The first renderer that matches wins, so a new kind of artifact (a
@@ -33,16 +35,6 @@ export type ArtifactRenderer = {
 const mediaType = (attachment: Attachment) =>
   (attachment.contentType ?? contentTypeOf(attachment.name)).split(';')[0]!.trim().toLowerCase();
 const label = (attachment: Attachment) => attachment.description ?? attachment.name;
-/** Only addresses a browser may follow: never `javascript:` or `data:` from a producer. */
-function safeUri(uri: string | undefined): string | null {
-  if (!uri) return null;
-  try {
-    const url = new URL(uri, 'https://atlas.invalid/');
-    return url.protocol === 'http:' || url.protocol === 'https:' ? uri : null;
-  } catch {
-    return null;
-  }
-}
 function TextValue({ attachment, path }: { attachment: Attachment; path: string | null }) {
   const stored = useQuery({
     queryKey: ['artifact-text', path ?? ''],
@@ -146,8 +138,12 @@ 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 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)}>
+      {scoped && <ScopeNotice scope={scope} name={attachment.name} />}
       {body}
       <Box component="figcaption">
         <Text span inherit fw={600}>
@@ -300,7 +296,7 @@ function Tries({ attempts, layer }: { attempts: readonly Attempt[]; layer: strin
       </Title>
       <List spacing="xs" listStyleType="none" type="ordered">
         {attempts.map((attempt) => (
-          <List.Item key={attempt.index}>
+          <List.Item key={attempt.index} data-attempt={attempt.index}>
             <Flex gap="xs" align="center" wrap="wrap">
               <StatusMark status={attempt.status} size={14} />
               <Text span inherit>
@@ -312,7 +308,9 @@ function Tries({ attempts, layer }: { attempts: readonly Attempt[]; layer: strin
               </Text>
             </Flex>
             {attempt.detail && <Text component="div">{attempt.detail}</Text>}
-            {attempt.attachments && <Attachments attachments={attempt.attachments} layer={layer} />}
+            <ScopeProvider scope={attempt.scope}>
+              {attempt.attachments && <Attachments attachments={attempt.attachments} layer={layer} />}
+            </ScopeProvider>
           </List.Item>
         ))}
       </List>
@@ -371,14 +369,14 @@ function Facts({ holder }: { holder: EvidenceHolder }) {
 }
 function Evidence({ holder, layer, steps }: { holder: EvidenceHolder; layer: string; steps?: boolean }) {
   return (
-    <>
+    <ScopeProvider scope={holder.scope}>
       <Facts holder={holder} />
       {holder.annotations && <Notes notes={holder.annotations} />}
       {steps && holder.steps && holder.steps.length > 0 && <Timeline steps={holder.steps} layer={layer} />}
       {holder.attempts && holder.attempts.length > 1 && <Tries attempts={holder.attempts} layer={layer} />}
       {holder.attachments && <Attachments attachments={holder.attachments} layer={layer} />}
       {holder.extensions && <Raw extensions={holder.extensions} />}
-    </>
+    </ScopeProvider>
   );
 }
 /** Everything one result carries beyond its outcome, read when it is opened, and what the run around it carried. */
@@ -408,7 +406,8 @@ export function ResultEvidence({ layer, row }: { layer: LayerHeader; row: LayerR
         What this result carries could not be read.
       </Text>
     );
-  const { check, run } = detail.data;
+  const { check, run, inheritedScope } = detail.data;
+  const declared = effectiveScope(check.scope, inheritedScope);
   const hasRun = Object.values(run).some((value) =>
     Array.isArray(value) ? value.length > 0 : value && typeof value === 'object' ? Object.keys(value).length > 0 : false
   );
@@ -416,7 +415,14 @@ export function ResultEvidence({ layer, row }: { layer: LayerHeader; row: LayerR
     <ArtifactTagsProvider layer={layer.id} kind={row.kind} check={row.id} holders={[check, run]}>
       <Stack aria-label="Evidence" gap="sm" miw={0}>
         <TagFilterBar holders={[check, run]} />
-        <Evidence holder={check} layer={layer.id} steps />
+        {declared && (
+          <Box aria-label="Scope of this result" component="section">
+            <ScopeNotice scope={declared} name={row.title} />
+          </Box>
+        )}
+        <ScopeProvider scope={inheritedScope}>
+          <Evidence holder={check} layer={layer.id} steps />
+        </ScopeProvider>
         {hasRun && (
           <Box aria-label="From the run" component="section" mb="lg">
             <Title order={4} mb="sm">

package/packages/visualizer/src/evidence/evidence-scope.tsx

@@ -0,0 +1,106 @@
+import { scopeBadges, scopeCaveats, scopeFacts, type ScopeBasis } from '@crvouga/atlas/reports/evidence-scope';
+import type { EvidenceScope } from '@crvouga/atlas/schema';
+import { Accordion, Anchor, Badge, Group, List, Stack, Table, Text } from '@mantine/core';
+import { createContext, useContext, type ReactNode } from 'react';
+import { safeUri } from './format';
+
+/** The scope declared by the nearest holder around an attachment: its attempt, its check, or the run. */
+const Around = createContext<EvidenceScope | undefined>(undefined);
+
+/**
+ * Makes `scope` the one that applies to the attachments inside, unless it is undefined, in which case the scope
+ * declared further out still applies. The nearest declaration wins as a whole and is never mixed with another.
+ */
+export function ScopeProvider({ scope, children }: { scope: EvidenceScope | undefined; children: ReactNode }) {
+  const outer = useContext(Around);
+  return <Around.Provider value={scope ?? outer}>{children}</Around.Provider>;
+}
+
+/** The scope in effect here, undefined when none was declared. */
+export function useScope(): EvidenceScope | undefined {
+  return useContext(Around);
+}
+
+const BASIS_WORD: Record<ScopeBasis, string> = { verified: 'Verified', declared: 'Declared', undeclared: 'Not declared' };
+
+/**
+ * What a recording does and does not show, in the producer's declaration: concise badges that are visible before it
+ * is played, and the exact declaration, caveats and provenance on demand. A recording that declared nothing says its
+ * scope is unknown. `scope` is the declaration that applies to this one source (see `effectiveScope`).
+ */
+export function ScopeNotice({ scope, name }: { scope: EvidenceScope | undefined; name: string }) {
+  const badges = scopeBadges(scope);
+  const unknown = badges[0]?.dimension === 'unknown';
+  const links = (scope?.provenance ?? []).flatMap((link) => {
+    const url = safeUri(link.url);
+    return url ? [{ url, label: link.name ?? link.rel ?? link.url }] : [];
+  });
+  return (
+    <Stack gap="xs" aria-label={`Evidence scope of ${name}`} data-scope={unknown ? 'unknown' : 'declared'} mb="xs">
+      <Group gap="xs" role="list" aria-label="Scope badges">
+        {badges.map((badge) => (
+          <Badge
+            key={badge.text}
+            role="listitem"
+            variant={badge.basis === 'verified' ? 'filled' : 'light'}
+            color={unknown ? 'gray' : undefined}
+            tt="none"
+            data-basis={badge.basis}
+          >
+            {badge.text}
+            {badge.basis === 'verified' ? ' (verified)' : ''}
+          </Badge>
+        ))}
+      </Group>
+      <Accordion variant="separated">
+        <Accordion.Item value="scope">
+          <Accordion.Control>Scope details</Accordion.Control>
+          <Accordion.Panel>
+            <Stack gap="sm">
+              <Table.ScrollContainer minWidth={280}>
+                <Table aria-label="Declared scope">
+                  <Table.Thead>
+                    <Table.Tr>
+                      <Table.Th>Dimension</Table.Th>
+                      <Table.Th>Value</Table.Th>
+                      <Table.Th>Basis</Table.Th>
+                    </Table.Tr>
+                  </Table.Thead>
+                  <Table.Tbody>
+                    {scopeFacts(scope).map((fact) => (
+                      <Table.Tr key={fact.dimension}>
+                        <Table.Td>{fact.label}</Table.Td>
+                        <Table.Td>{fact.value}</Table.Td>
+                        <Table.Td>{BASIS_WORD[fact.basis]}</Table.Td>
+                      </Table.Tr>
+                    ))}
+                  </Table.Tbody>
+                </Table>
+              </Table.ScrollContainer>
+              <Text component="div">
+                {unknown ? 'The producer declared no scope for this recording. ' : scope?.declaredBy ? `Declared by ${scope.declaredBy}. ` : 'The producer declared this; Atlas did not check it. '}
+                {scope?.verified?.length ? `Verified by ${scope.verifiedBy ?? 'something independent of the producer'}: ${scope.verified.join(', ')}.` : ''}
+              </Text>
+              <List aria-label="What this does not show" spacing="xs">
+                {scopeCaveats(scope).map((caveat) => (
+                  <List.Item key={caveat}>{caveat}</List.Item>
+                ))}
+              </List>
+              {links.length > 0 && (
+                <List aria-label="Provenance" spacing="xs">
+                  {links.map((link) => (
+                    <List.Item key={link.url}>
+                      <Anchor href={link.url} target="_blank" rel="noreferrer">
+                        {link.label}
+                      </Anchor>
+                    </List.Item>
+                  ))}
+                </List>
+              )}
+            </Stack>
+          </Accordion.Panel>
+        </Accordion.Item>
+      </Accordion>
+    </Stack>
+  );
+}

package/packages/visualizer/src/evidence/format.ts

@@ -54,3 +54,14 @@ export function useNow(everyMs = 30_000) {
   }, [everyMs]);
   return now;
 }
+
+/** Only addresses a browser may follow: never `javascript:` or `data:` from a producer. */
+export function safeUri(uri: string | undefined): string | null {
+  if (!uri) return null;
+  try {
+    const url = new URL(uri, 'https://atlas.invalid/');
+    return url.protocol === 'http:' || url.protocol === 'https:' ? uri : null;
+  } catch {
+    return null;
+  }
+}

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

@@ -511,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.scope).map((token) => ({ label: `Scope: ${token}`, clear: { scope: toggled(search.scope, token) } })),
     ...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 } }] : [])
   ];
@@ -654,6 +655,23 @@ function Toolbar({
             </NativeSelect>
           </Box>
         )}
+        {(model.facets.scopes?.length ?? 0) > 0 && (
+          <Box component="label">
+            <VisuallyHidden>Recording scope</VisuallyHidden>
+            <NativeSelect
+              aria-label="Recording scope"
+              value=""
+              onChange={(event) => event.target.value && go({ scope: toggled(search.scope, event.target.value) })}
+            >
+              <option value="">Any recording scope</option>
+              {model.facets.scopes!.filter(({ value }) => !values(search.scope).includes(value)).map(({ value, count }) => (
+                <option key={value} value={value}>
+                  {value === 'unknown' ? 'Scope unknown' : value} ({count})
+                </option>
+              ))}
+            </NativeSelect>
+          </Box>
+        )}
       </Flex>
       <Flex role="status" gap="xs" align="center" wrap="wrap">
         <Text span inherit>
@@ -682,6 +700,7 @@ function Toolbar({
                 domain: undefined,
                 spec: undefined,
                 tag: undefined,
+                scope: undefined,
                 artifactTag: undefined,
                 inherited: undefined,
                 inRun: undefined

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

@@ -35,6 +35,8 @@ export const ExplorerSearchFields = {
   domain: text,
   spec: text,
   tag: text,
+  /** Only tests with one recording that declares every one of these scope tokens (`device:physical,audio:recorded`). */
+  scope: text,
   /** Artifact tags (`demo`, shown `#demo`): tests with an attachment carrying one; runs and artifacts likewise. */
   artifactTag: text,
   /** With `artifactTag`: also the tags attachments inherit from their check and run. */
@@ -74,6 +76,7 @@ export type ExplorerSearch = {
   readonly domain?: string;
   readonly spec?: string;
   readonly tag?: string;
+  readonly scope?: string;
   readonly artifactTag?: string;
   readonly inherited?: true;
   readonly type?: string;
@@ -117,6 +120,7 @@ export function queryOf(search: ExplorerSearch): TestQuery {
     domain: values(search.domain),
     spec: values(search.spec),
     tag: values(search.tag),
+    ...(values(search.scope).length ? { scope: values(search.scope) } : {}),
     artifactTag: values(search.artifactTag),
     ...(search.inherited ? { inherited: true } : {}),
     sort: search.sort ?? 'spec'
@@ -130,7 +134,7 @@ export function explorerSearch(search: Record<string, unknown>): ExplorerSearch
 
 /** True when any filter or search narrows the list. */
 export function narrowed(search: ExplorerSearch): boolean {
-  return !!(search.q || search.status || search.env || search.producer || search.domain || search.spec || search.tag || search.artifactTag || search.inRun);
+  return !!(search.q || search.status || search.env || search.producer || search.domain || search.spec || search.tag || search.scope || search.artifactTag || search.inRun);
 }
 
 /** The filters of the Runs and Artifacts tabs, in the address. */