@crvouga/atlas 1.5.0 → 1.6.0

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(' · ');
+}

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

@@ -5,6 +5,8 @@ import type { AtlasView, ItemStatus } from '../data/model';
 import { worstOf } from '../data/model/status';
 import { featureModel, scenarioLabel, slotsByScenario } from '../evidence/gherkin';
 import { kindOfFile, outlinePath, specFile } from '../spec-kind';
+import type { TestSummary } from '@crvouga/atlas/reports/test-catalog';
+import { testFacets, testFields } from './behaviors';
 import type { FindDoc, FindField, FindStatus, FindTarget } from './rank';
 
 export type CorpusChart = { readonly id: string; readonly name: string };
@@ -67,6 +69,8 @@ export type CorpusSource = {
   readonly texts: ReadonlyMap<string, string>;
   /** The project home is the test explorer (no statecharts): a check without a published spec opens there. */
   readonly explorer?: boolean;
+  /** The report's tests by key. A check that is one of them is searched by the same fields and filters as in the test list. */
+  readonly tests?: ReadonlyMap<string, TestSummary>;
 };
 
 function itemStatus(status: ItemStatus): FindStatus {
@@ -130,9 +134,17 @@ function actionsIn(text: string): string[] {
   return [...new Set([...text.matchAll(ACTION)].map((match) => match[1]!))];
 }
 
-function runDoc(slot: CorpusSlot, title: string, kind: string | null, file: string, explorer = false): FindDoc {
+/** A check's fields: those the test list searches, else what the check itself says. */
+function checkFields(slot: CorpusSlot, title: string, file: string, test: TestSummary | undefined): { fields: FindField[]; facets?: FindDoc['facets'] } {
+  if (!test) return { fields: fieldsOf(title, '', slot.detail, file) };
+  const fields = testFields(test);
+  return { fields: title === test.title ? fields : [{ name: 'title', text: title }, ...fields], facets: testFacets(test) };
+}
+
+function runDoc(slot: CorpusSlot, title: string, kind: string | null, file: string, explorer = false, test?: TestSummary): FindDoc {
+  const { fields, facets } = checkFields(slot, title, file, test);
   if (explorer) {
-    return { id: `run:${slot.key}`, group: 'Runs', kind: 'run', title, subtitle: file, fields: fieldsOf(title, '', slot.detail, file), status: slot.status, related: [], target: { to: '/', search: { test: slot.key } }, recording: null };
+    return { id: `run:${slot.key}`, group: 'Runs', kind: 'run', title, subtitle: file, fields, status: slot.status, related: [], target: { to: '/', search: { test: slot.key } }, recording: null, ...(facets ? { facets } : {}) };
   }
   const recording = timelineTarget(kind, file, [slot]);
   return {
@@ -141,12 +153,13 @@ function runDoc(slot: CorpusSlot, title: string, kind: string | null, file: stri
     kind: 'run',
     title,
     subtitle: file,
-    fields: fieldsOf(title, '', slot.detail, file),
+    fields,
     status: slot.status,
     related: [],
     // Enter opens the recording when this check has a timeline.
     target: recording ?? (kind ? specTarget(kind, file, slot.id) : { to: '/' as const, search: {} }),
-    recording
+    recording,
+    ...(facets ? { facets } : {})
   };
 }
 
@@ -231,7 +244,7 @@ export function buildCorpus(source: CorpusSource): FindDoc[] {
     const id = `run:${slot.key}`;
     if (seenRuns.has(id)) return;
     seenRuns.add(id);
-    docs.push(runDoc(slot, title, kind, file, explorer));
+    docs.push(runDoc(slot, title, kind, file, explorer, source.tests?.get(slot.key)));
   };
 
   for (const file of source.files) {
@@ -326,7 +339,7 @@ export function buildCorpus(source: CorpusSource): FindDoc[] {
 }
 
 /** The view and the evidence the page already holds, in the shape `buildCorpus` reads. */
-export function corpusFrom(view: AtlasView | null, files: readonly string[], titleOf: (file: string) => string, evidence: EvidenceView, texts: ReadonlyMap<string, string>): FindDoc[] {
+export function corpusFrom(view: AtlasView | null, files: readonly string[], titleOf: (file: string) => string, evidence: EvidenceView, texts: ReadonlyMap<string, string>, tests?: ReadonlyMap<string, TestSummary>): FindDoc[] {
   const slots: CorpusSlot[] = [];
   const take = (slot: CheckSlot) => {
     slots.push({
@@ -370,6 +383,7 @@ export function corpusFrom(view: AtlasView | null, files: readonly string[], tit
     files: files.map((path) => ({ path, title: titleOf(path) })),
     slots,
     texts,
-    explorer: !files.some(isStatechartFile)
+    explorer: !files.some(isStatechartFile),
+    ...(tests ? { tests } : {})
   });
 }

package/packages/visualizer/src/find/doc-search.ts

@@ -0,0 +1,66 @@
+/**
+ * @module Searching a list of documents
+ *
+ * What the test list, the runs list and the results of an opened run call to narrow themselves by a typed query. It is
+ * the finder's engine (`rank.ts`) applied to a whole list: every document that is eligible for the words, phrases and
+ * identifiers of the query, best first, with the reason it matched; meaning-based additions when an embedder is
+ * available. The structured filters (`status:`, `has:video`…) are applied by the caller with `passesFilters`, so a
+ * count can leave one of them out; nothing here limits or pages the result.
+ */
+import { useMemo } from 'react';
+
+import { applySemantic } from './semantic';
+import { indexCorpus, matchText, type FindDoc, type FindIndex, type Ranked } from './rank';
+import { parseSearch, passesFilters, type ParsedSearch } from './query';
+import { useSemantic, type SemanticStatus } from './semantic-search';
+
+/** The semantic part of a search to add to the words, when there is one. */
+export type SemanticInput = {
+  readonly queryVector: Float32Array | null;
+  readonly vectors: ReadonlyMap<string, Float32Array>;
+  /** The documents a paraphrase may add (those that pass the filters). */
+  readonly docs: readonly FindDoc[];
+};
+
+/**
+ * Every document eligible for the text of a search (words, quoted phrases, identifiers), best first, by document id; null
+ * when the search has no text. A document missing a distinctive word is not eligible. With a semantic input, documents
+ * close in meaning are added (not when the search asks for an exact phrase or identifier).
+ */
+export function searchList(index: FindIndex, parsed: ParsedSearch, semantic?: SemanticInput): Map<string, Ranked> | null {
+  const lexical = matchText(index, parsed, { snippets: false });
+  if (lexical === null) return null;
+  const plain: Ranked[] = lexical.map(({ order: _order, misses: _misses, ...hit }) => hit);
+  const literal = parsed.phrases.length + parsed.identifiers.length > 0;
+  const list = semantic?.queryVector && !literal ? applySemantic(semantic.docs, plain, semantic.queryVector, semantic.vectors, Number.POSITIVE_INFINITY) : plain;
+  return new Map(list.map((hit) => [hit.doc.id, hit]));
+}
+
+/** What {@link useDocSearch} reads out. */
+export type DocSearch = {
+  readonly parsed: ParsedSearch;
+  /** Eligible documents by id, best first; null when the query has no text to match (it may still have filters). */
+  readonly hits: ReadonlyMap<string, Ranked> | null;
+  /** How the meaning-based part stands: idle when there is nothing to match by meaning. */
+  readonly status: SemanticStatus;
+};
+
+/**
+ * Parses `query` and searches `docs` with it: lexical results at once, meaning-based additions when they arrive. The
+ * index is only built when the query has text.
+ */
+export function useDocSearch(docs: readonly FindDoc[], query: string | undefined): DocSearch {
+  const parsed = useMemo(() => parseSearch(query ?? ''), [query]);
+  const hasText = parsed.words.length > 0 || parsed.phrases.length > 0 || parsed.identifiers.length > 0;
+  const index = useMemo(() => (hasText ? indexCorpus(docs) : null), [docs, hasText]);
+  const lexical = useMemo(() => (index ? searchList(index, parsed) : null), [index, parsed]);
+  const candidates = useMemo(() => (hasText ? docs.filter((doc) => passesFilters(doc.facets, parsed.filters)) : []), [docs, parsed, hasText]);
+  const lexicalDocs = useMemo(() => (lexical ? [...lexical.values()].map((hit) => hit.doc) : []), [lexical]);
+  const wantsMeaning = hasText && parsed.words.length > 0 && parsed.phrases.length + parsed.identifiers.length === 0;
+  const semantic = useSemantic(wantsMeaning, parsed.words, candidates, lexicalDocs);
+  const hits = useMemo(
+    () => (index ? searchList(index, parsed, { queryVector: semantic.queryVector, vectors: semantic.vectors, docs: candidates }) : null),
+    [index, parsed, semantic.queryVector, semantic.vectors, candidates]
+  );
+  return { parsed, hits, status: wantsMeaning ? semantic.status : 'idle' };
+}