@crvouga/atlas 1.4.0 → 1.6.0

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

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

@@ -0,0 +1,247 @@
+/**
+ * @module Search query language
+ *
+ * One reading of a search box, shared by the finder, the test list, the runs list and the results of one run, so a
+ * sentence means the same thing wherever it is typed:
+ *
+ * - plain words are matched by meaning, spelling and word form (see `rank.ts`), and every distinctive word must be found;
+ * - `"a quoted phrase"` and identifiers that contain `/`, `_` or `.` (`checkout/save.feature`) are matched literally and
+ *   are reported as exact matches;
+ * - `field:value` narrows by structure instead of matching words: `status:failed`, `env:ios` (or `platform:`,
+ *   `environment:`, `device:`), `producer:`, `domain:`, `spec:`, `tag:`, `branch:` and `has:video`. A value with spaces is
+ *   quoted (`domain:"user account"`). Several values of one field (`status:failed,flaky`, or the field twice) match any of
+ *   them; different fields must all hold.
+ *
+ * Nothing here is ever dropped silently: a word it cannot use as a filter (`colour:red`, `status:great`, `has:smell`) is
+ * returned as an {@link SearchIssue} for the interface to show, and it filters nothing.
+ */
+
+/** The filters a search can carry. Each list matches any of its values; the lists combine with AND. */
+export type SearchFilters = {
+  readonly status: readonly string[];
+  readonly env: readonly string[];
+  readonly producer: readonly string[];
+  readonly domain: readonly string[];
+  readonly spec: readonly string[];
+  readonly tag: readonly string[];
+  readonly branch: readonly string[];
+  /** `has:video`: only what has a playable video recording. */
+  readonly video: boolean;
+};
+
+/** One of the filters a search can carry, by the name a person types before the colon. */
+export type FilterKey = Exclude<keyof SearchFilters, 'video'> | 'video';
+
+/** One filter as typed, for showing as a removable chip. */
+export type FilterToken = {
+  readonly key: FilterKey;
+  /** The value (`failed`), or `video` for `has:video`. */
+  readonly value: string;
+  /** The text to remove from the query to remove this filter. */
+  readonly text: string;
+};
+
+/** Something in the query that could not be used, and what to type instead. */
+export type SearchIssue = {
+  /** The text as typed. */
+  readonly token: string;
+  /** A sentence for the person, naming what is supported. */
+  readonly message: string;
+};
+
+/** A query read into what it asks for. */
+export type ParsedSearch = {
+  /** The query as typed. */
+  readonly raw: string;
+  /** The loose words to match by meaning and spelling (quoted phrases, identifiers and filters removed). */
+  readonly words: string;
+  /** Quoted phrases, each of which must appear literally. */
+  readonly phrases: readonly string[];
+  /** Identifier-like words (`lists/add`, `save_answer`, `a.feature`), each of which must appear literally. */
+  readonly identifiers: readonly string[];
+  readonly filters: SearchFilters;
+  /** The filters in the order typed. */
+  readonly tokens: readonly FilterToken[];
+  readonly issues: readonly SearchIssue[];
+};
+
+/** The statuses a `status:` filter accepts. */
+export const STATUS_VALUES = ['passed', 'failed', 'flaky', 'not-run', 'running'] as const;
+
+/** The `has:` values a search accepts. */
+export const HAS_VALUES = ['video'] as const;
+
+const FIELD_ALIASES: Readonly<Record<string, Exclude<FilterKey, 'video'>>> = {
+  status: 'status',
+  env: 'env',
+  environment: 'env',
+  platform: 'env',
+  device: 'env',
+  producer: 'producer',
+  domain: 'domain',
+  spec: 'spec',
+  tag: 'tag',
+  branch: 'branch'
+};
+
+/** The operator names a search understands, for guidance. */
+export const OPERATOR_NAMES: readonly string[] = [...Object.keys(FIELD_ALIASES), 'has'];
+
+/** A sentence that lists what can be typed, shown with every issue. */
+export const SYNTAX_HELP = 'Filters: status:failed, env:ios, producer:, domain:, spec:, tag:, branch: and has:video. Quote phrases: "saved answer".';
+
+/** A search with nothing in it. */
+export const NO_FILTERS: SearchFilters = { status: [], env: [], producer: [], domain: [], spec: [], tag: [], branch: [], video: false };
+
+const OPERATOR = /^([A-Za-z][A-Za-z-]*):(.*)$/;
+const IDENTIFIER = /[A-Za-z0-9][/_.][A-Za-z0-9]/;
+
+/** The pieces of a query: quoted strings (optionally after `name:`) and runs of non-space characters. */
+function pieces(query: string): { readonly text: string; readonly quoted: boolean; readonly name?: string }[] {
+  const out: { text: string; quoted: boolean; name?: string }[] = [];
+  const pattern = /(?:([A-Za-z][A-Za-z-]*):)?"([^"]*)"|(\S+)/g;
+  for (const match of query.matchAll(pattern)) {
+    if (match[3] !== undefined) out.push({ text: match[3], quoted: false });
+    else out.push({ text: match[2] ?? '', quoted: true, ...(match[1] ? { name: match[1] } : {}) });
+  }
+  return out;
+}
+
+/** Reads a query: see the module comment. Never throws; whatever it cannot use is in `issues`. */
+export function parseSearch(query: string): ParsedSearch {
+  const words: string[] = [];
+  const phrases: string[] = [];
+  const identifiers: string[] = [];
+  const issues: SearchIssue[] = [];
+  const tokens: FilterToken[] = [];
+  const lists: Record<Exclude<FilterKey, 'video'>, string[]> = { status: [], env: [], producer: [], domain: [], spec: [], tag: [], branch: [] };
+  let video = false;
+  const issue = (token: string, message: string) => issues.push({ token, message: `${message} ${SYNTAX_HELP}` });
+
+  for (const piece of pieces(query)) {
+    const operator = piece.name !== undefined ? ([piece.name, piece.text] as const) : !piece.quoted ? OPERATOR.exec(piece.text)?.slice(1, 3) : undefined;
+    if (piece.quoted && piece.name === undefined) {
+      const phrase = piece.text.trim().toLowerCase();
+      if (phrase) phrases.push(phrase);
+      else issue('""', 'is an empty phrase, which matches nothing.');
+      continue;
+    }
+    if (operator) {
+      const name = operator[0].toLowerCase();
+      const original = piece.quoted ? `${operator[0]}:"${operator[1]}"` : piece.text;
+      const rawValues = piece.quoted ? [operator[1]!] : operator[1]!.split(',');
+      const values = rawValues.map((value) => value.trim().replace(/^"|"$/g, '')).filter(Boolean);
+      if (name === 'has') {
+        if (!values.length) issue(original, 'needs a value after the colon (has:video).');
+        for (const value of values) {
+          if (value.toLowerCase() === 'video') {
+            video = true;
+            tokens.push({ key: 'video', value: 'video', text: original });
+          } else issue(original, 'is not supported (only has:video).');
+        }
+        continue;
+      }
+      const key = FIELD_ALIASES[name];
+      if (!key && !piece.quoted && !values.length) {
+        // Prose such as "Done:" is not a filter.
+        words.push(piece.text.replace(/:$/, ''));
+        continue;
+      }
+      if (!key) {
+        issue(original, 'is not a filter.');
+        continue;
+      }
+      if (!values.length) {
+        issue(original, 'needs a value after the colon.');
+        continue;
+      }
+      for (const raw of values) {
+        const value = key === 'tag' ? raw.replace(/^#/, '').toLowerCase() : raw.toLowerCase();
+        if (key === 'status' && !(STATUS_VALUES as readonly string[]).includes(value)) {
+          issue(original, `is not a status (use ${STATUS_VALUES.join(', ')}).`);
+          continue;
+        }
+        if (!lists[key].includes(value)) lists[key].push(value);
+        tokens.push({ key, value, text: original });
+      }
+      continue;
+    }
+    if (piece.text.startsWith('"')) {
+      issue(piece.text, 'has a quote that is never closed, so its words are matched as ordinary words.');
+      words.push(piece.text.replace(/"/g, ' '));
+      continue;
+    }
+    const bare = piece.text.replace(/^[("']+|[)"',;!?]+$/g, '').replace(/\.+$/, '');
+    if (IDENTIFIER.test(bare)) identifiers.push(bare.toLowerCase());
+    else words.push(piece.text);
+  }
+  return {
+    raw: query,
+    words: words.join(' ').trim(),
+    phrases,
+    identifiers,
+    filters: { ...lists, video },
+    tokens,
+    issues
+  };
+}
+
+/** True when the query narrows by structure (any filter, phrase or identifier) rather than only by loose words. */
+export function isStructured(parsed: ParsedSearch): boolean {
+  return parsed.tokens.length > 0 || parsed.phrases.length > 0 || parsed.identifiers.length > 0;
+}
+
+/** True when the query has nothing to match at all (no words, phrases, identifiers or filters). */
+export function isBlank(parsed: ParsedSearch): boolean {
+  return parsed.words.length === 0 && !isStructured(parsed);
+}
+
+/** The query with one filter's text removed, other text left as typed. */
+export function withoutToken(query: string, token: FilterToken): string {
+  const at = query.indexOf(token.text);
+  if (at < 0) return query;
+  return `${query.slice(0, at)}${query.slice(at + token.text.length)}`.replace(/\s{2,}/g, ' ').trim();
+}
+
+/**
+ * What a document says about itself, to be filtered by structure. Lowercased on use. A document without facets (a
+ * flow, a spec) can satisfy no filter.
+ */
+export type DocFacets = {
+  readonly status: readonly string[];
+  readonly env: readonly string[];
+  readonly producer: readonly string[];
+  readonly domain: readonly string[];
+  readonly spec: readonly string[];
+  readonly tag: readonly string[];
+  readonly branch: readonly string[];
+  readonly video: boolean;
+};
+
+/** The filter groups a count can leave out (status and environment buttons count what the other filters leave). */
+export type FilterOmit = ReadonlySet<FilterKey>;
+
+/**
+ * Whether facets satisfy the filters: every filter that is set must match at least one of the document's values.
+ * `omit` skips some filters (to count what a button would add).
+ */
+export function passesFilters(facets: DocFacets | undefined, filters: SearchFilters, omit?: FilterOmit): boolean {
+  const wanted = (key: FilterKey) => !omit?.has(key);
+  const lists: (Exclude<FilterKey, 'video'>)[] = ['status', 'env', 'producer', 'domain', 'spec', 'tag', 'branch'];
+  const active = lists.filter((key) => filters[key].length > 0 && wanted(key));
+  const needsVideo = filters.video && wanted('video');
+  if (!active.length && !needsVideo) return true;
+  if (!facets) return false;
+  if (needsVideo && !facets.video) return false;
+  for (const key of active) {
+    const have = facets[key].map((value) => value.toLowerCase());
+    const ok = filters[key].some((value) => (key === 'spec' ? have.some((path) => path === value || path.endsWith(`/${value}`) || path.includes(value)) : have.includes(value)));
+    if (!ok) return false;
+  }
+  return true;
+}
+
+/** True when a search carries a filter (as opposed to words), counting only those not in `omit`. */
+export function hasFilters(filters: SearchFilters): boolean {
+  return filters.video || filters.status.length + filters.env.length + filters.producer.length + filters.domain.length + filters.spec.length + filters.tag.length + filters.branch.length > 0;
+}