@mmapp/react-compiler 0.1.0-alpha.1

package/src/codemod/import-manager.ts

@@ -0,0 +1,171 @@
+/**
+ * Import manager — tracks atom usage and rewrites imports.
+ */
+
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { ATOM_IMPORT_SOURCE, ALL_ATOM_NAMES } from './rules';
+
+export interface ImportTracker {
+  /** Mark an atom as used (forward: add to imports) */
+  addAtom(name: string): void;
+  /** Mark an atom as removed (reverse: remove from imports) */
+  removeAtom(name: string): void;
+  /** Get the set of atoms that need importing */
+  getUsedAtoms(): Set<string>;
+  /** Get the set of atoms that were removed */
+  getRemovedAtoms(): Set<string>;
+}
+
+export function createImportTracker(): ImportTracker {
+  const used = new Set<string>();
+  const removed = new Set<string>();
+
+  return {
+    addAtom(name: string) {
+      used.add(name);
+      removed.delete(name);
+    },
+    removeAtom(name: string) {
+      removed.add(name);
+    },
+    getUsedAtoms() {
+      return used;
+    },
+    getRemovedAtoms() {
+      return removed;
+    },
+  };
+}
+
+/**
+ * Rewrite imports after forward transform.
+ *
+ * - Adds `import { Stack, Row, ... } from '@mindmatrix/react/atoms'`
+ * - Preserves all other imports
+ */
+export function rewriteImportsForward(
+  programPath: NodePath<t.Program>,
+  tracker: ImportTracker,
+): void {
+  const usedAtoms = tracker.getUsedAtoms();
+  if (usedAtoms.size === 0) return;
+
+  // Check if there's already an atom import
+  let existingImport: NodePath<t.ImportDeclaration> | null = null;
+
+  programPath.traverse({
+    ImportDeclaration(path: NodePath<t.ImportDeclaration>) {
+      if (path.node.source.value === ATOM_IMPORT_SOURCE) {
+        existingImport = path;
+      }
+    },
+  });
+
+  if (existingImport) {
+    // Merge new atoms into existing import
+    const existing = new Set(
+      (existingImport as NodePath<t.ImportDeclaration>).node.specifiers
+        .filter((s): s is t.ImportSpecifier => s.type === 'ImportSpecifier')
+        .map(s => (s.imported as t.Identifier).name),
+    );
+
+    for (const atom of usedAtoms) {
+      if (!existing.has(atom)) {
+        (existingImport as NodePath<t.ImportDeclaration>).node.specifiers.push(
+          t.importSpecifier(t.identifier(atom), t.identifier(atom)),
+        );
+      }
+    }
+  } else {
+    // Create new import declaration
+    const specifiers = Array.from(usedAtoms)
+      .sort()
+      .map(name => t.importSpecifier(t.identifier(name), t.identifier(name)));
+
+    const importDecl = t.importDeclaration(
+      specifiers,
+      t.stringLiteral(ATOM_IMPORT_SOURCE),
+    );
+
+    // Insert after existing imports
+    const lastImport = programPath
+      .get('body')
+      .filter((p): p is NodePath<t.ImportDeclaration> => p.isImportDeclaration())
+      .pop();
+
+    if (lastImport) {
+      lastImport.insertAfter(importDecl);
+    } else {
+      (programPath.get('body')[0] as NodePath).insertBefore(importDecl);
+    }
+  }
+}
+
+/**
+ * Rewrite imports after reverse transform.
+ *
+ * - Removes unused atoms from `@mindmatrix/react/atoms` import
+ * - Removes the import entirely if empty
+ * - Ensures `import React from 'react'` exists
+ */
+export function rewriteImportsReverse(
+  programPath: NodePath<t.Program>,
+  tracker: ImportTracker,
+): void {
+  const removed = tracker.getRemovedAtoms();
+  if (removed.size === 0) return;
+
+  programPath.traverse({
+    ImportDeclaration(path: NodePath<t.ImportDeclaration>) {
+      if (path.node.source.value !== ATOM_IMPORT_SOURCE) return;
+
+      // Remove specifiers for removed atoms
+      path.node.specifiers = path.node.specifiers.filter(spec => {
+        if (spec.type !== 'ImportSpecifier') return true;
+        const name = (spec.imported as t.Identifier).name;
+        return !removed.has(name);
+      });
+
+      // If no specifiers left, remove the entire import
+      if (path.node.specifiers.length === 0) {
+        path.remove();
+      }
+    },
+  });
+
+  // Ensure React import exists
+  let hasReactImport = false;
+  programPath.traverse({
+    ImportDeclaration(path: NodePath<t.ImportDeclaration>) {
+      if (path.node.source.value === 'react') {
+        hasReactImport = true;
+      }
+    },
+  });
+
+  if (!hasReactImport) {
+    const reactImport = t.importDeclaration(
+      [t.importDefaultSpecifier(t.identifier('React'))],
+      t.stringLiteral('react'),
+    );
+    (programPath.get('body')[0] as NodePath).insertBefore(reactImport);
+  }
+}
+
+/**
+ * Collect all atoms currently referenced in JSX (for dead-import cleanup).
+ */
+export function collectUsedAtoms(programPath: NodePath<t.Program>): Set<string> {
+  const used = new Set<string>();
+
+  programPath.traverse({
+    JSXIdentifier(path: NodePath<t.JSXIdentifier>) {
+      if (ALL_ATOM_NAMES.has(path.node.name)) {
+        used.add(path.node.name);
+      }
+    },
+  });
+
+  return used;
+}

