@mmapp/react-compiler 0.1.0-alpha.1

package/src/babel/extractors/state-extractor.ts

@@ -0,0 +1,214 @@
+/**
+ * State Extractor — extracts useState calls and converts them to IRFieldDefinition.
+ *
+ * INPUT:
+ *   const [count, setCount] = useState(0);
+ *   const [name, setName] = useState('');
+ *   const [active, setActive] = useState(false);
+ *   const [items, setItems] = useState<string[]>([]);
+ *
+ * OUTPUT:
+ *   [
+ *     { name: "count", type: "number", default_value: 0 },
+ *     { name: "name", type: "text", default_value: "" },
+ *     { name: "active", type: "boolean", default_value: false },
+ *     { name: "items", type: "json", default_value: [] }
+ *   ]
+ */
+
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import type { IRFieldDefinition, IRWorkflowFieldType } from '@mindmatrix/player-core';
+import type { CompilerState } from '../../types';
+
+/** Well-known TypeScript type names that map to built-in IR field types */
+const KNOWN_TYPE_REFS: Record<string, IRWorkflowFieldType> = {
+  Date: 'date',
+  URL: 'url',
+  Record: 'json',
+  Map: 'json',
+  Set: 'json',
+};
+
+/**
+ * Converts a PascalCase TypeScript name to a kebab-case slug.
+ * e.g. 'EmailAddress' → 'email-address', 'Currency' → 'currency'
+ */
+function typeNameToSlug(name: string): string {
+  return name
+    .replace(/([A-Z])/g, '-$1')
+    .toLowerCase()
+    .replace(/^-/, '');
+}
+
+/**
+ * Infers IR field type from TypeScript type annotation or default value.
+ *
+ * For built-in primitives (string, number, boolean, Date), returns canonical types.
+ * For custom type references (e.g. useState<Email>(), useState<Currency>()),
+ * returns the type name as a kebab-case slug — enabling Element-based field types.
+ */
+/**
+ * Resolves a single (non-union) TS type node to an IR field type.
+ * Extracted so that union-stripping logic can delegate per-member.
+ */
+function resolveSingleType(annotation: t.TSType): IRWorkflowFieldType | null {
+  if (t.isTSNumberKeyword(annotation)) return 'number';
+  if (t.isTSStringKeyword(annotation)) return 'text';
+  if (t.isTSBooleanKeyword(annotation)) return 'boolean';
+  if (t.isTSTypeReference(annotation)) {
+    const typeName = t.isIdentifier(annotation.typeName)
+      ? annotation.typeName.name
+      : '';
+    // Array<T> generic reference → multi_select
+    if (typeName === 'Array') return 'multi_select';
+    // Check known type references
+    if (typeName && KNOWN_TYPE_REFS[typeName]) return KNOWN_TYPE_REFS[typeName];
+    // Unknown type reference → emit as slug (Element-based custom field type)
+    if (typeName) return typeNameToSlug(typeName) as IRWorkflowFieldType;
+  }
+  // Array types (T[]) → multi_select
+  if (t.isTSArrayType(annotation)) return 'multi_select';
+  // Objects and tuples → json
+  if (t.isTSTypeLiteral(annotation) || t.isTSTupleType(annotation)) return 'json';
+  return null;
+}
+
+function inferFieldType(
+  typeAnnotation: t.TSType | null,
+  defaultValue: t.Expression | null
+): IRWorkflowFieldType {
+  // Check TypeScript type annotation first
+  if (typeAnnotation) {
+    // Handle union types: strip null/undefined members, then resolve the remaining type
+    // e.g. useState<{ name: string; age: number } | null>(null) → json
+    // e.g. useState<string | null>(null) → text
+    if (t.isTSUnionType(typeAnnotation)) {
+      // Check for union of string literals first → select
+      const allStringLiterals = typeAnnotation.types.every(
+        m => t.isTSLiteralType(m) && t.isStringLiteral(m.literal),
+      );
+      if (allStringLiterals) return 'select';
+
+      // String literals + null → select (nullable enum)
+      const nonNullMembers = typeAnnotation.types.filter(
+        m => !t.isTSNullKeyword(m) && !t.isTSUndefinedKeyword(m),
+      );
+      const allLiteralsExceptNull = nonNullMembers.every(
+        m => t.isTSLiteralType(m) && t.isStringLiteral(m.literal),
+      );
+      if (allLiteralsExceptNull && nonNullMembers.length > 0) return 'select';
+
+      // Strip null/undefined from union, resolve remaining type
+      if (nonNullMembers.length === 1) {
+        const resolved = resolveSingleType(nonNullMembers[0]);
+        if (resolved) return resolved;
+      }
+
+      // Multiple non-null members that aren't all string literals → json
+      if (nonNullMembers.length > 1) return 'json';
+    }
+
+    // Try resolving as a single type
+    const resolved = resolveSingleType(typeAnnotation);
+    if (resolved) return resolved;
+  }
+
+  // Infer from default value
+  if (defaultValue) {
+    if (t.isNumericLiteral(defaultValue)) return 'number';
+    if (t.isStringLiteral(defaultValue)) return 'text';
+    if (t.isBooleanLiteral(defaultValue)) return 'boolean';
+    if (t.isArrayExpression(defaultValue)) return 'json';
+    if (t.isObjectExpression(defaultValue)) return 'json';
+    if (t.isNewExpression(defaultValue) && t.isIdentifier(defaultValue.callee)) {
+      if (defaultValue.callee.name === 'Date') return 'date';
+    }
+  }
+
+  // Default fallback
+  return 'text';
+}
+
+/**
+ * Extracts the default value from the useState argument.
+ */
+function extractDefaultValue(arg: t.Expression): unknown {
+  if (t.isNumericLiteral(arg)) return arg.value;
+  if (t.isStringLiteral(arg)) return arg.value;
+  if (t.isBooleanLiteral(arg)) return arg.value;
+  if (t.isNullLiteral(arg)) return null;
+  if (t.isArrayExpression(arg)) {
+    return arg.elements.map((el) =>
+      el && t.isExpression(el) ? extractDefaultValue(el) : null
+    );
+  }
+  if (t.isObjectExpression(arg)) {
+    const obj: Record<string, unknown> = {};
+    arg.properties.forEach((prop) => {
+      if (t.isObjectProperty(prop) && t.isIdentifier(prop.key) && t.isExpression(prop.value)) {
+        obj[prop.key.name] = extractDefaultValue(prop.value);
+      }
+    });
+    return obj;
+  }
+  return undefined;
+}
+
+/**
+ * Main extractor function called from the visitor.
+ */
+export function extractStates(path: NodePath<t.CallExpression>, state: any): void {
+  const parent = path.parentPath;
+
+  // Must be part of a variable declaration: const [x, setX] = useState(...)
+  if (!parent.isVariableDeclarator()) return;
+
+  const id = parent.node.id;
+  if (!t.isArrayPattern(id) || id.elements.length < 1) return;
+
+  const firstElement = id.elements[0];
+  if (!t.isIdentifier(firstElement)) return;
+
+  const fieldName = firstElement.name;
+  const args = path.node.arguments;
+  const defaultValue = args.length > 0 && t.isExpression(args[0]) ? args[0] : null;
+
+  // Extract type annotation if present: useState<Type>(...)
+  let typeAnnotation: t.TSType | null = null;
+  if (path.node.typeParameters && t.isTSTypeParameterInstantiation(path.node.typeParameters)) {
+    const params = path.node.typeParameters.params;
+    if (params.length > 0) {
+      typeAnnotation = params[0];
+    }
+  }
+
+  const fieldType = inferFieldType(typeAnnotation, defaultValue);
+  const fieldDefaultValue = defaultValue ? extractDefaultValue(defaultValue) : undefined;
+
+  const field: IRFieldDefinition = {
+    name: fieldName,
+    type: fieldType,
+    default_value: fieldDefaultValue,
+  };
+
+  // Extract select options from union type annotation: useState<"a" | "b" | "c">
+  // Also handles nullable unions: useState<"a" | "b" | null>
+  if (fieldType === 'select' && typeAnnotation && t.isTSUnionType(typeAnnotation)) {
+    const options = typeAnnotation.types
+      .filter((m): m is t.TSLiteralType => t.isTSLiteralType(m) && t.isStringLiteral(m.literal))
+      .map(m => (m.literal as t.StringLiteral).value);
+    if (options.length > 0) {
+      (field as any).validation = { options };
+    }
+  }
+
+  // Add to compiler state
+  const compilerState = state as CompilerState;
+  if (!compilerState.fields) compilerState.fields = [];
+
+  // Avoid duplicates
+  if (!compilerState.fields.some((f) => f.name === fieldName)) {
+    compilerState.fields.push(field);
+  }
+}

