@mmapp/react-compiler 0.1.0-alpha.1 → 0.1.0-alpha.3

package/src/testing/test-utils.ts

@@ -1,226 +0,0 @@
-/**
- * Test Utilities — mock providers and compile helpers for .workflow.tsx unit tests.
- *
- * These wrappers let test authors compile workflow source, inspect IR output,
- * and wrap components in mock providers — without touching the Babel API directly.
- *
- * Usage:
- *   import { compileWorkflow, compileModel, MockBlueprintProvider, MockWorkflowProvider } from '@mindmatrix/react-compiler/testing';
- *
- *   const ir = compileWorkflow(`
- *     import { useState } from 'react';
- *     export function Counter() { ... }
- *   `);
- *   expect(ir.fields).toHaveLength(1);
- */
-
-import { transformSync } from '@babel/core';
-import babelPlugin from '../babel';
-import type { IRWorkflowDefinition } from '@mindmatrix/player-core';
-
-// =============================================================================
-// Compilation Helpers
-// =============================================================================
-
-export interface CompileOptions {
-  /** Compilation mode. Default: 'infer' */
-  mode?: 'strict' | 'infer';
-  /** Override filename (affects file-type detection). */
-  filename?: string;
-}
-
-/**
- * Compile a .workflow.tsx source string to IR.
- * Returns the full IRWorkflowDefinition extracted by the Babel plugin.
- */
-export function compileWorkflow(
-  code: string,
-  options: CompileOptions = {},
-): IRWorkflowDefinition {
-  const filename = options.filename ?? 'test.workflow.tsx';
-  const mode = options.mode ?? 'infer';
-
-  const result = transformSync(code, {
-    filename,
-    plugins: [[babelPlugin, { mode }]],
-    parserOpts: { plugins: ['typescript', 'jsx'], attachComment: true },
-  });
-
-  const ir = (result as any)?.metadata?.mindmatrixIR;
-  if (!ir) {
-    throw new Error(
-      `compileWorkflow: no IR produced. Check that the source exports a component or model.\n` +
-      `Source preview: ${code.trim().slice(0, 120)}...`,
-    );
-  }
-  return ir;
-}
-
-/**
- * Compile a model file (models/*.ts) to IR.
- * Model files use interface-based extraction (no JSX).
- */
-export function compileModel(
-  code: string,
-  options: CompileOptions = {},
-): IRWorkflowDefinition {
-  const filename = options.filename ?? 'models/test.ts';
-  const mode = options.mode ?? 'infer';
-
-  const result = transformSync(code, {
-    filename,
-    plugins: [[babelPlugin, { mode }]],
-    parserOpts: { plugins: ['typescript'], attachComment: true },
-  });
-
-  const ir = (result as any)?.metadata?.mindmatrixIR;
-  if (!ir) {
-    throw new Error(
-      `compileModel: no IR produced. Check that the source exports an interface and transitions.\n` +
-      `Source preview: ${code.trim().slice(0, 120)}...`,
-    );
-  }
-  return ir;
-}
-
-/**
- * Compile a server action file (*.server.ts) to IR.
- */
-export function compileServerAction(
-  code: string,
-  options: CompileOptions = {},
-): IRWorkflowDefinition {
-  const filename = options.filename ?? 'actions.server.ts';
-  return compileWorkflow(code, { ...options, filename });
-}
-
-/**
- * Extract raw Babel metadata from compilation (IR + warnings + errors).
- */
-export function compileRaw(code: string, options: CompileOptions = {}): {
-  ir: IRWorkflowDefinition | undefined;
-  code: string | null;
-  warnings: Array<{ message: string; code?: string }>;
-  errors: Array<{ message: string; code?: string }>;
-} {
-  const filename = options.filename ?? 'test.workflow.tsx';
-  const mode = options.mode ?? 'infer';
-
-  const result = transformSync(code, {
-    filename,
-    plugins: [[babelPlugin, { mode }]],
-    parserOpts: { plugins: ['typescript', 'jsx'], attachComment: true },
-  });
-
-  const metadata = (result as any)?.metadata ?? {};
-  return {
-    ir: metadata.mindmatrixIR,
-    code: result?.code ?? null,
-    warnings: metadata.mindmatrixWarnings ?? [],
-    errors: metadata.mindmatrixErrors ?? [],
-  };
-}
-
-// =============================================================================
-// Mock Providers — lightweight wrappers for rendering .workflow.tsx in tests
-// =============================================================================
-
-/**
- * Mock blueprint context for testing workflow components.
- *
- * Provides the minimal context shape that @mindmatrix/react hooks expect.
- * Does NOT render React — this is a data-only mock for unit testing IR output.
- */
-export interface MockBlueprintProviderProps {
-  /** Blueprint slug. Default: 'test-blueprint' */
-  slug?: string;
-  /** Blueprint version. Default: '1.0.0' */
-  version?: string;
-  /** Initial state data for the workflow instance. */
-  initialState?: Record<string, unknown>;
-  /** Mock definitions available in context. */
-  definitions?: IRWorkflowDefinition[];
-}
-
-/**
- * Creates a mock blueprint context value.
- *
- * Use this to provide context when testing hooks or components that
- * read from BlueprintContext.
- */
-export function createMockBlueprintContext(props: MockBlueprintProviderProps = {}) {
-  const {
-    slug = 'test-blueprint',
-    version = '1.0.0',
-    initialState = {},
-    definitions = [],
-  } = props;
-
-  return {
-    slug,
-    version,
-    definitions,
-    activeDefinition: definitions[0] ?? null,
-    instanceState: initialState,
-    dispatch: () => {},
-    navigate: () => {},
-  };
-}
-
-/**
- * Mock workflow provider props for testing individual workflow components.
- */
-export interface MockWorkflowProviderProps {
-  /** Workflow slug. Default: 'test-workflow' */
-  slug?: string;
-  /** Current state name. Default: 'draft' */
-  currentState?: string;
-  /** Field values. */
-  fields?: Record<string, unknown>;
-  /** Available transitions from current state. */
-  transitions?: string[];
-  /** Mock transition handler. */
-  onTransition?: (name: string, data?: Record<string, unknown>) => void;
-}
-
-/**
- * Creates a mock workflow context value.
- *
- * Provides the shape expected by useWorkflow(), useTransition(), etc.
- */
-export function createMockWorkflowContext(props: MockWorkflowProviderProps = {}) {
-  const {
-    slug = 'test-workflow',
-    currentState = 'draft',
-    fields = {},
-    transitions = [],
-    onTransition = () => {},
-  } = props;
-
-  return {
-    slug,
-    currentState,
-    fields,
-    availableTransitions: transitions,
-    transition: onTransition,
-    setField: (name: string, value: unknown) => {
-      (fields as Record<string, unknown>)[name] = value;
-    },
-    getField: (name: string) => (fields as Record<string, unknown>)[name],
-  };
-}
-
-/**
- * Convenience: compile + extract specific parts of the IR.
- */
-export function extractFields(code: string, options?: CompileOptions) {
-  return compileWorkflow(code, options).fields;
-}
-
-export function extractStates(code: string, options?: CompileOptions) {
-  return compileWorkflow(code, options).states;
-}
-
-export function extractTransitions(code: string, options?: CompileOptions) {
-  return compileWorkflow(code, options).transitions;
-}

