@crvouga/atlas 1.4.0 → 1.6.0

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

package/packages/visualizer/src/evidence/feature-page.tsx

@@ -1,8 +1,11 @@
 import type { CheckSlot, SpecEvidence } from '@crvouga/atlas/reports/evidence-view';
 import { Alert, Box, Container, List, Stack, Text, Title } from '@mantine/core';
 import { useMemo } from 'react';
-import type { SpecKind } from '../spec-kind';
+import { outlinePath, type SpecKind } from '../spec-kind';
 import { CheckDetail, PlainSteps, ResultRow, type CheckSelection, type SelectCheck } from './check-detail';
+import { behaviorOf, coverageCounts, scenarioBehaviors, type Behavior, type RevisionSource } from './behavior';
+import { BehaviorPanel, CoverageBadge, CoverageSummary } from './behavior-panel';
+import { useEvidence } from './evidence-context';
 import { featureModel, scenarioLabel, slotsByScenario, type FeatureModel, type FeatureScenario } from './gherkin';
 import { Bounded } from './marks';
 import { SpecHeader } from './spec-header';
@@ -23,7 +26,10 @@ function parse(text: string): {
   try {
     return { feature: featureModel(text), error: null };
   } catch (error) {
-    return { feature: null, error: error instanceof Error ? error.message : String(error) };
+    return {
+      feature: null,
+      error: error instanceof Error ? error.message : String(error)
+    };
   }
 }
 /** A feature read as its rules and scenarios, each scenario with what was recorded when it ran. */
@@ -35,43 +41,81 @@ export function FeaturePage({ file, text, kind, entry, selection, select }: Prop
     () => (feature ? slotsByScenario(feature, slots) : { byScenario: new Map<string, CheckSlot[]>(), leftOver: slots }),
     [feature, slots]
   );
-  const scenarios = feature?.rules.flatMap((rule) => rule.scenarios.filter((scenario) => !scenario.background)) ?? [];
-  const planned =
-    scenarios.reduce((count, scenario) => count + Math.max(1, filed.byScenario.get(scenario.name)?.length ?? 0), 0) + filed.leftOver.length;
+  const { specs, evidence } = useEvidence();
+  const specPath = outlinePath(file);
+  const revisions = useMemo<RevisionSource>(() => {
+    const recorded = new Map(evidence.map((layer) => [layer.layer.id, layer.fingerprints[specPath]]));
+    return {
+      current: specs.find((spec) => spec.path === specPath)?.fingerprint ?? null,
+      recorded: (id) => recorded.get(id)
+    };
+  }, [specs, evidence, specPath]);
+  const behaviors = useMemo(() => {
+    const byScenario = new Map<FeatureScenario, Behavior[]>();
+    for (const scenario of feature?.rules.flatMap((rule) => rule.scenarios.filter((each) => !each.background)) ?? []) {
+      byScenario.set(scenario, scenarioBehaviors(scenario, filed.byScenario.get(scenario.name) ?? [], feature!.name, revisions));
+    }
+    // A result no scenario claims is still a behavior that was checked, so it is counted.
+    const stray: FeatureScenario = {
+      keyword: 'Scenario',
+      name: '',
+      description: '',
+      background: false,
+      tags: [],
+      steps: [],
+      examples: []
+    };
+    const other = filed.leftOver.map((slot) => behaviorOf({ ...stray, name: slot.title }, slot, null, revisions, slot.key));
+    return { byScenario, all: [...[...byScenario.values()].flat(), ...other] };
+  }, [feature, filed, revisions]);
+  const counts = useMemo(() => coverageCounts(behaviors.all), [behaviors]);
+  const planned = behaviors.all.length;
   const toggle = (id: string) => select({ check: selection.check === id ? null : id, layer: null });
