@shipfox/api-workflows 11.0.0 → 12.1.0

package/src/core/step-config/assemble-run-context.test.ts

@@ -1,3 +1,4 @@
+import {getWorkflowPredicateContextRoots} from '@shipfox/expression';
 import type {JobExecution} from '#core/entities/job-execution.js';
 import type {Step, StepAttempt} from '#core/entities/step.js';
 import {
@@ -19,7 +20,9 @@ const date = new Date('2026-06-30T12:00:00.000Z');
 describe('assembleWorkflowRunContext', () => {
   const run = {
     id: 'run-1',
+    number: 1,
     name: 'Build',
+    workflowName: 'Build',
     definitionId: 'def-1',
     projectId: 'proj-1',
     workspaceId: 'workspace-1',
@@ -39,15 +42,26 @@ describe('assembleWorkflowRunContext', () => {
     });
 
     expect(context).toEqual({
+      workflow: {
+        id: 'def-1',
+        name: 'Build',
+      },
       run: {
         id: 'run-1',
+        number: 1,
         name: 'Build',
-        definition_id: 'def-1',
         project_id: 'proj-1',
         workspace_id: 'workspace-1',
         created_at: run.createdAt,
       },
-      trigger: {source: 'github', event: 'push'},
+      trigger: {
+        source: 'github',
+        event: 'push',
+        project: null,
+        repository: null,
+        ref: null,
+        commit: null,
+      },
       event: {ref: 'refs/heads/main'},
       inputs: {deploy: true},
     });
@@ -76,7 +90,9 @@ describe('assembleWorkflowRunContext', () => {
 describe('assembleCreationContext', () => {
   const run = {
     id: 'run-1',
+    number: 1,
     name: 'Build',
+    workflowName: 'Build',
     definitionId: 'def-1',
     projectId: 'proj-1',
     workspaceId: 'workspace-1',
@@ -109,12 +125,44 @@ describe('assembleCreationContext', () => {
       }),
     });
   });
+
+  it('exposes the normalized trigger reference on the trigger root', () => {
+    const context = assembleWorkflowRunContext({
+      run: {
+        ...run,
+        triggerReference: {
+          project: {id: 'project-1'},
+          repository: 'acme/api',
+          ref: 'refs/pull/42/head',
+          commit: 'a'.repeat(40),
+          actor: 'octocat',
+        },
+      },
+      triggerPayload: {
+        source: 'github',
+        event: 'pull_request',
+        deliveryId: 'delivery-1',
+        data: {},
+      },
+    });
+
+    expect(context.trigger).toEqual({
+      source: 'github',
+      event: 'pull_request',
+      project: {id: 'project-1'},
+      repository: 'acme/api',
+      ref: 'refs/pull/42/head',
+      commit: 'a'.repeat(40),
+    });
+  });
 });
 
 describe('assembleExecutionCreationContext', () => {
   const run = {
     id: 'run-1',
+    number: 1,
     name: 'Build',
+    workflowName: 'Build',
     definitionId: 'def-1',
     projectId: 'proj-1',
     workspaceId: 'workspace-1',
@@ -140,8 +188,9 @@ describe('assembleExecutionCreationContext', () => {
         data: {ref: 'refs/heads/main'},
       },
       inputs: {deploy: true},
-      jobId: 'job-1',
+      job: {id: 'job-1', key: 'build', name: 'Build'},
       sequence: 2,
+      nameOverride: null,
       executionName: 'Build #2',
       status: 'pending',
       triggerEvents: [
@@ -150,6 +199,10 @@ describe('assembleExecutionCreationContext', () => {
           event: 'deployment',
           delivery_id: 'delivery-2',
           received_at: '2026-06-30T12:01:00.000Z',
+          project: null,
+          repository: null,
+          ref: null,
+          commit: null,
           data: {environment: 'prod'},
         },
       ],
@@ -191,12 +244,17 @@ describe('assembleExecutionCreationContext', () => {
                 event: 'deployment',
                 delivery_id: 'delivery-2',
                 received_at: '2026-06-30T12:01:00.000Z',
+                project: null,
+                repository: null,
+                ref: null,
+                commit: null,
                 data: {environment: 'prod'},
               },
             ],
             outputs: {},
           },
         ],
+        job: {key: 'build', name: 'Build'},
         execution: {
           index: 1,
           name: 'Build #2',
@@ -209,6 +267,10 @@ describe('assembleExecutionCreationContext', () => {
               event: 'deployment',
               delivery_id: 'delivery-2',
               received_at: '2026-06-30T12:01:00.000Z',
+              project: null,
+              repository: null,
+              ref: null,
+              commit: null,
               data: {environment: 'prod'},
             },
           ],
@@ -222,7 +284,9 @@ describe('assembleExecutionCreationContext', () => {
 describe('assembleJobActivationContext', () => {
   const run = {
     id: 'run-1',
+    number: 1,
     name: 'Build',
+    workflowName: 'Build',
     definitionId: 'def-1',
     projectId: 'proj-1',
     workspaceId: 'workspace-1',
@@ -259,6 +323,9 @@ describe('assembleJobActivationContext', () => {
       ],
     });
 
+    expect(Object.keys(context.values).sort()).toEqual(
+      [...getWorkflowPredicateContextRoots('job.if')].sort(),
+    );
     expect(context).toEqual({
       site: 'job-activation',
       values: {
@@ -320,6 +387,7 @@ describe('assembleJobActivationContext', () => {
             executions: [],
           },
         ],
+        vars: {},
       },
     });
   });
@@ -328,7 +396,9 @@ describe('assembleJobActivationContext', () => {
 describe('listener filter snapshots', () => {
   const run = {
     id: 'run-1',
+    number: 1,
     name: 'Build',
+    workflowName: 'Build',
     definitionId: 'def-1',
     projectId: 'proj-1',
     workspaceId: 'workspace-1',
@@ -348,7 +418,7 @@ describe('listener filter snapshots', () => {
           source: 'github',
           event: 'pull_request',
           filter:
-            'jobs.build.outputs.pr_number == event.pull_request.number && inputs.environment == "prod" && trigger.event == "pull_request" && run.id != "" && job.key == "await"',
+            'jobs.build.outputs.pr_number == event.pull_request.number && inputs.environment == "prod" && trigger.event == "pull_request" && workflow.name != "" && run.id != "" && job.key == "await" && vars.ENABLED == "true"',
         },
       ],
       until: null,
@@ -358,6 +428,7 @@ describe('listener filter snapshots', () => {
       run,
       triggerPayload,
       inputs: {environment: 'prod'},
+      vars: {ENABLED: 'true'},
       plan,
       dependencyJobs: [
         {
@@ -374,10 +445,19 @@ describe('listener filter snapshots', () => {
     const [matcher] = applyListenerFilterSnapshots(plan.on, context);
 
     expect(matcher?.filter_snapshot).toEqual({
+      workflow: {id: 'def-1', name: 'Build'},
       run: expect.objectContaining({id: 'run-1', name: 'Build'}),
-      trigger: {source: 'github', event: 'pull_request'},
+      trigger: {
+        source: 'github',
+        event: 'pull_request',
+        project: null,
+        repository: null,
+        ref: null,
+        commit: null,
+      },
       inputs: {environment: 'prod'},
       job: {key: 'await'},
+      vars: {ENABLED: 'true'},
       jobs: {
         build: expect.objectContaining({
           key: 'build',
@@ -387,10 +467,40 @@ describe('listener filter snapshots', () => {
         }),
       },
     });
+    expect(Object.keys(matcher?.filter_snapshot ?? {}).sort()).toEqual(
+      getWorkflowPredicateContextRoots('listener.on')
+        .filter((root) => root !== 'event')
+        .sort(),
+    );
     expect(matcher?.filter_snapshot).not.toHaveProperty('event');
     expect(matcher?.filter_snapshot?.jobs).not.toHaveProperty('review');
   });
 
+  it('snapshots vars for listener filters', () => {
+    const plan = planListenerFilterSnapshots({
+      on: [
+        {
+          source: 'github',
+          event: 'pull_request',
+          filter: 'vars.ENABLED == "true"',
+        },
+      ],
+      until: null,
+    });
+    const context = assembleListenerSnapshotContext({
+      job: {key: 'await'},
+      run,
+      triggerPayload,
+      vars: {ENABLED: 'true'},
+      plan,
+      dependencyJobs: [],
+    });
+
+    const [matcher] = applyListenerFilterSnapshots(plan.on, context);
+
+    expect(matcher?.filter_snapshot).toEqual({vars: {ENABLED: 'true'}});
+  });
+
   it('omits snapshots for event-only filters and malformed filters', () => {
     const plan = planListenerFilterSnapshots({
       on: [
@@ -525,6 +635,9 @@ describe('assembleStepDispatchContext', () => {
       jobExecution: execution,
     });
 
+    expect(Object.keys(context.values).sort()).toEqual(
+      [...getWorkflowPredicateContextRoots('step.if')].sort(),
+    );
     expect(context).toEqual({
       site: 'step-dispatch',
       values: {
@@ -541,11 +654,16 @@ describe('assembleStepDispatchContext', () => {
               event: 'push',
               delivery_id: 'delivery-1',
               received_at: '2026-06-30T12:00:00.000Z',
+              project: null,
+              repository: null,
+              ref: null,
+              commit: null,
               data: {ref: 'refs/heads/main'},
             },
           ],
           outputs: {},
         },
+        jobs: {},
         step: {
           attempt: 2n,
           is_retry: true,
@@ -568,6 +686,7 @@ describe('assembleStepDispatchContext', () => {
           test: {status: 'pending', attempts: []},
           running: {status: 'running', attempts: []},
         },
+        vars: {},
       },
     });
   });
@@ -811,9 +930,13 @@ describe('assembleGateContext', () => {
   it('wraps the reported step result with the step-report site', () => {
     const context = assembleGateContext({status: 'failed', exitCode: 1});
 
+    expect(Object.keys(context.values).sort()).toEqual(
+      [...getWorkflowPredicateContextRoots('step.success')].sort(),
+    );
     expect(context).toEqual({
       site: 'step-report',
       values: {
+        vars: {},
         step: {
           exit_code: 1n,
           status: 'failed',
@@ -845,11 +968,16 @@ describe('assembleJobResolutionContext', () => {
       jobExecution({sequence: 1, name: 'Second', status: 'succeeded', finishedAt: date}),
     ];
 
-    const context = assembleJobResolutionContext(executions);
+    const context = assembleJobResolutionContext({executions, jobs: []});
 
+    expect(Object.keys(context.values).sort()).toEqual(
+      [...getWorkflowPredicateContextRoots('job.success')].sort(),
+    );
     expect(context).toEqual({
       site: 'job-resolution',
       values: {
+        jobs: {},
+        vars: {},
         executions: [
           {
             index: 0,
@@ -863,6 +991,10 @@ describe('assembleJobResolutionContext', () => {
                 event: 'push',
                 delivery_id: 'delivery-1',
                 received_at: '2026-06-30T12:00:00.000Z',
+                project: null,
+                repository: null,
+                ref: null,
+                commit: null,
                 data: {ref: 'refs/heads/main'},
               },
             ],
@@ -880,6 +1012,10 @@ describe('assembleJobResolutionContext', () => {
                 event: 'push',
                 delivery_id: 'delivery-1',
                 received_at: '2026-06-30T12:00:00.000Z',
+                project: null,
+                repository: null,
+                ref: null,
+                commit: null,
                 data: {ref: 'refs/heads/main'},
               },
             ],
@@ -894,7 +1030,9 @@ describe('assembleJobResolutionContext', () => {
 describe('assembleExecutionResolutionContext', () => {
   const run = {
     id: 'run-1',
+    number: 1,
     name: 'Build',
+    workflowName: 'Build',
     definitionId: 'def-1',
     projectId: 'proj-1',
     workspaceId: 'workspace-1',
@@ -995,6 +1133,7 @@ function jobExecution(overrides: Partial<JobExecution> = {}): JobExecution {
     id: 'exec-1',
     jobId: 'job-1',
     sequence: 2,
+    nameOverride: 'Deploy',
     name: 'Deploy',
     runner: null,
     status: 'running',
@@ -1005,6 +1144,10 @@ function jobExecution(overrides: Partial<JobExecution> = {}): JobExecution {
         event: 'push',
         delivery_id: 'delivery-1',
         received_at: '2026-06-30T12:00:00.000Z',
+        project: null,
+        repository: null,
+        ref: null,
+        commit: null,
         data: {ref: 'refs/heads/main'},
       },
     ],

package/src/core/step-config/assemble-run-context.ts

@@ -1,12 +1,18 @@
 import {
   analyzeContextRootKeyAccess,
   extractExactContextRoots,
+  getWorkflowPredicateContextRoots,
   type WorkflowExpressionEvaluationContext,
+  type WorkflowPredicateContextRoot,
 } from '@shipfox/expression';
 import type {Job, JobListeningTrigger} from '#core/entities/job.js';
 import type {JobExecution} from '#core/entities/job-execution.js';
 import type {Step, StepAttempt, StepStatus} from '#core/entities/step.js';
-import type {TriggerPayload, WorkflowRun} from '#core/entities/workflow-run.js';
+import type {
+  TriggerPayload,
+  WorkflowRun,
+  WorkflowRunTriggerReference,
+} from '#core/entities/workflow-run.js';
 import type {WorkflowEvaluationContext} from './workflow-evaluation-context.js';
 
 export interface JobContextInput {
@@ -17,8 +23,15 @@ export interface JobContextInput {
 export interface AssembleWorkflowRunContextParams {
   readonly run: Pick<
     WorkflowRun,
-    'id' | 'name' | 'definitionId' | 'projectId' | 'workspaceId' | 'createdAt'
-  >;
+    | 'id'
+    | 'number'
+    | 'name'
+    | 'workflowName'
+    | 'definitionId'
+    | 'projectId'
+    | 'workspaceId'
+    | 'createdAt'
+  > & {readonly triggerReference?: WorkflowRunTriggerReference | null | undefined};
   readonly triggerPayload: TriggerPayload;
   readonly inputs?: Record<string, unknown> | null | undefined;
   readonly vars?: Record<string, string> | undefined;
@@ -27,11 +40,16 @@ export interface AssembleWorkflowRunContextParams {
 export function assembleWorkflowRunContext(
   params: AssembleWorkflowRunContextParams,
 ): WorkflowExpressionEvaluationContext {
+  const triggerReference = params.run.triggerReference;
   return {
+    workflow: {
+      id: params.run.definitionId,
+      name: params.run.workflowName,
+    },
     run: {
       id: params.run.id,
+      number: params.run.number,
       name: params.run.name,
-      definition_id: params.run.definitionId,
       project_id: params.run.projectId,
       workspace_id: params.run.workspaceId,
       created_at: params.run.createdAt,
@@ -39,6 +57,10 @@ export function assembleWorkflowRunContext(
     trigger: {
       source: params.triggerPayload.source,
       event: params.triggerPayload.event,
+      project: triggerReference?.project ?? null,
+      repository: triggerReference?.repository ?? null,
+      ref: triggerReference?.ref ?? null,
+      commit: triggerReference?.commit ?? null,
     },
     event: 'data' in params.triggerPayload ? params.triggerPayload.data : null,
     inputs: params.inputs ?? null,
@@ -56,8 +78,9 @@ export function assembleCreationContext(
 }
 
 export interface AssembleExecutionCreationContextParams extends AssembleWorkflowRunContextParams {
-  readonly jobId: string;
+  readonly job: Pick<Job, 'id' | 'key' | 'name'>;
   readonly sequence: number;
+  readonly nameOverride: string | null;
   readonly executionName: string;
   readonly status: JobExecution['status'];
   readonly triggerEvents: readonly JobExecution['triggerEvents'][number][];
@@ -68,9 +91,10 @@ export function assembleExecutionCreationContext(
   params: AssembleExecutionCreationContextParams,
 ): WorkflowEvaluationContext {
   const execution: JobExecution = {
-    id: `${params.jobId}:${params.sequence}`,
-    jobId: params.jobId,
+    id: `${params.job.id}:${params.sequence}`,
+    jobId: params.job.id,
     sequence: params.sequence,
+    nameOverride: params.nameOverride,
     name: params.executionName,
     runner: null,
     status: params.status,
@@ -92,6 +116,7 @@ export function assembleExecutionCreationContext(
     values: {
       ...assembleWorkflowRunContext(params),
       ...executions,
+      job: {key: params.job.key, name: params.job.name ?? params.job.key},
       execution: executionValues.at(-1),
     },
   };
@@ -142,11 +167,13 @@ export function assembleJobActivationContext(
       ...assembleWorkflowRunContext(params),
       ...assembleJobsContext(params.jobs),
       needs: params.jobs.map(assembleJobContext),
+      vars: params.vars ?? {},
     },
   };
 }
 
-type ListenerSnapshotRoot = 'run' | 'trigger' | 'inputs' | 'job' | 'jobs';
+type ListenerPredicateField = 'listener.on' | 'listener.until';
+type ListenerSnapshotRoot = Exclude<WorkflowPredicateContextRoot<ListenerPredicateField>, 'event'>;
 
 export interface MatcherSnapshotPlan {
   readonly matcher: JobListeningTrigger;
@@ -167,14 +194,17 @@ export function planListenerFilterSnapshots(params: {
 }): ListenerSnapshotPlan {
   const roots = new Set<ListenerSnapshotRoot>();
   const jobKeys = new Set<string>();
-  const on = params.on.map((matcher) => planMatcherFilterSnapshot(matcher, roots, jobKeys));
+  const on = params.on.map((matcher) =>
+    planMatcherFilterSnapshot('listener.on', matcher, roots, jobKeys),
+  );
   const until = (params.until ?? []).map((matcher) =>
-    planMatcherFilterSnapshot(matcher, roots, jobKeys),
+    planMatcherFilterSnapshot('listener.until', matcher, roots, jobKeys),
   );
   return {on, until, roots, jobKeys};
 }
 
 function planMatcherFilterSnapshot(
+  field: ListenerPredicateField,
   matcher: JobListeningTrigger,
   allRoots: Set<ListenerSnapshotRoot>,
   allJobKeys: Set<string>,
@@ -183,9 +213,9 @@ function planMatcherFilterSnapshot(
 
   let roots: ListenerSnapshotRoot[];
   try {
-    roots = extractExactContextRoots(matcher.filter)
-      .filter((root) => root !== 'event')
-      .filter(isListenerSnapshotRoot);
+    roots = extractExactContextRoots(matcher.filter).filter((root) =>
+      isListenerSnapshotRoot(field, root),
+    );
   } catch {
     return {matcher, roots: new Set(), jobKeys: new Set()};
   }
@@ -205,27 +235,40 @@ function planMatcherFilterSnapshot(
   return {matcher, roots: new Set(roots), jobKeys};
 }
 
-function isListenerSnapshotRoot(root: string): root is ListenerSnapshotRoot {
+function isListenerSnapshotRoot(
+  field: ListenerPredicateField,
+  root: string,
+): root is ListenerSnapshotRoot {
   return (
-    root === 'run' || root === 'trigger' || root === 'inputs' || root === 'job' || root === 'jobs'
+    root !== 'event' &&
+    getWorkflowPredicateContextRoots(field).includes(
+      root as WorkflowPredicateContextRoot<ListenerPredicateField>,
+    )
   );
 }
 
 export function assembleListenerSnapshotContext(params: {
-  readonly job: Pick<Job, 'key'>;
+  readonly job: Pick<Job, 'key'> & Partial<Pick<Job, 'name'>>;
   readonly run: AssembleWorkflowRunContextParams['run'];
   readonly triggerPayload: TriggerPayload;
   readonly inputs?: Record<string, unknown> | null | undefined;
+  readonly vars?: Record<string, string> | undefined;
   readonly plan: ListenerSnapshotPlan;
   readonly dependencyJobs: readonly JobContextInput[];
 }): WorkflowExpressionEvaluationContext {
   const context: Record<string, unknown> = {};
-  if (params.plan.roots.has('run') || params.plan.roots.has('trigger')) {
+  if (
+    params.plan.roots.has('workflow') ||
+    params.plan.roots.has('run') ||
+    params.plan.roots.has('trigger')
+  ) {
     const runContext = assembleWorkflowRunContext({
       run: params.run,
       triggerPayload: params.triggerPayload,
       inputs: params.inputs,
+      vars: params.vars,
     });
+    if (params.plan.roots.has('workflow')) context.workflow = runContext.workflow;
     if (params.plan.roots.has('run')) context.run = runContext.run;
     if (params.plan.roots.has('trigger')) context.trigger = runContext.trigger;
   }
@@ -233,8 +276,14 @@ export function assembleListenerSnapshotContext(params: {
   if (params.plan.roots.has('inputs')) {
     context.inputs = params.inputs ?? null;
   }
+  if (params.plan.roots.has('vars')) {
+    context.vars = params.vars ?? {};
+  }
   if (params.plan.roots.has('job')) {
-    context.job = {key: params.job.key};
+    context.job = {
+      key: params.job.key,
+      ...(params.job.name === undefined ? {} : {name: params.job.name ?? params.job.key}),
+    };
   }
   if (params.plan.roots.has('jobs')) {
     context.jobs = requestedJobsContext(params.dependencyJobs, params.plan.jobKeys);
@@ -376,6 +425,7 @@ export function assembleStepDispatchContext(params: {
   readonly targetStepId: string;
   readonly jobExecution?: JobExecution;
   readonly jobs?: readonly JobContextInput[];
+  readonly vars?: Record<string, string> | undefined;
 }): WorkflowEvaluationContext {
   const targetStep = params.steps.find((step) => step.id === params.targetStepId);
   const stepAttemptContext = buildStepAttemptContext(params);
@@ -392,7 +442,8 @@ export function assembleStepDispatchContext(params: {
   return {
     site: 'step-dispatch',
     values: {
-      ...(params.jobs === undefined ? {} : assembleJobsContext(params.jobs)),
+      vars: params.vars ?? {},
+      ...assembleJobsContext(params.jobs ?? []),
       ...(params.jobExecution === undefined
         ? {}
         : {
@@ -479,10 +530,12 @@ export function assembleGateContext(params: {
   readonly status: StepStatus;
   readonly exitCode: number | null;
   readonly output?: Record<string, unknown> | null | undefined;
+  readonly vars?: Record<string, string> | undefined;
 }): WorkflowEvaluationContext {
   return {
     site: 'step-report',
     values: {
+      vars: params.vars ?? {},
       step: {
         ...(params.exitCode === null ? {} : {exit_code: BigInt(params.exitCode)}),
         status: params.status,
@@ -492,12 +545,18 @@ export function assembleGateContext(params: {
   };
 }
 
-export function assembleJobResolutionContext(
-  executions: readonly JobExecution[],
-): WorkflowEvaluationContext {
+export function assembleJobResolutionContext(params: {
+  readonly executions: readonly JobExecution[];
+  readonly jobs: readonly JobContextInput[];
+  readonly vars?: Record<string, string> | undefined;
+}): WorkflowEvaluationContext {
   return {
     site: 'job-resolution',
-    values: assembleExecutionsContext(executions),
+    values: {
+      ...assembleExecutionsContext(params.executions),
+      ...assembleJobsContext(params.jobs),
+      vars: params.vars ?? {},
+    },
   };
 }
 
@@ -506,7 +565,7 @@ export function assembleExecutionResolutionContext(params: {
   readonly triggerPayload: TriggerPayload;
   readonly inputs?: Record<string, unknown> | null | undefined;
   readonly vars?: Record<string, string> | undefined;
-  readonly job: Pick<Job, 'key'>;
+  readonly job: Pick<Job, 'key'> & Partial<Pick<Job, 'name'>>;
   readonly jobExecution: JobExecution;
   readonly executions: readonly JobExecution[];
   readonly steps: readonly Step[];
@@ -528,7 +587,10 @@ export function assembleExecutionResolutionContext(params: {
         params.jobExecution,
         executionIndex < 0 ? params.jobExecution.sequence - 1 : executionIndex,
       ),
-      job: {key: params.job.key},
+      job: {
+        key: params.job.key,
+        ...(params.job.name === undefined ? {} : {name: params.job.name ?? params.job.key}),
+      },
       steps: assembleStepsContext({steps: params.steps, attempts: params.attempts}),
     },
   };