@xemahq/dsl 0.1.1

package/src/workflow/lib/expression/parser.ts

@@ -0,0 +1,264 @@
+import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+import {
+  type BinaryNode,
+  type ExpressionNode,
+  ExpressionFunction,
+  ExpressionNodeKind,
+  ExpressionRoot,
+  type IdentifierNode,
+  type IndexNode,
+  type LiteralNode,
+  type MemberNode,
+} from './ast';
+import { type Token, TokenKind } from './tokens';
+
+/**
+ * Recursive-descent parser for the Xema expression subset. Grammar is a
+ * closed subset inspired by GitHub Actions' expression language:
+ *
+ *   expression := logicalOr
+ *   logicalOr  := logicalAnd ('||' logicalAnd)*
+ *   logicalAnd := equality  ('&&' equality)*
+ *   equality   := unary (('==' | '!=') unary)*
+ *   unary      := '!' unary | postfix
+ *   postfix    := primary ('.' IDENT | '[' expression ']')*
+ *   primary    := '(' expression ')'
+ *              | literal
+ *              | identifierOrCall
+ *   identifierOrCall := IDENT ('(' argList? ')')?
+ *   argList    := expression (',' expression)*
+ *
+ * Root identifiers must be one of {needs, matrix, inputs, vars, trigger, job}.
+ * Call callees must be one of {fromJSON, toJSON}.
+ */
+export function parseExpression(source: string, tokens: readonly Token[]): ExpressionNode {
+  const parser = new Parser(source, tokens);
+  const node = parser.parseExpression();
+  parser.expect(TokenKind.EOF);
+  return node;
+}
+
+class Parser {
+  private index = 0;
+
+  constructor(
+    private readonly source: string,
+    private readonly tokens: readonly Token[],
+  ) {}
+
+  parseExpression(): ExpressionNode {
+    return this.parseOr();
+  }
+
+  expect(kind: TokenKind): Token {
+    const token = this.peek();
+    if (token.kind !== kind) {
+      throw this.error(
+        `Expected ${kind} but found ${token.kind === TokenKind.EOF ? 'end of expression' : token.kind}`,
+        token.column,
+      );
+    }
+    this.index++;
+    return token;
+  }
+
+  private peek(): Token {
+    const token = this.tokens[this.index];
+    if (!token) {
+      throw this.error('Parser consumed past end of token stream', this.source.length + 1);
+    }
+    return token;
+  }
+
+  private consume(): Token {
+    const token = this.peek();
+    this.index++;
+    return token;
+  }
+
+  private match(kind: TokenKind): boolean {
+    return this.peek().kind === kind;
+  }
+
+  private parseOr(): ExpressionNode {
+    let left = this.parseAnd();
+    while (this.match(TokenKind.OR)) {
+      this.consume();
+      const right = this.parseAnd();
+      left = binary(ExpressionNodeKind.BINARY_OR, left, right);
+    }
+    return left;
+  }
+
+  private parseAnd(): ExpressionNode {
+    let left = this.parseEquality();
+    while (this.match(TokenKind.AND)) {
+      this.consume();
+      const right = this.parseEquality();
+      left = binary(ExpressionNodeKind.BINARY_AND, left, right);
+    }
+    return left;
+  }
+
+  private parseEquality(): ExpressionNode {
+    let left = this.parseUnary();
+    for (;;) {
+      if (this.match(TokenKind.EQ)) {
+        this.consume();
+        const right = this.parseUnary();
+        left = binary(ExpressionNodeKind.BINARY_EQ, left, right);
+      } else if (this.match(TokenKind.NEQ)) {
+        this.consume();
+        const right = this.parseUnary();
+        left = binary(ExpressionNodeKind.BINARY_NEQ, left, right);
+      } else {
+        break;
+      }
+    }
+    return left;
+  }
+
+  private parseUnary(): ExpressionNode {
+    if (this.match(TokenKind.BANG)) {
+      this.consume();
+      const operand = this.parseUnary();
+      return { kind: ExpressionNodeKind.UNARY_NOT, operand };
+    }
+    return this.parsePostfix();
+  }
+
+  private parsePostfix(): ExpressionNode {
+    let node = this.parsePrimary();
+    for (;;) {
+      if (this.match(TokenKind.DOT)) {
+        this.consume();
+        const propertyToken = this.expect(TokenKind.IDENTIFIER);
+        const member: MemberNode = {
+          kind: ExpressionNodeKind.MEMBER,
+          target: node,
+          property: propertyToken.value,
+        };
+        node = member;
+      } else if (this.match(TokenKind.LBRACKET)) {
+        this.consume();
+        const indexExpr = this.parseExpression();
+        this.expect(TokenKind.RBRACKET);
+        const indexNode: IndexNode = {
+          kind: ExpressionNodeKind.INDEX,
+          target: node,
+          index: indexExpr,
+        };
+        node = indexNode;
+      } else {
+        break;
+      }
+    }
+    return node;
+  }
+
+  private parsePrimary(): ExpressionNode {
+    const token = this.peek();
+    switch (token.kind) {
+      case TokenKind.LPAREN: {
+        this.consume();
+        const expr = this.parseExpression();
+        this.expect(TokenKind.RPAREN);
+        return expr;
+      }
+      case TokenKind.NUMBER: {
+        this.consume();
+        const literal: LiteralNode = { kind: ExpressionNodeKind.LITERAL, value: Number(token.value) };
+        return literal;
+      }
+      case TokenKind.STRING: {
+        this.consume();
+        const literal: LiteralNode = { kind: ExpressionNodeKind.LITERAL, value: token.value };
+        return literal;
+      }
+      case TokenKind.BOOLEAN: {
+        this.consume();
+        const literal: LiteralNode = { kind: ExpressionNodeKind.LITERAL, value: token.value === 'true' };
+        return literal;
+      }
+      case TokenKind.NULL: {
+        this.consume();
+        const literal: LiteralNode = { kind: ExpressionNodeKind.LITERAL, value: null };
+        return literal;
+      }
+      case TokenKind.IDENTIFIER: {
+        return this.parseIdentifierOrCall();
+      }
+      default:
+        throw this.error(
+          `Unexpected token '${token.value}' at column ${token.column}`,
+          token.column,
+        );
+    }
+  }
+
+  private parseIdentifierOrCall(): ExpressionNode {
+    const identifierToken = this.expect(TokenKind.IDENTIFIER);
+    const name = identifierToken.value;
+
+    if (this.match(TokenKind.LPAREN)) {
+      this.consume();
+      if (!isExpressionFunction(name)) {
+        throw this.error(
+          `Unknown function '${name}' at column ${identifierToken.column}. Allowed: ${Object.values(ExpressionFunction).join(', ')}.`,
+          identifierToken.column,
+        );
+      }
+      const args: ExpressionNode[] = [];
+      if (!this.match(TokenKind.RPAREN)) {
+        args.push(this.parseExpression());
+        while (this.match(TokenKind.COMMA)) {
+          this.consume();
+          args.push(this.parseExpression());
+        }
+      }
+      this.expect(TokenKind.RPAREN);
+      return {
+        kind: ExpressionNodeKind.CALL,
+        callee: name,
+        args,
+      };
+    }
+
+    // Bare identifier: must be one of the allowed roots.
+    if (!isExpressionRoot(name)) {
+      throw this.error(
+        `Unknown identifier '${name}' at column ${identifierToken.column}. Allowed roots: ${Object.values(ExpressionRoot).join(', ')}.`,
+        identifierToken.column,
+      );
+    }
+    const ident: IdentifierNode = { kind: ExpressionNodeKind.IDENTIFIER, name };
+    return ident;
+  }
+
+  private error(message: string, column: number): WorkflowDslError {
+    return new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `${message} [expression: ${this.source}]`,
+      { expression: this.source, column },
+    );
+  }
+}
+
+function binary(
+  kind: BinaryNode['kind'],
+  left: ExpressionNode,
+  right: ExpressionNode,
+): BinaryNode {
+  return { kind, left, right };
+}
+
+function isExpressionRoot(name: string): name is ExpressionRoot {
+  const roots: readonly string[] = Object.values(ExpressionRoot);
+  return roots.includes(name);
+}
+
+function isExpressionFunction(name: string): name is ExpressionFunction {
+  const fns: readonly string[] = Object.values(ExpressionFunction);
+  return fns.includes(name);
+}

