@crvouga/atlas 0.0.0-stage → 0.2.0

package/packages/visualizer/src/reachable.test.ts

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { expect, it } from 'bun:test';
+
+const SRC = path.dirname(fileURLToPath(import.meta.url));
+const ENTRY = path.join(SRC, 'main.tsx');
+const SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(?\s*|@import\s+(?:url\(\s*)?|\burl\(\s*)['"]([^'"]+)['"]/g;
+const SUFFIXES = ['', '.ts', '.tsx', '.css', '/index.ts', '/index.tsx'];
+
+function filesUnder(dir: string): string[] {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const file = path.join(dir, entry.name);
+    return entry.isDirectory() ? filesUnder(file) : [file];
+  });
+}
+
+function resolve(from: string, specifier: string): string | null {
+  if (!specifier.startsWith('.')) return null;
+  const base = path.resolve(path.dirname(from), specifier.split('?')[0]!);
+  for (const suffix of SUFFIXES) if (fs.statSync(base + suffix, { throwIfNoEntry: false })?.isFile()) return base + suffix;
+  return null;
+}
+
+function reachableFrom(entry: string): Set<string> {
+  const seen = new Set<string>();
+  const queue = [entry];
+  for (let file = queue.pop(); file; file = queue.pop()) {
+    if (seen.has(file)) continue;
+    seen.add(file);
+    if (!/\.(tsx?|css)$/.test(file)) continue;
+    for (const match of fs.readFileSync(file, 'utf8').matchAll(SPECIFIER)) {
+      const next = resolve(file, match[1]!);
+      if (next) queue.push(next);
+    }
+  }
+  return seen;
+}
+
+/** Test support and license texts are never part of the page. */
+function isExempt(file: string): boolean {
+  return /\.test\.tsx?$/.test(file) || /\.d\.ts$/.test(file) || /\.(txt|md)$/.test(file) || file.split(path.sep).includes('testing');
+}
+
+it('every module of the viewer is part of the page it serves', () => {
+  // regression: atlas-explorer-old-shell
+  // A merge that keeps one side's shell leaves the other side's interface in the tree, unused and unseen.
+  const reachable = reachableFrom(ENTRY);
+  const unused = filesUnder(SRC)
+    .filter((file) => !isExempt(file) && !reachable.has(file))
+    .map((file) => path.relative(SRC, file).split(path.sep).join('/'))
+    .sort();
+  expect(unused).toEqual([]);
+});

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

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'bun:test';
+
+import { fileName, folderOf, kindOfFile, outlinePath, specFile, specKind } from './spec-kind';
+
+describe('spec kinds', () => {
+  it('gives each notation its own tab and leaves statecharts and notes to the map', () => {
+    expect(kindOfFile('auth/sign-in.feature')?.id).toBe('gherkin');
+    expect(kindOfFile('spaces/hosting.qnt')?.id).toBe('quint');
+    expect(kindOfFile('billing/access.dmn')?.id).toBe('dmn');
+    expect(kindOfFile('room/seats.als')?.id).toBe('alloy');
+    expect(kindOfFile('health/api.openslo.yaml')?.id).toBe('openslo');
+    expect(kindOfFile('product.machine.yaml')).toBeNull();
+    expect(kindOfFile('journeys.yaml')).toBeNull();
+    expect(kindOfFile('known-issues.md')).toBeNull();
+    expect(specKind('quint')?.many).toBe('models');
+    expect(specKind('unknown')).toBeNull();
+  });
+
+  it('names a spec the way reports do, whichever form it starts from', () => {
+    expect(outlinePath('auth/sign-in.feature')).toBe('specs/auth/sign-in.feature');
+    expect(outlinePath('specs/auth/sign-in.feature')).toBe('specs/auth/sign-in.feature');
+    expect(specFile('specs/auth/sign-in.feature')).toBe('auth/sign-in.feature');
+    expect(fileName('auth/sign-in.feature')).toBe('sign-in.feature');
+    expect(folderOf('auth/sign-in.feature')).toBe('auth');
+    expect(folderOf('atlas.yaml')).toBe('');
+  });
+});

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

