@crvouga/atlas 0.0.0-stage → 0.2.0

package/packages/visualizer/scripts/publish-data.ts

@@ -0,0 +1,22 @@
+import path from 'node:path';
+
+import { APP_ROOT, resolveRoots } from '../vite/atlas-files';
+import { publishData } from '../vite/publish';
+
+/**
+ * `pnpm publish-data`: the spec and the newest runs into `public/data` (or `ATLAS_OUT`), where
+ * `pnpm build` picks them up. Roots come from `ATLAS_SPECS_ROOT` / `ATLAS_RUNS_ROOT` or
+ * `ATLAS_FIXTURE`, as for the dev server.
+ */
+try {
+  const roots = resolveRoots();
+  const base = process.env.INIT_CWD || process.cwd();
+  const out = process.env.ATLAS_OUT ? path.resolve(base, process.env.ATLAS_OUT) : path.join(APP_ROOT, 'public/data');
+  const keep = Number(process.env.ATLAS_KEEP_RUNS ?? 30);
+  const result = publishData({ roots, out, keep: Number.isFinite(keep) && keep >= 0 ? keep : 30 });
+  process.stdout.write(`Published ${result.files.length} spec file(s) and ${result.published.length} run(s) to ${out} (${roots.label})\n`);
+  if (result.skipped.length) process.stdout.write(`Not published, privacy check missing or failed: ${result.skipped.join(', ')}\n`);
+} catch (error) {
+  process.stderr.write(`publish-data failed: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/packages/visualizer/src/app/AppShell.tsx

@@ -0,0 +1,56 @@
+import { Outlet, useLocation, useSearch } from '@tanstack/react-router';
+
+import { Header } from '../components/Header';
+import { EvidenceProvider } from '../evidence/evidence-context';
+import { SourcesPanel } from '../evidence/sources-panel';
+import { SpecIndex } from '../evidence/spec-index';
+import { kindOfAddress } from '../spec-kind';
+import styles from '../views/views.module.css';
+import { AtlasProvider, useAtlas } from './atlas-context';
+import { Gazetteer } from './gazetteer';
+import { SearchQueryProvider } from './search-query';
+
+function Index() {
+  const { pathname } = useLocation();
+  const kind = kindOfAddress(pathname);
+  return kind ? <SpecIndex kind={kind} /> : pathname.startsWith('/specs/') ? <nav aria-label="Specs" /> : <Gazetteer />;
+}
+
+function Body() {
+  const { view, spec } = useAtlas();
+  const { pathname } = useLocation();
+  if (!pathname.startsWith('/specs/') && !view && spec.error) {
+    return (
+      <div className={styles.message} role="alert">
+        <h1>The spec couldn’t be loaded</h1>
+        <p>{spec.error}</p>
+        <button type="button" className={styles.button} onClick={spec.retry}>
+          Try again
+        </button>
+      </div>
+    );
+  }
+  return <Outlet />;
+}
+
+export function AppShell() {
+  const { run } = useSearch({ strict: false });
+  return (
+    <AtlasProvider run={run}>
+      <EvidenceProvider>
+        <SearchQueryProvider>
+          <div className={styles.app}>
+            <Header />
+            <div className={styles.frame}>
+              <Index />
+              <main className={styles.main}>
+                <Body />
+              </main>
+            </div>
+            <SourcesPanel />
+          </div>
+        </SearchQueryProvider>
+      </EvidenceProvider>
+    </AtlasProvider>
+  );
+}

package/packages/visualizer/src/app/atlas-context.tsx

@@ -0,0 +1,23 @@
+import { createContext, useContext, useState, type ReactNode } from 'react';
+
+import { useAtlasData, useLiveUpdates, type AtlasData } from '../data/queries';
+
+type AtlasSession = AtlasData & { live: boolean; setLive: (enabled: boolean) => void };
+const AtlasContext = createContext<AtlasSession | null>(null);
+
+export function AtlasProvider({ run, children }: { run: string | undefined; children: ReactNode }) {
+  const [live, setLiveState] = useState(true);
+  useLiveUpdates(live);
+  const data = useAtlasData(run, live);
+  const setLive = (enabled: boolean) => {
+    setLiveState(enabled);
+    if (enabled) data.refresh();
+  };
+  return <AtlasContext.Provider value={{ ...data, live, setLive }}>{children}</AtlasContext.Provider>;
+}
+
+export function useAtlas() {
+  const data = useContext(AtlasContext);
+  if (!data) throw new Error('useAtlas needs an AtlasProvider');
+  return data;
+}

package/packages/visualizer/src/app/gazetteer.module.css

@@ -0,0 +1,97 @@
+.index {
+  background: var(--bg);
+  border-right: 1px solid var(--line);
+  overflow: auto;
+  padding: 12px 8px 32px;
+  min-height: 0;
+}
+
+.index h2 {
+  margin: 14px 10px 6px;
+  font-size: 0.9375rem;
+  font-weight: 600;
+}
+
+.index h3 {
+  margin: 16px 10px 4px;
+  color: var(--ink-3);
+  font-size: 0.75rem;
+  font-weight: 600;
+}
+
+.index ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.chart,
+.row {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 12px;
+  padding: 6px 10px;
+  border-radius: 8px;
+  color: inherit;
+  font-size: 0.9rem;
+  text-decoration: none;
+}
+
+.chart {
+  color: var(--ink-2);
+  font-weight: 600;
+}
+
+.chart:hover,
+.row:hover {
+  background: var(--bg-2);
+}
+
+.chart[aria-current='page'],
+.row[aria-current='page'] {
+  background: var(--place-soft);
+  color: var(--ink);
+  font-weight: 600;
+}
+
+.status {
+  flex: none;
+  color: var(--ink-3);
+  font-size: 0.75rem;
+  font-weight: 400;
+  text-align: right;
+  white-space: nowrap;
+}
+
+.row[data-status='failed'] .status {
+  color: var(--failed);
+  font-weight: 600;
+}
+
+.row[data-status='flaky'] .status {
+  color: var(--flaky-ink);
+}
+
+.excluded {
+  padding: 6px 10px;
+  color: var(--ink-3);
+  font-size: 0.9rem;
+}
+
+.empty {
+  margin: 4px 10px;
+  color: var(--ink-3);
+  font-size: 0.875rem;
+}
+
+@media (max-width: 760px) {
+  .index {
+    flex: none;
+    max-height: none;
+    min-height: auto;
+    overflow: visible;
+    border-right: 0;
+    border-top: 1px solid var(--line);
+  }
+}

package/packages/visualizer/src/app/gazetteer.tsx

@@ -0,0 +1,105 @@
+import { Link, useLocation, useParams, useSearch } from '@tanstack/react-router';
+
+import { STATUS_LABEL, type AtlasView, type StateView } from '../data/model';
+import { useAtlas } from './atlas-context';
+import { useSearchQuery } from './search-query';
+import styles from './gazetteer.module.css';
+
+function hit(query: string, text: string) {
+  const needle = query.trim().toLowerCase();
+  return needle.length === 0 || text.toLowerCase().includes(needle);
+}
+
+function screensOf(view: AtlasView, chartId: string) {
+  const chart = view.charts.get(chartId);
+  if (!chart) return [];
+  return chart.states
+    .map((key) => view.states.get(key))
+    .filter((state): state is StateView => Boolean(state && (state.kind === 'screen' || state.kind === 'final')));
+}
+
+export function Gazetteer() {
+  const { query } = useSearchQuery();
+  const { view } = useAtlas();
+  const params = useParams({ strict: false });
+  const search = useSearch({ strict: false });
+  const { pathname } = useLocation();
+  const screen = typeof search.screen === 'string' ? search.screen : undefined;
+  const journeyId = typeof search.journey === 'string' ? search.journey : undefined;
+  const group = typeof search.group === 'string' ? search.group : undefined;
+  const journeys = (view?.journeys ?? []).filter((journey) => journey.chartIds.length > 0 && hit(query, journey.name));
+  return (
+    <nav className={styles.index} aria-label="Places">
+      <h2>Places</h2>
+      {!view && <p className={styles.empty}>Loading the spec…</p>}
+      {view?.contexts.map((context) => (
+        <section key={context.id}>
+          <h3>{context.name}</h3>
+          {context.chartIds.map((chartId) => {
+            const chart = view.charts.get(chartId);
+            if (!chart) return null;
+            const screens = screensOf(view, chartId).filter((state) => hit(query, `${state.name} ${chart.name} ${context.name}`));
+            const chartHit = hit(query, `${chart.name} ${context.name}`);
+            if (query.trim() && screens.length === 0 && !chartHit) return null;
+            return (
+              <div key={chartId}>
+                <Link className={styles.chart} to="/chart/$chartId" params={{ chartId }} search={(prev) => ({ run: prev.run, screen: undefined, journey: undefined, group: undefined })} activeOptions={{ includeSearch: true, explicitUndefined: true }} aria-current={params.chartId === chartId && !screen && !journeyId && !group ? 'page' : undefined}>
+                  {chart.name}
+                </Link>
+                <ul>
+                  {screens.map((state) => (
+                    <li key={state.key}>
+                      <Link
+                        className={styles.row}
+                        data-status={state.status}
+                        to="/chart/$chartId"
+                        params={{ chartId }}
+                        search={(prev) => ({ run: prev.run, screen: state.name, journey: prev.journey })}
+                        aria-current={params.chartId === chartId && screen === state.name ? 'page' : undefined}
+                      >
+                        <span>{state.name}</span>
+                        <span className={styles.status}>{STATUS_LABEL[state.status]}</span>
+                      </Link>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            );
+          })}
+        </section>
+      ))}
+      {journeys.length > 0 && (
+        <section>
+          <h3>Journeys</h3>
+          <ul>
+            {journeys.map((journey) => (
+              <li key={journey.id}>
+                <Link
+                  className={styles.row}
+                  data-status={journey.status}
+                  to="/chart/$chartId"
+                  params={{ chartId: journey.chartIds[0] ?? '' }}
+                  search={(prev) => ({ run: prev.run, journey: journey.id })}
+                  aria-current={journeyId === journey.id && pathname.startsWith('/chart') ? 'page' : undefined}
+                >
+                  <span>{journey.name}</span>
+                  <span className={styles.status}>{STATUS_LABEL[journey.status]}</span>
+                </Link>
+              </li>
+            ))}
+          </ul>
+        </section>
+      )}
+      {view && view.excluded.length > 0 && (
+        <section>
+          <h2>Not in the spec yet</h2>
+          <ul>
+            {view.excluded.filter((item) => hit(query, item)).map((item) => (
+              <li key={item} className={styles.excluded}>{item}</li>
+            ))}
+          </ul>
+        </section>
+      )}
+    </nav>
+  );
+}

package/packages/visualizer/src/app/report-sources.tsx

@@ -0,0 +1,122 @@
+import type { RemoteReportSource } from '@crvouga/atlas/schema';
+import type { ReactNode } from 'react';
+import { createContext, useContext, useMemo, useState } from 'react';
+import { RemoteReportSourceSchema } from '@crvouga/atlas/schema';
+import { useQuery } from '@tanstack/react-query';
+import { z } from 'zod/v4';
+
+import type { ReportBackend } from '../data/adapters/report-backend';
+import { getJson, LoadError } from '../data/adapters';
+import { useAdapter } from '../data/adapters/context';
+import { createReportBackend } from '../data/adapters/report-backend';
+
+const SourceListSchema = z
+  .object({ schemaVersion: z.literal(1), sources: z.array(RemoteReportSourceSchema) })
+  .refine(({ sources }) => new Set(sources.map((source) => source.id)).size === sources.length, 'Each source needs a unique id.');
+const PreferencesSchema = z.object({ custom: z.array(RemoteReportSourceSchema), disabled: z.array(z.string()) });
+
+export type BackendEntry = { backend: ReportBackend; config: RemoteReportSource; enabled: boolean; custom: boolean };
+export type ReportSources = {
+  entries: BackendEntry[];
+  loading: boolean;
+  error: string | null;
+  retry: () => void;
+  add: (config: RemoteReportSource) => void;
+  remove: (id: string) => void;
+  toggle: (id: string) => void;
+};
+export const ReportSourcesContext = createContext<ReportSources | null>(null);
+
+export function useReportSources() {
+  const registry = useContext(ReportSourcesContext);
+  if (!registry) throw new Error('useReportSources needs a ReportSourcesProvider');
+  return registry;
+}
+
+export function ReportSourcesProvider({ children }: { children: ReactNode }) {
+  const adapter = useAdapter();
+  const defaultConfig = useMemo<RemoteReportSource>(
+    () => ({
+      id: 'workspace',
+      label: adapter.kind === 'dev' ? 'Workspace runs' : 'Published reports',
+      type: 'http',
+      baseUrl: adapter.kind === 'dev' ? '/__atlas/' : (import.meta.env.VITE_ATLAS_BASE_URL ?? './data/'),
+      live: adapter.kind === 'dev'
+    }),
+    [adapter]
+  );
+  const configBase = defaultConfig.baseUrl.endsWith('/') ? defaultConfig.baseUrl : `${defaultConfig.baseUrl}/`;
+  const configUrl = new URL(import.meta.env.VITE_ATLAS_SOURCES_URL ?? 'sources.json', new URL(configBase, window.location.href)).href;
+  const storageKey = `atlas:sources:${configUrl}`;
+  const [storageError, setStorageError] = useState<string | null>(null);
+  const [preferences, setPreferences] = useState(() => {
+    try {
+      const parsed = PreferencesSchema.safeParse(JSON.parse(localStorage.getItem(storageKey) ?? '{}'));
+      return parsed.success ? parsed.data : { custom: [], disabled: [] };
+    } catch {
+      return { custom: [], disabled: [] };
+    }
+  });
+  const configuration = useQuery({
+    queryKey: ['report-sources', configUrl],
+    queryFn: async () => {
+      try {
+        const parsed = SourceListSchema.parse(await getJson(configUrl));
+        return parsed.sources.map((source) => ({
+          ...source,
+          baseUrl: new URL(source.baseUrl, configUrl).href,
+          eventsUrl: source.eventsUrl
+            ? new URL(source.eventsUrl, new URL(source.baseUrl.endsWith('/') ? source.baseUrl : `${source.baseUrl}/`, configUrl)).href
+            : undefined
+        }));
+      } catch (error) {
+        if (error instanceof LoadError && error.status === 404) return [defaultConfig];
+        throw error;
+      }
+    }
+  });
+  const configured = configuration.data ?? [defaultConfig];
+  const entries = useMemo(() => {
+    const ids = new Set(configured.map((source) => source.id));
+    const custom = preferences.custom.filter((source) => !ids.has(source.id));
+    return [...configured, ...custom].map((config) => ({
+      config,
+      backend: createReportBackend(config),
+      enabled: !preferences.disabled.includes(config.id),
+      custom: !ids.has(config.id)
+    }));
+  }, [configured, preferences]);
+  const update = (next: z.infer<typeof PreferencesSchema>) => {
+    setPreferences(next);
+    try {
+      localStorage.setItem(storageKey, JSON.stringify(next));
+      setStorageError(null);
+    } catch {
+      setStorageError('Source preferences could not be saved in this browser. They remain active for this session.');
+    }
+  };
+  const registry: ReportSources = {
+    entries,
+    loading: configuration.isPending,
+    error: configuration.error ? `Source configuration could not be loaded: ${configuration.error.message}` : storageError,
+    retry: () => void configuration.refetch(),
+    add: (raw) => {
+      const config = RemoteReportSourceSchema.parse({ ...raw, live: false });
+      if (entries.some((entry) => entry.config.id === config.id)) throw new Error('A source with this id already exists.');
+      update({ ...preferences, custom: [...preferences.custom, config] });
+    },
+    remove: (id) =>
+      update({
+        custom: preferences.custom.filter((source) => source.id !== id),
+        disabled: preferences.disabled.filter((sourceId) => sourceId !== id)
+      }),
+    toggle: (id) =>
+      update({
+        ...preferences,
+        disabled: preferences.disabled.includes(id)
+          ? preferences.disabled.filter((sourceId) => sourceId !== id)
+          : [...preferences.disabled, id]
+      })
+  };
+  return <ReportSourcesContext.Provider value={registry}>{children}</ReportSourcesContext.Provider>;
+}

package/packages/visualizer/src/app/router.tsx

@@ -0,0 +1,69 @@
+import { createHashHistory, createRootRoute, createRoute, createRouter, type RouterHistory } from '@tanstack/react-router';
+import { z } from 'zod/v4';
+
+import { SpecPage } from '../evidence/spec-page';
+import { ChartPage } from '../views/ChartPage';
+import { ProductPage } from '../views/ProductPage';
+import { AppShell } from './AppShell';
+
+const RootSearch = z.object({ run: z.string().min(1).optional().catch(undefined) });
+
+const ChartSearch = RootSearch.extend({
+  screen: z.string().min(1).optional().catch(undefined),
+  event: z.string().min(1).optional().catch(undefined),
+  journey: z.string().min(1).optional().catch(undefined),
+  group: z.string().min(1).optional().catch(undefined),
+  t: z.coerce.number().nonnegative().optional().catch(undefined)
+});
+
+export type ChartSearch = z.infer<typeof ChartSearch>;
+
+/** A spec document, the check opened in it, one layer's record of that check, and a recorded moment. */
+const SpecSearch = RootSearch.extend({
+  spec: z.string().min(1).optional().catch(undefined),
+  check: z.string().min(1).optional().catch(undefined),
+  layer: z.string().min(1).optional().catch(undefined),
+  view: z.enum(['recording']).optional().catch(undefined),
+  moment: z.coerce.number().int().positive().optional().catch(undefined)
+});
+
+export type SpecSearch = z.infer<typeof SpecSearch>;
+
+/** A fresh route tree per router, so a test can run its own viewer beside the page's. */
+function routeTree() {
+  const rootRoute = createRootRoute({
+    validateSearch: (search) => RootSearch.parse(search),
+    component: AppShell
+  });
+  const productRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/',
+    component: ProductPage
+  });
+  const chartRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/chart/$chartId',
+    validateSearch: (search) => ChartSearch.parse(search),
+    component: ChartPage
+  });
+  const specRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/specs/$kind',
+    validateSearch: (search) => SpecSearch.parse(search),
+    component: SpecPage
+  });
+  return rootRoute.addChildren([productRoute, chartRoute, specRoute]);
+}
+
+export function createAtlasRouter(history: RouterHistory) {
+  return createRouter({ routeTree: routeTree(), history, defaultPreload: false, scrollRestoration: true });
+}
+
+/** Addresses use the hash, so a built site deep-links without server rewrites. */
+export const router = createAtlasRouter(createHashHistory());
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router;
+  }
+}

package/packages/visualizer/src/app/search-query.tsx

@@ -0,0 +1,14 @@
+import { createContext, useContext, useState, type ReactNode } from 'react';
+
+type SearchQuery = { query: string; setQuery: (value: string) => void };
+const SearchQueryContext = createContext<SearchQuery>({ query: '', setQuery: () => {} });
+
+/** What is typed in the header narrows whichever index is open. */
+export function useSearchQuery() {
+  return useContext(SearchQueryContext);
+}
+
+export function SearchQueryProvider({ children }: { children: ReactNode }) {
+  const [query, setQuery] = useState('');
+  return <SearchQueryContext.Provider value={{ query, setQuery }}>{children}</SearchQueryContext.Provider>;
+}

package/packages/visualizer/src/components/DataIssues.module.css

@@ -0,0 +1,136 @@
+.trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  font-size: 0.78rem;
+  color: var(--muted);
+  background: transparent;
+  border: 1px solid var(--line);
+  border-radius: var(--pill);
+  padding: 0.3rem 0.7rem;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.trigger:hover {
+  border-color: var(--line-2);
+  color: var(--ink-2);
+}
+
+.trigger[data-has-problems='true'] {
+  color: var(--system-ink);
+}
+
+.overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(15, 23, 42, 0.18);
+  z-index: 60;
+}
+
+.sheet {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: min(34rem, 100vw);
+  background: var(--card);
+  border-left: 1px solid var(--line);
+  box-shadow: var(--shadow-pop);
+  z-index: 61;
+  display: flex;
+  flex-direction: column;
+  padding: 1.25rem 1.25rem 0;
+}
+
+.head {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.title {
+  margin: 0;
+  font-size: 1.15rem;
+}
+
+.close {
+  border: 0;
+  background: transparent;
+  color: var(--muted);
+  cursor: pointer;
+  width: 2rem;
+  height: 2rem;
+  display: grid;
+  place-items: center;
+  border-radius: var(--pill);
+}
+
+.close:hover {
+  background: var(--bg-2);
+}
+
+.lead {
+  margin: 0.4rem 0 1rem;
+  color: var(--ink-3);
+  font-size: 0.9rem;
+}
+
+.list {
+  overflow-y: auto;
+  padding-bottom: 2rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.fileName {
+  margin: 0 0 0.4rem;
+  font-family: var(--mono);
+  font-size: 0.78rem;
+  font-weight: 600;
+  color: var(--ink-2);
+  word-break: break-all;
+}
+
+.items {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.item {
+  display: grid;
+  grid-template-columns: 4.6rem 1fr;
+  gap: 0.6rem;
+  font-size: 0.85rem;
+  color: var(--ink-2);
+  background: var(--bg);
+  border-radius: var(--radius-sm);
+  padding: 0.5rem 0.65rem;
+}
+
+.severity {
+  font-size: 0.7rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--muted);
+  padding-top: 0.1rem;
+}
+
+.item[data-severity='error'] .severity {
+  color: var(--failed-ink);
+}
+
+.item[data-severity='warning'] .severity {
+  color: var(--system-ink);
+}
+
+.path {
+  font-weight: 600;
+  color: var(--ink);
+}