package/src/workflow/lib/expression/template.ts

@@ -0,0 +1,117 @@
+import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+
+/**
+ * Template parsing for fields that explicitly accept partial interpolation
+ * (`literal-text-${{ expression }}-more-text`). Most authored expressions in
+ * the DSL must be fully wrapped — see `interpolation.ts` and the policy on
+ * `with`, `outputs`, `if`, `strategy.dynamic.from`. Concurrency `group` is
+ * the documented exception, so it composes from this primitive instead.
+ *
+ * The parser is deterministic and total: every input string maps to one
+ * sequence of segments. Authoring errors (an open `${{` without a matching
+ * `}}`, an empty body) raise `DSL_EXPRESSION_INVALID` at the position they
+ * occur — never at <root>, never silently coerced.
+ */
+export enum TemplateSegmentKind {
+  Literal = 'literal',
+  Expression = 'expression',
+}
+
+export interface TemplateLiteralSegment {
+  readonly kind: TemplateSegmentKind.Literal;
+  readonly value: string;
+}
+
+export interface TemplateExpressionSegment {
+  readonly kind: TemplateSegmentKind.Expression;
+  readonly source: string;
+  /** Byte offset of the opening `${{` within the input source. */
+  readonly start: number;
+  /** Byte offset just past the closing `}}` within the input source. */
+  readonly end: number;
+}
+
+export type TemplateSegment = TemplateLiteralSegment | TemplateExpressionSegment;
+
+const OPEN_DELIM = '${{';
+const CLOSE_DELIM = '}}';
+
+/**
+ * Parse a string into a sequence of literal + expression segments. Pure
+ * literals (no interpolation) return a single literal segment; an empty
+ * input returns no segments. Unbalanced delimiters fail fast with a typed
+ * `WorkflowDslError`.
+ */
+export function parseTemplate(
+  source: string,
+  authoredPath: readonly string[] = [],
+): readonly TemplateSegment[] {
+  const segments: TemplateSegment[] = [];
+  let cursor = 0;
+
+  while (cursor < source.length) {
+    const openIdx = source.indexOf(OPEN_DELIM, cursor);
+    if (openIdx === -1) {
+      segments.push({
+        kind: TemplateSegmentKind.Literal,
+        value: source.slice(cursor),
+      });
+      return segments;
+    }
+
+    if (openIdx > cursor) {
+      segments.push({
+        kind: TemplateSegmentKind.Literal,
+        value: source.slice(cursor, openIdx),
+      });
+    }
+
+    const bodyStart = openIdx + OPEN_DELIM.length;
+    const closeIdx = source.indexOf(CLOSE_DELIM, bodyStart);
+    if (closeIdx === -1) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+        `Unterminated template interpolation at ${pathLabel(authoredPath)} (offset ${openIdx}): missing closing '}}'.`,
+        { authoredPath: [...authoredPath], offset: openIdx },
+      );
+    }
+
+    const rawBody = source.slice(bodyStart, closeIdx);
+    const trimmed = rawBody.trim();
+    if (trimmed.length === 0) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+        `Empty template interpolation at ${pathLabel(authoredPath)} (offset ${openIdx}): '\${{ }}' must contain an expression.`,
+        { authoredPath: [...authoredPath], offset: openIdx },
+      );
+    }
+
+    segments.push({
+      kind: TemplateSegmentKind.Expression,
+      source: trimmed,
+      start: openIdx,
+      end: closeIdx + CLOSE_DELIM.length,
+    });
+
+    cursor = closeIdx + CLOSE_DELIM.length;
+  }
+
+  return segments;
+}
+
+/**
+ * True iff the parsed template has at least one expression segment. Cheap
+ * shortcut for callers that need to distinguish "static literal" from
+ * "needs evaluation" without re-parsing.
+ */
+export function templateHasExpressions(segments: readonly TemplateSegment[]): boolean {
+  for (const segment of segments) {
+    if (segment.kind === TemplateSegmentKind.Expression) return true;
+  }
+  return false;
+}
+
+function pathLabel(path: readonly string[]): string {
+  return path.length === 0 ? '<root>' : path.join('.');
+}

