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

package/src/route-extractor.ts

@@ -1,333 +0,0 @@
-/**
- * Route Extractor — parses app/ directory structure into a routing table.
- *
- * Supports Next.js-style file-based routing conventions:
- *   - app/page.tsx → route '/'
- *   - app/rider/home.tsx → route '/rider/home'
- *   - app/[id]/page.tsx → route '/:id'
- *   - app/layout.tsx → wrapping layout boundary
- *   - app/admin/layout.tsx → nested layout boundary
- *
- * Generates a router configuration that maps to IR states and transitions.
- */
-
-import type { IRWorkflowDefinition, IRStateDefinition, IRTransitionDefinition, IRFieldDefinition } from '@mindmatrix/player-core';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface RouteEntry {
-  /** URL path pattern (e.g., '/rider/home', '/chat/:channelId'). */
-  path: string;
-  /** IR state name (e.g., 'RIDER_HOME', 'CHAT_CHANNELID'). */
-  stateName: string;
-  /** Source file relative path. */
-  sourceFile: string;
-  /** Dynamic route parameters. */
-  params: string[];
-  /** Nearest layout boundary file. */
-  layoutBoundary?: string;
-  /** Route segment depth (0 = root). */
-  depth: number;
-}
-
-export interface LayoutEntry {
-  /** Relative path to layout file. */
-  sourceFile: string;
-  /** Directory this layout covers. */
-  directory: string;
-  /** Depth in the layout hierarchy. */
-  depth: number;
-}
-
-export interface RouteExtractionResult {
-  /** All extracted routes. */
-  routes: RouteEntry[];
-  /** All discovered layout boundaries. */
-  layouts: LayoutEntry[];
-  /** Generated router workflow IR. */
-  routerIR: IRWorkflowDefinition;
-  /** Route parameters discovered (for field generation). */
-  allParams: string[];
-}
-
-export interface RouteExtractorOptions {
-  /** Blueprint slug prefix for the router. */
-  slugPrefix?: string;
-  /** Root directory name (default: 'app'). */
-  rootDir?: string;
-  /** Page file naming convention (default: 'page.tsx'). */
-  pageFileName?: string;
-  /** Layout file naming convention (default: 'layout.tsx'). */
-  layoutFileName?: string;
-}
-
-// =============================================================================
-// Path Utilities
-// =============================================================================
-
-/**
- * Converts a file path to a URL pattern.
- * 'app/rider/home.tsx' → '/rider/home'
- * 'app/chat/[channelId]/page.tsx' → '/chat/:channelId'
- */
-function filePathToUrlPattern(filePath: string, rootDir: string): string {
-  let route = filePath;
-
-  // Remove root directory prefix
-  const rootPrefix = rootDir + '/';
-  if (route.startsWith(rootPrefix)) {
-    route = route.slice(rootPrefix.length);
-  }
-
-  // Remove file extension
-  route = route.replace(/\.(tsx?|jsx?)$/, '');
-
-  // Remove trailing /page or /index
-  route = route.replace(/\/(page|index)$/, '');
-
-  // Handle root page
-  if (route === 'page' || route === 'index' || route === '') {
-    return '/';
-  }
-
-  // Convert [param] to :param
-  route = route.replace(/\[([^\]]+)\]/g, ':$1');
-
-  // Ensure leading slash
-  return '/' + route;
-}
-
-/**
- * Converts a URL path to an IR state name.
- * '/rider/home' → 'RIDER_HOME'
- * '/' → 'HOME'
- * '/chat/:channelId' → 'CHAT_CHANNELID'
- */
-function urlToStateName(urlPath: string): string {
-  if (urlPath === '/') return 'HOME';
-
-  return urlPath
-    .split('/')
-    .filter(Boolean)
-    .map(segment => segment.replace(/^:/, ''))
-    .join('_')
-    .replace(/([a-z])([A-Z])/g, '$1_$2')
-    .replace(/-/g, '_')
-    .toUpperCase();
-}
-
-/**
- * Extracts dynamic parameters from a file path.
- * 'app/chat/[channelId]/[messageId]/page.tsx' → ['channelId', 'messageId']
- */
-function extractRouteParams(filePath: string): string[] {
-  const params: string[] = [];
-  const regex = /\[([^\]]+)\]/g;
-  let match;
-  while ((match = regex.exec(filePath)) !== null) {
-    params.push(match[1]);
-  }
-  return params;
-}
-
-/**
- * Calculates route depth from URL path.
- * '/' → 0, '/rider' → 1, '/rider/home' → 2
- */
-function routeDepth(urlPath: string): number {
-  if (urlPath === '/') return 0;
-  return urlPath.split('/').filter(Boolean).length;
-}
-
-// =============================================================================
-// File Classification
-// =============================================================================
-
-function isPageFile(filename: string, pageFileName: string): boolean {
-  // Match exact page file name or any .tsx/.ts in the app directory
-  if (filename.endsWith('/' + pageFileName)) return true;
-  // Also match direct component files like app/rider/home.tsx
-  return /\.(tsx|ts|jsx|js)$/.test(filename)
-    && !filename.endsWith('.test.ts')
-    && !filename.endsWith('.test.tsx')
-    && !filename.includes('layout');
-}
-
-function isLayoutFile(filename: string, layoutFileName: string): boolean {
-  return filename.endsWith('/' + layoutFileName) || filename.endsWith(layoutFileName);
-}
-
-// =============================================================================
-// Main API
-// =============================================================================
-
-/**
- * Extracts routes from a set of files in an app/ directory structure.
- *
- * @param files - Record of filename → source code (only app/ files needed)
- * @param options - Extraction options
- * @returns RouteExtractionResult with routes, layouts, and router IR
- */
-export function extractRoutes(
-  files: Record<string, string>,
-  options: RouteExtractorOptions = {},
-): RouteExtractionResult {
-  const rootDir = options.rootDir || 'app';
-  const pageFileName = options.pageFileName || 'page.tsx';
-  const layoutFileName = options.layoutFileName || 'layout.tsx';
-  const slugPrefix = options.slugPrefix || 'app';
-
-  // Discover layouts
-  const layouts: LayoutEntry[] = [];
-  for (const filename of Object.keys(files)) {
-    if (isLayoutFile(filename, layoutFileName)) {
-      const dir = filename.replace(/\/[^/]+$/, '');
-      layouts.push({
-        sourceFile: filename,
-        directory: dir,
-        depth: dir.split('/').filter(Boolean).length,
-      });
-    }
-  }
-  // Sort layouts by depth (shallowest first) for boundary lookup
-  layouts.sort((a, b) => a.depth - b.depth);
-
-  // Discover routes
-  const routes: RouteEntry[] = [];
-  const allParams = new Set<string>();
-
-  for (const filename of Object.keys(files)) {
-    // Skip layout files and non-app files
-    if (isLayoutFile(filename, layoutFileName)) continue;
-    if (!filename.startsWith(rootDir + '/') && !filename.startsWith(rootDir)) continue;
-    if (!isPageFile(filename, pageFileName)) continue;
-
-    const urlPath = filePathToUrlPattern(filename, rootDir);
-    const stateName = urlToStateName(urlPath);
-    const params = extractRouteParams(filename);
-    const depth = routeDepth(urlPath);
-
-    // Find nearest layout boundary
-    const fileDir = filename.replace(/\/[^/]+$/, '');
-    let layoutBoundary: string | undefined;
-    for (let i = layouts.length - 1; i >= 0; i--) {
-      if (fileDir.startsWith(layouts[i].directory)) {
-        layoutBoundary = layouts[i].sourceFile;
-        break;
-      }
-    }
-
-    for (const p of params) allParams.add(p);
-
-    routes.push({
-      path: urlPath,
-      stateName,
-      sourceFile: filename,
-      params,
-      layoutBoundary,
-      depth,
-    });
-  }
-
-  // Sort routes by path for deterministic output
-  routes.sort((a, b) => a.path.localeCompare(b.path));
-
-  // Generate router workflow IR
-  const routerIR = buildRouterIR(routes, layouts, Array.from(allParams), slugPrefix);
-
-  return {
-    routes,
-    layouts,
-    routerIR,
-    allParams: Array.from(allParams),
-  };
-}
-
-/**
- * Builds a router IRWorkflowDefinition from extracted routes.
- */
-function buildRouterIR(
-  routes: RouteEntry[],
-  layouts: LayoutEntry[],
-  allParams: string[],
-  slugPrefix: string,
-): IRWorkflowDefinition {
-  // Build states — one per route
-  const states: IRStateDefinition[] = routes.map(route => ({
-    name: route.stateName,
-    type: route.path === '/' ? 'START' as const : 'REGULAR' as const,
-    description: 'Route: ' + route.path,
-    on_enter: [],
-    during: [],
-    on_exit: [],
-  }));
-
-  // Ensure at least one START state
-  if (states.length > 0 && !states.some(s => s.type === 'START')) {
-    states[0].type = 'START';
-  }
-
-  // Build transitions — navigate from any state to any other state
-  const transitions: IRTransitionDefinition[] = [];
-  for (const from of routes) {
-    for (const to of routes) {
-      if (from.stateName === to.stateName) continue;
-      transitions.push({
-        name: 'nav_' + from.stateName.toLowerCase() + '_to_' + to.stateName.toLowerCase(),
-        from: [from.stateName],
-        to: to.stateName,
-        actions: [],
-        conditions: [],
-      });
-    }
-  }
-
-  // Build fields for route parameters
-  const fields: IRFieldDefinition[] = allParams.map(param => ({
-    name: param,
-    type: 'text' as const,
-    label: param.replace(/([A-Z])/g, ' $1').replace(/^./, c => c.toUpperCase()),
-    required: false,
-    default_value: '',
-  }));
-
-  // Add current_route field
-  fields.push({
-    name: 'current_route',
-    type: 'text',
-    label: 'Current Route',
-    required: false,
-    default_value: '/',
-  });
-
-  return {
-    slug: slugPrefix + '-router',
-    name: 'Router',
-    version: '1.0.0',
-    description: 'Auto-generated router from app/ directory structure',
-    category: 'router',
-    fields,
-    states,
-    transitions,
-    roles: [],
-    tags: [{ tag_name: 'auto-derived' }, { tag_name: 'router' }],
-    metadata: {
-      runtime: 'local',
-      routes: routes.map(r => ({
-        state: r.stateName,
-        path: r.path,
-        params: r.params,
-        layoutBoundary: r.layoutBoundary,
-        sourceFile: r.sourceFile,
-      })),
-      layoutBoundaries: layouts.map(l => l.sourceFile),
-      provenance: {
-        frontend: 'react-compiler',
-        source: 'route-extractor',
-        compiler_version: '2.0.0',
-      },
-    },
-  };
-}

