@shipfox/api-definitions 2.0.0

package/src/core/workflow-model/validate-job-references.ts

@@ -0,0 +1,54 @@
+import {
+  analyzeContextRootKeyAccess,
+  type WorkflowExpression,
+  type WorkflowInterpolationField,
+  type WorkflowPredicateField,
+} from '@shipfox/expression';
+import type {
+  WorkflowModelValidationIssue,
+  WorkflowModelValidationIssuePathSegment,
+} from './invalid-workflow-model-error.js';
+import {issue} from './validation-issue.js';
+import {workflowFieldLabel} from './workflow-field-label.js';
+
+export function validateDirectJobReferences(params: {
+  source: string;
+  expression: WorkflowExpression;
+  field: WorkflowInterpolationField | WorkflowPredicateField;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  allowedJobReferences: ReadonlySet<string>;
+}): WorkflowModelValidationIssue | undefined {
+  const access = analyzeContextRootKeyAccess(params.expression, ['jobs']);
+  const [computed] = access.violations;
+  if (computed !== undefined) {
+    return issue({
+      code: 'computed-context-key',
+      message: `${workflowFieldLabel(params.field)} must reference jobs with a literal dot key.`,
+      path: params.path,
+      details: {
+        field: params.field,
+        source: params.source,
+        expression: computed.source,
+        contextRoots: ['jobs'],
+      },
+    });
+  }
+
+  const missing = access.references.find(
+    (reference) => !params.allowedJobReferences.has(reference.key),
+  );
+  if (missing === undefined) return undefined;
+
+  return issue({
+    code: 'missing-job-needs-edge',
+    message: `${workflowFieldLabel(params.field)} references job "${missing.key}" without a direct needs edge.`,
+    path: params.path,
+    details: {
+      field: params.field,
+      source: params.source,
+      expression: params.expression.source,
+      job: missing.key,
+      allowedJobs: [...params.allowedJobReferences],
+    },
+  });
+}

package/src/core/workflow-model/validate-predicate-expression.test.ts