package/src/codemod/index.ts

@@ -0,0 +1,120 @@
+/**
+ * Bidirectional React ↔ Workflow Atom Codemod
+ *
+ * Babel plugin entry point. Dispatches by `direction` option.
+ *
+ * Usage as Babel plugin:
+ *   plugins: [['@mindmatrix/react-compiler/codemod', { direction: 'forward' }]]
+ *
+ * Usage programmatic:
+ *   import { transform } from '@mindmatrix/react-compiler/codemod';
+ *   const result = transform(source, { direction: 'forward' });
+ */
+
+import { transformSync, type TransformOptions } from '@babel/core';
+import type { PluginObj } from '@babel/core';
+// @ts-ignore — no types available for helper-plugin-utils
+import { declare } from '@babel/helper-plugin-utils';
+import { createForwardVisitor } from './forward';
+import { createReverseVisitor } from './reverse';
+import { createStateVisitor, type StateMode } from './state-transform';
+import {
+  createImportTracker,
+  rewriteImportsForward,
+  rewriteImportsReverse,
+} from './import-manager';
+
+export interface CodemodOptions {
+  /** Transform direction */
+  direction: 'forward' | 'reverse';
+  /** Add/strip @mm-original annotations */
+  annotate?: boolean;
+  /** State transform mode (default: 'preserve') */
+  stateMode?: StateMode;
+}
+
+/**
+ * Babel plugin — use via .babelrc or programmatic config.
+ */
+export const codemodPlugin = declare(
+  (api: any, options: CodemodOptions): PluginObj => {
+    api.assertVersion(7);
+
+    const direction = options.direction || 'forward';
+    const stateMode = options.stateMode || 'preserve';
+
+    return {
+      name: 'mm-codemod',
+      visitor: {
+        Program: {
+          enter(programPath) {
+            const imports = createImportTracker();
+            const stateVisitor = createStateVisitor(stateMode);
+
+            if (direction === 'forward') {
+              const forwardVisitor = createForwardVisitor(imports, {
+                annotate: options.annotate ?? true,
+                stateMode,
+              });
+
+              // Apply state transforms first
+              programPath.traverse(stateVisitor);
+              // Then apply element + control flow transforms
+              programPath.traverse(forwardVisitor);
+              // Finally rewrite imports
+              rewriteImportsForward(programPath, imports);
+            } else {
+              const reverseVisitor = createReverseVisitor(imports, {
+                stripAnnotations: !options.annotate,
+              });
+
+              programPath.traverse(reverseVisitor);
+              rewriteImportsReverse(programPath, imports);
+            }
+          },
+        },
+      },
+    };
+  },
+);
+
+export default codemodPlugin;
+
+/**
+ * Programmatic transform API.
+ *
+ * @param source - Source code string
+ * @param options - Codemod options
+ * @returns Transformed source code
+ */
+export function transform(
+  source: string,
+  options: CodemodOptions,
+): { code: string; map: any } {
+  const babelOptions: TransformOptions = {
+    filename: 'file.tsx',
+    plugins: [
+      ['@babel/plugin-syntax-typescript', { isTSX: true }],
+      [codemodPlugin, options],
+    ],
+    // Preserve formatting as much as possible
+    retainLines: true,
+    compact: false,
+    sourceMaps: true,
+  };
+
+  const result = transformSync(source, babelOptions);
+
+  if (!result || !result.code) {
+    throw new Error('Codemod transform produced no output');
+  }
+
+  return { code: result.code, map: result.map };
+}
+
+// Re-export types and utilities for testing
+export { createImportTracker } from './import-manager';
+export { classifyElement, reverseClassifyAtom, extractStaticClasses } from './classify';
+export type { ClassifyResult, ReverseClassifyResult } from './classify';
+export type { MappingRule, ReverseRule } from './rules';
+export { FORWARD_RULES, REVERSE_RULES, ATOM_IMPORT_SOURCE } from './rules';

