@mmapp/player-core 0.1.0-alpha.1

package/src/dsl/lexer.ts

@@ -0,0 +1,579 @@
+/**
+ * DSL Lexer — line-level tokenizer for the noun-first DSL.
+ *
+ * Each line is classified independently based on pattern matching.
+ * Indentation is measured as the number of leading spaces (2-space indent).
+ */
+
+import type {
+  LineToken,
+  LineData,
+  Emphasis,
+  Constraint,
+} from './types';
+
+// =============================================================================
+// Section keywords (bare nouns that start structural blocks)
+// =============================================================================
+
+const SECTION_KEYWORDS = new Set([
+  'things', 'paths', 'levels', 'numbers', 'tabs',
+  'controls', 'overlay', 'actions',
+]);
+
+// =============================================================================
+// Qualifier patterns
+// =============================================================================
+
+const QUALIFIER_PATTERNS: Array<{
+  pattern: RegExp;
+  kind: 'order' | 'searchable' | 'filterable' | 'pagination';
+}> = [
+  { pattern: /^(\w[\w\s]*)\s+first$/, kind: 'order' },
+  { pattern: /^searchable\s+by\s+(.+)$/, kind: 'searchable' },
+  { pattern: /^filterable\s+by\s+(.+)$/, kind: 'filterable' },
+  { pattern: /^(\d+)\s+at\s+a\s+time$/, kind: 'pagination' },
+];
+
+// =============================================================================
+// Known pre-type adjectives
+// =============================================================================
+
+const TYPE_ADJECTIVES = new Set([
+  'required', 'unique', 'computed', 'non-negative', 'positive',
+  'negative', 'lowercase', 'uppercase', 'optional', 'readonly',
+]);
+
+// =============================================================================
+// Known base types (for field definitions)
+// =============================================================================
+
+const FIELD_TYPES = new Set([
+  'text', 'number', 'integer', 'time', 'rich text', 'choice',
+]);
+
+// =============================================================================
+// Content roles (for display, NOT field definitions)
+// =============================================================================
+
+const CONTENT_ROLES = new Set([
+  'tag', 'card', 'progress', 'meter', 'slider', 'timeline', 'image',
+]);
+
+// =============================================================================
+// Pronouns that start content lines
+// =============================================================================
+
+const PRONOUNS = new Set(['its', 'my', 'the', 'this', 'these']);
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * Tokenize a full DSL source string into line tokens.
+ */
+export function tokenize(source: string): LineToken[] {
+  const rawLines = source.split('\n');
+  return rawLines.map((raw, i) => tokenizeLine(raw, i + 1));
+}
+
+/**
+ * Tokenize a single line of DSL source.
+ */
+export function tokenizeLine(raw: string, lineNumber: number = 1): LineToken {
+  const indent = measureIndent(raw);
+  const trimmed = raw.trim();
+  const data = classifyLine(trimmed);
+  return { indent, lineNumber, raw, data };
+}
+
+// =============================================================================
+// Indentation
+// =============================================================================
+
+function measureIndent(line: string): number {
+  let count = 0;
+  for (const ch of line) {
+    if (ch === ' ') count++;
+    else if (ch === '\t') count += 2;
+    else break;
+  }
+  return count;
+}
+
+// =============================================================================
+// Line Classification
+// =============================================================================
+
+function classifyLine(trimmed: string): LineData {
+  // Blank
+  if (trimmed === '') return { type: 'blank' };
+
+  // Comment
+  if (trimmed.startsWith('#')) {
+    return { type: 'comment', text: trimmed.slice(1).trim() };
+  }
+
+  // Pages (exact keyword)
+  if (trimmed === 'pages') return { type: 'pages' };
+
+  // Section keywords
+  if (SECTION_KEYWORDS.has(trimmed)) {
+    return { type: 'section', name: trimmed };
+  }
+
+  // Tagged
+  const taggedMatch = trimmed.match(/^tagged:\s*(.+)$/);
+  if (taggedMatch) {
+    return {
+      type: 'tagged',
+      tags: taggedMatch[1].split(',').map(t => t.trim()),
+    };
+  }
+
+  // Path mapping: /path → view (context)
+  const pathMappingMatch = trimmed.match(
+    /^(\/[\w\/:.-]+)\s*→\s*([\w\s]+?)(?:\s*\((\w+)\))?$/
+  );
+  if (pathMappingMatch) {
+    return {
+      type: 'path_mapping',
+      path: pathMappingMatch[1],
+      view: pathMappingMatch[2].trim(),
+      context: pathMappingMatch[3],
+    };
+  }
+
+  // Level definition: N: "name", from N xp
+  const levelMatch = trimmed.match(
+    /^(\d+):\s*"([^"]+)",\s*from\s+(\d+)\s+xp$/
+  );
+  if (levelMatch) {
+    return {
+      type: 'level_def',
+      level: parseInt(levelMatch[1], 10),
+      title: levelMatch[2],
+      fromXp: parseInt(levelMatch[3], 10),
+    };
+  }
+
+  // Starts at
+  const startsAtMatch = trimmed.match(/^starts\s+at\s+(.+)$/);
+  if (startsAtMatch) {
+    return { type: 'starts_at', state: startsAtMatch[1].trim() };
+  }
+
+  // Transition: can verb → state [, guard]
+  const transitionMatch = trimmed.match(
+    /^can\s+(.+?)\s*→\s*(.+?)(?:,\s*(.+))?$/
+  );
+  if (transitionMatch) {
+    return {
+      type: 'transition',
+      verb: transitionMatch[1].trim(),
+      target: transitionMatch[2].trim(),
+      guard: transitionMatch[3]?.trim(),
+    };
+  }
+
+  // When clause
+  if (trimmed.startsWith('when ') || trimmed === 'when') {
+    return { type: 'when', condition: trimmed.slice(5).trim() };
+  }
+
+  // Set action: set field = expr
+  const setMatch = trimmed.match(/^set\s+(.+?)\s*=\s*(.+)$/);
+  if (setMatch) {
+    return {
+      type: 'set_action',
+      field: setMatch[1].trim(),
+      expression: setMatch[2].trim(),
+    };
+  }
+
+  // Do action: do verb
+  if (trimmed.startsWith('do ')) {
+    return { type: 'do_action', action: trimmed.slice(3).trim() };
+  }
+
+  // Go action: go to path
+  const goMatch = trimmed.match(/^go\s+to\s+(.+)$/);
+  if (goMatch) {
+    return { type: 'go_action', path: goMatch[1].trim() };
+  }
+
+  // Tell action: tell target "message"
+  const tellMatch = trimmed.match(/^tell\s+(.+?)\s+"([^"]+)"$/);
+  if (tellMatch) {
+    return {
+      type: 'tell_action',
+      target: tellMatch[1].trim(),
+      message: tellMatch[2],
+    };
+  }
+
+  // Show action: show content [briefly]
+  const showMatch = trimmed.match(/^show\s+(.+?)(?:\s+(briefly))?$/);
+  if (showMatch) {
+    return {
+      type: 'show_action',
+      content: showMatch[1].trim(),
+      modifier: showMatch[2],
+    };
+  }
+
+  // Search: search target
+  if (trimmed.startsWith('search ')) {
+    return { type: 'search', target: trimmed.slice(7).trim() };
+  }
+
+  // Each/iteration: each subject [as role] [, emphasis]
+  const eachMatch = trimmed.match(
+    /^each\s+(.+?)(?:\s+as\s+([\w\s]+?))?(?:,\s*(big|small))?$/
+  );
+  if (eachMatch) {
+    return {
+      type: 'iteration',
+      subject: eachMatch[1].trim(),
+      role: eachMatch[2]?.trim(),
+      emphasis: eachMatch[3] as Emphasis | undefined,
+    };
+  }
+
+  // Qualifier patterns (newest first, searchable by, etc.)
+  for (const { pattern, kind } of QUALIFIER_PATTERNS) {
+    const qMatch = trimmed.match(pattern);
+    if (qMatch) {
+      return { type: 'qualifier', kind, value: qMatch[1] ?? trimmed };
+    }
+  }
+
+  // Space/thing declaration: name @version
+  const versionedDeclMatch = trimmed.match(
+    /^(?:a\s+)?(.+?)\s+@(\d+\.\d+\.\d+)$/
+  );
+  if (versionedDeclMatch) {
+    const hasPrefix = trimmed.startsWith('a ');
+    const name = versionedDeclMatch[1].replace(/^a\s+/, '').trim();
+    if (hasPrefix) {
+      return { type: 'thing_decl', name, version: versionedDeclMatch[2] };
+    }
+    return { type: 'space_decl', name, version: versionedDeclMatch[2] };
+  }
+
+  // Fragment definition: a name: (ends with colon)
+  const fragmentMatch = trimmed.match(/^a\s+(.+):$/);
+  if (fragmentMatch) {
+    return { type: 'fragment_def', name: fragmentMatch[1].trim() };
+  }
+
+  // Thing reference in 'things' section: [a] name (kind)
+  const thingRefMatch = trimmed.match(/^(?:a\s+)?(.+?)\s*\((\w+)\)$/);
+  if (thingRefMatch) {
+    return {
+      type: 'thing_ref',
+      name: thingRefMatch[1].trim(),
+      kind: thingRefMatch[2],
+    };
+  }
+
+  // String literal: "text" [, emphasis]
+  const stringLitMatch = trimmed.match(
+    /^"([^"]+)"(?:,\s*(big|small))?$/
+  );
+  if (stringLitMatch) {
+    return {
+      type: 'string_literal',
+      text: stringLitMatch[1],
+      emphasis: stringLitMatch[2] as Emphasis | undefined,
+    };
+  }
+
+  // Navigation: trigger → path (tap, click, label)
+  const navMatch = trimmed.match(/^(.+?)\s*→\s*(.+)$/);
+  if (navMatch) {
+    return {
+      type: 'navigation',
+      trigger: navMatch[1].trim(),
+      target: navMatch[2].trim(),
+    };
+  }
+
+  // Data source: name from source [, qualifier] [for scope]
+  // Must come before content/field_def since both can start with pronouns
+  const dataSourceResult = tryParseDataSource(trimmed);
+  if (dataSourceResult) return dataSourceResult;
+
+  // Content display: pronoun field [, emphasis] [as role] [with "label"]
+  // Must come before field_def since both use "as"
+  const contentResult = tryParseContent(trimmed);
+  if (contentResult) return contentResult;
+
+  // Field definition: name as [adj]* type [, constraint]*
+  // Only matches bare nouns (not pronouns) with known field types
+  const fieldResult = tryParseFieldDef(trimmed);
+  if (fieldResult) return fieldResult;
+
+  // Grouping: collection by key
+  const groupMatch = trimmed.match(/^(.+?)\s+by\s+(.+)$/);
+  if (groupMatch) {
+    return {
+      type: 'grouping',
+      collection: groupMatch[1].trim(),
+      key: groupMatch[2].trim(),
+    };
+  }
+
+  // State declaration: name [, final]
+  const stateResult = tryParseStateDef(trimmed);
+  if (stateResult) return stateResult;
+
+  return { type: 'unknown', text: trimmed };
+}
+
+// =============================================================================
+// Utilities
+// =============================================================================
+
+/**
+ * Split a string on commas, but not inside [...] brackets.
+ */
+function splitOutsideBrackets(str: string): string[] {
+  const parts: string[] = [];
+  let current = '';
+  let depth = 0;
+  for (const ch of str) {
+    if (ch === '[') depth++;
+    else if (ch === ']') depth--;
+
+    if (ch === ',' && depth === 0) {
+      parts.push(current.trim());
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+
+// =============================================================================
+// Complex parsers
+// =============================================================================
+
+function tryParseFieldDef(trimmed: string): (FieldDefData & { type: 'field_def' }) | null {
+  // Pattern: name as [adj]* type [, constraint]*
+  const asMatch = trimmed.match(/^(.+?)\s+as\s+(.+)$/);
+  if (!asMatch) return null;
+
+  const name = asMatch[1].trim();
+  const rest = asMatch[2].trim();
+
+  // Reject if name starts with a pronoun — those are content, not field defs
+  const firstWord = name.split(/\s+/)[0];
+  if (PRONOUNS.has(firstWord)) return null;
+
+  // Reject if "as" is followed by a quoted string — that's a label (content)
+  if (rest.startsWith('"')) return null;
+
+  // Split on commas, but not inside brackets
+  const parts = splitOutsideBrackets(rest);
+  const typeSpec = parts[0];
+  const constraintParts = parts.slice(1);
+
+  // Parse type spec: [adj]* type
+  const typeWords = typeSpec.split(/\s+/);
+  const adjectives: string[] = [];
+  let baseType = '';
+
+  // Check for "choice of [...]"
+  const choiceMatch = typeSpec.match(/^(.+?\s+)?choice\s+of\s+\[(.+)\]$/);
+  if (choiceMatch) {
+    const prefix = choiceMatch[1]?.trim() ?? '';
+    if (prefix) {
+      for (const w of prefix.split(/\s+/)) {
+        if (TYPE_ADJECTIVES.has(w)) adjectives.push(w);
+      }
+    }
+    baseType = `choice of [${choiceMatch[2]}]`;
+  } else {
+    // Walk words: adjectives before the type, type is the rest
+    let i = 0;
+    while (i < typeWords.length && TYPE_ADJECTIVES.has(typeWords[i])) {
+      adjectives.push(typeWords[i]);
+      i++;
+    }
+    // Handle multi-word types like "rich text"
+    baseType = typeWords.slice(i).join(' ');
+  }
+
+  if (!baseType) return null;
+
+  // Only classify as field_def if the base type is a known FIELD type (not a content role)
+  // Content roles (tag, card, meter, etc.) are handled by tryParseContent
+  const knownFieldType = FIELD_TYPES.has(baseType) ||
+    baseType.startsWith('choice of') ||
+    adjectives.length > 0;
+
+  if (!knownFieldType) return null;
+
+  // If base type is a content role and no adjectives, this is content not a field
+  if (CONTENT_ROLES.has(baseType) && adjectives.length === 0) return null;
+
+  // Parse constraints
+  const constraints: Constraint[] = [];
+  for (const cp of constraintParts) {
+    const constraint = parseConstraint(cp);
+    if (constraint) constraints.push(constraint);
+  }
+
+  return {
+    type: 'field_def',
+    name,
+    adjectives,
+    baseType,
+    constraints,
+  };
+}
+
+function parseConstraint(text: string): Constraint | null {
+  const trimmed = text.trim();
+
+  // max N
+  const maxMatch = trimmed.match(/^max\s+(\d+)$/);
+  if (maxMatch) return { kind: 'max', value: parseInt(maxMatch[1], 10) };
+
+  // min N
+  const minMatch = trimmed.match(/^min\s+(\d+)$/);
+  if (minMatch) return { kind: 'min', value: parseInt(minMatch[1], 10) };
+
+  // default "value" or default value
+  const defaultMatch = trimmed.match(/^default\s+(.+)$/);
+  if (defaultMatch) {
+    const val = defaultMatch[1].trim();
+    const num = Number(val);
+    return { kind: 'default', value: isNaN(num) ? val.replace(/^"(.*)"$/, '$1') : num };
+  }
+
+  // between X and Y
+  const betweenMatch = trimmed.match(/^between\s+(\d+)\s+and\s+(\d+)$/);
+  if (betweenMatch) {
+    return {
+      kind: 'between',
+      value: parseInt(betweenMatch[1], 10),
+      value2: parseInt(betweenMatch[2], 10),
+    };
+  }
+
+  // unique
+  if (trimmed === 'unique') return { kind: 'unique', value: true };
+
+  return null;
+}
+
+function tryParseContent(trimmed: string): (ContentData & { type: 'content' }) | null {
+  // Patterns:
+  //   its field [, emphasis] [as role] [with "label"]
+  //   my field [, emphasis] [as role] [with "label"]
+  //   the field [, emphasis] [as role] [with "label"]
+  //   field.name [, emphasis]
+
+  const pronounMatch = trimmed.match(
+    /^(its|my|the|this)\s+(.+?)(?:,\s*(big|small))?(?:\s+as\s+(.+?))?(?:\s+with\s+"([^"]+)")?$/
+  );
+  if (pronounMatch) {
+    return {
+      type: 'content',
+      pronoun: pronounMatch[1],
+      field: pronounMatch[2].trim(),
+      emphasis: pronounMatch[3] as Emphasis | undefined,
+      role: pronounMatch[4]?.trim(),
+      label: pronounMatch[5],
+    };
+  }
+
+  // Also handle: field as "Label" (without pronoun, in numbers sections)
+  const labelMatch = trimmed.match(
+    /^([\w\s]+?)\s+as\s+"([^"]+)"(?:\s+with\s+"([^"]+)")?$/
+  );
+  if (labelMatch) {
+    return {
+      type: 'content',
+      field: labelMatch[1].trim(),
+      label: labelMatch[2],
+    };
+  }
+
+  return null;
+}
+
+function tryParseDataSource(trimmed: string): (LineData & { type: 'data_source' }) | null {
+  // Patterns:
+  //   my projects from project
+  //   my projects from project, live
+  //   my recent from project, 5 newest
+  //   this project from project
+  //   its tasks from task for this project
+  //   my media from media-library for this project
+
+  const fromMatch = trimmed.match(
+    /^(.+?)\s+from\s+([\w-]+)(?:,\s*(.+?))?(?:\s+for\s+(.+))?$/
+  );
+  if (!fromMatch) return null;
+
+  const alias = fromMatch[1].trim();
+  const source = fromMatch[2].trim();
+  const qualifierOrLive = fromMatch[3]?.trim();
+  const scope = fromMatch[4]?.trim();
+
+  return {
+    type: 'data_source',
+    alias,
+    source,
+    isLive: qualifierOrLive === 'live',
+    qualifier: qualifierOrLive !== 'live' ? qualifierOrLive : undefined,
+    scope,
+  };
+}
+
+function tryParseStateDef(trimmed: string): (LineData & { type: 'state_decl' }) | null {
+  // State names are bare identifiers, possibly multi-word, optionally with ", final"
+  // Must NOT start with structural keywords
+  const nonStateStarters = [
+    'a ', 'an ', 'the ', 'my ', 'its ', 'this ',
+    'each ', 'when ', 'can ', 'set ', 'do ', 'go ',
+    'tell ', 'show ', 'search ', 'from ', 'emit ',
+    'tagged', 'starts ', 'follow ', 'facing ', 'playing ',
+    'volume ', 'playback ',
+  ];
+
+  for (const prefix of nonStateStarters) {
+    if (trimmed.startsWith(prefix)) return null;
+  }
+
+  // Reject if it contains "→" (navigation)
+  if (trimmed.includes('→')) return null;
+
+  // Reject if it contains " from " (data source)
+  if (trimmed.includes(' from ')) return null;
+
+  // Reject if it contains " by " (grouping)
+  if (trimmed.includes(' by ')) return null;
+
+  // Reject if it contains " as " (content/field)
+  if (trimmed.includes(' as ')) return null;
+
+  // Check for ", final"
+  const finalMatch = trimmed.match(/^(.+?),\s*final$/);
+  if (finalMatch) {
+    return { type: 'state_decl', name: finalMatch[1].trim(), isFinal: true };
+  }
+
+  // Plain state: must be simple identifier(s)
+  if (/^[a-z][\w\s]*$/i.test(trimmed) && !SECTION_KEYWORDS.has(trimmed) && trimmed !== 'pages') {
+    return { type: 'state_decl', name: trimmed, isFinal: false };
+  }
+
+  return null;
+}

package/src/dsl/parser.ts

@@ -0,0 +1,115 @@
+/**
+ * DSL Parser — builds a tree from tokenized lines.
+ *
+ * Takes the flat list of LineTokens from the lexer and produces
+ * a nested ASTNode tree based on indentation levels.
+ */
+
+import type { LineToken, ASTNode, ParseResult, ParseError } from './types';
+
+/**
+ * Parse tokenized lines into an AST tree.
+ * Indentation defines parent-child nesting.
+ */
+export function parse(tokens: LineToken[]): ParseResult {
+  const errors: ParseError[] = [];
+  const roots: ASTNode[] = [];
+
+  // Filter out blanks and comments for tree building
+  const meaningful = tokens.filter(
+    t => t.data.type !== 'blank' && t.data.type !== 'comment'
+  );
+
+  if (meaningful.length === 0) {
+    return { nodes: [], errors };
+  }
+
+  // Stack-based tree building
+  // Each entry: { node, indent }
+  const stack: Array<{ node: ASTNode; indent: number }> = [];
+
+  for (const token of meaningful) {
+    const node: ASTNode = { token, children: [] };
+
+    // Pop stack until we find a parent with lower indent
+    while (stack.length > 0 && stack[stack.length - 1].indent >= token.indent) {
+      stack.pop();
+    }
+
+    if (stack.length === 0) {
+      // Root level
+      roots.push(node);
+    } else {
+      // Child of the top of stack
+      stack[stack.length - 1].node.children.push(node);
+    }
+
+    stack.push({ node, indent: token.indent });
+  }
+
+  // Validate structural rules
+  validateStructure(roots, errors);
+
+  return { nodes: roots, errors };
+}
+
+/**
+ * Validate structural rules of the parsed tree.
+ */
+function validateStructure(nodes: ASTNode[], errors: ParseError[]): void {
+  for (const node of nodes) {
+    const { data } = node.token;
+
+    // Transitions must be inside states
+    if (data.type === 'transition' && !isInsideState(node, nodes)) {
+      // This is a soft warning — transitions at root level are unusual
+    }
+
+    // Set actions must be inside when clauses
+    if (data.type === 'set_action' && !hasAncestorType(node, 'when', nodes)) {
+      // Soft warning
+    }
+
+    // Recurse
+    if (node.children.length > 0) {
+      validateStructure(node.children, errors);
+    }
+  }
+}
+
+function isInsideState(_node: ASTNode, _roots: ASTNode[]): boolean {
+  // Simplified check — full implementation would trace parent chain
+  return true;
+}
+
+function hasAncestorType(_node: ASTNode, _type: string, _roots: ASTNode[]): boolean {
+  // Simplified check
+  return true;
+}
+
+/**
+ * Walk all nodes in the tree, depth-first.
+ */
+export function walkTree(
+  nodes: ASTNode[],
+  visitor: (node: ASTNode, depth: number) => void,
+  depth: number = 0,
+): void {
+  for (const node of nodes) {
+    visitor(node, depth);
+    walkTree(node.children, visitor, depth + 1);
+  }
+}
+
+/**
+ * Find all nodes of a given type in the tree.
+ */
+export function findByType(nodes: ASTNode[], type: string): ASTNode[] {
+  const results: ASTNode[] = [];
+  walkTree(nodes, (node) => {
+    if (node.token.data.type === type) {
+      results.push(node);
+    }
+  });
+  return results;
+}