@mmapp/player-core 0.1.0-alpha.1

package/src/dsl/compiler/workflow-compiler.ts

@@ -0,0 +1,600 @@
+/**
+ * Workflow Compiler — Pass 2 of compilation.
+ *
+ * Transforms ThingSymbol → IRWorkflowDefinition.
+ * Handles states, transitions, fields, roles, events, and expressions.
+ */
+
+import type { ASTNode } from '../types';
+import type {
+  IRWorkflowDefinition,
+  IRStateDefinition,
+  IRTransitionDefinition,
+  IRFieldDefinition,
+  IRActionDefinition,
+  IRConditionDefinition,
+  IROnEventSubscription,
+  IROnEventAction,
+  IRRoleDefinition,
+  IRStateType,
+  CompilerError,
+} from '../ir-types';
+import type { SymbolTable, ThingSymbol } from './symbol-table';
+import { mapField } from './field-mapper';
+import { slugify, snakeCase, generateActionId } from './utils';
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+export function compileWorkflows(
+  symbols: SymbolTable,
+): { workflows: IRWorkflowDefinition[]; errors: CompilerError[] } {
+  const workflows: IRWorkflowDefinition[] = [];
+  const errors: CompilerError[] = [];
+
+  for (const [, thing] of symbols.things) {
+    const { workflow, errors: wfErrors } = compileThing(thing);
+    workflows.push(workflow);
+    errors.push(...wfErrors);
+  }
+
+  return { workflows, errors };
+}
+
+// =============================================================================
+// Thing → Workflow
+// =============================================================================
+
+function compileThing(
+  thing: ThingSymbol,
+): { workflow: IRWorkflowDefinition; errors: CompilerError[] } {
+  const errors: CompilerError[] = [];
+  const slug = slugify(thing.name);
+
+  // Collect field names for expression resolution
+  const fieldNames = new Set(
+    thing.fields.map(f => {
+      const fd = f.token.data;
+      return fd.type === 'field_def' ? fd.name : '';
+    }).filter(Boolean),
+  );
+
+  // Compile fields
+  const fields = compileFields(thing.fields);
+
+  // Compile states
+  const stateNames = new Set(
+    thing.states.map(s => {
+      const sd = s.token.data;
+      return sd.type === 'state_decl' ? sd.name : '';
+    }).filter(Boolean),
+  );
+
+  const states = compileStates(thing, fieldNames);
+
+  // Compile transitions
+  const transitions = compileTransitions(thing, fieldNames, stateNames, errors);
+
+  // Collect roles from transition guards
+  const roles = collectRoles(thing);
+
+  // Validate starts_at
+  if (!thing.startsAt) {
+    errors.push({
+      code: 'MISSING_STARTS_AT',
+      message: `Workflow "${thing.name}" has no starts_at declaration`,
+      lineNumber: thing.node.token.lineNumber,
+      severity: 'error',
+    });
+  }
+
+  // Tags
+  const tags = thing.tags.length > 0
+    ? thing.tags.map(t => ({ tag_name: t }))
+    : undefined;
+
+  // Metadata (levels)
+  let metadata: Record<string, unknown> | undefined;
+  if (thing.levels.length > 0) {
+    metadata = {
+      levels: thing.levels.map(l => {
+        const ld = l.token.data;
+        if (ld.type === 'level_def') {
+          return { level: ld.level, title: ld.title, fromXp: ld.fromXp };
+        }
+        return null;
+      }).filter(Boolean),
+    };
+  }
+
+  return {
+    workflow: {
+      slug,
+      name: thing.name,
+      version: thing.version,
+      category: 'blueprint',
+      states,
+      transitions,
+      fields,
+      roles,
+      tags,
+      metadata,
+    },
+    errors,
+  };
+}
+
+// =============================================================================
+// Fields
+// =============================================================================
+
+function compileFields(fieldNodes: ASTNode[]): IRFieldDefinition[] {
+  return fieldNodes.map(node => {
+    const data = node.token.data;
+    if (data.type !== 'field_def') return null;
+    return mapField(data);
+  }).filter((f): f is IRFieldDefinition => f !== null);
+}
+
+// =============================================================================
+// States
+// =============================================================================
+
+function compileStates(
+  thing: ThingSymbol,
+  fieldNames: Set<string>,
+): IRStateDefinition[] {
+  return thing.states.map(stateNode => {
+    const data = stateNode.token.data;
+    if (data.type !== 'state_decl') {
+      return null;
+    }
+
+    const stateName = data.name;
+    const stateType = resolveStateType(stateName, data.isFinal, thing.startsAt);
+
+    // Collect on_enter actions from "when entered" children
+    const onEnterActions: IRActionDefinition[] = [];
+    const onEventSubs: IROnEventSubscription[] = [];
+
+    for (const child of stateNode.children) {
+      const cd = child.token.data;
+      if (cd.type === 'when') {
+        if (cd.condition === 'entered') {
+          // on_enter: collect set_action/do_action children
+          const actions = compileWhenEnteredActions(child, stateName, fieldNames);
+          onEnterActions.push(...actions);
+        } else if (cd.condition.startsWith('receives ')) {
+          // on_event subscription
+          const sub = compileOnEvent(child, stateName, fieldNames);
+          if (sub) onEventSubs.push(sub);
+        }
+      }
+    }
+
+    const state: IRStateDefinition = {
+      name: stateName,
+      type: stateType,
+      on_enter: onEnterActions,
+      during: [],
+      on_exit: [],
+    };
+
+    if (onEventSubs.length > 0) {
+      state.on_event = onEventSubs;
+    }
+
+    return state;
+  }).filter((s): s is IRStateDefinition => s !== null);
+}
+
+function resolveStateType(
+  name: string,
+  isFinal: boolean,
+  startsAt?: string,
+): IRStateType {
+  if (startsAt && name === startsAt) return 'START';
+  if (isFinal && name.toLowerCase().includes('cancel')) return 'CANCELLED';
+  if (isFinal) return 'END';
+  return 'REGULAR';
+}
+
+// =============================================================================
+// When Entered → on_enter actions
+// =============================================================================
+
+function compileWhenEnteredActions(
+  whenNode: ASTNode,
+  stateName: string,
+  fieldNames: Set<string>,
+): IRActionDefinition[] {
+  const context = `${slugify(stateName)}-on-enter`;
+  return whenNode.children.map((child, i) => {
+    const cd = child.token.data;
+    if (cd.type === 'set_action') {
+      return {
+        id: generateActionId(context, i),
+        type: 'set_field',
+        mode: 'auto' as const,
+        config: {
+          field: snakeCase(cd.field),
+          expression: transformExpression(cd.expression, fieldNames),
+        },
+      };
+    }
+    if (cd.type === 'do_action') {
+      return {
+        id: generateActionId(context, i),
+        type: cd.action,
+        mode: 'auto' as const,
+        config: {},
+      };
+    }
+    return null;
+  }).filter((a): a is IRActionDefinition => a !== null);
+}
+
+// =============================================================================
+// When Receives → on_event subscription
+// =============================================================================
+
+function compileOnEvent(
+  whenNode: ASTNode,
+  stateName: string,
+  fieldNames: Set<string>,
+): IROnEventSubscription | null {
+  const cd = whenNode.token.data;
+  if (cd.type !== 'when') return null;
+
+  // Parse: receives "event name" from source
+  const match = cd.condition.match(/^receives\s+"([^"]+)"\s+from\s+(\S+)$/);
+  if (!match) return null;
+
+  const eventName = match[1];
+  const sourceSlug = slugify(match[2]);
+
+  // Build topic pattern: *:{{ entity_id }}:<source-slug>:instance.<event-slug>
+  const eventSlug = eventName.replace(/\s+/g, '.');
+  const topicPattern = `*:{{ entity_id }}:${sourceSlug}:instance.${eventSlug}`;
+
+  // Compile child set_actions into on_event actions
+  const actions: IROnEventAction[] = whenNode.children.map(child => {
+    const acd = child.token.data;
+    if (acd.type === 'set_action') {
+      return {
+        type: 'set_field' as const,
+        field: snakeCase(acd.field),
+        expression: transformExpression(acd.expression, fieldNames),
+      };
+    }
+    return null;
+  }).filter((a): a is IROnEventAction => a !== null);
+
+  return {
+    match: topicPattern,
+    description: `On ${eventName} from ${match[2]}`,
+    actions,
+  };
+}
+
+// =============================================================================
+// Transitions
+// =============================================================================
+
+function compileTransitions(
+  thing: ThingSymbol,
+  fieldNames: Set<string>,
+  stateNames: Set<string>,
+  errors: CompilerError[],
+): IRTransitionDefinition[] {
+  const transitions: IRTransitionDefinition[] = [];
+
+  for (const stateNode of thing.states) {
+    const stateData = stateNode.token.data;
+    if (stateData.type !== 'state_decl') continue;
+    const fromState = stateData.name;
+
+    for (const child of stateNode.children) {
+      const cd = child.token.data;
+      if (cd.type !== 'transition') continue;
+
+      const isAuto = cd.verb.startsWith('auto ');
+      const transitionName = slugify(cd.verb);
+
+      // Validate target state
+      if (!stateNames.has(cd.target)) {
+        errors.push({
+          code: 'UNKNOWN_TARGET_STATE',
+          message: `Transition "${cd.verb}" targets unknown state "${cd.target}"`,
+          lineNumber: child.token.lineNumber,
+          severity: 'warning',
+        });
+      }
+
+      // Parse guard → roles
+      let roles: string[] | undefined;
+      if (cd.guard) {
+        roles = parseGuard(cd.guard);
+      }
+
+      // Compile conditions from nested `when` children
+      const conditions = compileTransitionConditions(child, fieldNames);
+
+      // Compile actions from nested `set_action`/`do_action` children
+      const actions = compileTransitionActions(child, transitionName, fieldNames);
+
+      const transition: IRTransitionDefinition = {
+        name: transitionName,
+        from: [fromState],
+        to: cd.target,
+        actions,
+      };
+
+      if (isAuto) transition.auto = true;
+      if (roles && roles.length > 0) transition.roles = roles;
+      if (conditions && conditions.length > 0) transition.conditions = conditions;
+
+      transitions.push(transition);
+    }
+  }
+
+  return transitions;
+}
+
+function parseGuard(guard: string): string[] {
+  // "admin only" → ['admin']
+  // "owner only" → ['owner']
+  // "admin and owner" → ['admin', 'owner']
+  const cleaned = guard.replace(/\s+only$/, '');
+  return cleaned.split(/\s+and\s+/).map(r => r.trim());
+}
+
+function compileTransitionConditions(
+  transitionNode: ASTNode,
+  fieldNames: Set<string>,
+): IRConditionDefinition[] | undefined {
+  const conditions: IRConditionDefinition[] = [];
+
+  for (const child of transitionNode.children) {
+    const cd = child.token.data;
+    if (cd.type === 'when') {
+      const parsed = parseConditionExpression(cd.condition, fieldNames);
+      if (parsed) conditions.push(parsed);
+    }
+  }
+
+  return conditions.length > 0 ? conditions : undefined;
+}
+
+function compileTransitionActions(
+  transitionNode: ASTNode,
+  transitionName: string,
+  fieldNames: Set<string>,
+): IRActionDefinition[] {
+  const actions: IRActionDefinition[] = [];
+  const context = `${transitionName}-action`;
+
+  for (const child of transitionNode.children) {
+    const cd = child.token.data;
+    if (cd.type === 'set_action') {
+      actions.push({
+        id: generateActionId(context, actions.length),
+        type: 'set_field',
+        mode: 'auto',
+        config: {
+          field: snakeCase(cd.field),
+          expression: transformExpression(cd.expression, fieldNames),
+        },
+      });
+    } else if (cd.type === 'do_action') {
+      actions.push({
+        id: generateActionId(context, actions.length),
+        type: cd.action,
+        mode: 'auto',
+        config: {},
+      });
+    }
+  }
+
+  return actions;
+}
+
+// =============================================================================
+// Condition Expression Parsing
+// =============================================================================
+
+function parseConditionExpression(
+  condition: string,
+  fieldNames: Set<string>,
+): IRConditionDefinition | null {
+  // Handle compound "and" conditions
+  if (condition.includes(' and ')) {
+    const parts = condition.split(/\s+and\s+/);
+    const subConditions = parts
+      .map(p => parseSingleCondition(p.trim(), fieldNames))
+      .filter((c): c is IRConditionDefinition => c !== null);
+
+    if (subConditions.length > 1) {
+      return { AND: subConditions };
+    }
+    if (subConditions.length === 1) {
+      return subConditions[0];
+    }
+    return null;
+  }
+
+  return parseSingleCondition(condition, fieldNames);
+}
+
+function parseSingleCondition(
+  expr: string,
+  fieldNames: Set<string>,
+): IRConditionDefinition | null {
+  // Pattern: left operator right
+  const opMatch = expr.match(/^(.+?)\s*(>=|<=|>|<|==|!=)\s*(.+)$/);
+  if (!opMatch) return null;
+
+  const left = opMatch[1].trim();
+  const op = opMatch[2];
+  const right = opMatch[3].trim();
+
+  const operatorMap: Record<string, IRConditionDefinition['operator']> = {
+    '>=': 'gte',
+    '<=': 'lte',
+    '>': 'gt',
+    '<': 'lt',
+    '==': 'eq',
+    '!=': 'ne',
+  };
+
+  const operator = operatorMap[op];
+  if (!operator) return null;
+
+  const leftField = resolveFieldRef(left, fieldNames);
+  const rightValue = resolveConditionValue(right, fieldNames);
+
+  const condition: IRConditionDefinition = {
+    field: leftField,
+    operator,
+  };
+
+  if (typeof rightValue === 'number') {
+    condition.value = rightValue;
+  } else {
+    condition.expression = rightValue;
+  }
+
+  return condition;
+}
+
+function resolveFieldRef(name: string, fieldNames: Set<string>): string {
+  // Check if name matches a known field
+  if (fieldNames.has(name)) {
+    return `state_data.${snakeCase(name)}`;
+  }
+  // Try to find by partial match
+  for (const fn of fieldNames) {
+    if (fn === name) return `state_data.${snakeCase(fn)}`;
+  }
+  return `state_data.${snakeCase(name)}`;
+}
+
+function resolveConditionValue(
+  value: string,
+  fieldNames: Set<string>,
+): number | string {
+  // Numeric literal
+  const num = Number(value);
+  if (!isNaN(num)) return num;
+
+  // Field reference
+  if (fieldNames.has(value)) {
+    return `state_data.${snakeCase(value)}`;
+  }
+
+  return `state_data.${snakeCase(value)}`;
+}
+
+// =============================================================================
+// Expression Transformation
+// =============================================================================
+
+/**
+ * Transform a DSL expression into an IR expression.
+ *
+ * Rules:
+ * 1. String literals (quoted) → passthrough
+ * 2. now() → passthrough
+ * 3. "the event's X" → $event.state_data.<snake_case_X>
+ * 4. Known field names → state_data.<snake_case>
+ * 5. A + B → add(resolved_A, resolved_B)
+ * 6. A - B → subtract(resolved_A, resolved_B)
+ * 7. Numeric literals → passthrough
+ */
+export function transformExpression(
+  expression: string,
+  fieldNames: Set<string>,
+): string {
+  const trimmed = expression.trim();
+
+  // String literal: "value"
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    return trimmed;
+  }
+
+  // now() passthrough
+  if (trimmed === 'now()') return 'now()';
+
+  // Arithmetic: A + B or A - B
+  const addMatch = trimmed.match(/^(.+?)\s*\+\s*(.+)$/);
+  if (addMatch) {
+    const left = resolveExpressionPart(addMatch[1].trim(), fieldNames);
+    const right = resolveExpressionPart(addMatch[2].trim(), fieldNames);
+    return `add(${left}, ${right})`;
+  }
+
+  const subMatch = trimmed.match(/^(.+?)\s*-\s*(.+)$/);
+  if (subMatch) {
+    const left = resolveExpressionPart(subMatch[1].trim(), fieldNames);
+    const right = resolveExpressionPart(subMatch[2].trim(), fieldNames);
+    return `subtract(${left}, ${right})`;
+  }
+
+  // Single value
+  return resolveExpressionPart(trimmed, fieldNames);
+}
+
+function resolveExpressionPart(
+  part: string,
+  fieldNames: Set<string>,
+): string {
+  const trimmed = part.trim();
+
+  // Numeric literal
+  const num = Number(trimmed);
+  if (!isNaN(num) && trimmed !== '') return String(num);
+
+  // String literal
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) return trimmed;
+
+  // "the event's X" → $event.state_data.<snake>
+  const eventMatch = trimmed.match(/^the event's\s+(.+)$/);
+  if (eventMatch) {
+    return `$event.state_data.${snakeCase(eventMatch[1])}`;
+  }
+
+  // now() passthrough
+  if (trimmed === 'now()') return 'now()';
+
+  // Known field name → state_data.<snake>
+  if (fieldNames.has(trimmed)) {
+    return `state_data.${snakeCase(trimmed)}`;
+  }
+
+  // Default: treat as field reference
+  return `state_data.${snakeCase(trimmed)}`;
+}
+
+// =============================================================================
+// Role Collection
+// =============================================================================
+
+function collectRoles(thing: ThingSymbol): IRRoleDefinition[] {
+  const roleNames = new Set<string>();
+
+  for (const stateNode of thing.states) {
+    for (const child of stateNode.children) {
+      const cd = child.token.data;
+      if (cd.type === 'transition' && cd.guard) {
+        const roles = parseGuard(cd.guard);
+        for (const r of roles) roleNames.add(r);
+      }
+    }
+  }
+
+  return Array.from(roleNames).map(name => ({
+    name,
+    permissions: [`transition:${name}`],
+  }));
+}

