@crvouga/atlas 1.0.0 → 1.2.0

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

@@ -3,8 +3,13 @@
  *
  * Everything the test explorer shows is in the address of the `/` route, so a link reproduces the view: the open test,
  * the words searched, the filters, the grouping, the order, the Runs tab with the run opened in it, and the exact layer a test's detail is pinned to. Filters that
- * take several values are comma-separated (`status=failed,flaky`). Anything unreadable is dropped, never an error.
+ * take several values are comma-separated (`status=failed,flaky`); a comma or backslash inside a value is written `\,`
+ * or `\\`, and the router encodes `#` and spaces. Anything unreadable is dropped, never an error.
+ *
+ * The Runs and Artifacts tabs share the tests' `q`, `env`, `producer`, `domain` and `spec` and add `artifactTag`,
+ * `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 { z } from 'zod/v4';
 
@@ -30,11 +35,27 @@ export const ExplorerSearchFields = {
   domain: text,
   spec: text,
   tag: text,
+  /** Artifact tags (`demo`, shown `#demo`): tests with an attachment carrying one; runs and artifacts likewise. */
+  artifactTag: text,
+  /** With `artifactTag`: also the tags attachments inherit from their check and run. */
+  inherited: z.preprocess((value) => (value === 'true' ? true : value), z.literal(true)).optional().catch(undefined),
+  /** Media types of attachments (`video`, `image`…): runs and artifacts. */
+  type: text,
+  /** `key=value` labels: runs and artifacts. */
+  label: text,
+  /** Branches: runs and artifacts. */
+  branch: text,
+  /** Outcomes of a run or recorded result (`passed`, `failed`…). */
+  outcome: text,
+  /** Only records from this day (`YYYY-MM-DD`, the viewer's local time). */
+  since: text,
+  /** Only records until the end of this day (`YYYY-MM-DD`, local time). */
+  until: text,
   /** 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),
-  tab: z.enum(['runs']).optional().catch(undefined),
+  tab: z.enum(['runs', 'artifacts']).optional().catch(undefined),
   /** The run opened in the Runs tab. */
   openRun: text,
   /** Pins the open test's detail to one exact layer (a run's record of it), instead of the latest combined evidence. */
