@xemahq/dsl 0.1.1

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

@@ -0,0 +1,108 @@
+/**
+ * AST node kinds for parsed expressions. Closed set.
+ */
+export enum ExpressionNodeKind {
+  LITERAL = 'literal',
+  IDENTIFIER = 'identifier',
+  MEMBER = 'member',
+  INDEX = 'index',
+  CALL = 'call',
+  UNARY_NOT = 'unary-not',
+  BINARY_EQ = 'binary-eq',
+  BINARY_NEQ = 'binary-neq',
+  BINARY_AND = 'binary-and',
+  BINARY_OR = 'binary-or',
+}
+
+/** Closed set of root identifier bindings allowed in expressions. */
+export enum ExpressionRoot {
+  NEEDS = 'needs',
+  MATRIX = 'matrix',
+  INPUTS = 'inputs',
+  VARS = 'vars',
+  /**
+   * Project / org secret variables resolved at dispatch from the
+   * project-registry-api variable store, declared by the workflow under
+   * `requires.variables[*].secret: true`. Values are strings; expressions
+   * reading this namespace are subject to log redaction by the runtime.
+   */
+  SECRETS = 'secrets',
+  TRIGGER = 'trigger',
+  JOB = 'job',
+  /**
+   * System-managed canonical context for the run. Mirrors GitHub
+   * Actions' `github.*` namespace: stable, system-populated, available
+   * in every expression. Exposes org/project/run/workflow/job/actor
+   * fields so authors don't have to reach into trigger metadata for
+   * what is really run-level state.
+   */
+  XEMA = 'xema',
+}
+
+/** Closed set of built-in function names. Any other identifier-call fails. */
+export enum ExpressionFunction {
+  FROM_JSON = 'fromJSON',
+  TO_JSON = 'toJSON',
+  /**
+   * `format(template, ...args)` — GitHub-Actions-style positional
+   * interpolation. The template is a literal string with `{0}`, `{1}`,
+   * ... placeholders; each is replaced with the stringified arg at that
+   * index. Authors use this when they need to combine an expression
+   * value with surrounding literal text — partial `${{ ... }}`
+   * interpolation in YAML is intentionally rejected, so `format` is the
+   * supported way to build composed strings.
+   */
+  FORMAT = 'format',
+}
+
+export type ExpressionNode =
+  | LiteralNode
+  | IdentifierNode
+  | MemberNode
+  | IndexNode
+  | CallNode
+  | UnaryNotNode
+  | BinaryNode;
+
+export interface LiteralNode {
+  readonly kind: ExpressionNodeKind.LITERAL;
+  readonly value: string | number | boolean | null;
+}
+
+export interface IdentifierNode {
+  readonly kind: ExpressionNodeKind.IDENTIFIER;
+  readonly name: string;
+}
+
+export interface MemberNode {
+  readonly kind: ExpressionNodeKind.MEMBER;
+  readonly target: ExpressionNode;
+  readonly property: string;
+}
+
+export interface IndexNode {
+  readonly kind: ExpressionNodeKind.INDEX;
+  readonly target: ExpressionNode;
+  readonly index: ExpressionNode;
+}
+
+export interface CallNode {
+  readonly kind: ExpressionNodeKind.CALL;
+  readonly callee: ExpressionFunction;
+  readonly args: readonly ExpressionNode[];
+}
+
+export interface UnaryNotNode {
+  readonly kind: ExpressionNodeKind.UNARY_NOT;
+  readonly operand: ExpressionNode;
+}
+
+export interface BinaryNode {
+  readonly kind:
+    | ExpressionNodeKind.BINARY_EQ
+    | ExpressionNodeKind.BINARY_NEQ
+    | ExpressionNodeKind.BINARY_AND
+    | ExpressionNodeKind.BINARY_OR;
+  readonly left: ExpressionNode;
+  readonly right: ExpressionNode;
+}

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