package/src/dsl/index.ts

@@ -0,0 +1,66 @@
+export { tokenize, tokenizeLine } from './lexer';
+export { parse, walkTree, findByType } from './parser';
+export type {
+  LineType,
+  LineToken,
+  LineData,
+  ASTNode,
+  ParseResult,
+  ParseError,
+  Emphasis,
+  Constraint,
+  SpaceDeclData,
+  ThingDeclData,
+  ThingRefData,
+  FragmentDefData,
+  FieldDefData,
+  StateDeclData,
+  StartsAtData,
+  TransitionData,
+  WhenData,
+  SetActionData,
+  DoActionData,
+  GoActionData,
+  TellActionData,
+  ShowActionData,
+  DataSourceData,
+  IterationData,
+  GroupingData,
+  ContentData,
+  StringLiteralData,
+  SearchData,
+  QualifierData,
+  NavigationData,
+  PathMappingData,
+  SectionData,
+  TaggedData,
+  LevelDefData,
+} from './types';
+
+export { compile, compileAST } from './compiler';
+export type {
+  CompilationResult,
+  CompilerError,
+  CompilerErrorCode,
+  IRWorkflowDefinition,
+  IRStateDefinition,
+  IRTransitionDefinition,
+  IRFieldDefinition,
+  IRFieldValidation,
+  IRActionDefinition,
+  IRConditionDefinition,
+  IRExperienceNode,
+  IRDataSource,
+  IRWorkflowDataSource,
+  IRExperienceDefinition,
+  IRBlueprintManifest,
+  IROnEventSubscription,
+  IROnEventAction,
+  IRRoleDefinition,
+  IRStateType,
+  IRActionMode,
+  IRWorkflowFieldType,
+  PureFormWorkflow,
+  CompiledOutput,
+} from './ir-types';
+export { normalizeCategory } from './ir-types';