@xemahq/dsl 0.8.0 → 0.8.2

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

@@ -1,84 +0,0 @@
-import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
-import { WorkflowDslError } from '../errors';
-
-/**
- * Authored expressions in YAML are wrapped as `${{ ... }}`. These helpers
- * strip the wrapping deterministically and detect partial interpolation.
- *
- * Design choice: partial interpolation (`hello ${{ inputs.name }}!`) is
- * NOT supported in v1. Every authored expression must be the whole value
- * of its field. String templating introduces ambiguity around type
- * coercion — we keep the surface small and composable instead.
- */
-const INTERPOLATION_RE = /^\s*\$\{\{\s*(?<body>[\s\S]+?)\s*\}\}\s*$/;
-export const ANY_INTERPOLATION_RE = /\$\{\{/;
-
-/** True if the raw string is a single `${{ ... }}` expression (and only that). */
-export function isInterpolationWrapped(raw: string): boolean {
-  return INTERPOLATION_RE.test(raw);
-}
-
-/**
- * Strip `${{ ... }}` wrapping. Throws DSL_EXPRESSION_INVALID if the raw
- * string is not fully wrapped (rejects partial interpolation).
- */
-export function stripInterpolation(raw: string): string {
-  const match = INTERPOLATION_RE.exec(raw);
-  if (!match) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
-      `Expression must be fully wrapped in \${{ ... }}: ${raw}`,
-      { raw },
-    );
-  }
-  return match.groups?.['body'] ?? '';
-}
-
-/**
- * Walks an arbitrary value tree and returns every `${{ ... }}` source it
- * finds. Used by the compiler's validation pass: collect all expressions
- * in `with`, `outputs`, `if`, `strategy.dynamic.from`, etc., and compile
- * each one so authored expressions are caught at compile time.
- */
-export function extractInterpolations(node: unknown, path: string[] = []): ExtractedExpression[] {
-  if (typeof node === 'string') {
-    if (isInterpolationWrapped(node)) {
-      return [{ path: [...path], source: stripInterpolation(node) }];
-    }
-    if (ANY_INTERPOLATION_RE.test(node)) {
-      // Partial interpolation — reject fast so authors can't accidentally
-      // rely on broken string templating.
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_EXPRESSION_INVALID,
-        `Partial \${{ ... }} interpolation is not supported at ${pathLabel(path)}. Use a fully wrapped expression or plain text.`,
-        { path },
-      );
-    }
-    return [];
-  }
-  if (Array.isArray(node)) {
-    const collected: ExtractedExpression[] = [];
-    for (let i = 0; i < node.length; i++) {
-      collected.push(...extractInterpolations(node[i], [...path, String(i)]));
-    }
-    return collected;
-  }
-  if (node !== null && typeof node === 'object') {
-    const record = node as Record<string, unknown>;
-    const collected: ExtractedExpression[] = [];
-    for (const key of Object.keys(record)) {
-      collected.push(...extractInterpolations(record[key], [...path, key]));
-    }
-    return collected;
-  }
-  return [];
-}
-
-export interface ExtractedExpression {
-  readonly path: readonly string[];
-  readonly source: string;
-}
-
-function pathLabel(path: readonly string[]): string {
-  return path.length === 0 ? '<root>' : path.join('.');
-}

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

@@ -1,264 +0,0 @@
-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

@@ -1,117 +0,0 @@
-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

@@ -1,200 +0,0 @@
-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

@@ -1,30 +0,0 @@
-/**
- * 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;
-}