@crvouga/atlas 0.0.0-stage → 0.2.0

package/packages/visualizer/src/data/model/types.ts

@@ -0,0 +1,280 @@
+import type {
+  BusinessEvents,
+  BusinessContract,
+  CheckResult,
+  Confidence,
+  DataIssue,
+  DesignLink,
+  EventKind,
+  LayoutFile,
+  RunInfo,
+  RunStatus,
+  RunSummary,
+  StateType,
+  TimelineEntry
+} from '@crvouga/atlas/schema';
+import type { ChartSimulation } from './simulation';
+
+export const ITEM_STATUSES = ['passed', 'flaky', 'failed', 'not-reached', 'not-yet-run', 'spec-only'] as const;
+export type ItemStatus = (typeof ITEM_STATUSES)[number];
+
+export type StatusCounts = Record<ItemStatus, number> & { total: number };
+
+/** Where an item stands against a second spec version laid over this one. Always `same` today. */
+export type SpecChange = 'same' | 'added' | 'removed' | 'changed';
+
+export type MediaState = 'available' | 'missing' | 'processing';
+
+export type ImageMedia = { state: MediaState; thumb: string | null; full: string | null };
+
+export type VideoMedia = {
+  state: MediaState;
+  src: string | null;
+  poster: string | null;
+  durationMs: number | null;
+  captions: string | null;
+};
+
+export type StateKind = 'screen' | 'final' | 'group' | 'parallel' | 'region' | 'chart-link';
+
+export type QuestionView = {
+  id: string;
+  number: number;
+  section: string;
+  title: string;
+  body: string;
+  specToday: string | null;
+  file: string;
+  states: string[];
+  transitions: string[];
+};
+
+export type NoteView = { title: string; body: string; file: string };
+
+export type PathRef = { id: string; name: string };
+
+export type StateResult = {
+  runId: string;
+  status: RunStatus;
+  screenshot: ImageMedia;
+  screenshotsByPath: { path: PathRef; image: ImageMedia }[];
+  checks: CheckResult[];
+  /** Expected, observed and missing business events, with the CloudEvents seen when the run had a source. */
+  businessEvents: BusinessEvents | null;
+  reachedBy: PathRef[];
+  notes: string[];
+  looksLike: string[];
+  recognizer: { matched: boolean; signals: { signal: string; expected: string; visible: boolean }[] } | null;
+  /** Seeds that start paths with this screen showing. */
+  seeds: string[];
+};
+
+export type StateView = {
+  key: string;
+  name: string;
+  chartId: string;
+  contextId: string;
+  file: string;
+  parent: string | null;
+  children: string[];
+  depth: number;
+  type: StateType;
+  kind: StateKind;
+  initial: string | null;
+  description: string;
+  snapshot: string | null;
+  confidence: Confidence | null;
+  sources: string[];
+  owner: string | null;
+  tier: string | null;
+  quint: string | null;
+  gherkin: string[];
+  contracts: BusinessContract[];
+  design: DesignLink | null;
+  hints: string[];
+  specChecks: string[];
+  specBusinessEvents: string[];
+  deadEnd: string | null;
+  childChartId: string | null;
+  incoming: string[];
+  outgoing: string[];
+  questionIds: string[];
+  knownIssues: NoteView[];
+  status: ItemStatus;
+  result: StateResult | null;
+  change: SpecChange;
+};
+
+export type EventKindSource = 'spec' | 'structure' | 'run' | 'guess';
+
+export type TransitionResult = {
+  runId: string;
+  status: RunStatus;
+  how: string | null;
+  reason: string | null;
+  clip: VideoMedia;
+  timeline: TimelineEntry[];
+  reachedBy: PathRef[];
+};
+
+export type TransitionView = {
+  id: string;
+  chartId: string;
+  source: string;
+  target: string | null;
+  event: string;
+  kind: EventKind;
+  kindSource: EventKindSource;
+  timeSpan: string | null;
+  handOff: boolean;
+  carriedBy: string | null;
+  questionIds: string[];
+  knownIssues: NoteView[];
+  status: ItemStatus;
+  result: TransitionResult | null;
+  change: SpecChange;
+};
+
+export type JourneyStep = {
+  index: number;
+  event: string;
+  transitionIds: string[];
+  handOff: boolean;
+  from: string[];
+  to: string[];
+};
+
+export type JourneyRunPath = {
+  id: string;
+  name: string;
+  /** The seed the stretch started from; null when it started at the beginning. */
+  seed: string | null;
+  status: RunStatus;
+  progress: 'queued' | 'running' | 'complete';
+  stoppedAt: string | null;
+  error: string | null;
+  steps: { transition: string | null; event: string; status: RunStatus | null; reason: string | null }[];
+};
+
+export type JourneyView = {
+  id: string;
+  name: string;
+  description: string;
+  file: string;
+  chartIds: string[];
+  owner: string | null;
+  tour: boolean;
+  events: string[];
+  endsIn: string[];
+  steps: JourneyStep[];
+  replay: { ok: boolean; failedAt: string | null; missingEnds: string[] };
+  status: ItemStatus;
+  runPaths: JourneyRunPath[];
+};
+
+export type ChartView = {
+  id: string;
+  name: string;
+  file: string;
+  dir: string;
+  contextId: string;
+  description: string;
+  contracts: BusinessContract[];
+  parent: { chartId: string; state: string } | null;
+  childChartIds: string[];
+  initial: string | null;
+  rootStates: string[];
+  states: string[];
+  transitions: string[];
+  journeyIds: string[];
+  layout: LayoutFile | null;
+  screens: StatusCounts;
+  events: StatusCounts;
+  /** Changes only when states, nesting or transitions change, never when results do. */
+  structureKey: string;
+};
+
+export type ContextView = {
+  id: string;
+  name: string;
+  description: string;
+  owner: string | null;
+  chartIds: string[];
+  topChartIds: string[];
+  screens: StatusCounts;
+  events: StatusCounts;
+  journeys: StatusCounts;
+};
+
+export type HandOffView = {
+  from: string;
+  to: string;
+  event: string;
+  description: string;
+  fromContext: string;
+  toContext: string;
+  fromState: string | null;
+  toState: string | null;
+};
+
+export type RunReport = { label: string; url: string };
+
+export type RunView = {
+  id: string;
+  info: RunInfo;
+  progress: 'running' | 'complete';
+  privacyPassed: boolean | null;
+  outOfDate: boolean;
+  /** Links to the other formats the run wrote: JUnit, CTRF, Mermaid. */
+  reports: RunReport[];
+  paths: {
+    id: string;
+    name: string;
+    kind: 'journey' | 'generated';
+    status: ItemStatus;
+    progress: 'queued' | 'running' | 'complete';
+    steps: number;
+    seed: string | null;
+    durationMs: number | null;
+    error: string | null;
+    stoppedAt: string | null;
+    traces: RunReport[];
+  }[];
+};
+
+export type RemovedState = {
+  name: string;
+  chartId: string | null;
+  status: RunStatus;
+  screenshot: ImageMedia;
+  description: string;
+};
+
+export type RemovedTransition = {
+  id: string;
+  source: string;
+  event: string;
+  target: string | null;
+  status: RunStatus;
+};
+
+export type AtlasView = {
+  simulation: (chartId: string) => ChartSimulation;
+  title: string;
+  description: string;
+  ref: string | null;
+  mode: 'spec-only' | 'run';
+  contexts: ContextView[];
+  charts: Map<string, ChartView>;
+  states: Map<string, StateView>;
+  transitions: Map<string, TransitionView>;
+  journeys: JourneyView[];
+  questions: Map<string, QuestionView>;
+  excluded: string[];
+  handOffs: HandOffView[];
+  run: RunView | null;
+  runs: RunSummary[];
+  removed: { states: RemovedState[]; transitions: RemovedTransition[] };
+  totals: { screens: StatusCounts; events: StatusCounts; journeys: StatusCounts };
+  issues: DataIssue[];
+};

