@crvouga/atlas 1.15.0 → 1.17.0

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

@@ -0,0 +1,402 @@
+/**
+ * @module Catalog health view
+ *
+ * The Catalog health tab: why the Specs and the Tests of a report disagree, and what a producer or an operator can change.
+ * It shows the denominators apart (spec files, defined specs, specs with an executed test, tests, outlines, examples and
+ * per-environment observations), the steps from the Specs count to the Tests count, the domains in use, specs seen under
+ * more than one path, and every finding with the paths it affects. Two paths are one logical spec only when a root mapping
+ * relates them: the server's configured mappings are shown as such, and further `from>to` mappings can be tried here
+ * (they are the address's `root`, so a link reproduces the figures). Ambiguous paths are never merged by similar title.
+ * The tab only reads: it never changes a status, a count of passed checks or a domain.
+ */
+import { parseRootMappings, type CatalogHealth, type HealthFinding, type RootMapping } from '@crvouga/atlas/reports/catalog-health';
+import { Accordion, ActionIcon, Alert, Badge, Box, Button, Code, Group, List, Paper, SimpleGrid, Stack, Table, Text, TextInput, Title, Tooltip } from '@mantine/core';
+import { IconTrash } from '@tabler/icons-react';
+import { useMemo, useState } from 'react';
+
+import { plural } from '../evidence/format';
+import { useCatalogHealth } from './catalog';
+import { useExplorerNavigate, useExplorerSearch } from './navigate';
+
+const label = (root: { readonly from: string; readonly to: string }) => `${root.from}>${root.to}`;
+
+function Figure({ name, value, hint }: { name: string; value: number; hint: string }) {
+  return (
+    <Paper withBorder p="sm" title={hint}>
+      <Text size="xs" c="dimmed" component="div">
+        {name}
+      </Text>
+      <Text fw={700} size="xl" component="div" data-health-figure={name}>
+        {value}
+      </Text>
+    </Paper>
+  );
+}
+
+function Counts({ health }: { health: CatalogHealth }) {
+  const { specs, tests, scenarios } = health.counts;
+  return (
+    <Stack gap="md">
+      <Box component="section" aria-label="Spec counts">
+        <Title order={4} mb="xs">
+          Specs
+        </Title>
+        <SimpleGrid cols={{ base: 2, sm: 3, md: 5 }}>
+          <Figure name="Spec files" value={specs.files} hint="Files the report is laid over, before any root mapping. This is the number the Specs view shows." />
+          <Figure name="Defined specs" value={specs.defined} hint="Spec files, with those joined by a declared root mapping counted once." />
+          <Figure name="Specs with tests" value={specs.withTests} hint="Specs, defined or not, with at least one test. This is what the Tests view groups by." />
+          <Figure name="Specs executed" value={specs.executed} hint="Defined specs with a test that passed or failed: the denominator of execution coverage." />
+          <Figure name="Defined, not executed" value={specs.withoutExecution} hint="Defined specs with no passed or failed test: the coverage gaps. They add to no passed count." />
+        </SimpleGrid>
+      </Box>
+      <Box component="section" aria-label="Test counts">
+        <Title order={4} mb="xs">
+          Tests
+        </Title>
+        <SimpleGrid cols={{ base: 2, sm: 3, md: 5 }}>
+          <Figure name="Tests" value={tests.total} hint="Check identities: a spec path and an id, however many environments ran them." />
+          <Figure name="Tests passed" value={tests.passed} hint="Tests whose current status is passed." />
+          <Figure name="Tests with a spec" value={tests.withSpec} hint="Tests that name the spec they belong to." />
+          <Figure name="Tests without a spec" value={tests.withoutSpec} hint="Tests that name no spec; they are in no spec or domain group." />
+          <Figure name="Only in history" value={tests.historicalOnly} hint="Tests the history holds but the report has no current result for (removed, renamed or not re-run)." />
+        </SimpleGrid>
+      </Box>
+      <Box component="section" aria-label="Scenario counts">
+        <Title order={4} mb="xs">
+          Outlines, examples and observations
+        </Title>
+        <SimpleGrid cols={{ base: 2, sm: 3, md: 5 }}>
+          <Figure name="Outlines" value={scenarios.outlines} hint="Tests sharing the label outline count once; a test without it is its own outline." />
+          <Figure name="Examples" value={scenarios.examples} hint="Concrete examples: tests, however many environments ran them." />
+          <Figure name="Observations" value={scenarios.observations} hint="Current results per producer, environment and parameter set." />
+          <Figure name="Observations executed" value={scenarios.executedObservations} hint="Observations that passed or failed." />
+          <Figure name="Observations passed" value={scenarios.passedObservations} hint="Observations that passed." />
+        </SimpleGrid>
+      </Box>
+    </Stack>
+  );
+}
+
+function Reconciliation({ health }: { health: CatalogHealth }) {
+  const { reconciliation } = health;
+  let total = reconciliation.specs;
+  const rows = reconciliation.steps.map((step) => {
+    total += step.delta;
+    return (
+      <Table.Tr key={step.code}>
+        <Table.Td>{step.label}</Table.Td>
+        <Table.Td ta="right">{step.delta > 0 ? `+${step.delta}` : step.delta}</Table.Td>
+        <Table.Td ta="right">{total}</Table.Td>
+      </Table.Tr>
+    );
+  });
+  return (
+    <Box component="section" aria-label="Why Specs and Tests differ">
+      <Title order={3} mb="xs">
+        Why Specs and Tests differ
+      </Title>
+      <Table.ScrollContainer minWidth={420}>
+        <Table data-health-reconciliation>
+          <Table.Thead>
+            <Table.Tr>
+              <Table.Th scope="col">Step</Table.Th>
+              <Table.Th scope="col" ta="right">
+                Change
+              </Table.Th>
+              <Table.Th scope="col" ta="right">
+                Total
+              </Table.Th>
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            <Table.Tr>
+              <Table.Td>Spec files the Specs view lists</Table.Td>
+              <Table.Td />
+              <Table.Td ta="right">{reconciliation.specs}</Table.Td>
+            </Table.Tr>
+            {rows}
+            <Table.Tr>
+              <Table.Td fw={600}>Specs the Tests view groups its tests into</Table.Td>
+              <Table.Td />
+              <Table.Td ta="right" fw={600}>
+                {reconciliation.testSpecs}
+              </Table.Td>
+            </Table.Tr>
+          </Table.Tbody>
+        </Table>
+      </Table.ScrollContainer>
+      <List size="sm" mt="sm" data-health-explanation>
+        {reconciliation.explanation.map((line) => (
+          <List.Item key={line}>{line}</List.Item>
+        ))}
+      </List>
+    </Box>
+  );
+}
+
+function Finding({ item }: { item: HealthFinding }) {
+  return (
+    <Accordion.Item value={item.code} data-health-finding={item.code}>
+      <Accordion.Control>
+        <Group gap="xs" wrap="wrap">
+          <Badge variant="light" color={item.severity === 'warning' ? 'orange' : 'blue'} tt="none">
+            {item.severity === 'warning' ? 'Warning' : 'Note'}
+          </Badge>
+          <Code>{item.code}</Code>
+          <Text span size="sm" c="dimmed">
+            {item.count} affected
+          </Text>
+        </Group>
+      </Accordion.Control>
+      <Accordion.Panel>
+        <Stack gap="xs">
+          <Text component="div" size="sm">
+            {item.message}
+          </Text>
+          {item.items.length > 0 && (
+            <List size="sm" listStyleType="none">
+              {item.items.map((entry) => (
+                <List.Item key={entry.path}>
+                  <Code>{entry.path}</Code>
+                  {entry.candidates?.map((candidate) => (
+                    <Text key={candidate.path} component="div" size="xs" c="dimmed" ml="md">
+                      may be the same promise as <Code>{candidate.path}</Code> ({candidate.reason}); not merged
+                    </Text>
+                  ))}
+                </List.Item>
+              ))}
+            </List>
+          )}
+          {item.count > item.items.length && (
+            <Text size="xs" c="dimmed" component="div">
+              and {item.count - item.items.length} more
+            </Text>
+          )}
+        </Stack>
+      </Accordion.Panel>
+    </Accordion.Item>
+  );
+}
+
+function Mappings({ health, tried }: { health: CatalogHealth | undefined; tried: readonly RootMapping[] }) {
+  const go = useExplorerNavigate();
+  const [from, setFrom] = useState('');
+  const [to, setTo] = useState('');
+  const configured = (health?.roots ?? []).filter((root) => root.source === 'configuration');
+  const write = (list: readonly RootMapping[]) => go({ root: list.length ? list.map(label).join(',') : undefined }, { replace: true });
+  const known = [...configured, ...tried].some((root) => root.from === from.trim() && root.to === to.trim());
+  const matched = (root: RootMapping) => health?.roots.find((item) => item.from === root.from && item.to === root.to && item.source !== 'configuration')?.matched;
+  return (
+    <Box component="section" aria-label="Root mappings">
+      <Title order={3} mb="xs">
+        Root mappings
+      </Title>
+      <Text size="sm" c="dimmed" mb="sm">
+        Two spec paths are one spec only when a mapping says so. A mapping states that paths under one folder are the same specs as paths under another; Atlas never merges paths by a similar title. A mapping tried here is kept in the address and changes nothing on the server. To keep one, set <Code>catalog.roots</Code> or <Code>ATLAS_CATALOG_ROOTS</Code> on the server.
+      </Text>
+      {configured.length + tried.length > 0 && (
+        <List size="sm" listStyleType="none" mb="sm" aria-label="Declared root mappings">
+          {configured.map((root) => (
+            <List.Item key={`c${label(root)}`}>
+              <Group gap="xs" wrap="wrap">
+                <Code>{label(root)}</Code>
+                <Badge variant="light" tt="none">
+                  Configured on the server
+                </Badge>
+                <Text span size="xs" c="dimmed">
+                  changed {plural(root.matched, 'path', 'paths')}
+                </Text>
+              </Group>
+            </List.Item>
+          ))}
+          {tried.map((root) => (
+            <List.Item key={`t${label(root)}`}>
+              <Group gap="xs" wrap="wrap">
+                <Code>{label(root)}</Code>
+                <Badge variant="light" color="gray" tt="none">
+                  Tried here
+                </Badge>
+                {matched(root) !== undefined && (
+                  <Text span size="xs" c="dimmed">
+                    changed {plural(matched(root)!, 'path', 'paths')}
+                  </Text>
+                )}
+                <Tooltip label="Stop trying this mapping">
+                  <ActionIcon variant="subtle" color="gray" aria-label={`Stop trying ${label(root)}`} onClick={() => write(tried.filter((item) => item !== root))}>
+                    <IconTrash size={16} aria-hidden="true" />
+                  </ActionIcon>
+                </Tooltip>
+              </Group>
+            </List.Item>
+          ))}
+        </List>
+      )}
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          if (!to.trim() || known) return;
+          write([...tried, { from: from.trim(), to: to.trim() }]);
+          setFrom('');
+          setTo('');
+        }}
+      >
+        <Group align="flex-end" gap="md" wrap="wrap">
+          <TextInput label="Paths under" description="Leave empty to match every path" placeholder="checkout/" value={from} onChange={(event) => setFrom(event.currentTarget.value)} />
+          <TextInput label="are the same specs as paths under" description="Where the specs are recorded" placeholder="specs/checkout/" value={to} onChange={(event) => setTo(event.currentTarget.value)} />
+          <Button type="submit" disabled={!to.trim() || known}>
+            Try this mapping
+          </Button>
+        </Group>
+      </form>
+    </Box>
+  );
+}
+
+/** The Catalog health tab. */
+export function HealthView() {
+  const search = useExplorerSearch();
+  const tried = useMemo(() => (search.root ? parseRootMappings(new URLSearchParams([['root', search.root]])) : []), [search.root]);
+  const answer = useCatalogHealth(tried);
+  const health = answer.data && !answer.data.unsupported ? answer.data.health : undefined;
+  const warnings = health?.findings.filter((item) => item.severity === 'warning') ?? [];
+  return (
+    <Box aria-label="Catalog health" component="section" mb="lg">
+      <Title order={2} mb="sm">
+        Catalog health
+      </Title>
+      <Text component="div" c="dimmed" mb="md">
+        Specs, domains and coverage counts can disagree because of how specs are named and described, not because of a defect in a test. This explains each number, where the totals differ, and what to change at the source. It only reads: it changes no result.
+      </Text>
+      <Stack gap="lg">
+        <Mappings health={health} tried={tried} />
+        {answer.isPending && (
+          <Text role="status" component="div" c="dimmed">
+            Reading the catalog…
+          </Text>
+        )}
+        {answer.isError && (
+          <Alert role="alert" color="red">
+            The catalog health could not be read. {answer.error.message}
+            <Group mt="xs">
+              <Button type="button" variant="light" onClick={() => void answer.refetch()}>
+                Try again
+              </Button>
+            </Group>
+          </Alert>
+        )}
+        {answer.data?.unsupported && (
+          <Alert role="status" color="blue">
+            This server is older than the catalog health report, so it cannot explain these counts. Upgrade the server to read it.
+          </Alert>
+        )}
+        {health && (
+          <>
+            <Alert role="status" color={health.ok ? 'green' : 'orange'} title={health.ok ? 'No warnings' : plural(warnings.length, 'warning', 'warnings')} data-health-summary>
+              {health.ok ? 'Nothing found that makes a count or a domain filter misleading.' : 'These make a count or a domain filter misleading. Each says what to change at its source.'}
+            </Alert>
+            <Reconciliation health={health} />
+            <Counts health={health} />
+            {health.aliases.length > 0 && (
+              <Box component="section" aria-label="Specs under more than one path">
+                <Title order={3} mb="xs">
+                  Specs under more than one path
+                </Title>
+                <Text size="sm" c="dimmed" mb="xs">
+                  Joined because a root mapping relates them. Every original path stays inspectable.
+                </Text>
+                <Table.ScrollContainer minWidth={420}>
+                  <Table data-health-aliases>
+                    <Table.Thead>
+                      <Table.Tr>
+                        <Table.Th scope="col">Spec</Table.Th>
+                        <Table.Th scope="col">Original paths</Table.Th>
+                      </Table.Tr>
+                    </Table.Thead>
+                    <Table.Tbody>
+                      {health.aliases.map((alias) => (
+                        <Table.Tr key={alias.path}>
+                          <Table.Td>
+                            <Code>{alias.path}</Code>
+                          </Table.Td>
+                          <Table.Td>
+                            <Stack gap={2}>
+                              {alias.sources.map((source) => (
+                                <Code key={source}>{source}</Code>
+                              ))}
+                            </Stack>
+                          </Table.Td>
+                        </Table.Tr>
+                      ))}
+                    </Table.Tbody>
+                  </Table>
+                </Table.ScrollContainer>
+              </Box>
+            )}
+            <Box component="section" aria-label="Domains">
+              <Title order={3} mb="xs">
+                Domains
+              </Title>
+              <Text size="sm" c="dimmed" mb="xs">
+                A domain is what a spec&apos;s own metadata says. Explicit metadata is always authoritative; a domain shared by nearly every spec is reported as a finding below, not changed.
+              </Text>
+              {health.domains.length === 0 ? (
+                <Text component="div" c="dimmed">
+                  No spec declares a domain.
+                </Text>
+              ) : (
+                <Table.ScrollContainer minWidth={320}>
+                  <Table data-health-domains>
+                    <Table.Thead>
+                      <Table.Tr>
+                        <Table.Th scope="col">Domain</Table.Th>
+                        <Table.Th scope="col" ta="right">
+                          Specs
+                        </Table.Th>
+                      </Table.Tr>
+                    </Table.Thead>
+                    <Table.Tbody>
+                      {health.domains.map((domain) => (
+                        <Table.Tr key={domain.name}>
+                          <Table.Td>{domain.name}</Table.Td>
+                          <Table.Td ta="right">{domain.specs}</Table.Td>
+                        </Table.Tr>
+                      ))}
+                    </Table.Tbody>
+                  </Table>
+                </Table.ScrollContainer>
+              )}
+            </Box>
+            <Box component="section" aria-label="Findings">
+              <Title order={3} mb="xs">
+                Findings
+              </Title>
+              {health.findings.length === 0 ? (
+                <Text component="div" c="dimmed">
+                  Nothing to report.
+                </Text>
+              ) : (
+                <Accordion multiple defaultValue={warnings.map((item) => item.code)}>
+                  {health.findings.map((item) => (
+                    <Finding key={item.code} item={item} />
+                  ))}
+                </Accordion>
+              )}
+            </Box>
+            <Box component="section" aria-label="Identity">
+              <Title order={3} mb="xs">
+                Identity
+              </Title>
+              <Text size="sm" component="div" data-health-identity>
+                Fallback identity (known by title only): {health.identity.fallbackIdentity} of {health.identity.checks} checks.
+                {health.identity.declaredBehaviorIds !== undefined && ` Declared behavior ids: ${health.identity.declaredBehaviorIds}. Declared example ids: ${health.identity.declaredExampleIds ?? 0}.`}
+              </Text>
+              <Text size="sm" c="dimmed" component="div" mt="xs">
+                {health.identity.basis}
+              </Text>
+            </Box>
+          </>
+        )}
+      </Stack>
+    </Box>
+  );
+}

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