@@ -0,0 +1,56 @@
+/** A kind of spec document with its own tab: what it is called, and which files belong to it. */
+export type SpecKind = {
+  readonly id: string;
+  /** The tab, named after the notation. */
+  readonly label: string;
+  readonly one: string;
+  readonly many: string;
+  /** What one recorded check of this kind is called. */
+  readonly check: string;
+  readonly accepts: (path: string) => boolean;
+};
+
+function ending(pattern: RegExp) {
+  return (path: string) => pattern.test(path.split('?')[0] ?? '');
+}
+
+/** Statecharts are the map; every other notation is a document tab from this list. */
+export const SPEC_KINDS: readonly SpecKind[] = [
+  { id: 'gherkin', label: 'Gherkin', one: 'feature', many: 'features', check: 'scenario', accepts: ending(/\.feature$/i) },
+  { id: 'quint', label: 'Quint', one: 'model', many: 'models', check: 'trace', accepts: ending(/\.qnt$/i) },
+  { id: 'dmn', label: 'DMN', one: 'decision table', many: 'decision tables', check: 'check', accepts: ending(/\.dmn$/i) },
+  { id: 'alloy', label: 'Alloy', one: 'structure', many: 'structures', check: 'check', accepts: ending(/\.als$/i) },
+  { id: 'openslo', label: 'OpenSLO', one: 'objective', many: 'objectives', check: 'check', accepts: ending(/\.openslo\.ya?ml$/i) },
+];
+
+export function specKind(id: string | undefined): SpecKind | null {
+  return SPEC_KINDS.find((kind) => kind.id === id) ?? null;
+}
+
+/** The spec tab an address is in, or null on the statechart map. */
+export function kindOfAddress(pathname: string): SpecKind | null {
+  return pathname.startsWith('/specs/') ? specKind(pathname.split('/')[2]) : null;
+}
+
+export function kindOfFile(path: string): SpecKind | null {
+  return SPEC_KINDS.find((kind) => kind.accepts(path)) ?? null;
+}
+
+/** The path a report names a spec by, from a file path relative to the specs folder. */
+export function outlinePath(file: string) {
+  const normal = file.replaceAll('\\', '/');
+  return normal.startsWith('specs/') ? normal : `specs/${normal}`;
+}
+
+/** A file path relative to the specs folder, from either form. */
+export function specFile(path: string) {
+  return path.replaceAll('\\', '/').replace(/^specs\//, '');
+}
+
+export function fileName(path: string) {
+  return path.split('/').at(-1) ?? path;
+}
+
+export function folderOf(path: string) {
+  return path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '';
+}

package/packages/visualizer/src/state/ui-store.ts

@@ -0,0 +1,44 @@
+import { ALL_SOURCES, type SourceSelection } from '@crvouga/atlas/reports/evidence-view';
+import type { Viewport } from '@xyflow/react';
+import { create } from 'zustand';
+import { createJSONStorage, persist } from 'zustand/middleware';
+
+/** Which specs the index lists, by what has been recorded for them. */
+export type ResultFilter = 'all' | 'results' | 'failed' | 'none';
+
+type UiState = {
+  viewports: Record<string, Viewport>;
+  issuesOpen: boolean;
+  sourcesOpen: boolean;
+  resultFilter: ResultFilter;
+  /** Backends, branches and layers left out of the combined report. */
+  excluded: SourceSelection;
+  saveViewport: (chartId: string, viewport: Viewport) => void;
+  setIssuesOpen: (open: boolean) => void;
+  setSourcesOpen: (open: boolean) => void;
+  setResultFilter: (filter: ResultFilter) => void;
+  setExcluded: (excluded: SourceSelection) => void;
+};
+
+/** UI state that outlives a data refresh: zoom and pan per chart, the chosen sources, and open panels. */
+export const useUiStore = create<UiState>()(
+  persist(
+    (set) => ({
+      viewports: {},
+      issuesOpen: false,
+      sourcesOpen: false,
+      resultFilter: 'all',
+      excluded: ALL_SOURCES,
+      saveViewport: (chartId, viewport) => set((s) => ({ viewports: { ...s.viewports, [chartId]: viewport } })),
+      setIssuesOpen: (issuesOpen) => set({ issuesOpen }),
+      setSourcesOpen: (sourcesOpen) => set({ sourcesOpen }),
+      setResultFilter: (resultFilter) => set({ resultFilter }),
+      setExcluded: (excluded) => set({ excluded })
+    }),
+    {
+      name: 'atlas-ui',
+      storage: createJSONStorage(() => sessionStorage),
+      partialize: (s) => ({ viewports: s.viewports, excluded: s.excluded, resultFilter: s.resultFilter })
+    }
+  )
+);

package/packages/visualizer/src/styles/global.css

@@ -0,0 +1,105 @@
+@import './tokens.css';
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  height: 100%;
+}
+
+@media (max-width: 760px) {
+  html,
+  body,
+  #root {
+    height: auto;
+    min-height: 100%;
+  }
+}
+
+body {
+  margin: 0;
+  font-family: var(--font);
+  color: var(--ink);
+  background: var(--bg);
+  font-size: 0.9375rem;
+  line-height: 1.45;
+  -webkit-font-smoothing: antialiased;
+}
+
+a {
+  color: var(--place);
+}
+
+::selection {
+  background: var(--place-soft);
+}
+
+input,
+textarea {
+  caret-color: var(--place);
+}
+
+button,
+input,
+select {
+  font: inherit;
+  color: inherit;
+}
+
+:focus-visible {
+  outline: 2px solid var(--focus);
+  outline-offset: 2px;
+  border-radius: 0.375rem;
+}
+
+code,
+pre {
+  font-family: var(--mono);
+  font-size: 0.8rem;
+}
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.react-flow__attribution {
+  font-size: 9px;
+  opacity: 0.6;
+  background: transparent;
+}
+
+.react-flow__node:focus-visible {
+  outline: none;
+}
+
+.react-flow__node:focus-visible > * {
+  outline: 3px solid var(--focus);
+  outline-offset: 3px;
+}
+
+.react-flow__minimap {
+  border-radius: var(--radius);
+  border: 1px solid var(--line);
+  overflow: hidden;
+  box-shadow: var(--shadow-card);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    transition: none !important;
+    animation: none !important;
+  }
+}

