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

package/src/action-compiler.ts

@@ -1,361 +0,0 @@
-/**
- * Action Compiler — extracts server action signatures from *.server.ts files.
- *
- * Server action files define backend-side handlers that execute during
- * workflow transitions. This compiler:
- *   - Extracts exported function signatures (name, params, async, JSDoc)
- *   - Registers actions on the parent blueprint metadata
- *   - Maps each action to a Rust execution endpoint
- *   - Resolves action references from model hooks and transitions
- *
- * INPUT (actions/pricing.server.ts):
- *   export async function calculateEstimatedFare(ctx: TransitionContext): Promise<ActionResult> { ... }
- *   export async function calculateActualFare(ctx: TransitionContext): Promise<ActionResult> { ... }
- *
- * OUTPUT:
- *   ServerActionRegistration[] with endpoint mappings and parameter metadata
- */
-
-import { transformSync } from '@babel/core';
-import type { IRWorkflowDefinition } from '@mindmatrix/player-core';
-import babelPlugin from './babel';
-import type { ServerAction } from './babel/extractors/server-action-extractor';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface ServerActionRegistration {
-  /** Function name (e.g., 'calculateEstimatedFare'). */
-  name: string;
-  /** Source file path. */
-  sourceFile: string;
-  /** Whether the function is async. */
-  async: boolean;
-  /** Parameter names. */
-  params: string[];
-  /** TypeScript type of the context parameter. */
-  contextType?: string;
-  /** JSDoc description. */
-  description?: string;
-  /** Full function source text (for round-trip preservation). */
-  body?: string;
-  /** TypeScript return type (e.g., 'Promise<ActionResult>'). */
-  returnType?: string;
-  /** Generated Rust execution endpoint. */
-  endpoint: string;
-  /** Action group (derived from filename without .server.ts). */
-  group: string;
-  /** Fully qualified action ID for blueprint registration. */
-  actionId: string;
-}
-
-export interface ActionCompilationResult {
-  /** All extracted server actions. */
-  actions: ServerActionRegistration[];
-  /** Actions grouped by source file. */
-  byFile: Map<string, ServerActionRegistration[]>;
-  /** Actions grouped by action group. */
-  byGroup: Map<string, ServerActionRegistration[]>;
-  /** Compilation errors. */
-  errors: Array<{ file: string; message: string }>;
-}
-
-export interface ActionCompilerOptions {
-  /** Compilation mode. Default: 'infer'. */
-  mode?: 'strict' | 'infer';
-  /** Blueprint slug (used for endpoint generation). */
-  blueprintSlug?: string;
-  /** API base path for endpoint generation. Default: '/api/v1/actions'. */
-  apiBasePath?: string;
-}
-
-// =============================================================================
-// Utilities
-// =============================================================================
-
-/**
- * Extracts the action group from a server action filename.
- * 'actions/pricing.server.ts' → 'pricing'
- * 'payments.server.ts' → 'payments'
- */
-function extractActionGroup(filename: string): string {
-  const base = filename.split('/').pop() || filename;
-  return base.replace(/\.server\.(ts|tsx|js|jsx)$/, '');
-}
-
-/**
- * Generates a Rust execution endpoint for an action.
- * Blueprint slug + group + action name → endpoint path
- */
-function generateEndpoint(
-  blueprintSlug: string,
-  group: string,
-  actionName: string,
-  apiBasePath: string,
-): string {
-  return apiBasePath + '/' + blueprintSlug + '/' + group + '/' + actionName;
-}
-
-/**
- * Generates a fully qualified action ID.
- */
-function generateActionId(group: string, actionName: string): string {
-  return group + ':' + actionName;
-}
-
-/**
- * Extracts the full source text of each exported function in a server action file.
- *
- * Uses brace-matching from the function keyword to the closing brace.
- * Returns a map of function name → full function source text (including signature).
- */
-function extractFunctionBodies(source: string): Map<string, { body: string; returnType?: string }> {
-  const result = new Map<string, { body: string; returnType?: string }>();
-
-  // Match exported function declarations: export (async )function name(...)
-  const funcHeaderRegex = /export\s+(async\s+)?function\s+(\w+)\s*\(/g;
-  let headerMatch;
-  while ((headerMatch = funcHeaderRegex.exec(source)) !== null) {
-    const funcName = headerMatch[2];
-    const startIdx = headerMatch.index;
-
-    // Find the opening brace of the function body
-    let braceStart = source.indexOf('{', headerMatch.index + headerMatch[0].length);
-    if (braceStart === -1) continue;
-
-    // Extract return type from between closing paren and opening brace
-    const signatureSlice = source.slice(headerMatch.index + headerMatch[0].length, braceStart);
-    const returnTypeMatch = signatureSlice.match(/\)\s*:\s*([^{]+)/);
-    const returnType = returnTypeMatch
-      ? returnTypeMatch[1].trim()
-      : undefined;
-
-    // Find matching closing brace using brace counting
-    let depth = 0;
-    let endIdx = braceStart;
-    for (let i = braceStart; i < source.length; i++) {
-      if (source[i] === '{') depth++;
-      else if (source[i] === '}') {
-        depth--;
-        if (depth === 0) {
-          endIdx = i + 1;
-          break;
-        }
-      }
-    }
-
-    const fullText = source.slice(startIdx, endIdx);
-    result.set(funcName, { body: fullText, returnType });
-  }
-
-  return result;
-}
-
-/**
- * Extracts function signatures via regex (fast path, no Babel needed).
- * Used when full Babel compilation is not desired.
- */
-function extractActionsViaRegex(
-  source: string,
-): Array<{ name: string; async: boolean; params: string[]; description?: string }> {
-  const actions: Array<{ name: string; async: boolean; params: string[]; description?: string }> = [];
-
-  // Match exported async/sync function declarations
-  const funcRegex = /(?:\/\*\*([\s\S]*?)\*\/\s*)?export\s+(async\s+)?function\s+(\w+)\s*\(([^)]*)\)/g;
-  let match;
-  while ((match = funcRegex.exec(source)) !== null) {
-    const jsdoc = match[1];
-    const isAsync = !!match[2];
-    const name = match[3];
-    const paramsStr = match[4];
-
-    // Extract param names (strip types)
-    const params = paramsStr
-      .split(',')
-      .map(p => p.trim().split(':')[0].trim().split('?')[0].trim())
-      .filter(Boolean);
-
-    // Extract description from JSDoc
-    let description: string | undefined;
-    if (jsdoc) {
-      const lines = jsdoc.split('\n');
-      for (const line of lines) {
-        const trimmed = line.replace(/^\s*\*\s?/, '').trim();
-        if (trimmed && !trimmed.startsWith('@')) {
-          description = trimmed;
-          break;
-        }
-      }
-    }
-
-    actions.push({ name, async: isAsync, params, description });
-  }
-
-  // Match exported const arrow functions
-  const arrowRegex = /export\s+const\s+(\w+)\s*=\s*(async\s+)?\([^)]*\)/g;
-  while ((match = arrowRegex.exec(source)) !== null) {
-    const name = match[1];
-    const isAsync = !!match[2];
-    // Simple param extraction for arrow functions
-    const arrowParamMatch = source.slice(match.index).match(/\(([^)]*)\)/);
-    const params = arrowParamMatch
-      ? arrowParamMatch[1].split(',').map(p => p.trim().split(':')[0].trim()).filter(Boolean)
-      : [];
-    actions.push({ name, async: isAsync, params });
-  }
-
-  return actions;
-}
-
-// =============================================================================
-// Main API
-// =============================================================================
-
-/**
- * Compiles all server action files and extracts their function signatures.
- *
- * @param files - Record of filename → source (only *.server.ts files)
- * @param options - Compilation options
- * @returns ActionCompilationResult with all registered actions
- */
-export function compileActions(
-  files: Record<string, string>,
-  options: ActionCompilerOptions = {},
-): ActionCompilationResult {
-  const mode = options.mode || 'infer';
-  const blueprintSlug = options.blueprintSlug || 'app';
-  const apiBasePath = options.apiBasePath || '/api/v1/actions';
-
-  const allActions: ServerActionRegistration[] = [];
-  const byFile = new Map<string, ServerActionRegistration[]>();
-  const byGroup = new Map<string, ServerActionRegistration[]>();
-  const errors: Array<{ file: string; message: string }> = [];
-
-  for (const [filename, source] of Object.entries(files)) {
-    const group = extractActionGroup(filename);
-    const fileActions: ServerActionRegistration[] = [];
-
-    // Extract full function bodies from source for round-trip preservation
-    const bodies = extractFunctionBodies(source);
-
-    try {
-      // Try full Babel compilation first
-      const parserPlugins = filename.endsWith('.tsx')
-        ? (['typescript', 'jsx'] as const)
-        : (['typescript'] as const);
-
-      const babelResult = transformSync(source, {
-        filename,
-        plugins: [[babelPlugin, { mode }]],
-        parserOpts: { plugins: parserPlugins as any, attachComment: true },
-      });
-
-      const ir: IRWorkflowDefinition | null =
-        (babelResult as any)?.metadata?.mindmatrixIR ?? null;
-
-      // Extract server actions from IR metadata
-      const meta = ir?.metadata as Record<string, unknown> | undefined;
-      const babelActions = meta?.serverActions as ServerAction[] | undefined;
-
-      if (babelActions && babelActions.length > 0) {
-        for (const action of babelActions) {
-          const bodyInfo = bodies.get(action.name);
-          const reg: ServerActionRegistration = {
-            name: action.name,
-            sourceFile: filename,
-            async: action.async,
-            params: action.params,
-            contextType: action.contextType,
-            description: action.description,
-            body: bodyInfo?.body,
-            returnType: bodyInfo?.returnType,
-            endpoint: generateEndpoint(blueprintSlug, group, action.name, apiBasePath),
-            group,
-            actionId: generateActionId(group, action.name),
-          };
-          fileActions.push(reg);
-        }
-      } else {
-        // Fallback to regex extraction
-        const regexActions = extractActionsViaRegex(source);
-        for (const action of regexActions) {
-          const bodyInfo = bodies.get(action.name);
-          const reg: ServerActionRegistration = {
-            name: action.name,
-            sourceFile: filename,
-            async: action.async,
-            params: action.params,
-            description: action.description,
-            body: bodyInfo?.body,
-            returnType: bodyInfo?.returnType,
-            endpoint: generateEndpoint(blueprintSlug, group, action.name, apiBasePath),
-            group,
-            actionId: generateActionId(group, action.name),
-          };
-          fileActions.push(reg);
-        }
-      }
-    } catch (err) {
-      // On Babel failure, fall back to regex extraction
-      errors.push({ file: filename, message: (err as Error).message });
-
-      const regexActions = extractActionsViaRegex(source);
-      for (const action of regexActions) {
-        const bodyInfo = bodies.get(action.name);
-        const reg: ServerActionRegistration = {
-          name: action.name,
-          sourceFile: filename,
-          async: action.async,
-          params: action.params,
-          description: action.description,
-          body: bodyInfo?.body,
-          returnType: bodyInfo?.returnType,
-          endpoint: generateEndpoint(blueprintSlug, group, action.name, apiBasePath),
-          group,
-          actionId: generateActionId(group, action.name),
-        };
-        fileActions.push(reg);
-      }
-    }
-
-    byFile.set(filename, fileActions);
-    if (!byGroup.has(group)) byGroup.set(group, []);
-    byGroup.get(group)!.push(...fileActions);
-    allActions.push(...fileActions);
-  }
-
-  return { actions: allActions, byFile, byGroup, errors };
-}
-
-/**
- * Resolves action references found in model hooks/transitions to registered actions.
- * Returns a map of action name → ServerActionRegistration.
- */
-export function resolveActionReferences(
-  actionNames: string[],
-  registrations: ServerActionRegistration[],
-): Map<string, ServerActionRegistration | null> {
-  const result = new Map<string, ServerActionRegistration | null>();
-  const byName = new Map(registrations.map(r => [r.name, r]));
-
-  for (const name of actionNames) {
-    // Try exact match
-    if (byName.has(name)) {
-      result.set(name, byName.get(name)!);
-      continue;
-    }
-    // Try group:name format
-    const colonIdx = name.indexOf(':');
-    if (colonIdx > 0) {
-      const actionName = name.slice(colonIdx + 1);
-      if (byName.has(actionName)) {
-        result.set(name, byName.get(actionName)!);
-        continue;
-      }
-    }
-    result.set(name, null);
-  }
-
-  return result;
-}

