@mmapp/react-compiler 0.1.0-alpha.1

package/src/__tests__/golden-suite.test.ts

@@ -0,0 +1,403 @@
+/**
+ * Golden Test Suite — snapshot-based tests verifying complete compiler output.
+ *
+ * Each test compiles a workflow and validates the IR structure matches
+ * the expected shape. These are the "contract tests" for the compiler.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { transformSync } from '@babel/core';
+import babelPlugin from '../babel';
+import type { IRWorkflowDefinition } from '@mindmatrix/player-core';
+
+function compileWorkflow(code: string, filename = 'test.workflow.tsx'): IRWorkflowDefinition {
+  const result = transformSync(code, {
+    filename,
+    plugins: [[babelPlugin]],
+    parserOpts: { plugins: ['typescript', 'jsx'], attachComment: true },
+  });
+  return (result as any)?.metadata?.mindmatrixIR;
+}
+
+function compileModel(code: string, filename = 'models/test.ts'): IRWorkflowDefinition {
+  const result = transformSync(code, {
+    filename,
+    plugins: [[babelPlugin, { mode: 'strict' }]],
+    parserOpts: { plugins: ['typescript'], attachComment: true },
+  });
+  return (result as any)?.metadata?.mindmatrixIR;
+}
+
+describe('Golden Suite', () => {
+  // =========================================================================
+  // 1. Basic Counter — simplest valid workflow
+  // =========================================================================
+  it('golden: basic counter workflow', () => {
+    const ir = compileWorkflow(`
+      /**
+       * @workflow slug="counter" version="1.0.0"
+       */
+      import { useState } from 'react';
+      import { useOnEnter, useTransition } from '@mindmatrix/react';
+
+      export function Counter() {
+        const [count, setCount] = useState(0);
+        const [status, setStatus] = useState('idle');
+
+        useOnEnter('counting', () => {
+          setCount(0);
+        });
+
+        useTransition('increment', { from: 'counting', to: 'counting' });
+        useTransition('reset', { from: 'counting', to: 'idle' });
+
+        return (
+          <Stack>
+            <Heading>Counter: {count}</Heading>
+            <Button onClick={() => {}}>Increment</Button>
+          </Stack>
+        );
+      }
+    `);
+
+    // Structure assertions
+    expect(ir.slug).toBe('counter');
+    expect(ir.version).toBe('1.0.0');
+    expect(ir.fields).toHaveLength(2);
+    expect(ir.fields.find((f) => f.name === 'count')?.type).toBe('number');
+    expect(ir.fields.find((f) => f.name === 'status')?.type).toBe('text');
+
+    // States: at minimum 1 state (draft START), plus counting + idle from hooks
+    expect(ir.states.length).toBeGreaterThanOrEqual(1);
+
+    // Transitions from useTransition hooks
+    expect(ir.transitions.length).toBeGreaterThanOrEqual(2);
+
+    // State with on_enter (from useOnEnter)
+    const countingState = ir.states.find((s) => s.name === 'counting');
+    if (countingState) {
+      expect(countingState.on_enter.length).toBeGreaterThanOrEqual(1);
+    }
+
+    // Experience node from JSX return
+    expect(ir.metadata?.experience).toBeDefined();
+  });
+
+  // =========================================================================
+  // 2. Model with transitions and guards
+  // =========================================================================
+  it('golden: model file with guards and hooks', () => {
+    const ir = compileModel(`
+      export interface Task {
+        title: string;
+        assignee?: string;
+        status: 'draft' | 'active' | 'completed' | 'archived';
+        priority: number;
+      }
+
+      export const transitions = {
+        activate: {
+          from: 'draft',
+          to: 'active',
+          guard: '$assignee != ""',
+          required_fields: ['title', 'assignee'],
+        },
+        complete: {
+          from: 'active',
+          to: 'completed',
+          roles: ['owner', 'admin'],
+        },
+        archive: {
+          from: ['completed', 'draft'],
+          to: 'archived',
+        },
+      };
+
+      export const hooks = {
+        on_enter_active: {
+          emit: 'task:activated',
+          actions: ['notifyAssignee'],
+        },
+      };
+
+      export const endStates = ['archived'];
+      export const runtime = 'backend';
+    `);
+
+    // Fields
+    expect(ir.fields).toHaveLength(4);
+    expect(ir.fields.find((f) => f.name === 'title')?.type).toBe('text');
+    expect(ir.fields.find((f) => f.name === 'status')?.type).toBe('select');
+    expect(ir.fields.find((f) => f.name === 'priority')?.type).toBe('number');
+    expect(ir.fields.find((f) => f.name === 'assignee')?.required).toBe(false);
+
+    // Transitions
+    expect(ir.transitions).toHaveLength(3);
+    const activate = ir.transitions.find((t) => t.name === 'activate');
+    // Model transitions store from as arrays (can be multi-source)
+    expect(activate?.from).toEqual(['draft']);
+    expect(activate?.to).toBe('active');
+    expect(activate?.conditions).toBeDefined();
+    expect(activate!.conditions!.length).toBeGreaterThanOrEqual(1);
+
+    const complete = ir.transitions.find((t) => t.name === 'complete');
+    expect(complete?.from).toEqual(['active']);
+    expect(complete?.to).toBe('completed');
+
+    // States
+    const archivedState = ir.states.find((s) => s.name === 'archived');
+    expect(archivedState?.type).toBe('END');
+
+    // Hooks
+    const activeState = ir.states.find((s) => s.name === 'active');
+    expect(activeState?.on_enter.length).toBeGreaterThanOrEqual(1);
+
+    // Runtime
+    expect(ir.metadata?.runtime).toBe('backend');
+  });
+
+  // =========================================================================
+  // 3. Grammar islands in model
+  // =========================================================================
+  it('golden: model with grammar islands', () => {
+    const ir = compileModel(`
+      export interface Order {
+        status: 'draft' | 'submitted' | 'approved';
+        amount: number;
+      }
+
+      export const transitions = {
+        submit: { from: 'draft', to: 'submitted' },
+        approve: { from: 'submitted', to: 'approved' },
+      };
+
+      export const access = cedar\`
+        permit (principal, action == Action::"read", resource)
+        when { principal.role == "member" };
+      \`;
+
+      export const cleanup = cron\`0 3 * * *\`;
+    `);
+
+    // Grammar islands in extensions
+    expect(ir.extensions).toBeDefined();
+    expect(ir.extensions!.cedar).toHaveLength(1);
+    expect(ir.extensions!.cron).toHaveLength(1);
+
+    // Cedar parsed
+    const cedarIsland = ir.extensions!.cedar[0];
+    expect(cedarIsland.contextTag).toBe('cedar');
+    const parsed = cedarIsland.parsed as any;
+    expect(parsed.policies).toHaveLength(1);
+    expect(parsed.policies[0].effect).toBe('permit');
+
+    // Cron parsed
+    const cronIsland = ir.extensions!.cron[0];
+    const cronParsed = cronIsland.parsed as any;
+    expect(cronParsed.valid).toBe(true);
+    expect(cronParsed.fields.hour).toBe('3');
+  });
+
+  // =========================================================================
+  // 4. Server action file
+  // =========================================================================
+  it('golden: server action file', () => {
+    const ir = compileWorkflow(`
+      export async function notifyMembers(ctx: TransitionContext) {
+        // Server action
+      }
+
+      export function logEvent(ctx: TransitionContext) {
+        // Sync action
+      }
+
+      export const sendEmail = async (ctx: TransitionContext) => {
+        // Arrow function
+      };
+    `, 'actions.server.ts');
+
+    const actions = ir.metadata?.serverActions as any[];
+    expect(actions).toBeDefined();
+    expect(actions).toHaveLength(3);
+    expect(actions.find((a: any) => a.name === 'notifyMembers')?.async).toBe(true);
+    expect(actions.find((a: any) => a.name === 'logEvent')?.async).toBe(false);
+    expect(actions.find((a: any) => a.name === 'sendEmail')?.async).toBe(true);
+  });
+
+  // =========================================================================
+  // 5. Data hooks (useQuery + useMutation)
+  // =========================================================================
+  it('golden: useQuery and useMutation extraction', () => {
+    const ir = compileWorkflow(`
+      import { useState } from 'react';
+      import { useQuery, useMutation } from '@mindmatrix/react';
+
+      export function Dashboard() {
+        const [view, setView] = useState('list');
+        const { data: channels } = useQuery('channel', { limit: 50, orderBy: 'created_at' });
+        const { data: messages } = useQuery('message', { search: 'content' });
+        const channelMutation = useMutation('channel');
+        const messageMutation = useMutation('message');
+
+        return <div />;
+      }
+    `);
+
+    const dataSources = (ir.metadata as any).dataSources;
+    expect(dataSources).toHaveLength(2);
+    expect(dataSources[0].slug).toBe('channel');
+    expect(dataSources[0].pageSize).toBe(50);
+    expect(dataSources[0].sort).toBe('created_at');
+    expect(dataSources[1].slug).toBe('message');
+    expect(dataSources[1].search).toBe('content');
+
+    const targets = (ir.metadata as any).mutationTargets;
+    expect(targets).toHaveLength(2);
+    expect(targets).toContain('channel');
+    expect(targets).toContain('message');
+  });
+
+  // =========================================================================
+  // 6. Strict mode validation
+  // =========================================================================
+  it('golden: strict mode catches forbidden hooks', () => {
+    const result = transformSync(`
+      import { useEffect, useState } from 'react';
+      export function BadComponent() {
+        useEffect(() => {}, []);
+        return <div />;
+      }
+    `, {
+      filename: 'test.workflow.tsx',
+      plugins: [[babelPlugin, { mode: 'strict' }]],
+      parserOpts: { plugins: ['typescript', 'jsx'], attachComment: true },
+    });
+
+    const ir = (result as any)?.metadata?.mindmatrixIR;
+    expect(ir.metadata?.errors).toBeDefined();
+    const errors = (ir.metadata as any).errors;
+    expect(errors.length).toBeGreaterThanOrEqual(1);
+    expect(errors[0].code).toBe('STRICT_USE_EFFECT');
+  });
+
+  // =========================================================================
+  // 7. Context workflow extraction
+  // =========================================================================
+  it('golden: context with reducer', () => {
+    const ir = compileWorkflow(`
+      import { createContext, useReducer } from 'react';
+
+      interface AppState {
+        theme: string;
+        count: number;
+      }
+
+      function appReducer(state: AppState, action: { type: string }) {
+        switch (action.type) {
+          case 'TOGGLE_THEME': return { ...state, theme: state.theme === 'dark' ? 'light' : 'dark' };
+          case 'INCREMENT': return { ...state, count: state.count + 1 };
+          default: return state;
+        }
+      }
+
+      const AppContext = createContext<AppState>({ theme: 'light', count: 0 });
+
+      export function AppProvider({ children }: any) {
+        const [state, dispatch] = useReducer(appReducer, { theme: 'light', count: 0 });
+        return <AppContext.Provider value={state}>{children}</AppContext.Provider>;
+      }
+    `);
+
+    const workflows = (ir.metadata as any).contextWorkflows;
+    expect(workflows).toHaveLength(1);
+    expect(workflows[0].name).toBe('AppContext');
+    expect(workflows[0].fields).toHaveLength(2);
+    expect(workflows[0].reducerActions).toHaveLength(2);
+    expect(workflows[0].reducerActions.map((a: any) => a.type)).toContain('TOGGLE_THEME');
+    expect(workflows[0].reducerActions.map((a: any) => a.type)).toContain('INCREMENT');
+  });
+
+  // =========================================================================
+  // 8. Complete workflow with all features
+  // =========================================================================
+  it('golden: full-featured workflow component', () => {
+    const ir = compileWorkflow(`
+      /**
+       * @workflow slug="chat-channel" version="2.0.0" category="blueprint"
+       * @description Chat channel workflow
+       */
+      import { useState } from 'react';
+      import { useOnEnter, useOnExit, useTransition, useOnEvent, useWhileIn, useOnChange, useOnTransition, useQuery } from '@mindmatrix/react';
+
+      export function ChatChannel() {
+        const [name, setName] = useState('');
+        const [status, setStatus] = useState('draft');
+        const [memberCount, setMemberCount] = useState(0);
+
+        useOnEnter('active', () => { setMemberCount(0); });
+        useOnExit('active', () => { setMemberCount(0); });
+
+        useTransition('activate', { from: 'draft', to: 'active' });
+        useTransition('archive', { from: 'active', to: 'archived' });
+        useTransition('deactivate', { from: 'active', to: 'draft' });
+
+        useOnEvent('member:joined', () => {});
+        useWhileIn('active', 5000, () => {});
+        useOnChange('name', () => {});
+        useOnTransition(() => {});
+
+        const { data: messages } = useQuery('message');
+
+        return (
+          <Stack>
+            <Heading>{name}</Heading>
+            <Text>Members: {memberCount}</Text>
+          </Stack>
+        );
+      }
+    `);
+
+    // Metadata
+    expect(ir.slug).toBe('chat-channel');
+    expect(ir.version).toBe('2.0.0');
+    expect(ir.category).toBe('blueprint');
+    expect(ir.description).toBe('Chat channel workflow');
+
+    // Fields (3 from useState calls)
+    expect(ir.fields).toHaveLength(3);
+
+    // States — at minimum START state; useTransition creates additional states
+    expect(ir.states.length).toBeGreaterThanOrEqual(1);
+
+    // Check that hooks were processed
+    const activeState = ir.states.find((s) => s.name === 'active');
+    if (activeState) {
+      // useOnEnter('active', ...) → on_enter action
+      expect(activeState.on_enter.length).toBeGreaterThanOrEqual(1);
+      // useOnExit('active', ...) → on_exit action
+      expect(activeState.on_exit.length).toBeGreaterThanOrEqual(1);
+      // useWhileIn('active', ...) → during action
+      if (activeState.during) {
+        expect(activeState.during.length).toBeGreaterThanOrEqual(1);
+      }
+    }
+
+    // Transitions from useTransition calls
+    expect(ir.transitions.length).toBeGreaterThanOrEqual(3);
+
+    // Events from useOnEvent
+    expect(ir.on_event).toBeDefined();
+
+    // Field watchers from useOnChange
+    expect(ir.metadata?.fieldWatchers).toBeDefined();
+
+    // Transition effects from useOnTransition
+    expect(ir.metadata?.transitionEffects).toBeDefined();
+
+    // Data sources from useQuery
+    expect((ir.metadata as any).dataSources).toBeDefined();
+
+    // Experience from JSX return
+    expect(ir.metadata?.experience).toBeDefined();
+  });
+});

