@mmapp/player-core 0.1.0-alpha.1

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

@@ -0,0 +1,76 @@
+/**
+ * Manifest Compiler — Pass 4 of compilation.
+ *
+ * Transforms space declaration → IRBlueprintManifest.
+ */
+
+import type { IRBlueprintManifest, CompilerError } from '../ir-types';
+import type { SymbolTable } from './symbol-table';
+import { slugify } from './utils';
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+export function compileManifest(
+  symbols: SymbolTable,
+): { manifest?: IRBlueprintManifest; errors: CompilerError[] } {
+  const errors: CompilerError[] = [];
+
+  if (!symbols.space) {
+    return { manifest: undefined, errors };
+  }
+
+  const space = symbols.space;
+
+  // Workflows from thing refs
+  const workflows = space.thingRefs.map(ref => ({
+    slug: slugify(ref.name),
+    role: (ref.kind ?? 'primary') as 'primary' | 'child' | 'derived' | 'utility',
+  }));
+
+  // Experience ID from space name
+  const experience_id = slugify(space.name);
+
+  // Routes from paths
+  const routes = space.paths.map(p => {
+    const route: {
+      path: string;
+      node: string;
+      entityType?: string;
+      entityIdSource?: 'user' | 'param';
+    } = {
+      path: p.path,
+      node: slugify(p.view),
+    };
+
+    if (p.context) {
+      route.entityType = p.context;
+      route.entityIdSource = inferEntityIdSource(p.path, p.context);
+    }
+
+    return route;
+  });
+
+  return {
+    manifest: {
+      workflows,
+      experience_id,
+      routes: routes.length > 0 ? routes : undefined,
+    },
+    errors,
+  };
+}
+
+// =============================================================================
+// Entity ID Source Inference
+// =============================================================================
+
+function inferEntityIdSource(
+  path: string,
+  context: string,
+): 'user' | 'param' {
+  if (context === 'user') return 'user';
+  if (path.includes(':id')) return 'param';
+  return 'user';
+}

package/src/dsl/compiler/symbol-table.ts