@@ -0,0 +1,161 @@
+import type {ExpressionTypeEnvironment} from '@shipfox/expression';
+import type {WorkflowModelValidationIssue} from './invalid-workflow-model-error.js';
+import {validatePredicateExpression} from './validate-predicate-expression.js';
+
+function validate(params: {
+  source: string;
+  field: Parameters<typeof validatePredicateExpression>[0]['field'];
+  site: Parameters<typeof validatePredicateExpression>[0]['site'];
+  allowedJobReferences?: ReadonlySet<string>;
+  typeOverlay?: ExpressionTypeEnvironment;
+}): {
+  readonly expression: ReturnType<typeof validatePredicateExpression>;
+  readonly issues: WorkflowModelValidationIssue[];
+} {
+  const issues: WorkflowModelValidationIssue[] = [];
+  const expression = validatePredicateExpression({
+    field: params.field,
+    source: params.source,
+    site: params.site,
+    path: ['predicate'],
+    invalidCode: 'invalid-job-success',
+    invalidMessage: 'Predicate must be a valid CEL boolean expression.',
+    issues,
+    ...(params.allowedJobReferences === undefined
+      ? {}
+      : {allowedJobReferences: params.allowedJobReferences}),
+    ...(params.typeOverlay === undefined ? {} : {typeOverlay: params.typeOverlay}),
+  });
+
+  return {expression, issues};
+}
+
+describe('validatePredicateExpression', () => {
+  it.each([
+    ['event.ref == "refs/heads/main"', 'syntax'],
+    ['trigger.event == "push"', 'typed'],
+    ['has(event.ref)', 'syntax'],
+  ] as const)('accepts trigger filters at ingest: %s', (source, check) => {
+    const result = validate({field: 'trigger.filter', source, site: 'ingest'});
+
+    expect(result.issues).toEqual([]);
+    expect(result.expression).toMatchObject({source, check});
+  });
+
+  it.each([
+    ['event.ref', 'Predicate source must be boolean-shaped.'],
+    ['trigger.event', 'must return bool'],
+  ])('rejects non-boolean trigger filters: %s', (source, reason) => {
+    const result = validate({field: 'trigger.filter', source, site: 'ingest'});
+
+    expect(result.expression).toBeUndefined();
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        code: 'invalid-job-success',
+        details: expect.objectContaining({
+          source,
+          reason: expect.stringContaining(reason),
+        }),
+      }),
+    ]);
+  });
+
+  it.each([
+    'run.id == "run-1"',
+    'inputs.env == "prod"',
+    'jobs.build.status == "succeeded"',
+  ])('rejects trigger filter roots that are unavailable at ingest: %s', (source) => {
+    const result = validate({field: 'trigger.filter', source, site: 'ingest'});
+
+    expect(result.expression).toBeUndefined();
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        code: 'context-unavailable-at-predicate-site',
+        details: expect.objectContaining({field: 'trigger.filter', source, site: 'ingest'}),
+      }),
+    ]);
+  });
+
+  it.each([
+    ['runner.os == "linux"', 'runner-context-in-server-predicate'],
+    ['vars.ENV == "prod"', 'vars-context-in-server-predicate'],
+  ])('rejects forbidden server predicate roots: %s', (source, code) => {
+    const result = validate({field: 'trigger.filter', source, site: 'ingest'});
+
+    expect(result.expression).toBeUndefined();
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        code,
+        details: expect.objectContaining({field: 'trigger.filter', source}),
+      }),
+    ]);
+  });
+
+  it.each([
+    ['listener.on', 'event.action == "created"', undefined],
+    ['listener.on', 'run.id == "run-1"', undefined],
+    ['listener.until', 'inputs.target == event.issue.number', undefined],
+    ['listener.until', 'job.key == "await-review"', undefined],
+    ['listener.on', 'executions.all(execution, execution.status != "")', undefined],
+    ['listener.until', 'execution.status == "waiting"', undefined],
+    ['listener.on', 'matrix.os == "linux"', undefined],
+    ['listener.until', 'jobs.build.outputs.pr_number == event.issue.number', new Set(['build'])],
+    ['listener.until', 'has(jobs.build.outputs.pr_number)', new Set(['build'])],
+  ] as const)('accepts listener filters at job activation: %s %s', (field, source, allowedJobs) => {
+    const result = validate({
+      field,
+      source,
+      site: 'job-activation',
+      ...(allowedJobs === undefined ? {} : {allowedJobReferences: allowedJobs}),
+    });
+
+    expect(result.issues).toEqual([]);
+    expect(result.expression).toMatchObject({source});
+  });
+
+  it.each([
+    'step.status == "succeeded"',
+    'steps.build.outputs.sha == "abc"',
+  ])('rejects listener roots that are unavailable at job activation: %s', (source) => {
+    const result = validate({field: 'listener.on', source, site: 'job-activation'});
+
+    expect(result.expression).toBeUndefined();
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        code: 'context-unavailable-at-predicate-site',
+        details: expect.objectContaining({field: 'listener.on', source, site: 'job-activation'}),
+      }),
+    ]);
+  });
+
+  it('rejects listener job references without a direct needs edge', () => {
+    const result = validate({
+      field: 'listener.on',
+      source: 'jobs.build.outputs.pr_number == event.issue.number',
+      site: 'job-activation',
+      allowedJobReferences: new Set(['test']),
+    });
+
+    expect(result.expression).toBeUndefined();
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        code: 'missing-job-needs-edge',
+        details: expect.objectContaining({field: 'listener.on', job: 'build'}),
+      }),
+    ]);
+  });
+
+  it('keeps existing job success syntax-only behavior unchanged', () => {
+    const result = validate({
+      field: 'job.success',
+      source: 'jobs.build.outputs.ready',
+      site: 'job-resolution',
+    });
+
+    expect(result.issues).toEqual([]);
+    expect(result.expression).toMatchObject({
+      source: 'jobs.build.outputs.ready',
+      check: 'syntax',
+    });
+  });
+});

package/src/core/workflow-model/validate-predicate-expression.ts

