@crvouga/atlas 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog: @crvouga/atlas
 
-## 1.5.0 (2026-10-29)
+## 1.6.0 (2026-10-29)
+
+### Features
+
+- unify fuzzy semantic search with complete filterable sortable results ([3b0b90e](https://github.com/crvouga/atlas/commit/3b0b90e4960dcbcbcfee924f33aca4ce02beaaec))
+
+## 1.5.0 (2026-10-28)
 
 ### Features
 

package/docs/ui.md

@@ -101,6 +101,16 @@ visible notation label; marks are decorative. Sources, licenses and the DMN nota
 and update this mapping when adding a format. Brand artwork preserves upstream colors independently of
 Atlas's theme. SVG data plots and statechart arrow markers are geometry, not handcrafted UI icons.
 
+## Search
+
+All search boxes (finder, test list, Runs tab, an opened run) use `src/find/query.ts` for the query language and
+`src/find/rank.ts` for matching; do not add a second matcher or filter on `includes`. Build documents from
+`src/find/behaviors.ts` so a behavior has the same fields and facets everywhere. Match first, then count, filter and sort
+the whole set, then page. Show filters typed in the box as removable chips, show what was not understood
+(`SearchNotes`), show why a result matched and mark exact ones, and say when matching is words only (no embedder, or
+a failed one). A bounded list says it is bounded and offers all results. Selection follows result identity, never a
+position, when results change. The query, filters and sort stay in the address.
+
 ## Accessibility and responsive behavior
 
 The shell collapses its index below Mantine's `md` breakpoint; its named Burger toggles mobile navigation.
@@ -151,7 +161,7 @@ The narrowly scoped exceptions are:
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
 | Evidence | Steps, retries, annotations, facts, unknown extensions, safe downloads and previews | List, Badge, Accordion, Code, Image, native media |
 | Recordings | Pictures/video/timeline, actor selection, moments, failure jumps, timing, model-state differences | Tabs, Slider, Button, ScrollArea, Table, Progress |
-| Search/help | Ranked and semantic search, shortcut help, recording shortcuts | Spotlight, Modal, Kbd |
+| Search/help | Ranked, filterable and semantic search across behaviors, runs and results; complete results; shortcut help, recording shortcuts | Spotlight, TextInput, NativeSelect, Button chips, Alert, Modal, Kbd |
 | Administration | Token access, S3 storage notice, garbage collection policy (saved in S3), live timeouts, report rules, limits, raw JSON, conflicts | Same provider/theme, Fieldset, Mantine inputs, Accordion, Alert |
 
 The hash routes (`/`, `/chart/$chartId`, `/specs/$kind`), query contracts, project scoping, streaming,

package/llms-full.txt

@@ -3933,6 +3933,16 @@ visible notation label; marks are decorative. Sources, licenses and the DMN nota
 and update this mapping when adding a format. Brand artwork preserves upstream colors independently of
 Atlas's theme. SVG data plots and statechart arrow markers are geometry, not handcrafted UI icons.
 
+## Search
+
+All search boxes (finder, test list, Runs tab, an opened run) use `src/find/query.ts` for the query language and
+`src/find/rank.ts` for matching; do not add a second matcher or filter on `includes`. Build documents from
+`src/find/behaviors.ts` so a behavior has the same fields and facets everywhere. Match first, then count, filter and sort
+the whole set, then page. Show filters typed in the box as removable chips, show what was not understood
+(`SearchNotes`), show why a result matched and mark exact ones, and say when matching is words only (no embedder, or
+a failed one). A bounded list says it is bounded and offers all results. Selection follows result identity, never a
+position, when results change. The query, filters and sort stay in the address.
+
 ## Accessibility and responsive behavior
 
 The shell collapses its index below Mantine's `md` breakpoint; its named Burger toggles mobile navigation.
@@ -3983,7 +3993,7 @@ The narrowly scoped exceptions are:
 | Statecharts | Graph, screen/event/journey details, developer metadata, chart test results | Mantine cards/navigation and product compositions; graph exception above |
 | Evidence | Steps, retries, annotations, facts, unknown extensions, safe downloads and previews | List, Badge, Accordion, Code, Image, native media |
 | Recordings | Pictures/video/timeline, actor selection, moments, failure jumps, timing, model-state differences | Tabs, Slider, Button, ScrollArea, Table, Progress |
-| Search/help | Ranked and semantic search, shortcut help, recording shortcuts | Spotlight, Modal, Kbd |
+| Search/help | Ranked, filterable and semantic search across behaviors, runs and results; complete results; shortcut help, recording shortcuts | Spotlight, TextInput, NativeSelect, Button chips, Alert, Modal, Kbd |
 | Administration | Token access, S3 storage notice, garbage collection policy (saved in S3), live timeouts, report rules, limits, raw JSON, conflicts | Same provider/theme, Fieldset, Mantine inputs, Accordion, Alert |
 
 The hash routes (`/`, `/chart/$chartId`, `/specs/$kind`), query contracts, project scoping, streaming,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",

package/packages/visualizer/README.md

@@ -154,6 +154,34 @@ Components read only the view model (`AtlasView`), never raw files.
   its own worker. Positions are cached under a hash of the chart's structure only, so new results
   never move anything.
 
+## Searching behaviors, runs and recordings
+
+Every search box (the finder opened with `Ctrl+K` or `/`, the test list, the Runs tab and the results of an opened
+run) reads one query language and matches with one engine (`src/find/query.ts`, `src/find/rank.ts`), so the same words
+make the same behaviors eligible everywhere.
+
+- **Words** match titles, steps, descriptions, specs, tags, environments and failure messages by stem, everyday synonym
+  and close spelling (`savde answer` finds "Keep a saved answer"), and the start of a longer word while it is typed.
+  Every distinctive word must be found; a word present in most behaviors is optional. When an embedder is available the
+  results are also re-ranked by meaning and a paraphrase with no word in common is added (`Similar meaning`); when none
+  is, or it fails, the box says it is matching words and spellings only.
+- **Exact matches.** `"a quoted phrase"` and identifiers with `/`, `_` or `.` (`memory/keep`) must appear as written, are
+  marked `Exact` and are listed first.
+- **Filters** narrow by structure instead of matching words: `status:failed` (`passed`, `failed`, `flaky`, `not-run`,
+  `running`), `env:ios` (also `platform:`, `environment:`, `device:`), `producer:`, `domain:`, `spec:`, `tag:`, `branch:`
+  and `has:video` (a playable recording, not the word). Values of one field are alternatives (`status:failed,flaky`);
+  different fields all hold. Each shows as a removable chip, and the status, environment and Has video buttons are the
+  same filters without the syntax.
+- **Nothing is dropped silently.** An unknown operator, an unknown status, an unclosed quote, or a filter a list does not
+  have (`domain:` on runs) is listed under the box with what to type instead.
+- **Complete results.** Counts, filters and sorting (including Best match, offered with words to match) apply to the whole
+  dataset before anything is shown in pages. The finder shows its first 40 results, says so, and opens all of them
+  (`Shift+Enter`, or the explorer's list for the same query). The query, filters and sort are in the address, so a link
+  and the back button restore them. Results that change under the cursor keep the highlighted result highlighted by
+  identity, and say so when it is no longer listed.
+
+The standing rules are in [the UI conventions](../../docs/ui.md#search).
+
 ## Fixtures
 
 `fixtures/` holds seven scenarios generated by `scripts/make-fixtures.ts` from `example/specs`, a

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

@@ -1,5 +1,5 @@
 import { SpecLogo } from '../components/SpecLogo';
-import { IconX } from '@tabler/icons-react';
+import { IconVideo, IconX } from '@tabler/icons-react';
 import {
   Accordion,
   Alert,
@@ -37,11 +37,9 @@ import {
   durationStats,
   formatMs,
   matchesQuery,
-  TEST_SORTS,
   testCatalog,
   type CatalogModel,
   type TestQuery,
-  type TestSort,
   type TestSummary
 } from '@crvouga/atlas/reports/test-catalog';
 import { Link } from '@tanstack/react-router';
@@ -50,13 +48,18 @@ import { useEvidence } from '../evidence/evidence-context';
 import { ago, plural, useNow } from '../evidence/format';
 import { Meter, StatusMark } from '../evidence/marks';
 import { SPEC_KINDS } from '../spec-kind';
+import { behaviorDocs, behaviorId, describeHit, testHasVideo } from '../find/behaviors';
+import { useDocSearch } from '../find/doc-search';
+import { hasFilters, passesFilters, withoutToken, type FilterKey, type ParsedSearch } from '../find/query';
+import type { FindDoc, Ranked } from '../find/rank';
 import { useRunDetail, useTestCatalog } from './catalog';
 import { groupTests, tally, type TestGroupView } from './groups';
 import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
 import { Badges, EnvironmentChips, projectTitle, runName } from './parts';
 import { ArtifactsView } from './ArtifactsView';
 import { RunsView } from './RunsView';
-import { joined, narrowed, queryOf, TEST_GROUPS, toggled, values, type ExplorerSearch, type TestGroup } from './search';
+import { SearchNotes, TypedFilters } from './search-notes';
+import { EXPLORER_SORTS, joined, narrowed, queryOf, sortOf, TEST_GROUPS, toggled, values, type ExplorerSearch, type ExplorerSort, type TestGroup } from './search';
 import { TestDetail } from './TestDetail';
 /** Groups start closed when there are more of them than this, unless the list is short. */
 const OPEN_GROUPS = 40;
@@ -71,7 +74,8 @@ const GROUP_LABEL: Record<TestGroup, string> = {
   producer: 'Producer',
   none: 'None'
 };
-const SORT_LABEL: Record<TestSort, string> = {
+const SORT_LABEL: Record<ExplorerSort, string> = {
+  relevance: 'Best match',
   spec: 'Spec',
   title: 'Title',
   recent: 'Most recent',
@@ -91,30 +95,59 @@ const STATUS_FILTERS = [
 function percent(rate: number | null): string {
   return rate === null ? '—' : `${Math.round(rate * 100)}%`;
 }
-/** What the explorer lists for an address: the tests shown, and the scope the insight strip and filter counts describe. */
+const NO_STRUCTURE: ReadonlySet<FilterKey> = new Set();
+const WITHOUT_STATUS_AND_ENVIRONMENT: ReadonlySet<FilterKey> = new Set<FilterKey>(['status', 'env']);
+const WITHOUT_STATUS: ReadonlySet<FilterKey> = new Set<FilterKey>(['status']);
+const WITHOUT_ENVIRONMENT: ReadonlySet<FilterKey> = new Set<FilterKey>(['env']);
+const WITHOUT_VIDEO: ReadonlySet<FilterKey> = new Set<FilterKey>(['video']);
+/**
+ * What the explorer lists for an address: the tests shown, and the scope the insight strip and filter counts describe.
+ * The words, quoted phrases and filters typed in the search box are read by the shared search (`find/`), over every
+ * test, before anything is counted or ordered; nothing is cut to a page here.
+ */
 function useListing(model: CatalogModel | null, search: ExplorerSearch, q: string | undefined) {
   const run = useRunDetail(search.inRun);
   const inRun = useMemo(
     () => (search.inRun ? new Set(run.data?.results.map((result) => result.key) ?? []) : null),
     [search.inRun, run.data]
   );
-  return useMemo(() => {
+  const docs = useMemo(() => ((q || search.video) && model ? behaviorDocs(model.tests) : new Map<string, FindDoc>()), [q, search.video, model?.tests]);
+  const list = useMemo(() => [...docs.values()], [docs]);
+  const found = useDocSearch(list, q);
+  const sort = sortOf(search);
+  const listing = useMemo(() => {
     if (!model) return null;
-    const query: TestQuery = { ...queryOf(search), ...(q ? { q } : { q: undefined }) };
-    const shown = testCatalog(model, { ...query, limit: 20000 }).tests.filter((test) => !inRun || inRun.has(test.key));
+    const query: TestQuery = { ...queryOf(search), q: undefined };
+    // `has:video` typed in the box and the Has video button are the same filter.
+    const operator = { ...found.parsed.filters, video: found.parsed.filters.video || search.video === true };
+    const structured = hasFilters(operator);
+    const hits = found.hits;
+    const passes = (test: TestSummary, omit: ReadonlySet<FilterKey>) =>
+      (!hits || hits.has(behaviorId(test.key))) && (!structured || passesFilters(docs.get(test.key)?.facets, operator, omit));
+    let shown = testCatalog(model, { ...query, limit: 20000 }).tests.filter((test) => (!inRun || inRun.has(test.key)) && passes(test, NO_STRUCTURE));
+    if (sort === 'relevance' && hits) {
+      const order = new Map([...hits.keys()].map((id, at) => [id, at] as const));
+      shown = [...shown].sort((a, b) => (order.get(behaviorId(a.key)) ?? 0) - (order.get(behaviorId(b.key)) ?? 0));
+    }
     // The strip and the status and environment counts describe what the other filters leave.
-    const scope = model.tests.filter((test) => matchesQuery(model, test, { ...query, status: [], environment: [] }, inRun));
-    const byEnvironment = scope.filter((test) => matchesQuery(model, test, { environment: query.environment }));
-    const byStatus = scope.filter((test) => matchesQuery(model, test, { status: query.status }));
+    const scope = model.tests.filter((test) => matchesQuery(model, test, { ...query, status: [], environment: [] }, inRun) && passes(test, WITHOUT_STATUS_AND_ENVIRONMENT));
+    const byEnvironment = scope.filter((test) => matchesQuery(model, test, { environment: query.environment }) && passes(test, WITHOUT_STATUS));
+    const byStatus = scope.filter((test) => matchesQuery(model, test, { status: query.status }) && passes(test, WITHOUT_ENVIRONMENT));
+    const videoScope = model.tests.filter((test) => matchesQuery(model, test, query, inRun) && passes(test, WITHOUT_VIDEO));
     return {
       shown,
+      withVideo: videoScope.filter((test) => docs.get(test.key)?.facets?.video ?? testHasVideo(test)).length,
       scope,
       byEnvironment,
       byStatus,
+      hits: hits as ReadonlyMap<string, Ranked> | null,
+      parsed: found.parsed,
+      semantic: found.status,
       runPending: !!search.inRun && run.isPending,
       runMissing: !!search.inRun && run.isSuccess && run.data === null
     };
-  }, [model, search, q, inRun, run.isPending, run.isSuccess, run.data]);
+  }, [model, search, found, docs, sort, inRun, run.isPending, run.isSuccess, run.data]);
+  return listing;
 }
 /** The project home: the published spec kinds, the insight strip, the toolbar, the grouped list and the open test. */
 export function Explorer() {
@@ -252,7 +285,7 @@ export function Explorer() {
                   That run is not in the report any more.
                 </Alert>
               )}
-              <TestList tests={listing.shown} search={search} total={model.tests.length} />
+              <TestList tests={listing.shown} search={search} total={model.tests.length} hits={listing.hits} sort={search.sort ?? (listing.hits ? 'relevance' : 'spec')} />
             </>
           ))}
       </Box>
@@ -496,6 +529,9 @@ function Toolbar({
   onSearch: (value: string) => void;
 }) {
   const go = useExplorerNavigate();
+  // Best match is the order of a search with words; without words the list is in spec order.
+  const defaultSort: ExplorerSort = listing.hits ? 'relevance' : 'spec';
+  const sort: ExplorerSort = search.sort ?? defaultSort;
   const [draft, setDraft] = useState(search.q ?? '');
   // The address may change from elsewhere (a link, the index, back): follow it.
   useEffect(() => setDraft((current) => (current.trim() === (search.q ?? '').trim() ? current : (search.q ?? ''))), [search.q]);
@@ -527,7 +563,7 @@ function Toolbar({
           miw={{ base: '100%', sm: '15rem' }}
           type="search"
           aria-label="Search tests"
-          placeholder="Search titles, specs, domains, tags, environments…"
+          placeholder='Search titles, specs, tags… or filter: status:failed has:video "exact phrase"'
           value={draft}
           onChange={(event) => {
             setDraft(event.target.value);
@@ -556,12 +592,12 @@ function Toolbar({
           </Text>
           <NativeSelect
             aria-label="Sort"
-            value={search.sort ?? 'spec'}
-            onChange={(event) => go({ sort: event.target.value === 'spec' ? undefined : (event.target.value as TestSort) })}
+            value={sort}
+            onChange={(event) => go({ sort: event.target.value === defaultSort ? undefined : (event.target.value as ExplorerSort) })}
           >
-            {TEST_SORTS.map((sort) => (
-              <option key={sort} value={sort}>
-                {SORT_LABEL[sort]}
+            {EXPLORER_SORTS.filter((option) => option !== 'relevance' || listing.hits !== null || sort === 'relevance').map((option) => (
+              <option key={option} value={option}>
+                {SORT_LABEL[option]}
               </option>
             ))}
           </NativeSelect>
@@ -608,6 +644,26 @@ function Toolbar({
             ))}
           </Flex>
         )}
+        <Button
+          type="button"
+          aria-pressed={search.video === true || listing.parsed.filters.video}
+          aria-label={`Has video: ${plural(listing.withVideo, 'test', 'tests')}`}
+          onClick={() => {
+            if (listing.parsed.filters.video) {
+              const token = listing.parsed.tokens.find((item) => item.key === 'video')!;
+              const next = withoutToken(draft, token);
+              setDraft(next);
+              onSearch(next);
+            } else go({ video: search.video ? undefined : true });
+          }}
+          variant={search.video === true || listing.parsed.filters.video ? 'light' : 'subtle'}
+          leftSection={<IconVideo size={16} aria-hidden="true" />}
+        >
+          Has video{' '}
+          <Text span inherit>
+            {listing.withVideo.toLocaleString()}
+          </Text>
+        </Button>
         {model.facets.producers.length > 1 && (
           <Box component="label">
             <VisuallyHidden>Producer</VisuallyHidden>
@@ -683,6 +739,14 @@ function Toolbar({
             ? plural(model.tests.length, 'test', 'tests')
             : `${listing.shown.length.toLocaleString()} of ${plural(model.tests.length, 'test', 'tests')}`}
         </Text>
+        <TypedFilters
+          parsed={listing.parsed}
+          query={draft}
+          onChange={(next) => {
+            setDraft(next);
+            onSearch(next);
+          }}
+        />
         {chips.map((chip) => (
           <Button key={chip.label} type="button" onClick={() => go(chip.clear)} aria-label={`Remove ${chip.label}`} variant="light">
             {chip.label}{' '}
@@ -707,7 +771,8 @@ function Toolbar({
                 scope: undefined,
                 artifactTag: undefined,
                 inherited: undefined,
-                inRun: undefined
+                inRun: undefined,
+                video: undefined
               });
             }}
             variant="subtle"
@@ -716,12 +781,13 @@ function Toolbar({
           </Button>
         )}
       </Flex>
+      <SearchNotes issues={listing.parsed.issues} semantic={listing.semantic} />
     </Box>
   );
 }
-function TestList({ tests, search, total }: { tests: readonly TestSummary[]; search: ExplorerSearch; total: number }) {
+function TestList({ tests, search, total, hits, sort }: { tests: readonly TestSummary[]; search: ExplorerSearch; total: number; hits: ReadonlyMap<string, Ranked> | null; sort: ExplorerSort }) {
   const by = search.group ?? 'spec';
-  const groups = useMemo(() => groupTests(tests, by, (search.sort ?? 'spec') === 'spec'), [tests, by, search.sort]);
+  const groups = useMemo(() => groupTests(tests, by, sort === 'spec'), [tests, by, sort]);
   const [overrides, setOverrides] = useState<ReadonlyMap<string, boolean>>(new Map());
   const defaultOpen = groups.length <= OPEN_GROUPS || tests.length <= OPEN_TESTS;
   const isOpen = (group: TestGroupView) => by === 'none' || (overrides.get(`${by}|${group.key}`) ?? defaultOpen);
@@ -781,6 +847,7 @@ function TestList({ tests, search, total }: { tests: readonly TestSummary[]; sea
               by={by}
               open={isOpen(group)}
               selected={search.test}
+              hits={hits}
               onToggle={() => setOverrides(new Map(overrides).set(`${by}|${group.key}`, !isOpen(group)))}
             />
           </Stack>
@@ -794,12 +861,14 @@ function TestGroupSection({
   by,
   open,
   selected,
+  hits,
   onToggle
 }: {
   group: TestGroupView;
   by: TestGroup;
   open: boolean;
   selected: string | undefined;
+  hits: ReadonlyMap<string, Ranked> | null;
   onToggle: () => void;
 }) {
   const [shown, setShown] = useState(by === 'none' ? 100 : GROUP_ROWS);
@@ -807,7 +876,7 @@ function TestGroupSection({
   const rows = (
     <List spacing="xs" listStyleType="none">
       {group.tests.slice(0, shown).map((test) => (
-        <TestRow key={test.key} test={test} selected={selected === test.key} now={now} />
+        <TestRow key={test.key} test={test} selected={selected === test.key} now={now} hit={hits?.get(behaviorId(test.key))} />
       ))}
       {group.tests.length > shown && (
         <List.Item>
@@ -852,7 +921,8 @@ function TestGroupSection({
     </Box>
   );
 }
-function TestRow({ test, selected, now }: { test: TestSummary; selected: boolean; now: number }) {
+function TestRow({ test, selected, now, hit }: { test: TestSummary; selected: boolean; now: number; hit: Ranked | undefined }) {
+  const why = hit ? describeHit(hit) : '';
   const failure = test.status === 'failed' ? test.outcomes.find((outcome) => outcome.status === 'failed')?.detail.split('\n')[0] : '';
   return (
     <List.Item data-status={test.status}>
@@ -886,6 +956,16 @@ function TestRow({ test, selected, now }: { test: TestSummary; selected: boolean
                 {failure}
               </Text>
             )}
+            {why && (
+              <Text size="xs" c="dimmed" data-why>
+                {hit?.exact && (
+                  <Badge component="span" color="blue" mr="xs">
+                    Exact
+                  </Badge>
+                )}
+                {why}
+              </Text>
+            )}
           </Stack>
           <Group gap="md" visibleFrom="sm">
             <Text title="Average duration" size="xs" c="dimmed">