@xemahq/dsl 0.1.1

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

@@ -0,0 +1,492 @@
+import {
+  isArtifactRef,
+  isArtifactRefEnvelopeField,
+  WorkflowErrorCode,
+  type ArtifactRef,
+} from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+import {
+  type BinaryNode,
+  type CallNode,
+  type ExpressionNode,
+  ExpressionFunction,
+  ExpressionNodeKind,
+  ExpressionRoot,
+  type IdentifierNode,
+  type IndexNode,
+  type LiteralNode,
+  type MemberNode,
+} from './ast';
+import type { ExpressionContext } from './context';
+import { parseExpression } from './parser';
+import { tokenize } from './tokenizer';
+
+/**
+ * Compile a source expression into an {@link ExpressionNode} tree. Used by
+ * the workflow compiler to pre-validate every expression at compile time
+ * (so runtime evaluation can only fail on unknown bindings, not on
+ * syntax). Reject unknown identifiers, roots, and function calls.
+ */
+export function compileExpression(source: string): ExpressionNode {
+  if (source.length === 0) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      'Expression source must not be empty',
+      { source },
+    );
+  }
+  const tokens = tokenize(source);
+  return parseExpression(source, tokens);
+}
+
+/**
+ * Evaluate a pre-compiled {@link ExpressionNode} against a bound context.
+ * Deterministic: same (node, context) always produces the same value, no
+ * implicit time/random/env access, no silent coercion.
+ *
+ * Throws {@link WorkflowDslError} with code DSL_EXPRESSION_INVALID on any
+ * unknown property lookup or type mismatch — the caller must surface the
+ * error; silent substitution is forbidden.
+ */
+export function evaluateExpression(node: ExpressionNode, ctx: ExpressionContext): unknown {
+  switch (node.kind) {
+    case ExpressionNodeKind.LITERAL:
+      return evalLiteral(node);
+    case ExpressionNodeKind.IDENTIFIER:
+      return evalIdentifier(node, ctx);
+    case ExpressionNodeKind.MEMBER:
+      return evalMember(node, ctx);
+    case ExpressionNodeKind.INDEX:
+      return evalIndex(node, ctx);
+    case ExpressionNodeKind.CALL:
+      return evalCall(node, ctx);
+    case ExpressionNodeKind.UNARY_NOT: {
+      const operand = evaluateExpression(node.operand, ctx);
+      return !toBool(operand);
+    }
+    case ExpressionNodeKind.BINARY_EQ:
+    case ExpressionNodeKind.BINARY_NEQ:
+    case ExpressionNodeKind.BINARY_AND:
+    case ExpressionNodeKind.BINARY_OR:
+      return evalBinary(node, ctx);
+  }
+}
+
+function evalLiteral(node: LiteralNode): unknown {
+  return node.value;
+}
+
+function evalIdentifier(node: IdentifierNode, ctx: ExpressionContext): unknown {
+  switch (node.name as ExpressionRoot) {
+    case ExpressionRoot.NEEDS:
+      return ctx.needs;
+    case ExpressionRoot.MATRIX:
+      return ctx.matrix;
+    case ExpressionRoot.INPUTS:
+      return ctx.inputs;
+    case ExpressionRoot.VARS:
+      return ctx.vars;
+    case ExpressionRoot.SECRETS:
+      return ctx.secrets;
+    case ExpressionRoot.TRIGGER:
+      return ctx.trigger;
+    case ExpressionRoot.JOB:
+      return ctx.job;
+    case ExpressionRoot.XEMA:
+      return ctx.xema;
+    default:
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+        `Unknown identifier root '${node.name}'`,
+        { name: node.name },
+      );
+  }
+}
+
+function evalMember(node: MemberNode, ctx: ExpressionContext): unknown {
+  const target = evaluateExpression(node.target, ctx);
+  return readPropertyWithPayloadCache(target, node.property, ctx);
+}
+
+function evalIndex(node: IndexNode, ctx: ExpressionContext): unknown {
+  const target = evaluateExpression(node.target, ctx);
+  const key = evaluateExpression(node.index, ctx);
+
+  if (Array.isArray(target)) {
+    if (typeof key !== 'number' || !Number.isInteger(key)) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+        `Array index must be an integer, received ${typeof key}`,
+        { key, targetKind: 'array' },
+      );
+    }
+    if (key < 0 || key >= target.length) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+        `Array index out of range: ${key} (length ${target.length})`,
+        { key, length: target.length },
+      );
+    }
+    return target[key];
+  }
+
+  if (typeof target === 'object' && target !== null) {
+    if (typeof key !== 'string') {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+        `Object index must be a string, received ${typeof key}`,
+        { key, targetKind: 'object' },
+      );
+    }
+    return readPropertyWithPayloadCache(target, key, ctx);
+  }
+
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+    `Indexing is only supported on arrays or objects. Target kind: ${typeof target}`,
+    { targetKind: typeof target },
+  );
+}
+
+function evalCall(node: CallNode, ctx: ExpressionContext): unknown {
+  switch (node.callee) {
+    case ExpressionFunction.FROM_JSON:
+      return evalFromJson(node, ctx);
+    case ExpressionFunction.TO_JSON:
+      return evalToJson(node, ctx);
+    case ExpressionFunction.FORMAT:
+      return evalFormat(node, ctx);
+  }
+}
+
+/**
+ * `fromJSON` accepts two argument shapes:
+ *
+ *   1. `string` — JSON-parse the string (matches GitHub Actions semantics).
+ *      Parse failure → `DSL_EXPRESSION_INVALID` (the source is authored
+ *      literal text; we treat it as a syntax-level error).
+ *   2. `ArtifactRef` — look up the pre-fetched parsed payload in the
+ *      `payloadCache` (keyed on `versionId`). Missing entry →
+ *      `DSL_PAYLOAD_PARSE_ERROR`: the runtime is responsible for
+ *      pre-resolving every ref referenced by an expression before the
+ *      evaluator runs. A cache miss is a runtime infra bug, not an
+ *      author bug, so it carries a runtime-coded error.
+ *
+ * This is the §C.2 escape hatch. Authors who want compile-time field
+ * validation use the typed reach-in (`outputs.foo.field`, §C.1).
+ */
+function evalFromJson(node: CallNode, ctx: ExpressionContext): unknown {
+  const argNode = singleArg(node, 'fromJSON');
+  const arg = evaluateExpression(argNode, ctx);
+  if (typeof arg === 'string') {
+    try {
+      return JSON.parse(arg);
+    } catch (err) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+        `fromJSON failed to parse argument as JSON: ${(err as Error).message}`,
+        { callee: node.callee },
+      );
+    }
+  }
+  if (isArtifactRef(arg)) {
+    const cached = ctx.payloadCache.get(arg.versionId);
+    if (cached === undefined) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_PAYLOAD_PARSE_ERROR,
+        `fromJSON(<ArtifactRef>) called against versionId='${arg.versionId}' but the runtime did not pre-resolve its payload into the per-step cache. This is a runtime infra failure — the worker is expected to fetch and parse every referenced artifact before evaluating expressions.`,
+        {
+          callee: node.callee,
+          artifactId: arg.artifactId,
+          versionId: arg.versionId,
+          type: arg.type,
+        },
+      );
+    }
+    return cached;
+  }
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+    `fromJSON requires a string or ArtifactRef argument, received ${typeof arg}`,
+    { callee: node.callee, argKind: typeof arg },
+  );
+}
+
+function evalToJson(node: CallNode, ctx: ExpressionContext): string {
+  const argNode = singleArg(node, 'toJSON');
+  return JSON.stringify(evaluateExpression(argNode, ctx));
+}
+
+function evalFormat(node: CallNode, ctx: ExpressionContext): string {
+  if (node.args.length < 1) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `format expects at least one argument (the template string)`,
+      { callee: node.callee, arity: node.args.length },
+    );
+  }
+  const [templateNode, ...argNodes] = node.args;
+  if (!templateNode) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `format template is missing from AST`,
+      { callee: node.callee },
+    );
+  }
+  const template = evaluateExpression(templateNode, ctx);
+  if (typeof template !== 'string') {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `format template must be a string, received ${typeof template}`,
+      { callee: node.callee, templateKind: typeof template },
+    );
+  }
+  const args = argNodes.map((argNode) => evaluateExpression(argNode, ctx));
+  return formatTemplate(template, args);
+}
+
+function singleArg(node: CallNode, fnName: string): ExpressionNode {
+  if (node.args.length !== 1) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `${fnName} expects exactly one argument, received ${node.args.length}`,
+      { callee: node.callee, arity: node.args.length },
+    );
+  }
+  const [argNode] = node.args;
+  if (!argNode) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `${fnName} argument is missing from AST`,
+      { callee: node.callee },
+    );
+  }
+  return argNode;
+}
+
+/**
+ * Replace `{N}` placeholders in `template` with the stringified arg at
+ * index N. Escape `{{` / `}}` for literal braces. Out-of-range indices
+ * fail fast — silent emptiness would be a footgun for authors.
+ */
+function formatTemplate(template: string, args: readonly unknown[]): string {
+  let out = '';
+  let i = 0;
+  while (i < template.length) {
+    const ch = template[i];
+    if (ch === '{') {
+      const advance = consumeOpenBrace(template, i, args);
+      out += advance.text;
+      i = advance.next;
+      continue;
+    }
+    if (ch === '}') {
+      const advance = consumeCloseBrace(template, i);
+      out += advance.text;
+      i = advance.next;
+      continue;
+    }
+    out += ch;
+    i++;
+  }
+  return out;
+}
+
+interface FormatAdvance {
+  readonly text: string;
+  readonly next: number;
+}
+
+function consumeOpenBrace(
+  template: string,
+  i: number,
+  args: readonly unknown[],
+): FormatAdvance {
+  if (template[i + 1] === '{') {
+    return { text: '{', next: i + 2 };
+  }
+  const close = template.indexOf('}', i + 1);
+  if (close === -1) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `format template has unclosed '{' starting at index ${i}: ${template}`,
+      { template },
+    );
+  }
+  const indexLiteral = template.slice(i + 1, close);
+  const idx = parseFormatIndex(template, indexLiteral, args.length);
+  return { text: stringifyFormatArg(args[idx]), next: close + 1 };
+}
+
+function consumeCloseBrace(template: string, i: number): FormatAdvance {
+  if (template[i + 1] === '}') {
+    return { text: '}', next: i + 2 };
+  }
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+    `format template has unmatched '}' at index ${i}: ${template}`,
+    { template },
+  );
+}
+
+function parseFormatIndex(template: string, indexLiteral: string, argCount: number): number {
+  if (!/^\d+$/.test(indexLiteral)) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `format placeholder '{${indexLiteral}}' is not a non-negative integer`,
+      { template, placeholder: indexLiteral },
+    );
+  }
+  const idx = Number(indexLiteral);
+  if (idx >= argCount) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `format placeholder '{${idx}}' has no matching argument (received ${argCount} arg(s))`,
+      { template, placeholder: idx, argCount },
+    );
+  }
+  return idx;
+}
+
+function stringifyFormatArg(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (value === null) return 'null';
+  if (value === undefined) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `format argument resolved to undefined; expressions must produce a defined value`,
+      {},
+    );
+  }
+  // Objects + arrays serialize as JSON so authors can build deterministic
+  // strings without risk of `[object Object]` slipping through.
+  return JSON.stringify(value);
+}
+
+function evalBinary(node: BinaryNode, ctx: ExpressionContext): unknown {
+  switch (node.kind) {
+    case ExpressionNodeKind.BINARY_EQ: {
+      const left = evaluateExpression(node.left, ctx);
+      const right = evaluateExpression(node.right, ctx);
+      return strictEquals(left, right);
+    }
+    case ExpressionNodeKind.BINARY_NEQ: {
+      const left = evaluateExpression(node.left, ctx);
+      const right = evaluateExpression(node.right, ctx);
+      return !strictEquals(left, right);
+    }
+    case ExpressionNodeKind.BINARY_AND: {
+      const left = evaluateExpression(node.left, ctx);
+      if (!toBool(left)) return false;
+      return toBool(evaluateExpression(node.right, ctx));
+    }
+    case ExpressionNodeKind.BINARY_OR: {
+      const left = evaluateExpression(node.left, ctx);
+      if (toBool(left)) return true;
+      return toBool(evaluateExpression(node.right, ctx));
+    }
+  }
+}
+
+/**
+ * Property-read wrapper that transparently redirects payload reach-in
+ * (`outputs.foo.<payload-field>`) through the per-step `payloadCache`.
+ *
+ * When `target` is an `ArtifactRef`:
+ *   • envelope-field property (artifactId/versionId/version/hash/type/title)
+ *     → read directly off the ref (no fetch).
+ *   • any other property → look up the artifact's parsed payload in
+ *     `ctx.payloadCache` (populated by the worker's reach-in pre-fetch)
+ *     and read the field off that. Cache miss surfaces as
+ *     `DSL_PAYLOAD_PARSE_ERROR` so the author sees a clean DSL error
+ *     instead of a misleading "Unknown property" on the ref.
+ *
+ * Anything else delegates to the plain `readProperty` path.
+ */
+function readPropertyWithPayloadCache(
+  target: unknown,
+  property: string,
+  ctx: ExpressionContext,
+): unknown {
+  if (isArtifactRef(target) && !isArtifactRefEnvelopeField(property)) {
+    return readPayloadField(target, property, ctx);
+  }
+  return readProperty(target, property);
+}
+
+function readPayloadField(
+  ref: ArtifactRef,
+  property: string,
+  ctx: ExpressionContext,
+): unknown {
+  if (!ctx.payloadCache.has(ref.versionId)) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_PAYLOAD_PARSE_ERROR,
+      `Payload reach-in '${property}' on artifact '${ref.artifactId}' v${ref.version} ` +
+        `(versionId '${ref.versionId}') is not available — the per-step payloadCache ` +
+        `has no entry for this version. The runtime pre-fetch should have populated ` +
+        `the cache before this expression evaluated; this typically means the ref ` +
+        `surfaced from an indirection the pre-fetch walker can't trace (e.g. a ` +
+        `dynamically computed ref). Use 'fromJSON(<ref>)' as the documented ` +
+        `escape hatch when the runtime cannot statically pre-fetch.`,
+      { artifactId: ref.artifactId, versionId: ref.versionId, version: ref.version, property },
+    );
+  }
+  const payload = ctx.payloadCache.get(ref.versionId);
+  if (payload === null || payload === undefined) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_PAYLOAD_PARSE_ERROR,
+      `Payload reach-in '${property}' on artifact '${ref.artifactId}' v${ref.version} ` +
+        `failed: cached payload is ${payload === null ? 'null' : 'undefined'}.`,
+      { artifactId: ref.artifactId, versionId: ref.versionId, property },
+    );
+  }
+  return readProperty(payload, property);
+}
+
+function readProperty(target: unknown, property: string): unknown {
+  if (target === null || target === undefined) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `Cannot read property '${property}' of ${target === null ? 'null' : 'undefined'}`,
+      { property },
+    );
+  }
+  if (typeof target !== 'object' || Array.isArray(target)) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `Member access '${property}' is not supported on ${Array.isArray(target) ? 'arrays' : typeof target}`,
+      { property, targetKind: Array.isArray(target) ? 'array' : typeof target },
+    );
+  }
+  const record = target as Record<string, unknown>;
+  if (!Object.prototype.hasOwnProperty.call(record, property)) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+      `Unknown property '${property}'. Available keys: ${Object.keys(record).sort().join(', ') || '(none)'}.`,
+      { property, availableKeys: Object.keys(record) },
+    );
+  }
+  return record[property];
+}
+
+function toBool(value: unknown): boolean {
+  // Deterministic boolean coercion — closed set of accepted types. Anything
+  // else is a typed error. No JS truthiness footguns in expressions.
+  if (typeof value === 'boolean') return value;
+  if (value === null) return false;
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+    `Expected boolean, received ${typeof value}. Xema expressions do not implicitly coerce truthiness.`,
+    { valueKind: value === null ? 'null' : typeof value },
+  );
+}
+
+function strictEquals(a: unknown, b: unknown): boolean {
+  // Primitive equality only. Arrays/objects fall through to reference
+  // equality — expression authors should compare primitives.
+  if (typeof a !== typeof b) return false;
+  if (a === b) return true;
+  return false;
+}

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

@@ -0,0 +1,28 @@
+export {
+  type ExpressionContext,
+  type NeedsEntry,
+  type PayloadCache,
+  type XemaActor,
+  type XemaContext,
+  XemaActorKind,
+  EMPTY_CONTEXT_SEEDS,
+} from './context';
+export { compileExpression, evaluateExpression } from './evaluator';
+export { ExpressionFunction, ExpressionNodeKind, ExpressionRoot } from './ast';
+export type { ExpressionNode } from './ast';
+export { extractInterpolations, isInterpolationWrapped, stripInterpolation } from './interpolation';
+export {
+  extractUpstreamJobKey,
+  extractUpstreamOutputName,
+  walkRuntimeArtifactRefTargets,
+} from './walk-artifact-refs';
+export {
+  parseTemplate,
+  templateHasExpressions,
+  TemplateSegmentKind,
+} from './template';
+export type {
+  TemplateExpressionSegment,
+  TemplateLiteralSegment,
+  TemplateSegment,
+} from './template';

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

@@ -0,0 +1,84 @@
+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('.');
+}