@crvouga/atlas 1.1.0 → 1.2.0

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

@@ -0,0 +1,279 @@
+/**
+ * @module Run and artifact filters
+ *
+ * The filter bar of the Runs and Artifacts tabs: words, artifact tag, media type, label, environment, branch, outcome,
+ * feature domain and a time range, each offering the values the report has with counts in the scope of the list. What is
+ * chosen shows as removable chips and is the address, so copying it or reloading restores the same view; named views keep
+ * a query to open again. Choices combine with AND across the controls and OR within one.
+ */
+import { IconBookmark, IconLink, IconTrash, IconX } from '@tabler/icons-react';
+import { Anchor, Badge, Box, Button, Checkbox, CopyButton, Flex, Group, MultiSelect, Popover, SimpleGrid, Stack, Text, TextInput } from '@mantine/core';
+import type { QueryFacets, QueryFacetValue } from '@crvouga/atlas/reports/artifact-query';
+import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
+import { Link } from '@tanstack/react-router';
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
+
+import { currentProject } from '../runtime';
+import { patched, useExplorerNavigate } from './navigate';
+import { filtered, joined, NO_FILTERS, toggled, values, type ExplorerSearch } from './search';
+import { filtersOf, isView, readViews, writeViews, type SavedView } from './views';
+
+type Param = 'artifactTag' | 'type' | 'label' | 'env' | 'branch' | 'outcome' | 'domain' | 'producer';
+
+const NOUN: Record<Param, string> = {
+  artifactTag: 'Tag',
+  type: 'Type',
+  label: 'Label',
+  env: 'Environment',
+  branch: 'Branch',
+  outcome: 'Outcome',
+  domain: 'Domain',
+  producer: 'Producer'
+};
+
+/** How a chosen value reads: tags with their hash, environments by name. */
+function shown(param: Param, value: string): string {
+  if (param === 'artifactTag') return `#${value}`;
+  if (param === 'env') return environmentLabel(value);
+  if (param === 'domain' && value === '(no spec)') return 'No spec';
+  return value;
+}
+
+function Facet({ param, facets, search }: { param: Param; facets: readonly QueryFacetValue[]; search: ExplorerSearch }) {
+  const go = useExplorerNavigate();
+  const chosen = values(search[param]);
+  const data = useMemo(() => facets.map((facet) => ({ value: facet.value, label: `${shown(param, facet.value)} (${facet.count})` })), [facets, param]);
+  if (!data.length && !chosen.length) return null;
+  return (
+    <MultiSelect
+      label={NOUN[param]}
+      data={data}
+      value={chosen}
+      searchable
+      clearable
+      placeholder={chosen.length ? undefined : `Any ${NOUN[param].toLowerCase()}`}
+      nothingFoundMessage="Nothing found"
+      onChange={(next) => go({ [param]: joined(next) } as never)}
+    />
+  );
+}
+
+/** Saved views: name the current filters, open one again, delete it. They are live queries, said so beside the list. */
+function Views({
+  search,
+  tab,
+  views,
+  onChange,
+  failed
+}: {
+  search: ExplorerSearch;
+  tab: 'runs' | 'artifacts';
+  views: readonly SavedView[];
+  onChange: (next: SavedView[]) => void;
+  failed: boolean;
+}) {
+  const project = currentProject() ?? '';
+  const [name, setName] = useState('');
+  const mine = views.filter((view) => view.project === project && view.tab === tab);
+  const keep = onChange;
+  const narrowed = filtered(search);
+  return (
+    <Popover width={360} position="bottom-start" withArrow shadow="md" trapFocus>
+      <Popover.Target>
+        <Button type="button" variant="default" leftSection={<IconBookmark size={16} aria-hidden="true" />}>
+          Views{mine.length ? ` (${mine.length})` : ''}
+        </Button>
+      </Popover.Target>
+      <Popover.Dropdown>
+        <Stack gap="sm" aria-label="Saved views">
+          <Text size="sm" c="dimmed">
+            A saved view is a live query: opening it asks again, so it shows what matches the newest report now. It is not a snapshot of the results you see today.
+          </Text>
+          {mine.length === 0 && (
+            <Text size="sm" c="dimmed">
+              No saved views for this tab yet.
+            </Text>
+          )}
+          {mine.map((view) => (
+            <Group key={view.id} justify="space-between" wrap="nowrap">
+              <Anchor
+                aria-label={`Open view ${view.name}`}
+                renderRoot={(props) => (
+                  <Link
+                    {...props}
+                    to="/"
+                    search={patched({ ...NO_FILTERS, ...view.filters, tab: view.tab, openRun: undefined, test: undefined, layer: undefined } as never)}
+                    resetScroll={false}
+                    activeOptions={{ exact: true }}
+                  />
+                )}
+              >
+                {view.name}
+              </Anchor>
+              <Badge variant="outline" color="gray">
+                Live query
+              </Badge>
+              <Button
+                type="button"
+                variant="subtle"
+                color="red"
+                aria-label={`Delete view ${view.name}`}
+                onClick={() => keep(views.filter((entry) => entry.id !== view.id))}
+              >
+                <IconTrash size={16} aria-hidden="true" />
+              </Button>
+            </Group>
+          ))}
+          <TextInput label="View name" value={name} onChange={(event) => setName(event.target.value)} placeholder="Demo review" />
+          <Button
+            type="button"
+            disabled={!name.trim() || !narrowed}
+            onClick={() => {
+              const saved: SavedView = {
+                id: `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+                name: name.trim(),
+                tab,
+                project,
+                filters: filtersOf(search),
+                savedAtMs: Date.now()
+              };
+              keep([...views.filter((view) => !(view.project === project && view.tab === tab && view.name === saved.name)), saved]);
+              setName('');
+            }}
+          >
+            Save the current filters
+          </Button>
+          {!narrowed && (
+            <Text size="sm" c="dimmed">
+              Choose at least one filter to save a view.
+            </Text>
+          )}
+          {failed && (
+            <Text size="sm" c="red.7" role="alert">
+              This browser would not keep the view, so it will be gone when the page closes.
+            </Text>
+          )}
+        </Stack>
+      </Popover.Dropdown>
+    </Popover>
+  );
+}
+
+/**
+ * The filter bar for a tab. `facets` are the values on offer with their counts; `extra` is shown beside the controls (the
+ * Runs tab's Has video button); `domains` offers the feature domain (artifacts only).
+ */
+export function FilterBar({
+  facets,
+  search,
+  tab,
+  extra
+}: {
+  facets: QueryFacets;
+  search: ExplorerSearch;
+  tab: 'runs' | 'artifacts';
+  extra?: ReactNode;
+}) {
+  const go = useExplorerNavigate();
+  const [draft, setDraft] = useState(search.q ?? '');
+  // The address may change from elsewhere (a link, a saved view, back): follow it.
+  useEffect(() => setDraft((current) => (current.trim() === (search.q ?? '').trim() ? current : (search.q ?? ''))), [search.q]);
+  const params: Param[] = ['artifactTag', 'type', 'label', 'env', 'branch', 'outcome', ...(tab === 'artifacts' ? (['domain'] as const) : []), 'producer'];
+  const chips = [
+    ...params.flatMap((param) =>
+      values(search[param]).map((value) => ({ label: `${NOUN[param]}: ${shown(param, value)}`, clear: { [param]: toggled(search[param], value) } as never }))
+    ),
+    ...(search.since ? [{ label: `From ${search.since}`, clear: { since: undefined } as never }] : []),
+    ...(search.until ? [{ label: `Until ${search.until}`, clear: { until: undefined } as never }] : []),
+    ...(search.q ? [{ label: `Words: ${search.q}`, clear: { q: undefined } as never }] : []),
+    ...(search.video ? [{ label: 'Has video', clear: { video: undefined } as never }] : [])
+  ];
+  const [views, setViews] = useState<SavedView[]>(() => readViews());
+  const [failed, setFailed] = useState(false);
+  const saved = views.find((view) => view.project === (currentProject() ?? '') && isView(view, search));
+  return (
+    <Box aria-label="Filters" component="section" mb="md">
+      <Stack gap="sm">
+        <Flex gap="sm" align="flex-end" wrap="wrap">
+          <TextInput
+            flex={1}
+            miw={{ base: '100%', sm: '15rem' }}
+            type="search"
+            aria-label={`Search ${tab}`}
+            placeholder={tab === 'runs' ? 'Search runs by title, branch, commit, tag…' : 'Search by test, spec, tag, label…'}
+            value={draft}
+            onChange={(event) => {
+              setDraft(event.target.value);
+              go({ q: event.target.value.trim() || undefined }, { replace: true });
+            }}
+          />
+          <Views
+            search={search}
+            tab={tab}
+            views={views}
+            failed={failed}
+            onChange={(next) => {
+              setViews(next);
+              setFailed(!writeViews(next));
+            }}
+          />
+          <CopyButton value={typeof window === 'undefined' ? '' : window.location.href}>
+            {({ copied, copy }) => (
+              <Button type="button" variant="default" onClick={copy} leftSection={<IconLink size={16} aria-hidden="true" />}>
+                {copied ? 'Link copied' : 'Copy link'}
+              </Button>
+            )}
+          </CopyButton>
+          {extra}
+        </Flex>
+        <SimpleGrid cols={{ base: 1, sm: 2, md: 4 }}>
+          <Facet param="artifactTag" facets={facets.artifactTags} search={search} />
+          <Facet param="type" facets={facets.types} search={search} />
+          <Facet param="label" facets={facets.labels} search={search} />
+          <Facet param="env" facets={facets.environments} search={search} />
+          <Facet param="branch" facets={facets.branches} search={search} />
+          <Facet param="outcome" facets={facets.outcomes} search={search} />
+          {tab === 'artifacts' && facets.domains && <Facet param="domain" facets={facets.domains} search={search} />}
+          {facets.producers.length > 1 && <Facet param="producer" facets={facets.producers} search={search} />}
+          <TextInput type="date" label="From" value={search.since ?? ''} onChange={(event) => go({ since: event.target.value || undefined })} />
+          <TextInput type="date" label="Until" value={search.until ?? ''} onChange={(event) => go({ until: event.target.value || undefined })} />
+        </SimpleGrid>
+        {values(search.artifactTag).length > 0 && (
+          <Checkbox
+            label="Also match tags inherited from the check and run"
+            description="Off: only tags written on the recording itself."
+            checked={search.inherited === true}
+            onChange={(event) => go({ inherited: event.currentTarget.checked ? true : undefined })}
+          />
+        )}
+        {(chips.length > 0 || saved) && (
+          <Flex gap="xs" align="center" wrap="wrap" aria-label="Active filters">
+            {saved && (
+              <Badge variant="light" aria-label={`Live query ${saved.name}`}>
+                Live query: {saved.name}
+              </Badge>
+            )}
+            {chips.map((chip) => (
+              <Button key={chip.label} type="button" onClick={() => go(chip.clear)} aria-label={`Remove ${chip.label}`} variant="light">
+                {chip.label}{' '}
+                <Text aria-hidden="true" span inherit>
+                  <IconX size={16} aria-hidden="true" />
+                </Text>
+              </Button>
+            ))}
+            {filtered(search) && (
+              <Button type="button" variant="subtle" onClick={() => go(NO_FILTERS)}>
+                Clear filters
+              </Button>
+            )}
+            {saved && (
+              <Text size="sm" c="dimmed">
+                A live query, not a snapshot: it follows the newest report.
+              </Text>
+            )}
+          </Flex>
+        )}
+      </Stack>
+    </Box>
+  );
+}

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