@mmapp/react-compiler 0.1.0-alpha.1

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

@@ -0,0 +1,262 @@
+/**
+ * Computed Extractor — extracts useComputed() calls into IRFieldDefinition entries.
+ *
+ * INPUT:
+ *   const total = useComputed('line_total', () => quantity * unitPrice, {
+ *     mode: 'transaction-maintained',
+ *     deps: ['quantity', 'unit_price'],
+ *   });
+ *
+ * OUTPUT (added to compilerState.fields[]):
+ *   {
+ *     name: 'line_total',
+ *     type: 'number',            // inferred from return type or default
+ *     computed: 'quantity * unitPrice',
+ *     computed_deps: ['quantity', 'unit_price'],
+ *     computed_mode: 'transaction-maintained',
+ *   }
+ *
+ * Supports all three modes:
+ *   - 'read-time' (RT): computed on every read, no storage
+ *   - 'transaction-maintained' (TM): recomputed synchronously on dependency change
+ *   - 'async-materialized' (AM): recomputed asynchronously via background job
+ */
+
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import type { IRFieldDefinition } from '@mindmatrix/player-core';
+import type { CompilerState } from '../../types';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ComputedFieldExtraction {
+  /** The canonical field name (snake_case). */
+  name: string;
+  /** The variable name in the component (camelCase). */
+  varName: string;
+  /** The raw expression body as a string. */
+  expression: string;
+  /** Declared dependencies (from options.deps). */
+  deps: string[];
+  /** Execution mode. Default: 'read-time'. */
+  mode: 'read-time' | 'transaction-maintained' | 'async-materialized';
+  /** Inferred field type. */
+  type: string;
+  /** Staleness config for async-materialized fields. */
+  staleness?: string;
+  /** Whether RLS staleness is explicitly acceptable. */
+  rlsStalenessOk?: boolean;
+}
+
+// =============================================================================
+// Expression Extraction
+// =============================================================================
+
+/**
+ * Converts a Babel AST expression to a string representation for the IR.
+ * This is a simplified serializer — it handles common patterns.
+ */
+function expressionToString(node: t.Node): string {
+  if (t.isIdentifier(node)) return node.name;
+  if (t.isNumericLiteral(node)) return String(node.value);
+  if (t.isStringLiteral(node)) return `"${node.value}"`;
+  if (t.isBooleanLiteral(node)) return String(node.value);
+  if (t.isNullLiteral(node)) return 'null';
+  if (t.isTemplateLiteral(node)) {
+    return node.quasis.map((q, i) => {
+      const raw = q.value.raw;
+      if (i < node.expressions.length) {
+        const expr = node.expressions[i];
+        return raw + '${' + expressionToString(expr as t.Expression) + '}';
+      }
+      return raw;
+    }).join('');
+  }
+  if (t.isBinaryExpression(node)) {
+    return `${expressionToString(node.left)} ${node.operator} ${expressionToString(node.right)}`;
+  }
+  if (t.isLogicalExpression(node)) {
+    return `${expressionToString(node.left)} ${node.operator} ${expressionToString(node.right)}`;
+  }
+  if (t.isConditionalExpression(node)) {
+    return `${expressionToString(node.test)} ? ${expressionToString(node.consequent)} : ${expressionToString(node.alternate)}`;
+  }
+  if (t.isMemberExpression(node) && !node.computed) {
+    return `${expressionToString(node.object)}.${expressionToString(node.property)}`;
+  }
+  if (t.isCallExpression(node)) {
+    const callee = expressionToString(node.callee);
+    const args = node.arguments.map(a => expressionToString(a as t.Expression)).join(', ');
+    return `${callee}(${args})`;
+  }
+  if (t.isUnaryExpression(node)) {
+    return `${node.operator}${expressionToString(node.argument)}`;
+  }
+  if (t.isParenthesizedExpression(node)) {
+    return `(${expressionToString(node.expression)})`;
+  }
+  return '[Expression]';
+}
+
+/**
+ * Infers the field type from the compute function's return expression.
+ */
+function inferComputedType(body: t.Expression): string {
+  if (t.isNumericLiteral(body) || t.isBinaryExpression(body)) return 'number';
+  if (t.isStringLiteral(body) || t.isTemplateLiteral(body)) return 'text';
+  if (t.isBooleanLiteral(body) || t.isLogicalExpression(body)) return 'boolean';
+  if (t.isArrayExpression(body)) return 'json';
+  if (t.isObjectExpression(body)) return 'json';
+  // For function calls and other expressions, default to text
+  return 'text';
+}
+
+/**
+ * Extracts a string array from a Babel AST array expression.
+ */
+function extractStringArray(node: t.Node): string[] {
+  if (!t.isArrayExpression(node)) return [];
+  return node.elements
+    .filter((el): el is t.StringLiteral => t.isStringLiteral(el))
+    .map(el => el.value);
+}
+
+// =============================================================================
+// Main Extractor
+// =============================================================================
+
+/**
+ * Extracts useComputed() calls from the AST and adds computed field
+ * definitions to the compiler state.
+ *
+ * Called from the visitor for each CallExpression node.
+ */
+export function extractComputed(path: NodePath<t.CallExpression>, state: any): void {
+  const callee = path.node.callee;
+  if (!t.isIdentifier(callee) || callee.name !== 'useComputed') return;
+
+  const args = path.node.arguments;
+  if (args.length < 2) return;
+
+  // Arg 1: field name (string literal)
+  const nameArg = args[0];
+  if (!t.isStringLiteral(nameArg)) return;
+  const fieldName = nameArg.value;
+
+  // Arg 2: compute function (arrow/function expression)
+  const computeArg = args[1];
+  if (!t.isArrowFunctionExpression(computeArg) && !t.isFunctionExpression(computeArg)) return;
+
+  // Extract the expression body
+  let expression: string;
+  let returnType = 'text';
+
+  if (t.isExpression(computeArg.body) && !t.isBlockStatement(computeArg.body)) {
+    // Arrow with expression body: () => a + b
+    expression = expressionToString(computeArg.body);
+    returnType = inferComputedType(computeArg.body);
+  } else if (t.isBlockStatement(computeArg.body)) {
+    // Block body — look for return statement
+    const returnStmt = computeArg.body.body.find(
+      (s): s is t.ReturnStatement => t.isReturnStatement(s)
+    );
+    if (returnStmt?.argument) {
+      expression = expressionToString(returnStmt.argument);
+      returnType = inferComputedType(returnStmt.argument);
+    } else {
+      expression = '[Expression]';
+    }
+  } else {
+    expression = '[Expression]';
+  }
+
+  // Arg 3: options object (optional)
+  let mode: 'read-time' | 'transaction-maintained' | 'async-materialized' = 'read-time';
+  let deps: string[] = [];
+  let staleness: string | undefined;
+  let rlsStalenessOk: boolean | undefined;
+  let explicitType: string | undefined;
+
+  if (args.length >= 3 && t.isObjectExpression(args[2])) {
+    const optObj = args[2];
+    for (const prop of optObj.properties) {
+      if (!t.isObjectProperty(prop) || !t.isIdentifier(prop.key)) continue;
+
+      switch (prop.key.name) {
+        case 'mode':
+          if (t.isStringLiteral(prop.value)) {
+            const modeVal = prop.value.value;
+            if (modeVal === 'read-time' || modeVal === 'transaction-maintained' || modeVal === 'async-materialized') {
+              mode = modeVal;
+            }
+          }
+          break;
+        case 'deps':
+          deps = extractStringArray(prop.value);
+          break;
+        case 'staleness':
+          if (t.isStringLiteral(prop.value)) {
+            staleness = prop.value.value;
+          }
+          break;
+        case 'rlsStalenessOk':
+          if (t.isBooleanLiteral(prop.value)) {
+            rlsStalenessOk = prop.value.value;
+          }
+          break;
+        case 'type':
+          if (t.isStringLiteral(prop.value)) {
+            explicitType = prop.value.value;
+          }
+          break;
+      }
+    }
+  }
+
+  // Determine the variable name from the parent VariableDeclarator
+  let varName = fieldName;
+  const parent = path.parentPath;
+  if (parent?.isVariableDeclarator() && t.isIdentifier(parent.node.id)) {
+    varName = parent.node.id.name;
+  }
+
+  // Build IRFieldDefinition for the computed field
+  const compilerState = state as CompilerState;
+  const fieldDef: IRFieldDefinition = {
+    name: fieldName,
+    type: explicitType || returnType,
+    computed: expression,
+    computed_deps: deps.length > 0 ? deps : undefined,
+  };
+
+  // Store the computed mode in the field definition via metadata convention
+  // The IR doesn't have a top-level computed_mode field, so we attach it
+  // alongside the computed expression for the engine to interpret.
+  (fieldDef as any).computed_mode = mode;
+
+  if (staleness !== undefined) {
+    (fieldDef as any).computed_staleness = staleness;
+  }
+  if (rlsStalenessOk !== undefined) {
+    (fieldDef as any).rls_staleness_tolerance = rlsStalenessOk;
+  }
+
+  compilerState.fields.push(fieldDef);
+
+  // Also register in metadata for the decompiler
+  if (!compilerState.metadata) compilerState.metadata = {};
+  const meta = compilerState.metadata as Record<string, unknown>;
+  if (!meta.computedFields) meta.computedFields = [];
+  (meta.computedFields as ComputedFieldExtraction[]).push({
+    name: fieldName,
+    varName,
+    expression,
+    deps,
+    mode,
+    type: explicitType || returnType,
+    staleness,
+    rlsStalenessOk,
+  });
+}

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

