@mmapp/react-compiler 0.1.0-alpha.1

package/src/__tests__/define-blueprint.test.ts

@@ -0,0 +1,133 @@
+/**
+ * defineBlueprint Tests — validates blueprint configuration and manifest generation.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { defineBlueprint } from '../../../react/src/config/defineBlueprint';
+
+describe('defineBlueprint', () => {
+  it('should create a manifest with defaults applied', () => {
+    const manifest = defineBlueprint({
+      slug: 'my-app',
+      name: 'My App',
+      version: '1.0.0',
+    });
+
+    expect(manifest.slug).toBe('my-app');
+    expect(manifest.name).toBe('My App');
+    expect(manifest.version).toBe('1.0.0');
+    expect(manifest.mode).toBe('infer');
+    expect(manifest.defaultRuntime).toBe('local');
+    expect(manifest.category).toBe('blueprint');
+  });
+
+  it('should preserve explicit mode', () => {
+    const manifest = defineBlueprint({
+      slug: 'strict-app',
+      name: 'Strict App',
+      version: '1.0.0',
+      mode: 'strict',
+    });
+
+    expect(manifest.mode).toBe('strict');
+  });
+
+  it('should preserve explicit runtime', () => {
+    const manifest = defineBlueprint({
+      slug: 'collab-app',
+      name: 'Collab App',
+      version: '1.0.0',
+      defaultRuntime: 'collaborative',
+    });
+
+    expect(manifest.defaultRuntime).toBe('collaborative');
+  });
+
+  it('should preserve contributes_to', () => {
+    const manifest = defineBlueprint({
+      slug: 'plugin-app',
+      name: 'Plugin',
+      version: '1.0.0',
+      contributes_to: {
+        'mm-dashboard': {
+          sidebar: ['ChatSidebar'],
+          toolbar: ['ChatToolbar'],
+        },
+      },
+    });
+
+    expect(manifest.contributes_to).toBeDefined();
+    expect(manifest.contributes_to!['mm-dashboard'].sidebar).toEqual(['ChatSidebar']);
+  });
+
+  it('should throw for missing slug', () => {
+    expect(() => defineBlueprint({
+      slug: '',
+      name: 'No Slug',
+      version: '1.0.0',
+    })).toThrow('slug is required');
+  });
+
+  it('should throw for missing name', () => {
+    expect(() => defineBlueprint({
+      slug: 'test',
+      name: '',
+      version: '1.0.0',
+    })).toThrow('name is required');
+  });
+
+  it('should throw for missing version', () => {
+    expect(() => defineBlueprint({
+      slug: 'test',
+      name: 'Test',
+      version: '',
+    })).toThrow('version is required');
+  });
+
+  it('should throw for non-kebab-case slug', () => {
+    expect(() => defineBlueprint({
+      slug: 'MyApp',
+      name: 'My App',
+      version: '1.0.0',
+    })).toThrow('kebab-case');
+  });
+
+  it('should throw for invalid version format', () => {
+    expect(() => defineBlueprint({
+      slug: 'test',
+      name: 'Test',
+      version: 'abc',
+    })).toThrow('semver');
+  });
+
+  it('should accept valid semver versions', () => {
+    const manifest = defineBlueprint({
+      slug: 'test',
+      name: 'Test',
+      version: '0.1.0-beta.1',
+    });
+    expect(manifest.version).toBe('0.1.0-beta.1');
+  });
+
+  it('should preserve description', () => {
+    const manifest = defineBlueprint({
+      slug: 'test',
+      name: 'Test',
+      version: '1.0.0',
+      description: 'A test blueprint',
+    });
+    expect(manifest.description).toBe('A test blueprint');
+  });
+
+  it('should preserve entries and models paths', () => {
+    const manifest = defineBlueprint({
+      slug: 'test',
+      name: 'Test',
+      version: '1.0.0',
+      entries: ['app/page.tsx', 'app/settings/page.tsx'],
+      models: ['models/channel.ts', 'models/message.ts'],
+    });
+    expect(manifest.entries).toEqual(['app/page.tsx', 'app/settings/page.tsx']);
+    expect(manifest.models).toEqual(['models/channel.ts', 'models/message.ts']);
+  });
+});

package/src/__tests__/definition-validator.test.ts

@@ -0,0 +1,519 @@
+/**
+ * Definition Validator Tests — validates structural, referential,
+ * semantic, and experience tree validation of compiled IR.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { validateDefinition, isViableDefinition } from '@mindmatrix/player-core';
+import type { IRWorkflowDefinition } from '@mindmatrix/player-core';
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function createMinimalDefinition(overrides: Partial<IRWorkflowDefinition> = {}): IRWorkflowDefinition {
+  return {
+    slug: 'test-workflow',
+    name: 'Test Workflow',
+    version: '1.0.0',
+    category: 'test',
+    states: [
+      { name: 'draft', type: 'START', on_enter: [], during: [], on_exit: [] },
+      { name: 'active', type: 'REGULAR', on_enter: [], during: [], on_exit: [] },
+    ],
+    transitions: [
+      { name: 'activate', from: ['draft'], to: 'active', actions: [] },
+    ],
+    fields: [
+      { name: 'title', type: 'text', default_value: '' },
+    ],
+    roles: [],
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Structural Validation
+// =============================================================================
+
+describe('Structural Validation', () => {
+  it('should pass for a valid minimal definition', () => {
+    const def = createMinimalDefinition();
+    const result = validateDefinition(def);
+    expect(result.valid).toBe(true);
+    expect(result.errorCount).toBe(0);
+  });
+
+  it('should error on missing slug', () => {
+    const def = createMinimalDefinition({ slug: '' });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'MISSING_SLUG')).toBe(true);
+  });
+
+  it('should warn on missing name', () => {
+    const def = createMinimalDefinition({ name: '' });
+    const result = validateDefinition(def);
+    const issue = result.issues.find(i => i.code === 'MISSING_NAME');
+    expect(issue).toBeDefined();
+    expect(issue!.severity).toBe('warning');
+  });
+
+  it('should error on no states', () => {
+    const def = createMinimalDefinition({ states: [] });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'NO_STATES')).toBe(true);
+    expect(result.valid).toBe(false);
+  });
+
+  it('should error on state missing type', () => {
+    const def = createMinimalDefinition({
+      states: [{ name: 'draft', type: '' as any, on_enter: [], during: [], on_exit: [] }],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'STATE_MISSING_TYPE')).toBe(true);
+  });
+
+  it('should error on duplicate field names', () => {
+    const def = createMinimalDefinition({
+      fields: [
+        { name: 'title', type: 'text', default_value: '' },
+        { name: 'title', type: 'number', default_value: 0 },
+      ],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'DUPLICATE_FIELD')).toBe(true);
+  });
+
+  it('should error on transition missing from', () => {
+    const def = createMinimalDefinition({
+      transitions: [{ name: 'go', from: [], to: 'active', actions: [] }],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'TRANSITION_MISSING_FROM')).toBe(true);
+  });
+
+  it('should error on transition missing to', () => {
+    const def = createMinimalDefinition({
+      transitions: [{ name: 'go', from: ['draft'], to: '', actions: [] }],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'TRANSITION_MISSING_TO')).toBe(true);
+  });
+
+  it('should validate during action structure', () => {
+    const def = createMinimalDefinition({
+      states: [
+        {
+          name: 'draft', type: 'START', on_enter: [], on_exit: [],
+          during: [{ id: 'd1', type: 'interval', actions: [] }], // missing interval_ms
+        },
+      ],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'DURING_MISSING_INTERVAL')).toBe(true);
+  });
+});
+
+// =============================================================================
+// Referential Validation
+// =============================================================================
+
+describe('Referential Validation', () => {
+  it('should error on transition referencing unknown from state', () => {
+    const def = createMinimalDefinition({
+      transitions: [
+        { name: 'activate', from: ['nonexistent'], to: 'active', actions: [] },
+      ],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'TRANSITION_UNKNOWN_FROM')).toBe(true);
+  });
+
+  it('should error on transition referencing unknown to state', () => {
+    const def = createMinimalDefinition({
+      transitions: [
+        { name: 'activate', from: ['draft'], to: 'nonexistent', actions: [] },
+      ],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'TRANSITION_UNKNOWN_TO')).toBe(true);
+  });
+
+  it('should warn on set_field action referencing unknown field', () => {
+    const def = createMinimalDefinition({
+      states: [{
+        name: 'draft', type: 'START', during: [], on_exit: [],
+        on_enter: [{ id: 'a1', type: 'set_field', mode: 'auto', config: { field: 'nonexistent', value: 'x' } }],
+      }],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'ACTION_UNKNOWN_FIELD')).toBe(true);
+  });
+
+  it('should warn on field visible_in_states referencing unknown state', () => {
+    const def = createMinimalDefinition({
+      fields: [{ name: 'title', type: 'text', visible_in_states: ['nonexistent'] }],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'FIELD_UNKNOWN_STATE')).toBe(true);
+  });
+
+  it('should pass clean referential check on valid definition', () => {
+    const def = createMinimalDefinition();
+    const result = validateDefinition(def);
+    const refIssues = result.issues.filter(i => i.category === 'referential');
+    expect(refIssues).toHaveLength(0);
+  });
+});
+
+// =============================================================================
+// Semantic Validation
+// =============================================================================
+
+describe('Semantic Validation', () => {
+  it('should error on no START state', () => {
+    const def = createMinimalDefinition({
+      states: [
+        { name: 'active', type: 'REGULAR', on_enter: [], during: [], on_exit: [] },
+      ],
+      transitions: [],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'NO_START_STATE')).toBe(true);
+  });
+
+  it('should error on multiple START states', () => {
+    const def = createMinimalDefinition({
+      states: [
+        { name: 'draft', type: 'START', on_enter: [], during: [], on_exit: [] },
+        { name: 'init', type: 'START', on_enter: [], during: [], on_exit: [] },
+      ],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'MULTIPLE_START_STATES')).toBe(true);
+  });
+
+  it('should error on duplicate state names', () => {
+    const def = createMinimalDefinition({
+      states: [
+        { name: 'draft', type: 'START', on_enter: [], during: [], on_exit: [] },
+        { name: 'draft', type: 'REGULAR', on_enter: [], during: [], on_exit: [] },
+      ],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'DUPLICATE_STATE')).toBe(true);
+  });
+
+  it('should warn on unreachable states', () => {
+    const def = createMinimalDefinition({
+      states: [
+        { name: 'draft', type: 'START', on_enter: [], during: [], on_exit: [] },
+        { name: 'active', type: 'REGULAR', on_enter: [], during: [], on_exit: [] },
+        { name: 'orphan', type: 'REGULAR', on_enter: [], during: [], on_exit: [] },
+      ],
+      transitions: [
+        { name: 'activate', from: ['draft'], to: 'active', actions: [] },
+      ],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'UNREACHABLE_STATE' && i.message.includes('orphan'))).toBe(true);
+  });
+
+  it('should warn on dead-end non-END states', () => {
+    const def = createMinimalDefinition({
+      states: [
+        { name: 'draft', type: 'START', on_enter: [], during: [], on_exit: [] },
+        { name: 'stuck', type: 'REGULAR', on_enter: [], during: [], on_exit: [] },
+      ],
+      transitions: [
+        { name: 'go', from: ['draft'], to: 'stuck', actions: [] },
+      ],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'DEAD_END_STATE')).toBe(true);
+  });
+
+  it('should not warn on dead-end END states', () => {
+    const def = createMinimalDefinition({
+      states: [
+        { name: 'draft', type: 'START', on_enter: [], during: [], on_exit: [] },
+        { name: 'done', type: 'END', on_enter: [], during: [], on_exit: [] },
+      ],
+      transitions: [
+        { name: 'complete', from: ['draft'], to: 'done', actions: [] },
+      ],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'DEAD_END_STATE')).toBe(false);
+  });
+
+  it('should warn on transitions from END states', () => {
+    const def = createMinimalDefinition({
+      states: [
+        { name: 'draft', type: 'START', on_enter: [], during: [], on_exit: [] },
+        { name: 'done', type: 'END', on_enter: [], during: [], on_exit: [] },
+      ],
+      transitions: [
+        { name: 'complete', from: ['draft'], to: 'done', actions: [] },
+        { name: 'reopen', from: ['done'], to: 'draft', actions: [] },
+      ],
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'TRANSITION_FROM_END')).toBe(true);
+  });
+});
+
+// =============================================================================
+// Experience Tree Validation
+// =============================================================================
+
+describe('Experience Tree Validation', () => {
+  it('should warn on unknown component', () => {
+    const def = createMinimalDefinition({
+      metadata: {
+        experience: {
+          id: 'root',
+          component: 'SuperWidget',
+          children: [],
+        },
+      },
+    });
+    const result = validateDefinition(def, {
+      knownComponents: ['Stack', 'Button', 'Text'],
+    });
+    expect(result.issues.some(i => i.code === 'UNKNOWN_COMPONENT')).toBe(true);
+  });
+
+  it('should not warn when component is known', () => {
+    const def = createMinimalDefinition({
+      metadata: {
+        experience: {
+          id: 'root',
+          component: 'Stack',
+          children: [],
+        },
+      },
+    });
+    const result = validateDefinition(def, {
+      knownComponents: ['Stack', 'Button', 'Text'],
+    });
+    expect(result.issues.some(i => i.code === 'UNKNOWN_COMPONENT')).toBe(false);
+  });
+
+  it('should warn on unknown binding root', () => {
+    const def = createMinimalDefinition({
+      metadata: {
+        experience: {
+          id: 'root',
+          component: 'Text',
+          bindings: { text: '$unknown.field' },
+          children: [],
+        },
+      },
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'UNKNOWN_BINDING_ROOT')).toBe(true);
+  });
+
+  it('should accept known binding roots', () => {
+    const def = createMinimalDefinition({
+      metadata: {
+        experience: {
+          id: 'root',
+          component: 'Text',
+          bindings: { text: '$instance.count' },
+          children: [],
+        },
+      },
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'UNKNOWN_BINDING_ROOT')).toBe(false);
+  });
+
+  it('should warn on duplicate child IDs', () => {
+    const def = createMinimalDefinition({
+      metadata: {
+        experience: {
+          id: 'root',
+          component: 'Stack',
+          children: [
+            { id: 'btn', component: 'Button', children: [] },
+            { id: 'btn', component: 'Button', children: [] },
+          ],
+        },
+      },
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.some(i => i.code === 'DUPLICATE_NODE_ID')).toBe(true);
+  });
+
+  it('should skip experience validation when option set', () => {
+    const def = createMinimalDefinition({
+      metadata: {
+        experience: {
+          id: 'root',
+          component: 'FakeComponent',
+          children: [],
+        },
+      },
+    });
+    const result = validateDefinition(def, {
+      knownComponents: ['Stack'],
+      skipExperience: true,
+    });
+    expect(result.issues.some(i => i.code === 'UNKNOWN_COMPONENT')).toBe(false);
+  });
+
+  it('should accept literal bindings', () => {
+    const def = createMinimalDefinition({
+      metadata: {
+        experience: {
+          id: 'root',
+          component: 'Text',
+          bindings: { text: '"Hello"' },
+          children: [],
+        },
+      },
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.filter(i => i.category === 'experience')).toHaveLength(0);
+  });
+
+  it('should accept transition.fire bindings', () => {
+    const def = createMinimalDefinition({
+      metadata: {
+        experience: {
+          id: 'root',
+          component: 'Button',
+          bindings: { onPress: 'start.fire' },
+          children: [],
+        },
+      },
+    });
+    const result = validateDefinition(def);
+    expect(result.issues.filter(i => i.category === 'experience')).toHaveLength(0);
+  });
+});
+
+// =============================================================================
+// isViableDefinition
+// =============================================================================
+
+describe('isViableDefinition', () => {
+  it('should return true for valid definition', () => {
+    const def = createMinimalDefinition();
+    expect(isViableDefinition(def)).toBe(true);
+  });
+
+  it('should return false for null', () => {
+    expect(isViableDefinition(null)).toBe(false);
+  });
+
+  it('should return false for empty object', () => {
+    expect(isViableDefinition({})).toBe(false);
+  });
+
+  it('should return false for definition without states', () => {
+    expect(isViableDefinition({ slug: 'test', states: [], transitions: [], fields: [] })).toBe(false);
+  });
+
+  it('should return false for definition without slug', () => {
+    expect(isViableDefinition({
+      states: [{ name: 'draft' }],
+      transitions: [],
+      fields: [],
+    })).toBe(false);
+  });
+});
+
+// =============================================================================
+// Summary Statistics
+// =============================================================================
+
+describe('Validation Summary', () => {
+  it('should report correct summary statistics', () => {
+    const def = createMinimalDefinition();
+    const result = validateDefinition(def);
+    expect(result.summary.stateCount).toBe(2);
+    expect(result.summary.transitionCount).toBe(1);
+    expect(result.summary.fieldCount).toBe(1);
+    expect(result.summary.hasExperience).toBe(false);
+    expect(result.summary.hasExtensions).toBe(false);
+  });
+
+  it('should detect experience presence', () => {
+    const def = createMinimalDefinition({
+      metadata: {
+        experience: { id: 'root', component: 'Stack', children: [] },
+      },
+    });
+    const result = validateDefinition(def);
+    expect(result.summary.hasExperience).toBe(true);
+  });
+
+  it('should detect extensions presence', () => {
+    const def = createMinimalDefinition({
+      extensions: { cedar: [{ slug: 'test', contextTag: 'cedar', rawSource: '' }] },
+    });
+    const result = validateDefinition(def);
+    expect(result.summary.hasExtensions).toBe(true);
+  });
+});
+
+// =============================================================================
+// Compiled Output Validation (real-world counter.json format)
+// =============================================================================
+
+describe('Compiled Output Validation', () => {
+  it('should validate compiled counter.json format (v1.0 with state_type/action_type)', () => {
+    const compiled = {
+      slug: 'counter',
+      name: 'Counter',
+      version: '1.0.0',
+      category: 'demo',
+      states: [
+        {
+          name: 'idle',
+          state_type: 'START',
+          on_enter: [{ id: 'a1', action_type: 'set_field', config: { field: 'status', value: 'idle' } }],
+          on_exit: [],
+          during: [],
+        },
+        {
+          name: 'counting',
+          state_type: 'REGULAR',
+          on_enter: [],
+          on_exit: [],
+          during: [{ id: 'd1', type: 'interval', interval_ms: 1000, actions: [] }],
+        },
+      ],
+      transitions: [
+        { name: 'start', from: ['idle'], to: 'counting', actions: [] },
+      ],
+      fields: [
+        { name: 'count', field_type: 'number', default_value: 0 },
+        { name: 'status', field_type: 'text', default_value: 'idle' },
+      ],
+      roles: [],
+      metadata: {
+        experience: {
+          id: 'stack_1',
+          component: 'Stack',
+          children: [
+            { id: 'text_1', component: 'Text', bindings: { text: '$instance.count' }, children: [] },
+            {
+              id: 'btn_1', component: 'Button',
+              bindings: { onPress: 'start.fire' },
+              children: [],
+            },
+          ],
+        },
+      },
+    };
+
+    // The validator accepts both v1.0 (state_type/action_type/field_type) and v1.1+ (type) formats
+    const result = validateDefinition(compiled as any);
+    expect(result.valid).toBe(true);
+    expect(result.errorCount).toBe(0);
+  });
+});