@crvouga/atlas 1.3.0 → 1.5.0

package/packages/visualizer/src/evidence/behavior-panel.tsx

@@ -0,0 +1,291 @@
+/**
+ * @module Behavior panel
+ *
+ * How a product reader meets one behavior of a feature: Read (the promise and what is expected, with an outline's
+ * concrete example filled in), Watch (the matched recording beside what it should show) and Inspect (the technical
+ * record: run, environment, source, attempts). Also the coverage summary of the whole feature. A recording is always
+ * labelled as illustrative evidence with its own status, provenance and revision; it never stands for approval.
+ */
+import type { EvidenceHolder } from '@crvouga/atlas/reports/evidence-detail';
+import { isVideoAttachment } from '@crvouga/atlas/reports/evidence-detail';
+import { effectiveScope } from '@crvouga/atlas/reports/evidence-scope';
+import type { EvidenceResult } from '@crvouga/atlas/reports/layer-merge';
+import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
+import type { Attachment } from '@crvouga/atlas/schema';
+import { Alert, Badge, Box, Group, List, Paper, Stack, Tabs, Text, Title } from '@mantine/core';
+import { useMemo, type ReactNode } from 'react';
+
+import { attachmentSource, useCheckDetail } from './artifacts';
+import { COVERAGE, COVERAGE_ORDER, type Behavior, type CoverageCounts, type CoverageState, type Revision } from './behavior';
+import { PlainSteps } from './check-detail';
+import { useEvidence } from './evidence-context';
+import { ScopeNotice } from './evidence-scope';
+import { plural, statusWord, useNow } from './format';
+import { exampleIndexFor, exampleRows, fillExample, type FeatureStep } from './gherkin';
+import { Origin, StatusMark } from './marks';
+
+/** The short, readable form of a spec fingerprint (`<length>:<hash>:<hash>`): its length and the start of its hash. */
+export function shortRevision(fingerprint: string): string {
+  const [length, hash] = fingerprint.split(':');
+  return hash ? `${hash.slice(0, 8)} (${length} characters)` : fingerprint.slice(0, 12);
+}
+
+/** A behavior's coverage state, always in words. */
+export function CoverageBadge({ state }: { state: CoverageState }) {
+  return (
+    <Badge data-coverage={state} color={COVERAGE[state].color} variant="light" title={COVERAGE[state].meaning}>
+      {COVERAGE[state].label}
+    </Badge>
+  );
+}
+
+/**
+ * The promise and the evidence side by side, each with its own revision. A mismatch is stated, not hidden; a missing
+ * fingerprint is stated as unknown rather than treated as a match.
+ */
+export function RevisionLine({ revision }: { revision: Revision }) {
+  return (
+    <Stack gap="xs" data-revision={revision.match}>
+      <Group gap="md" wrap="wrap" c="dimmed">
+        <Text span inherit>
+          Promise revision:{' '}
+          <Text span inherit fw={600}>
+            {revision.promise ? shortRevision(revision.promise) : 'not recorded'}
+          </Text>
+        </Text>
+        <Text span inherit>
+          Evidence revision:{' '}
+          <Text span inherit fw={600}>
+            {revision.evidence ? shortRevision(revision.evidence) : 'not recorded'}
+          </Text>
+        </Text>
+      </Group>
+      {revision.match === 'different' && (
+        <Alert color="orange" role="status">
+          This evidence was recorded against an earlier revision of the spec. It does not show that the current promise holds.
+        </Alert>
+      )}
+      {revision.match === 'unknown' && (
+        <Text component="div" c="dimmed">
+          The revisions cannot be compared, so this evidence is not tied to the current promise.
+        </Text>
+      )}
+    </Stack>
+  );
+}
+
+/** The `Then` steps (and the `And`/`But` after them): what should be true when the behavior has run. */
+function expectedSteps(steps: readonly FeatureStep[]): FeatureStep[] {
+  const at = steps.findIndex((step) => step.keyword === 'Then');
+  return at < 0 ? [] : steps.slice(at);
+}
+
+function videosIn(holder: EvidenceHolder | undefined): Attachment[] {
+  if (!holder) return [];
+  const own = (holder.attachments ?? []).filter(isVideoAttachment);
+  return [
+    ...own,
+    ...(holder.steps ?? []).flatMap((step) => (step.attachments ?? []).filter(isVideoAttachment)),
+    ...(holder.attempts ?? []).flatMap((attempt) => [
+      ...(attempt.attachments ?? []).filter(isVideoAttachment),
+      ...(attempt.steps ?? []).flatMap((step) => (step.attachments ?? []).filter(isVideoAttachment))
+    ])
+  ];
+}
+
+/** The recording of one result, read only when this is on screen. */
+function Player({ result }: { result: EvidenceResult }) {
+  const detail = useCheckDetail(result.layer, result.row);
+  const videos = useMemo(() => videosIn(detail.data?.check), [detail.data]);
+  const sources = videos.flatMap((attachment) => {
+    const { url } = attachmentSource(attachment, result.layer.id);
+    return url ? [{ attachment, url }] : [];
+  });
+  if (detail.isLoading) {
+    return (
+      <Text role="status" component="div" c="dimmed">
+        Loading the recording…
+      </Text>
+    );
+  }
+  if (detail.isError) {
+    return (
+      <Alert role="alert" color="red">
+        The recording could not be read.
+      </Alert>
+    );
+  }
+  if (!sources.length) {
+    return (
+      <Text component="div" c="dimmed">
+        This result names a recording, but no file can be played from here.
+      </Text>
+    );
+  }
+  return (
+    <Stack gap="sm">
+      {sources.slice(0, 1).map(({ attachment, url }) => (
+        <Stack key={url} gap="xs">
+          {/* What the recording does and does not show, as its producer declared it; undeclared says unknown. */}
+          <ScopeNotice
+            scope={effectiveScope(attachment.scope, detail.data?.check.scope, detail.data?.inheritedScope)}
+            name={attachment.name}
+          />
+          <Box
+            component="video"
+            src={url}
+            controls
+            preload="metadata"
+            aria-label={`Recording: ${attachment.description ?? attachment.name}`}
+            maw="100%"
+            w="100%"
+            mah="70vh"
+          />
+        </Stack>
+      ))}
+      {sources.length > 1 && (
+        <Text component="div" c="dimmed">
+          {plural(sources.length - 1, 'more recording', 'more recordings')} in Inspect.
+        </Text>
+      )}
+    </Stack>
+  );
+}
+
+/** Read, Watch and Inspect for one behavior. `inspect` is the technical record, shown only under Inspect. */
+export function BehaviorPanel({
+  behavior,
+  inspect,
+  start
+}: {
+  behavior: Behavior;
+  inspect: ReactNode;
+  /** The tab to open on; by default Watch when there is something to watch, Inspect while a run is in progress (its progress lives there), else Read. */ start?:
+    'read' | 'watch' | 'inspect';
+}) {
+  const { backends } = useEvidence();
+  const now = useNow();
+  const { scenario, example, demo, subject, revision, state } = behavior;
+  const at = example === null ? -1 : exampleIndexFor(scenario, example);
+  const entry = at < 0 ? null : exampleRows(scenario)[at]!;
+  const steps = useMemo(() => (entry ? fillExample(scenario.steps, entry) : scenario.steps), [scenario, entry]);
+  const expected = expectedSteps(steps);
+  const named = example !== null && entry === null;
+  return (
+    <Tabs
+      defaultValue={start ?? (demo ? 'watch' : state === 'running' || behavior.slot?.live ? 'inspect' : 'read')}
+      keepMounted={false}
+      aria-label={`${scenario.name}${example ? `: ${example}` : ''}`}
+    >
+      <Tabs.List mb="sm">
+        <Tabs.Tab value="read">Read</Tabs.Tab>
+        <Tabs.Tab value="watch">Watch</Tabs.Tab>
+        <Tabs.Tab value="inspect">Inspect</Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="read">
+        <Stack gap="sm" miw={0}>
+          <Group gap="sm">
+            <CoverageBadge state={state} />
+            <Text component="span" c="dimmed">
+              {COVERAGE[state].meaning}
+            </Text>
+          </Group>
+          {example !== null && (
+            <Text component="div" c="dimmed">
+              Example: {example}
+            </Text>
+          )}
+          <PlainSteps steps={steps} examples={entry ? [] : scenario.examples} />
+          {named && (
+            <Text component="div" c="dimmed">
+              The recorded example name does not match one row of the examples, so the values are not filled in.
+            </Text>
+          )}
+        </Stack>
+      </Tabs.Panel>
+      <Tabs.Panel value="watch">
+        <Stack gap="sm" miw={0}>
+          <Group gap="sm">
+            <CoverageBadge state={state} />
+            {behavior.representative && <Badge variant="outline">Representative demo</Badge>}
+          </Group>
+          {expected.length > 0 && (
+            <Box component="section" aria-label="Expected outcome">
+              <Title order={4} mb="xs">
+                Expected
+              </Title>
+              <PlainSteps steps={expected} />
+            </Box>
+          )}
+          {demo ? (
+            <>
+              <Player result={demo} />
+              <Text component="div" c="dimmed">
+                Illustrative recording of one run. It shows what happened in that run and does not approve the behavior for production.
+              </Text>
+            </>
+          ) : (
+            <Text component="div" c="dimmed">
+              Nothing to watch. {COVERAGE[state].meaning}
+            </Text>
+          )}
+          {subject && (
+            <Group gap="xs" wrap="wrap" align="center">
+              <StatusMark status={subject.row.status} size={14} />
+              <Text span inherit fw={600}>
+                {statusWord(subject.row.status)}
+              </Text>
+              <Text span inherit c="dimmed">
+                in {environmentLabel(subject.layer.environment)}
+              </Text>
+              <Origin layer={subject.layer} backends={backends} now={now} />
+            </Group>
+          )}
+          <RevisionLine revision={revision} />
+        </Stack>
+      </Tabs.Panel>
+      <Tabs.Panel value="inspect">
+        <Stack gap="sm" miw={0}>
+          <RevisionLine revision={revision} />
+          {inspect}
+        </Stack>
+      </Tabs.Panel>
+    </Tabs>
+  );
+}
+
+/**
+ * What the feature's behaviors add up to, one count per state. A state with none is left out except
+ * `demonstrated`, which is always named so its absence is not mistaken for a pass.
+ */
+export function CoverageSummary({ counts, total }: { counts: CoverageCounts; total: number }) {
+  if (total === 0) return null;
+  return (
+    <Paper component="section" aria-label="Coverage" withBorder p="md" my="md">
+      <Stack gap="xs">
+        <Title order={2}>Coverage</Title>
+        <Text component="div">
+          {counts.demonstrated} of {plural(total, 'behavior', 'behaviors')} demonstrated with a recording of the current spec.
+        </Text>
+        <List listStyleType="none" spacing="xs">
+          {COVERAGE_ORDER.filter((state) => state === 'demonstrated' || counts[state] > 0).map((state) => (
+            <List.Item key={state} data-coverage={state}>
+              <Group gap="sm" wrap="wrap">
+                <CoverageBadge state={state} />
+                <Text span inherit fw={600}>
+                  {counts[state]}
+                </Text>
+                <Text span inherit c="dimmed">
+                  {COVERAGE[state].meaning}
+                </Text>
+              </Group>
+            </List.Item>
+          ))}
+        </List>
+        <Text component="div" c="dimmed">
+          A recording shows one run. It is illustrative evidence and does not mean the behavior is live or ready for production.
+        </Text>
+      </Stack>
+    </Paper>
+  );
+}

