@higher.archi/boe 1.0.0

package/src/core/parser/parser/expression.parser.ts

@@ -0,0 +1,308 @@
+import type { Token, OperatorTable } from '../types';
+import type { ParserState, ParsedOperand } from './types';
+import { SyntaxError } from '../errors';
+import { parsePrimary } from './primary.parser';
+
+/**
+ * Pratt Parser for Expressions
+ *
+ * This parser uses Vaughan Pratt's "top-down operator precedence" algorithm.
+ * It's elegant and handles operator precedence and associativity naturally.
+ *
+ * Key Insight:
+ * ────────────
+ * Each operator has a "binding power" (precedence). We parse the left side,
+ * then loop: if the next operator binds tighter than our current minimum,
+ * we consume it and recursively parse the right side.
+ *
+ * This creates the correct parse tree without complex grammar rules.
+ *
+ * Example: "$a + $b * $c"
+ *   1. Parse $a (primary)
+ *   2. See '+' (precedence 5), consume it
+ *   3. Parse right side with minPrecedence=6 (to get tighter ops)
+ *   4. That parses "$b * $c" as ['multiply', '$b', '$c']
+ *   5. Result: ['add', '$a', ['multiply', '$b', '$c']]
+ *
+ * Multi-Value Shorthand:
+ * ─────────────────────
+ * Special handling for patterns like: $status == 'a' or 'b' or 'c'
+ * This becomes: ['in', '$status', ['a', 'b', 'c']]
+ *
+ * Detection: When we see '==' or '!=' followed by 'or' with bare literals.
+ */
+
+/**
+ * Main parsing function - entry point for the Pratt parser.
+ */
+export function parseExpressionFromTokens(
+  tokens: Token[],
+  operatorTable: OperatorTable,
+  input: string
+): any {
+  const state: ParserState = {
+    tokens,
+    position: 0,
+    operatorTable,
+    input
+  };
+
+  const result = parseExpr(state, 0);
+
+  // Ensure we consumed all tokens (except EOF)
+  const remaining = peek(state);
+  if (remaining.type !== 'EOF') {
+    throw new SyntaxError(
+      `Unexpected token after expression: ${remaining.type}`,
+      remaining.position,
+      input
+    );
+  }
+
+  return result;
+}
+
+/**
+ * Recursive expression parser with precedence climbing.
+ *
+ * @param state - Parser state
+ * @param minPrecedence - Minimum precedence to parse (higher = tighter binding)
+ */
+function parseExpr(state: ParserState, minPrecedence: number): ParsedOperand {
+  // Parse the left-hand side (primary expression)
+  let left = parsePrimary(state, parseExpr);
+
+  // Loop while we see operators that bind at least as tight as minPrecedence
+  while (true) {
+    const token = peek(state);
+
+    // Stop if not an operator
+    if (token.type !== 'OPERATOR') {
+      break;
+    }
+
+    const opInfo = state.operatorTable.get(token.value);
+    if (!opInfo) {
+      // Unknown operator - stop here and let caller handle
+      break;
+    }
+
+    // Stop if operator doesn't bind tight enough
+    if (opInfo.precedence < minPrecedence) {
+      break;
+    }
+
+    // ─────────────────────────────────────────────────────────────────
+    // Multi-Value Shorthand Detection
+    // ─────────────────────────────────────────────────────────────────
+    // Check for: $x == 'a' or 'b' or 'c' pattern
+    // This should become: ['in', '$x', ['a', 'b', 'c']]
+
+    if (isComparisonOp(opInfo.canonical)) {
+      advance(state); // consume comparison operator
+      const firstValue = parsePrimary(state, parseExpr);
+
+      // Check for multi-value pattern: literal followed by 'or' and more literals
+      const multiValues = tryParseMultiValueShorthand(state, firstValue);
+
+      if (multiValues) {
+        // Transform to 'in' or 'notIn'
+        const inOp =
+          opInfo.canonical === 'notEquals' ? 'notIn' : 'in';
+        left = [inOp, left, multiValues];
+        continue;
+      }
+
+      // Not a multi-value pattern - normal binary operation
+      left = [opInfo.canonical, left, firstValue];
+      continue;
+    }
+
+    // ─────────────────────────────────────────────────────────────────
+    // Variadic Flattening (and, or)
+    // ─────────────────────────────────────────────────────────────────
+    // Multiple 'and'/'or' at same level should flatten:
+    // $a and $b and $c → ['and', '$a', '$b', '$c'] (not nested)
+
+    if (opInfo.arity === 'variadic') {
+      advance(state); // consume operator
+
+      // Parse the right side with same precedence (left associative)
+      const right = parseExpr(state, opInfo.precedence + 1);
+
+      // Collect all operands at same level
+      const operands: ParsedOperand[] = [];
+
+      // Flatten left if it's the same operator
+      if (Array.isArray(left) && left[0] === opInfo.canonical) {
+        operands.push(...left.slice(1));
+      } else {
+        operands.push(left);
+      }
+
+      // Flatten right if it's the same operator
+      if (Array.isArray(right) && right[0] === opInfo.canonical) {
+        operands.push(...right.slice(1));
+      } else {
+        operands.push(right);
+      }
+
+      left = [opInfo.canonical, ...operands];
+      continue;
+    }
+
+    // ─────────────────────────────────────────────────────────────────
+    // Normal Binary Operators
+    // ─────────────────────────────────────────────────────────────────
+
+    advance(state); // consume operator
+
+    // Calculate next precedence based on associativity
+    // Left-associative: next must be higher to steal operand
+    // Right-associative: next can be same or higher
+    const nextMinPrecedence =
+      opInfo.associativity === 'right'
+        ? opInfo.precedence
+        : opInfo.precedence + 1;
+
+    const right = parseExpr(state, nextMinPrecedence);
+
+    left = [opInfo.canonical, left, right];
+  }
+
+  return left;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Multi-Value Shorthand Handling
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Checks if an operator is a comparison operator that can use multi-value shorthand.
+ * Only 'equals' and 'notEquals' support this pattern.
+ */
+function isComparisonOp(canonical: string): boolean {
+  return canonical === 'equals' || canonical === 'notEquals';
+}
+
+/**
+ * Checks if a value is a "bare literal" (not a property ref or expression).
+ * Used to detect multi-value shorthand patterns.
+ */
+function isBareLiteral(value: ParsedOperand): boolean {
+  if (value === null || typeof value === 'boolean' || typeof value === 'number') {
+    return true;
+  }
+  if (typeof value === 'string') {
+    // Property refs start with $
+    return !value.startsWith('$');
+  }
+  return false;
+}
+
+/**
+ * Tries to parse multi-value shorthand after an equals comparison.
+ *
+ * Pattern: == literal or literal or literal ...
+ *
+ * Returns array of values if pattern matches, null otherwise.
+ *
+ * Example: $status == 'a' or 'b' or 'c'
+ *   - firstValue: 'a'
+ *   - Sees 'or' followed by bare literal 'b'
+ *   - Collects: ['a', 'b', 'c']
+ *   - Returns: ['a', 'b', 'c']
+ *
+ * NOT a match: $a == 5 or $b == 6
+ *   - firstValue: 5
+ *   - Sees 'or' followed by property ref $b (not bare literal)
+ *   - Returns: null (normal OR handling takes over)
+ */
+function tryParseMultiValueShorthand(
+  state: ParserState,
+  firstValue: ParsedOperand
+): ParsedOperand[] | null {
+  // First value must be a bare literal
+  if (!isBareLiteral(firstValue)) {
+    return null;
+  }
+
+  // Check if followed by 'or'
+  const token = peek(state);
+  if (token.type !== 'OPERATOR') {
+    return null;
+  }
+
+  const opInfo = state.operatorTable.get(token.value);
+  if (!opInfo || opInfo.canonical !== 'or') {
+    return null;
+  }
+
+  // Peek ahead to see if the next primary is a bare literal
+  // We need to be careful here - don't consume tokens yet
+
+  // Save position for potential backtrack
+  const savedPosition = state.position;
+
+  // Consume 'or' and check next primary
+  advance(state);
+  const nextValue = parsePrimary(state, parseExpr);
+
+  if (!isBareLiteral(nextValue)) {
+    // Not a multi-value pattern - restore position
+    state.position = savedPosition;
+    return null;
+  }
+
+  // It's a multi-value pattern! Collect all values
+  const values: ParsedOperand[] = [firstValue, nextValue];
+
+  // Continue collecting while we see 'or' followed by bare literals
+  while (true) {
+    const orToken = peek(state);
+    if (orToken.type !== 'OPERATOR') {
+      break;
+    }
+
+    const orInfo = state.operatorTable.get(orToken.value);
+    if (!orInfo || orInfo.canonical !== 'or') {
+      break;
+    }
+
+    // Peek at what comes after 'or'
+    const posBeforeOr = state.position;
+    advance(state); // consume 'or'
+
+    const value = parsePrimary(state, parseExpr);
+
+    if (!isBareLiteral(value)) {
+      // Not a bare literal - backtrack and stop
+      state.position = posBeforeOr;
+      break;
+    }
+
+    values.push(value);
+  }
+
+  return values;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Helper Functions
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Returns the current token without advancing.
+ */
+function peek(state: ParserState): Token {
+  return state.tokens[state.position];
+}
+
+/**
+ * Advances to the next token.
+ */
+function advance(state: ParserState): void {
+  if (state.position < state.tokens.length - 1) {
+    state.position++;
+  }
+}

package/src/core/parser/parser/function.parser.ts

@@ -0,0 +1,113 @@
+import type { Token } from '../types';
+import type { ParserState, ParsedOperand } from './types';
+import { SyntaxError } from '../errors';
+
+/**
+ * Parses function call syntax: functionName(arg1, arg2, ...)
+ *
+ * Function calls are used for both:
+ *   1. Operator functions: gt($a, 5), contains($str, "test")
+ *   2. Utility functions: daysAgo(7), now()
+ *
+ * Special handling for nullary functions (no arguments):
+ * ────────────────────────────────────────────────────────
+ * Some functions like now(), today(), yesterday() take no arguments.
+ * But our operator system expects at least one operand.
+ * So we output: now() → ['now', 0]
+ *
+ * The 0 is a dummy argument that the operator ignores.
+ * This maintains consistency with the S-expression format.
+ *
+ * Examples:
+ *   gt($a, 5)           → ['greaterThan', '$a', 5]
+ *   contains($x, "y")   → ['contains', '$x', 'y']
+ *   daysAgo(7)          → ['daysAgo', 7]
+ *   now()               → ['now', 0]
+ *   add($a, $b, $c)     → ['add', '$a', '$b', '$c']
+ */
+export function parseFunctionCall(
+  state: ParserState,
+  parseExpression: (state: ParserState, minPrecedence: number) => ParsedOperand
+): any[] {
+  const funcToken = peek(state);
+
+  if (funcToken.type !== 'FUNCTION') {
+    throw new SyntaxError(
+      `Expected function name but found ${funcToken.type}`,
+      funcToken.position,
+      state.input
+    );
+  }
+
+  const funcName = funcToken.value;
+  advance(state); // consume function name
+
+  // Get canonical name - prefer from token (set by tokenizer) or look up in table
+  // The tokenizer sets funcToken.canonical for known operators used as functions
+  const canonicalName = funcToken.canonical || funcName;
+
+  // Expect opening parenthesis
+  const openParen = peek(state);
+  if (openParen.type !== 'LPAREN') {
+    throw new SyntaxError(
+      `Expected '(' after function name '${funcName}'`,
+      openParen.position,
+      state.input
+    );
+  }
+  advance(state); // consume '('
+
+  // Parse arguments
+  const args: ParsedOperand[] = [];
+
+  // Check for empty argument list: func()
+  if (peek(state).type !== 'RPAREN') {
+    // Parse first argument
+    args.push(parseExpression(state, 0));
+
+    // Parse remaining arguments (comma-separated)
+    while (peek(state).type === 'COMMA') {
+      advance(state); // consume ','
+      args.push(parseExpression(state, 0));
+    }
+  }
+
+  // Expect closing parenthesis
+  const closeParen = peek(state);
+  if (closeParen.type !== 'RPAREN') {
+    throw new SyntaxError(
+      `Expected ')' after function arguments`,
+      closeParen.position,
+      state.input
+    );
+  }
+  advance(state); // consume ')'
+
+  // Handle nullary functions - add dummy argument
+  // This ensures consistent S-expression format: ['now', 0] not ['now']
+  if (args.length === 0) {
+    return [canonicalName, 0];
+  }
+
+  return [canonicalName, ...args];
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Helper Functions
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Returns the current token without advancing.
+ */
+function peek(state: ParserState): Token {
+  return state.tokens[state.position];
+}
+
+/**
+ * Advances to the next token.
+ */
+function advance(state: ParserState): void {
+  if (state.position < state.tokens.length - 1) {
+    state.position++;
+  }
+}

package/src/core/parser/parser/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Parser Module
+ *
+ * Provides the Pratt parser implementation for parsing tokenized
+ * expressions into S-expression condition arrays.
+ *
+ * The parser handles:
+ *   - Operator precedence (*, / before +, -)
+ *   - Operator associativity (left vs right)
+ *   - Parenthesized grouping
+ *   - Function calls
+ *   - Multi-value shorthand ($x == 'a' or 'b' → in)
+ *   - Variadic flattening (a and b and c → ['and', a, b, c])
+ */
+
+export { parseExpressionFromTokens } from './expression.parser';
+export { parsePrimary } from './primary.parser';
+export { parseFunctionCall } from './function.parser';
+
+export type { ParserState, ParsedCondition, ParsedOperand } from './types';

package/src/core/parser/parser/primary.parser.ts

@@ -0,0 +1,149 @@
+import type { Token } from '../types';
+import type { ParserState, ParsedOperand } from './types';
+import { SyntaxError } from '../errors';
+import { parseFunctionCall } from './function.parser';
+
+/**
+ * Parses primary expressions - the "atoms" of an expression.
+ *
+ * Primary expressions are the highest precedence elements:
+ *   - Literals: numbers (42, 3.14, -5, +5), strings, booleans, null
+ *   - Percentages: 50% → 0.5, +300% → 3.0, -50% → -0.5
+ *   - Property references: $age, $user.name
+ *   - Parenthesized expressions: (...)
+ *   - Function calls: fn(arg1, arg2)
+ *   - Unary prefix operators: not, !
+ *
+ * This function is called by the expression parser when it needs
+ * the left-hand side of an expression or after consuming an operator.
+ */
+export function parsePrimary(
+  state: ParserState,
+  parseExpression: (state: ParserState, minPrecedence: number) => ParsedOperand
+): ParsedOperand {
+  const token = peek(state);
+
+  switch (token.type) {
+    // ─────────────────────────────────────────────────────────────────
+    // Literals
+    // ─────────────────────────────────────────────────────────────────
+
+    case 'NUMBER': {
+      advance(state);
+      const numStr = token.value;
+      // Handle percentage literals: 50% → 0.5, +300% → 3.0, -50% → -0.5
+      if (numStr.endsWith('%')) {
+        return parseFloat(numStr) / 100;
+      }
+      return parseFloat(numStr);
+    }
+
+    case 'STRING':
+      advance(state);
+      return token.value;
+
+    case 'BOOLEAN':
+      advance(state);
+      return token.value === 'true';
+
+    case 'NULL':
+      advance(state);
+      return null;
+
+    // ─────────────────────────────────────────────────────────────────
+    // Property References
+    // ─────────────────────────────────────────────────────────────────
+
+    case 'PROPERTY_REF':
+      advance(state);
+      return token.value; // Keep as string: '$age', '$user.name'
+
+    // ─────────────────────────────────────────────────────────────────
+    // Parenthesized Expressions
+    // ─────────────────────────────────────────────────────────────────
+
+    case 'LPAREN': {
+      advance(state); // consume '('
+
+      // Parse the inner expression with minimum precedence (0)
+      // so all operators are included
+      const expr = parseExpression(state, 0);
+
+      // Expect closing parenthesis
+      const closeParen = peek(state);
+      if (closeParen.type !== 'RPAREN') {
+        throw new SyntaxError(
+          `Expected ')' but found ${closeParen.type}`,
+          closeParen.position,
+          state.input
+        );
+      }
+      advance(state); // consume ')'
+
+      return expr;
+    }
+
+    // ─────────────────────────────────────────────────────────────────
+    // Function Calls
+    // ─────────────────────────────────────────────────────────────────
+
+    case 'FUNCTION':
+      return parseFunctionCall(state, parseExpression);
+
+    // ─────────────────────────────────────────────────────────────────
+    // Unary Prefix Operators (not, !)
+    // ─────────────────────────────────────────────────────────────────
+
+    case 'OPERATOR': {
+      const opInfo = state.operatorTable.get(token.value);
+
+      // Check if this is a unary prefix operator
+      if (opInfo && opInfo.arity === 'unary') {
+        advance(state); // consume operator
+
+        // Parse the operand (recursively, to handle chained: not not $x)
+        const operand = parsePrimary(state, parseExpression);
+
+        return [opInfo.canonical, operand];
+      }
+
+      // Not a unary operator - unexpected in primary position
+      throw new SyntaxError(
+        `Unexpected operator '${token.value}' at start of expression`,
+        token.position,
+        state.input
+      );
+    }
+
+    // ─────────────────────────────────────────────────────────────────
+    // Unexpected Token
+    // ─────────────────────────────────────────────────────────────────
+
+    default:
+      throw new SyntaxError(
+        `Unexpected token ${token.type}: '${token.value}'`,
+        token.position,
+        state.input
+      );
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Helper Functions
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Returns the current token without advancing.
+ */
+function peek(state: ParserState): Token {
+  return state.tokens[state.position];
+}
+
+/**
+ * Advances to the next token.
+ */
+function advance(state: ParserState): void {
+  if (state.position < state.tokens.length - 1) {
+    state.position++;
+  }
+}

package/src/core/parser/parser/types.ts

@@ -0,0 +1,51 @@
+import type { Token, OperatorTable } from '../types';
+
+/**
+ * Internal parser state.
+ *
+ * The parser maintains a position in the token stream and advances
+ * as it consumes tokens. Unlike the scanner (which is immutable),
+ * the parser uses mutable state for simplicity since parsing is
+ * more complex and backtracking is rare.
+ */
+export interface ParserState {
+  /** The token stream from the tokenizer */
+  tokens: Token[];
+
+  /** Current position in the token stream */
+  position: number;
+
+  /** Operator table for precedence and alias lookup */
+  operatorTable: OperatorTable;
+
+  /** Original input string (for error messages) */
+  input: string;
+}
+
+/**
+ * The output from parsing - matches the existing Condition type.
+ *
+ * This is a type alias to make it clear what the parser produces.
+ * The actual type comes from the existing condition types.
+ */
+export type ParsedCondition =
+  | [string, ...any[]] // Operator with operands
+  | string // Property ref
+  | number // Numeric literal
+  | boolean // Boolean literal
+  | null; // Null literal
+
+/**
+ * A parsed operand (value in a condition).
+ *
+ * Operands can be:
+ *   - Property refs: '$age', '$user.name'
+ *   - Literals: 42, "hello", true, null
+ *   - Nested conditions: ['add', '$x', 5]
+ */
+export type ParsedOperand =
+  | string // Property ref or string literal
+  | number // Numeric literal
+  | boolean // Boolean literal
+  | null // Null literal
+  | any[]; // Array literal or nested condition