@@ -13,12 +13,15 @@ import { environmentLabel } from '@crvouga/atlas/reports/layer-axes';
 import { formatMs, runKey, type TestResultEntry, type TestSummary } from '@crvouga/atlas/reports/test-catalog';
 import { Link } from '@tanstack/react-router';
 import { lazy, Suspense, useState } from 'react';
+import { assessTest } from '../evidence/applicability';
+import { ApplicabilitySummary } from '../evidence/applicability-view';
 import { CheckDetail } from '../evidence/check-detail';
 import { ago, exactTime, plural, shortSha, statusWord, useNow } from '../evidence/format';
 import { useEvidence } from '../evidence/evidence-context';
 import { Origin, StatusMark } from '../evidence/marks';
 import { outcomeHeadline, selectedResult } from '../evidence/outcome';
 import { useTestHistory } from './catalog';
+import { releaseOf } from './applicability';
 import { patched, useExplorerNavigate, useExplorerSearch } from './navigate';
 import { Badges, runName } from './parts';
 import { Reliability } from './Reliability';
@@ -129,7 +132,10 @@ function Scope({ pinned, slot }: { pinned: PinnedResult; slot: CheckSlot | undef
 export function TestDetail({ test, slot }: { test: TestSummary; slot: CheckSlot | undefined }) {
   const now = useNow();
   const history = useTestHistory(test.key);
-  const { layer, source } = useExplorerSearch();
+  const search = useExplorerSearch();
+  const { layer, source } = search;
+  const release = releaseOf(search);
+  const applicability = assessTest(test, release);
   const go = useExplorerNavigate();
   const pinned = usePinnedResult(layer, test.key);
   const [recording, setRecording] = useState(false);
@@ -238,6 +244,13 @@ export function TestDetail({ test, slot }: { test: TestSummary; slot: CheckSlot
 
       <Scope pinned={pinned} slot={slot} />
 
+      <Box aria-label="Evidence applicability" component="section" mb="lg">
+        <Title order={3} mb="sm" c="dimmed">
+          Does this evidence apply?
+        </Title>
+        <ApplicabilitySummary assessment={applicability} release={release} />
+      </Box>
+
       <Box aria-label="Current results" component="section" mb="lg">
         <Title order={3} mb="sm" c="dimmed">
           Current result per environment

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

@@ -0,0 +1,43 @@
+/**
+ * @module Explorer evidence applicability
+ *
+ * The explorer's part of evidence applicability: the release a reader names and the stale-or-unverified filter, held in
+ * the explorer's address (`release`, `releaseSha`, `releasePlatform`, `evidence=stale`, the same names a spec page uses),
+ * and the reading of every test of the catalog against them. The reading is the one a feature page makes
+ * (`evidence/applicability.ts`); it never changes a test's status.
+ */
+import { useMemo } from 'react';
+import type { TestSummary } from '@crvouga/atlas/reports/test-catalog';
+
+import { assessTest, type Assessment, type ReleaseIdentity } from '../evidence/applicability';
+import type { ApplicabilityState } from '../evidence/applicability-view';
+import { useExplorerNavigate, useExplorerSearch } from './navigate';
+import type { ExplorerSearch } from './search';
+
+/** The release an explorer address names; every part is optional. */
+export function releaseOf(search: ExplorerSearch): ReleaseIdentity {
+  return {
+    ...(search.release ? { build: search.release } : {}),
+    ...(search.releaseSha ? { sha: search.releaseSha } : {}),
+    ...(search.releasePlatform ? { platform: search.releasePlatform } : {})
+  };
+}
+
+/** Each test's evidence read against the promise and the release, by test key. */
+export function assessTests(tests: readonly TestSummary[], release: ReleaseIdentity): ReadonlyMap<string, Assessment> {
+  return new Map(tests.map((test) => [test.key, assessTest(test, release)] as const));
+}
+
+/** The release and the evidence filter of the explorer's address, with the ways to change them. */
+export function useExplorerApplicability(): ApplicabilityState {
+  const search = useExplorerSearch();
+  const go = useExplorerNavigate();
+  const { release: build, releaseSha: sha, releasePlatform: platform } = search;
+  const release = useMemo(() => releaseOf({ release: build, releaseSha: sha, releasePlatform: platform }), [build, sha, platform]);
+  return {
+    release,
+    onlyStale: search.evidence === 'stale',
+    setRelease: (next) => go({ release: next.build || undefined, releaseSha: next.sha || undefined, releasePlatform: next.platform || undefined }, { replace: true }),
+    setOnlyStale: (on) => go({ evidence: on ? 'stale' : undefined }, { replace: true })
+  };
+}

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

@@ -26,6 +26,7 @@ import {
   type FilterName,
   type QueryFacets
 } from '@crvouga/atlas/reports/artifact-query';
+import { catalogHealth, type CatalogHealth, type RootMapping } from '@crvouga/atlas/reports/catalog-health';
 import {
   artifactList,
   catalogModel,
@@ -371,3 +372,35 @@ export function useRunDetail(key: string | undefined) {
     retry: false
   });
 }
+
+/** What the Catalog health tab reads: the diagnostics, or that this server is too old to give them. */
+export type HealthAnswer = { readonly unsupported: false; readonly health: CatalogHealth } | { readonly unsupported: true };
+
+/**
+ * Why the Specs, domains and counts of the report disagree. From the server when it has one (it also applies the root
+ * mappings it is configured with, and says so in `roots[].source`); otherwise worked out here from the specs and
+ * results this page holds. A server without the route answers `unsupported`, and the page says so.
+ */
+export function useCatalogHealth(roots: readonly RootMapping[]) {
+  const catalog = useTestCatalog();
+  const asked = roots.map((root) => `${root.from}>${root.to}`);
+  return useQuery({
+    queryKey: ['catalog-health', catalog.version, asked.join('\u0001')],
+    queryFn: async ({ signal }): Promise<HealthAnswer> => {
+      if (catalog.source === 'server') {
+        const params = new URLSearchParams(asked.map((root) => ['root', root]));
+        try {
+          return { unsupported: false, health: await reportJson<CatalogHealth>(`/tests/health${params.size ? `?${params}` : ''}`, signal) };
+        } catch (error) {
+          if (notFound(error)) return { unsupported: true };
+          throw error;
+        }
+      }
+      return { unsupported: false, health: catalogHealth(catalog.model!, roots) };
+    },
+    enabled: catalog.model !== null,
+    placeholderData: keepPreviousData,
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false
+  });
+}

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

@@ -2,7 +2,7 @@
  * @module Explorer address
  *
  * 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, the Compare tab with its two pinned runs (`base`, `cand`) and the behavior opened (`pair`), the exact layer a test's detail is pinned to, the recording and position of a shared moment in it (`clip`, `clipAt`), and the one file of a run's layer its Artifacts select. Filters that
+ * the words searched, the filters, the grouping, the order, the Runs tab with the run opened in it, the Compare tab with its two pinned runs (`base`, `cand`) and the behavior opened (`pair`), the Catalog health tab with the root mappings it tries (`root`), the exact layer a test's detail is pinned to, the recording and position of a shared moment in it (`clip`, `clipAt`), and the one file of a run's layer its Artifacts select. Filters that
  * 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.
  *
@@ -19,8 +19,8 @@ export const TEST_GROUPS = ['spec', 'domain', 'environment', 'status', 'producer
 /** One of {@link TEST_GROUPS}. */
 export type TestGroup = (typeof TEST_GROUPS)[number];
 
-/** The orders the explorer offers: `relevance` (best match first, only with words to match) and those of the catalog. */
-export const EXPLORER_SORTS = ['relevance', ...TEST_SORTS] as const;
+/** The orders the explorer offers: `relevance` (best match first, only with words to match), `evidence` (tests whose evidence is stale or unverified first, worked out in the viewer) and those of the catalog. */
+export const EXPLORER_SORTS = ['relevance', 'evidence', ...TEST_SORTS] as const;
 /** One of {@link EXPLORER_SORTS}. */
 export type ExplorerSort = (typeof EXPLORER_SORTS)[number];
 
@@ -61,9 +61,17 @@ export const ExplorerSearchFields = {
   until: text,
   /** Only the tests a CI run recorded (a `RunSummary.key`). Not `run`, which already names a recorded statechart run. */
   inRun: text,
+  /** `stale`: only tests whose evidence is stale or unverified (not that applies to the current promise and, when one is named, the release). Never a test status. */
+  evidence: z.enum(['stale']).optional().catch(undefined),
+  /** The release evidence is read against: its build, commit and platform (the names a spec page uses). A build such as `90` is read from a typed link as a number: coerced back to its text. */
+  release: text,
+  releaseSha: text,
+  releasePlatform: text,
   group: z.enum(TEST_GROUPS).optional().catch(undefined),
   sort: z.enum(EXPLORER_SORTS).optional().catch(undefined),
-  tab: z.enum(['runs', 'artifacts', 'collections', 'compare']).optional().catch(undefined),
+  tab: z.enum(['runs', 'artifacts', 'collections', 'compare', 'health']).optional().catch(undefined),
+  /** The root mappings (`from>to`, comma-separated) the Catalog health tab tries, beside those the server is configured with. */
+  root: text,
   /** The review collection opened in the Collections tab (its stable id), and the revision of it (default: the newest). */
   collection: text,
   rev: z.coerce.number().int().positive().optional().catch(undefined),
@@ -125,9 +133,14 @@ export type ExplorerSearch = {
   readonly since?: string;
   readonly until?: string;
   readonly inRun?: string;
+  readonly evidence?: 'stale';
+  readonly release?: string;
+  readonly releaseSha?: string;
+  readonly releasePlatform?: string;
   readonly group?: TestGroup;
   readonly sort?: ExplorerSort;
-  readonly tab?: 'runs' | 'artifacts' | 'collections' | 'compare';
+  readonly tab?: 'runs' | 'artifacts' | 'collections' | 'compare' | 'health';
+  readonly root?: string;
   readonly collection?: string;
   readonly rev?: number;
   readonly base?: string;
@@ -186,7 +199,7 @@ export function queryOf(search: ExplorerSearch): TestQuery {
     ...(values(search.scope).length ? { scope: values(search.scope) } : {}),
     artifactTag: values(search.artifactTag),
     ...(search.inherited ? { inherited: true } : {}),
-    sort: search.sort === 'relevance' || !search.sort ? 'spec' : search.sort
+    sort: search.sort === 'relevance' || search.sort === 'evidence' || !search.sort ? 'spec' : search.sort
   };
 }
 
@@ -197,7 +210,7 @@ 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.scope || search.artifactTag || search.inRun || search.video);
+  return !!(search.q || search.status || search.env || search.producer || search.domain || search.spec || search.tag || search.scope || search.artifactTag || search.inRun || search.video || search.evidence);
 }
 
 /** The reliability scope an address asks for, in the shape `reliability` reads: days are the viewer's local days. */