package/src/types.ts

@@ -1,68 +0,0 @@
-/**
- * Internal types for the compiler state and extracted data.
- */
-
-import type {
-  IRFieldDefinition,
-  IRStateDefinition,
-  IRTransitionDefinition,
-  IROnEventSubscription,
-  IRExperienceNode,
-  IRGrammarIsland,
-  CompilerErrorCode,
-} from '@mindmatrix/player-core';
-
-import type { FieldWatcher } from './babel/extractors/change-extractor';
-import type { TransitionEffect } from './babel/extractors/transition-effect-extractor';
-
-export interface ExtractedWorkflow {
-  slug: string;
-  name: string;
-  version: string;
-  description?: string;
-  category: string;
-  fields: IRFieldDefinition[];
-  states: Map<string, IRStateDefinition>;
-  transitions: IRTransitionDefinition[];
-  events: IROnEventSubscription[];
-  experience?: IRExperienceNode;
-  fieldWatchers?: FieldWatcher[];
-  transitionEffects?: TransitionEffect[];
-  grammarIslands?: IRGrammarIsland[];
-  errors?: ReactCompilerError[];
-  warnings?: ReactCompilerError[];
-  /** Extra metadata from model files (runtime, fieldOptions, etc.) */
-  extraMetadata?: Record<string, unknown>;
-}
-
-export interface CompilerState {
-  fields: IRFieldDefinition[];
-  states: Map<string, IRStateDefinition>;
-  transitions: IRTransitionDefinition[];
-  events: IROnEventSubscription[];
-  experience?: IRExperienceNode;
-  actionCounter: number;
-  metadata: {
-    slug?: string;
-    name?: string;
-    version?: string;
-    description?: string;
-    category?: string;
-    [key: string]: unknown;
-  };
-  errors?: ReactCompilerError[];
-  warnings?: ReactCompilerError[];
-}
-
-export interface CompilerOptions {
-  mode?: 'strict' | 'infer';
-  filename?: string;
-}
-
-export interface ReactCompilerError {
-  code: CompilerErrorCode;
-  message: string;
-  line?: number;
-  column?: number;
-  severity: 'error' | 'warning';
-}

