@crvouga/atlas 1.4.0 → 1.6.0

package/packages/visualizer/src/explorer/search-notes.tsx

@@ -0,0 +1,74 @@
+import { Alert, Button, Stack, Text } from '@mantine/core';
+import { IconX } from '@tabler/icons-react';
+/**
+ * @module Search guidance
+ *
+ * What every search box in the explorer says beside its results, from one place: the filters typed in the box shown as
+ * removable chips, the parts of the query that were not understood (never silently dropped), and whether meaning-based
+ * matching is working, still refining, or off, so a search that is words only says so.
+ */
+import { withoutToken, type FilterKey, type ParsedSearch } from '../find/query';
+import { semanticNote, type SemanticStatus } from '../find/semantic-search';
+
+const FILTER_LABEL: Record<FilterKey, string> = {
+  status: 'Status',
+  env: 'Environment',
+  producer: 'Producer',
+  domain: 'Domain',
+  spec: 'Spec',
+  tag: 'Tag',
+  branch: 'Branch',
+  video: 'Has video'
+};
+
+/** The label of a typed filter chip: `Status: failed`, or `Has video`. */
+export function filterLabel(key: FilterKey, value: string): string {
+  return key === 'video' ? FILTER_LABEL.video : `${FILTER_LABEL[key]}: ${value}`;
+}
+
+/** The filters typed in the box, each a button that removes its text from the query. */
+export function TypedFilters({ parsed, query, onChange }: { parsed: ParsedSearch; query: string; onChange: (next: string) => void }) {
+  return (
+    <>
+      {parsed.tokens.map((token) => {
+        const label = filterLabel(token.key, token.value);
+        return (
+          <Button key={`typed:${token.text}:${token.value}`} type="button" onClick={() => onChange(withoutToken(query, token))} aria-label={`Remove ${label}`} variant="light">
+            {label}{' '}
+            <Text aria-hidden="true" span inherit>
+              <IconX size={16} aria-hidden="true" />
+            </Text>
+          </Button>
+        );
+      })}
+    </>
+  );
+}
+
+/** The parts of a query that could not be used, with what to type instead, and the meaning-based search's state. */
+export function SearchNotes({ issues, semantic }: { issues: ParsedSearch['issues']; semantic: SemanticStatus }) {
+  const note = semanticNote(semantic);
+  return (
+    <>
+      {issues.length > 0 && (
+        <Alert role="status" color="yellow" my="sm" title="Part of this search was not understood">
+          <Stack gap="xs">
+            {issues.map((issue) => (
+              <Text key={issue.token + issue.message} size="sm">
+                <Text span inherit fw={600}>
+                  {issue.token}
+                </Text>{' '}
+                {issue.message}
+              </Text>
+            ))}
+          </Stack>
+        </Alert>
+      )}
+      {note && (
+        <Text role="status" size="xs" c="dimmed">
+          {note}
+        </Text>
+      )}
+    </>
+  );
+}

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

@@ -10,7 +10,7 @@
  * `type`, `label`, `branch`, `outcome`, `since` and `until`, so a link to one tab's filters opens the same query on another.
  */
 import { joinList, splitList, type ArtifactFilter } from '@crvouga/atlas/reports/artifact-query';
-import { TEST_SORTS, type TestQuery, type TestSort } from '@crvouga/atlas/reports/test-catalog';
+import { TEST_SORTS, type TestQuery } from '@crvouga/atlas/reports/test-catalog';
 import { z } from 'zod/v4';
 
 /** How the explorer groups its tests. `spec` is the default. */