package/src/workflow/lib/expression/tokenizer.ts

@@ -0,0 +1,200 @@
+import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+import { type Token, TokenKind } from './tokens';
+
+/**
+ * Hand-rolled tokenizer for the expression subset. Deterministic: same
+ * input always produces the same token stream. Fails fast on any character
+ * outside the grammar.
+ *
+ * Grammar (surface):
+ *   identifiers: [A-Za-z_][A-Za-z0-9_-]*
+ *   numbers:     [0-9]+(\.[0-9]+)?
+ *   strings:     '...'  (single-quoted; no escapes — keep grammar simple
+ *                and deterministic. If escapes are needed later, add once
+ *                with full test coverage; do not retrofit ad-hoc.)
+ *   operators:   == != && || ! ( ) [ ] , .
+ *   booleans:    true | false
+ *   null:        null
+ *   whitespace:  spaces and tabs (ignored)
+ */
+export function tokenize(source: string): readonly Token[] {
+  const tokens: Token[] = [];
+  const length = source.length;
+  let index = 0;
+
+  while (index < length) {
+    const ch = source.charAt(index);
+
+    if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+      index++;
+      continue;
+    }
+
+    const column = index + 1;
+
+    if (ch === '(') {
+      tokens.push({ kind: TokenKind.LPAREN, value: '(', column });
+      index++;
+      continue;
+    }
+    if (ch === ')') {
+      tokens.push({ kind: TokenKind.RPAREN, value: ')', column });
+      index++;
+      continue;
+    }
+    if (ch === '[') {
+      tokens.push({ kind: TokenKind.LBRACKET, value: '[', column });
+      index++;
+      continue;
+    }
+    if (ch === ']') {
+      tokens.push({ kind: TokenKind.RBRACKET, value: ']', column });
+      index++;
+      continue;
+    }
+    if (ch === ',') {
+      tokens.push({ kind: TokenKind.COMMA, value: ',', column });
+      index++;
+      continue;
+    }
+    if (ch === '.') {
+      tokens.push({ kind: TokenKind.DOT, value: '.', column });
+      index++;
+      continue;
+    }
+
+    if (ch === '=' && source.charAt(index + 1) === '=') {
+      tokens.push({ kind: TokenKind.EQ, value: '==', column });
+      index += 2;
+      continue;
+    }
+
+    if (ch === '!' && source.charAt(index + 1) === '=') {
+      tokens.push({ kind: TokenKind.NEQ, value: '!=', column });
+      index += 2;
+      continue;
+    }
+
+    if (ch === '!') {
+      tokens.push({ kind: TokenKind.BANG, value: '!', column });
+      index++;
+      continue;
+    }
+
+    if (ch === '&' && source.charAt(index + 1) === '&') {
+      tokens.push({ kind: TokenKind.AND, value: '&&', column });
+      index += 2;
+      continue;
+    }
+
+    if (ch === '|' && source.charAt(index + 1) === '|') {
+      tokens.push({ kind: TokenKind.OR, value: '||', column });
+      index += 2;
+      continue;
+    }
+
+    if (ch === "'") {
+      const { value, next } = readString(source, index);
+      tokens.push({ kind: TokenKind.STRING, value, column });
+      index = next;
+      continue;
+    }
+
+    if (isDigit(ch)) {
+      const { value, next } = readNumber(source, index);
+      tokens.push({ kind: TokenKind.NUMBER, value, column });
+      index = next;
+      continue;
+    }
+
+    if (isIdentStart(ch)) {
+      const { value, next } = readIdentifier(source, index);
+      if (value === 'true' || value === 'false') {
+        tokens.push({ kind: TokenKind.BOOLEAN, value, column });
+      } else if (value === 'null') {
+        tokens.push({ kind: TokenKind.NULL, value, column });
+      } else {
+        tokens.push({ kind: TokenKind.IDENTIFIER, value, column });
+      }
+      index = next;
+      continue;
+    }
+
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `Unexpected character '${ch}' at column ${column}`,
+      { source, column },
+    );
+  }
+
+  tokens.push({ kind: TokenKind.EOF, value: '', column: length + 1 });
+  return tokens;
+}
+
+function readString(source: string, start: number): { value: string; next: number } {
+  const length = source.length;
+  let end = start + 1;
+  while (end < length && source.charAt(end) !== "'") {
+    if (source.charAt(end) === '\\') {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+        `String escapes are not supported in expression literals (column ${end + 1}).`,
+        { source, column: end + 1 },
+      );
+    }
+    end++;
+  }
+  if (end >= length) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `Unterminated string literal starting at column ${start + 1}`,
+      { source, column: start + 1 },
+    );
+  }
+  return { value: source.slice(start + 1, end), next: end + 1 };
+}
+
+function readNumber(source: string, start: number): { value: string; next: number } {
+  const length = source.length;
+  let end = start;
+  while (end < length && isDigit(source.charAt(end))) {
+    end++;
+  }
+  if (end < length && source.charAt(end) === '.') {
+    end++;
+    const fractionStart = end;
+    while (end < length && isDigit(source.charAt(end))) {
+      end++;
+    }
+    if (end === fractionStart) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+        `Number literal with trailing dot at column ${start + 1}`,
+        { source, column: start + 1 },
+      );
+    }
+  }
+  return { value: source.slice(start, end), next: end };
+}
+
+function readIdentifier(source: string, start: number): { value: string; next: number } {
+  const length = source.length;
+  let end = start;
+  while (end < length && isIdentPart(source.charAt(end))) {
+    end++;
+  }
+  return { value: source.slice(start, end), next: end };
+}
+
+function isDigit(ch: string): boolean {
+  return ch >= '0' && ch <= '9';
+}
+
+function isIdentStart(ch: string): boolean {
+  return (ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z') || ch === '_';
+}
+
+function isIdentPart(ch: string): boolean {
+  return isIdentStart(ch) || isDigit(ch) || ch === '-';
+}

package/src/workflow/lib/expression/tokens.ts

@@ -0,0 +1,30 @@
+/**
+ * Token kinds for the Xema expression subset. Closed set; every token
+ * produced by the tokenizer picks one of these. Unknown input is rejected.
+ */
+export enum TokenKind {
+  IDENTIFIER = 'identifier',
+  NUMBER = 'number',
+  STRING = 'string',
+  BOOLEAN = 'boolean',
+  NULL = 'null',
+  LPAREN = '(',
+  RPAREN = ')',
+  LBRACKET = '[',
+  RBRACKET = ']',
+  COMMA = ',',
+  DOT = '.',
+  BANG = '!',
+  EQ = '==',
+  NEQ = '!=',
+  AND = '&&',
+  OR = '||',
+  EOF = 'eof',
+}
+
+export interface Token {
+  readonly kind: TokenKind;
+  readonly value: string;
+  /** 1-based column in the source expression for diagnostic output. */
+  readonly column: number;
+}