@@ -0,0 +1,277 @@
+/**
+ * Context Extractor — derives workflow definitions from React contexts.
+ *
+ * Detects createContext() calls and extracts:
+ * - Interface from context default value type → fields
+ * - useReducer() cases → transitions (state machine)
+ * - Provider component → instance creation boundary
+ *
+ * INPUT:
+ *   interface ChatState { messages: Message[]; channel: string; }
+ *   type ChatAction = { type: 'ADD_MESSAGE'; ... } | { type: 'SET_CHANNEL'; ... };
+ *
+ *   function chatReducer(state: ChatState, action: ChatAction): ChatState {
+ *     switch (action.type) {
+ *       case 'ADD_MESSAGE': ...
+ *       case 'SET_CHANNEL': ...
+ *     }
+ *   }
+ *
+ *   const ChatContext = createContext<ChatState>(initialState);
+ *
+ * OUTPUT (stored in compilerState metadata.contextWorkflow):
+ *   {
+ *     name: 'ChatContext',
+ *     fields: [...],           // from interface
+ *     reducerActions: [...],   // from switch cases
+ *     providerComponent: '...' // from usage
+ *   }
+ */
+
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import type { CompilerState } from '../../types';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ContextWorkflow {
+  /** Name of the context (e.g., 'ChatContext') */
+  name: string;
+  /** Fields extracted from the context value type */
+  fields: ContextField[];
+  /** Reducer actions (state machine transitions) */
+  reducerActions: ReducerAction[];
+  /** The reducer function name */
+  reducerName?: string;
+  /** Initial state values */
+  initialState?: Record<string, unknown>;
+}
+
+export interface ContextField {
+  /** Field name */
+  name: string;
+  /** TypeScript type (if extractable) */
+  type: string;
+  /** Whether the field is optional */
+  optional: boolean;
+}
+
+export interface ReducerAction {
+  /** Action type string (e.g., 'ADD_MESSAGE') */
+  type: string;
+  /** Payload fields if detectable */
+  payloadFields?: string[];
+}
+
+// =============================================================================
+// Detection
+// =============================================================================
+
+/**
+ * Checks if a file contains createContext() calls.
+ */
+export function hasContextCreation(path: NodePath<t.Program>): boolean {
+  let found = false;
+  path.traverse({
+    CallExpression(callPath) {
+      if (t.isIdentifier(callPath.node.callee, { name: 'createContext' })) {
+        found = true;
+        callPath.stop();
+      }
+    },
+  });
+  return found;
+}
+
+// =============================================================================
+// Extraction
+// =============================================================================
+
+/**
+ * Extracts context workflow definitions from a file.
+ */
+export function extractContextWorkflows(path: NodePath<t.Program>, state: any): void {
+  const compilerState = state as CompilerState;
+  const contextWorkflows: ContextWorkflow[] = [];
+
+  // Track variable bindings for context names
+  const contextNames = new Map<string, string>(); // variable name → context name
+
+  path.traverse({
+    // Detect: const XContext = createContext(...)
+    VariableDeclarator(declPath) {
+      const init = declPath.node.init;
+      if (!init || !t.isCallExpression(init)) return;
+      if (!t.isIdentifier(init.callee, { name: 'createContext' })) return;
+      if (!t.isIdentifier(declPath.node.id)) return;
+
+      const contextName = declPath.node.id.name;
+      contextNames.set(contextName, contextName);
+
+      const workflow: ContextWorkflow = {
+        name: contextName,
+        fields: [],
+        reducerActions: [],
+      };
+
+      // Try to extract type parameter: createContext<T>(default)
+      const typeParams = (init as any).typeParameters;
+      if (typeParams && t.isTSTypeParameterInstantiation(typeParams)) {
+        const typeArg = typeParams.params[0];
+        if (t.isTSTypeReference(typeArg) && t.isIdentifier(typeArg.typeName)) {
+          // Look for the interface definition
+          const interfaceName = typeArg.typeName.name;
+          extractFieldsFromInterface(path, interfaceName, workflow);
+        }
+      }
+
+      // Extract initial state from default value argument
+      if (init.arguments.length > 0 && t.isObjectExpression(init.arguments[0])) {
+        workflow.initialState = extractObjectLiteral(init.arguments[0]);
+      }
+
+      contextWorkflows.push(workflow);
+    },
+
+    // Detect useReducer(reducer, initialState) and extract reducer cases
+    CallExpression(callPath) {
+      if (!t.isIdentifier(callPath.node.callee, { name: 'useReducer' })) return;
+      const args = callPath.node.arguments;
+      if (args.length < 1) return;
+
+      const reducerArg = args[0];
+      if (!t.isIdentifier(reducerArg)) return;
+
+      const reducerName = reducerArg.name;
+
+      // Find the reducer function and extract switch cases
+      const actions = extractReducerActions(path, reducerName);
+
+      // Associate with the nearest context workflow
+      if (contextWorkflows.length > 0) {
+        const lastWorkflow = contextWorkflows[contextWorkflows.length - 1];
+        lastWorkflow.reducerActions = actions;
+        lastWorkflow.reducerName = reducerName;
+      }
+    },
+  });
+
+  // Store in compiler state metadata
+  if (contextWorkflows.length > 0) {
+    if (!compilerState.metadata) compilerState.metadata = {};
+    const meta = compilerState.metadata as Record<string, unknown>;
+    meta.contextWorkflows = contextWorkflows;
+  }
+}
+
+/**
+ * Extracts fields from a TypeScript interface.
+ */
+function extractFieldsFromInterface(
+  path: NodePath<t.Program>,
+  interfaceName: string,
+  workflow: ContextWorkflow
+): void {
+  path.traverse({
+    TSInterfaceDeclaration(ifacePath) {
+      if (!t.isIdentifier(ifacePath.node.id, { name: interfaceName })) return;
+
+      for (const prop of ifacePath.node.body.body) {
+        if (!t.isTSPropertySignature(prop)) continue;
+        if (!t.isIdentifier(prop.key)) continue;
+
+        const field: ContextField = {
+          name: prop.key.name,
+          type: extractTSType(prop.typeAnnotation),
+          optional: prop.optional || false,
+        };
+
+        workflow.fields.push(field);
+      }
+    },
+  });
+}
+
+/**
+ * Extracts a simplified type name from a TypeScript type annotation.
+ */
+function extractTSType(annotation: t.TypeAnnotation | t.TSTypeAnnotation | t.Noop | null | undefined): string {
+  if (!annotation || !t.isTSTypeAnnotation(annotation)) return 'unknown';
+
+  const typeNode = annotation.typeAnnotation;
+
+  if (t.isTSStringKeyword(typeNode)) return 'string';
+  if (t.isTSNumberKeyword(typeNode)) return 'number';
+  if (t.isTSBooleanKeyword(typeNode)) return 'boolean';
+  if (t.isTSArrayType(typeNode)) return `${extractTSTypeNode(typeNode.elementType)}[]`;
+  if (t.isTSTypeReference(typeNode) && t.isIdentifier(typeNode.typeName)) return typeNode.typeName.name;
+
+  return 'unknown';
+}
+
+/**
+ * Extracts type name from a TSType node.
+ */
+function extractTSTypeNode(node: t.TSType): string {
+  if (t.isTSStringKeyword(node)) return 'string';
+  if (t.isTSNumberKeyword(node)) return 'number';
+  if (t.isTSBooleanKeyword(node)) return 'boolean';
+  if (t.isTSTypeReference(node) && t.isIdentifier(node.typeName)) return node.typeName.name;
+  return 'unknown';
+}
+
+/**
+ * Extracts reducer action types from a reducer function.
+ * Looks for switch(action.type) { case 'X': ... }
+ */
+function extractReducerActions(
+  path: NodePath<t.Program>,
+  reducerName: string
+): ReducerAction[] {
+  const actions: ReducerAction[] = [];
+
+  path.traverse({
+    FunctionDeclaration(funcPath) {
+      if (!funcPath.node.id || funcPath.node.id.name !== reducerName) return;
+
+      // Look for switch statement on action.type
+      funcPath.traverse({
+        SwitchStatement(switchPath) {
+          for (const switchCase of switchPath.node.cases) {
+            if (!switchCase.test) continue; // skip default
+
+            if (t.isStringLiteral(switchCase.test)) {
+              actions.push({
+                type: switchCase.test.value,
+              });
+            }
+          }
+        },
+      });
+    },
+  });
+
+  return actions;
+}
+
+/**
+ * Extracts a simple object literal to a Record.
+ */
+function extractObjectLiteral(obj: t.ObjectExpression): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const prop of obj.properties) {
+    if (!t.isObjectProperty(prop) || !t.isIdentifier(prop.key)) continue;
+
+    if (t.isStringLiteral(prop.value)) result[prop.key.name] = prop.value.value;
+    else if (t.isNumericLiteral(prop.value)) result[prop.key.name] = prop.value.value;
+    else if (t.isBooleanLiteral(prop.value)) result[prop.key.name] = prop.value.value;
+    else if (t.isNullLiteral(prop.value)) result[prop.key.name] = null;
+    else if (t.isArrayExpression(prop.value)) result[prop.key.name] = [];
+    else if (t.isObjectExpression(prop.value)) result[prop.key.name] = extractObjectLiteral(prop.value);
+  }
+
+  return result;
+}