-  const rows = (scenario: FeatureScenario) => {
-    const written = <PlainSteps steps={scenario.steps} examples={scenario.examples} />;
-    const recorded = (filed.byScenario.get(scenario.name) ?? []).filter((slot) => !runningOnly || slot.status === 'running');
-    if (!recorded.length) {
-      if (runningOnly) return null;
-      const id = `scenario:${scenario.name}`;
+  const rows = (scenario: FeatureScenario) =>
+    (behaviors.byScenario.get(scenario) ?? []).map((behavior) => {
+      if (runningOnly && behavior.slot?.status !== 'running') return null;
+      const { slot } = behavior;
+      const written = <PlainSteps steps={scenario.steps} examples={scenario.examples} />;
+      const id = slot ? slot.id : `scenario:${scenario.name}${behavior.example ? `:${behavior.example}` : ''}`;
+      const label = slot
+        ? scenarioLabel(feature!.name, slot.title)
+        : behavior.example
+          ? `${scenario.name} — ${behavior.example}`
+          : scenario.name;
       return (
-        <ResultRow key={id} label={scenario.name} slot={null} open={selection.check === id} onToggle={() => toggle(id)}>
-          <Text component="div" c="dimmed">
-            No completed test report for this scenario yet.
-          </Text>
-          {written}
+        <ResultRow
+          key={id}
+          label={label}
+          slot={slot}
+          badge={<CoverageBadge state={behavior.state} />}
+          open={selection.check === id}
+          onToggle={() => toggle(id)}
+        >
+          <BehaviorPanel
+            behavior={behavior}
+            start={selection.check === id && selection.layer ? 'inspect' : undefined}
+            inspect={
+              slot ? (
+                <CheckDetail
+                  slot={slot}
+                  layerId={selection.check === id ? selection.layer : undefined}
+                  select={(patch) => select({ check: id, ...patch })}
+                  reads="steps"
+                  written={written}
+                />
+              ) : (
+                <>
+                  <Text component="div" c="dimmed">
+                    No completed test report for this scenario yet.
+                  </Text>
+                  {written}
+                </>
+              )
+            }
+          />
         </ResultRow>
       );
-    }
-    return recorded.map((slot) => (
-      <ResultRow
-        key={slot.key}
-        label={scenarioLabel(feature!.name, slot.title)}
-        slot={slot}
-        open={selection.check === slot.id}
-        onToggle={() => toggle(slot.id)}
-      >
-        <CheckDetail
-          slot={slot}
-          layerId={selection.check === slot.id ? selection.layer : undefined}
-          select={(patch) => select({ check: slot.id, ...patch })}
-          reads="steps"
-          written={written}
-        />
-      </ResultRow>
-    ));
-  };
+    });
   return (
     <Container component="article" size="xl" w="100%" py="xl">
       <SpecHeader
@@ -87,6 +131,7 @@ export function FeaturePage({ file, text, kind, entry, selection, select }: Prop
           </Text>
         )}
       </SpecHeader>
+      <CoverageSummary counts={counts} total={behaviors.all.length} />
       <SourceText text={text} file={file} withResults />
       <Box component="section" id="spec-results" aria-label="Recorded results" tabIndex={-1}>
         <TestFilter slots={slots} />