package/src/babel/extractors/transition-effect-extractor.ts

@@ -0,0 +1,176 @@
+/**
+ * Transition Effect Extractor — extracts useOnTransition calls.
+ *
+ * INPUT:
+ *   useOnTransition(({ from, to }) => {
+ *     console.log(`Transitioned from ${from} to ${to}`);
+ *   });
+ *
+ * OUTPUT (stored in compilerState metadata.transitionEffects[]):
+ *   {
+ *     id: "transition_effect_1",
+ *     actions: [{ id: "auto_N", type: "log_event", mode: "auto", config: { message: "..." } }]
+ *   }
+ */
+
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import type { IRActionDefinition } from '@mindmatrix/player-core';
+import type { CompilerState } from '../../types';
+
+export interface TransitionEffect {
+  id: string;
+  actions: IRActionDefinition[];
+}
+
+let transitionEffectIdCounter = 0;
+
+/**
+ * Resets the transition effect ID counter.
+ */
+export function resetTransitionEffectIdCounter(): void {
+  transitionEffectIdCounter = 0;
+}
+
+/**
+ * Analyzes a callback body and extracts action definitions.
+ */
+function analyzeCallbackBody(
+  body: t.Statement[],
+  actionCounter: { value: number }
+): IRActionDefinition[] {
+  const actions: IRActionDefinition[] = [];
+
+  for (const statement of body) {
+    if (!t.isExpressionStatement(statement)) continue;
+    const expr = statement.expression;
+
+    if (t.isCallExpression(expr) && t.isIdentifier(expr.callee)) {
+      const calleeName = expr.callee.name;
+      const args = expr.arguments;
+
+      if (calleeName === 'setField' && args.length >= 2) {
+        const field = t.isStringLiteral(args[0]) ? args[0].value : undefined;
+        if (field !== undefined) {
+          actions.push({
+            id: `auto_${++actionCounter.value}`,
+            type: 'set_field',
+            mode: 'auto',
+            config: { field, value: extractValue(args[1]) },
+          });
+        }
+      } else if (calleeName === 'setMemory' && args.length >= 2) {
+        const key = t.isStringLiteral(args[0]) ? args[0].value : undefined;
+        if (key !== undefined) {
+          actions.push({
+            id: `auto_${++actionCounter.value}`,
+            type: 'set_memory',
+            mode: 'auto',
+            config: { key, value: extractValue(args[1]) },
+          });
+        }
+      } else if (calleeName.startsWith('set') && calleeName.length > 3 && args.length >= 1) {
+        const fieldName = calleeName.slice(3, 4).toLowerCase() + calleeName.slice(4);
+        actions.push({
+          id: `auto_${++actionCounter.value}`,
+          type: 'set_field',
+          mode: 'auto',
+          config: { field: fieldName, value: extractValue(args[0]) },
+        });
+      }
+    } else if (t.isCallExpression(expr)) {
+      const callee = expr.callee;
+      if (
+        t.isMemberExpression(callee) &&
+        t.isIdentifier(callee.object) &&
+        callee.object.name === 'console' &&
+        t.isIdentifier(callee.property) &&
+        callee.property.name === 'log' &&
+        expr.arguments.length > 0
+      ) {
+        actions.push({
+          id: `auto_${++actionCounter.value}`,
+          type: 'log_event',
+          mode: 'auto',
+          config: { message: extractValue(expr.arguments[0]) },
+        });
+      }
+    }
+  }
+
+  return actions;
+}
+
+function extractValue(node: t.Node): unknown {
+  if (t.isNumericLiteral(node)) return node.value;
+  if (t.isStringLiteral(node)) return node.value;
+  if (t.isBooleanLiteral(node)) return node.value;
+  if (t.isNullLiteral(node)) return null;
+  if (t.isIdentifier(node)) return node.name;
+  if (t.isArrayExpression(node)) {
+    return node.elements.map((el) => (el && t.isExpression(el) ? extractValue(el) : null));
+  }
+  if (t.isObjectExpression(node)) {
+    const obj: Record<string, unknown> = {};
+    node.properties.forEach((prop) => {
+      if (t.isObjectProperty(prop) && t.isIdentifier(prop.key) && t.isExpression(prop.value)) {
+        obj[prop.key.name] = extractValue(prop.value);
+      }
+    });
+    return obj;
+  }
+  if (t.isMemberExpression(node)) {
+    const obj = t.isIdentifier(node.object) ? node.object.name : '[object]';
+    const prop = t.isIdentifier(node.property) ? node.property.name : '[property]';
+    return `${obj}.${prop}`;
+  }
+  if (t.isConditionalExpression(node)) {
+    return `(${extractValue(node.test)} ? ${extractValue(node.consequent)} : ${extractValue(node.alternate)})`;
+  }
+  if (t.isTSAsExpression(node)) return extractValue(node.expression);
+  if (t.isTSNonNullExpression(node)) return extractValue(node.expression);
+  return '[Expression]';
+}
+
+/**
+ * Main extractor function called from the visitor.
+ *
+ * Handles: useOnTransition(callback)
+ */
+export function extractTransitionEffect(path: NodePath<t.CallExpression>, state: any): void {
+  const callee = path.node.callee;
+  if (!t.isIdentifier(callee) || callee.name !== 'useOnTransition') return;
+
+  const args = path.node.arguments;
+  if (args.length < 1) return;
+
+  const callbackArg = args[0];
+
+  // Extract callback body
+  let callbackBody: t.Statement[] = [];
+  if (t.isArrowFunctionExpression(callbackArg) || t.isFunctionExpression(callbackArg)) {
+    const body = callbackArg.body;
+    if (t.isBlockStatement(body)) {
+      callbackBody = body.body;
+    } else if (t.isExpression(body)) {
+      callbackBody = [t.expressionStatement(body)];
+    }
+  }
+
+  const compilerState = state as CompilerState;
+  if (!compilerState.actionCounter) compilerState.actionCounter = 0;
+
+  const actions = analyzeCallbackBody(callbackBody, { value: compilerState.actionCounter });
+  compilerState.actionCounter += actions.length;
+
+  const effect: TransitionEffect = {
+    id: `transition_effect_${++transitionEffectIdCounter}`,
+    actions,
+  };
+
+  // Store in compiler state metadata
+  if (!compilerState.metadata) compilerState.metadata = {};
+  const meta = compilerState.metadata as Record<string, unknown>;
+  if (!meta.transitionEffects) meta.transitionEffects = [];
+  (meta.transitionEffects as TransitionEffect[]).push(effect);
+}