package/src/testing/index.ts

@@ -1,32 +0,0 @@
-/**
- * Testing utilities — public API for @mindmatrix/react-compiler/testing.
- */
-
-// Compilation helpers
-export {
-  compileWorkflow,
-  compileModel,
-  compileServerAction,
-  compileRaw,
-  extractFields,
-  extractStates,
-  extractTransitions,
-  createMockBlueprintContext,
-  createMockWorkflowContext,
-} from './test-utils';
-export type {
-  CompileOptions,
-  MockBlueprintProviderProps,
-  MockWorkflowProviderProps,
-} from './test-utils';
-
-// Snapshot utilities
-export {
-  snapshotIR,
-  irToSnapshot,
-  installIRMatchers,
-} from './snapshot';
-export type {
-  IRSnapshot,
-  IRMatcher,
-} from './snapshot';

package/src/testing/snapshot.ts

@@ -1,252 +0,0 @@
-/**
- * IR Snapshot Utilities — snapshot and compare compiled IR for regression testing.
- *
- * snapshotIR() compiles a .workflow.tsx source and returns a stable, serializable
- * IR representation suitable for vitest's toMatchSnapshot() or the custom
- * toMatchIR() matcher.
- *
- * Usage:
- *   import { snapshotIR, installIRMatchers } from '@mindmatrix/react-compiler/testing';
- *
- *   // In vitest setup or test file:
- *   installIRMatchers();
- *
- *   it('counter IR is stable', () => {
- *     const snapshot = snapshotIR(`
- *       import { useState } from 'react';
- *       export function Counter() {
- *         const [count, setCount] = useState(0);
- *         return <div>{count}</div>;
- *       }
- *     `);
- *     expect(snapshot).toMatchSnapshot();
- *   });
- *
- *   it('IR matches expected shape', () => {
- *     const ir = compileWorkflow(`...`);
- *     expect(ir).toMatchIR({
- *       fields: [{ name: 'count', type: 'number' }],
- *       states: expect.arrayContaining([expect.objectContaining({ name: 'draft' })]),
- *     });
- *   });
- */
-
-import { compileWorkflow, compileModel, type CompileOptions } from './test-utils';
-import type { IRWorkflowDefinition } from '@mindmatrix/player-core';
-
-// =============================================================================
-// Snapshot
-// =============================================================================
-
-export interface IRSnapshot {
-  /** Workflow slug. */
-  slug: string;
-  /** Version. */
-  version: string;
-  /** Category. */
-  category: string;
-  /** Field names and types. */
-  fields: Array<{ name: string; type: string; required?: boolean }>;
-  /** State names and types. */
-  states: Array<{ name: string; type: string; enterActions: number; exitActions: number }>;
-  /** Transition names with from→to. */
-  transitions: Array<{ name: string; from: string | string[]; to: string; conditions: number }>;
-  /** Whether experience (JSX) is present. */
-  hasExperience: boolean;
-  /** Extension tags present (cedar, cron, etc.). */
-  extensionTags: string[];
-  /** Number of data sources. */
-  dataSourceCount: number;
-  /** Number of mutation targets. */
-  mutationTargetCount: number;
-  /** Error count. */
-  errorCount: number;
-}
-
-/**
- * Compile workflow source and extract a stable snapshot of its IR structure.
- *
- * The snapshot omits volatile data (action IDs, generated code) and keeps only
- * the structural shape — making it safe for snapshot testing across refactors.
- */
-export function snapshotIR(code: string, options?: CompileOptions): IRSnapshot {
-  const ir = options?.filename?.includes('models/')
-    ? compileModel(code, options)
-    : compileWorkflow(code, options);
-
-  return irToSnapshot(ir);
-}
-
-/**
- * Convert an already-compiled IR to a snapshot.
- */
-export function irToSnapshot(ir: IRWorkflowDefinition): IRSnapshot {
-  const meta = (ir.metadata ?? {}) as Record<string, unknown>;
-
-  return {
-    slug: ir.slug ?? '',
-    version: ir.version ?? '',
-    category: Array.isArray(ir.category) ? ir.category[0] : (ir.category ?? 'workflow'),
-    fields: ir.fields.map((f) => ({
-      name: f.name,
-      type: f.type,
-      ...(f.required === false ? { required: false } : {}),
-    })),
-    states: ir.states.map((s) => ({
-      name: s.name,
-      type: s.type,
-      enterActions: s.on_enter?.length ?? 0,
-      exitActions: s.on_exit?.length ?? 0,
-    })),
-    transitions: ir.transitions.map((t) => ({
-      name: t.name,
-      from: t.from,
-      to: t.to,
-      conditions: t.conditions?.length ?? 0,
-    })),
-    hasExperience: !!meta.experience || !!(ir as any).experience,
-    extensionTags: ir.extensions ? Object.keys(ir.extensions) : [],
-    dataSourceCount: Array.isArray(meta.dataSources) ? meta.dataSources.length : 0,
-    mutationTargetCount: Array.isArray(meta.mutationTargets) ? meta.mutationTargets.length : 0,
-    errorCount: Array.isArray(meta.errors) ? meta.errors.length : 0,
-  };
-}
-
-// =============================================================================
-// Custom Matcher: toMatchIR
-// =============================================================================
-
-/**
- * Partial IR shape for matching.
- * Every field is optional — only specified fields are checked.
- */
-export interface IRMatcher {
-  slug?: string;
-  version?: string;
-  category?: string;
-  fields?: Array<Record<string, unknown>>;
-  states?: Array<Record<string, unknown>>;
-  transitions?: Array<Record<string, unknown>>;
-  description?: string;
-  [key: string]: unknown;
-}
-
-/**
- * Install the toMatchIR() custom matcher into vitest's expect.
- *
- * Call this once in your test setup file or at the top of a test file:
- *   import { installIRMatchers } from '@mindmatrix/react-compiler/testing';
- *   installIRMatchers();
- */
-export function installIRMatchers(): void {
-  // Dynamic import of expect to avoid requiring vitest at module parse time
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { expect } = require('vitest');
-
-    expect.extend({
-      toMatchIR(received: IRWorkflowDefinition, expected: IRMatcher) {
-        const failures: string[] = [];
-
-        if (expected.slug !== undefined && received.slug !== expected.slug) {
-          failures.push(`slug: expected "${expected.slug}", got "${received.slug}"`);
-        }
-        if (expected.version !== undefined && received.version !== expected.version) {
-          failures.push(`version: expected "${expected.version}", got "${received.version}"`);
-        }
-        if (expected.category !== undefined && received.category !== expected.category) {
-          failures.push(`category: expected "${expected.category}", got "${received.category}"`);
-        }
-        if (expected.description !== undefined && received.description !== expected.description) {
-          failures.push(`description: expected "${expected.description}", got "${received.description}"`);
-        }
-
-        // Field matching — check each expected field exists with matching properties
-        if (expected.fields !== undefined) {
-          const expectedFields = expected.fields as Array<Record<string, unknown>>;
-          for (const exp of expectedFields) {
-            const match = received.fields.find((f) => f.name === exp.name);
-            if (!match) {
-              failures.push(`fields: expected field "${exp.name}" not found`);
-            } else {
-              const matchRec = match as unknown as Record<string, unknown>;
-              for (const [key, val] of Object.entries(exp)) {
-                if (matchRec[key] !== val) {
-                  failures.push(`fields.${exp.name}.${key}: expected ${JSON.stringify(val)}, got ${JSON.stringify(matchRec[key])}`);
-                }
-              }
-            }
-          }
-        }
-
-        // State matching
-        if (expected.states !== undefined && Array.isArray(expected.states)) {
-          const expectedStates = expected.states as Array<Record<string, unknown>>;
-          for (const exp of expectedStates) {
-            const match = received.states.find((s) => s.name === exp.name);
-            if (!match) {
-              failures.push(`states: expected state "${exp.name}" not found`);
-            } else {
-              const matchRec = match as unknown as Record<string, unknown>;
-              for (const [key, val] of Object.entries(exp)) {
-                if (key === 'on_enter' || key === 'on_exit' || key === 'during') {
-                  const arr = matchRec[key] as unknown[] | undefined;
-                  if (typeof val === 'number' && (arr?.length ?? 0) !== val) {
-                    failures.push(`states.${exp.name}.${key}: expected length ${val}, got ${arr?.length ?? 0}`);
-                  }
-                } else if (matchRec[key] !== val) {
-                  failures.push(`states.${exp.name}.${key}: expected ${JSON.stringify(val)}, got ${JSON.stringify(matchRec[key])}`);
-                }
-              }
-            }
-          }
-        }
-
-        // Transition matching
-        if (expected.transitions !== undefined && Array.isArray(expected.transitions)) {
-          const expectedTransitions = expected.transitions as Array<Record<string, unknown>>;
-          for (const exp of expectedTransitions) {
-            const match = received.transitions.find((t) => t.name === exp.name);
-            if (!match) {
-              failures.push(`transitions: expected transition "${exp.name}" not found`);
-            } else {
-              if (exp.from !== undefined) {
-                const fromMatch = JSON.stringify(match.from) === JSON.stringify(exp.from);
-                if (!fromMatch) {
-                  failures.push(`transitions.${exp.name}.from: expected ${JSON.stringify(exp.from)}, got ${JSON.stringify(match.from)}`);
-                }
-              }
-              if (exp.to !== undefined && match.to !== exp.to) {
-                failures.push(`transitions.${exp.name}.to: expected "${exp.to}", got "${match.to}"`);
-              }
-            }
-          }
-        }
-
-        const pass = failures.length === 0;
-        return {
-          pass,
-          message: () =>
-            pass
-              ? `expected IR not to match, but it did`
-              : `IR mismatch:\n${failures.map((f) => `  - ${f}`).join('\n')}`,
-        };
-      },
-    });
-  } catch {
-    // vitest not available — skip matcher installation
-  }
-}
-
-// =============================================================================
-// Type augmentation for vitest
-// =============================================================================
-
-// Note: To use the toMatchIR() custom matcher with full type support,
-// add the following to your test setup or a global .d.ts file:
-//
-//   import type { IRMatcher } from '@mindmatrix/react-compiler/testing';
-//   declare module 'vitest' {
-//     interface Assertion<T> { toMatchIR(expected: IRMatcher): void; }
-//     interface AsymmetricMatchersContaining { toMatchIR(expected: IRMatcher): void; }
-//   }