package/packages/visualizer/src/styles/tokens.css

@@ -0,0 +1,80 @@
+:root {
+  /* Neutral surfaces and text. One blue marks what is chosen or can be followed. */
+  --ink: #0f1419;
+  --ink-2: #2f3336;
+  --ink-3: #536471;
+  --muted: #536471;
+  --faint: #8b98a5;
+  --line: #eff3f4;
+  --line-2: #cfd9de;
+  --bg: #ffffff;
+  --bg-2: #f7f9f9;
+  --card: #ffffff;
+  --place: #0b63ce;
+  --place-soft: #e8f1fd;
+
+  /* Who caused an event on the map. The person is the accent; everything else is gray. */
+  --user: #0b63ce;
+  --user-ink: #0a4fa6;
+  --user-soft: #e8f1fd;
+  --user-line: #b9d4f7;
+  --user-deep: #0a4fa6;
+  --user-ring: #d3e4fb;
+
+  --system: #536471;
+  --system-ink: #2f3336;
+  --system-soft: #f7f9f9;
+  --system-line: #cfd9de;
+  --system-wash: rgba(247, 249, 249, 0.97);
+
+  --time: #536471;
+  --time-ink: #2f3336;
+  --time-soft: #eff3f4;
+  --time-line: #cfd9de;
+
+  --handoff: #2f3336;
+  --handoff-ink: #0f1419;
+  --handoff-soft: #eff3f4;
+  --handoff-line: #cfd9de;
+
+  --passed: #1a7f37;
+  --passed-ink: #116329;
+  --passed-soft: #e6f4ea;
+  --passed-line: #b4dcc0;
+  --failed: #cf222e;
+  --failed-ink: #a40e26;
+  --failed-soft: #ffebe9;
+  --failed-line: #f7b9b5;
+  --flaky: #9a6700;
+  --flaky-ink: #7d4e00;
+  --flaky-soft: #fff8c5;
+  --not-reached: #cfd9de;
+  --unrun: #eff3f4;
+
+  --radius-sm: 0.5rem;
+  --radius: 0.75rem;
+  --radius-lg: 1rem;
+  --radius-xl: 1.25rem;
+  --pill: 999px;
+
+  --shadow-card: 0 1px 2px rgba(15, 20, 25, 0.06);
+  --shadow-raised: 0 2px 8px rgba(15, 20, 25, 0.06);
+  --shadow-sheet: 0 0 0 1px var(--line);
+  --shadow-pop: 0 8px 28px rgba(15, 20, 25, 0.14);
+  --focus: #0b63ce;
+
+  --font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+
+  --header-h: 3.25rem;
+  --index-w: 20rem;
+  --panel-w: min(30rem, 40vw);
+  --ease: cubic-bezier(0.2, 0.7, 0.2, 1);
+  --fade: 160ms;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --fade: 0ms;
+  }
+}

