@mmapp/player-core 0.1.0-alpha.1

package/src/__tests__/dsl-compiler.test.ts

@@ -0,0 +1,1382 @@
+import { describe, it, expect } from 'vitest';
+import { compile, tokenize, parse } from '../dsl';
+import type {
+  CompilationResult,
+  IRWorkflowDefinition,
+  IRFieldDefinition,
+  IRExperienceNode,
+} from '../dsl';
+import { mapField } from '../dsl/compiler/field-mapper';
+import {
+  mapContent,
+  mapStringLiteral,
+  mapIteration,
+  mapSection,
+  mapSearch,
+  mapNavigation,
+  mapPages,
+} from '../dsl/compiler/component-mapper';
+import { slugify, snakeCase, generateId, generateActionId } from '../dsl/compiler/utils';
+import { transformExpression } from '../dsl/compiler/workflow-compiler';
+import type { FieldDefData, ContentData, StringLiteralData, IterationData } from '../dsl';
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function compileSource(source: string): CompilationResult {
+  return compile(source.trim());
+}
+
+function findWorkflow(result: CompilationResult, slug: string): IRWorkflowDefinition | undefined {
+  return result.workflows.find(w => w.slug === slug);
+}
+
+// =============================================================================
+// Section 1: Utility Functions
+// =============================================================================
+
+describe('DSL Compiler — Utilities', () => {
+  it('slugifies names', () => {
+    expect(slugify('project management')).toBe('project-management');
+    expect(slugify('user stats')).toBe('user-stats');
+    expect(slugify('Task Board')).toBe('task-board');
+  });
+
+  it('snake_cases names', () => {
+    expect(snakeCase('total tasks')).toBe('total_tasks');
+    expect(snakeCase('started at')).toBe('started_at');
+    expect(snakeCase('xp reward')).toBe('xp_reward');
+  });
+
+  it('generates deterministic IDs', () => {
+    expect(generateId('project', 'draft')).toBe('project--draft');
+    expect(generateId('task', 'in progress')).toBe('task--in-progress');
+  });
+
+  it('generates action IDs', () => {
+    expect(generateActionId('active-on-enter', 0)).toBe('active-on-enter-0');
+    expect(generateActionId('draft-on-enter', 2)).toBe('draft-on-enter-2');
+  });
+});
+
+// =============================================================================
+// Section 2: Field Mapping
+// =============================================================================
+
+describe('DSL Compiler — Field Mapping', () => {
+  function makeField(overrides: Partial<FieldDefData> = {}): FieldDefData {
+    return {
+      name: 'test field',
+      adjectives: [],
+      baseType: 'text',
+      constraints: [],
+      ...overrides,
+    };
+  }
+
+  it('maps text field', () => {
+    const result = mapField(makeField({ baseType: 'text' }));
+    expect(result.type).toBe('text');
+    expect(result.name).toBe('test_field');
+  });
+
+  it('maps rich text field', () => {
+    const result = mapField(makeField({ baseType: 'rich text' }));
+    expect(result.type).toBe('rich_text');
+  });
+
+  it('maps number field', () => {
+    const result = mapField(makeField({ baseType: 'number' }));
+    expect(result.type).toBe('number');
+  });
+
+  it('maps integer field → number with validation rule', () => {
+    const result = mapField(makeField({ baseType: 'integer' }));
+    expect(result.type).toBe('number');
+    expect(result.validation?.rules).toEqual([
+      {
+        expression: 'eq(round($value), $value)',
+        message: 'Must be a whole number',
+        severity: 'error',
+      },
+    ]);
+  });
+
+  it('maps time field → datetime', () => {
+    const result = mapField(makeField({ baseType: 'time' }));
+    expect(result.type).toBe('datetime');
+  });
+
+  it('maps choice field → select with options', () => {
+    const result = mapField(makeField({
+      baseType: 'choice of [low, medium, high, critical]',
+    }));
+    expect(result.type).toBe('select');
+    expect(result.validation?.options).toEqual(['low', 'medium', 'high', 'critical']);
+  });
+
+  it('maps required adjective', () => {
+    const result = mapField(makeField({ adjectives: ['required'] }));
+    expect(result.required).toBe(true);
+  });
+
+  it('maps optional adjective', () => {
+    const result = mapField(makeField({ adjectives: ['optional'] }));
+    expect(result.required).toBe(false);
+  });
+
+  it('maps non-negative adjective → validation.min: 0', () => {
+    const result = mapField(makeField({
+      baseType: 'number',
+      adjectives: ['non-negative'],
+    }));
+    expect(result.validation?.min).toBe(0);
+  });
+
+  it('maps positive adjective → validation.min: 1', () => {
+    const result = mapField(makeField({
+      baseType: 'number',
+      adjectives: ['positive'],
+    }));
+    expect(result.validation?.min).toBe(1);
+  });
+
+  it('maps computed adjective', () => {
+    const result = mapField(makeField({ adjectives: ['computed'] }));
+    expect(result.computed).toBe('');
+  });
+
+  it('maps max constraint on text → maxLength', () => {
+    const result = mapField(makeField({
+      baseType: 'text',
+      constraints: [{ kind: 'max', value: 200 }],
+    }));
+    expect(result.validation?.maxLength).toBe(200);
+  });
+
+  it('maps max constraint on number → max', () => {
+    const result = mapField(makeField({
+      baseType: 'number',
+      constraints: [{ kind: 'max', value: 100 }],
+    }));
+    expect(result.validation?.max).toBe(100);
+  });
+
+  it('maps default constraint → default_value', () => {
+    const result = mapField(makeField({
+      constraints: [{ kind: 'default', value: 'hello' }],
+    }));
+    expect(result.default_value).toBe('hello');
+  });
+
+  it('maps numeric default', () => {
+    const result = mapField(makeField({
+      baseType: 'number',
+      constraints: [{ kind: 'default', value: 0 }],
+    }));
+    expect(result.default_value).toBe(0);
+  });
+
+  it('maps between constraint → min + max', () => {
+    const result = mapField(makeField({
+      baseType: 'number',
+      constraints: [{ kind: 'between', value: 1, value2: 5 }],
+    }));
+    expect(result.validation?.min).toBe(1);
+    expect(result.validation?.max).toBe(5);
+  });
+
+  it('maps combined: required text, max 200', () => {
+    const result = mapField(makeField({
+      adjectives: ['required'],
+      baseType: 'text',
+      constraints: [{ kind: 'max', value: 200 }],
+    }));
+    expect(result.required).toBe(true);
+    expect(result.type).toBe('text');
+    expect(result.validation?.maxLength).toBe(200);
+  });
+
+  it('maps combined: non-negative number, default 0', () => {
+    const result = mapField(makeField({
+      adjectives: ['non-negative'],
+      baseType: 'number',
+      constraints: [{ kind: 'default', value: 0 }],
+    }));
+    expect(result.validation?.min).toBe(0);
+    expect(result.default_value).toBe(0);
+  });
+
+  it('maps choice with required + default', () => {
+    const result = mapField(makeField({
+      adjectives: ['required'],
+      baseType: 'choice of [low, medium, high, critical]',
+      constraints: [{ kind: 'default', value: 'medium' }],
+    }));
+    expect(result.type).toBe('select');
+    expect(result.required).toBe(true);
+    expect(result.default_value).toBe('medium');
+    expect(result.validation?.options).toEqual(['low', 'medium', 'high', 'critical']);
+  });
+});
+
+// =============================================================================
+// Section 3: Component Mapping
+// =============================================================================
+
+describe('DSL Compiler — Component Mapping', () => {
+  it('maps content with big emphasis → Text heading', () => {
+    const node = mapContent(
+      { pronoun: 'its', field: 'name', emphasis: 'big' } as ContentData,
+      false, 'root', 0,
+    );
+    expect(node.component).toBe('Text');
+    expect(node.config).toEqual({ variant: 'heading' });
+    expect(node.bindings?.value).toBe('$instance.state_data.name');
+  });
+
+  it('maps content with small emphasis → Text caption', () => {
+    const node = mapContent(
+      { pronoun: 'its', field: 'date', emphasis: 'small' } as ContentData,
+      false, 'root', 0,
+    );
+    expect(node.component).toBe('Text');
+    expect(node.config).toEqual({ variant: 'caption' });
+  });
+
+  it('maps content with tag role → Badge', () => {
+    const node = mapContent(
+      { pronoun: 'its', field: 'priority', role: 'tag' } as ContentData,
+      false, 'root', 0,
+    );
+    expect(node.component).toBe('Badge');
+  });
+
+  it('maps content with progress role → ProgressTracker', () => {
+    const node = mapContent(
+      { pronoun: 'its', field: 'health', role: 'progress' } as ContentData,
+      false, 'root', 0,
+    );
+    expect(node.component).toBe('ProgressTracker');
+  });
+
+  it('maps content with label → Text with label config', () => {
+    const node = mapContent(
+      { field: 'total xp', label: 'Total XP' } as ContentData,
+      false, 'root', 0,
+    );
+    expect(node.component).toBe('Text');
+    expect(node.config?.label).toBe('Total XP');
+  });
+
+  it('maps content inside each → $item binding scope', () => {
+    const node = mapContent(
+      { pronoun: 'its', field: 'name' } as ContentData,
+      true, 'root', 0,
+    );
+    expect(node.bindings?.value).toBe('$item.state_data.name');
+  });
+
+  it('maps content for "state" field → $instance.current_state', () => {
+    const node = mapContent(
+      { pronoun: 'its', field: 'state', role: 'tag' } as ContentData,
+      false, 'root', 0,
+    );
+    expect(node.bindings?.value).toBe('$instance.current_state');
+  });
+
+  it('maps string literal → Text', () => {
+    const node = mapStringLiteral(
+      { text: 'Projects', emphasis: 'big' } as StringLiteralData,
+      'root', 0,
+    );
+    expect(node.component).toBe('Text');
+    expect(node.bindings?.value).toBe('"Projects"');
+    expect(node.config).toEqual({ variant: 'heading' });
+  });
+
+  it('maps iteration as card → Each wrapping Card', () => {
+    const children = [{ id: 'child-1', component: 'Text' }];
+    const node = mapIteration(
+      { subject: 'project', role: 'card' } as IterationData,
+      children, 'root', 0,
+    );
+    expect(node.component).toBe('Each');
+    expect(node.children?.[0].component).toBe('Card');
+    expect(node.children?.[0].children).toEqual(children);
+  });
+
+  it('maps search → SearchInput', () => {
+    const node = mapSearch({ target: 'my projects' }, 'root', 0);
+    expect(node.component).toBe('SearchInput');
+    expect(node.config?.target).toBe('my projects');
+  });
+
+  it('maps pages → Pagination', () => {
+    const node = mapPages('root', 0);
+    expect(node.component).toBe('Pagination');
+  });
+
+  it('maps numbers section → MetricsGrid', () => {
+    const node = mapSection({ name: 'numbers' }, [], 'root');
+    expect(node.component).toBe('MetricsGrid');
+  });
+
+  it('maps tabs section → TabbedLayout', () => {
+    const node = mapSection({ name: 'tabs' }, [], 'root');
+    expect(node.component).toBe('TabbedLayout');
+  });
+
+  it('maps actions section → TransitionActions', () => {
+    const node = mapSection({ name: 'actions' }, [], 'root');
+    expect(node.component).toBe('TransitionActions');
+  });
+
+  it('maps navigation → Link with onClick binding', () => {
+    const node = mapNavigation(
+      { trigger: 'tap', target: '/projects/{its id}' },
+      false, 'root', 0,
+    );
+    expect(node.component).toBe('Link');
+    expect(node.bindings?.onClick).toContain('$action.navigate');
+  });
+
+  it('maps navigation inside each → $item scope', () => {
+    const node = mapNavigation(
+      { trigger: 'tap', target: '/projects/{its id}' },
+      true, 'root', 0,
+    );
+    expect(node.bindings?.onClick).toContain('$item.id');
+  });
+});
+
+// =============================================================================
+// Section 4: Workflow Compilation
+// =============================================================================
+
+describe('DSL Compiler — Workflow Compilation', () => {
+  it('compiles minimal workflow', () => {
+    const result = compileSource(`
+a todo @1.0.0
+  starts at open
+  open
+  closed, final
+`);
+    expect(result.errors).toHaveLength(0);
+    const wf = findWorkflow(result, 'todo');
+    expect(wf).toBeDefined();
+    expect(wf!.slug).toBe('todo');
+    expect(wf!.version).toBe('1.0.0');
+    expect(wf!.states).toHaveLength(2);
+  });
+
+  it('generates correct slug from thing name', () => {
+    const result = compileSource(`
+a user stats @1.0.0
+  starts at active
+  active
+`);
+    const wf = findWorkflow(result, 'user-stats');
+    expect(wf).toBeDefined();
+    expect(wf!.name).toBe('user stats');
+  });
+
+  it('passes through version', () => {
+    const result = compileSource(`
+a task @2.1.0
+  starts at open
+  open
+`);
+    expect(findWorkflow(result, 'task')!.version).toBe('2.1.0');
+  });
+
+  it('compiles fields via field mapper', () => {
+    const result = compileSource(`
+a project @1.0.0
+  name as required text, max 200
+  count as non-negative number, default 0
+  starts at draft
+  draft
+`);
+    const wf = findWorkflow(result, 'project')!;
+    expect(wf.fields).toHaveLength(2);
+    expect(wf.fields[0]).toMatchObject({
+      name: 'name',
+      type: 'text',
+      required: true,
+      validation: { maxLength: 200 },
+    });
+    expect(wf.fields[1]).toMatchObject({
+      name: 'count',
+      type: 'number',
+      default_value: 0,
+      validation: { min: 0 },
+    });
+  });
+
+  it('resolves state type: starts_at target → START', () => {
+    const result = compileSource(`
+a task @1.0.0
+  starts at draft
+  draft
+  done, final
+`);
+    const wf = findWorkflow(result, 'task')!;
+    const draft = wf.states.find(s => s.name === 'draft');
+    expect(draft!.type).toBe('START');
+  });
+
+  it('resolves state type: final → END', () => {
+    const result = compileSource(`
+a task @1.0.0
+  starts at open
+  open
+  done, final
+`);
+    const done = findWorkflow(result, 'task')!.states.find(s => s.name === 'done');
+    expect(done!.type).toBe('END');
+  });
+
+  it('resolves state type: cancelled + final → CANCELLED', () => {
+    const result = compileSource(`
+a task @1.0.0
+  starts at open
+  open
+  cancelled, final
+`);
+    const cancelled = findWorkflow(result, 'task')!.states.find(s => s.name === 'cancelled');
+    expect(cancelled!.type).toBe('CANCELLED');
+  });
+
+  it('resolves state type: regular (no markers)', () => {
+    const result = compileSource(`
+a task @1.0.0
+  starts at open
+  open
+  in progress
+  done, final
+`);
+    const inProgress = findWorkflow(result, 'task')!.states.find(s => s.name === 'in progress');
+    expect(inProgress!.type).toBe('REGULAR');
+  });
+
+  it('compiles on_enter: set action → set_field', () => {
+    const result = compileSource(`
+a task @1.0.0
+  started at as time
+  starts at open
+  open
+    when entered
+      set started at = now()
+  done, final
+`);
+    const open = findWorkflow(result, 'task')!.states.find(s => s.name === 'open');
+    expect(open!.on_enter).toHaveLength(1);
+    expect(open!.on_enter[0]).toMatchObject({
+      type: 'set_field',
+      mode: 'auto',
+      config: {
+        field: 'started_at',
+        expression: 'now()',
+      },
+    });
+  });
+
+  it('compiles on_enter: multiple set actions', () => {
+    const result = compileSource(`
+a task @1.0.0
+  started at as time
+  status label as text
+  starts at open
+  open
+    when entered
+      set started at = now()
+      set status label = "ACTIVE"
+  done, final
+`);
+    const open = findWorkflow(result, 'task')!.states.find(s => s.name === 'open');
+    expect(open!.on_enter).toHaveLength(2);
+    expect(open!.on_enter[0].config.field).toBe('started_at');
+    expect(open!.on_enter[1].config.field).toBe('status_label');
+    expect(open!.on_enter[1].config.expression).toBe('"ACTIVE"');
+  });
+
+  it('compiles on_event: receives event subscription', () => {
+    const result = compileSource(`
+a project @1.0.0
+  total tasks as number, default 0
+  starts at active
+  active
+    when receives "task created" from task
+      set total tasks = total tasks + 1
+`);
+    const active = findWorkflow(result, 'project')!.states.find(s => s.name === 'active');
+    expect(active!.on_event).toHaveLength(1);
+    expect(active!.on_event![0].match).toContain('task');
+    expect(active!.on_event![0].match).toContain('instance.task.created');
+    expect(active!.on_event![0].actions).toHaveLength(1);
+    expect(active!.on_event![0].actions[0].type).toBe('set_field');
+    expect(active!.on_event![0].actions[0].field).toBe('total_tasks');
+  });
+
+  it('compiles on_event: set action with $event references', () => {
+    const result = compileSource(`
+a stats @1.0.0
+  total xp as number, default 0
+  starts at active
+  active
+    when receives "task completed" from task
+      set total xp = total xp + the event's xp reward
+`);
+    const active = findWorkflow(result, 'stats')!.states.find(s => s.name === 'active');
+    const action = active!.on_event![0].actions[0];
+    expect(action.expression).toContain('$event.state_data.xp_reward');
+  });
+
+  it('compiles transition: basic verb → target', () => {
+    const result = compileSource(`
+a task @1.0.0
+  starts at open
+  open
+    can close → closed
+  closed, final
+`);
+    const wf = findWorkflow(result, 'task')!;
+    expect(wf.transitions).toHaveLength(1);
+    expect(wf.transitions[0]).toMatchObject({
+      name: 'close',
+      from: ['open'],
+      to: 'closed',
+    });
+  });
+
+  it('compiles transition: guard → roles', () => {
+    const result = compileSource(`
+a task @1.0.0
+  starts at open
+  open
+    can approve → approved, admin only
+  approved, final
+`);
+    const transition = findWorkflow(result, 'task')!.transitions[0];
+    expect(transition.roles).toEqual(['admin']);
+  });
+
+  it('compiles transition: auto prefix → auto: true', () => {
+    const result = compileSource(`
+a project @1.0.0
+  starts at draft
+  draft
+    can auto complete → done
+  done, final
+`);
+    const transition = findWorkflow(result, 'project')!.transitions[0];
+    expect(transition.auto).toBe(true);
+    expect(transition.name).toBe('auto-complete');
+  });
+
+  it('compiles transition: with when condition', () => {
+    const result = compileSource(`
+a project @1.0.0
+  count as number
+  starts at active
+  active
+    can finish → done
+      when count > 0
+  done, final
+`);
+    const transition = findWorkflow(result, 'project')!.transitions[0];
+    expect(transition.conditions).toBeDefined();
+    expect(transition.conditions).toHaveLength(1);
+    expect(transition.conditions![0]).toMatchObject({
+      field: 'state_data.count',
+      operator: 'gt',
+      value: 0,
+    });
+  });
+
+  it('compiles transition: compound condition (and)', () => {
+    const result = compileSource(`
+a project @1.0.0
+  completed tasks as number
+  total tasks as number
+  starts at active
+  active
+    can auto complete → done
+      when completed tasks >= total tasks and total tasks > 0
+  done, final
+`);
+    const transition = findWorkflow(result, 'project')!.transitions[0];
+    expect(transition.conditions).toHaveLength(1);
+    const cond = transition.conditions![0];
+    expect(cond.AND).toBeDefined();
+    expect(cond.AND).toHaveLength(2);
+    expect(cond.AND![0]).toMatchObject({
+      field: 'state_data.completed_tasks',
+      operator: 'gte',
+    });
+    expect(cond.AND![1]).toMatchObject({
+      field: 'state_data.total_tasks',
+      operator: 'gt',
+      value: 0,
+    });
+  });
+
+  it('compiles multiple transitions from one state', () => {
+    const result = compileSource(`
+a task @1.0.0
+  starts at open
+  open
+    can complete → done
+    can cancel → cancelled
+  done, final
+  cancelled, final
+`);
+    const wf = findWorkflow(result, 'task')!;
+    expect(wf.transitions).toHaveLength(2);
+    expect(wf.transitions[0].name).toBe('complete');
+    expect(wf.transitions[1].name).toBe('cancel');
+  });
+
+  it('collects roles from guards', () => {
+    const result = compileSource(`
+a task @1.0.0
+  starts at open
+  open
+    can approve → done, admin only
+    can reject → cancelled, admin only
+  done, final
+  cancelled, final
+`);
+    const wf = findWorkflow(result, 'task')!;
+    expect(wf.roles).toHaveLength(1);
+    expect(wf.roles[0].name).toBe('admin');
+  });
+
+  it('compiles tags', () => {
+    const result = compileSource(`
+a task @1.0.0
+  tagged: project-management, mvp
+  starts at open
+  open
+`);
+    const wf = findWorkflow(result, 'task')!;
+    expect(wf.tags).toEqual([
+      { tag_name: 'project-management' },
+      { tag_name: 'mvp' },
+    ]);
+  });
+
+  it('compiles levels → metadata.levels', () => {
+    const result = compileSource(`
+a stats @1.0.0
+  starts at active
+  levels
+    1: "Newcomer", from 0 xp
+    2: "Veteran", from 100 xp
+  active
+`);
+    const wf = findWorkflow(result, 'stats')!;
+    expect(wf.metadata?.levels).toEqual([
+      { level: 1, title: 'Newcomer', fromXp: 0 },
+      { level: 2, title: 'Veteran', fromXp: 100 },
+    ]);
+  });
+
+  it('reports error for missing starts_at', () => {
+    const result = compileSource(`
+a task @1.0.0
+  open
+  closed, final
+`);
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(result.errors[0].code).toBe('MISSING_STARTS_AT');
+  });
+
+  it('warns for transition to unknown state', () => {
+    const result = compileSource(`
+a task @1.0.0
+  starts at open
+  open
+    can go → nonexistent
+`);
+    expect(result.warnings.length).toBeGreaterThan(0);
+    expect(result.warnings[0].code).toBe('UNKNOWN_TARGET_STATE');
+  });
+});
+
+// =============================================================================
+// Section 5: Expression Transformation
+// =============================================================================
+
+describe('DSL Compiler — Expression Transformation', () => {
+  const fields = new Set(['total tasks', 'completed tasks', 'total xp', 'xp reward', 'started at']);
+
+  it('transforms field ref → state_data.snake', () => {
+    expect(transformExpression('total tasks', fields)).toBe('state_data.total_tasks');
+  });
+
+  it('transforms "the event\'s X" → $event.state_data.snake', () => {
+    expect(transformExpression("the event's xp reward", fields))
+      .toBe('$event.state_data.xp_reward');
+  });
+
+  it('transforms arithmetic + → add()', () => {
+    expect(transformExpression('total tasks + 1', fields))
+      .toBe('add(state_data.total_tasks, 1)');
+  });
+
+  it('transforms arithmetic with event ref', () => {
+    expect(transformExpression("total xp + the event's xp reward", fields))
+      .toBe('add(state_data.total_xp, $event.state_data.xp_reward)');
+  });
+
+  it('transforms now() passthrough', () => {
+    expect(transformExpression('now()', fields)).toBe('now()');
+  });
+
+  it('transforms string literal passthrough', () => {
+    expect(transformExpression('"IN_PROGRESS"', fields)).toBe('"IN_PROGRESS"');
+  });
+
+  it('transforms numeric addition', () => {
+    expect(transformExpression('total xp + 50', fields))
+      .toBe('add(state_data.total_xp, 50)');
+  });
+});
+
+// =============================================================================
+// Section 6: View Compilation
+// =============================================================================
+
+describe('DSL Compiler — View Compilation', () => {
+  it('compiles a fragment', () => {
+    const result = compileSource(`
+a project card:
+  its name, big
+  its priority as tag
+`);
+    expect(result.experiences).toHaveLength(1);
+    expect(result.experiences[0].slug).toBe('project-card');
+    expect(result.experiences[0].view_definition.children).toBeDefined();
+  });
+
+  it('compiles a view with data source', () => {
+    const result = compileSource(`
+project list
+  my projects from project
+    newest first
+    20 at a time
+`);
+    expect(result.experiences).toHaveLength(1);
+    const exp = result.experiences[0];
+    expect(exp.slug).toBe('project-list');
+    expect(exp.view_definition.dataSources).toBeDefined();
+
+    const ds = exp.view_definition.dataSources![0];
+    expect(ds.type).toBe('workflow');
+    if (ds.type === 'workflow') {
+      expect(ds.name).toBe('projects');
+      expect(ds.slug).toBe('project');
+      expect(ds.query).toBe('list');
+      expect(ds.sort).toBe('created_at:desc');
+      expect(ds.paginated).toBe(true);
+      expect(ds.pageSize).toBe(20);
+    }
+  });
+
+  it('compiles data source: this X → latest query', () => {
+    const result = compileSource(`
+task view
+  this task from task
+`);
+    const ds = result.experiences[0].view_definition.dataSources![0];
+    if (ds.type === 'workflow') {
+      expect(ds.query).toBe('latest');
+      expect(ds.name).toBe('task');
+    }
+  });
+
+  it('compiles data source: scope → parentInstanceId', () => {
+    const result = compileSource(`
+project view
+  its tasks from task for this project
+`);
+    const ds = result.experiences[0].view_definition.dataSources![0];
+    if (ds.type === 'workflow') {
+      expect(ds.parentInstanceId).toBe('{{ parent_instance_id }}');
+    }
+  });
+
+  it('compiles data source: searchable by → searchFields', () => {
+    const result = compileSource(`
+project list
+  my projects from project
+    searchable by name and description
+`);
+    const ds = result.experiences[0].view_definition.dataSources![0];
+    if (ds.type === 'workflow') {
+      expect(ds.searchFields).toEqual(['name', 'description']);
+    }
+  });
+
+  it('compiles data source: filterable by → facets', () => {
+    const result = compileSource(`
+project list
+  my projects from project
+    filterable by priority
+`);
+    const ds = result.experiences[0].view_definition.dataSources![0];
+    if (ds.type === 'workflow') {
+      expect(ds.facets).toEqual(['priority']);
+    }
+  });
+
+  it('compiles content nodes in view', () => {
+    const result = compileSource(`
+task view
+  this task from task
+  its title, big
+  its state as tag
+`);
+    const children = result.experiences[0].view_definition.children!;
+    expect(children.length).toBeGreaterThanOrEqual(2);
+    // First should be Text heading
+    const titleNode = children.find(c => c.config?.variant === 'heading');
+    expect(titleNode?.component).toBe('Text');
+    // Second should be Badge
+    const tagNode = children.find(c => c.component === 'Badge');
+    expect(tagNode).toBeDefined();
+  });
+
+  it('compiles iteration in view', () => {
+    const result = compileSource(`
+project list
+  my projects from project
+  each project as card
+    its name, big
+    its priority as tag
+`);
+    const children = result.experiences[0].view_definition.children!;
+    const eachNode = children.find(c => c.component === 'Each');
+    expect(eachNode).toBeDefined();
+    expect(eachNode!.children![0].component).toBe('Card');
+  });
+
+  it('compiles iteration children with $item binding scope', () => {
+    const result = compileSource(`
+project list
+  my projects from project
+  each project as card
+    its name, big
+`);
+    const eachNode = result.experiences[0].view_definition.children!
+      .find(c => c.component === 'Each')!;
+    const card = eachNode.children![0];
+    const nameNode = card.children![0];
+    expect(nameNode.bindings?.value).toBe('$item.state_data.name');
+  });
+
+  it('compiles string literals', () => {
+    const result = compileSource(`
+project list
+  my projects from project
+  "Projects", big
+  "Manage your projects", small
+`);
+    const children = result.experiences[0].view_definition.children!;
+    const heading = children.find(
+      c => c.component === 'Text' && c.config?.variant === 'heading',
+    );
+    expect(heading?.bindings?.value).toBe('"Projects"');
+  });
+
+  it('compiles search node', () => {
+    const result = compileSource(`
+project list
+  my projects from project
+  search my projects
+`);
+    const children = result.experiences[0].view_definition.children!;
+    const searchNode = children.find(c => c.component === 'SearchInput');
+    expect(searchNode).toBeDefined();
+  });
+
+  it('compiles pages node', () => {
+    const result = compileSource(`
+project list
+  my projects from project
+  pages
+`);
+    const children = result.experiences[0].view_definition.children!;
+    const pagesNode = children.find(c => c.component === 'Pagination');
+    expect(pagesNode).toBeDefined();
+  });
+
+  it('compiles numbers section → MetricsGrid', () => {
+    const result = compileSource(`
+task view
+  this task from task
+  numbers
+    its xp as "XP Reward"
+    its started at as "Started"
+`);
+    const children = result.experiences[0].view_definition.children!;
+    const metricsNode = children.find(c => c.component === 'MetricsGrid');
+    expect(metricsNode).toBeDefined();
+    expect(metricsNode!.children!.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('compiles tabs section → TabbedLayout', () => {
+    const result = compileSource(`
+project view
+  this project from project
+  tabs
+    "Board" → task board
+`);
+    const children = result.experiences[0].view_definition.children!;
+    const tabsNode = children.find(c => c.component === 'TabbedLayout');
+    expect(tabsNode).toBeDefined();
+  });
+
+  it('compiles navigation in view', () => {
+    const result = compileSource(`
+project list
+  my projects from project
+  each project as card
+    its name, big
+    tap → /projects/{its id}
+`);
+    const eachNode = result.experiences[0].view_definition.children!
+      .find(c => c.component === 'Each')!;
+    const card = eachNode.children![0];
+    const navNode = card.children!.find(c => c.component === 'Link');
+    expect(navNode).toBeDefined();
+    expect(navNode!.bindings!.onClick).toContain('$action.navigate');
+  });
+
+  it('compiles grouping in view', () => {
+    const result = compileSource(`
+task board
+  these tasks from task for this project
+  tasks by state
+`);
+    const children = result.experiences[0].view_definition.children!;
+    const groupNode = children.find(c => c.config?.groupBy === 'state');
+    expect(groupNode).toBeDefined();
+  });
+
+  it('infers stack layout for multiple siblings', () => {
+    const result = compileSource(`
+task view
+  this task from task
+  its title, big
+  its state as tag
+  its priority as tag
+`);
+    expect(result.experiences[0].view_definition.layout).toBe('stack');
+  });
+
+  it('tracks workflow slugs from data sources', () => {
+    const result = compileSource(`
+project view
+  this project from project
+  its tasks from task for this project
+`);
+    expect(result.experiences[0].workflows).toContain('project');
+    expect(result.experiences[0].workflows).toContain('task');
+  });
+});
+
+// =============================================================================
+// Section 7: Manifest Compilation
+// =============================================================================
+
+describe('DSL Compiler — Manifest Compilation', () => {
+  it('compiles space with thing refs → manifest.workflows', () => {
+    const result = compileSource(`
+project management @1.0.0
+  things
+    a project (primary)
+    a task (child)
+    user stats (derived)
+`);
+    expect(result.manifest).toBeDefined();
+    expect(result.manifest!.workflows).toHaveLength(3);
+    expect(result.manifest!.workflows).toContainEqual({ slug: 'project', role: 'primary' });
+    expect(result.manifest!.workflows).toContainEqual({ slug: 'task', role: 'child' });
+    expect(result.manifest!.workflows).toContainEqual({ slug: 'user-stats', role: 'derived' });
+  });
+
+  it('compiles experience_id from space name', () => {
+    const result = compileSource(`
+project management @1.0.0
+  things
+    a project (primary)
+`);
+    expect(result.manifest!.experience_id).toBe('project-management');
+  });
+
+  it('compiles paths → routes with node slugs', () => {
+    const result = compileSource(`
+project management @1.0.0
+  paths
+    /projects → project list (user)
+    /projects/:id → project view (project)
+`);
+    expect(result.manifest!.routes).toHaveLength(2);
+    expect(result.manifest!.routes![0]).toMatchObject({
+      path: '/projects',
+      node: 'project-list',
+      entityType: 'user',
+      entityIdSource: 'user',
+    });
+    expect(result.manifest!.routes![1]).toMatchObject({
+      path: '/projects/:id',
+      node: 'project-view',
+      entityType: 'project',
+      entityIdSource: 'param',
+    });
+  });
+
+  it('sets entityIdSource: user for user context', () => {
+    const result = compileSource(`
+project management @1.0.0
+  paths
+    /profile → user profile (user)
+`);
+    expect(result.manifest!.routes![0].entityIdSource).toBe('user');
+  });
+
+  it('sets entityIdSource: param for path with :id', () => {
+    const result = compileSource(`
+project management @1.0.0
+  paths
+    /tasks/:id → task view (task)
+`);
+    expect(result.manifest!.routes![0].entityIdSource).toBe('param');
+  });
+
+  it('produces no manifest without space', () => {
+    const result = compileSource(`
+a task @1.0.0
+  starts at open
+  open
+`);
+    expect(result.manifest).toBeUndefined();
+  });
+
+  it('handles space with no paths', () => {
+    const result = compileSource(`
+project management @1.0.0
+  things
+    a project (primary)
+`);
+    expect(result.manifest).toBeDefined();
+    // routes may be undefined or empty
+  });
+
+  it('handles space with no things', () => {
+    const result = compileSource(`
+project management @1.0.0
+  paths
+    /projects → project list (user)
+`);
+    expect(result.manifest).toBeDefined();
+    expect(result.manifest!.workflows).toHaveLength(0);
+  });
+});
+
+// =============================================================================
+// Section 8: Full Blueprint E2E
+// =============================================================================
+
+describe('DSL Compiler — Full Blueprint E2E', () => {
+  const BLUEPRINT = `
+# ═══════════════════════════════════════════════════
+# Space
+# ═══════════════════════════════════════════════════
+
+project management @1.0.0
+  tagged: project-management, blueprint-mvp1
+
+  things
+    a project (primary)
+    a task (child)
+    user stats (derived)
+
+  paths
+    /projects           → project list     (user)
+    /projects/:id       → project view     (project)
+    /projects/:id/board → task board        (project)
+    /tasks/:id          → task view         (task)
+    /profile            → user profile      (user)
+
+
+# ═══════════════════════════════════════════════════
+# Things (Workflows)
+# ═══════════════════════════════════════════════════
+
+a project @1.0.0
+  tagged: project-management, blueprint-mvp1
+
+  name as required text, max 200
+  description as rich text
+  priority as required choice of [low, medium, high, critical], default medium
+  total tasks as non-negative number, default 0
+  completed tasks as non-negative number, default 0
+  started at as time
+  completed at as time
+
+  starts at draft
+
+  draft
+    can activate → active
+
+  active
+    when entered
+      set started at = now()
+
+    when receives "task created" from task
+      set total tasks = total tasks + 1
+
+    when receives "task completed" from task
+      set completed tasks = completed tasks + 1
+
+    can auto complete → completed
+      when completed tasks >= total tasks and total tasks > 0
+    can manual complete → completed, admin only
+    can cancel → cancelled
+
+  completed, final
+    when entered
+      set completed at = now()
+
+  cancelled, final
+
+
+a task @1.0.0
+  tagged: project-management, blueprint-mvp1
+
+  title as required text, max 200
+  description as rich text
+  priority as required choice of [low, medium, high, critical], default medium
+  status label as computed text
+  xp reward as non-negative number, default 25
+  assignee as text
+  started at as time
+  completed at as time
+
+  starts at todo
+
+  todo
+    can start → in progress
+
+  in progress
+    when entered
+      set started at = now()
+      set status label = "IN_PROGRESS"
+    can complete → done
+    can cancel → cancelled
+
+  done, final
+    when entered
+      set completed at = now()
+      set status label = "DONE"
+
+  cancelled, final
+    when entered
+      set status label = "CANCELLED"
+
+
+a user stats @1.0.0
+  tagged: project-management, gamification
+
+  total xp as number, default 0
+  current level as number, default 1
+  level title as text, default "Newcomer"
+  tasks completed as number, default 0
+  projects completed as number, default 0
+  user id as text
+  streak days as number, default 0
+  last activity at as time
+
+  levels
+    1: "Newcomer",      from 0 xp
+    2: "Contributor",   from 50 xp
+    3: "Team Player",   from 150 xp
+    4: "Veteran",       from 350 xp
+    5: "Expert",        from 600 xp
+    6: "Master",        from 1000 xp
+    7: "Grand Master",  from 1500 xp
+    8: "Legend",        from 2500 xp
+
+  starts at active
+
+  active
+    when receives "task completed" from task
+      set total xp = total xp + the event's xp reward
+      set tasks completed = tasks completed + 1
+      set last activity at = now()
+
+    when receives "project completed" from project
+      set total xp = total xp + 50
+      set projects completed = projects completed + 1
+`.trim();
+
+  let result: CompilationResult;
+
+  // Compile once for all E2E tests
+  beforeAll(() => {
+    result = compile(BLUEPRINT);
+  });
+
+  it('compiles without errors', () => {
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('produces 3 workflows', () => {
+    expect(result.workflows).toHaveLength(3);
+    const slugs = result.workflows.map(w => w.slug).sort();
+    expect(slugs).toEqual(['project', 'task', 'user-stats']);
+  });
+
+  it('project workflow: 4 states with correct types', () => {
+    const wf = findWorkflow(result, 'project')!;
+    expect(wf.states).toHaveLength(4);
+    expect(wf.states.find(s => s.name === 'draft')!.type).toBe('START');
+    expect(wf.states.find(s => s.name === 'active')!.type).toBe('REGULAR');
+    expect(wf.states.find(s => s.name === 'completed')!.type).toBe('END');
+    expect(wf.states.find(s => s.name === 'cancelled')!.type).toBe('CANCELLED');
+  });
+
+  it('project workflow: 7 fields correctly typed', () => {
+    const wf = findWorkflow(result, 'project')!;
+    expect(wf.fields).toHaveLength(7);
+
+    const name = wf.fields.find(f => f.name === 'name')!;
+    expect(name.type).toBe('text');
+    expect(name.required).toBe(true);
+    expect(name.validation?.maxLength).toBe(200);
+
+    const desc = wf.fields.find(f => f.name === 'description')!;
+    expect(desc.type).toBe('rich_text');
+
+    const priority = wf.fields.find(f => f.name === 'priority')!;
+    expect(priority.type).toBe('select');
+    expect(priority.required).toBe(true);
+    expect(priority.default_value).toBe('medium');
+    expect(priority.validation?.options).toEqual(['low', 'medium', 'high', 'critical']);
+
+    const totalTasks = wf.fields.find(f => f.name === 'total_tasks')!;
+    expect(totalTasks.type).toBe('number');
+    expect(totalTasks.default_value).toBe(0);
+    expect(totalTasks.validation?.min).toBe(0);
+
+    const startedAt = wf.fields.find(f => f.name === 'started_at')!;
+    expect(startedAt.type).toBe('datetime');
+  });
+
+  it('project workflow: transitions with guards and auto', () => {
+    const wf = findWorkflow(result, 'project')!;
+    // activate, auto complete, manual complete, cancel
+    expect(wf.transitions.length).toBeGreaterThanOrEqual(4);
+
+    const autoComplete = wf.transitions.find(t => t.name === 'auto-complete');
+    expect(autoComplete).toBeDefined();
+    expect(autoComplete!.auto).toBe(true);
+    expect(autoComplete!.conditions).toBeDefined();
+
+    const manualComplete = wf.transitions.find(t => t.name === 'manual-complete');
+    expect(manualComplete).toBeDefined();
+    expect(manualComplete!.roles).toEqual(['admin']);
+  });
+
+  it('project workflow: on_enter and on_event actions', () => {
+    const wf = findWorkflow(result, 'project')!;
+
+    // active state should have on_enter and on_event
+    const active = wf.states.find(s => s.name === 'active')!;
+    expect(active.on_enter.length).toBeGreaterThanOrEqual(1);
+    expect(active.on_enter[0].config.field).toBe('started_at');
+    expect(active.on_event).toBeDefined();
+    expect(active.on_event!.length).toBeGreaterThanOrEqual(2);
+
+    // completed state should have on_enter
+    const completed = wf.states.find(s => s.name === 'completed')!;
+    expect(completed.on_enter.length).toBeGreaterThanOrEqual(1);
+    expect(completed.on_enter[0].config.field).toBe('completed_at');
+  });
+
+  it('task workflow: states and transitions', () => {
+    const wf = findWorkflow(result, 'task')!;
+    expect(wf.states).toHaveLength(4); // todo, in progress, done, cancelled
+    expect(wf.states.find(s => s.name === 'todo')!.type).toBe('START');
+    expect(wf.states.find(s => s.name === 'in progress')!.type).toBe('REGULAR');
+    expect(wf.states.find(s => s.name === 'done')!.type).toBe('END');
+
+    // start, complete, cancel transitions
+    expect(wf.transitions.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('task workflow: 8 fields', () => {
+    const wf = findWorkflow(result, 'task')!;
+    expect(wf.fields).toHaveLength(8);
+
+    const statusLabel = wf.fields.find(f => f.name === 'status_label')!;
+    expect(statusLabel.computed).toBe('');
+
+    const xpReward = wf.fields.find(f => f.name === 'xp_reward')!;
+    expect(xpReward.type).toBe('number');
+    expect(xpReward.default_value).toBe(25);
+    expect(xpReward.validation?.min).toBe(0);
+  });
+
+  it('user-stats workflow: on_event subscriptions', () => {
+    const wf = findWorkflow(result, 'user-stats')!;
+    const active = wf.states.find(s => s.name === 'active')!;
+    expect(active.on_event).toBeDefined();
+    expect(active.on_event!.length).toBeGreaterThanOrEqual(2);
+
+    // First subscription: task completed
+    const taskSub = active.on_event!.find(e => e.match.includes('task'));
+    expect(taskSub).toBeDefined();
+    expect(taskSub!.actions.length).toBeGreaterThanOrEqual(3);
+
+    // Check that total_xp expression references $event
+    const xpAction = taskSub!.actions.find(a => a.field === 'total_xp');
+    expect(xpAction?.expression).toContain('$event.state_data.xp_reward');
+  });
+
+  it('user-stats workflow: levels in metadata', () => {
+    const wf = findWorkflow(result, 'user-stats')!;
+    expect(wf.metadata?.levels).toBeDefined();
+    const levels = wf.metadata!.levels as Array<{ level: number; title: string; fromXp: number }>;
+    expect(levels).toHaveLength(8);
+    expect(levels[0]).toEqual({ level: 1, title: 'Newcomer', fromXp: 0 });
+    expect(levels[7]).toEqual({ level: 8, title: 'Legend', fromXp: 2500 });
+  });
+
+  it('manifest: 3 workflow entries and 5 routes', () => {
+    expect(result.manifest).toBeDefined();
+    expect(result.manifest!.workflows).toHaveLength(3);
+    expect(result.manifest!.routes).toHaveLength(5);
+    expect(result.manifest!.experience_id).toBe('project-management');
+
+    // Verify route structure
+    const projectsRoute = result.manifest!.routes!.find(r => r.path === '/projects');
+    expect(projectsRoute).toMatchObject({
+      node: 'project-list',
+      entityType: 'user',
+      entityIdSource: 'user',
+    });
+
+    const projectViewRoute = result.manifest!.routes!.find(r => r.path === '/projects/:id');
+    expect(projectViewRoute).toMatchObject({
+      node: 'project-view',
+      entityType: 'project',
+      entityIdSource: 'param',
+    });
+  });
+});