package/src/vite/index.ts

@@ -1,288 +0,0 @@
-/**
- * Vite Plugin — integrates the MindMatrix Babel compiler into the Vite build pipeline.
- *
- * Transforms `.workflow.tsx` files through the Babel plugin to extract workflow
- * IR (fields, states, transitions, experience tree) and emit:
- *   1. Transformed React code (standard JSX, runs in browser)
- *   2. `.workflow.json` sidecar files (IR for mm-engine consumption)
- *
- * Supports HMR: re-compiles on save, optionally seeds definitions to the dev API.
- *
- * Usage:
- *   // vite.config.ts
- *   import { mindmatrixReact } from '@mindmatrix/react-compiler/vite';
- *
- *   export default defineConfig({
- *     plugins: [
- *       mindmatrixReact({
- *         mode: 'infer',
- *         include: ['**\/*.workflow.tsx'],
- *         seedOnCompile: true,
- *         apiUrl: 'http://localhost:4200/api/v1',
- *       })
- *     ]
- *   });
- */
-
-import type { Plugin } from 'vite';
-import { transformSync } from '@babel/core';
-import { writeFileSync, mkdirSync } from 'fs';
-import { dirname, join, relative, basename } from 'path';
-import babelPlugin from '../babel';
-
-export interface MindMatrixReactOptions {
-  /** Compilation mode: 'strict' validates imports, 'infer' is permissive. Default: 'infer' */
-  mode?: 'strict' | 'infer';
-  /** Glob patterns for files to compile. Default: ['**\/*.workflow.tsx'] */
-  include?: string[];
-  /** Output directory for .workflow.json sidecar files. Default: 'dist/workflows' */
-  outDir?: string;
-  /** When true, POST compiled definitions to the dev API on each compile. Default: false */
-  seedOnCompile?: boolean;
-  /** Dev API base URL for seeding. Default: 'http://localhost:4200/api/v1' */
-  apiUrl?: string;
-  /** Auth token for dev API seeding. Default: reads from MINDMATRIX_TOKEN env var */
-  authToken?: string;
-  /**
-   * Source map configuration for .workflow.tsx files.
-   * - true: Generate source maps with original source embedded (default in dev)
-   * - false: No source maps
-   * - 'inline': Inline source maps in compiled output
-   * Default: auto-detected from Vite mode (true in dev, false in build)
-   */
-  sourceMaps?: boolean | 'inline';
-  /**
-   * Embed __source metadata on IR nodes (file, line, column).
-   * Enables: compilation error mapping, IR inspector, runtime error traces.
-   * Default: true in dev, false in production.
-   */
-  sourceAnnotations?: boolean;
-}
-
-/** Compiled IR result attached to Babel metadata */
-interface CompiledIR {
-  slug: string;
-  name: string;
-  version: string;
-  category: string;
-  fields: unknown[];
-  states: unknown[];
-  transitions: unknown[];
-  experience?: unknown;
-  metadata?: Record<string, unknown>;
-}
-
-export function mindmatrixReact(options?: MindMatrixReactOptions): Plugin {
-  const include = options?.include ?? ['**/*.workflow.tsx'];
-  const mode = options?.mode ?? 'infer';
-  const outDir = options?.outDir ?? 'dist/workflows';
-  const seedOnCompile = options?.seedOnCompile ?? false;
-  const apiUrl = options?.apiUrl ?? 'http://localhost:4200/api/v1';
-  const authToken = options?.authToken ?? process.env.MINDMATRIX_TOKEN;
-
-  // Source map and annotation config — resolved in configResolved
-  let enableSourceMaps = options?.sourceMaps;
-  let enableSourceAnnotations = options?.sourceAnnotations;
-  let isDev = true;
-
-  // Track compiled files for HMR
-  const compiledFiles = new Map<string, CompiledIR>();
-
-  /** Check if a file path matches any of the include patterns */
-  function shouldTransform(id: string): boolean {
-    return include.some((pattern) => {
-      // Convert glob-like pattern to regex
-      const regex = pattern
-        .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape regex chars except * and ?
-        .replace(/\*\*/g, '<<GLOBSTAR>>')
-        .replace(/\*/g, '[^/]*')
-        .replace(/<<GLOBSTAR>>/g, '.*')
-        .replace(/\?/g, '.');
-      return new RegExp(regex).test(id);
-    });
-  }
-
-  /** Seed a compiled definition to the dev API */
-  async function seedToApi(ir: CompiledIR, filePath: string): Promise<void> {
-    if (!seedOnCompile || !authToken) return;
-
-    try {
-      const body = {
-        slug: ir.slug,
-        name: ir.name,
-        version: ir.version,
-        category: ir.category || 'workflow',
-        fields: ir.fields || [],
-        states: ir.states || [],
-        transitions: ir.transitions || [],
-        experience: ir.experience || {},
-        metadata: {
-          ...(ir.metadata || {}),
-          source_file: relative(process.cwd(), filePath),
-          compiled_at: new Date().toISOString(),
-        },
-      };
-
-      const resp = await fetch(`${apiUrl}/workflow/definitions`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'Authorization': `Bearer ${authToken}`,
-        },
-        body: JSON.stringify(body),
-      });
-
-      if (resp.ok) {
-        console.log(`[mindmatrix-react] Seeded ${ir.slug} to ${apiUrl}`);
-      } else if (resp.status === 409) {
-        // Definition already exists — try PATCH instead
-        const existing = await fetch(
-          `${apiUrl}/workflow/definitions?slug=${encodeURIComponent(ir.slug)}&version=${encodeURIComponent(ir.version)}`,
-          { headers: { 'Authorization': `Bearer ${authToken}` } },
-        );
-        if (existing.ok) {
-          const data = await existing.json() as Record<string, unknown> | Record<string, unknown>[];
-          const defId = Array.isArray(data) ? (data[0] as Record<string, unknown>)?.id : data?.id;
-          if (defId) {
-            await fetch(`${apiUrl}/workflow/definitions/${defId}`, {
-              method: 'PATCH',
-              headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${authToken}`,
-              },
-              body: JSON.stringify(body),
-            });
-            console.log(`[mindmatrix-react] Updated ${ir.slug} (PATCH)`);
-          }
-        }
-      } else {
-        const text = await resp.text().catch(() => '');
-        console.warn(`[mindmatrix-react] Seed failed (${resp.status}): ${text.slice(0, 200)}`);
-      }
-    } catch (e) {
-      console.warn(`[mindmatrix-react] Seed failed:`, e instanceof Error ? e.message : e);
-    }
-  }
-
-  return {
-    name: 'mindmatrix-react',
-    enforce: 'pre',
-
-    configResolved(config) {
-      isDev = config.command === 'serve';
-      // Resolve source map defaults based on dev/build mode
-      if (enableSourceMaps === undefined) enableSourceMaps = isDev;
-      if (enableSourceAnnotations === undefined) enableSourceAnnotations = isDev;
-    },
-
-    transform(code: string, id: string) {
-      if (!shouldTransform(id)) return null;
-
-      try {
-        const wantMaps = enableSourceMaps !== false;
-        const result = transformSync(code, {
-          filename: id,
-          plugins: [[babelPlugin, { mode, filename: id, sourceAnnotations: enableSourceAnnotations }]],
-          parserOpts: { plugins: ['jsx', 'typescript'] },
-          sourceMaps: wantMaps,
-          // Embed original source in the source map so debuggers can show .workflow.tsx
-          ...(wantMaps ? { sourceFileName: basename(id) } : {}),
-        });
-
-        if (!result?.code) return null;
-
-        // Extract IR from Babel metadata
-        const metadata = (result as any).metadata || {};
-        const ir = metadata.mindmatrixIR as CompiledIR | undefined;
-        const warnings = metadata.mindmatrixWarnings as Array<{ message: string }> | undefined;
-        const errors = metadata.mindmatrixErrors as Array<{ message: string }> | undefined;
-
-        // Report warnings
-        if (warnings?.length) {
-          for (const w of warnings) {
-            console.warn(`[mindmatrix-react] ${basename(id)}: ${w.message}`);
-          }
-        }
-
-        // Report errors (but don't fail the build in infer mode)
-        if (errors?.length) {
-          for (const e of errors) {
-            if (mode === 'strict') {
-              this.error(`${basename(id)}: ${e.message}`);
-            } else {
-              this.warn(`${basename(id)}: ${e.message}`);
-            }
-          }
-        }
-
-        if (ir) {
-          // Track for HMR
-          compiledFiles.set(id, ir);
-
-          // Write IR to .workflow.json sidecar file
-          const outputFileName = basename(id).replace(/\.tsx?$/, '.workflow.json');
-          const outputPath = join(process.cwd(), outDir, outputFileName);
-          mkdirSync(dirname(outputPath), { recursive: true });
-          writeFileSync(outputPath, JSON.stringify(ir, null, 2), 'utf-8');
-          console.log(`[mindmatrix-react] Compiled ${basename(id)} → ${outputFileName}`);
-
-          // Seed to dev API (async, non-blocking)
-          seedToApi(ir, id);
-        }
-
-        // Strip __source annotations from IR in production sidecar files
-        if (!enableSourceAnnotations && ir) {
-          stripSourceAnnotations(ir);
-        }
-
-        return {
-          code: result.code,
-          map: wantMaps ? result.map : undefined,
-        };
-      } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        if (mode === 'strict') {
-          this.error(`Failed to compile ${basename(id)}: ${msg}`);
-        } else {
-          console.error(`[mindmatrix-react] Error compiling ${basename(id)}:`, msg);
-        }
-        return null;
-      }
-    },
-
-    handleHotUpdate(ctx) {
-      if (!shouldTransform(ctx.file)) return;
-
-      // Log HMR event
-      console.log(`[mindmatrix-react] HMR: ${basename(ctx.file)} changed`);
-
-      // The standard Vite HMR will re-run transform() above
-      // and re-write the sidecar + re-seed API
-      return undefined;
-    },
-  };
-}
-
-/**
- * Strip __source annotations from IR for production builds.
- * These are useful for dev debugging but add size to deployed definitions.
- */
-function stripSourceAnnotations(ir: CompiledIR): void {
-  const strip = (obj: unknown) => {
-    if (!obj || typeof obj !== 'object') return;
-    if (Array.isArray(obj)) {
-      for (const item of obj) strip(item);
-      return;
-    }
-    const rec = obj as Record<string, unknown>;
-    delete rec.__source;
-    for (const val of Object.values(rec)) {
-      if (val && typeof val === 'object') strip(val);
-    }
-  };
-
-  strip(ir.fields);
-  strip(ir.states);
-  strip(ir.transitions);
-  strip(ir.experience);
-}