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

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

@@ -1,303 +0,0 @@
-/**
- * Router Extractor — derives a router workflow from file-based routing structure.
- *
- * Converts a set of page file paths into an IRWorkflowDefinition where:
- * - Each page → a state
- * - navigation calls → transitions
- * - layout files → context boundaries
- * - [param] segments → parameterized states
- *
- * INPUT (file paths):
- *   app/page.tsx          → state HOME (START)
- *   app/chat/page.tsx     → state CHAT
- *   app/chat/[channelId]/page.tsx → state CHAT_CHANNEL
- *   app/settings/page.tsx → state SETTINGS
- *
- * OUTPUT:
- *   IRWorkflowDefinition with states, transitions, and route metadata
- *
- * This is a standalone utility — it doesn't run as part of the Babel visitor.
- * Instead, it's called by the build pipeline with a list of discovered files.
- */
-
-import type {
-  IRWorkflowDefinition,
-  IRStateDefinition,
-  IRTransitionDefinition,
-  IRFieldDefinition,
-} from '@mindmatrix/player-core';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface PageFile {
-  /** Relative path from app root (e.g., 'chat/[channelId]/page.tsx') */
-  relativePath: string;
-  /** Absolute file path */
-  absolutePath: string;
-  /** Exported component name (if detectable) */
-  componentName?: string;
-  /** Whether this is a layout file */
-  isLayout?: boolean;
-  /** Navigation targets found in the file (paths navigated to) */
-  navigationTargets?: string[];
-}
-
-export interface RouteState {
-  /** State name (e.g., 'CHAT_CHANNEL') */
-  name: string;
-  /** Route path (e.g., '/chat/:channelId') */
-  path: string;
-  /** Dynamic parameters (e.g., ['channelId']) */
-  params: string[];
-  /** Layout boundary this route belongs to */
-  layoutBoundary?: string;
-  /** Source page file */
-  sourceFile: string;
-  /** State type */
-  type: 'START' | 'REGULAR';
-}
-
-export interface RouterExtractionOptions {
-  /** Blueprint slug for the router workflow */
-  slug?: string;
-  /** Root directory name (defaults to 'app') */
-  rootDir?: string;
-  /** Page file naming convention */
-  pageFileName?: string;
-  /** Layout file naming convention */
-  layoutFileName?: string;
-}
-
-// =============================================================================
-// Path → State Name conversion
-// =============================================================================
-
-/**
- * Converts a route path to a state name.
- * 'chat/[channelId]' → 'CHAT_CHANNEL'
- * '' (root) → 'HOME'
- */
-export function pathToStateName(routePath: string): string {
-  if (!routePath || routePath === '' || routePath === '/') return 'HOME';
-
-  return routePath
-    .split('/')
-    .filter(Boolean)
-    .map((segment) => {
-      // [param] → strip brackets
-      if (segment.startsWith('[') && segment.endsWith(']')) {
-        return segment.slice(1, -1);
-      }
-      return segment;
-    })
-    .join('_')
-    .replace(/([a-z])([A-Z])/g, '$1_$2')
-    .toUpperCase()
-    .replace(/-/g, '_');
-}
-
-/**
- * Converts a route path to a URL pattern.
- * 'chat/[channelId]/page.tsx' → '/chat/:channelId'
- */
-export function pathToUrlPattern(relativePath: string, pageFileName = 'page.tsx'): string {
-  // Remove page filename
-  let routePath = relativePath.replace(new RegExp(`/?${pageFileName.replace('.', '\\.')}$`), '');
-
-  // Convert [param] to :param
-  routePath = routePath.replace(/\[([^\]]+)\]/g, ':$1');
-
-  // Ensure leading slash
-  return '/' + routePath;
-}
-
-/**
- * Extracts dynamic parameters from a route path.
- * 'chat/[channelId]/page.tsx' → ['channelId']
- */
-export function extractParams(relativePath: string): string[] {
-  const params: string[] = [];
-  const paramRegex = /\[([^\]]+)\]/g;
-  let match: RegExpExecArray | null;
-  while ((match = paramRegex.exec(relativePath)) !== null) {
-    params.push(match[1]);
-  }
-  return params;
-}
-
-// =============================================================================
-// Main extraction
-// =============================================================================
-
-/**
- * Extracts a router workflow from a set of page files.
- */
-export function extractRouterWorkflow(
-  pages: PageFile[],
-  options: RouterExtractionOptions = {}
-): IRWorkflowDefinition {
-  const {
-    slug = 'app-router',
-    pageFileName = 'page.tsx',
-    layoutFileName = 'layout.tsx',
-  } = options;
-
-  // Separate page files from layout files
-  const pageFiles = pages.filter((p) => !p.isLayout && p.relativePath.endsWith(pageFileName));
-  const layoutFiles = pages.filter((p) => p.isLayout || p.relativePath.endsWith(layoutFileName));
-
-  // Build route states
-  const routeStates: RouteState[] = [];
-  const stateMap = new Map<string, RouteState>();
-
-  for (const page of pageFiles) {
-    const routePath = page.relativePath.replace(new RegExp(`/?${pageFileName.replace('.', '\\.')}$`), '');
-    const stateName = pathToStateName(routePath);
-    const urlPattern = pathToUrlPattern(page.relativePath, pageFileName);
-    const params = extractParams(page.relativePath);
-
-    // Find layout boundary
-    const layoutBoundary = findLayoutBoundary(page.relativePath, layoutFiles);
-
-    const routeState: RouteState = {
-      name: stateName,
-      path: urlPattern,
-      params,
-      layoutBoundary,
-      sourceFile: page.relativePath,
-      type: stateName === 'HOME' ? 'START' : 'REGULAR',
-    };
-
-    routeStates.push(routeState);
-    stateMap.set(stateName, routeState);
-  }
-
-  // Ensure HOME exists
-  if (!stateMap.has('HOME') && routeStates.length > 0) {
-    routeStates[0].type = 'START';
-  }
-
-  // Build IR states
-  const states: IRStateDefinition[] = routeStates.map((rs) => ({
-    name: rs.name,
-    type: rs.type,
-    description: `Route: ${rs.path}`,
-    on_enter: [],
-    during: [],
-    on_exit: [],
-  }));
-
-  // Build transitions from navigation targets
-  const transitions: IRTransitionDefinition[] = [];
-  let transitionId = 0;
-
-  for (const page of pageFiles) {
-    if (!page.navigationTargets) continue;
-    const fromPath = page.relativePath.replace(new RegExp(`/?${pageFileName.replace('.', '\\.')}$`), '');
-    const fromState = pathToStateName(fromPath);
-
-    for (const target of page.navigationTargets) {
-      // Convert target path to state name
-      const targetPath = target.replace(/^\//, '').replace(/\/page\.(tsx|ts|jsx|js)$/, '');
-      const toState = pathToStateName(targetPath);
-
-      // Only create transition if target state exists
-      if (stateMap.has(toState) || toState === fromState) continue;
-
-      // Create navigate transition
-      const transitionName = `navigate_to_${toState.toLowerCase()}`;
-      transitions.push({
-        name: transitionName,
-        from: [fromState],
-        to: toState,
-        actions: [],
-        conditions: [],
-      });
-      transitionId++;
-    }
-  }
-
-  // Add universal back/navigate transitions
-  if (routeStates.length > 1) {
-    // Add a generic navigate_home transition from all non-home states
-    for (const rs of routeStates) {
-      if (rs.type !== 'START') {
-        transitions.push({
-          name: `navigate_home_from_${rs.name.toLowerCase()}`,
-          from: [rs.name],
-          to: 'HOME',
-          actions: [],
-          conditions: [],
-        });
-      }
-    }
-  }
-
-  // Build fields for route parameters
-  const fields: IRFieldDefinition[] = [];
-  const seenParams = new Set<string>();
-
-  for (const rs of routeStates) {
-    for (const param of rs.params) {
-      if (seenParams.has(param)) continue;
-      seenParams.add(param);
-      fields.push({
-        name: param,
-        type: 'text',
-        required: false,
-        default_value: '',
-      });
-    }
-  }
-
-  // Build route metadata
-  const routeMetadata = routeStates.map((rs) => ({
-    state: rs.name,
-    path: rs.path,
-    params: rs.params,
-    layoutBoundary: rs.layoutBoundary,
-    sourceFile: rs.sourceFile,
-  }));
-
-  return {
-    slug,
-    name: 'Router',
-    version: '1.0.0',
-    description: 'Auto-derived router workflow from file-based routing',
-    category: 'router',
-    fields,
-    states,
-    transitions,
-    roles: [],
-    tags: [{ tag_name: 'auto-derived' }, { tag_name: 'router' }],
-    metadata: {
-      runtime: 'local',
-      routes: routeMetadata,
-      layoutBoundaries: layoutFiles.map((l) => l.relativePath),
-    },
-  };
-}
-
-/**
- * Finds the nearest layout boundary for a page file.
- */
-function findLayoutBoundary(
-  pageRelativePath: string,
-  layoutFiles: PageFile[]
-): string | undefined {
-  const layoutPaths = layoutFiles.map((l) => l.relativePath);
-
-  // Walk up the directory tree to find nearest layout
-  const parts = pageRelativePath.split('/');
-  for (let i = parts.length - 1; i >= 0; i--) {
-    const dir = parts.slice(0, i).join('/');
-    const layoutPath = dir ? `${dir}/layout.tsx` : 'layout.tsx';
-    if (layoutPaths.includes(layoutPath)) {
-      return layoutPath;
-    }
-  }
-
-  return undefined;
-}

package/src/babel/extractors/server-action-extractor.ts

@@ -1,173 +0,0 @@
-/**
- * Server Action Extractor — extracts exported functions from *.server.ts files.
- *
- * Server action files define backend-side handlers that are referenced in
- * model hooks and transition actions.
- *
- * INPUT (actions.server.ts):
- *   export async function notifyMembers(ctx: TransitionContext) {
- *     const members = await ctx.refs('member', { channel_id: ctx.env.instance_id });
- *     for (const m of members) {
- *       await ctx.emit('notification:send', { user_id: m.stateData.user_id });
- *     }
- *   }
- *
- *   export function logDeactivation(ctx: TransitionContext) {
- *     ctx.log('Channel deactivated', { channel_id: ctx.env.instance_id });
- *   }
- *
- * OUTPUT (stored in compilerState metadata.serverActions[]):
- *   [
- *     { name: 'notifyMembers', async: true, params: ['ctx'] },
- *     { name: 'logDeactivation', async: false, params: ['ctx'] },
- *   ]
- */
-
-import type { NodePath } from '@babel/traverse';
-import * as t from '@babel/types';
-import type { CompilerState } from '../../types';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface ServerAction {
-  /** Function name. */
-  name: string;
-  /** Whether the function is async. */
-  async: boolean;
-  /** Parameter names. */
-  params: string[];
-  /** TypeScript type of first parameter (if any). */
-  contextType?: string;
-  /** Description from JSDoc (if any). */
-  description?: string;
-}
-
-// =============================================================================
-// Detection
-// =============================================================================
-
-/**
- * Checks if a file is a server action file.
- * Convention: filename ends with .server.ts or .server.tsx
- */
-export function isServerActionFile(filename: string | undefined): boolean {
-  if (!filename) return false;
-  return /\.server\.(ts|tsx|js|jsx)$/.test(filename);
-}
-
-// =============================================================================
-// Extraction
-// =============================================================================
-
-/**
- * Extracts all exported functions from a server action file.
- */
-export function extractServerActions(path: NodePath<t.Program>, state: any): void {
-  const compilerState = state as CompilerState;
-  const serverActions: ServerAction[] = [];
-
-  for (const node of path.node.body) {
-    // export function name(ctx) { ... }
-    if (t.isExportNamedDeclaration(node)) {
-      const decl = node.declaration;
-
-      if (t.isFunctionDeclaration(decl) && decl.id) {
-        const action = extractFunctionAction(decl);
-        if (action) {
-          // Extract description from leading comments
-          const comments = node.leadingComments || decl.leadingComments || [];
-          action.description = extractDescription(comments);
-          serverActions.push(action);
-        }
-      }
-
-      // export const name = async (ctx) => { ... }
-      if (t.isVariableDeclaration(decl)) {
-        for (const varDecl of decl.declarations) {
-          if (!t.isIdentifier(varDecl.id)) continue;
-          const init = varDecl.init;
-          if (t.isArrowFunctionExpression(init) || t.isFunctionExpression(init)) {
-            const action: ServerAction = {
-              name: varDecl.id.name,
-              async: init.async || false,
-              params: init.params
-                .filter((p): p is t.Identifier => t.isIdentifier(p))
-                .map((p) => p.name),
-            };
-            // Extract context type from first param
-            if (init.params.length > 0) {
-              const firstParam = init.params[0];
-              if (t.isIdentifier(firstParam) && firstParam.typeAnnotation) {
-                action.contextType = extractTypeName(firstParam.typeAnnotation);
-              }
-            }
-            serverActions.push(action);
-          }
-        }
-      }
-    }
-  }
-
-  // Store in compiler state metadata
-  if (serverActions.length > 0) {
-    if (!compilerState.metadata) compilerState.metadata = {};
-    (compilerState.metadata as Record<string, unknown>).serverActions = serverActions;
-  }
-}
-
-/**
- * Extracts a ServerAction from a FunctionDeclaration.
- */
-function extractFunctionAction(decl: t.FunctionDeclaration): ServerAction | null {
-  if (!decl.id) return null;
-
-  const action: ServerAction = {
-    name: decl.id.name,
-    async: decl.async || false,
-    params: decl.params
-      .filter((p): p is t.Identifier => t.isIdentifier(p))
-      .map((p) => p.name),
-  };
-
-  // Extract context type from first param
-  if (decl.params.length > 0) {
-    const firstParam = decl.params[0];
-    if (t.isIdentifier(firstParam) && firstParam.typeAnnotation) {
-      action.contextType = extractTypeName(firstParam.typeAnnotation);
-    }
-  }
-
-  return action;
-}
-
-/**
- * Extracts a type name from a type annotation.
- */
-function extractTypeName(annotation: t.TypeAnnotation | t.TSTypeAnnotation | t.Noop): string | undefined {
-  if (t.isTSTypeAnnotation(annotation)) {
-    const typeNode = annotation.typeAnnotation;
-    if (t.isTSTypeReference(typeNode) && t.isIdentifier(typeNode.typeName)) {
-      return typeNode.typeName.name;
-    }
-  }
-  return undefined;
-}
-
-/**
- * Extracts a description from JSDoc comments.
- */
-function extractDescription(comments: readonly t.Comment[]): string | undefined {
-  for (const comment of comments) {
-    if (comment.type !== 'CommentBlock') continue;
-    const lines = comment.value.split('\n');
-    for (const line of lines) {
-      const trimmed = line.replace(/^\s*\*\s?/, '').trim();
-      if (trimmed && !trimmed.startsWith('@')) {
-        return trimmed;
-      }
-    }
-  }
-  return undefined;
-}

package/src/babel/extractors/server-action-hook-extractor.ts

@@ -1,72 +0,0 @@
-/**
- * Server Action Hook Extractor — extracts useServerAction() calls from .workflow.tsx.
- *
- * INPUT:
- *   const approve = useServerAction('approve-order', { instanceId: orderId });
- *
- * OUTPUT (stored in compilerState metadata.serverActionHooks[]):
- *   [{ name: 'approve-order', variableName: 'approve' }]
- *
- * The extracted info tells the runtime that this workflow depends on a
- * server-side action endpoint and needs the action to be available at
- * POST /api/v1/workflow/instances/{id}/actions/{name}.
- */
-
-import type { NodePath } from '@babel/traverse';
-import * as t from '@babel/types';
-import type { CompilerState } from '../../types';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface ServerActionHookEntry {
-  /** The action name (first argument to useServerAction). */
-  name: string;
-  /** The variable name the hook result is assigned to. */
-  variableName?: string;
-  /** Static instance ID if provided as a string literal. */
-  staticInstanceId?: string;
-}
-
-// =============================================================================
-// Extraction
-// =============================================================================
-
-/**
- * Extracts useServerAction('name', { instanceId }) calls into metadata.
- */
-export function extractServerActionHook(path: NodePath<t.CallExpression>, state: any): void {
-  const args = path.node.arguments;
-  if (args.length < 1) return;
-
-  const nameArg = args[0];
-  if (!t.isStringLiteral(nameArg)) return;
-
-  const compilerState = state as CompilerState;
-  const entry: ServerActionHookEntry = {
-    name: nameArg.value,
-  };
-
-  // Extract static instanceId if provided as string literal in options
-  if (args.length > 1 && t.isObjectExpression(args[1])) {
-    for (const prop of args[1].properties) {
-      if (!t.isObjectProperty(prop) || !t.isIdentifier(prop.key)) continue;
-      if (prop.key.name === 'instanceId' && t.isStringLiteral(prop.value)) {
-        entry.staticInstanceId = prop.value.value;
-      }
-    }
-  }
-
-  // Try to get the variable name from the parent VariableDeclarator
-  const parent = path.parentPath;
-  if (parent?.isVariableDeclarator() && t.isIdentifier(parent.node.id)) {
-    entry.variableName = parent.node.id.name;
-  }
-
-  // Store in compiler state metadata
-  if (!compilerState.metadata) compilerState.metadata = {};
-  const meta = compilerState.metadata as Record<string, unknown>;
-  if (!meta.serverActionHooks) meta.serverActionHooks = [];
-  (meta.serverActionHooks as ServerActionHookEntry[]).push(entry);
-}

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

@@ -1,88 +0,0 @@
-/**
- * Server State Extractor — extracts useServerState() calls from .workflow.tsx.
- *
- * INPUT:
- *   const { state, stateData, loading } = useServerState(instanceId);
- *   const order = useServerState('static-id', { onStateChange: handleChange });
- *
- * OUTPUT (stored in compilerState metadata.serverStateSubscriptions[]):
- *   [{ variableName: undefined, staticInstanceId: undefined }]
- *   [{ variableName: 'order', staticInstanceId: 'static-id' }]
- *
- * The extracted info tells the runtime that this workflow subscribes to
- * real-time server state via SSE at /api/v1/workflow/events.
- */
-
-import type { NodePath } from '@babel/traverse';
-import * as t from '@babel/types';
-import type { CompilerState } from '../../types';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface ServerStateEntry {
-  /** The variable name the hook result is assigned to. */
-  variableName?: string;
-  /** Static instance ID if provided as a string literal. */
-  staticInstanceId?: string;
-  /** Whether the enabled option is explicitly set to false. */
-  disabled?: boolean;
-}
-
-// =============================================================================
-// Extraction
-// =============================================================================
-
-/**
- * Extracts useServerState(instanceId, options?) calls into metadata.
- */
-export function extractServerState(path: NodePath<t.CallExpression>, state: any): void {
-  const args = path.node.arguments;
-  if (args.length < 1) return;
-
-  const compilerState = state as CompilerState;
-  const entry: ServerStateEntry = {};
-
-  // First arg: instance ID (could be string literal or variable)
-  const instanceArg = args[0];
-  if (t.isStringLiteral(instanceArg)) {
-    entry.staticInstanceId = instanceArg.value;
-  }
-
-  // Second arg: options object
-  if (args.length > 1 && t.isObjectExpression(args[1])) {
-    for (const prop of args[1].properties) {
-      if (!t.isObjectProperty(prop) || !t.isIdentifier(prop.key)) continue;
-      if (prop.key.name === 'enabled' && t.isBooleanLiteral(prop.value)) {
-        if (!prop.value.value) entry.disabled = true;
-      }
-    }
-  }
-
-  // Try to get the variable name from the parent VariableDeclarator
-  const parent = path.parentPath;
-  if (parent?.isVariableDeclarator()) {
-    if (t.isIdentifier(parent.node.id)) {
-      entry.variableName = parent.node.id.name;
-    } else if (t.isObjectPattern(parent.node.id)) {
-      // Destructured: const { state, stateData } = useServerState(...)
-      // Record the property names for documentation, use first as variableName
-      const props = parent.node.id.properties
-        .filter((p): p is t.ObjectProperty => t.isObjectProperty(p) && t.isIdentifier(p.key))
-        .map((p) => (p.key as t.Identifier).name);
-      if (props.length > 0) {
-        entry.variableName = props.join(', ');
-      }
-    }
-  }
-
-  // Store in compiler state metadata
-  if (!compilerState.metadata) compilerState.metadata = {};
-  const meta = compilerState.metadata as Record<string, unknown>;
-  if (!meta.serverStateSubscriptions) meta.serverStateSubscriptions = [];
-  (meta.serverStateSubscriptions as ServerStateEntry[]).push(entry);
-
-  // Also flag that this workflow requires SSE connectivity
-  meta.requiresSSE = true;
-}