@@ -18,6 +18,11 @@ export const TEST_GROUPS = ['spec', 'domain', 'environment', 'status', 'producer
 /** One of {@link TEST_GROUPS}. */
 export type TestGroup = (typeof TEST_GROUPS)[number];
 
+/** The orders the explorer offers: `relevance` (best match first, only with words to match) and those of the catalog. */
+export const EXPLORER_SORTS = ['relevance', ...TEST_SORTS] as const;
+/** One of {@link EXPLORER_SORTS}. */
+export type ExplorerSort = (typeof EXPLORER_SORTS)[number];
+
 /** A search value as text: the router reads `123` as a number and `["a"]` as an array, both of which are meant as text here. */
 const text = z
   .preprocess((value) => (typeof value === 'number' || typeof value === 'boolean' ? String(value) : value !== null && typeof value === 'object' ? JSON.stringify(value) : value), z.string().min(1))
@@ -56,7 +61,7 @@ export const ExplorerSearchFields = {
   /** Only the tests a CI run recorded (a `RunSummary.key`). Not `run`, which already names a recorded statechart run. */
   inRun: text,
   group: z.enum(TEST_GROUPS).optional().catch(undefined),
-  sort: z.enum(TEST_SORTS).optional().catch(undefined),
+  sort: z.enum(EXPLORER_SORTS).optional().catch(undefined),
   tab: z.enum(['runs', 'artifacts']).optional().catch(undefined),
   /** The run opened in the Runs tab. */
   openRun: text,
@@ -89,7 +94,7 @@ export type ExplorerSearch = {
   readonly until?: string;
   readonly inRun?: string;
   readonly group?: TestGroup;
-  readonly sort?: TestSort;
+  readonly sort?: ExplorerSort;
   readonly tab?: 'runs' | 'artifacts';
   readonly openRun?: string;
   readonly layer?: string;
@@ -113,7 +118,12 @@ export function toggled(value: string | undefined, item: string): string | undef
   return joined(list.includes(item) ? list.filter((entry) => entry !== item) : [...list, item]);
 }
 
-/** The catalog query an address asks for, without the run (it is matched separately) and without paging. */
+/** The order a list is in: what the address says, else best match when words are searched, else by spec. */
+export function sortOf(search: ExplorerSearch): ExplorerSort {
+  return search.sort ?? (search.q ? 'relevance' : 'spec');
+}
+
+/** The catalog query an address asks for, without the run (it is matched separately) and without paging. The words in `q` are matched by the shared search, not by the catalog. */
 export function queryOf(search: ExplorerSearch): TestQuery {
   return {
     ...(search.q ? { q: search.q } : {}),
@@ -126,7 +136,7 @@ export function queryOf(search: ExplorerSearch): TestQuery {
     ...(values(search.scope).length ? { scope: values(search.scope) } : {}),
     artifactTag: values(search.artifactTag),
     ...(search.inherited ? { inherited: true } : {}),
-    sort: search.sort ?? 'spec'
+    sort: search.sort === 'relevance' || !search.sort ? 'spec' : search.sort
   };
 }
 
@@ -137,7 +147,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.scope || 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 || search.video);
 }
 
 /** The filters of the Runs and Artifacts tabs, in the address. */

package/packages/visualizer/src/find/Finder.tsx

@@ -1,18 +1,26 @@
-import { Badge, Group, Kbd, List, Modal, Text } from '@mantine/core';
+import { Badge, Button, Group, Kbd, List, Modal, Stack, Text } from '@mantine/core';
 import { Spotlight, useSpotlight } from '@mantine/spotlight';
 import { useQueryClient } from '@tanstack/react-query';
 import { useNavigate, useSearch } from '@tanstack/react-router';
-import { useEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from 'react';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from 'react';
 import { useAtlas } from '../app/atlas-context';
+import { useTestCatalog } from '../explorer/catalog';
+import { SearchNotes } from '../explorer/search-notes';
 import { keys, specKey, useAdapter } from '../data/queries';
 import { useEvidence } from '../evidence/evidence-context';
 import { plural } from '../evidence/format';
 import { StatusMark } from '../evidence/marks';
 import { kindOfFile } from '../spec-kind';
+import { describeHit } from './behaviors';
 import { corpusFrom } from './corpus';
 import { finderStore, isHelpOpen, setFinderOpen, setHelpOpen, toggleFinder, useFinderOpen, useHelpOpen } from './open';
-import { FIND_GROUPS, indexCorpus, notationOf, rankIndex, splitQuery, type FindDoc, type FindKind, type FindTarget } from './rank';
-import { applySemantic, createWorkerEmbedder, embeddingsAvailable, embedText, textHash, type Embedder } from './semantic';
+import { parseSearch, passesFilters } from './query';
+import { FIND_GROUPS, indexCorpus, notationOf, rankIndex, splitQuery, type FindKind, type FindTarget, type Ranked } from './rank';
+import { applySemantic } from './semantic';
+import { useSemantic } from './semantic-search';
+
+/** The finder lists at most this many results; it says so, and offers all of them, when there are more. */
+export const FINDER_LIMIT = 40;
 
 const KIND_WORD: Record<FindKind, string> = {
   journey: 'Journey',
@@ -31,6 +39,7 @@ const SHORTCUTS: readonly {
   { keys: '/', does: 'Find a flow' },
   { keys: '↑  ↓', does: 'Move through the list' },
   { keys: 'Enter', does: 'Open' },
+  { keys: 'Shift+Enter', does: 'See all results of the search' },
   { keys: '⌘Enter  or  Ctrl+Enter', does: 'Open the recording' },
   { keys: 'Esc', does: 'Close' },
   { keys: '?', does: 'Show these shortcuts' },
@@ -102,16 +111,6 @@ function useSpecTexts(files: readonly string[], enabled: boolean, open: boolean)
   const failed = useMemo(() => files.filter((file) => failedFiles.has(file)).length, [files, failedFiles]);
   return { texts, pending, total: files.length, read, failed };
 }
-/** The vector cache outlives a keystroke, so a live run does not embed the suite again. */
-const vectorCache = new Map<string, Float32Array>();
-function vectorsFor(docs: readonly FindDoc[]): ReadonlyMap<string, Float32Array> {
-  const vectors = new Map<string, Float32Array>();
-  for (const doc of docs) {
-    const vector = vectorCache.get(textHash(embedText(doc)));
-    if (vector) vectors.set(doc.id, vector);
-  }
-  return vectors;
-}
 export function Finder() {
   const open = useFinderOpen();
   const help = useHelpOpen();
@@ -125,49 +124,85 @@ export function Finder() {
   useEffect(() => {
     if (open) setWanted(true);
   }, [open]);
-  const { texts, pending, total, read, failed } = useSpecTexts(readable, wanted, open);
+  const { texts, pending, total: specTotal, read, failed } = useSpecTexts(readable, wanted, open);
+  const catalog = useTestCatalog();
+  const tests = useMemo(() => (catalog.model ? new Map(catalog.model.tests.map((test) => [test.key, test] as const)) : undefined), [catalog.model]);
   const docs = useMemo(
-    () => corpusFrom(view, evidence.files, evidence.titleOf, evidence.view, texts),
-    [view, evidence.files, evidence.titleOf, evidence.view, texts]
+    () => corpusFrom(view, evidence.files, evidence.titleOf, evidence.view, texts, tests),
+    [view, evidence.files, evidence.titleOf, evidence.view, texts, tests]
   );
   const index = useMemo(() => indexCorpus(docs), [docs]);
   // What search has not covered yet, so an empty answer is not read as "no such behavior".
   const unindexed = evidence.filesPending
     ? 'The spec list is still loading'
     : pending
-      ? `${total - read} of ${total} specs are still being read`
+      ? `${specTotal - read} of ${specTotal} specs are still being read`
       : !evidence.ready && !evidence.unavailable
         ? 'Recorded results are still loading'
         : '';
   const [query, setQuery] = useState('');
+  const [showAll, setShowAll] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
   const store = finderStore;
   const spotlightState = useSpotlight(store);
 
-  const lexical = useMemo(() => rankIndex(index, query), [index, query]);
-  const [embedded, setEmbedded] = useState<{
-    readonly query: string;
-    readonly vector: Float32Array;
-  } | null>(null);
-  const [vectors, setVectors] = useState<ReadonlyMap<string, Float32Array>>(() => new Map());
-  const queryVector = embedded !== null && embedded.query === query.trim() ? embedded.vector : null;
+  const parsed = useMemo(() => parseSearch(query), [query]);
+  // Every match, best first: the list below is the first FINDER_LIMIT of it, and says so when there are more.
+  const everything = useMemo(() => rankIndex(index, query, Number.POSITIVE_INFINITY), [index, query]);
+  const lexical = useMemo(() => (showAll ? everything : everything.slice(0, FINDER_LIMIT)), [everything, showAll]);
   const searchable = useMemo(() => {
-    const notations = splitQuery(query).notations;
-    if (notations.size === 0) return docs;
-    return docs.filter((doc) => notations.has(notationOf(doc)));
-  }, [docs, query]);
-  const shown = useMemo(
-    () => (queryVector ? applySemantic(searchable, lexical, queryVector, vectors) : lexical),
-    [queryVector, searchable, lexical, vectors]
+    const notations = splitQuery(parsed.words).notations;
+    return docs.filter((doc) => (notations.size === 0 || notations.has(notationOf(doc))) && passesFilters(doc.facets, parsed.filters));
+  }, [docs, parsed]);
+  const lexicalDocs = useMemo(() => lexical.map((hit) => hit.doc), [lexical]);
+  const literal = parsed.phrases.length + parsed.identifiers.length > 0;
+  const semantic = useSemantic(open && parsed.words.length > 0 && !literal, parsed.words, searchable, lexicalDocs);
+  const shown = useMemo<Ranked[]>(
+    () => (semantic.queryVector ? applySemantic(searchable, lexical, semantic.queryVector, semantic.vectors, showAll ? Number.POSITIVE_INFINITY : FINDER_LIMIT) : lexical),
+    [semantic.queryVector, searchable, lexical, semantic.vectors, showAll]
   );
   const ordered = useMemo(() => FIND_GROUPS.flatMap((group) => shown.filter((hit) => hit.doc.group === group)), [shown]);
+  const total = everything.length;
+  const bounded = !showAll && total > FINDER_LIMIT;
+  const orderedRef = useRef(ordered);
+  orderedRef.current = ordered;
+  const selectedId = useRef<string | null>(null);
+  useEffect(
+    () =>
+      store.subscribe((state) => {
+        selectedId.current = orderedRef.current[Math.max(0, state.selected)]?.doc.id ?? null;
+      }),
+    [store]
+  );
 
   // Rank results ourselves, then let Spotlight own keyboard selection and scrolling.
-  // Compound Spotlight does not initialize a selection when asynchronous results arrive.
-  useEffect(() => {
-    if (open) store.setState((state) => ({ ...state, selected: 0 }));
-  }, [open, query, store]);
-  const embedder = useRef<Embedder | null>(null);
-  const embedFailed = useRef(false);
+  // Compound Spotlight does not initialize a selection when asynchronous results arrive. A new query selects its first
+  // result; results that change under the same query (specs read, meaning-based re-ranking) keep the selected result
+  // selected by identity, and say so when it is gone, so Enter always opens what is highlighted.
+  const lastQuery = useRef<string | null>(null);
+  useLayoutEffect(() => {
+    if (!open) {
+      lastQuery.current = null;
+      return;
+    }
+    const first = ordered[0]?.doc.id ?? null;
+    if (lastQuery.current !== query) {
+      lastQuery.current = query;
+      selectedId.current = first;
+      setNotice(null);
+      setShowAll(false);
+      store.setState((state) => ({ ...state, selected: 0 }));
+      return;
+    }
+    const kept = selectedId.current === null ? -1 : ordered.findIndex((hit) => hit.doc.id === selectedId.current);
+    if (kept >= 0) {
+      if (store.getState().selected !== kept) store.setState((state) => ({ ...state, selected: kept }));
+    } else {
+      if (selectedId.current !== null) setNotice('The results changed and the selected result is no longer listed, so the first result is selected.');
+      selectedId.current = first;
+      store.setState((state) => ({ ...state, selected: 0 }));
+    }
+  }, [open, query, ordered, store]);
   useEffect(() => {
     if (open) return;
     setQuery('');
@@ -198,40 +233,6 @@ export function Finder() {
     window.addEventListener('keydown', onKey);
     return () => window.removeEventListener('keydown', onKey);
   }, []);
-  useEffect(() => {
-    if (!open || embedFailed.current || !embeddingsAvailable() || query.trim().length === 0) return;
-    let cancelled = false;
-    const needle = query.trim();
-    embedder.current ??= createWorkerEmbedder();
-    const rankedFirst = new Set(lexical.map((hit) => hit.doc.id));
-    const ordered = [...lexical.map((hit) => hit.doc), ...docs.filter((doc) => !rankedFirst.has(doc.id))];
-    void (async () => {
-      try {
-        const embedded = await embedder.current!.embed([needle]);
-        const nextQuery = embedded[0];
-        if (cancelled || !nextQuery) return;
-        setEmbedded({ query: needle, vector: nextQuery });
-        for (let start = 0; start < ordered.length && !cancelled; start += 8) {
-          const batch = ordered.slice(start, start + 8);
-          const missing = batch.filter((doc) => !vectorCache.has(textHash(embedText(doc))));
-          if (missing.length > 0) {
-            const batchVectors = await embedder.current!.embed(missing.map((doc) => embedText(doc)));
-            if (cancelled) return;
-            missing.forEach((doc, at) => {
-              const vector = batchVectors[at];
-              if (vector) vectorCache.set(textHash(embedText(doc)), vector);
-            });
-          }
-          if (!cancelled) setVectors(vectorsFor(docs));
-        }
-      } catch {
-        embedFailed.current = true;
-      }
-    })();
-    return () => {
-      cancelled = true;
-    };
-  }, [open, query, docs, lexical]);
   const openTarget = (target: FindTarget) => {
     const run = typeof routeSearch.run === 'string' ? routeSearch.run : undefined;
     if (target.to === '/chart/$chartId' && target.chartId) {
@@ -253,7 +254,22 @@ export function Finder() {
     }
     setFinderOpen(false);
   };
+  // The full results of a search: the explorer's list when the project has one (it filters, counts and sorts everything),
+  // else every result in this list.
+  const seeAll = () => {
+    if (catalog.model && query.trim()) {
+      const run = typeof routeSearch.run === 'string' ? routeSearch.run : undefined;
+      void navigate({ to: '/', search: { run, q: query.trim() } });
+      setFinderOpen(false);
+    } else setShowAll(true);
+  };
   const onCommandKey = (event: ReactKeyboardEvent) => {
+    if (event.key === 'Enter' && event.shiftKey && !event.metaKey && !event.ctrlKey) {
+      event.preventDefault();
+      event.stopPropagation();
+      seeAll();
+      return;
+    }
     if (event.key !== 'Enter' || (!event.metaKey && !event.ctrlKey)) return;
     event.preventDefault();
     event.stopPropagation();
@@ -311,9 +327,15 @@ export function Finder() {
                     aria-selected={ordered[Math.max(0, spotlightState.selected)]?.doc.id === hit.doc.id}
                     onClick={() => openTarget(hit.doc.target)}
                     label={hit.doc.title}
-                    description={[hit.snippet !== hit.doc.subtitle ? hit.snippet : '', hit.doc.subtitle].filter(Boolean).join(' · ')}
+                    description={[hit.snippet !== hit.doc.subtitle ? hit.snippet : '', hit.doc.subtitle, query.trim() ? describeHit(hit) : ''].filter(Boolean).join(' · ')}
                     leftSection={hit.doc.status ? <StatusMark status={hit.doc.status} size={16} /> : undefined}
-                    rightSection={<Badge color="gray">{KIND_WORD[hit.doc.kind]}</Badge>}
+                    rightSection={
+                      <Group gap="xs" wrap="nowrap">
+                        {hit.exact && <Badge color="blue">Exact</Badge>}
+                        {hit.partial && <Badge color="gray" variant="outline">Partial</Badge>}
+                        <Badge color="gray">{KIND_WORD[hit.doc.kind]}</Badge>
+                      </Group>
+                    }
                   />
                 ))}
               </Spotlight.ActionsGroup>
@@ -321,13 +343,37 @@ export function Finder() {
           })}
         </Spotlight.ActionsList>
         <Spotlight.Footer>
-          <Group gap="md" justify="space-between">
-            <Text size="xs" c="dimmed">
-              {unindexed ? `Searching what is read so far: ${unindexed}` : failed > 0 ? `${plural(failed, 'spec', 'specs')} could not be read and ${failed === 1 ? 'is' : 'are'} not searched` : '↑↓ move'}
-            </Text>
-            <Text size="xs" c="dimmed">
-              ↵ open · esc close
-            </Text>
+          <Group gap="md" justify="space-between" align="flex-start">
+            <Stack gap={0}>
+              <Text role="status" size="xs" c="dimmed">
+                {query.trim() && total > 0
+                  ? bounded
+                    ? `Showing the first ${shown.length} of ${total} results, not all of them.`
+                    : `${total} ${total === 1 ? 'result' : 'results'}.`
+                  : '↑↓ move'}
+              </Text>
+              {(unindexed || failed > 0) && (
+                <Text role="status" size="xs" c="dimmed">
+                  {unindexed ? `Searching what is read so far: ${unindexed}` : `${plural(failed, 'spec', 'specs')} could not be read and ${failed === 1 ? 'is' : 'are'} not searched`}
+                </Text>
+              )}
+              {notice && (
+                <Text role="status" size="xs" c="dimmed">
+                  {notice}
+                </Text>
+              )}
+              <SearchNotes issues={parsed.issues} semantic={query.trim() ? semantic.status : 'idle'} />
+            </Stack>
+            <Group gap="xs" wrap="wrap" justify="flex-end">
+              {bounded && (
+                <Button size="compact-xs" variant="light" onClick={seeAll}>
+                  See all {total} results
+                </Button>
+              )}
+              <Text size="xs" c="dimmed">
+                ↵ open · ⇧↵ all results · esc close
+              </Text>
+            </Group>
           </Group>
         </Spotlight.Footer>
       </Spotlight.Root>

package/packages/visualizer/src/find/behaviors.ts

@@ -0,0 +1,205 @@
+/**
+ * @module Searchable behaviors, results and runs
+ *
+ * The documents every search surface matches against, built from one place so they cannot disagree. A recorded
+ * behavior (`TestSummary`) is searched by the same fields wherever it appears: the finder's Runs group, the test list
+ * and the results of an opened run all call {@link testFields} and {@link testFacets}. They differ only in what the
+ * structured filters say about this particular appearance (a run's result has the status, environment and videos of
+ * that run, not of the latest combined evidence), so the same words always give the same eligible behaviors.
+ */
+import { videoCounts } from '@crvouga/atlas/reports/evidence-detail';
+import type { RunResult, RunSummary, TestSummary } from '@crvouga/atlas/reports/test-catalog';
+
+import type { DocFacets, ParsedSearch, SearchIssue, SearchFilters } from './query';
+import { NO_FILTERS, SYNTAX_HELP } from './query';
+import type { FieldName, FindDoc, FindField, FindStatus, Ranked } from './rank';
+
+/** True when a behavior's current results reference at least one playable video recording. */
+export function testHasVideo(test: Pick<TestSummary, 'outcomes'>): boolean {
+  return test.outcomes.some((outcome) => (videoCounts(outcome.evidence?.videos)?.recordings ?? 0) > 0);
+}
+
+/** The id of the finder document of a behavior (`run:` followed by its `TestSummary.key`): the identity every surface shares. */
+export function behaviorId(key: string): string {
+  return `run:${key}`;
+}
+
+/** What the filters read about a behavior: its current status, where it ran, its domain, spec, tags and branches, and its videos. */
+export function testFacets(test: TestSummary): DocFacets {
+  return {
+    status: [test.status, ...(test.stats.flaky ? ['flaky'] : [])],
+    env: test.environments.length ? test.environments : ['(none)'],
+    producer: test.producers,
+    domain: [test.spec?.domain || '(no spec)'],
+    spec: test.specPath ? [test.specPath] : [],
+    tag: [...test.tags, ...(test.artifactTags ?? []), ...(test.inheritedArtifactTags ?? [])].map((tag) => tag.replace(/^#/, '')),
+    branch: test.stats.branches,
+    video: testHasVideo(test)
+  };
+}
+
+/** The first line of a failure, for finding a behavior by what went wrong. */
+function failureLines(test: TestSummary): string[] {
+  return test.outcomes.filter((outcome) => outcome.status === 'failed' && outcome.detail).map((outcome) => outcome.detail.split('\n')[0]!);
+}
+
+/** The searchable texts of a behavior: title, path and identifier, spec and failures, and metadata. Every surface uses these. */
+export function testFields(test: TestSummary): FindField[] {
+  const fields: FindField[] = [{ name: 'title', text: test.title }];
+  fields.push({ name: 'path', text: [test.specPath ?? '', test.id].filter(Boolean).join('\n') });
+  const description = [test.spec?.title ?? '', ...failureLines(test)].filter(Boolean).join('\n');
+  if (description) fields.push({ name: 'description', text: description });
+  const metadata = [
+    test.spec?.domain ?? '',
+    ...test.tags,
+    ...(test.artifactTags ?? []),
+    ...Object.entries(test.labels).flatMap(([key, value]) => [key, value]),
+    ...test.environments,
+    ...test.producers
+  ].filter(Boolean);
+  if (metadata.length) fields.push({ name: 'metadata', text: metadata.join('\n') });
+  return fields;
+}
+
+function findStatus(status: TestSummary['status']): FindStatus {
+  return status;
+}
+
+/** A behavior as a document. Its id is {@link behaviorId}. */
+export function testDoc(test: TestSummary): FindDoc {
+  return {
+    id: behaviorId(test.key),
+    group: 'Runs',
+    kind: 'run',
+    title: test.title,
+    subtitle: test.specPath ?? '',
+    fields: testFields(test),
+    status: findStatus(test.status),
+    related: [],
+    target: { to: '/', search: { test: test.key } },
+    recording: null,
+    facets: testFacets(test)
+  };
+}
+
+const documents = new WeakMap<readonly TestSummary[], ReadonlyMap<string, FindDoc>>();
+
+/**
+ * The documents of every behavior of a report by `TestSummary.key`, built once per list of tests. Every surface that
+ * searches behaviors (the test list, the results of a run) searches this same set, so the same words are judged against
+ * the same vocabulary and the same behaviors are eligible.
+ */
+export function behaviorDocs(tests: readonly TestSummary[]): ReadonlyMap<string, FindDoc> {
+  let found = documents.get(tests);
+  if (!found) {
+    found = new Map(tests.map((test) => [test.key, testDoc(test)] as const));
+    documents.set(tests, found);
+  }
+  return found;
+}
+
+/**
+ * The result of a behavior within one run as a document: the behavior's own fields (so it matches exactly when the
+ * behavior does), with the status, environment, producer and videos of this result for the filters. Without the
+ * behavior in the report any more, its title, spec and environment are all there is to match.
+ */
+export function resultDoc(result: RunResult, test: TestSummary | undefined): FindDoc {
+  const base: FindDoc = test
+    ? testDoc(test)
+    : {
+        id: behaviorId(result.key),
+        group: 'Runs',
+        kind: 'run',
+        title: result.title,
+        subtitle: result.specPath ?? '',
+        fields: [
+          { name: 'title', text: result.title },
+          { name: 'path', text: [result.specPath ?? '', result.id].filter(Boolean).join('\n') },
+          { name: 'metadata', text: [result.environment ?? '', result.producer].filter(Boolean).join('\n') }
+        ],
+        status: findStatus(result.status),
+        related: [],
+        target: { to: '/', search: { test: result.key } },
+        recording: null
+      };
+  const facets = base.facets;
+  return {
+    ...base,
+    status: findStatus(result.status),
+    facets: {
+      status: [result.status, ...(facets?.status.includes('flaky') ? ['flaky'] : [])],
+      env: [result.environment ?? '(none)'],
+      producer: [result.producer],
+      domain: facets?.domain ?? ['(no spec)'],
+      spec: result.specPath ? [result.specPath] : [],
+      tag: facets?.tag ?? [],
+      branch: facets?.branch ?? [],
+      video: (videoCounts(result.videos)?.recordings ?? 0) > 0
+    }
+  };
+}
+
+/** What a run is searched by: its label, commit and branch, environments, producers, and the tests that failed in it. */
+export function runDoc(run: RunSummary, label: string): FindDoc {
+  const status = run.counts.failed > 0 ? 'failed' : run.counts.running > 0 ? 'running' : run.counts['not-run'] > 0 ? 'not-run' : 'passed';
+  return {
+    id: `runs:${run.key}`,
+    group: 'Runs',
+    kind: 'run',
+    title: label,
+    subtitle: [run.branch, run.sha?.slice(0, 7)].filter(Boolean).join(' @ '),
+    fields: [
+      { name: 'title', text: label },
+      { name: 'path', text: [run.key, run.branch ?? '', run.sha ?? '', run.runId ?? ''].filter(Boolean).join('\n') },
+      { name: 'description', text: run.failing.flatMap((failure) => [failure.title, failure.detail.split('\n')[0] ?? '']).filter(Boolean).join('\n') },
+      { name: 'metadata', text: [...run.environments, ...run.producers].join('\n') }
+    ],
+    status,
+    related: [],
+    target: { to: '/', search: {} },
+    recording: null,
+    facets: {
+      status: [...(run.counts.failed > 0 ? ['failed'] : []), ...(run.counts.running > 0 ? ['running'] : []), ...(run.counts['not-run'] > 0 ? ['not-run'] : []), ...(run.counts.passed > 0 ? ['passed'] : [])],
+      env: run.environments.length ? run.environments : ['(none)'],
+      producer: run.producers,
+      domain: [],
+      spec: [],
+      tag: [],
+      branch: run.branch ? [run.branch] : [],
+      video: (run.videos?.recordings ?? 0) > 0
+    }
+  };
+}
+
+/**
+ * A search for a list that has no domain, spec or tag (the runs): those filters are removed and said so, instead of
+ * silently emptying the list or pretending to filter.
+ */
+export function forRuns(parsed: ParsedSearch): ParsedSearch {
+  const issues: SearchIssue[] = [...parsed.issues];
+  const dropped = parsed.tokens.filter((token) => token.key === 'domain' || token.key === 'spec' || token.key === 'tag');
+  for (const token of dropped) issues.push({ token: token.text, message: `does not apply to runs, so it filters nothing here. Open a run to filter its tests by ${token.key}:. ${SYNTAX_HELP}` });
+  const filters: SearchFilters = { ...parsed.filters, domain: NO_FILTERS.domain, spec: NO_FILTERS.spec, tag: NO_FILTERS.tag };
+  return { ...parsed, filters, tokens: parsed.tokens.filter((token) => !dropped.includes(token)), issues };
+}
+
+const FIELD_WORD: Record<FieldName, string> = {
+  title: 'title',
+  steps: 'steps',
+  description: 'description',
+  metadata: 'tags and details',
+  path: 'path or identifier'
+};
+
+/**
+ * Why a document is in the results, for a person: an exact phrase or identifier, the fields the words were found
+ * in, and whether a close spelling or only the meaning brought it. Empty for a hit that carries no reason (a browse).
+ */
+export function describeHit(hit: Pick<Ranked, 'fields' | 'exact' | 'literals' | 'fuzzy' | 'partial' | 'semantic' | 'related'>): string {
+  const parts: string[] = [];
+  if (hit.exact && hit.literals?.length) parts.push(`Exact: ${hit.literals.map((literal) => `“${literal}”`).join(', ')}`);
+  if (hit.semantic) parts.push('Similar meaning');
+  else if (hit.fields?.length) parts.push(`${hit.partial ? 'Some words in' : 'Matches'} ${hit.fields.map((field) => FIELD_WORD[field]).join(', ')}${hit.fuzzy ? ' (close spelling)' : ''}`);
+  if (hit.related && !parts.length) parts.push('Related to a match');
+  return parts.join(' · ');
+}