package/src/babel/emitters/experience-transform.ts

@@ -1,199 +0,0 @@
-/**
- * Experience Transform — converts IRExperienceNode to frontend ExperienceNode format.
- *
- * The React compiler emits player-core IR types (IRExperienceNode, IRDataSource).
- * The frontend runtime expects the richer types from experience-tree-types.ts.
- * This transform bridges the gap by:
- *
- *   1. Hoisting legacy config fields (slot, className, displayName) to top-level
- *   2. Mapping IRDataSource → frontend DataSource shape (adding default fields)
- *   3. Recursively transforming the entire node tree
- *
- * This is a pure function with no side effects — safe for tests and caching.
- */
-
-import type { IRDataSource } from '@mindmatrix/player-core';
-
-/**
- * Extended IR node type — the compiler emits additional fields beyond the
- * base player-core IRExperienceNode. These are consumed by the frontend CTR.
- * We use our own interface to avoid fighting the base type's narrowness.
- */
-interface IRExperienceNode {
-  id: string;
-  component?: string;
-  config?: Record<string, unknown>;
-  bindings?: Record<string, string>;
-  children?: IRExperienceNode[];
-  dataSources?: IRDataSource[];
-  dataScope?: string;
-  layout?: string;
-  visible_when?: string;
-  displayName?: string;
-  experienceId?: string;
-  slot?: string;
-  className?: string;
-  style?: Record<string, unknown>;
-  overrides?: Record<string, unknown>;
-}
-
-/**
- * Frontend-compatible ExperienceNode shape.
- * Matches packages/frontend/src/experiences/experience-tree-types.ts.
- * Declared locally to avoid a cross-package import dependency.
- */
-export interface FrontendExperienceNode {
-  id: string;
-  displayName?: string;
-  experienceId?: string;
-  component?: string;
-  slot?: string;
-  dataSources?: FrontendDataSource[];
-  dataScope?: string;
-  children?: FrontendExperienceNode[];
-  config?: Record<string, unknown>;
-  layout?: string;
-  className?: string;
-  style?: Record<string, unknown>;
-  overrides?: Record<string, unknown>;
-  bindings?: Record<string, string>;
-  visible_when?: string;
-}
-
-/**
- * Frontend-compatible DataSource — superset of IR DataSource with default fields.
- */
-export interface FrontendDataSource {
-  type: 'workflow' | 'api' | 'ref' | 'static';
-  name: string;
-  [key: string]: unknown;
-}
-
-/**
- * Transforms an IRExperienceNode tree into frontend-compatible ExperienceNode format.
- *
- * Handles:
- * - Hoisting config.slot → top-level slot (backward compat for old IR)
- * - Hoisting config.className → top-level className
- * - Hoisting config.displayName → top-level displayName
- * - Mapping IRDataSource[] → FrontendDataSource[] with defaults
- * - Recursive child transformation
- */
-export function transformToFrontend(node: IRExperienceNode): FrontendExperienceNode {
-  const result: FrontendExperienceNode = {
-    id: node.id,
-  };
-
-  // Top-level fields (prefer IR top-level, fall back to config for backward compat)
-  if (node.displayName) {
-    result.displayName = node.displayName;
-  } else if (node.config?.displayName && typeof node.config.displayName === 'string') {
-    result.displayName = node.config.displayName;
-  }
-
-  if (node.experienceId) result.experienceId = node.experienceId;
-  if (node.component) result.component = node.component;
-
-  if (node.slot) {
-    result.slot = node.slot;
-  } else if (node.config?.slot && typeof node.config.slot === 'string') {
-    result.slot = node.config.slot;
-  }
-
-  if (node.className) {
-    result.className = node.className;
-  } else if (node.config?.className && typeof node.config.className === 'string') {
-    result.className = node.config.className;
-  }
-
-  if (node.style) result.style = node.style;
-  if (node.overrides) result.overrides = node.overrides;
-  if (node.layout) result.layout = node.layout;
-  if (node.dataScope) result.dataScope = node.dataScope;
-  if (node.bindings) result.bindings = node.bindings;
-  if (node.visible_when) result.visible_when = node.visible_when;
-
-  // Config — strip hoisted fields to avoid duplication
-  if (node.config) {
-    const cleaned = { ...node.config };
-    delete cleaned.slot;
-    delete cleaned.className;
-    delete cleaned.displayName;
-    if (Object.keys(cleaned).length > 0) {
-      result.config = cleaned;
-    }
-  }
-
-  // DataSources — map IR to frontend format
-  if (node.dataSources && node.dataSources.length > 0) {
-    result.dataSources = node.dataSources.map(transformDataSource);
-  }
-
-  // Children — recursive transform
-  if (node.children && node.children.length > 0) {
-    result.children = node.children.map(transformToFrontend);
-  }
-
-  return result;
-}
-
-/**
- * Maps an IRDataSource to frontend DataSource format.
- * Passes through all fields and adds sensible defaults where needed.
- */
-function transformDataSource(ds: IRDataSource): FrontendDataSource {
-  // Cast for property access — IRDataSource is a discriminated union
-  // but the compiler emits extended fields not in the base type definition.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const d = ds as any;
-  switch (ds.type) {
-    case 'workflow':
-      return {
-        type: 'workflow',
-        name: ds.name,
-        slug: ds.slug,
-        query: ds.query,
-        ...(d.instanceId && { instanceId: d.instanceId }),
-        ...(d.entity !== undefined && { entity: d.entity }),
-        ...(ds.paginated !== undefined && { paginated: ds.paginated }),
-        ...(ds.pageSize !== undefined && { pageSize: ds.pageSize }),
-        ...(d.filter && { filter: d.filter }),
-        ...(d.filters && { filters: d.filters }),
-        ...(ds.sort && { sort: ds.sort }),
-        ...(d.search && { search: d.search }),
-        ...(ds.searchFields && { searchFields: ds.searchFields }),
-        ...(ds.facets && { facets: ds.facets }),
-        ...(d.range && { range: d.range }),
-        ...(d.aggregate && { aggregate: d.aggregate }),
-        ...(ds.groupBy && { groupBy: ds.groupBy }),
-        ...(ds.parentInstanceId && { parentInstanceId: ds.parentInstanceId }),
-        ...(d.autoStart !== undefined && { autoStart: d.autoStart }),
-        ...(d.initialData && { initialData: d.initialData }),
-        ...(d.includeDefinition !== undefined && { includeDefinition: d.includeDefinition }),
-      };
-
-    case 'api':
-      return {
-        type: 'api',
-        name: ds.name,
-        endpoint: ds.endpoint,
-        ...(d.method && { method: d.method }),
-        ...(d.mapping && { mapping: d.mapping }),
-        ...(d.staleTime !== undefined && { staleTime: d.staleTime }),
-      };
-
-    case 'ref':
-      return {
-        type: 'ref',
-        name: ds.name,
-        expression: ds.expression,
-      };
-
-    case 'static':
-      return {
-        type: 'static',
-        name: ds.name,
-        data: ds.data,
-      };
-  }
-}