@@ -53,10 +74,18 @@ export type ExplorerSearch = {
   readonly domain?: string;
   readonly spec?: string;
   readonly tag?: string;
+  readonly artifactTag?: string;
+  readonly inherited?: true;
+  readonly type?: string;
+  readonly label?: string;
+  readonly branch?: string;
+  readonly outcome?: string;
+  readonly since?: string;
+  readonly until?: string;
   readonly inRun?: string;
   readonly group?: TestGroup;
   readonly sort?: TestSort;
-  readonly tab?: 'runs';
+  readonly tab?: 'runs' | 'artifacts';
   readonly openRun?: string;
   readonly layer?: string;
   readonly video?: true;
@@ -64,12 +93,12 @@ export type ExplorerSearch = {
 
 /** The values of a comma-separated filter, empty when it is not set. */
 export function values(value: string | undefined): string[] {
-  return value ? value.split(',').map((item) => item.trim()).filter(Boolean) : [];
+  return value ? splitList(value) : [];
 }
 
 /** A list of values as one comma-separated parameter, or undefined (left out of the address) when empty. */
 export function joined(list: readonly string[]): string | undefined {
-  return list.length ? list.join(',') : undefined;
+  return joinList(list);
 }
 
 /** Adds a value to a comma-separated filter, or removes it when it is there. */
@@ -88,6 +117,8 @@ export function queryOf(search: ExplorerSearch): TestQuery {
     domain: values(search.domain),
     spec: values(search.spec),
     tag: values(search.tag),
+    artifactTag: values(search.artifactTag),
+    ...(search.inherited ? { inherited: true } : {}),
     sort: search.sort ?? 'spec'
   };
 }
@@ -99,5 +130,49 @@ 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.inRun);
+  return !!(search.q || search.status || search.env || search.producer || search.domain || search.spec || search.tag || search.artifactTag || search.inRun);
+}
+
+/** The filters of the Runs and Artifacts tabs, in the address. */
+export const FILTER_FIELDS = ['q', 'artifactTag', 'inherited', 'type', 'label', 'env', 'producer', 'branch', 'outcome', 'domain', 'spec', 'since', 'until', 'video'] as const;
+
+/** A patch that removes every filter of the Runs and Artifacts tabs. */
+export const NO_FILTERS = Object.fromEntries(FILTER_FIELDS.map((field) => [field, undefined])) as { [K in (typeof FILTER_FIELDS)[number]]?: undefined };
+
+/** True when an address narrows the Runs and Artifacts tabs. */
+export function filtered(search: ExplorerSearch): boolean {
+  return FILTER_FIELDS.some((field) => field !== 'inherited' && search[field] !== undefined);
+}
+
+/** Midnight at the start (or the last millisecond) of a `YYYY-MM-DD` day in the viewer's local time, or undefined. */
+function dayMs(day: string | undefined, end: boolean): number | undefined {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(day ?? '');
+  if (!match) return undefined;
+  const [year, month, date] = [Number(match[1]), Number(match[2]) - 1, Number(match[3])];
+  const value = new Date(year, month, date + (end ? 1 : 0)).getTime() - (end ? 1 : 0);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+/** The query the Runs and Artifacts tabs ask for: the address's filters in the shape the report API and `matchesFilter` read. */
+export function filterOf(search: ExplorerSearch): ArtifactFilter {
+  const list = (value: string | undefined) => (values(value).length ? values(value) : undefined);
+  const since = dayMs(search.since, false);
+  const until = dayMs(search.until, true);
+  const parts = {
+    q: search.q,
+    artifactTag: list(search.artifactTag),
+    inherited: search.inherited,
+    type: list(search.type),
+    label: list(search.label),
+    environment: list(search.env),
+    producer: list(search.producer),
+    branch: list(search.branch),
+    outcome: list(search.outcome),
+    domain: list(search.domain),
+    spec: list(search.spec),
+    since,
+    until,
+    video: search.video
+  };
+  return Object.fromEntries(Object.entries(parts).filter(([, value]) => value !== undefined)) as ArtifactFilter;
 }

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

@@ -0,0 +1,75 @@
+/**
+ * @module Saved views
+ *
+ * A saved view is a name for a set of filters on the Runs or Artifacts tab of one project, kept in this browser. It is a
+ * live query, not a snapshot: opening it asks again and shows what matches the newest report, so its results change as
+ * runs arrive. (An immutable collection of reviewed results is a different thing, and is not what this stores.) Unreadable
+ * storage is treated as no saved views, never as an error.
+ */
+import { FILTER_FIELDS, type ExplorerSearch } from './search';
+
+/** The storage key of the saved views of this browser, all projects. */
+export const VIEWS_KEY = 'atlas.savedViews.v1';
+
+/** A saved live query. `filters` holds only the filter fields of the address, as the address writes them. */
+export type SavedView = {
+  readonly id: string;
+  readonly name: string;
+  /** The tab it opens on. */
+  readonly tab: 'runs' | 'artifacts';
+  /** The project it belongs to (the page's `?project=`), or an empty string. */
+  readonly project: string;
+  readonly filters: Readonly<Record<string, string | true>>;
+  readonly savedAtMs: number;
+};
+
+/** The filters of an address, ready to save: only the fields that narrow, with their values. */
+export function filtersOf(search: ExplorerSearch): Record<string, string | true> {
+  const filters: Record<string, string | true> = {};
+  for (const field of FILTER_FIELDS) {
+    const value = search[field];
+    if (value !== undefined) filters[field] = value;
+  }
+  return filters;
+}
+
+/** Whether an address is exactly a saved view's query on its tab (ignoring anything that is not a filter). */
+export function isView(view: SavedView, search: ExplorerSearch): boolean {
+  if ((search.tab ?? 'tests') !== view.tab) return false;
+  const now = filtersOf(search);
+  const keys = Object.keys(now);
+  return keys.length === Object.keys(view.filters).length && keys.every((key) => now[key] === view.filters[key]);
+}
+
+/** The saved views of this browser, oldest first; empty when none or when storage cannot be read. */
+export function readViews(storage: Pick<Storage, 'getItem'> | undefined = safeStorage()): SavedView[] {
+  try {
+    const parsed: unknown = JSON.parse(storage?.getItem(VIEWS_KEY) ?? '[]');
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (item): item is SavedView =>
+        !!item && typeof item.id === 'string' && typeof item.name === 'string' && (item.tab === 'runs' || item.tab === 'artifacts') && typeof item.project === 'string' && !!item.filters && typeof item.filters === 'object'
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Keeps the saved views. Returns false when storage refused them (full, private or unavailable), so the page can say so. */
+export function writeViews(views: readonly SavedView[], storage: Pick<Storage, 'setItem'> | undefined = safeStorage()): boolean {
+  try {
+    if (!storage) return false;
+    storage.setItem(VIEWS_KEY, JSON.stringify(views));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function safeStorage(): Storage | undefined {
+  try {
+    return typeof localStorage === 'undefined' ? undefined : localStorage;
+  } catch {
+    return undefined;
+  }
+}

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

@@ -6,6 +6,7 @@ import { useEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboa
 import { useAtlas } from '../app/atlas-context';
 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 { corpusFrom } from './corpus';
@@ -41,15 +42,29 @@ function isTypingTarget(target: EventTarget | null) {
   const tag = target.tagName;
   return target.isContentEditable || tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || tag === 'BUTTON' || tag === 'A';
 }
-function useSpecTexts(files: readonly string[]) {
+/**
+ * Reads the text of every spec for search, a few at a time, once `enabled`. Each file lands as it arrives, so a search
+ * can use what is read so far; `read` of `total` say how far it is, and `failed` how many could not be read at all.
+ */
+function useSpecTexts(files: readonly string[], enabled: boolean, open: boolean) {
   const adapter = useAdapter();
   const client = useQueryClient();
   const source = specKey(adapter);
   const cache = useRef(new Map<string, string>());
+  const unreadable = useRef(new Set<string>());
   const [texts, setTexts] = useState<ReadonlyMap<string, string>>(() => new Map());
   const [pending, setPending] = useState(false);
+  const [failedFiles, setFailedFiles] = useState<ReadonlySet<string>>(() => new Set());
   const key = files.join('\n');
+  // Opening the finder is another chance for the files that could not be read.
   useEffect(() => {
+    if (!open || unreadable.current.size === 0) return;
+    for (const file of unreadable.current) cache.current.delete(file);
+    unreadable.current.clear();
+    setFailedFiles(new Set());
+  }, [open]);
+  useEffect(() => {
+    if (!enabled) return;
     const wanted = key.length === 0 ? [] : key.split('\n');
     let cancelled = false;
     const missing = wanted.filter((file) => !cache.current.has(file));
@@ -65,13 +80,15 @@ function useSpecTexts(files: readonly string[]) {
         if (file === undefined || cancelled) return;
         let text = '';
         try {
-          text = await client.fetchQuery({ queryKey: keys.specFile(source, file), queryFn: () => adapter.specFile(file) });
+          text = await client.fetchQuery({ queryKey: keys.specFile(source, file), queryFn: () => adapter.specFile(file), retry: false });
         } catch {
           text = '';
+          unreadable.current.add(file);
         }
         if (cancelled) return;
         cache.current.set(file, text);
         setTexts(new Map(cache.current));
+        if (unreadable.current.has(file)) setFailedFiles(new Set(unreadable.current));
       }
     };
     void Promise.all([pull(), pull(), pull(), pull()]).then(() => {
@@ -80,8 +97,10 @@ function useSpecTexts(files: readonly string[]) {
     return () => {
       cancelled = true;
     };
-  }, [adapter, client, key, source]);
-  return { texts, pending };
+  }, [adapter, client, enabled, key, source]);
+  const read = useMemo(() => files.filter((file) => texts.has(file)).length, [files, texts]);
+  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>();
@@ -101,12 +120,25 @@ export function Finder() {
   const navigate = useNavigate();
   const routeSearch = useSearch({ strict: false });
   const readable = useMemo(() => evidence.files.filter((file) => kindOfFile(file)), [evidence.files]);
-  const { texts, pending } = useSpecTexts(readable);
+  // Reading every spec's text is for search, and a focused page needs its own spec first: start only once search is wanted.
+  const [wanted, setWanted] = useState(false);
+  useEffect(() => {
+    if (open) setWanted(true);
+  }, [open]);
+  const { texts, pending, total, read, failed } = useSpecTexts(readable, wanted, open);
   const docs = useMemo(
     () => corpusFrom(view, evidence.files, evidence.titleOf, evidence.view, texts),
     [view, evidence.files, evidence.titleOf, evidence.view, texts]
   );
   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`
+      : !evidence.ready && !evidence.unavailable
+        ? 'Recorded results are still loading'
+        : '';
   const [query, setQuery] = useState('');
   const store = finderStore;
   const spotlightState = useSpotlight(store);
@@ -254,7 +286,13 @@ export function Finder() {
         <Spotlight.ActionsList id="atlas-finder-actions" role="listbox" aria-label="Flows, specs and runs">
           {shown.length === 0 && (
             <Spotlight.Empty>
-              {query.trim() ? 'Nothing close to that.' : 'Type what someone does. For example, add a todo.'}
+              {!query.trim()
+                ? 'Type what someone does. For example, add a todo.'
+                : unindexed
+                  ? `No match yet. ${unindexed}, so this is not the final answer.`
+                  : failed > 0
+                    ? `Nothing close to that. ${plural(failed, 'spec', 'specs')} could not be read, so search may miss ${failed === 1 ? 'it' : 'them'}.`
+                    : 'Nothing close to that.'}
             </Spotlight.Empty>
           )}
           {FIND_GROUPS.map((group) => {
@@ -285,7 +323,7 @@ export function Finder() {
         <Spotlight.Footer>
           <Group gap="md" justify="space-between">
             <Text size="xs" c="dimmed">
-              {pending ? 'Reading specs…' : '↑↓ move'}
+              {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

package/packages/visualizer/src/spec-kind.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'bun:test';
 
-import { fileName, folderOf, kindOfFile, outlinePath, specFile, specKind } from './spec-kind';
+import { fileName, folderOf, kindOfFile, outlinePath, resolveSpec, similarSpecs, specFile, specKind } from './spec-kind';
 
 describe('spec kinds', () => {
   it('gives each notation its own tab and leaves statecharts and notes to the map', () => {
@@ -24,4 +24,17 @@ describe('spec kinds', () => {
     expect(folderOf('auth/sign-in.feature')).toBe('auth');
     expect(folderOf('atlas.yaml')).toBe('');
   });
+
+  it('reads a link to a spec by any form of its path and finds the listed spec it means', () => {
+    expect(specFile('./auth/sign-in.feature')).toBe('auth/sign-in.feature');
+    expect(specFile('/specs/auth\\sign-in.feature')).toBe('auth/sign-in.feature');
+    const listed = ['auth/sign-in.feature', 'billing/Pay.feature', 'billing/pay-later.feature', 'a/x.feature', 'b/x.feature'];
+    expect(resolveSpec('auth/sign-in.feature', listed)).toBe('auth/sign-in.feature');
+    expect(resolveSpec('Auth/Sign-In.feature', listed)).toBe('auth/sign-in.feature');
+    expect(resolveSpec('sign-in.feature', listed)).toBe('auth/sign-in.feature');
+    // Two candidates, or none, leave the link as written.
+    expect(resolveSpec('x.feature', listed)).toBe('x.feature');
+    expect(resolveSpec('nothing.feature', listed)).toBe('nothing.feature');
+    expect(similarSpecs('other/pay.feature', listed)).toEqual(['billing/Pay.feature']);
+  });
 });

package/packages/visualizer/src/spec-kind.ts

@@ -42,9 +42,35 @@ export function outlinePath(file: string) {
   return normal.startsWith('specs/') ? normal : `specs/${normal}`;
 }
 
-/** A file path relative to the specs folder, from either form. */
+/**
+ * A file path relative to the specs folder, from any form a link may name it by: with or without the `specs/` folder,
+ * with a leading `./` or `/`, with backslashes. Nothing here can leave the folder; `..` parts are kept for the reader to refuse.
+ */
 export function specFile(path: string) {
-  return path.replaceAll('\\', '/').replace(/^specs\//, '');
+  return path
+    .replaceAll('\\', '/')
+    .replace(/^(\.?\/)+/, '')
+    .replace(/^specs\//, '')
+    .replace(/\/{2,}/g, '/');
+}
+
+/**
+ * The listed spec a link means. An exact entry wins; otherwise the one listed spec that differs only in letter case, or that
+ * the link names by a trailing part of its path. More than one candidate, or none, leaves the link as written.
+ */
+export function resolveSpec(file: string, listed: readonly string[]): string {
+  if (listed.includes(file)) return file;
+  const lower = file.toLowerCase();
+  const sameCase = listed.filter((candidate) => candidate.toLowerCase() === lower);
+  if (sameCase.length === 1) return sameCase[0]!;
+  const tail = listed.filter((candidate) => candidate.toLowerCase().endsWith(`/${lower}`));
+  return tail.length === 1 ? tail[0]! : file;
+}
+
+/** The listed specs with the same file name as `file`, to offer when a link names one that is not there. */
+export function similarSpecs(file: string, listed: readonly string[], limit = 5): string[] {
+  const name = fileName(file).toLowerCase();
+  return listed.filter((candidate) => fileName(candidate).toLowerCase() === name).slice(0, limit);
 }
 
 export function fileName(path: string) {