package/packages/visualizer/src/data/parse/issues.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'bun:test';
+import { z } from 'zod/v4';
+
+import { createIssueSink, formatPath, parseFields, parseOne, plainZodMessage } from './issues';
+
+describe('plainZodMessage', () => {
+  it.each<[string, z.ZodType, unknown, string]>([
+    ['a missing field', z.object({ name: z.string() }), {}, '"name" is missing.'],
+    ['text where a number belongs', z.object({ count: z.number() }), { count: 'many' }, '"count" should be a number, but is text.'],
+    ['a number where text belongs', z.object({ name: z.string() }), { name: 3 }, '"name" should be text, but is a number.'],
+    ['text where a list belongs', z.array(z.string()), 'abc', 'should be a list, but is text.'],
+    ['a list where fields belong', z.object({ a: z.string() }), ['x'], 'should be a group of fields, but is a list.'],
+    ['a nested yes-or-no', z.object({ a: z.object({ on: z.boolean() }) }), { a: { on: 'yes' } }, '"a › on" should be yes or no, but is text.'],
+    ['null where text belongs', z.object({ name: z.string() }), { name: null }, '"name" should be text, but is empty.'],
+    ['a value outside a list of choices', z.enum(['confirmed', 'assumed']), 'maybe', 'should be one of "confirmed", "assumed", but is "maybe".'],
+    ['empty text', z.string().min(1), '', 'is empty.'],
+    ['an unknown shape', z.union([z.string(), z.object({ target: z.string() })]), 5, 'is not in a shape this app understands.']
+  ])('explains %s', (_label, schema, value, expected) => {
+    const result = schema.safeParse(value);
+    expect(result.success).toBe(false);
+    expect(plainZodMessage(result.error!, value)).toBe(expected);
+  });
+
+  it('falls back to the schema message for other problems', () => {
+    const value = 5;
+    const result = z.number().max(3).safeParse(value);
+    expect(plainZodMessage(result.error!, value)).toMatch(/3/);
+  });
+});
+
+describe('formatPath', () => {
+  it.each<[(string | number)[], string]>([
+    [[], ''],
+    [['states', 'Drink ready'], 'states › Drink ready'],
+    [['paths', 0, 'steps', 2], 'paths › item 1 › steps › item 3']
+  ])('formats %j as %j', (path, expected) => {
+    expect(formatPath(path)).toBe(expected);
+  });
+});
+
+describe('parseFields', () => {
+  const shape = { name: z.string(), count: z.number(), tags: z.array(z.string()) };
+
+  it.each<[string, unknown, Record<string, unknown>, { path: string; message: string }[]]>([
+    ['all valid', { name: 'x', count: 2, tags: ['a'] }, { name: 'x', count: 2, tags: ['a'] }, []],
+    ['one invalid field', { name: 'x', count: 'many', tags: ['a'] }, { name: 'x', tags: ['a'] }, [{ path: 'meta › count', message: 'should be a number, but is text.' }]],
+    [
+      'two invalid fields',
+      { name: 1, count: 2, tags: 'a' },
+      { count: 2 },
+      [
+        { path: 'meta › name', message: 'should be text, but is a number.' },
+        { path: 'meta › tags', message: 'should be a list, but is text.' }
+      ]
+    ],
+    ['unknown fields', { name: 'x', colour: 'red', future: { a: 1 } }, { name: 'x' }, []],
+    ['missing fields', { count: 1 }, { count: 1 }, []],
+    ['nothing at all', undefined, {}, []],
+    ['null', null, {}, []],
+    ['a list instead of fields', ['x'], {}, [{ path: 'meta', message: 'should be a group of fields, but is a list.' }]]
+  ])('keeps valid fields and reports invalid ones: %s', (_label, raw, expected, issues) => {
+    const sink = createIssueSink();
+    expect(parseFields(shape, raw, sink, 'machine.yaml', ['meta'])).toEqual(expected);
+    expect(sink.issues.map(({ path, message }) => ({ path, message }))).toEqual(issues);
+    expect(sink.issues.every((i) => i.file === 'machine.yaml' && i.severity === 'warning')).toBe(true);
+  });
+
+  it('reports at the severity asked for', () => {
+    const sink = createIssueSink();
+    parseFields(shape, { count: 'x' }, sink, 'f', [], 'error');
+    expect(sink.issues[0]).toMatchObject({ severity: 'error', path: 'count' });
+  });
+});
+
+describe('parseOne', () => {
+  it('returns the value or null and an issue, never throwing', () => {
+    const sink = createIssueSink();
+    expect(parseOne(z.object({ a: z.string() }), { a: 'x' }, sink, 'f', [])).toEqual({ a: 'x' });
+    expect(parseOne(z.object({ a: z.string() }), { a: 1 }, sink, 'f', ['root'])).toBeNull();
+    expect(sink.issues).toEqual([{ severity: 'warning', file: 'f', path: 'root', message: '"a" should be text, but is a number.' }]);
+  });
+});

