@crvouga/atlas 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'bun:test';
+
+import { parseKnownIssues, parseOpenQuestions } from './markdown';
+
+const QUESTIONS = `# Open questions
+
+Intro text that is not a question.
+
+## Paying
+
+6. **Saved cards after a refund.** Nothing removes the saved card.
+   When the customer orders again, the saved card is offered first.
+   - S: Refund issued, Told the card was saved.
+   - T: Waiting for the payment → Refund is issued; Refund issued → Orders again.
+7. **An order in progress when the shop closes.** Nothing cancels it.
+   - T: Drink being made → Shop closes; Drink ready for pickup → Barista finishes the drink after closing.
+   - Spec today: the drink is made with **no pickup window**.
+8. **Guest customers.** What can they do?
+   - S: Paid, waiting for the barista (assumed).
+   - T: Asks for a receipt.
+
+## Pickup
+
+12. **Curbside pickup.** S: and T: on one line.
+    - S: \`Order placed\`, Drink ready for pickup. T: every pickup path.
+
+## Not modeled
+
+27. These are outside this spec today:
+    - tips and split bills
+    - **gift** and promo codes
+`;
+
+const KNOWN = new Set(['Refund issued', 'Told the card was saved', 'Paid, waiting for the barista', 'Order placed', 'Drink ready for pickup']);
+
+describe('parseOpenQuestions', () => {
+  const { questions, excluded } = parseOpenQuestions('open-questions.md', QUESTIONS, KNOWN);
+  const byNumber = (n: number) => questions.find((q) => q.number === n)!;
+
+  it('reads every numbered question under its section', () => {
+    expect(questions.map((q) => [q.number, q.section])).toEqual([
+      [6, 'Paying'],
+      [7, 'Paying'],
+      [8, 'Paying'],
+      [12, 'Pickup']
+    ]);
+    expect(byNumber(6)).toMatchObject({
+      file: 'open-questions.md',
+      title: 'Saved cards after a refund.',
+      body: 'Nothing removes the saved card. When the customer orders again, the saved card is offered first.'
+    });
+  });
+
+  it.each<[number, string[], { source: string; event: string }[]]>([
+    [6, ['Refund issued', 'Told the card was saved'], [
+      { source: 'Waiting for the payment', event: 'Refund is issued' },
+      { source: 'Refund issued', event: 'Orders again' }
+    ]],
+    [7, [], [
+      { source: 'Drink being made', event: 'Shop closes' },
+      { source: 'Drink ready for pickup', event: 'Barista finishes the drink after closing' }
+    ]],
+    [8, ['Paid, waiting for the barista'], [{ source: '', event: 'Asks for a receipt' }]],
+    [12, ['Order placed', 'Drink ready for pickup'], []]
+  ])('question %i names its states and transitions', (number, states, transitions) => {
+    expect(byNumber(number).states).toEqual(states);
+    expect(byNumber(number).transitions).toEqual(transitions);
+  });
+
+  it('keeps "Spec today" apart from the references', () => {
+    expect(byNumber(7).specToday).toBe('the drink is made with no pickup window.');
+    expect(byNumber(6).specToday).toBeNull();
+  });
+
+  it('lists the "Not modeled" bullets as excluded, not as a question', () => {
+    expect(excluded).toEqual(['tips and split bills', 'gift and promo codes']);
+    expect(questions.some((q) => q.number === 27)).toBe(false);
+  });
+
+  it('splits on commas when no state names are known', () => {
+    const plain = parseOpenQuestions('q.md', QUESTIONS);
+    expect(plain.questions.find((q) => q.number === 8)!.states).toEqual(['Paid', 'waiting for the barista']);
+  });
+});
+
+describe('parseKnownIssues', () => {
+  const TEXT = `# Known issues
+
+## Refund issued
+
+- The banner flickers on first load.
+- It also shows twice.
+
+## Refund issued → Orders again
+
+* The menu opens scrolled to the bottom.
+
+## Something that is not a state
+
+- \`Order placed\` uses the wrong icon.
+- Nothing named here.
+`;
+
+  it.each<[number, string, string[], { source: string; event: string }[]]>([
+    [0, 'The banner flickers on first load.', ['Refund issued'], []],
+    [1, 'It also shows twice.', ['Refund issued'], []],
+    [2, 'The menu opens scrolled to the bottom.', [], [{ source: 'Refund issued', event: 'Orders again' }]],
+    [3, 'Order placed uses the wrong icon.', ['Order placed'], []]
+  ])('note %i: %s', (index, title, states, transitions) => {
+    const notes = parseKnownIssues('known-issues.md', TEXT, KNOWN);
+    expect(notes).toHaveLength(4);
+    expect(notes[index]).toMatchObject({ file: 'known-issues.md', title, states, transitions });
+  });
+
+  it('takes the first sentence as the title', () => {
+    const [note] = parseKnownIssues('k.md', '## Refund issued\n\n- First sentence. Second sentence.\n', KNOWN);
+    expect(note).toMatchObject({ title: 'First sentence.', body: 'First sentence. Second sentence.' });
+  });
+});

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