@@ -0,0 +1,148 @@
+import type { TriggerPayload } from '@xemahq/kernel-contracts/workflow';
+
+/**
+ * Per-run, read-only cache of pre-fetched artifact payloads keyed by
+ * `versionId`. Populated by the workflow runtime BEFORE each step's
+ * expressions are evaluated — see `biomes/workflow-runtime/api/workflow-runtime-worker` for the
+ * fetch + cache plumbing. The evaluator only ever reads from this map;
+ * concurrent reads are safe by construction (no writes once frozen for a
+ * step). Empty when no expression in scope reaches into a typed
+ * payload or invokes `fromJSON(ref)`.
+ *
+ * Values are the parsed payload (any JSON-shaped value). The runtime is
+ * responsible for parse-time validation; the evaluator surfaces a
+ * missing-key as `DSL_PAYLOAD_PARSE_ERROR` so authors get a clear
+ * "this ref was never resolved" signal rather than a generic null
+ * dereference.
+ */
+export type PayloadCache = ReadonlyMap<string, unknown>;
+
+/**
+ * Runtime binding context passed to the evaluator. Every entry is a plain
+ * JSON value — no closures, no functions — so evaluation is pure and
+ * deterministic for any given input.
+ */
+export interface ExpressionContext {
+  readonly needs: Readonly<Record<string, NeedsEntry>>;
+  readonly matrix: Readonly<Record<string, unknown>>;
+  readonly inputs: Readonly<Record<string, unknown>>;
+  readonly vars: Readonly<Record<string, unknown>>;
+  /**
+   * Project / org secret variables, populated at dispatch from
+   * `requires.variables[*].secret: true` entries. Always present; empty
+   * when the workflow declares no secret requirements.
+   */
+  readonly secrets: Readonly<Record<string, string>>;
+  /**
+   * The trigger that started this run. Readers access via `trigger.kind`,
+   * `trigger.inputs`, etc. as defined by {@link TriggerPayload}.
+   */
+  readonly trigger: TriggerPayload;
+  /**
+   * Outputs of the current job (if an expression is evaluated at job-level,
+   * e.g. inside `job.outputs`). Empty when evaluating matrix/needs/if.
+   */
+  readonly job: { readonly outputs: Readonly<Record<string, unknown>> };
+  /**
+   * System-managed canonical context for the run — see {@link XemaContext}.
+   * Always present. Authors reach for `${{ xema.project.id }}` instead of
+   * `${{ trigger.projectId }}` because project id is run-level state, not
+   * trigger metadata.
+   */
+  readonly xema: XemaContext;
+  /**
+   * Pre-fetched artifact payloads for the current step, keyed by
+   * `ArtifactRef.versionId`. Used by `fromJSON(ref)` to return the
+   * already-parsed payload without a runtime fetch. Empty map when the
+   * step has no payload-reaching expressions. Always present so the
+   * evaluator can distinguish "ref not resolved" (missing key →
+   * `DSL_PAYLOAD_PARSE_ERROR`) from "no cache at all".
+   */
+  readonly payloadCache: PayloadCache;
+}
+
+export interface NeedsEntry {
+  readonly outputs: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Canonical system-managed context. Modelled after GitHub Actions'
+ * `github.*` so authors reach for an obvious, stable namespace rather
+ * than digging into `trigger.*` metadata for run-level state.
+ *
+ * Every nested record is a plain JSON object — evaluator-safe.
+ */
+export interface XemaContext {
+  readonly org: { readonly id: string };
+  readonly project: { readonly id: string };
+  readonly run: {
+    readonly id: string;
+    readonly attempt: number;
+    /** ISO-8601 wall-clock at trigger dispatch (mirrors `trigger.triggeredAt`). */
+    readonly startedAtIso: string;
+    readonly correlationId: string;
+    readonly actor: XemaActor;
+  };
+  readonly workflow: {
+    readonly key: string;
+    readonly version: string;
+  };
+  readonly job: {
+    readonly key: string;
+    readonly attempt: number;
+  };
+}
+
+export interface XemaActor {
+  /** Subject id of the user who initiated the run; null for scheduled / webhook triggers. */
+  readonly subject: string | null;
+  readonly kind: XemaActorKind;
+}
+
+/**
+ * Closed set of run-actor kinds. `user` is set whenever a subject id is
+ * present; `webhook` / `schedule` come from the trigger discriminator
+ * for unattended runs; `system` is the fallback for engine-initiated
+ * dispatches with no actor (e.g. internal recovery).
+ */
+export enum XemaActorKind {
+  User = 'user',
+  System = 'system',
+  Webhook = 'webhook',
+  Schedule = 'schedule',
+}
+
+/** Empty-but-typed seeds for contexts where an axis doesn't apply yet. */
+export const EMPTY_CONTEXT_SEEDS = {
+  needs: Object.freeze({}) as Readonly<Record<string, NeedsEntry>>,
+  matrix: Object.freeze({}) as Readonly<Record<string, unknown>>,
+  vars: Object.freeze({}) as Readonly<Record<string, unknown>>,
+  secrets: Object.freeze({}) as Readonly<Record<string, string>>,
+  job: Object.freeze({ outputs: Object.freeze({}) }) as {
+    readonly outputs: Readonly<Record<string, unknown>>;
+  },
+  /**
+   * Empty payload cache for compile-time / static contexts where no
+   * artifact resolution has been performed. The runtime replaces this
+   * with the per-step populated map.
+   */
+  payloadCache: new Map<string, unknown>() as PayloadCache,
+  /**
+   * Seed `xema` for compile-time evaluation contexts (concurrency,
+   * static workflow checks) where the canonical fields aren't available
+   * yet. Runtime callers always replace this with the populated shape.
+   */
+  xema: Object.freeze({
+    org: Object.freeze({ id: '' }),
+    project: Object.freeze({ id: '' }),
+    run: Object.freeze({
+      id: '',
+      attempt: 0,
+      startedAtIso: '',
+      correlationId: '',
+      actor: Object.freeze({ subject: null, kind: XemaActorKind.System }),
+    }),
+    workflow: Object.freeze({ key: '', version: '' }),
+    job: Object.freeze({ key: '', attempt: 0 }),
+  }) as XemaContext,
+} as const;