@@ -112,7 +157,8 @@ export function FeaturePage({ file, text, kind, entry, selection, select }: Prop
               .map((scenario, at) => (
                 <Stack key={at} gap="sm" miw={0}>
                   <Text component="div" c="dimmed">
-                    Before each scenario{scenario.name ? `: ${scenario.name}` : ''}
+                    Before each scenario
+                    {scenario.name ? `: ${scenario.name}` : ''}
                   </Text>
                   <PlainSteps steps={scenario.steps} />
                 </Stack>

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

@@ -13,6 +13,8 @@ export type FeatureScenario = {
   readonly name: string;
   readonly description: string;
   readonly background: boolean;
+  /** The scenario's own tags, without the `@` (a parked or skipped scenario says so here). */
+  readonly tags: readonly string[];
   readonly steps: readonly FeatureStep[];
   readonly examples: readonly FeatureExamples[];
 };
@@ -50,13 +52,14 @@ export function featureModel(text: string): FeatureModel | null {
     for (const entry of child.rule ? child.rule.children : [child]) {
       const background = entry.background;
       const scenario = entry.scenario;
-      if (background) group.scenarios.push({ keyword: background.keyword, name: background.name, description: prose(background.description), background: true, steps: steps(background.steps), examples: [] });
+      if (background) group.scenarios.push({ keyword: background.keyword, name: background.name, description: prose(background.description), background: true, tags: [], steps: steps(background.steps), examples: [] });
       if (scenario) {
         group.scenarios.push({
           keyword: scenario.keyword,
           name: scenario.name,
           description: prose(scenario.description),
           background: false,
+          tags: [...new Set([...feature.tags, ...(child.rule?.tags ?? []), ...scenario.tags].map((tag) => tag.name.replace(/^@/, '')))],
           steps: steps(scenario.steps),
           examples: scenario.examples.map((example) => ({ name: example.name, header: cells(example.tableHeader), rows: example.tableBody.map(cells) }))
         });
@@ -96,3 +99,30 @@ export function slotsByScenario(feature: FeatureModel, slots: readonly CheckSlot
   }
   return { byScenario, leftOver };
 }
+
+/** The rows of an outline's examples, each with the names of its columns. */
+export function exampleRows(scenario: Pick<FeatureScenario, 'examples'>): { readonly header: readonly string[]; readonly row: readonly string[] }[] {
+  return scenario.examples.flatMap((example) => example.rows.map((row) => ({ header: example.header, row })));
+}
+
+/** Whether a recorded example label (what follows `Scenario — `) names one row: by its cells, joined, or by `column=value` pairs. */
+function namesRow(label: string, entry: { readonly header: readonly string[]; readonly row: readonly string[] }) {
+  const joined = [entry.row.join(', '), entry.row.join(' '), entry.row.join(' | '), entry.header.map((name, at) => `${name}=${entry.row[at] ?? ''}`).join(', ')];
+  return joined.includes(label) || entry.row.includes(label);
+}
+
+/** The index (in {@link exampleRows}) of the row a recorded label stands for, or -1 when the label names no single row (the producer worded it its own way, or two rows read alike). */
+export function exampleIndexFor(scenario: Pick<FeatureScenario, 'examples'>, label: string): number {
+  const rows = exampleRows(scenario);
+  const found = rows.flatMap((entry, at) => (namesRow(label, entry) ? [at] : []));
+  return found.length === 1 ? found[0]! : -1;
+}
+
+/** The steps of a scenario with one example's values put in for its `<column>` placeholders, so the concrete inputs read as written. */
+export function fillExample(steps: readonly FeatureStep[], entry: { readonly header: readonly string[]; readonly row: readonly string[] }): FeatureStep[] {
+  const fill = (text: string) => text.replace(/<([^<>]+)>/g, (whole, name: string) => {
+    const at = entry.header.indexOf(name);
+    return at < 0 ? whole : (entry.row[at] ?? whole);
+  });
+  return steps.map((step) => ({ ...step, text: fill(step.text), docString: step.docString === null ? null : fill(step.docString), table: step.table.map((row) => row.map(fill)) }));
+}

package/packages/visualizer/src/evidence/spec-index.tsx

@@ -1,7 +1,7 @@
 import { addSummaries, NO_EVIDENCE, type SpecSummary } from '@crvouga/atlas/reports/evidence-view';
-import { Box, Button, Group, NavLink, Stack, Text, Title } from '@mantine/core';
+import { Box, Button, Group, NavLink, SegmentedControl, Stack, Text, TextInput, Title } from '@mantine/core';
 import { Link, useSearch } from '@tanstack/react-router';
-import { useMemo } from 'react';
+import { useMemo, useState } from 'react';
 import { folderOf, outlinePath, specFile, type SpecKind } from '../spec-kind';
 import { useUiStore, type ResultFilter } from '../state/ui-store';
 import { useEvidence } from './evidence-context';
@@ -17,30 +17,42 @@ const FILTERS: readonly {
   { id: 'failed', label: 'Failing', keeps: (summary) => summary.counts.failed > 0 },
   { id: 'none', label: 'None', keeps: (summary) => summary.status === 'none' }
 ];
+const NO_DOMAIN = 'No domain declared';
 /** Every spec of one kind, grouped by folder, each with what the combined report holds for it. */
 export function SpecIndex({ kind }: { kind: SpecKind }) {
   const evidence = useEvidence();
   const search = useSearch({ strict: false });
   const filter = useUiStore((s) => s.resultFilter);
   const setFilter = useUiStore((s) => s.setResultFilter);
+  const [query, setQuery] = useState('');
+  const [grouping, setGrouping] = useState<'folder' | 'domain'>('folder');
   const open = typeof search.spec === 'string' ? specFile(search.spec) : '';
+  // The domain a spec declares in its metadata is used as given; a spec that declares none is not given one.
+  const domains = useMemo(() => new Map(evidence.specs.map((spec) => [spec.path, spec.domain])), [evidence.specs]);
   const rows = useMemo(
     () =>
       evidence.files.filter(kind.accepts).map((file) => ({
         file,
         title: evidence.titleOf(file),
+        domain: domains.get(outlinePath(file)) || '',
         summary: evidence.view.specs.get(outlinePath(file))?.summary ?? NO_EVIDENCE
       })),
     // `titleOf` reads the outline the view was built from.
-    [evidence.files, evidence.view, kind]
+    [evidence.files, evidence.view, kind, domains]
   );
   const keeps = FILTERS.find((entry) => entry.id === filter)!.keeps;
-  const visible = rows.filter((row) => keeps(row.summary));
+  const needle = query.trim().toLowerCase();
+  const visible = rows.filter(
+    (row) => keeps(row.summary) && (!needle || `${row.title} ${row.file} ${row.domain}`.toLowerCase().includes(needle))
+  );
   const groups = useMemo(() => {
-    const byFolder = new Map<string, typeof visible>();
-    for (const row of visible) byFolder.set(folderOf(row.file), [...(byFolder.get(folderOf(row.file)) ?? []), row]);
-    return [...byFolder];
-  }, [visible]);
+    const byGroup = new Map<string, typeof visible>();
+    for (const row of visible) {
+      const group = grouping === 'domain' ? row.domain || NO_DOMAIN : folderOf(row.file);
+      byGroup.set(group, [...(byGroup.get(group) ?? []), row]);
+    }
+    return [...byGroup];
+  }, [visible, grouping]);
   return (
     <Box aria-label={`${kind.label} ${kind.many}`} component="nav" p="md">
       <Group role="group" aria-label="Show" gap="xs" mb="md">
@@ -59,19 +71,40 @@ export function SpecIndex({ kind }: { kind: SpecKind }) {
           </Button>
         ))}
       </Group>
+      <Group gap="md" align="end" mb="md">
+        <TextInput
+          label={`Search ${kind.many}`}
+          type="search"
+          value={query}
+          onChange={(event) => setQuery(event.currentTarget.value)}
+          flex={1}
+          miw="12rem"
+        />
+        <SegmentedControl
+          aria-label="Group by"
+          value={grouping}
+          onChange={(value) => setGrouping(value === 'domain' ? 'domain' : 'folder')}
+          data={[
+            { label: 'Folder', value: 'folder' },
+            { label: 'Domain', value: 'domain' }
+          ]}
+        />
+      </Group>
       {evidence.filesPending && <Text component="div">Loading…</Text>}
       {evidence.filesError && <Text component="div">The file list could not be loaded.</Text>}
       {!evidence.filesPending && !evidence.filesError && visible.length === 0 && (
         <Text component="div">
           {rows.length === 0
             ? `No ${kind.many} in this spec set.`
-            : filter === 'running'
-              ? `No running ${kind.many}.`
-              : filter === 'failed'
-                ? `No failing ${kind.many}.`
-                : filter === 'results'
-                  ? `No ${kind.many} with results yet.`
-                  : `Every ${kind.one} has results.`}
+            : needle
+              ? `No ${kind.many} match "${query.trim()}".`
+              : filter === 'running'
+                ? `No running ${kind.many}.`
+                : filter === 'failed'
+                  ? `No failing ${kind.many}.`
+                  : filter === 'results'
+                    ? `No ${kind.many} with results yet.`
+                    : `Every ${kind.one} has results.`}
         </Text>
       )}
       {groups.map(([folder, entries]) => (