package/packages/visualizer/src/evidence/behavior.test.ts

@@ -0,0 +1,99 @@
+import type { LayerHeader, LayerRow } from '@crvouga/atlas/reports/evidence-types';
+import type { CheckSlot } from '@crvouga/atlas/reports/evidence-view';
+import type { EvidenceResult } from '@crvouga/atlas/reports/layer-merge';
+import { expect, test } from 'bun:test';
+
+import { behaviorOf, compareRevisions, coverageCounts, isRepresentative, scenarioBehaviors, type RevisionSource } from './behavior';
+import { exampleIndexFor, featureModel, fillExample, exampleRows } from './gherkin';
+
+const FEATURE = featureModel(`Feature: Lists
+  @demo
+  Scenario: Add
+    When adding tea
+
+  @parked
+  Scenario: Archive
+    When archiving
+
+  Scenario Outline: Several
+    When adding "<item>" for <who>
+    Examples:
+      | item | who |
+      | Tea  | Ann |
+      | Milk | Bo  |
+`)!;
+const [ADD, ARCHIVE, SEVERAL] = FEATURE.rules[0]!.scenarios;
+
+const header = (layer: string, environment: string | null = 'desktop-web'): LayerHeader => ({
+  id: layer, backend: 'b', producer: 'p', packageDir: null, recordedAtMs: 1, sha: null, branch: null, environment, runUrl: null, parameters: {},
+  recording: null, live: false, counts: { passed: 0, failed: 0, running: 0, 'not-run': 0 }, execution: layer
+});
+function result(layer: string, row: Partial<LayerRow>, environment: string | null = 'desktop-web'): EvidenceResult {
+  return {
+    key: layer, slot: 's', layer: header(layer, environment), parameters: {}, warning: null,
+    row: { kind: 'behavior', id: 'x', title: 'Lists: Add', status: 'passed', specPath: 'specs/a.feature', detail: '', measurements: [], testId: null, variant: {}, durationMs: null, ...row }
+  };
+}
+const slot = (status: CheckSlot['status'], outcomes: EvidenceResult[], title = 'Lists: Add'): CheckSlot => ({
+  key: title, id: title, title, specPath: 'specs/a.feature', status, outcomes, diagnostics: [], latestAtMs: 1, live: false
+});
+const VIDEO = { attachments: 1, steps: 0, annotations: 0, attempts: 0, links: 0, tags: [], labels: {}, roles: ['video'], videos: [{ name: 'a.webm', owner: 'check' as const, recording: 'sha256:1', available: true }] };
+const revisions = (current: string | null, recorded: Record<string, string> = {}): RevisionSource => ({ current, recorded: (id) => recorded[id] });
+const stateOf = (s: CheckSlot | null, rev = revisions('f1', { l1: 'f1', l2: 'f0' }), scenario = ADD!) => behaviorOf(scenario, s, null, rev, 'k').state;
+
+test('revisions compare only when both are known', () => {
+  expect(compareRevisions('a', 'a').match).toBe('same');
+  expect(compareRevisions('a', 'b').match).toBe('different');
+  expect(compareRevisions('a', undefined).match).toBe('unknown');
+  expect(compareRevisions(null, 'a').match).toBe('unknown');
+});
+
+test('only a passing result with a playable recording of the current promise is demonstrated', () => {
+  expect(stateOf(slot('passed', [result('l1', { evidence: VIDEO })]))).toBe('demonstrated');
+  // The same recording of an older revision is not proof of the new promise.
+  expect(stateOf(slot('passed', [result('l2', { evidence: VIDEO })]))).toBe('outdated-recording');
+  // An unplayable reference is a gap, and a pass with nothing to watch says so.
+  expect(stateOf(slot('passed', [result('l1', { evidence: { ...VIDEO, videos: [{ ...VIDEO.videos[0]!, available: false }] } })]))).toBe('recording-missing');
+  expect(stateOf(slot('passed', [result('l1', { recording: { state: 'skipped', reason: 'too-large' } })]))).toBe('recording-missing');
+  expect(stateOf(slot('passed', [result('l1', {})]))).toBe('no-recording');
+  expect(stateOf(slot('passed', [result('l1', {}, 'api')]))).toBe('api-only');
+  // A video on the API does not turn it into API-only evidence: it can be watched.
+  expect(stateOf(slot('passed', [result('l1', { evidence: VIDEO }, 'api')]))).toBe('demonstrated');
+});
+
+test('failed, running, skipped, parked and unexecuted stay distinct and never read as passes', () => {
+  expect(stateOf(slot('failed', [result('l1', { status: 'failed', evidence: VIDEO })]))).toBe('failed');
+  expect(stateOf(slot('running', [result('l1', { status: 'running' })]))).toBe('running');
+  expect(stateOf(slot('not-run', [result('l1', { status: 'not-run' })]))).toBe('skipped');
+  expect(stateOf(null, undefined, ARCHIVE)).toBe('parked');
+  expect(stateOf(null)).toBe('unexecuted');
+  // One environment passing with a clip does not hide another that failed.
+  expect(stateOf(slot('failed', [result('l1', { evidence: VIDEO }), result('l3', { status: 'failed' })]))).toBe('failed');
+});
+
+test('a demo tag marks the scenario as the representative one', () => {
+  expect(isRepresentative(['#Demo'])).toBe(true);
+  expect(isRepresentative(['smoke'])).toBe(false);
+  expect(behaviorOf(ADD!, null, null, revisions(null), 'k').representative).toBe(true);
+  expect(behaviorOf(ARCHIVE!, null, null, revisions(null), 'k').representative).toBe(false);
+});
+
+test('an outline is one behavior per example, never the template as well', () => {
+  const tea = slot('passed', [result('l1', {})], 'Lists: Several — Tea');
+  const behaviors = scenarioBehaviors(SEVERAL!, [tea], 'Lists', revisions('f1'));
+  expect(behaviors.map((behavior) => [behavior.example, behavior.state])).toEqual([
+    ['Tea', 'no-recording'],
+    ['Milk, Bo', 'unexecuted']
+  ]);
+  expect(coverageCounts(behaviors).unexecuted).toBe(1);
+  // With nothing recorded there are still only the two examples.
+  expect(scenarioBehaviors(SEVERAL!, [], 'Lists', revisions(null))).toHaveLength(2);
+});
+
+test('a recorded example is matched to its row by cells or column pairs, and its values are filled in', () => {
+  expect(exampleIndexFor(SEVERAL!, 'Milk')).toBe(1);
+  expect(exampleIndexFor(SEVERAL!, 'item=Tea, who=Ann')).toBe(0);
+  expect(exampleIndexFor(SEVERAL!, 'Unrelated wording')).toBe(-1);
+  const filled = fillExample(SEVERAL!.steps, exampleRows(SEVERAL!)[1]!);
+  expect(filled[0]!.text).toBe('adding "Milk" for Bo');
+});

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