@@ -0,0 +1,406 @@
+import {
+  type AvailabilitySite,
+  analyzeContextRootKeyAccess,
+  availabilitySites,
+  createWorkflowExpression,
+  type ExpressionTypeEnvironment,
+  extractExactContextRoots,
+  getWorkflowContextDefinition,
+  getWorkflowContextTypeEnvironment,
+  InvalidWorkflowExpressionError,
+  predicateSourceIsBooleanShaped,
+  resolveContextRootAvailability,
+  resolveContextRootHost,
+  routeExpression,
+  validateServerEvaluable,
+  type WorkflowContextName,
+  type WorkflowExpression,
+  type WorkflowPredicateField,
+  workflowContextNames,
+} from '@shipfox/expression';
+import type {
+  WorkflowModelValidationIssue,
+  WorkflowModelValidationIssueCode,
+  WorkflowModelValidationIssuePathSegment,
+} from './invalid-workflow-model-error.js';
+import {validateDirectJobReferences} from './validate-job-references.js';
+import {issue} from './validation-issue.js';
+import {workflowFieldLabel} from './workflow-field-label.js';
+
+export function validatePredicateExpression(params: {
+  field: WorkflowPredicateField;
+  source: string;
+  site: AvailabilitySite;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  invalidCode: WorkflowModelValidationIssueCode;
+  invalidMessage: string;
+  issues: WorkflowModelValidationIssue[];
+  allowedJobReferences?: ReadonlySet<string>;
+  typeOverlay?: ExpressionTypeEnvironment | undefined;
+}): WorkflowExpression | undefined {
+  const syntaxExpression = createSyntaxExpression(params);
+  if (syntaxExpression === undefined) return undefined;
+
+  const contextRoots = extractExactContextRoots(syntaxExpression.source);
+  const knownRoots = contextRoots.filter((root) => resolveContextRootHost(root) !== undefined);
+  const unknownRoots = contextRoots.filter((root) => resolveContextRootHost(root) === undefined);
+
+  if (unknownRoots.length > 0) {
+    params.issues.push(invalidPredicateIssue({...params, contextRoots}));
+    return undefined;
+  }
+
+  const serverEvaluability = validateServerEvaluable(syntaxExpression);
+  if (!serverEvaluability.ok) {
+    params.issues.push(
+      ...serverEvaluability.violations.map((violation) =>
+        runnerContextInServerPredicateIssue({
+          ...params,
+          contextRoots,
+          runnerRoots: violation.runnerRoots,
+        }),
+      ),
+    );
+    return undefined;
+  }
+
+  const varsRoots = knownRoots.filter((root) => root === 'vars');
+  if (varsRoots.length > 0) {
+    params.issues.push(varsContextInServerPredicateIssue({...params, contextRoots}));
+    return undefined;
+  }
+
+  const unavailableRoots = knownRoots.filter((root) => !isRootAvailableAt(root, params.site));
+  if (unavailableRoots.length > 0) {
+    params.issues.push(
+      unavailablePredicateContextIssue({...params, contextRoots, unavailableRoots}),
+    );
+    return undefined;
+  }
+
+  const route = routeExpression(syntaxExpression);
+  if (route.fillTarget !== 'runner-fill' && !isSiteAtOrAfter(params.site, route.fillTarget)) {
+    const unavailableRoots = unavailableRouteReferences(syntaxExpression);
+    params.issues.push(
+      unavailableRoots.length > 0
+        ? unavailablePredicateContextIssue({
+            ...params,
+            contextRoots,
+            unavailableRoots,
+          })
+        : routeUnavailablePredicateContextIssue({
+            ...params,
+            contextRoots,
+            fillTarget: route.fillTarget,
+          }),
+    );
+    return undefined;
+  }
+
+  const invalidJobReferenceIssue =
+    params.allowedJobReferences === undefined
+      ? undefined
+      : validateDirectJobReferences({
+          source: params.source,
+          expression: syntaxExpression,
+          field: params.field,
+          path: params.path,
+          allowedJobReferences: params.allowedJobReferences,
+        });
+  if (invalidJobReferenceIssue !== undefined) {
+    params.issues.push(invalidJobReferenceIssue);
+    return undefined;
+  }
+
+  if (params.typeOverlay === undefined && knownRoots.some((root) => hasSyntaxOnlyCheckMode(root))) {
+    if (
+      isWorkflowFilterPredicateField(params.field) &&
+      !predicateSourceIsBooleanShaped(syntaxExpression.source)
+    ) {
+      params.issues.push(
+        invalidPredicateIssue({
+          ...params,
+          contextRoots,
+          reason: 'Predicate source must be boolean-shaped.',
+        }),
+      );
+      return undefined;
+    }
+
+    return syntaxExpression;
+  }
+
+  try {
+    return createWorkflowExpression({
+      source: params.source,
+      check: {
+        mode: 'typed',
+        // `undefined` preserves the legacy syntax-only path above. `{}` means
+        // callers intentionally requested typed checking with the standard roots.
+        typeEnvironment: mergeTypeEnvironments(knownRoots, params.typeOverlay),
+        expectedResultType: 'bool',
+      },
+    });
+  } catch (error) {
+    params.issues.push(
+      invalidPredicateIssue({
+        ...params,
+        contextRoots,
+        reason:
+          error instanceof InvalidWorkflowExpressionError
+            ? error.reason
+            : 'Expression source did not parse or type-check.',
+      }),
+    );
+    return undefined;
+  }
+}
+
+function createSyntaxExpression(params: {
+  field: WorkflowPredicateField;
+  source: string;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  invalidCode: WorkflowModelValidationIssueCode;
+  invalidMessage: string;
+  issues: WorkflowModelValidationIssue[];
+}): WorkflowExpression | undefined {
+  try {
+    return createWorkflowExpression({
+      source: params.source,
+      check: {mode: 'syntax'},
+    });
+  } catch (error) {
+    params.issues.push(
+      invalidPredicateIssue({
+        ...params,
+        contextRoots: [],
+        reason:
+          error instanceof InvalidWorkflowExpressionError
+            ? error.reason
+            : 'Expression source did not parse or type-check.',
+      }),
+    );
+    return undefined;
+  }
+}
+
+function invalidPredicateIssue(params: {
+  field: WorkflowPredicateField;
+  source: string;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  invalidCode: WorkflowModelValidationIssueCode;
+  invalidMessage: string;
+  contextRoots: readonly string[];
+  reason?: string;
+}): WorkflowModelValidationIssue {
+  return issue({
+    code: params.invalidCode,
+    message: params.invalidMessage,
+    path: params.path,
+    details: {
+      field: params.field,
+      source: params.source,
+      contextRoots: params.contextRoots,
+      reason: params.reason ?? 'Expression source did not parse or type-check.',
+    },
+  });
+}
+
+const availabilitySiteLabels = {
+  ingest: 'ingest',
+  'run-creation': 'run creation',
+  'execution-creation': 'execution creation',
+  'job-activation': 'job activation',
+  'step-dispatch': 'step dispatch',
+  'step-report': 'step reporting',
+  'execution-resolution': 'execution resolution',
+  'job-resolution': 'job resolution',
+} as const satisfies Record<AvailabilitySite, string>;
+
+function runnerContextInServerPredicateIssue(params: {
+  field: WorkflowPredicateField;
+  source: string;
+  site: AvailabilitySite;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  contextRoots: readonly string[];
+  runnerRoots: readonly string[];
+}): WorkflowModelValidationIssue {
+  return issue({
+    code: 'runner-context-in-server-predicate',
+    message: `${fieldLabel(params.field)} cannot reference runner context ${formatList(
+      params.runnerRoots,
+    )} because it is evaluated on the server at ${describeAvailabilitySite(params.site)}.`,
+    path: params.path,
+    details: {
+      field: params.field,
+      source: params.source,
+      contextRoots: params.contextRoots,
+      runnerRoots: params.runnerRoots,
+      site: params.site,
+    },
+  });
+}
+
+function varsContextInServerPredicateIssue(params: {
+  field: WorkflowPredicateField;
+  source: string;
+  site: AvailabilitySite;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  contextRoots: readonly string[];
+}): WorkflowModelValidationIssue {
+  return issue({
+    code: 'vars-context-in-server-predicate',
+    message: `${fieldLabel(params.field)} cannot reference vars because predicate evaluation does not include workflow variables.`,
+    path: params.path,
+    details: {
+      field: params.field,
+      source: params.source,
+      contextRoots: params.contextRoots,
+      rejectedRoots: ['vars'],
+      site: params.site,
+    },
+  });
+}
+
+function unavailablePredicateContextIssue(params: {
+  field: WorkflowPredicateField;
+  source: string;
+  site: AvailabilitySite;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  contextRoots: readonly string[];
+  unavailableRoots: readonly string[];
+}): WorkflowModelValidationIssue {
+  return issue({
+    code: 'context-unavailable-at-predicate-site',
+    message: `${fieldLabel(params.field)} references ${contextNoun(
+      params.unavailableRoots,
+    )} ${formatList(params.unavailableRoots)} that ${availabilityVerb(
+      params.unavailableRoots,
+    )} not available at ${describeAvailabilitySite(params.site)}. ${params.unavailableRoots
+      .map(unavailableRootAvailabilityMessage)
+      .join(' ')}`,
+    path: params.path,
+    details: {
+      field: params.field,
+      source: params.source,
+      contextRoots: params.contextRoots,
+      unavailableRoots: params.unavailableRoots,
+      site: params.site,
+    },
+  });
+}
+
+function routeUnavailablePredicateContextIssue(params: {
+  field: WorkflowPredicateField;
+  source: string;
+  site: AvailabilitySite;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  contextRoots: readonly string[];
+  fillTarget: AvailabilitySite;
+}): WorkflowModelValidationIssue {
+  return issue({
+    code: 'context-unavailable-at-predicate-site',
+    message: `${fieldLabel(params.field)} requires context filled at ${describeAvailabilitySite(
+      params.fillTarget,
+    )}, but it is evaluated at ${describeAvailabilitySite(params.site)}.`,
+    path: params.path,
+    details: {
+      field: params.field,
+      source: params.source,
+      contextRoots: params.contextRoots,
+      fillTarget: params.fillTarget,
+      site: params.site,
+    },
+  });
+}
+
+function isRootAvailableAt(root: string, site: AvailabilitySite): boolean {
+  const availability = resolveContextRootAvailability(root);
+  if (availability === undefined) return false;
+
+  return availabilitySites.indexOf(availability) <= availabilitySites.indexOf(site);
+}
+
+function unavailableRootAvailabilityMessage(root: string): string {
+  if (root === 'execution.failed') {
+    return '"execution.failed" becomes available at step dispatch.';
+  }
+
+  const availability = resolveContextRootAvailability(root);
+  if (availability === undefined) return `"${root}" is not available at any server site.`;
+  return `"${root}" becomes available at ${describeAvailabilitySite(availability)}.`;
+}
+
+function unavailableRouteReferences(expression: WorkflowExpression): readonly string[] {
+  const access = analyzeContextRootKeyAccess(expression, ['execution']);
+  return access.references.some((reference) => reference.key === 'failed')
+    ? ['execution.failed']
+    : [];
+}
+
+function hasSyntaxOnlyCheckMode(root: string): boolean {
+  if (!isWorkflowContextName(root)) return resolveContextRootHost(root) === 'server';
+  return isWorkflowContextName(root) && getWorkflowContextDefinition(root).checkMode === 'syntax';
+}
+
+function mergeTypeEnvironments(
+  roots: readonly string[],
+  typeOverlay?: ExpressionTypeEnvironment,
+): ExpressionTypeEnvironment {
+  const typeEnvironment: Record<string, ExpressionTypeEnvironment[string]> = {};
+
+  for (const root of roots) {
+    const overlayType = typeOverlay?.[root];
+    if (overlayType !== undefined) {
+      typeEnvironment[root] = overlayType;
+      continue;
+    }
+
+    if (!isWorkflowContextName(root)) {
+      if (typeOverlay !== undefined) typeEnvironment[root] = {kind: 'map'};
+      continue;
+    }
+
+    const contextTypeEnvironment = getWorkflowContextTypeEnvironment(root);
+    if (contextTypeEnvironment === undefined) {
+      if (typeOverlay !== undefined) typeEnvironment[root] = {kind: 'map'};
+      continue;
+    }
+
+    Object.assign(typeEnvironment, contextTypeEnvironment);
+  }
+
+  return typeEnvironment;
+}
+
+function isWorkflowContextName(root: string): root is WorkflowContextName {
+  return (workflowContextNames as readonly string[]).includes(root);
+}
+
+function isWorkflowFilterPredicateField(field: WorkflowPredicateField): boolean {
+  return field === 'trigger.filter' || field === 'listener.on' || field === 'listener.until';
+}
+
+function fieldLabel(field: WorkflowPredicateField): string {
+  return workflowFieldLabel(field);
+}
+
+function contextNoun(roots: readonly string[]): 'context' | 'contexts' {
+  return roots.length === 1 ? 'context' : 'contexts';
+}
+
+function availabilityVerb(roots: readonly string[]): 'is' | 'are' {
+  return roots.length === 1 ? 'is' : 'are';
+}
+
+function describeAvailabilitySite(site: AvailabilitySite): string {
+  return availabilitySiteLabels[site];
+}
+
+function isSiteAtOrAfter(site: AvailabilitySite, fillTarget: AvailabilitySite): boolean {
+  return availabilitySites.indexOf(site) >= availabilitySites.indexOf(fillTarget);
+}
+
+function formatList(values: readonly string[]): string {
+  return values.map((value) => `"${value}"`).join(', ');
+}

