@mmapp/react-compiler 0.1.0-alpha.1

package/src/index.ts

@@ -0,0 +1,99 @@
+/**
+ * Main entry point — @mindmatrix/react-compiler
+ *
+ * Exports all public APIs from extractors, emitters, and types.
+ */
+
+export * from './types';
+export { extractStates } from './babel/extractors/state-extractor';
+export { extractEffects } from './babel/extractors/effect-extractor';
+export { extractTransitions } from './babel/extractors/transition-extractor';
+export { extractEvents } from './babel/extractors/event-extractor';
+export { extractComponents } from './babel/extractors/component-extractor';
+export { emitIR, emitPureForm, emitCanonical, emitCompiledOutput, compilerStateToWorkflow } from './babel/emitters/pure-form-emitter';
+export { transformToFrontend } from './babel/emitters/experience-transform';
+export type { FrontendExperienceNode, FrontendDataSource } from './babel/emitters/experience-transform';
+export { decompileToTSX, normalizeDecompilerInput } from './babel/emitters/ir-to-tsx-emitter';
+export { extractComputed } from './babel/extractors/computed-extractor';
+export type { ComputedFieldExtraction } from './babel/extractors/computed-extractor';
+export { createVisitor } from './babel/visitor';
+
+// Re-export Babel plugin as default
+export { default as babelPlugin } from './babel';
+
+// Decompiler (IR → .workflow.tsx)
+export { decompile, decompileProject, shouldDecompileAsProject } from './decompiler';
+export type { DecompilerInput, DecompileOptions, DecompileResult, ProjectFile, DecompileProjectResult, DecompileProjectOptions } from './decompiler';
+
+// Round-trip validator (IR → TSX → IR)
+export { validateRoundTrip, validateSourceRoundTrip, compileSource } from './RoundTripValidator';
+export type { RoundTripResult, RoundTripDiff } from './RoundTripValidator';
+
+// Dev server (programmatic API)
+export { createDevServer } from './dev-server';
+export type { DevServerOptions, DevServerInstance } from './dev-server';
+
+// CLI build/deploy (programmatic API)
+export { build } from './cli/build';
+export type { BuildOptions, BuildResult } from './cli/build';
+export { deploy } from './cli/deploy';
+export type { DeployOptions, DeployResult } from './cli/deploy';
+
+// Envelope builder (content-addressed deployment bundles)
+export { buildEnvelope } from './envelope';
+export type { EnvelopeManifest, EnvelopeFile, BuildEnvelopeOptions, BuildEnvelopeResult } from './envelope';
+
+// Source envelope (lower-level API)
+export { createSourceEnvelope, computeEnvelopeId, envelopesEqual, diffEnvelopes } from './envelope/source-envelope';
+export type { SourceEnvelope, SourceBinding, EnvelopeMetadata } from './envelope/source-envelope';
+export { generateFsTree, detectFileRole, filterByRole, diffFsTrees } from './envelope/fs-tree';
+export type { FsTree, FsTreeEntry, FileRole } from './envelope/fs-tree';
+
+// Project compiler (multi-file → composed blueprint with child definitions)
+export { compileProject, IncrementalProjectCompiler } from './project-compiler';
+export type {
+  ProjectCompilerOptions,
+  ProjectCompilationResult,
+  ProjectCompilationError,
+  RouteTableEntry,
+  ServerActionEntry,
+  ImportLink,
+} from './project-compiler';
+
+// Phase 2: Model compiler
+export { compileModel, compileModels } from './model-compiler';
+export type { ModelCompilationResult, ModelCompilerOptions } from './model-compiler';
+
+// Phase 2: Route extractor
+export { extractRoutes } from './route-extractor';
+export type {
+  RouteEntry,
+  LayoutEntry,
+  RouteExtractionResult,
+  RouteExtractorOptions,
+} from './route-extractor';
+
+// Phase 2: Action compiler
+export { compileActions, resolveActionReferences } from './action-compiler';
+export type {
+  ServerActionRegistration,
+  ActionCompilationResult,
+  ActionCompilerOptions,
+} from './action-compiler';
+
+// Phase 2: Incremental compiler utilities
+export {
+  hashContent,
+  extractImports,
+  resolveImport,
+  buildDependencyGraph,
+  computeTransitiveDirtySet,
+  topologicalSort,
+  IncrementalCache,
+} from './incremental-compiler';
+export type {
+  FileHash,
+  IncrementalStats,
+  DependencyEdge,
+  DirtyFileSet,
+} from './incremental-compiler';