@@ -0,0 +1,268 @@
+/**
+ * @module Behavior coverage
+ *
+ * Reads a feature the way a product reader does: each scenario (or each concrete example of an outline) is one
+ * behavior, and each behavior is in exactly one coverage state. The states keep apart what a green count would blur:
+ * a passing test with a playable recording of the current promise is `demonstrated`; a passing test with no
+ * recording, with a recording of an older revision of the spec, or only in API environments is not. Nothing here
+ * decides an outcome: statuses and winners come from the combined report, and a state is a reading of them.
+ * A missing fingerprint, recording or result is unknown or missing, never a pass.
+ */
+import type { CheckSlot } from '@crvouga/atlas/reports/evidence-view';
+import type { EvidenceResult } from '@crvouga/atlas/reports/layer-merge';
+
+import { exampleIndexFor, exampleRows, scenarioLabel, type FeatureScenario } from './gherkin';
+
+/** Where a behavior stands, from the most reassuring to the least. */
+export type CoverageState =
+  | 'demonstrated'
+  | 'outdated-recording'
+  | 'recording-missing'
+  | 'no-recording'
+  | 'api-only'
+  | 'failed'
+  | 'running'
+  | 'skipped'
+  | 'parked'
+  | 'unexecuted';
+
+/** What each state is called and why, in the order a summary lists them. */
+export const COVERAGE: Readonly<Record<CoverageState, { readonly label: string; readonly meaning: string; readonly color: string }>> = {
+  demonstrated: {
+    label: 'Demonstrated',
+    meaning: 'A passing result with a recording of the current promise.',
+    color: 'green'
+  },
+  'outdated-recording': {
+    label: 'Recording is older',
+    meaning: 'A passing result, but the recording is of an earlier revision of the spec.',
+    color: 'orange'
+  },
+  'recording-missing': {
+    label: 'Recording missing',
+    meaning: 'A passing result whose expected recording was not published or cannot be played.',
+    color: 'orange'
+  },
+  'no-recording': {
+    label: 'No recording',
+    meaning: 'A passing result with nothing to watch.',
+    color: 'gray'
+  },
+  'api-only': {
+    label: 'API only',
+    meaning: 'A passing result recorded only through the API, so there is no screen to watch.',
+    color: 'gray'
+  },
+  failed: {
+    label: 'Failed',
+    meaning: 'The latest result failed.',
+    color: 'red'
+  },
+  running: {
+    label: 'Running',
+    meaning: 'A run is checking it now.',
+    color: 'blue'
+  },
+  skipped: {
+    label: 'Skipped',
+    meaning: 'It was reported as skipped or not run.',
+    color: 'gray'
+  },
+  parked: {
+    label: 'Parked',
+    meaning: 'The scenario is tagged as parked or work in progress, and has no result.',
+    color: 'gray'
+  },
+  unexecuted: {
+    label: 'Not executed',
+    meaning: 'No test reported a result for it.',
+    color: 'gray'
+  }
+};
+
+/** The order a coverage summary lists states in. */
+export const COVERAGE_ORDER = Object.keys(COVERAGE) as CoverageState[];
+
+/** How the spec the evidence was recorded against compares with the spec now. */
+export type Revision = {
+  /** Fingerprint of the spec now (the promise). Null when the outline has none. */
+  readonly promise: string | null;
+  /** Fingerprint of the spec when the evidence was recorded. Null when the layer did not record one. */
+  readonly evidence: string | null;
+  /** `same`, `different`, or `unknown` when either side is missing. */
+  readonly match: 'same' | 'different' | 'unknown';
+};
+
+/** Compares two fingerprints: unknown unless both are there. */
+export function compareRevisions(promise: string | null | undefined, evidence: string | null | undefined): Revision {
+  const now = promise || null;
+  const then = evidence || null;
+  return {
+    promise: now,
+    evidence: then,
+    match: now === null || then === null ? 'unknown' : now === then ? 'same' : 'different'
+  };
+}
+
+/** The tags that mark a scenario as deliberately not running, and the state each gives it. */
+const TAG_STATE: Readonly<Record<string, CoverageState>> = {
+  parked: 'parked',
+  wip: 'parked',
+  pending: 'parked',
+  skip: 'skipped',
+  skipped: 'skipped',
+  ignore: 'skipped'
+};
+
+/** The tags that say a recording was picked to stand for a behavior. */
+const REPRESENTATIVE = new Set(['demo', 'representative']);
+
+/** Whether a recorded result or its scenario is tagged as the representative demo. */
+export function isRepresentative(tags: readonly string[]): boolean {
+  return tags.some((tag) => REPRESENTATIVE.has(tag.replace(/^[#@]/, '').toLowerCase()));
+}
+
+/** A result's playable video references: those that name bytes. */
+function playable(result: EvidenceResult): number {
+  return result.row.evidence?.videos?.filter((video) => video.available).length ?? 0;
+}
+
+/** Environments a reader cannot watch: a result recorded only through these has no screen. */
+function isApi(environment: string | null): boolean {
+  return environment !== null && /^(api|http|rest|graphql|service|backend)(-|$)/.test(environment);
+}
+
+/** What is known about one behavior. */
+export type Behavior = {
+  /** Stable within the page: the scenario and its example. */
+  readonly key: string;
+  readonly scenario: FeatureScenario;
+  /** The example label of an outline's row (what the producer named it), or null for a plain scenario. */
+  readonly example: string | null;
+  /** The recorded check, or null when nothing reported on it. */
+  readonly slot: CheckSlot | null;
+  readonly state: CoverageState;
+  /** The result to watch: the newest of those with a playable recording, preferring one of the current revision. */
+  readonly demo: EvidenceResult | null;
+  /** The result the revision line and provenance describe: the demo, else the newest. */
+  readonly subject: EvidenceResult | null;
+  readonly revision: Revision;
+  /** Whether the scenario or the recorded result is tagged as the representative demo. */
+  readonly representative: boolean;
+};
+
+/** What the page knows about the spec as it is now and as each layer recorded it. */
+export type RevisionSource = {
+  /** The spec's fingerprint now. */
+  readonly current: string | null;
+  /** The fingerprint a layer recorded for this spec, if it did. */
+  readonly recorded: (layerId: string) => string | undefined;
+};
+
+/**
+ * The state of one behavior from its recorded check (or none). A failing, running or skipped result is that, whatever
+ * recordings exist. A pass is `demonstrated` only with a playable recording that is not known to be of another
+ * revision; a recording whose revision cannot be compared is still shown, with the revision stated as unknown.
+ */
+export function behaviorOf(
+  scenario: FeatureScenario,
+  slot: CheckSlot | null,
+  example: string | null,
+  revisions: RevisionSource,
+  key: string
+): Behavior {
+  const outcomes = slot?.outcomes ?? [];
+  const revisionOf = (result: EvidenceResult | null) =>
+    compareRevisions(revisions.current, result ? revisions.recorded(result.layer.id) : undefined);
+  const withVideo = outcomes.filter((result) => result.row.status === 'passed' && playable(result) > 0);
+  const demo = withVideo.find((result) => revisionOf(result).match !== 'different') ?? withVideo[0] ?? null;
+  const subject = demo ?? outcomes[0] ?? null;
+  const revision = revisionOf(subject);
+  const representative =
+    isRepresentative(scenario.tags) ||
+    outcomes.some((result) => isRepresentative([...(result.row.evidence?.tags ?? []), ...(result.row.evidence?.artifactTags ?? [])]));
+  const base = {
+    key,
+    scenario,
+    example,
+    slot,
+    demo,
+    subject,
+    revision,
+    representative
+  };
+  if (!slot || outcomes.length === 0) {
+    const tagged = scenario.tags.map((tag) => TAG_STATE[tag.toLowerCase()]).find((state) => state !== undefined);
+    return { ...base, state: tagged ?? 'unexecuted' };
+  }
+  if (slot.status === 'failed') return { ...base, state: 'failed' };
+  if (slot.status === 'running') return { ...base, state: 'running' };
+  if (slot.status === 'not-run') return { ...base, state: 'skipped' };
+  if (demo)
+    return {
+      ...base,
+      state: revision.match === 'different' ? 'outdated-recording' : 'demonstrated'
+    };
+  const passed = outcomes.filter((result) => result.row.status === 'passed');
+  // A recording was promised and is not here, or is referenced without bytes: that is a gap, not an API test.
+  if (
+    passed.some((result) => result.row.recording && !['uploaded', 'referenced', 'not-applicable'].includes(result.row.recording.state)) ||
+    passed.some((result) => (result.row.evidence?.videos?.length ?? 0) > 0)
+  ) {
+    return { ...base, state: 'recording-missing' };
+  }
+  if (passed.length > 0 && passed.every((result) => isApi(result.layer.environment))) return { ...base, state: 'api-only' };
+  return { ...base, state: 'no-recording' };
+}
+
+/**
+ * Every behavior of a scenario. A plain scenario is one. An outline is one per example row, never the template as an
+ * extra: a recorded example is filed under the row it names; a row nothing reported on is `unexecuted` (or parked);
+ * a recorded example whose label names no row is kept as its own behavior and the unclaimed rows are counted against
+ * the recorded results that remain, so the total never exceeds the rows by inventing a template.
+ */
+export function scenarioBehaviors(
+  scenario: FeatureScenario,
+  slots: readonly CheckSlot[],
+  feature: string,
+  revisions: RevisionSource
+): Behavior[] {
+  const rows = exampleRows(scenario);
+  if (rows.length === 0) {
+    // A scenario with no examples fills one slot per environment/parameter set, which the slot already groups.
+    const slot = slots[0] ?? null;
+    if (slots.length <= 1) return [behaviorOf(scenario, slot, null, revisions, scenario.name)];
+    return slots.map((each) => behaviorOf(scenario, each, null, revisions, each.key));
+  }
+  const claimed = new Map<number, CheckSlot[]>();
+  const loose: CheckSlot[] = [];
+  for (const slot of slots) {
+    const label = scenarioLabel(feature, slot.title).slice(scenario.name.length + 3);
+    const at = exampleIndexFor(scenario, label);
+    if (at < 0) loose.push(slot);
+    else claimed.set(at, [...(claimed.get(at) ?? []), slot]);
+  }
+  const behaviors: Behavior[] = [];
+  const unmatched = rows.map((_, at) => at).filter((at) => !claimed.has(at));
+  // Results whose wording matches no row stand in for the rows nothing claimed, in order, before any row is called unexecuted.
+  const spare = [...loose];
+  rows.forEach((entry, at) => {
+    const found = claimed.get(at) ?? (unmatched.includes(at) && spare.length ? [spare.shift()!] : []);
+    const label = found[0] ? scenarioLabel(feature, found[0].title).slice(scenario.name.length + 3) : entry.row.join(', ');
+    if (found.length === 0) behaviors.push(behaviorOf(scenario, null, label, revisions, `${scenario.name}:${at}`));
+    for (const slot of found) behaviors.push(behaviorOf(scenario, slot, label, revisions, slot.key));
+  });
+  for (const slot of spare)
+    behaviors.push(behaviorOf(scenario, slot, scenarioLabel(feature, slot.title).slice(scenario.name.length + 3), revisions, slot.key));
+  return behaviors;
+}
+
+/** Behaviors counted by state. Every state is present, so an absent one reads as zero, not as unknown. */
+export type CoverageCounts = Readonly<Record<CoverageState, number>>;
+
+/** Counts behaviors by coverage state; only `demonstrated` is a demonstrated pass. */
+export function coverageCounts(behaviors: readonly Behavior[]): CoverageCounts {
+  const counts = Object.fromEntries(COVERAGE_ORDER.map((state) => [state, 0])) as Record<CoverageState, number>;
+  for (const behavior of behaviors) counts[behavior.state] += 1;
+  return counts;
+}

package/packages/visualizer/src/evidence/check-detail.tsx

@@ -61,12 +61,15 @@ export function ResultRow({
   slot,
   open,
   onToggle,
+  badge,
   children
 }: {
   label: string;
   slot: CheckSlot | null;
   open: boolean;
   onToggle: () => void;
+  /** A short extra mark after the label, such as a coverage state. */
+  badge?: ReactNode;
   children: ReactNode;
 }) {
   const now = useNow();
@@ -96,6 +99,7 @@ export function ResultRow({
                   </Flex>
                 )}
               </Text>
+              {badge}
               {slot?.live && (
                 <Text span inherit>
                   Running now