package/src/core/workflow-model/validation-issue.ts

@@ -0,0 +1,27 @@
+import type {
+  WorkflowModelValidationIssue,
+  WorkflowModelValidationIssueCode,
+  WorkflowModelValidationIssuePathSegment,
+} from './invalid-workflow-model-error.js';
+
+export function issue(params: {
+  code: WorkflowModelValidationIssueCode;
+  message: string;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  details?: Readonly<Record<string, unknown>>;
+}): WorkflowModelValidationIssue {
+  if (params.details === undefined) {
+    return {
+      code: params.code,
+      message: params.message,
+      path: params.path,
+    };
+  }
+
+  return {
+    code: params.code,
+    message: params.message,
+    path: params.path,
+    details: params.details,
+  };
+}

package/src/core/workflow-model/workflow-field-label.ts

@@ -0,0 +1,50 @@
+import type {WorkflowInterpolationField, WorkflowPredicateField} from '@shipfox/expression';
+
+export function workflowFieldLabel(
+  field: WorkflowInterpolationField | WorkflowPredicateField,
+): string {
+  switch (field) {
+    case 'run':
+      return 'Run command interpolation';
+    case 'env.value':
+      return 'Env value interpolation';
+    case 'agent.prompt':
+      return 'Agent prompt interpolation';
+    case 'agent.model':
+      return 'Agent model interpolation';
+    case 'agent.provider':
+      return 'Agent provider interpolation';
+    case 'agent.thinking':
+      return 'Agent thinking';
+    case 'job.runner':
+      return 'Job runner interpolation';
+    case 'job.outputs':
+      return 'Job outputs mapping';
+    case 'job.name':
+      return 'Job name interpolation';
+    case 'step.name':
+      return 'Step name interpolation';
+    case 'step.success':
+      return 'Step gate success';
+    case 'step.feedback':
+      return 'Step feedback';
+    case 'job.success':
+      return 'Job success';
+    case 'trigger.filter':
+      return 'Trigger filter';
+    case 'listener.on':
+      return 'Listener on filter';
+    case 'listener.until':
+      return 'Listener until filter';
+    case 'job.if':
+      return 'Job if';
+    case 'step.if':
+      return 'Step if';
+    default:
+      return assertNever(field);
+  }
+}
+
+function assertNever(value: never): never {
+  throw new Error(`Unhandled workflow field: ${value}`);
+}