package/packages/visualizer/src/data/parse/issues.ts

@@ -0,0 +1,114 @@
+import type { DataIssue, IssueSeverity } from '@crvouga/atlas/schema';
+import type { z } from 'zod/v4';
+
+export type IssueSink = {
+  add: (severity: IssueSeverity, file: string, path: readonly (string | number)[], message: string) => void;
+};
+
+export function createIssueSink(into: DataIssue[] = []) {
+  const sink: IssueSink & { issues: DataIssue[] } = {
+    issues: into,
+    add: (severity, file, path, message) => {
+      into.push({ severity, file, path: formatPath(path), message });
+    }
+  };
+  return sink;
+}
+
+export function formatPath(path: readonly (string | number)[]) {
+  return path.map((part) => (typeof part === 'number' ? `item ${part + 1}` : part)).join(' › ');
+}
+
+function describeValue(value: unknown) {
+  if (value === null) return 'empty';
+  if (value === undefined) return 'missing';
+  if (Array.isArray(value)) return 'a list';
+  if (typeof value === 'object') return 'a group of fields';
+  if (typeof value === 'string') return value.trim() ? 'text' : 'empty text';
+  return `a ${typeof value}`;
+}
+
+const EXPECTED_WORDS: Record<string, string> = {
+  string: 'text',
+  number: 'a number',
+  int: 'a whole number',
+  boolean: 'yes or no',
+  array: 'a list',
+  object: 'a group of fields',
+  record: 'a group of fields',
+  null: 'empty'
+};
+
+/** One sentence a non-engineer can read, for the first problem Zod found. */
+export function plainZodMessage(error: z.ZodError, value: unknown) {
+  const first = error.issues[0];
+  if (!first) return 'This value could not be read.';
+  const where = first.path.length ? `"${first.path.join(' › ')}" ` : '';
+  const actual = first.path.reduce<unknown>(
+    (v, key) => (v && typeof v === 'object' ? (v as Record<PropertyKey, unknown>)[key] : undefined),
+    value
+  );
+  switch (first.code) {
+    case 'invalid_type':
+      return actual === undefined
+        ? `${where || 'A required value '}is missing.`
+        : `${where}should be ${EXPECTED_WORDS[first.expected] ?? first.expected}, but is ${describeValue(actual)}.`;
+    case 'invalid_value':
+      return `${where}should be one of ${first.values.map((v) => `"${String(v)}"`).join(', ')}, but is "${String(actual)}".`;
+    case 'too_small':
+      return `${where}is empty.`;
+    case 'invalid_union':
+      return `${where}is not in a shape this app understands.`;
+    default:
+      return `${where}${first.message}`;
+  }
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Validate an object one field at a time: keep the fields that parse, report the ones that don't,
+ * and ignore fields the shape doesn't know, so newer data never breaks an older build.
+ */
+export function parseFields<Shape extends Record<string, z.ZodType>>(
+  shape: Shape,
+  raw: unknown,
+  sink: IssueSink,
+  file: string,
+  path: readonly (string | number)[],
+  severity: 'warning' | 'error' = 'warning'
+) {
+  const out: Partial<{ [K in keyof Shape]: z.infer<Shape[K]> }> = {};
+  if (raw === undefined || raw === null) return out;
+  if (!isRecord(raw)) {
+    sink.add(severity, file, path, `should be a group of fields, but is ${describeValue(raw)}.`);
+    return out;
+  }
+  for (const key of Object.keys(shape) as (keyof Shape & string)[]) {
+    if (!(key in raw) || raw[key] === undefined) continue;
+    const result = shape[key]!.safeParse(raw[key]);
+    if (result.success) {
+      out[key] = result.data as z.infer<Shape[typeof key]>;
+    } else {
+      sink.add(severity, file, [...path, key], plainZodMessage(result.error, raw[key]).replace(/^"" /, ''));
+    }
+  }
+  return out;
+}
+
+/** Parse a value with a schema, reporting and returning null instead of throwing. */
+export function parseOne<T>(
+  schema: z.ZodType<T>,
+  raw: unknown,
+  sink: IssueSink,
+  file: string,
+  path: readonly (string | number)[],
+  severity: IssueSeverity = 'warning'
+): T | null {
+  const result = schema.safeParse(raw);
+  if (result.success) return result.data;
+  sink.add(severity, file, path, plainZodMessage(result.error, raw));
+  return null;
+}

package/packages/visualizer/src/data/parse/manifest.ts

@@ -0,0 +1,173 @@
+import {
+  LATEST_MANIFEST_SCHEMA_VERSION,
+  JourneyRecordSchema,
+  ManifestChartSchema,
+  MapEdgeSchema,
+  PathRecordSchema,
+  PathStepSchema,
+  PrivacySchema,
+  ReportsSchema,
+  RunInfoSchema,
+  RunSummarySchema,
+  RunsIndexSchema,
+  SeedRecordSchema,
+  StateRecordSchema,
+  TimelineEntrySchema,
+  TransitionRecordSchema,
+  transitionId,
+  type EventKind,
+  type JourneyRecord,
+  type PathRecord,
+  type SeedRecord,
+  type RunInfo,
+  type RunSummary,
+  type StateRecord,
+  type TimelineEntry,
+  type TransitionRecord
+} from '@crvouga/atlas/schema';
+import type { z } from 'zod/v4';
+
+import { createIssueSink, isRecord, parseFields, parseOne, type IssueSink } from './issues';
+
+export type ParsedTransitionRecord = Omit<TransitionRecord, 'timeline'> & { id: string; timeline: TimelineEntry[] };
+
+export type ParsedPath = Omit<PathRecord, 'steps'> & { steps: z.infer<typeof PathStepSchema>[] };
+
+export type ParsedRun = {
+  id: string;
+  file: string;
+  schemaVersion: number;
+  info: RunInfo;
+  charts: z.infer<typeof ManifestChartSchema>[];
+  states: Map<string, StateRecord>;
+  transitions: Map<string, ParsedTransitionRecord>;
+  paths: ParsedPath[];
+  /** Journeys as the run composed them from their seeded stretches. */
+  journeys: JourneyRecord[];
+  seeds: SeedRecord[];
+  mapKinds: Map<string, EventKind>;
+  privacy: z.infer<typeof PrivacySchema> | null;
+  /** Other formats the run wrote beside its manifest: JUnit XML, CTRF JSON, a Mermaid diagram. */
+  reports: z.infer<typeof ReportsSchema> | null;
+};
+
+function startedAtFromId(id: string) {
+  const m = id.match(/^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z/);
+  return m ? `${m[1]}T${m[2]}:${m[3]}:${m[4]}.${m[5]}Z` : new Date(0).toISOString();
+}
+
+function parseTimeline(raw: unknown, sink: IssueSink, file: string, path: (string | number)[]) {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) {
+    sink.add('warning', file, path, 'should be a list of steps.');
+    return [];
+  }
+  const entries: TimelineEntry[] = [];
+  raw.forEach((entry, i) => {
+    if (isRecord(entry) && typeof entry.kind === 'string' && !TimelineEntrySchema.shape.kind.options.includes(entry.kind as TimelineEntry['kind'])) {
+      sink.add('info', file, [...path, i, 'kind'], `"${entry.kind}" is a step type this app doesn't know yet; it is shown as a note.`);
+      entry = { ...entry, kind: 'note' };
+    }
+    const parsed = parseOne(TimelineEntrySchema, entry, sink, file, [...path, i]);
+    if (parsed) entries.push(parsed);
+  });
+  return entries.sort((a, b) => a.atMs - b.atMs);
+}
+
+/**
+ * One run's manifest, record by record. A broken state, transition or path is reported and
+ * dropped; the rest of the run still shows. Unknown fields are ignored.
+ */
+export function parseManifest(runId: string, file: string, raw: unknown, sink: IssueSink = createIssueSink()): ParsedRun | null {
+  if (!isRecord(raw)) {
+    sink.add('error', file, [], 'This run file is empty or not in a shape this app understands, so the run is skipped.');
+    return null;
+  }
+  let schemaVersion = typeof raw.schemaVersion === 'number' ? raw.schemaVersion : 0;
+  if (!schemaVersion) {
+    sink.add('warning', file, ['schemaVersion'], `The run doesn't say which format it uses; it is read as format ${LATEST_MANIFEST_SCHEMA_VERSION}.`);
+    schemaVersion = LATEST_MANIFEST_SCHEMA_VERSION;
+  } else if (schemaVersion > LATEST_MANIFEST_SCHEMA_VERSION) {
+    sink.add('info', file, ['schemaVersion'], `This run uses a newer format (${schemaVersion}) than this app knows (${LATEST_MANIFEST_SCHEMA_VERSION}). The parts it recognizes are shown.`);
+  }
+
+  let info = RunInfoSchema.safeParse(raw.run).success ? RunInfoSchema.parse(raw.run) : null;
+  if (!info) {
+    if (raw.run === undefined || raw.run === null) {
+      sink.add('warning', file, ['run'], "The run has no details section, so its name, date and type are taken from its folder name.");
+    }
+    const partial = parseFields(RunInfoSchema.shape, raw.run, sink, file, ['run']);
+    info = {
+      id: partial.id ?? runId,
+      startedAt: partial.startedAt ?? startedAtFromId(runId),
+      durationMs: partial.durationMs ?? 0,
+      mode: partial.mode ?? (runId.endsWith('showcase') ? 'showcase' : 'fast'),
+      specVersion: partial.specVersion ?? 'unknown',
+      ...partial
+    } as RunInfo;
+  }
+
+  const charts = (Array.isArray(raw.charts) ? raw.charts : []).flatMap((c, i) => {
+    const parsed = parseOne(ManifestChartSchema, c, sink, file, ['charts', i]);
+    return parsed ? [parsed] : [];
+  });
+
+  const states = new Map<string, StateRecord>();
+  if (raw.states !== undefined && !isRecord(raw.states)) sink.add('warning', file, ['states'], 'should list screens by name.');
+  for (const [name, record] of Object.entries(isRecord(raw.states) ? raw.states : {})) {
+    const parsed = parseOne(StateRecordSchema, isRecord(record) ? { name, ...record } : record, sink, file, ['states', name]);
+    if (parsed) states.set(name, parsed);
+  }
+
+  const transitions = new Map<string, ParsedTransitionRecord>();
+  if (raw.transitions !== undefined && !isRecord(raw.transitions)) sink.add('warning', file, ['transitions'], 'should list events by name.');
+  for (const [key, record] of Object.entries(isRecord(raw.transitions) ? raw.transitions : {})) {
+    const { timeline: rawTimeline, ...rest } = isRecord(record) ? record : { value: record };
+    const parsed = parseOne(TransitionRecordSchema, isRecord(record) ? rest : record, sink, file, ['transitions', key]);
+    if (!parsed) continue;
+    const id = parsed.id ?? (key.includes(' :: ') ? key : transitionId(parsed.source, parsed.event));
+    transitions.set(id, { ...parsed, id, timeline: parseTimeline(rawTimeline, sink, file, ['transitions', key, 'timeline']) });
+  }
+
+  const paths: ParsedPath[] = (Array.isArray(raw.paths) ? raw.paths : []).flatMap((p, i) => {
+    const parsed = parseOne(PathRecordSchema, p, sink, file, ['paths', i]);
+    if (!parsed) return [];
+    const steps = parsed.steps.flatMap((s, j) => {
+      const step = parseOne(PathStepSchema, s, sink, file, ['paths', i, 'steps', j]);
+      return step ? [step] : [];
+    });
+    return [{ ...parsed, steps }];
+  });
+
+  const mapKinds = new Map<string, EventKind>();
+  const edges = isRecord(raw.map) && Array.isArray(raw.map.edges) ? raw.map.edges : [];
+  for (const edge of edges) {
+    const parsed = MapEdgeSchema.safeParse(edge);
+    if (parsed.success) mapKinds.set(parsed.data.id, parsed.data.kind);
+  }
+
+  const privacy = raw.privacy === undefined ? null : parseOne(PrivacySchema, raw.privacy, sink, file, ['privacy']);
+  const reports = raw.reports === undefined ? null : parseOne(ReportsSchema, raw.reports, sink, file, ['reports']);
+  const journeys = (Array.isArray(raw.journeys) ? raw.journeys : []).flatMap((j, i) => {
+    const parsed = parseOne(JourneyRecordSchema, j, sink, file, ['journeys', i]);
+    return parsed ? [parsed] : [];
+  });
+  const seeds = (Array.isArray(raw.seeds) ? raw.seeds : []).flatMap((s, i) => {
+    const parsed = parseOne(SeedRecordSchema, s, sink, file, ['seeds', i]);
+    return parsed ? [parsed] : [];
+  });
+  return { id: runId, file, schemaVersion, info, charts, states, transitions, paths, journeys, seeds, mapKinds, privacy, reports };
+}
+
+export type ParsedRunsIndex = { runs: RunSummary[]; excluded: string[] };
+
+export function parseRunsIndex(file: string, raw: unknown, sink: IssueSink = createIssueSink()): ParsedRunsIndex {
+  const index = parseOne(RunsIndexSchema, raw, sink, file, [], 'error');
+  if (!index) return { runs: [], excluded: [] };
+  const runs = index.runs.flatMap((r, i) => {
+    const parsed = parseOne(RunSummarySchema, r, sink, file, ['runs', i]);
+    return parsed ? [parsed] : [];
+  });
+  runs.sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt));
+  return { runs, excluded: index.excluded ?? [] };
+}