package/src/model-compiler.ts

@@ -0,0 +1,277 @@
+/**
+ * Model Compiler — standalone module for compiling model files into IR.
+ *
+ * Extracts TypeScript interfaces from models/*.ts files and produces
+ * category='data' IRWorkflowDefinition objects. Handles:
+ *   - Interface properties → IRFieldDefinition[]
+ *   - Exported `transitions` arrays/objects → IRTransitionDefinition[]
+ *   - Exported `fieldOptions` → field enrichment (validation, ACL, computed)
+ *   - Exported `states` → explicit state declarations
+ *   - JSDoc @workflow annotations for slug, version, category
+ *
+ * This module wraps the low-level Babel model-extractor with a clean
+ * file-level API for the ProjectCompiler to consume.
+ */
+
+import { transformSync } from '@babel/core';
+import type {
+  IRWorkflowDefinition,
+} from '@mindmatrix/player-core';
+import babelPlugin from './babel';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ModelCompilationResult {
+  /** The compiled IR with category='data'. */
+  ir: IRWorkflowDefinition;
+  /** Interface name extracted from the model file. */
+  interfaceName: string;
+  /** Field names extracted from the interface. */
+  fieldNames: string[];
+  /** Transition names extracted from the model. */
+  transitionNames: string[];
+  /** State names (derived from transitions + explicit declarations). */
+  stateNames: string[];
+  /** Whether fieldOptions were present and applied. */
+  hasFieldOptions: boolean;
+  /** Raw field options map (for cross-file enrichment). */
+  fieldOptions: Record<string, Record<string, unknown>>;
+}
+
+export interface ModelCompilerOptions {
+  /** Compilation mode. Default: 'infer'. */
+  mode?: 'strict' | 'infer';
+  /** Override the slug (otherwise derived from interface name or @workflow). */
+  slugOverride?: string;
+  /** Override the category (defaults to 'data'). */
+  categoryOverride?: string;
+}
+
+// =============================================================================
+// Interface Extraction (regex-based fast path)
+// =============================================================================
+
+/**
+ * Extracts the primary exported interface name from source code.
+ * Uses regex for speed — the full Babel parse handles the real extraction.
+ */
+function extractInterfaceName(source: string): string {
+  const match = source.match(/export\s+interface\s+(\w+)/);
+  return match ? match[1] : 'Unknown';
+}
+
+/**
+ * Extracts @workflow JSDoc annotation metadata from source.
+ */
+function extractWorkflowAnnotation(source: string): {
+  slug?: string;
+  version?: string;
+  category?: string;
+  description?: string;
+} {
+  const result: Record<string, string> = {};
+  const workflowMatch = source.match(/@workflow\s+(.+)/);
+  if (workflowMatch) {
+    const attrs = workflowMatch[1];
+    const slugM = attrs.match(/slug="([^"]+)"/);
+    if (slugM) result.slug = slugM[1];
+    const versionM = attrs.match(/version="([^"]+)"/);
+    if (versionM) result.version = versionM[1];
+    const categoryM = attrs.match(/category="([^"]+)"/);
+    if (categoryM) result.category = categoryM[1];
+  }
+  const descMatch = source.match(/@description\s+(.+)/);
+  if (descMatch) result.description = descMatch[1].trim();
+  return result;
+}
+
+/**
+ * Extracts fieldOptions from source via regex (for metadata before full compile).
+ */
+function extractFieldOptionsRaw(source: string): Record<string, Record<string, unknown>> {
+  const result: Record<string, Record<string, unknown>> = {};
+  const match = source.match(/export\s+const\s+fieldOptions\s*=\s*\{([\s\S]*?)\};/);
+  if (!match) return result;
+
+  const body = match[1];
+  const fieldRegex = /(\w+)\s*:\s*\{([^}]*)\}/g;
+  let fieldMatch;
+  while ((fieldMatch = fieldRegex.exec(body)) !== null) {
+    const fieldName = fieldMatch[1];
+    const optionsBody = fieldMatch[2];
+    const opts: Record<string, unknown> = {};
+
+    const kvRegex = /(\w+)\s*:\s*(?:'([^']*)'|"([^"]*)"|\[([^\]]*)\]|(\d+(?:\.\d+)?)|(\w+))/g;
+    let kvMatch;
+    while ((kvMatch = kvRegex.exec(optionsBody)) !== null) {
+      const key = kvMatch[1];
+      const strVal = kvMatch[2] ?? kvMatch[3];
+      const arrVal = kvMatch[4];
+      const numVal = kvMatch[5];
+      const identVal = kvMatch[6];
+
+      if (strVal !== undefined) {
+        opts[key] = strVal;
+      } else if (arrVal !== undefined) {
+        opts[key] = arrVal.split(',').map(s => s.trim().replace(/['"]/g, '')).filter(Boolean);
+      } else if (numVal !== undefined) {
+        opts[key] = Number(numVal);
+      } else if (identVal !== undefined) {
+        if (identVal === 'true') opts[key] = true;
+        else if (identVal === 'false') opts[key] = false;
+        else opts[key] = identVal;
+      }
+    }
+
+    result[fieldName] = opts;
+  }
+
+  return result;
+}
+
+// =============================================================================
+// Main API
+// =============================================================================
+
+/**
+ * Compiles a single model file (models/*.ts) into an IRWorkflowDefinition
+ * with category='data'.
+ */
+export function compileModel(
+  filename: string,
+  source: string,
+  options: ModelCompilerOptions = {},
+): ModelCompilationResult {
+  const mode = options.mode || 'infer';
+  const interfaceName = extractInterfaceName(source);
+  const annotation = extractWorkflowAnnotation(source);
+  const rawFieldOptions = extractFieldOptionsRaw(source);
+
+  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 =
+    (babelResult as any)?.metadata?.mindmatrixIR ?? createEmptyModelIR(interfaceName);
+
+  // Enforce category
+  ir.category = options.categoryOverride || annotation.category || 'data';
+
+  // Apply slug override
+  if (options.slugOverride) {
+    ir.slug = options.slugOverride;
+  }
+
+  // Ensure states have at least a draft/idle state
+  if (ir.states.length === 0) {
+    ir.states.push({
+      name: 'draft',
+      type: 'START',
+      on_enter: [],
+      during: [],
+      on_exit: [],
+    });
+  }
+
+  // Ensure START state exists
+  const hasStart = ir.states.some(s => s.type === 'START');
+  if (!hasStart && ir.states.length > 0) {
+    ir.states[0].type = 'START';
+  }
+
+  // Add data provenance metadata
+  if (!ir.metadata) ir.metadata = {};
+  const meta = ir.metadata as Record<string, unknown>;
+  meta.sourceInterface = interfaceName;
+  meta.fieldOptions = rawFieldOptions;
+  meta.provenance = {
+    frontend: 'react-compiler',
+    source: 'model',
+    compiler_version: '2.0.0',
+  };
+
+  return {
+    ir,
+    interfaceName,
+    fieldNames: ir.fields.map(f => f.name),
+    transitionNames: ir.transitions.map(t => t.name),
+    stateNames: ir.states.map(s => s.name),
+    hasFieldOptions: Object.keys(rawFieldOptions).length > 0,
+    fieldOptions: rawFieldOptions,
+  };
+}
+
+/**
+ * Compiles multiple model files and returns all results keyed by filename.
+ */
+export function compileModels(
+  files: Record<string, string>,
+  options: ModelCompilerOptions = {},
+): Map<string, ModelCompilationResult> {
+  const results = new Map<string, ModelCompilationResult>();
+
+  for (const [filename, source] of Object.entries(files)) {
+    try {
+      const compiled = compileModel(filename, source, options);
+      results.set(filename, compiled);
+    } catch (_err) {
+      const iface = extractInterfaceName(source);
+      results.set(filename, {
+        ir: createEmptyModelIR(iface),
+        interfaceName: iface,
+        fieldNames: [],
+        transitionNames: [],
+        stateNames: ['draft'],
+        hasFieldOptions: false,
+        fieldOptions: {},
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Creates an empty model IR for error cases.
+ */
+function createEmptyModelIR(interfaceName: string): IRWorkflowDefinition {
+  const slug = interfaceName
+    .replace(/([A-Z])/g, '-$1')
+    .toLowerCase()
+    .replace(/^-/, '');
+
+  return {
+    slug,
+    name: interfaceName,
+    version: '1.0.0',
+    description: 'Data model: ' + interfaceName,
+    category: 'data',
+    fields: [],
+    states: [{
+      name: 'draft',
+      type: 'START',
+      on_enter: [],
+      during: [],
+      on_exit: [],
+    }],
+    transitions: [],
+    roles: [],
+    tags: [{ tag_name: 'data' }, { tag_name: 'model' }],
+    metadata: {
+      sourceInterface: interfaceName,
+      provenance: {
+        frontend: 'react-compiler',
+        source: 'model',
+        compiler_version: '2.0.0',
+      },
+    },
+  };
+}