@@ -0,0 +1,133 @@
+export type ParsedQuestion = {
+  file: string;
+  number: number;
+  section: string;
+  title: string;
+  body: string;
+  specToday: string | null;
+  states: string[];
+  transitions: { source: string; event: string }[];
+};
+
+export type ParsedNote = {
+  file: string;
+  title: string;
+  body: string;
+  states: string[];
+  transitions: { source: string; event: string }[];
+};
+
+const NOT_MODELED = /^not modeled$/i;
+
+function stripMarkdown(text: string) {
+  return text
+    .replace(/\*\*(.+?)\*\*/g, '$1')
+    .replace(/`(.+?)`/g, '$1')
+    .replace(/\[(.+?)\]\((.+?)\)/g, '$1')
+    .trim();
+}
+
+function parseTransitionRef(text: string, eventOnly = false) {
+  const [source, event] = text.split(/\s*→\s*/);
+  if (source && event) return { source: source.trim(), event: event.trim().replace(/\.$/, '') };
+  return eventOnly && source && !/^every\b/i.test(source) ? { source: '', event: source.trim().replace(/\.$/, '') } : null;
+}
+
+/** Comma-split names joined back where the joined name is a known state, like "Results in, review pending". */
+function joinKnownNames(parts: string[], known: ReadonlySet<string> | undefined) {
+  if (!known) return parts;
+  const out: string[] = [];
+  for (let i = 0; i < parts.length; ) {
+    let j = parts.length;
+    while (j > i + 1 && !known.has(parts.slice(i, j).join(', '))) j--;
+    out.push(parts.slice(i, j).join(', '));
+    i = j;
+  }
+  return out;
+}
+
+/** "S: A, B. T: X → e; Y → f." into its state and transition references. */
+function parseRefs(line: string, knownStates?: ReadonlySet<string>) {
+  const states: string[] = [];
+  const transitions: { source: string; event: string }[] = [];
+  const s = line.match(/(?:^|\s)S:\s*(.+?)(?=\s+T:|$)/)?.[1];
+  const t = line.match(/(?:^|\s)T:\s*(.+)$/)?.[1];
+  if (s) states.push(...joinKnownNames(s.replace(/\.$/, '').split(/,\s*/).map((name) => stripMarkdown(name).replace(/\s*\(.*\)$/, '')), knownStates));
+  if (t) {
+    for (const part of t.split(/;\s*/)) {
+      const ref = parseTransitionRef(stripMarkdown(part), true);
+      if (ref) transitions.push(ref);
+    }
+  }
+  return { states: states.filter(Boolean), transitions };
+}
+
+/**
+ * `open-questions.md`: numbered questions under `##` sections, each with `- S:` / `- T:` lines
+ * naming what it affects, and a "Not modeled" section listing features outside the spec.
+ */
+export function parseOpenQuestions(file: string, text: string, knownStates?: ReadonlySet<string>) {
+  const questions: ParsedQuestion[] = [];
+  const excluded: string[] = [];
+  let section = '';
+  let current: ParsedQuestion | null = null;
+  for (const line of text.split('\n')) {
+    const heading = line.match(/^##\s+(.+?)\s*$/);
+    if (heading) {
+      section = heading[1]!;
+      current = null;
+      continue;
+    }
+    if (NOT_MODELED.test(section)) {
+      const bullet = line.match(/^\s+-\s+(.+)$/)?.[1];
+      if (bullet) excluded.push(stripMarkdown(bullet));
+      continue;
+    }
+    const item = line.match(/^(\d+)\.\s+\*\*(.+?)\*\*\s*(.*)$/);
+    if (item) {
+      current = { file, number: Number(item[1]), section, title: stripMarkdown(item[2]!), body: stripMarkdown(item[3] ?? ''), specToday: null, states: [], transitions: [] };
+      questions.push(current);
+      continue;
+    }
+    if (!current) continue;
+    const bullet = line.match(/^\s+-\s+(.+)$/)?.[1];
+    if (bullet) {
+      if (/^Spec today:/i.test(bullet)) current.specToday = stripMarkdown(bullet.replace(/^Spec today:\s*/i, ''));
+      else {
+        const refs = parseRefs(bullet, knownStates);
+        current.states.push(...refs.states);
+        current.transitions.push(...refs.transitions);
+      }
+      continue;
+    }
+    if (line.trim()) current.body = `${current.body} ${stripMarkdown(line)}`.trim();
+  }
+  return { questions, excluded };
+}
+
+/**
+ * `known-issues.md`: `## <state>` or `## <from> → <event>` sections with the issues as bullets.
+ * Bullets elsewhere that name a state in backticks attach to that state.
+ */
+export function parseKnownIssues(file: string, text: string, knownStates: ReadonlySet<string>) {
+  const notes: ParsedNote[] = [];
+  let heading: { states: string[]; transitions: { source: string; event: string }[] } | null = null;
+  for (const line of text.split('\n')) {
+    const h = line.match(/^##+\s+(.+?)\s*$/)?.[1];
+    if (h) {
+      const clean = stripMarkdown(h);
+      const ref = parseTransitionRef(clean);
+      heading = ref ? { states: [], transitions: [ref] } : knownStates.has(clean) ? { states: [clean], transitions: [] } : null;
+      continue;
+    }
+    const bullet = line.match(/^\s*[-*]\s+(.+)$/)?.[1];
+    if (!bullet) continue;
+    const named = [...bullet.matchAll(/`([^`]+)`/g)].map((m) => m[1]!).filter((name) => knownStates.has(name));
+    const states = [...(heading?.states ?? []), ...named];
+    const transitions = heading?.transitions ?? [];
+    if (states.length === 0 && transitions.length === 0) continue;
+    const body = stripMarkdown(bullet);
+    notes.push({ file, title: body.split(/(?<=[.!?])\s/)[0] ?? body, body, states, transitions });
+  }
+  return notes;
+}

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

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createIssueSink } from './issues';
+import { parseSpec, type SpecFile } from './spec';
+
+function parse(files: SpecFile[]) {
+  const sink = createIssueSink();
+  const doc = parseSpec({ ref: null, files }, sink);
+  return { doc, issues: sink.issues, problems: sink.issues.filter((i) => i.severity !== 'info') };
+}
+
+const ROOT_SCXML = `<?xml version="1.0" encoding="UTF-8"?>
+<scxml xmlns="http://www.w3.org/2005/07/scxml" xmlns:atlas="https://github.com/crvouga/atlas/ns/1" version="1.0" name="Todo list" initial="listing">
+  <atlas:meta>
+    <atlas:eventKinds>{"Reminder is due": "time"}</atlas:eventKinds>
+  </atlas:meta>
+  <state id="listing" atlas:name="Listing todos">
+    <atlas:meta>
+      <atlas:description>All todos.</atlas:description>
+      <atlas:hints>["A list of todos", "An add button"]</atlas:hints>
+      <atlas:gherkin>features/todos.feature</atlas:gherkin>
+    </atlas:meta>
+    <transition event="adds-a-todo" atlas:name="Adds a todo" target="adding"/>
+  </state>
+  <state id="adding" atlas:name="Adding a todo">
+    <invoke type="scxml" src="todo-editor.scxml" id="editor" atlas:name="Todo editor"/>
+    <transition event="done.invoke.editor" target="reminders"/>
+  </state>
+  <parallel id="reminders" atlas:name="Reminders">
+    <state id="sound" atlas:name="Sound" initial="sound-on">
+      <state id="sound-on" atlas:name="Sound on"><transition event="mutes" atlas:name="Mutes" target="sound-off"/></state>
+      <state id="sound-off" atlas:name="Sound off"><transition event="unmutes" atlas:name="Unmutes" target="sound-on"/></state>
+    </state>
+    <state id="due" atlas:name="Due" initial="waiting">
+      <state id="waiting" atlas:name="Waiting"><transition event="reminder-is-due" atlas:name="Reminder is due" target="ringing"/></state>
+      <state id="ringing" atlas:name="Ringing"/>
+    </state>
+  </parallel>
+</scxml>
+`;
+
+const EDITOR_YAML = `id: Todo editor
+initial: Typing
+states:
+  Typing:
+    meta: { description: A text field. }
+    on:
+      Saves the todo: '#Saved'
+  Saved:
+    type: final
+    meta: { description: Saved. }
+`;
+
+describe('SCXML charts', () => {
+  const { doc, problems } = parse([
+    { path: 'todo/todo-list.scxml', text: ROOT_SCXML },
+    { path: 'todo/todo-editor.machine.yaml', text: EDITOR_YAML }
+  ]);
+
+  it('reads states, parallel regions and readable names', () => {
+    expect(problems).toEqual([]);
+    expect(doc.charts.map((c) => [c.id, c.format])).toEqual([
+      ['Todo editor', 'xstate'],
+      ['Todo list', 'scxml']
+    ]);
+    expect(doc.states.get('Reminders')?.type).toBe('parallel');
+    expect(doc.states.get('Sound')).toMatchObject({ type: 'compound', initial: 'Sound on', parent: 'Reminders' });
+    expect(doc.transitions.get('Sound on :: Mutes')?.target).toBe('Sound off');
+  });
+
+  it('reads list and map metadata carried as text', () => {
+    expect(doc.states.get('Listing todos')?.meta).toMatchObject({ hints: ['A list of todos', 'An add button'], gherkin: ['features/todos.feature'] });
+    expect(doc.charts.find((c) => c.id === 'Todo list')?.meta.eventKinds).toEqual({ 'Reminder is due': 'time' });
+  });
+
+  it('composes an <invoke> whose done.invoke transition becomes the hand-off', () => {
+    expect(doc.states.get('Adding a todo')).toMatchObject({ childChartId: 'Todo editor', invoke: { src: 'Todo editor', id: 'editor', onDone: '#Reminders' } });
+    expect(doc.charts.find((c) => c.id === 'Todo editor')?.parent).toEqual({ chartId: 'Todo list', state: 'Adding a todo' });
+    expect(doc.transitions.get('Saved :: done.invoke.editor')).toMatchObject({ handOff: true, chartId: 'Todo editor', target: 'Reminders' });
+    expect(doc.transitions.get('Adding a todo :: done.invoke.editor')).toMatchObject({ chartId: 'Todo list', target: 'Reminders', carriedBy: 'Saved :: done.invoke.editor' });
+  });
+});
+
+describe('child chart problems', () => {
+  it.each<[string, string, RegExp]>([
+    ['an invoke of a chart that is not in the spec', "    invoke: { src: Nowhere }\n", /names the chart "Nowhere"/],
+    ['an invoke with no src', '    invoke: { id: editor }\n', /should name the chart it runs/],
+    ['a child final the parent does not handle', '    invoke: { src: Todo editor }\n', /"Saved" ends "Todo editor" and passes "done\.invoke\.Todo editor" up/]
+  ])('reports %s', (_label, invoke, message) => {
+    const parent = `id: Todos\ninitial: Adding\nstates:\n  Adding:\n    meta: { description: Adding. }\n${invoke}`;
+    const { problems } = parse([
+      { path: 'todo/machine.yaml', text: parent },
+      { path: 'todo/todo-editor.machine.yaml', text: EDITOR_YAML }
+    ]);
+    expect(problems.map((p) => p.message)).toContainEqual(expect.stringMatching(message));
+  });
+
+  it('reports an SCXML file it cannot read and keeps the rest', () => {
+    const { doc, problems } = parse([
+      { path: 'todo/broken.scxml', text: '<statechart name="Broken"/>' },
+      { path: 'todo/todo-editor.machine.yaml', text: EDITOR_YAML }
+    ]);
+    expect(problems).toEqual([expect.objectContaining({ severity: 'error', file: 'todo/broken.scxml', message: expect.stringMatching(/could not be read/) })]);
+    expect(doc.charts.map((c) => c.id)).toEqual(['Todo editor']);
+  });
+});