@mmapp/react-compiler 0.1.0-alpha.1

package/src/decompiler/config-generator.ts

@@ -0,0 +1,151 @@
+/**
+ * config-generator.ts — generates mm.config.ts from definition metadata.
+ *
+ * Produces a configuration file that the compiler uses to locate and
+ * compile workflow sources in a project directory.
+ */
+
+import type { IRWorkflowDefinition } from '@mindmatrix/player-core';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface MmConfigData {
+  slug: string;
+  name: string;
+  version: string;
+  category: string | string[];
+  description?: string;
+  /** Blueprint-specific: application mode (e.g. 'full', 'embedded'). */
+  mode?: string;
+  /** Blueprint-specific: default runtime target. */
+  defaultRuntime?: string;
+  models: string[];
+  entries: string[];
+  actions: string[];
+  roles: string[];
+}
+
+// =============================================================================
+// Extraction
+// =============================================================================
+
+/**
+ * Extracts configuration data from an IR workflow definition.
+ */
+export function extractConfigData(
+  def: IRWorkflowDefinition,
+  modelPaths: string[],
+  entryPaths: string[],
+  actionPaths: string[],
+): MmConfigData {
+  const meta = def.metadata as Record<string, unknown> | undefined;
+  return {
+    slug: def.slug,
+    name: def.name || pascalCase(def.slug),
+    version: def.version,
+    category: def.category,
+    description: def.description || undefined,
+    mode: (meta?.mode as string) || undefined,
+    defaultRuntime: (meta?.defaultRuntime as string) || undefined,
+    models: modelPaths,
+    entries: entryPaths,
+    actions: actionPaths,
+    roles: (def.roles || []).map(r => r.name),
+  };
+}
+
+// =============================================================================
+// Code Generation
+// =============================================================================
+
+/**
+ * Generates an mm.config.ts source string from config data.
+ *
+ * For blueprints, emits defineBlueprint() with additional fields (mode, defaultRuntime).
+ * For other categories, emits defineWorkspace().
+ */
+export function generateMmConfig(config: MmConfigData): string {
+  const isBlueprint = config.category === 'blueprint';
+  const fnName = isBlueprint ? 'defineBlueprint' : 'defineWorkspace';
+  const label = isBlueprint ? 'Blueprint' : 'Workspace';
+
+  const lines: string[] = [
+    `/**`,
+    ` * MindMatrix ${label.toLowerCase()} configuration.`,
+    ` *`,
+    ` * Auto-generated from workflow definition "${config.slug}".`,
+    ` */`,
+    ``,
+    `import { ${fnName} } from '@mindmatrix/react';`,
+    ``,
+    `export default ${fnName}({`,
+    `  slug: '${esc(config.slug)}',`,
+    `  name: '${esc(config.name)}',`,
+    `  version: '${esc(config.version)}',`,
+    `  category: ${Array.isArray(config.category) ? `[${config.category.map(c => `'${esc(c)}'`).join(', ')}]` : `'${esc(config.category)}'`},`,
+  ];
+
+  if (config.description) {
+    lines.push(`  description: '${esc(config.description)}',`);
+  }
+
+  // Blueprint-specific fields
+  if (isBlueprint) {
+    if (config.mode) {
+      lines.push(`  mode: '${esc(config.mode)}',`);
+    }
+    if (config.defaultRuntime) {
+      lines.push(`  defaultRuntime: '${esc(config.defaultRuntime)}',`);
+    }
+  }
+
+  if (config.models.length > 0) {
+    lines.push(`  models: [`);
+    for (const m of config.models) {
+      lines.push(`    '${esc(m)}',`);
+    }
+    lines.push(`  ],`);
+  }
+
+  if (config.entries.length > 0) {
+    lines.push(`  entries: [`);
+    for (const e of config.entries) {
+      lines.push(`    '${esc(e)}',`);
+    }
+    lines.push(`  ],`);
+  }
+
+  if (config.actions.length > 0) {
+    lines.push(`  actions: [`);
+    for (const a of config.actions) {
+      lines.push(`    '${esc(a)}',`);
+    }
+    lines.push(`  ],`);
+  }
+
+  if (config.roles.length > 0) {
+    lines.push(`  roles: [${config.roles.map(r => `'${esc(r)}'`).join(', ')}],`);
+  }
+
+  lines.push(`});`);
+  lines.push(``);
+
+  return lines.join('\n');
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function esc(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+function pascalCase(slug: string): string {
+  return slug
+    .split(/[-_]/)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join('');
+}

package/src/decompiler/index.ts

@@ -0,0 +1,315 @@
+/**
+ * IR-to-TSX Decompiler — converts IRWorkflowDefinition back to .workflow.tsx source.
+ *
+ * This is the inverse of the Babel compiler (extractors + pure-form-emitter).
+ * Given an IR tree (from the database, visual editor, or AI agent), it produces
+ * valid .workflow.tsx source code that compiles back to an equivalent IR.
+ *
+ * Architecture (per Appendix H):
+ *   IRWorkflowDefinition
+ *     → Import collection
+ *     → Field declarations (useState)
+ *     → State effects (useOnEnter/useOnExit)
+ *     → Transition declarations (useTransition)
+ *     → JSX return tree (experience → atoms)
+ *     → Babel AST (t.program)
+ *     → @babel/generator
+ *     → .workflow.tsx source string
+ *
+ * Covers: fields, states (enter/exit/during), transitions (with conditions),
+ * experience tree (JSX + sx props + bindings), and all known action types.
+ */
+
+import * as t from '@babel/types';
+import generate from '@babel/generator';
+import type {
+  IRWorkflowDefinition,
+  IRExperienceNode,
+} from '@mindmatrix/player-core';
+import { buildJSXTree, buildSymbolTable } from './ast-builder';
+import type { SymbolTable } from './ast-builder';
+import {
+  emitFieldDeclarations,
+  emitStateEffects,
+  emitTransitionDeclarations,
+  emitRoleDeclarations,
+  emitQueryDeclarations,
+  emitChangeWatchers,
+  emitEventSubscriptions,
+  emitTransitionEffects,
+  emitLocalDefaultDeclarations,
+} from './state-emitter';
+
+// =============================================================================
+// Public Types
+// =============================================================================
+
+/**
+ * Import tracker: maps package specifier → set of named imports.
+ * Used across all emitter modules to collect imports as they're needed.
+ */
+export type ImportTracker = Map<string, Set<string>>;
+
+/**
+ * Decompiler input — an IR definition plus an optional experience tree.
+ *
+ * The experience tree may come from:
+ *   - ExtractedWorkflow.experience (compiler internal)
+ *   - Stored definition metadata
+ *   - Visual editor BlueprintEditorContext.tree
+ */
+export interface DecompilerInput extends IRWorkflowDefinition {
+  /** The experience tree to decompile into the JSX return. */
+  experience?: IRExperienceNode;
+  /** Child workflow definitions for multi-workflow blueprints (UBER-SCALE projects). */
+  childDefinitions?: IRWorkflowDefinition[];
+}
+
+export interface DecompileOptions {
+  /** Override the component function name. Defaults to displayName or pascalCase(slug). */
+  componentName?: string;
+  /** Include JSDoc workflow annotation. Default: true. */
+  includeAnnotation?: boolean;
+  /** Emit displayName comments for named nodes. Default: false. */
+  emitDisplayNames?: boolean;
+}
+
+export interface DecompileResult {
+  /** The generated .workflow.tsx source code. */
+  code: string;
+  /** List of package specifiers that were imported. */
+  imports: string[];
+  /** The component function name used. */
+  componentName: string;
+}
+
+// =============================================================================
+// Name Helpers
+// =============================================================================
+
+/**
+ * Converts a kebab-case or snake_case slug to PascalCase component name.
+ *   "invoice-approval" → "InvoiceApproval"
+ *   "my_workflow"      → "MyWorkflow"
+ */
+function pascalCase(slug: string): string {
+  return slug
+    .split(/[-_]/)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join('');
+}
+
+// =============================================================================
+// Import Statement Emission
+// =============================================================================
+
+/**
+ * Converts the import tracker into sorted Babel import declarations.
+ */
+function emitImportStatements(tracker: ImportTracker): t.ImportDeclaration[] {
+  const result: t.ImportDeclaration[] = [];
+
+  // Sort by package name for deterministic output
+  const sources = [...tracker.keys()].sort();
+
+  for (const source of sources) {
+    const names = [...tracker.get(source)!].sort();
+    const specifiers: (t.ImportSpecifier | t.ImportDefaultSpecifier)[] = [];
+    for (const name of names) {
+      if (name.startsWith('default as ')) {
+        // Default import: "default as varName" → import varName from "source"
+        const localName = name.slice('default as '.length);
+        specifiers.push(t.importDefaultSpecifier(t.identifier(localName)));
+      } else {
+        specifiers.push(t.importSpecifier(t.identifier(name), t.identifier(name)));
+      }
+    }
+    result.push(t.importDeclaration(specifiers, t.stringLiteral(source)));
+  }
+
+  return result;
+}
+
+// =============================================================================
+// JSDoc Annotation
+// =============================================================================
+
+/**
+ * Builds the JSDoc annotation comment text for the @workflow annotation.
+ *
+ * The comment is attached directly to the export declaration so the compiler
+ * can find it when re-parsing the generated source.
+ */
+function buildWorkflowAnnotation(def: DecompilerInput): string {
+  const parts = [
+    `@workflow slug="${def.slug}" version="${def.version}" category="${def.category}"`,
+  ];
+  if (def.description) {
+    parts.push(`@description ${def.description}`);
+  }
+
+  return `*\n * ${parts.join('\n * ')}\n `;
+}
+
+// =============================================================================
+// Main: decompile
+// =============================================================================
+
+/**
+ * Decompiles an IR definition into a .workflow.tsx source string.
+ *
+ * @param definition - The IR workflow definition to decompile.
+ * @param options - Optional configuration for the output.
+ * @returns The generated source code, imports list, and component name.
+ */
+export function decompile(
+  definition: DecompilerInput,
+  options?: DecompileOptions,
+): DecompileResult {
+  const imports: ImportTracker = new Map();
+  const includeAnnotation = options?.includeAnnotation ?? true;
+
+  // 1. Determine component name
+  const componentName =
+    options?.componentName ??
+    (definition.metadata?.displayName as string | undefined) ??
+    pascalCase(definition.slug);
+
+  // 2. Build symbol table for IR token resolution
+  const symbols: SymbolTable = buildSymbolTable(
+    definition.fields,
+    definition.metadata,
+    definition.transitions,
+    definition.experience,
+  );
+
+  // 3. Build component body
+  const componentBody: t.Statement[] = [];
+
+  // 4. Fields → useState() calls (sorted alphabetically for deterministic output)
+  const sortedFields = [...definition.fields].sort((a, b) => a.name.localeCompare(b.name));
+  const fieldStmts = emitFieldDeclarations(sortedFields, imports);
+  componentBody.push(...fieldStmts);
+
+  // 4b. localDefaults → additional useState() calls for section-scoped variables
+  if (definition.experience) {
+    const localDefaultStmts = emitLocalDefaultDeclarations(
+      definition.experience,
+      definition.fields,
+      imports,
+    );
+    componentBody.push(...localDefaultStmts);
+  }
+
+  // 5. Data sources → useQuery() / useMutation()
+  const queryStmts = emitQueryDeclarations(definition.metadata, imports);
+  componentBody.push(...queryStmts);
+
+  // 6. Roles → useRole() declarations
+  const roleStmts = emitRoleDeclarations(definition.metadata, imports);
+  componentBody.push(...roleStmts);
+
+  // 7. State effects → useOnEnter/useOnExit/useWhileIn (sorted for determinism)
+  const sortedStates = [...definition.states].sort((a, b) => a.name.localeCompare(b.name));
+  const effectStmts = emitStateEffects(sortedStates, imports);
+  componentBody.push(...effectStmts);
+
+  // 8. Field watchers → useOnChange()
+  const watcherStmts = emitChangeWatchers(definition.metadata, imports);
+  componentBody.push(...watcherStmts);
+
+  // 9. Event subscriptions → useOnEvent()
+  const eventStmts = emitEventSubscriptions(definition.on_event, imports);
+  componentBody.push(...eventStmts);
+
+  // 10. Transitions → useTransition() declarations (sorted for determinism)
+  const sortedTransitions = [...definition.transitions].sort((a, b) => a.name.localeCompare(b.name));
+  const transStmts = emitTransitionDeclarations(sortedTransitions, imports);
+  componentBody.push(...transStmts);
+
+  // 11. Transition effects → useOnTransition()
+  const effectHookStmts = emitTransitionEffects(definition.metadata, imports);
+  componentBody.push(...effectHookStmts);
+
+  // 12. Experience → JSX return statement
+  if (definition.experience) {
+    const jsxTree = buildJSXTree(definition.experience, imports, symbols);
+    componentBody.push(t.returnStatement(jsxTree));
+  } else {
+    // No experience tree → return null
+    componentBody.push(t.returnStatement(t.nullLiteral()));
+  }
+
+  // 7. Build the function declaration
+  const func = t.functionDeclaration(
+    t.identifier(componentName),
+    [],
+    t.blockStatement(componentBody),
+  );
+
+  // 8. Assemble the full program
+  const programBody: t.Statement[] = [];
+
+  // Import statements (collected from all emitters)
+  programBody.push(...emitImportStatements(imports));
+
+  // export default function ComponentName() { ... }
+  const exportDecl = t.exportDefaultDeclaration(func);
+
+  // Attach JSDoc annotation directly to the export declaration
+  if (includeAnnotation) {
+    t.addComment(exportDecl, 'leading', buildWorkflowAnnotation(definition), false);
+  }
+
+  programBody.push(exportDecl);
+
+  const program = t.program(programBody);
+  const file = t.file(program);
+
+  // 9. Generate source code
+  const { code } = generate(file, {
+    retainLines: false,
+    compact: false,
+    jsescOption: { minimal: true },
+  });
+
+  return {
+    code,
+    imports: [...imports.keys()],
+    componentName,
+  };
+}
+
+// =============================================================================
+// Re-exports
+// =============================================================================
+
+export { buildJSXTree, buildSymbolTable } from './ast-builder';
+export type { SymbolTable } from './ast-builder';
+export { emitSxProp } from './sx-emitter';
+export {
+  emitFieldDeclarations,
+  emitStateEffects,
+  emitTransitionDeclarations,
+  emitRoleDeclarations,
+  emitQueryDeclarations,
+  emitChangeWatchers,
+  emitEventSubscriptions,
+  emitTransitionEffects,
+  emitLocalDefaultDeclarations,
+} from './state-emitter';
+export { decompileProject, shouldDecompileAsProject } from './project';
+export type { ProjectFile, DecompileProjectResult, DecompileProjectOptions } from './project';
+
+// =============================================================================
+// Enhanced Decompiler Re-exports
+// =============================================================================
+
+export { determineSplitStrategy, tierLabel } from './split-strategy';
+export type { SplitTier, SplitDecision } from './split-strategy';
+export { extractConfigData, generateMmConfig } from './config-generator';
+export type { MmConfigData } from './config-generator';
+export { decompileProjectEnhanced } from './project-decompiler';
+export type { EnhancedProjectFile, EnhancedDecompileResult } from './project-decompiler';
+export { hydrateWorkspace, decompileToFileMap } from './workspace-hydrator';
+export type { FileMap, HydrationResult } from './workspace-hydrator';