package/src/babel/extractors/transition-extractor.ts

@@ -0,0 +1,143 @@
+/**
+ * Transition Extractor — extracts useTransition calls to build IRTransitionDefinition.
+ *
+ * INPUT:
+ *   const submit = useTransition('submit');
+ *   const cancel = useTransition('cancel');
+ *
+ * OUTPUT:
+ *   [
+ *     { name: "submit", from: [], to: "", actions: [], conditions: [] },
+ *     { name: "cancel", from: [], to: "", actions: [] }
+ *   ]
+ *
+ * Note: The from/to states are inferred during the emitter phase by analyzing state flow.
+ */
+
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import type { IRTransitionDefinition } from '@mindmatrix/player-core';
+import type { CompilerState } from '../../types';
+
+/**
+ * Main extractor function called from the visitor.
+ *
+ * Supports two forms:
+ *   useTransition('submit')
+ *   useTransition('submit', { from: ['DRAFT'], to: 'SUBMITTED' })
+ */
+export function extractTransitions(path: NodePath<t.CallExpression>, state: any): void {
+  const callee = path.node.callee;
+  if (!t.isIdentifier(callee) || callee.name !== 'useTransition') return;
+
+  const args = path.node.arguments;
+  if (args.length < 1) return;
+
+  const nameArg = args[0];
+  if (!t.isStringLiteral(nameArg)) return;
+
+  const transitionName = nameArg.value;
+
+  const compilerState = state as CompilerState;
+  if (!compilerState.transitions) compilerState.transitions = [];
+
+  // Check if transition already exists
+  const existing = compilerState.transitions.find((tr) => tr.name === transitionName);
+  if (existing) return;
+
+  // Extract from/to/roles/requiredFields/auto from optional second argument
+  let from: string[] = [];
+  let to = '';
+  let roles: string[] | undefined;
+  let requiredFields: string[] | undefined;
+  let auto: boolean | undefined;
+
+  if (args.length >= 2 && t.isObjectExpression(args[1])) {
+    const opts = args[1];
+    for (const prop of opts.properties) {
+      if (!t.isObjectProperty(prop) || !t.isIdentifier(prop.key)) continue;
+
+      if (prop.key.name === 'from') {
+        if (t.isArrayExpression(prop.value)) {
+          from = prop.value.elements
+            .filter((el): el is t.StringLiteral => t.isStringLiteral(el))
+            .map((el) => el.value);
+        } else if (t.isStringLiteral(prop.value)) {
+          from = [prop.value.value];
+        }
+      } else if (prop.key.name === 'to') {
+        if (t.isStringLiteral(prop.value)) {
+          to = prop.value.value;
+        }
+      } else if (prop.key.name === 'roles') {
+        if (t.isArrayExpression(prop.value)) {
+          roles = prop.value.elements
+            .filter((el): el is t.StringLiteral => t.isStringLiteral(el))
+            .map((el) => el.value);
+        }
+      } else if (prop.key.name === 'requiredFields') {
+        if (t.isArrayExpression(prop.value)) {
+          requiredFields = prop.value.elements
+            .filter((el): el is t.StringLiteral => t.isStringLiteral(el))
+            .map((el) => el.value);
+        }
+      } else if (prop.key.name === 'auto') {
+        if (t.isBooleanLiteral(prop.value)) {
+          auto = prop.value.value;
+        }
+      }
+    }
+  }
+
+  const transition: IRTransitionDefinition = {
+    name: transitionName,
+    from,
+    to,
+    actions: [],
+    conditions: [],
+    ...(roles && roles.length > 0 && { roles }),
+    ...(requiredFields && requiredFields.length > 0 && { required_fields: requiredFields }),
+    ...(auto !== undefined && { auto }),
+  };
+
+  compilerState.transitions.push(transition);
+}
+
+/**
+ * Infers from/to states for transitions that don't have explicit values.
+ * Transitions with explicit from/to (from .workflow.tsx options) are left untouched.
+ * Called during the emitter phase.
+ */
+export function inferTransitionStates(
+  transitions: IRTransitionDefinition[],
+  states: Map<string, any>
+): void {
+  const stateArray = Array.from(states.values());
+  const startStates = stateArray.filter((s) => s.type === 'START');
+  const regularStates = stateArray.filter((s) => s.type === 'REGULAR');
+
+  // Only infer for transitions missing from/to
+  const needsInference = transitions.filter((t) => t.from.length === 0 || !t.to);
+  if (needsInference.length === 0) return;
+
+  if (startStates.length === 1 && regularStates.length > 0) {
+    needsInference.forEach((t, idx) => {
+      if (t.from.length === 0) {
+        t.from = [startStates[0].name];
+      }
+      if (!t.to) {
+        t.to = regularStates[idx % regularStates.length]?.name || startStates[0].name;
+      }
+    });
+  } else {
+    const allStateNames = stateArray.map((s) => s.name);
+    needsInference.forEach((t, idx) => {
+      if (t.from.length === 0 && allStateNames.length > 0) {
+        t.from = [allStateNames[0]];
+      }
+      if (!t.to && allStateNames.length > 1) {
+        t.to = allStateNames[Math.min(idx + 1, allStateNames.length - 1)];
+      }
+    });
+  }
+}

package/src/babel/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Babel Plugin Entry — @mindmatrix/react-compiler/babel
+ *
+ * Usage:
+ *   babel.config.js:
+ *   {
+ *     plugins: [
+ *       ['@mindmatrix/react-compiler/babel', { mode: 'infer' }]
+ *     ]
+ *   }
+ */
+
+import { createVisitor } from './visitor';
+import type { CompilerOptions } from '../types';
+
+// Babel plugin using manual declaration (avoiding helper-plugin-utils typing issues)
+export default function babelPlugin(api: any, options: CompilerOptions = {}) {
+  api.assertVersion(7);
+
+  return {
+    name: 'mindmatrix-react',
+    visitor: createVisitor(options),
+  };
+}