package/packages/visualizer/src/views/ChartPage.tsx

@@ -0,0 +1,52 @@
+import { Link, useParams, useSearch } from '@tanstack/react-router';
+
+import { useAtlas } from '../app/atlas-context';
+import { mapFrame } from '../layout/graph';
+import { ChartMap } from '../map/ChartMap';
+import { SidePanel } from './SidePanel';
+import styles from './views.module.css';
+
+export function ChartPage() {
+  const { chartId } = useParams({ from: '/chart/$chartId' });
+  const search = useSearch({ from: '/chart/$chartId' });
+  const { view } = useAtlas();
+  if (!view) return <div className={styles.plateScroll} role="status">Loading the spec…</div>;
+  if (!view.charts.has(chartId)) {
+    return (
+      <div className={styles.plateScroll}>
+        <h1 className={styles.plateTitle}>This chart isn’t in the spec</h1>
+        <p className={styles.lead}>It may have been renamed or removed since this link was shared.</p>
+        <Link to="/" search={(prev) => ({ run: prev.run })} className={styles.button}>
+          Back to the product map
+        </Link>
+      </div>
+    );
+  }
+  const selection = { screen: search.screen, event: search.event, journey: search.journey };
+  const open = Boolean(search.screen || search.event || search.journey);
+  if (open) return <SidePanel view={view} chartId={chartId} selection={selection} />;
+  const chart = view.charts.get(chartId)!;
+  const frame = mapFrame(view, chartId, search.group ?? null);
+  const homeFocus = mapFrame(view, chartId, null).focus;
+  return (
+    <div className={styles.mapPlate}>
+      <div className={styles.mapHeading}>
+        <h1>{chart.name}</h1>
+        {chart.description && <p>{chart.description}</p>}
+        {frame.focus && (
+          <p className={styles.mapScope}>
+            <span>{frame.focus}</span>
+            {frame.wider && (
+              <Link to="/chart/$chartId" params={{ chartId }} search={(prev) => ({ run: prev.run, group: frame.wider && frame.wider !== homeFocus ? frame.wider : undefined })}>
+                Wider map
+              </Link>
+            )}
+          </p>
+        )}
+      </div>
+      <div className={styles.mapArea}>
+        <ChartMap key={`${chartId}:${search.group ?? ''}`} view={view} chartId={chartId} selection={selection} group={search.group} />
+      </div>
+    </div>
+  );
+}

package/packages/visualizer/src/views/ProductPage.tsx

@@ -0,0 +1,35 @@
+import { Navigate, useSearch } from '@tanstack/react-router';
+
+import { useAtlas } from '../app/atlas-context';
+import type { AtlasView } from '../data/model';
+import styles from './views.module.css';
+
+function openingPlace(view: AtlasView) {
+  const screens = [...view.states.values()].filter((state) => state.kind === 'screen' || state.kind === 'final');
+  const withFailedEvent = screens.find((state) => state.outgoing.some((id) => view.transitions.get(id)?.status === 'failed'));
+  return withFailedEvent ?? screens.find((state) => state.status === 'failed') ?? screens[0] ?? null;
+}
+
+export function ProductPage() {
+  const { view } = useAtlas();
+  const search = useSearch({ strict: false });
+  const run = typeof search.run === 'string' ? search.run : undefined;
+  if (!view) return <div className={styles.plateScroll} role="status">Loading the spec…</div>;
+  const place = openingPlace(view);
+  if (!place) {
+    return (
+      <article className={styles.plateScroll}>
+        <h1 className={styles.plateTitle}>{view.title}</h1>
+        <p className={styles.lead}>This spec has no screens yet.</p>
+      </article>
+    );
+  }
+  return (
+    <Navigate
+      to="/chart/$chartId"
+      params={{ chartId: place.chartId }}
+      search={{ ...(run ? { run } : {}), screen: place.name }}
+      replace
+    />
+  );
+}