package/src/codemod/reverse.ts

@@ -0,0 +1,197 @@
+/**
+ * Reverse transform: Workflow Atoms → Raw React
+ *
+ * Babel visitor that:
+ * 1. Renames atoms to HTML elements (Stack→div, Row→div, Text→span, etc.)
+ * 2. Transforms control flow (<Show> → &&, <Each> → .map())
+ * 3. Injects implicit className classes (flex, flex-col)
+ * 4. Reads @mm-original annotations for precise restoration
+ * 5. Updates imports
+ */
+
+import type { NodePath, Visitor } from '@babel/traverse';
+import * as t from '@babel/types';
+import { reverseClassifyAtom, addClassesToString } from './classify';
+import { matchShowElement, matchEachElement, showToConditional, eachToMap } from './control-flow';
+import { readAnnotationComment } from './annotation';
+import type { ImportTracker } from './import-manager';
+
+export interface ReverseOptions {
+  /** Strip @mm-original annotations from output */
+  stripAnnotations?: boolean;
+}
+
+/**
+ * Create the reverse visitor (Atoms → Raw React).
+ */
+export function createReverseVisitor(
+  imports: ImportTracker,
+  _options: ReverseOptions = {},
+): Visitor {
+  return {
+    JSXElement: {
+      // Use exit so children are processed first (bottom-up)
+      exit(path: NodePath<t.JSXElement>) {
+        const opening = path.node.openingElement;
+        const tag = opening.name;
+
+        if (tag.type !== 'JSXIdentifier') return;
+        const atomName = tag.name;
+
+        // Handle <Show> → {condition && children}
+        const showMatch = matchShowElement(path.node);
+        if (showMatch) {
+          const replacement = showToConditional(showMatch.condition, showMatch.children);
+          imports.removeAtom('Show');
+          path.replaceWith(replacement);
+          return;
+        }
+
+        // Handle <Each> → {items.map(callback)}
+        const eachMatch = matchEachElement(path.node);
+        if (eachMatch) {
+          const replacement = eachToMap(
+            eachMatch.items,
+            eachMatch.paramName,
+            eachMatch.keyExpression,
+            eachMatch.children,
+          );
+          imports.removeAtom('Each');
+          path.replaceWith(replacement);
+          return;
+        }
+
+        // Check annotation for precise restoration
+        const annotation = readAnnotationComment(path.node);
+
+        // Build props map for reverse classification
+        const propsMap = new Map<string, t.Node>();
+        for (const attr of opening.attributes) {
+          if (
+            attr.type === 'JSXAttribute' &&
+            attr.name.type === 'JSXIdentifier'
+          ) {
+            propsMap.set(attr.name.name, attr.value ?? t.booleanLiteral(true));
+          }
+        }
+
+        // Classify the atom back to HTML
+        const result = reverseClassifyAtom(atomName, propsMap);
+        if (!result) return;
+
+        // Use annotation tag if available, otherwise use classification
+        const targetTag = annotation?.tag ?? result.htmlTag;
+
+        // Rename the element
+        tag.name = targetTag;
+        if (path.node.closingElement) {
+          (path.node.closingElement.name as t.JSXIdentifier).name = targetTag;
+        }
+
+        // Track removal
+        imports.removeAtom(atomName);
+
+        // Remove props that are encoded in the HTML tag
+        if (result.removeProps.length > 0) {
+          opening.attributes = opening.attributes.filter(
+            attr =>
+              !(
+                attr.type === 'JSXAttribute' &&
+                attr.name.type === 'JSXIdentifier' &&
+                result.removeProps.includes(attr.name.name)
+              ),
+          );
+        }
+
+        // Inject implicit classes into className
+        if (result.injectClasses.length > 0) {
+          injectClasses(opening, result.injectClasses, annotation?.classes);
+        }
+
+        // Rename event handlers back
+        renameEventHandlers(opening);
+      },
+    },
+  };
+}
+
+/**
+ * Inject classes into a className attribute.
+ * If annotation provides original classes, use those instead.
+ */
+function injectClasses(
+  opening: t.JSXOpeningElement,
+  injectClasses: string[],
+  _annotationClasses?: string[],
+): void {
+  const classAttr = opening.attributes.find(
+    (a): a is t.JSXAttribute =>
+      a.type === 'JSXAttribute' &&
+      a.name.type === 'JSXIdentifier' &&
+      a.name.name === 'className',
+  );
+
+  if (classAttr && classAttr.value) {
+    // Modify existing className
+    if (classAttr.value.type === 'StringLiteral') {
+      classAttr.value = t.stringLiteral(
+        addClassesToString(classAttr.value.value, injectClasses),
+      );
+      return;
+    }
+
+    if (classAttr.value.type === 'JSXExpressionContainer') {
+      const expr = classAttr.value.expression;
+
+      // Template literal
+      if (expr.type === 'TemplateLiteral' && expr.quasis.length > 0) {
+        const first = expr.quasis[0];
+        first.value.raw = addClassesToString(first.value.raw, injectClasses);
+        first.value.cooked = addClassesToString(first.value.cooked ?? first.value.raw, injectClasses);
+        return;
+      }
+
+      // cn() call
+      if (
+        expr.type === 'CallExpression' &&
+        expr.callee.type === 'Identifier' &&
+        expr.callee.name === 'cn' &&
+        expr.arguments.length > 0 &&
+        expr.arguments[0].type === 'StringLiteral'
+      ) {
+        expr.arguments[0] = t.stringLiteral(
+          addClassesToString((expr.arguments[0] as t.StringLiteral).value, injectClasses),
+        );
+        return;
+      }
+    }
+  } else {
+    // No className — add one with injected classes
+    const classValue = injectClasses.join(' ');
+    if (classValue) {
+      opening.attributes.push(
+        t.jsxAttribute(
+          t.jsxIdentifier('className'),
+          t.stringLiteral(classValue),
+        ),
+      );
+    }
+  }
+}
+
+/**
+ * Rename atom event handlers back to HTML conventions.
+ */
+function renameEventHandlers(opening: t.JSXOpeningElement): void {
+  const map: Record<string, string> = { onPress: 'onClick' };
+
+  for (const attr of opening.attributes) {
+    if (
+      attr.type === 'JSXAttribute' &&
+      attr.name.type === 'JSXIdentifier' &&
+      attr.name.name in map
+    ) {
+      attr.name.name = map[attr.name.name];
+    }
+  }
+}