@@ -0,0 +1,214 @@
+/**
+ * Symbol Table — Pass 1 of compilation.
+ *
+ * Walks all root-level AST nodes and collects declared names:
+ * space, things (workflows), fragments, and views.
+ */
+
+import type { ASTNode } from '../types';
+
+// =============================================================================
+// Symbol Types
+// =============================================================================
+
+export interface SpaceSymbol {
+  name: string;
+  version: string;
+  node: ASTNode;
+  thingRefs: Array<{ name: string; kind?: string }>;
+  paths: Array<{ path: string; view: string; context?: string }>;
+  tags: string[];
+}
+
+export interface ThingSymbol {
+  name: string;
+  version: string;
+  node: ASTNode;
+  fields: ASTNode[];
+  states: ASTNode[];
+  startsAt?: string;
+  tags: string[];
+  levels: ASTNode[];
+}
+
+export interface FragmentSymbol {
+  name: string;
+  node: ASTNode;
+}
+
+export interface ViewSymbol {
+  name: string;
+  node: ASTNode;
+}
+
+export interface SymbolTable {
+  space?: SpaceSymbol;
+  things: Map<string, ThingSymbol>;
+  fragments: Map<string, FragmentSymbol>;
+  views: Map<string, ViewSymbol>;
+}
+
+// =============================================================================
+// View-like child types (used to distinguish root views from states)
+// =============================================================================
+
+const VIEW_CHILD_TYPES = new Set([
+  'data_source', 'content', 'iteration', 'section',
+  'string_literal', 'search', 'grouping', 'navigation', 'pages',
+  'qualifier',
+]);
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+export function collectSymbols(nodes: ASTNode[]): SymbolTable {
+  const table: SymbolTable = {
+    things: new Map(),
+    fragments: new Map(),
+    views: new Map(),
+  };
+
+  for (const node of nodes) {
+    const { data } = node.token;
+
+    switch (data.type) {
+      case 'space_decl':
+        table.space = collectSpace(node);
+        break;
+
+      case 'thing_decl':
+        table.things.set(data.name, collectThing(node));
+        break;
+
+      case 'fragment_def':
+        table.fragments.set(data.name, { name: data.name, node });
+        break;
+
+      case 'state_decl':
+        // Root-level state_decl with view-like children → it's actually a view
+        if (hasViewChildren(node)) {
+          table.views.set(data.name, { name: data.name, node });
+        }
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  return table;
+}
+
+// =============================================================================
+// Space Collection
+// =============================================================================
+
+function collectSpace(node: ASTNode): SpaceSymbol {
+  const data = node.token.data;
+  if (data.type !== 'space_decl') throw new Error('Expected space_decl');
+
+  const space: SpaceSymbol = {
+    name: data.name,
+    version: data.version,
+    node,
+    thingRefs: [],
+    paths: [],
+    tags: [],
+  };
+
+  for (const child of node.children) {
+    const cd = child.token.data;
+
+    if (cd.type === 'tagged') {
+      space.tags.push(...cd.tags);
+    } else if (cd.type === 'section' && cd.name === 'things') {
+      for (const ref of child.children) {
+        if (ref.token.data.type === 'thing_ref') {
+          space.thingRefs.push({
+            name: ref.token.data.name,
+            kind: ref.token.data.kind,
+          });
+        }
+      }
+    } else if (cd.type === 'section' && cd.name === 'paths') {
+      for (const pm of child.children) {
+        if (pm.token.data.type === 'path_mapping') {
+          space.paths.push({
+            path: pm.token.data.path,
+            view: pm.token.data.view,
+            context: pm.token.data.context,
+          });
+        }
+      }
+    }
+  }
+
+  return space;
+}
+
+// =============================================================================
+// Thing Collection
+// =============================================================================
+
+function collectThing(node: ASTNode): ThingSymbol {
+  const data = node.token.data;
+  if (data.type !== 'thing_decl') throw new Error('Expected thing_decl');
+
+  const thing: ThingSymbol = {
+    name: data.name,
+    version: data.version ?? '1.0.0',
+    node,
+    fields: [],
+    states: [],
+    tags: [],
+    levels: [],
+  };
+
+  for (const child of node.children) {
+    const cd = child.token.data;
+
+    switch (cd.type) {
+      case 'field_def':
+        thing.fields.push(child);
+        break;
+
+      case 'state_decl':
+        thing.states.push(child);
+        break;
+
+      case 'starts_at':
+        thing.startsAt = cd.state;
+        break;
+
+      case 'tagged':
+        thing.tags.push(...cd.tags);
+        break;
+
+      case 'section':
+        if (cd.name === 'levels') {
+          for (const lvl of child.children) {
+            if (lvl.token.data.type === 'level_def') {
+              thing.levels.push(lvl);
+            }
+          }
+        }
+        break;
+    }
+  }
+
+  return thing;
+}
+
+// =============================================================================
+// Heuristic: Does a root node have view-like children?
+// =============================================================================
+
+function hasViewChildren(node: ASTNode): boolean {
+  for (const child of node.children) {
+    if (VIEW_CHILD_TYPES.has(child.token.data.type)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/dsl/compiler/utils.ts

@@ -0,0 +1,48 @@
+/**
+ * Compiler Utilities — pure string transformation helpers.
+ */
+
+/**
+ * Convert a name to kebab-case slug.
+ * "project management" → "project-management"
+ * "user stats" → "user-stats"
+ */
+export function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-');
+}
+
+/**
+ * Convert a name to snake_case.
+ * "total tasks" → "total_tasks"
+ * "started at" → "started_at"
+ */
+export function snakeCase(name: string): string {
+  return name
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s_]/g, '')
+    .replace(/\s+/g, '_')
+    .replace(/_+/g, '_');
+}
+
+/**
+ * Generate a deterministic ID from parts.
+ * generateId("project", "draft") → "project--draft"
+ * generateId("task", "in progress") → "task--in-progress"
+ */
+export function generateId(...parts: string[]): string {
+  return parts.map(p => slugify(p)).join('--');
+}
+
+/**
+ * Generate a deterministic action ID.
+ * generateActionId("active-on-enter", 0) → "active-on-enter-0"
+ */
+export function generateActionId(context: string, index: number): string {
+  return `${context}-${index}`;
+}

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

@@ -0,0 +1,286 @@
+/**
+ * View Compiler — Pass 3 of compilation.
+ *
+ * Transforms fragments and views → IRExperienceDefinition with ExperienceNode trees.
+ * Handles data sources, content, iteration, layout, and bindings.
+ */
+
+import type { ASTNode } from '../types';
+import type {
+  IRExperienceDefinition,
+  IRExperienceNode,
+  IRWorkflowDataSource,
+  IRDataSource,
+  CompilerError,
+} from '../ir-types';
+import type { SymbolTable, SpaceSymbol } from './symbol-table';
+import { slugify, snakeCase, generateId } from './utils';
+import {
+  mapContent,
+  mapStringLiteral,
+  mapIteration,
+  mapSection,
+  mapSearch,
+  mapNavigation,
+  mapPages,
+} from './component-mapper';
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+export function compileViews(
+  symbols: SymbolTable,
+): { experiences: IRExperienceDefinition[]; errors: CompilerError[] } {
+  const experiences: IRExperienceDefinition[] = [];
+  const errors: CompilerError[] = [];
+
+  // Compile fragments
+  for (const [, fragment] of symbols.fragments) {
+    const exp = compileViewNode(
+      fragment.name,
+      fragment.node,
+      symbols.space,
+    );
+    experiences.push(exp);
+  }
+
+  // Compile views
+  for (const [, view] of symbols.views) {
+    const exp = compileViewNode(
+      view.name,
+      view.node,
+      symbols.space,
+    );
+    experiences.push(exp);
+  }
+
+  return { experiences, errors };
+}
+
+// =============================================================================
+// View Compilation
+// =============================================================================
+
+function compileViewNode(
+  name: string,
+  node: ASTNode,
+  space?: SpaceSymbol,
+): IRExperienceDefinition {
+  const viewSlug = slugify(name);
+  const dataSources: IRDataSource[] = [];
+  const workflowSlugs: string[] = [];
+
+  // First pass: collect data sources
+  for (const child of node.children) {
+    if (child.token.data.type === 'data_source') {
+      const ds = compileDataSource(child);
+      dataSources.push(ds);
+      if (ds.type === 'workflow' && ds.slug) {
+        workflowSlugs.push(ds.slug);
+      }
+    }
+  }
+
+  // Second pass: build ExperienceNode tree from remaining children
+  const children = compileChildren(node.children, viewSlug, false);
+
+  // Build the root node
+  const rootNode: IRExperienceNode = {
+    id: viewSlug,
+    children: children.length > 0 ? children : undefined,
+    dataSources: dataSources.length > 0 ? dataSources : undefined,
+  };
+
+  if (children.length > 1) {
+    rootNode.layout = 'stack';
+  }
+
+  return {
+    slug: viewSlug,
+    version: space?.version ?? '1.0.0',
+    name,
+    category: 'purpose',
+    view_definition: rootNode,
+    workflows: workflowSlugs,
+    children: [],
+    data_bindings: [],
+    is_default: false,
+  };
+}
+
+// =============================================================================
+// Data Source Compilation
+// =============================================================================
+
+function compileDataSource(node: ASTNode): IRWorkflowDataSource {
+  const data = node.token.data;
+  if (data.type !== 'data_source') throw new Error('Expected data_source');
+
+  // Determine query type from alias pronoun
+  const query = resolveQueryType(data.alias);
+
+  // Strip pronoun from alias to get the name
+  const name = stripPronoun(data.alias);
+
+  // Slug from source
+  const slug = slugify(data.source);
+
+  const ds: IRWorkflowDataSource = {
+    type: 'workflow',
+    name,
+    slug,
+    query,
+  };
+
+  // Scope
+  if (data.scope) {
+    ds.parentInstanceId = '{{ parent_instance_id }}';
+  }
+
+  // Process qualifier children
+  for (const child of node.children) {
+    const cd = child.token.data;
+    if (cd.type === 'qualifier') {
+      applyQualifier(ds, cd);
+    }
+  }
+
+  return ds;
+}
+
+function resolveQueryType(alias: string): 'latest' | 'list' | 'count' {
+  const firstWord = alias.split(/\s+/)[0];
+  if (firstWord === 'this') return 'latest';
+  // my, its, these → list
+  return 'list';
+}
+
+function stripPronoun(alias: string): string {
+  const pronouns = ['my', 'this', 'its', 'these'];
+  const words = alias.split(/\s+/);
+  if (words.length > 1 && pronouns.includes(words[0])) {
+    return words.slice(1).join(' ');
+  }
+  return alias;
+}
+
+function applyQualifier(
+  ds: IRWorkflowDataSource,
+  qualifier: { kind: string; value: string },
+): void {
+  switch (qualifier.kind) {
+    case 'order':
+      if (qualifier.value === 'newest') {
+        ds.sort = 'created_at:desc';
+      } else if (qualifier.value === 'oldest') {
+        ds.sort = 'created_at:asc';
+      } else {
+        ds.sort = `${snakeCase(qualifier.value)}:desc`;
+      }
+      break;
+
+    case 'pagination':
+      ds.paginated = true;
+      ds.pageSize = parseInt(qualifier.value, 10);
+      break;
+
+    case 'searchable':
+      ds.searchFields = qualifier.value
+        .split(/\s+and\s+/)
+        .map(f => snakeCase(f.trim()));
+      break;
+
+    case 'filterable':
+      ds.facets = qualifier.value
+        .split(/\s+and\s+/)
+        .map(f => snakeCase(f.trim()));
+      break;
+  }
+}
+
+// =============================================================================
+// Children Compilation
+// =============================================================================
+
+function compileChildren(
+  children: ASTNode[],
+  parentId: string,
+  insideEach: boolean,
+): IRExperienceNode[] {
+  const nodes: IRExperienceNode[] = [];
+  let childIndex = 0;
+
+  for (const child of children) {
+    const cd = child.token.data;
+
+    switch (cd.type) {
+      case 'data_source':
+        // Data sources are handled at the root level, skip here
+        break;
+
+      case 'qualifier':
+        // Qualifiers attach to their parent data source, skip here
+        break;
+
+      case 'content':
+        nodes.push(mapContent(cd, insideEach, parentId, childIndex++));
+        break;
+
+      case 'string_literal': {
+        const strNode = mapStringLiteral(cd, parentId, childIndex++);
+        // If string literal has children, they're nested under it
+        if (child.children.length > 0) {
+          strNode.children = compileChildren(child.children, strNode.id, insideEach);
+          if (strNode.children.length > 1) {
+            strNode.layout = 'stack';
+          }
+        }
+        nodes.push(strNode);
+        break;
+      }
+
+      case 'iteration': {
+        const iterChildren = compileChildren(child.children, generateId(parentId, 'each', cd.subject), true);
+        nodes.push(mapIteration(cd, iterChildren, parentId, childIndex++));
+        break;
+      }
+
+      case 'section': {
+        const sectionChildren = compileChildren(child.children, generateId(parentId, cd.name), insideEach);
+        nodes.push(mapSection(cd, sectionChildren, parentId));
+        break;
+      }
+
+      case 'search':
+        nodes.push(mapSearch(cd, parentId, childIndex++));
+        break;
+
+      case 'navigation':
+        nodes.push(mapNavigation(cd, insideEach, parentId, childIndex++));
+        break;
+
+      case 'pages':
+        nodes.push(mapPages(parentId, childIndex++));
+        break;
+
+      case 'grouping':
+        // grouping affects data source rather than creating a node
+        // but we record it as a node for structural completeness
+        nodes.push({
+          id: generateId(parentId, 'group', cd.collection),
+          config: {
+            groupBy: snakeCase(cd.key),
+            collection: cd.collection,
+          },
+          children: compileChildren(child.children, generateId(parentId, 'group', cd.collection), insideEach),
+        });
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  return nodes;
+}