@crvouga/atlas 0.4.0 → 0.5.0

package/packages/visualizer/README.md

@@ -45,6 +45,27 @@ manager sets it to where you ran the command, or the current directory). With no
 Editing a spec file or a run publishing a snapshot updates the open page in about a second, without a reload,
 keeping selection, zoom and pan.
 
+### Layered reports for any spec
+
+Besides charts and runs, the viewer shows the combined result of every spec (Gherkin, Quint, DMN,
+Alloy, OpenSLO, …) from the layers your suites published. Point `ATLAS_REPORTS_MODULE` at a module in
+your project that exports `reportsDevFetch`, built with `reportsHost` from
+`@crvouga/atlas/reports/host`:
+
+```ts
+// atlas.reports.ts
+import { reportsHost } from '@crvouga/atlas/reports/host';
+
+export const reportsDevFetch = reportsHost({ specs: './specs', stores: ['./atlas-reports'] });
+```
+
+```sh
+ATLAS_REPORTS_MODULE="$(pwd)/atlas.reports.ts" atlas-visualizer dev --specs ./specs
+```
+
+See [integrating Atlas](../../docs/integrating.md#6-browse-it) for publishing layers and the routes
+this serves.
+
 ### Commands
 
 ```sh

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

@@ -1,4 +1,5 @@
 import { Outlet, useLocation, useSearch } from '@tanstack/react-router';
+import { lazy, Suspense } from 'react';
 
 import { Header } from '../components/Header';
 import { EvidenceProvider } from '../evidence/evidence-context';
@@ -6,10 +7,14 @@ 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 { Finder } from '../find/Finder';
 import { AtlasProvider, useAtlas } from './atlas-context';
 import { Gazetteer } from './gazetteer';
 
+// The finder brings every spec parser with it. It loads as soon as the page has drawn, long before anyone presses ⌘K.
+const loadFinder = () => import('../find/Finder').then((m) => ({ default: m.Finder }));
+const Finder = lazy(loadFinder);
+if (typeof window !== 'undefined') setTimeout(() => void loadFinder(), 0);
+
 function Index() {
   const { pathname } = useLocation();
   const kind = kindOfAddress(pathname);
@@ -47,7 +52,9 @@ export function AppShell() {
             </main>
           </div>
           <SourcesPanel />
-          <Finder />
+          <Suspense fallback={null}>
+            <Finder />
+          </Suspense>
         </div>
       </EvidenceProvider>
     </AtlasProvider>

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

@@ -9,6 +9,7 @@ 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';
+import { runtimeConfig, runtimeUrl } from '../runtime';
 
 const SourceListSchema = z
   .object({ schemaVersion: z.literal(1), sources: z.array(RemoteReportSourceSchema) })
@@ -35,15 +36,16 @@ export function useReportSources() {
 
 export function ReportSourcesProvider({ children }: { children: ReactNode }) {
   const adapter = useAdapter();
+  const server = runtimeUrl(runtimeConfig()?.dataUrl);
   const defaultConfig = useMemo<RemoteReportSource>(
     () => ({
       id: 'workspace',
-      label: adapter.kind === 'dev' ? 'Workspace runs' : 'Published reports',
+      label: server ? 'Atlas server' : 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'
+      baseUrl: server ?? (adapter.kind === 'dev' ? '/__atlas/' : (import.meta.env.VITE_ATLAS_BASE_URL ?? './data/')),
+      live: server !== undefined || adapter.kind === 'dev'
     }),
-    [adapter]
+    [adapter, server]
   );
   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;

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

@@ -1,8 +1,7 @@
-import { createHashHistory, createRootRoute, createRoute, createRouter, type RouterHistory } from '@tanstack/react-router';
+import { createHashHistory, createRootRoute, createRoute, createRouter, lazyRouteComponent, 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';
 
@@ -44,7 +43,8 @@ function routeTree() {
     getParentRoute: () => rootRoute,
     path: '/chart/$chartId',
     validateSearch: (search) => ChartSearch.parse(search),
-    component: ChartPage
+    // The map (the graph, its layout and its renderer) is the largest part of the page and only this route needs it.
+    component: lazyRouteComponent(() => import('../views/ChartPage'), 'ChartPage')
   });
   const specRoute = createRoute({
     getParentRoute: () => rootRoute,

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

@@ -87,6 +87,40 @@
   animation: pulse 1.4s var(--ease) infinite;
 }
 
+.connection {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--ink-3);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  white-space: nowrap;
+}
+
+.connectionDot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--ink-3);
+}
+
+.connection[data-status='live'] {
+  color: var(--place);
+}
+
+.connection[data-status='live'] .connectionDot {
+  background: var(--place);
+}
+
+.connection[data-status='reconnecting'] {
+  color: var(--failed-ink);
+}
+
+.connection[data-status='reconnecting'] .connectionDot {
+  background: currentColor;
+  animation: pulse 1.4s var(--ease) infinite;
+}
+
 @keyframes pulse {
   50% {
     opacity: 0.35;
@@ -195,6 +229,7 @@
   }
 
   .live,
+  .connection,
   .picker {
     display: none;
   }

package/packages/visualizer/src/components/Header.tsx

@@ -1,14 +1,14 @@
 import { Link, useLocation, useNavigate, useSearch } from '@tanstack/react-router';
-import { useEffect, useMemo } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 
 import { useAtlas } from '../app/atlas-context';
-import { commandKey } from '../find/Finder';
-import { setFinderOpen } from '../find/open';
+import { commandKey, setFinderOpen } from '../find/open';
 import type { AtlasView } from '../data/model';
 import { LATEST } from '../data/queries';
 import { useEvidence } from '../evidence/evidence-context';
 import { plural } from '../evidence/format';
 import { excludedCount } from '../evidence/sources-panel';
+import { eventsAddress, listenLive, useLiveStatus, type ReportAnnouncement } from '../live/live-stream';
 import { kindOfAddress, outlinePath, SPEC_KINDS } from '../spec-kind';
 import { useUiStore } from '../state/ui-store';
 import { DataIssues } from './DataIssues';
@@ -69,6 +69,42 @@ function LiveRuns() {
   );
 }
 
+/** Is this page being kept up to date by its server, and what arrived last. Nothing at all for a static site. */
+function ServerConnection() {
+  const status = useLiveStatus();
+  const [arrival, setArrival] = useState<ReportAnnouncement | null>(null);
+  useEffect(() => {
+    const url = eventsAddress();
+    if (!url) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const stop = listenLive(url, (event) => {
+      if (event.type !== 'report' || !event.report.added.length) return;
+      setArrival(event.report);
+      clearTimeout(timer);
+      timer = setTimeout(() => setArrival(null), 8_000);
+    });
+    return () => {
+      clearTimeout(timer);
+      stop();
+    };
+  }, []);
+  if (status === 'off') return null;
+  const first = arrival?.added[0];
+  const failed = arrival?.added.reduce((sum, layer) => sum + (layer.counts?.failed ?? 0), 0) ?? 0;
+  return (
+    <span className={styles.connection} data-status={status} role="status" title={status === 'live' ? 'This page updates as results reach the server.' : status === 'connecting' ? 'Connecting to the server.' : 'The connection to the server was lost. Trying again; the report on screen is the last one received.'}>
+      <span className={styles.connectionDot} aria-hidden="true" />
+      {arrival && first
+        ? `${first.producer}${first.environment ? ` · ${first.environment}` : ''}${arrival.addedTotal > 1 ? ` +${arrival.addedTotal - 1}` : ''}${failed ? ` · ${plural(failed, 'failure', 'failures')}` : ' · new results'}`
+        : status === 'live'
+          ? 'Live'
+          : status === 'connecting'
+            ? 'Connecting'
+            : 'Reconnecting'}
+    </span>
+  );
+}
+
 function SourcesButton() {
   const { layers, ready, unavailable, excluded } = useEvidence();
   const setOpen = useUiStore((s) => s.setSourcesOpen);
@@ -116,6 +152,7 @@ export function Header() {
         ))}
       </nav>
       <div className={styles.tools}>
+        <ServerConnection />
         <LiveRuns />
         {!kind && view && <RunPicker view={view} />}
         {!kind && view && <DataIssues issues={view.issues} />}

package/packages/visualizer/src/data/adapters/adapter.ts

@@ -1,4 +1,6 @@
-import { AtlasChangeSchema, type AtlasChange } from '@crvouga/atlas/schema';
+import type { AtlasChange } from '@crvouga/atlas/schema';
+
+import { listenChanges } from '../../live/live-stream';
 
 export type { AtlasChange } from '@crvouga/atlas/schema';
 
@@ -93,20 +95,6 @@ export function createHttpAdapter(baseUrl: string, kind: AtlasAdapter['kind'] =
 function subscribeToEvents(url: string): NonNullable<AtlasAdapter['subscribe']> {
   const location = new URL(url);
   if (!['http:', 'https:'].includes(location.protocol) || location.username || location.password) throw new Error('Use an HTTP event URL without credentials.');
-  return (onChange) => {
-    if (typeof EventSource === 'undefined') return () => undefined;
-    const stream = new EventSource(url);
-    const receive = (event: MessageEvent<string>) => {
-      try {
-        const change = AtlasChangeSchema.safeParse(JSON.parse(event.data));
-        if (change.success) onChange(change.data);
-      } catch {
-        return;
-      }
-    };
-    stream.addEventListener('message', receive);
-    stream.addEventListener('atlas:change', receive);
-    stream.addEventListener('open', () => onChange({ scope: 'runs', files: [], runIds: [] }));
-    return () => stream.close();
-  };
+  // One connection per address, however many parts of the page listen to it.
+  return (onChange) => listenChanges(url, onChange);
 }

package/packages/visualizer/src/data/adapters/index.ts

@@ -1,3 +1,4 @@
+import { runtimeConfig, runtimeUrl } from '../../runtime';
 import { createHttpAdapter, type AtlasAdapter, type AtlasChange } from './adapter';
 
 export * from './adapter';
@@ -22,8 +23,16 @@ export function createDevAdapter(base = DEV_PREFIX, label = 'Live from disk', so
   };
 }
 
-/** The dev adapter under `vite dev`, the static adapter everywhere else. */
+/** The server's own files, with its event stream: what a page served by `atlas serve` or `atlas dev` reads. */
+export function createServerAdapter(dataUrl: string, eventsUrl: string | undefined): AtlasAdapter {
+  return { ...createHttpAdapter(dataUrl, 'static', eventsUrl), label: 'Atlas server' };
+}
+
+/** The server's adapter when the page was served by one, the dev adapter under a bare `vite dev`, the static adapter everywhere else. */
 export function createAdapter(): AtlasAdapter {
+  const config = runtimeConfig();
+  const dataUrl = runtimeUrl(config?.dataUrl);
+  if (dataUrl) return createServerAdapter(dataUrl, runtimeUrl(config?.eventsUrl));
   if (import.meta.env.DEV && import.meta.hot) return createDevAdapter();
   return createHttpAdapter(import.meta.env.VITE_ATLAS_BASE_URL ?? './data/');
 }

package/packages/visualizer/src/evidence/api.ts

@@ -1,8 +1,20 @@
 import { evidenceFile } from '@crvouga/atlas/reports/export-evidence';
 
+import { runtimeConfig } from '../runtime';
+
+/**
+ * An Atlas server writes its address book into the page it serves (`atlas serve`, and `atlas dev` through
+ * Vite), so one build of the viewer works for every project. A build can instead be pointed at a reports
+ * API when it is made.
+ */
+const runtime = runtimeConfig;
+
 /** A built site without a reports API reads the evidence exported beside it. */
-export const staticEvidence = !import.meta.env.DEV && !import.meta.env.VITE_ATLAS_REPORTS_URL;
-export const reportsBase = (import.meta.env.VITE_ATLAS_REPORTS_URL as string | undefined)?.replace(/\/$/, '') ?? (staticEvidence ? './data/evidence' : '/api/reports');
+export const staticEvidence = !import.meta.env.DEV && !import.meta.env.VITE_ATLAS_REPORTS_URL && !runtime()?.reportsUrl;
+export const reportsBase = (import.meta.env.VITE_ATLAS_REPORTS_URL as string | undefined)?.replace(/\/$/, '') ?? runtime()?.reportsUrl?.replace(/\/$/, '') ?? (staticEvidence ? './data/evidence' : '/api/reports');
+
+/** Does the server answer `/evidence/effective`: the whole report in one request, without per-layer history? */
+export const effectiveEvidence = () => runtime()?.effective === true;
 
 export class ReportsError extends Error {
   constructor(

package/packages/visualizer/src/evidence/artifacts.module.css

@@ -0,0 +1,213 @@
+.panel {
+  display: grid;
+  gap: 14px;
+  margin: 12px 0;
+}
+
+.panel h4 {
+  margin: 0 0 6px;
+  font-size: 0.78rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--faint);
+}
+
+.chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.chip {
+  display: inline-flex;
+  gap: 4px;
+  padding: 2px 8px;
+  border-radius: var(--pill);
+  background: var(--unrun);
+  color: var(--ink-3);
+  font-size: 0.78rem;
+}
+
+.chip b {
+  font-weight: 600;
+  color: var(--ink-2, inherit);
+}
+
+.links a {
+  font-size: 0.85rem;
+}
+
+.gallery {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  gap: 12px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.figure {
+  display: grid;
+  gap: 4px;
+  margin: 0;
+  min-width: 0;
+}
+
+.figure[data-wide] {
+  grid-column: 1 / -1;
+}
+
+.figure img,
+.figure video {
+  width: 100%;
+  max-height: 420px;
+  object-fit: contain;
+  border: 1px solid var(--line, #dfe3e8);
+  border-radius: 6px;
+  background: #f6f7f9;
+}
+
+.figure iframe {
+  width: 100%;
+  height: 360px;
+  border: 1px solid var(--line, #dfe3e8);
+  border-radius: 6px;
+  background: #fff;
+}
+
+.figure audio {
+  width: 100%;
+}
+
+.figure figcaption {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  align-items: baseline;
+  font-size: 0.8rem;
+  color: var(--ink-3);
+}
+
+.figure figcaption strong {
+  font-weight: 600;
+  overflow-wrap: anywhere;
+}
+
+.role {
+  padding: 0 6px;
+  border-radius: var(--pill);
+  background: var(--unrun);
+  font-size: 0.72rem;
+}
+
+.text {
+  max-height: 260px;
+  margin: 0;
+  padding: 8px 10px;
+  overflow: auto;
+  border: 1px solid var(--line, #dfe3e8);
+  border-radius: 6px;
+  background: #f6f7f9;
+  font: 0.78rem/1.45 ui-monospace, SFMono-Regular, Menlo, monospace;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.timeline,
+.timeline ol {
+  display: grid;
+  gap: 4px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.timeline ol {
+  margin-left: 18px;
+  padding-left: 8px;
+  border-left: 1px solid var(--line, #dfe3e8);
+}
+
+.step {
+  display: grid;
+  gap: 4px;
+}
+
+.stepRow {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  font-size: 0.9rem;
+}
+
+.stepRow .spacer {
+  flex: 1;
+}
+
+.stepKind,
+.stepTime {
+  font-size: 0.75rem;
+  color: var(--faint);
+}
+
+.step[data-status='failed'] > .stepRow .stepName {
+  color: var(--failed);
+}
+
+.stepDetail {
+  margin: 0 0 0 24px;
+  font-size: 0.82rem;
+  color: var(--ink-3);
+  white-space: pre-wrap;
+}
+
+.notes {
+  display: grid;
+  gap: 6px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.note {
+  display: flex;
+  gap: 8px;
+  align-items: baseline;
+  font-size: 0.88rem;
+}
+
+.level {
+  flex: none;
+  padding: 0 7px;
+  border-radius: var(--pill);
+  background: var(--unrun);
+  color: var(--ink-3);
+  font-size: 0.72rem;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.level[data-level='warning'] {
+  background: #fff4d6;
+  color: #7a5200;
+}
+
+.level[data-level='error'] {
+  background: #fde4e4;
+  color: var(--failed);
+}
+
+.where {
+  color: var(--faint);
+  font-size: 0.78rem;
+}
+
+.raw summary {
+  cursor: pointer;
+  font-size: 0.82rem;
+  color: var(--ink-3);
+}