package/src/babel/emitters/ir-to-tsx-emitter.ts

@@ -1,110 +0,0 @@
-/**
- * IR-to-TSX Emitter — bridge module that re-exports the decompiler API
- * from the canonical location expected by the investigation doc (Appendix H).
- *
- * The full decompiler implementation lives in packages/react-compiler/src/decompiler/
- * (index.ts, ast-builder.ts, state-emitter.ts, sx-emitter.ts, project.ts).
- *
- * This module provides:
- *   - decompileToTSX() — the primary entry point per Appendix H §H.3
- *   - All supporting types and sub-emitters
- *
- * Usage:
- *   import { decompileToTSX } from './ir-to-tsx-emitter';
- *   const result = decompileToTSX(irDefinition, { includeAnnotation: true });
- *   console.log(result.code); // valid .workflow.tsx source
- */
-
-import type { IRWorkflowDefinition, IRExperienceNode } from '@mindmatrix/player-core';
-import {
-  decompile,
-  type DecompilerInput,
-  type DecompileOptions,
-  type DecompileResult,
-} from '../../decompiler';
-
-// =============================================================================
-// Public API
-// =============================================================================
-
-export type { DecompilerInput, DecompileOptions, DecompileResult };
-
-/**
- * Decompiles an IRWorkflowDefinition to valid .workflow.tsx source code.
- *
- * This is the primary entry point specified in Appendix H §H.3.
- * Uses @babel/types to construct a Babel AST, then @babel/generator to emit code.
- *
- * Emits:
- *   - useState for fields
- *   - useOnEnter/Exit for state effects
- *   - useTransition declarations
- *   - useWhileIn for during-actions
- *   - useOnEvent subscriptions
- *   - useOnChange watchers
- *   - useOnTransition effects
- *   - useRole declarations
- *   - useQuery/useMutation data sources
- *   - JSX return tree from experience nodes
- *   - @workflow JSDoc header
- *   - Proper imports from @mindmatrix/react
- *
- * @param definition - The IR workflow definition (with optional experience tree).
- * @param options - Decompile options (componentName, includeAnnotation, etc.).
- * @returns { code, imports, componentName }
- */
-export function decompileToTSX(
-  definition: IRWorkflowDefinition & { experience?: IRExperienceNode },
-  options?: DecompileOptions,
-): DecompileResult {
-  return decompile(definition as DecompilerInput, options);
-}
-
-/**
- * Convenience: checks if a definition needs the experience tree attached.
- *
- * The decompiler expects the experience tree either:
- *   1. As definition.experience (direct on the input)
- *   2. From (definition as any).views?.default (stored IR format)
- *   3. From definition.metadata?.experience (legacy format)
- *
- * This helper normalizes the input.
- */
-export function normalizeDecompilerInput(
-  definition: IRWorkflowDefinition,
-): DecompilerInput {
-  const input = { ...definition } as DecompilerInput;
-
-  // Try views.default first (IR format from emitIR)
-  if (!input.experience) {
-    const views = (definition as any).views;
-    if (views?.default) {
-      input.experience = views.default;
-    }
-  }
-
-  // Fall back to metadata.experience (legacy format)
-  if (!input.experience && definition.metadata?.experience) {
-    input.experience = definition.metadata.experience as IRExperienceNode;
-  }
-
-  return input;
-}
-
-// =============================================================================
-// Re-exports for convenience
-// =============================================================================
-
-export { decompile } from '../../decompiler';
-export { buildJSXTree } from '../../decompiler/ast-builder';
-export { emitSxProp, valueToExpression } from '../../decompiler/sx-emitter';
-export {
-  emitFieldDeclarations,
-  emitStateEffects,
-  emitTransitionDeclarations,
-  emitRoleDeclarations,
-  emitQueryDeclarations,
-  emitChangeWatchers,
-  emitEventSubscriptions,
-  emitTransitionEffects,
-} from '../../decompiler/state-emitter';