package/src/__tests__/grammar-island-extractor.test.ts

@@ -0,0 +1,289 @@
+/**
+ * Grammar Island Extractor Tests — validates tagged template DSL extraction.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { transformSync } from '@babel/core';
+import babelPlugin from '../babel';
+import type { IRWorkflowDefinition } from '@mindmatrix/player-core';
+
+function compile(code: string, filename = 'models/test.ts'): IRWorkflowDefinition {
+  const result = transformSync(code, {
+    filename,
+    plugins: [[babelPlugin, { mode: 'strict' }]],
+    parserOpts: { plugins: ['typescript'], attachComment: true },
+  });
+  return (result as any)?.metadata?.mindmatrixIR;
+}
+
+function compileWorkflow(code: string, filename = 'test.workflow.tsx'): IRWorkflowDefinition {
+  const result = transformSync(code, {
+    filename,
+    plugins: [[babelPlugin]],
+    parserOpts: { plugins: ['typescript', 'jsx'], attachComment: true },
+  });
+  return (result as any)?.metadata?.mindmatrixIR;
+}
+
+describe('Grammar Island Extractor', () => {
+  describe('Cedar', () => {
+    it('should extract cedar tagged template', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const access = cedar\`
+          permit (principal, action == Action::"read", resource)
+          when { principal.role == "member" };
+        \`;
+      `);
+
+      expect(ir.extensions).toBeDefined();
+      expect(ir.extensions!.cedar).toBeDefined();
+      expect(ir.extensions!.cedar).toHaveLength(1);
+      expect(ir.extensions!.cedar[0].contextTag).toBe('cedar');
+      expect(ir.extensions!.cedar[0].slug).toBe('access');
+      expect(ir.extensions!.cedar[0].rawSource).toContain('permit');
+    });
+
+    it('should parse cedar policies', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const access = cedar\`
+          permit (principal, action == Action::"read", resource)
+          when { principal.role == "member" };
+        \`;
+      `);
+
+      const parsed = ir.extensions!.cedar[0].parsed as any;
+      expect(parsed.policies).toBeDefined();
+      expect(parsed.policies).toHaveLength(1);
+      expect(parsed.policies[0].effect).toBe('permit');
+      expect(parsed.policies[0].principal).toBe('principal');
+      expect(parsed.policies[0].action).toContain('Action::"read"');
+    });
+
+    it('should extract multiple cedar policies', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const access = cedar\`
+          permit (principal, action == Action::"read", resource)
+          when { principal.role == "member" };
+          forbid (principal, action == Action::"delete", resource)
+          when { principal.role != "admin" };
+        \`;
+      `);
+
+      const parsed = ir.extensions!.cedar[0].parsed as any;
+      expect(parsed.policies).toHaveLength(2);
+      expect(parsed.policies[0].effect).toBe('permit');
+      expect(parsed.policies[1].effect).toBe('forbid');
+    });
+  });
+
+  describe('SQL', () => {
+    it('should extract sql tagged template', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const computed = {
+          messageCount: sql\`SELECT COUNT(*) FROM messages WHERE channel_id = $instance_id\`,
+        };
+      `);
+
+      expect(ir.extensions).toBeDefined();
+      expect(ir.extensions!.sql).toBeDefined();
+      expect(ir.extensions!.sql).toHaveLength(1);
+      expect(ir.extensions!.sql[0].slug).toBe('messageCount');
+      expect(ir.extensions!.sql[0].rawSource).toContain('SELECT COUNT');
+    });
+
+    it('should parse sql query', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const query = sql\`SELECT * FROM users WHERE active = true\`;
+      `);
+
+      const parsed = ir.extensions!.sql[0].parsed as any;
+      expect(parsed.query).toBe('SELECT * FROM users WHERE active = true');
+    });
+  });
+
+  describe('Cron', () => {
+    it('should extract cron tagged template', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const schedule = {
+          cleanup: cron\`0 3 * * *\`,
+        };
+      `);
+
+      expect(ir.extensions!.cron).toBeDefined();
+      expect(ir.extensions!.cron).toHaveLength(1);
+      expect(ir.extensions!.cron[0].slug).toBe('cleanup');
+    });
+
+    it('should parse cron fields', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const job = cron\`30 14 * * 1-5\`;
+      `);
+
+      const parsed = ir.extensions!.cron[0].parsed as any;
+      expect(parsed.expression).toBe('30 14 * * 1-5');
+      expect(parsed.fields.minute).toBe('30');
+      expect(parsed.fields.hour).toBe('14');
+      expect(parsed.fields.dayOfWeek).toBe('1-5');
+      expect(parsed.valid).toBe(true);
+    });
+
+    it('should flag invalid cron expressions', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const job = cron\`only three fields\`;
+      `);
+
+      const parsed = ir.extensions!.cron[0].parsed as any;
+      expect(parsed.valid).toBe(false);
+    });
+  });
+
+  describe('DMN', () => {
+    it('should extract dmn tagged template', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const rules = dmn\`
+          | age | income | risk   |
+          |-----|--------|--------|
+          | <18 | *      | reject |
+          | >=18| >50000 | low    |
+        \`;
+      `);
+
+      expect(ir.extensions!.dmn).toBeDefined();
+      expect(ir.extensions!.dmn).toHaveLength(1);
+    });
+
+    it('should parse dmn rules', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const rules = dmn\`
+          | age | income | risk   |
+          |-----|--------|--------|
+          | <18 | *      | reject |
+          | >=18| >50000 | low    |
+        \`;
+      `);
+
+      const parsed = ir.extensions!.dmn[0].parsed as any;
+      expect(parsed.headers).toEqual(['age', 'income', 'risk']);
+      expect(parsed.rules).toHaveLength(2);
+      expect(parsed.rules[0].inputs.age).toBe('<18');
+      expect(parsed.rules[0].output.risk).toBe('reject');
+      expect(parsed.rules[1].inputs.age).toBe('>=18');
+    });
+  });
+
+  describe('GraphQL', () => {
+    it('should extract graphql tagged template', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const query = graphql\`
+          query GetChannel($id: ID!) {
+            channel(id: $id) { name }
+          }
+        \`;
+      `);
+
+      expect(ir.extensions!.graphql).toBeDefined();
+      expect(ir.extensions!.graphql[0].rawSource).toContain('GetChannel');
+    });
+  });
+
+  describe('JSONPath', () => {
+    it('should extract jsonpath tagged template', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const path = jsonpath\`$.store.book[?(@.price < 10)]\`;
+      `);
+
+      expect(ir.extensions!.jsonpath).toBeDefined();
+      const parsed = ir.extensions!.jsonpath[0].parsed as any;
+      expect(parsed.expression).toContain('$.store.book');
+    });
+  });
+
+  describe('Multiple islands', () => {
+    it('should extract multiple grammar types in one file', () => {
+      const ir = compile(`
+        export interface Order {
+          status: 'draft' | 'active';
+        }
+        export const transitions = {};
+        export const access = cedar\`
+          permit (principal, action == Action::"read", resource);
+        \`;
+        export const computed = {
+          count: sql\`SELECT COUNT(*) FROM orders\`,
+        };
+        export const schedule = cron\`0 0 * * *\`;
+      `);
+
+      expect(Object.keys(ir.extensions!)).toHaveLength(3);
+      expect(ir.extensions!.cedar).toHaveLength(1);
+      expect(ir.extensions!.sql).toHaveLength(1);
+      expect(ir.extensions!.cron).toHaveLength(1);
+    });
+  });
+
+  describe('Workflow files', () => {
+    it('should extract grammar islands from workflow files too', () => {
+      const ir = compileWorkflow(`
+        import { useState } from 'react';
+        export function OrderWorkflow() {
+          const [status, setStatus] = useState('draft');
+          return <div />;
+        }
+        export const access = cedar\`
+          permit (principal, action == Action::"read", resource);
+        \`;
+      `);
+
+      expect(ir.extensions).toBeDefined();
+      expect(ir.extensions!.cedar).toHaveLength(1);
+    });
+  });
+});