package/src/codemod/rules.ts

@@ -0,0 +1,174 @@
+/**
+ * Bidirectional element mapping rules.
+ *
+ * Each rule defines:
+ *  - htmlTag: The raw React element tag name
+ *  - atom: The workflow atom component name
+ *  - classSignal: Tailwind classes that trigger this mapping (forward)
+ *  - implicitClasses: Classes that are implicit in the atom and should be
+ *    removed on forward / added on reverse
+ *  - props: Additional props to set on forward / remove on reverse
+ */
+
+export interface MappingRule {
+  htmlTag: string;
+  atom: string;
+  /** Classes in className that signal this atom (forward classification) */
+  classSignal?: string[];
+  /** Classes implicit in the atom — removed on forward, injected on reverse */
+  implicitClasses?: string[];
+  /** Props added on forward, removed on reverse */
+  props?: Record<string, string | boolean>;
+  /** Priority when multiple rules match (higher wins) */
+  priority?: number;
+}
+
+/**
+ * Forward rules: HTML element → Atom
+ * Ordered by specificity — more specific signals checked first.
+ */
+export const FORWARD_RULES: MappingRule[] = [
+  // div with flex-col → Stack
+  {
+    htmlTag: 'div',
+    atom: 'Stack',
+    classSignal: ['flex-col'],
+    implicitClasses: ['flex', 'flex-col'],
+    priority: 20,
+  },
+  // div with grid → Grid
+  {
+    htmlTag: 'div',
+    atom: 'Grid',
+    classSignal: ['grid'],
+    implicitClasses: ['grid'],
+    priority: 20,
+  },
+  // div with flex (no flex-col) → Row
+  {
+    htmlTag: 'div',
+    atom: 'Row',
+    classSignal: ['flex'],
+    implicitClasses: ['flex'],
+    priority: 10,
+  },
+  // div with no layout signal → Stack (default container)
+  {
+    htmlTag: 'div',
+    atom: 'Stack',
+    classSignal: [],
+    implicitClasses: [],
+    priority: 0,
+  },
+
+  // Semantic HTML
+  { htmlTag: 'main', atom: 'Stack', implicitClasses: [] },
+  { htmlTag: 'aside', atom: 'Stack', implicitClasses: [] },
+  { htmlTag: 'nav', atom: 'Stack', implicitClasses: [] },
+  { htmlTag: 'section', atom: 'Section', implicitClasses: [] },
+  { htmlTag: 'header', atom: 'Row', implicitClasses: [] },
+  { htmlTag: 'footer', atom: 'Row', implicitClasses: [] },
+
+  // Text elements
+  { htmlTag: 'span', atom: 'Text', implicitClasses: [] },
+  { htmlTag: 'p', atom: 'Text', implicitClasses: [] },
+  { htmlTag: 'label', atom: 'Text', implicitClasses: [] },
+  { htmlTag: 'h1', atom: 'Text', implicitClasses: [], props: { variant: 'h1' } },
+  { htmlTag: 'h2', atom: 'Text', implicitClasses: [], props: { variant: 'h2' } },
+  { htmlTag: 'h3', atom: 'Text', implicitClasses: [], props: { variant: 'h3' } },
+  { htmlTag: 'h4', atom: 'Text', implicitClasses: [], props: { variant: 'h4' } },
+  { htmlTag: 'h5', atom: 'Text', implicitClasses: [], props: { variant: 'h5' } },
+  { htmlTag: 'h6', atom: 'Text', implicitClasses: [], props: { variant: 'h6' } },
+
+  // Interactive elements
+  { htmlTag: 'button', atom: 'Button', implicitClasses: [] },
+  { htmlTag: 'a', atom: 'Link', implicitClasses: [] },
+
+  // Form elements
+  { htmlTag: 'input', atom: 'TextInput', implicitClasses: [] },
+  {
+    htmlTag: 'textarea',
+    atom: 'TextInput',
+    implicitClasses: [],
+    props: { multiline: true },
+  },
+
+  // Media
+  { htmlTag: 'img', atom: 'Image', implicitClasses: [] },
+];
+
+/**
+ * Reverse rules: Atom → HTML element
+ * Derived from forward rules but keyed by atom name.
+ */
+export interface ReverseRule {
+  atom: string;
+  htmlTag: string;
+  /** Classes to inject into className on reverse */
+  injectClasses?: string[];
+  /** Props to remove on reverse (they're encoded in the HTML tag) */
+  removeProps?: string[];
+}
+
+export const REVERSE_RULES: ReverseRule[] = [
+  { atom: 'Stack', htmlTag: 'div', injectClasses: ['flex', 'flex-col'] },
+  { atom: 'Row', htmlTag: 'div', injectClasses: ['flex'] },
+  { atom: 'Grid', htmlTag: 'div', injectClasses: ['grid'] },
+  { atom: 'Text', htmlTag: 'span' },
+  { atom: 'Button', htmlTag: 'button' },
+  { atom: 'Link', htmlTag: 'a' },
+  { atom: 'TextInput', htmlTag: 'input' },
+  { atom: 'Image', htmlTag: 'img' },
+  { atom: 'Section', htmlTag: 'section' },
+];
+
+/**
+ * Atoms that are NOT HTML elements — control flow and structural.
+ * These are handled separately by control-flow.ts, not element mapping.
+ */
+export const CONTROL_FLOW_ATOMS = new Set([
+  'Show',
+  'Each',
+  'Modal',
+  'Slot',
+  'Divider',
+]);
+
+/**
+ * Components that should never be transformed (third-party, icons, etc.)
+ */
+export const PASSTHROUGH_COMPONENTS = new Set([
+  // Framer Motion
+  'AnimatePresence',
+  // TanStack
+  'useVirtualizer',
+  // Fragment
+  'Fragment',
+]);
+
+/**
+ * Atom import source
+ */
+export const ATOM_IMPORT_SOURCE = '@mindmatrix/react/atoms';
+
+/**
+ * Atoms that may appear in import but are control-flow, not elements.
+ */
+export const ALL_ATOM_NAMES = new Set([
+  'Stack', 'Row', 'Grid', 'Text', 'Button', 'Link',
+  'TextInput', 'Image', 'Section',
+  'Show', 'Each', 'Modal', 'Slot', 'Divider',
+  'Badge', 'Icon',
+]);
+
+/**
+ * Text variant → heading tag mapping for reverse.
+ */
+export const TEXT_VARIANT_TO_TAG: Record<string, string> = {
+  h1: 'h1',
+  h2: 'h2',
+  h3: 'h3',
+  h4: 'h4',
+  h5: 'h5',
+  h6: 'h6',
+};