@shipfox/api-definitions 10.2.0 → 12.0.0

package/src/core/workflow-model/normalize-workflow-document.ts

@@ -12,6 +12,8 @@ import {normalizeDependencies, validateCycles} from './normalize-dependencies.js
 import {normalizeEnv} from './normalize-env.js';
 import {normalizeJobs} from './normalize-jobs.js';
 import {normalizeTriggers} from './normalize-triggers.js';
+import {parseInterpolationField} from './parse-interpolation-field.js';
+import {unescapeLiteralName, validateLiteralName} from './validate-literal-name.js';
 
 export function normalizeWorkflowDocument(
   document: WorkflowDocument,
@@ -20,6 +22,8 @@ export function normalizeWorkflowDocument(
     agentValidationCatalog: AgentValidationCatalog;
     integrationValidationContext?: IntegrationValidationContext | undefined;
     stepSourceLocations?: WorkflowStepSourceLocationMap | undefined;
+    /** Provide a fresh array for each call to collect non-fatal validation issues. */
+    warnings?: WorkflowModelValidationIssue[] | undefined;
   },
 ): WorkflowModel {
   const issues: WorkflowModelValidationIssue[] = [];
@@ -29,6 +33,14 @@ export function normalizeWorkflowDocument(
     agentValidationCatalog: options.agentValidationCatalog,
     integrationValidationContext: options.integrationValidationContext,
   };
+  validateLiteralName({
+    field: 'workflow.name',
+    dynamicField: 'run_name',
+    source: document.name,
+    path: ['name'],
+    message: 'Workflow name must be literal. Move runtime interpolation to run_name.',
+    issues,
+  });
   const jobIdBySourceName = mapJobIds(document, issues);
   const triggers = normalizeTriggers(document, issues);
   const jobs = normalizeJobs(
@@ -40,16 +52,29 @@ export function normalizeWorkflowDocument(
   );
   const dependencies = normalizeDependencies(document.jobs, jobIdBySourceName, issues);
   const workflowEnv = normalizeEnv({env: document.env, path: ['env'], issues});
+  const runName =
+    document.run_name === undefined
+      ? undefined
+      : (parseInterpolationField({
+          field: 'workflow.run_name',
+          source: document.run_name,
+          path: ['run_name'],
+          issues,
+          fillSite: 'run-creation',
+        }) ?? [{kind: 'literal' as const, value: document.run_name}]);
 
   validateCycles(document.jobs, jobIdBySourceName, issues);
 
-  if (issues.length > 0) {
-    throw new InvalidWorkflowModelError(issues);
-  }
+  const warnings = issues.filter((issue) => issue.severity === 'warning');
+  options.warnings?.push(...warnings);
+
+  const errors = issues.filter((issue) => issue.severity !== 'warning');
+  if (errors.length > 0) throw new InvalidWorkflowModelError(errors);
 
   return {
     kind: 'workflow',
-    name: document.name,
+    name: unescapeLiteralName(document.name),
+    ...(runName === undefined ? {} : {runName}),
     ...workflowEnv,
     triggers,
     jobs,

package/src/core/workflow-model/parse-interpolation-field.ts

@@ -2,14 +2,14 @@ import {secretKeySchema, secretStoreSchema} from '@shipfox/api-secrets-dto';
 import {
   type AvailabilitySite,
   analyzeContextKeyAccess,
+  analyzeContextRootKeyAccess,
   createWorkflowExpression,
   type ExpressionTypeEnvironment,
-  extractCelUntrustedPathAccesses,
   getWorkflowContextAvailability,
   getWorkflowContextDefinition,
   getWorkflowContextHost,
   getWorkflowContextTypeEnvironment,
-  getWorkflowContextUntrustedPaths,
+  getWorkflowInterpolationFieldSelfReference,
   InvalidWorkflowExpressionError,
   InvalidWorkflowTemplateError,
   type PlanViolation,
@@ -21,9 +21,7 @@ import {
   type WorkflowTemplateExprSegment,
   type WorkflowTemplateSegment,
   workflowContextNames,
-  workflowInterpolationFieldAcceptsContext,
   workflowInterpolationFieldAcceptsHost,
-  workflowInterpolationFieldAcceptsTrustTier,
 } from '@shipfox/expression';
 import type {WorkflowFieldTemplate} from '../entities/workflow-model.js';
 import type {
@@ -39,11 +37,19 @@ export type StoredInterpolationField =
   | 'agent.prompt'
   | 'agent.model'
   | 'agent.provider'
+  | 'agent.thinking'
   | 'job.outputs'
-  | 'job.name'
+  | 'workflow.run_name'
+  | 'job.execution_name'
   | 'job.runner'
   | 'step.name'
-  | 'step.feedback';
+  | 'step.working_directory'
+  | 'step.feedback'
+  | 'checkout.project'
+  | 'checkout.connection'
+  | 'checkout.repository'
+  | 'checkout.ref'
+  | 'checkout.path';
 
 export function parseInterpolationField(params: {
   field: StoredInterpolationField;
@@ -78,6 +84,38 @@ export function parseInterpolationField(params: {
   return plan.plan.field.segments;
 }
 
+function dynamicNameSelfReference(params: {
+  field: StoredInterpolationField;
+  source: string;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  segment: WorkflowTemplateExprSegment;
+}): WorkflowModelValidationIssue | undefined {
+  const target = getWorkflowInterpolationFieldSelfReference(params.field);
+  if (target === undefined) return undefined;
+
+  const access = analyzeContextRootKeyAccess(params.segment.expression, [target.root]);
+  const reference = access.references.find((entry) => entry.key === target.key);
+  const computedReference = access.violations.find(
+    (violation) =>
+      violation.root === target.root &&
+      (violation.key === undefined || violation.key === target.key),
+  );
+  if (reference === undefined && computedReference === undefined) return undefined;
+
+  return issue({
+    code: 'dynamic-name-self-reference',
+    message: `${fieldLabel(params.field)} interpolation cannot reference its own dynamic name.`,
+    path: params.path,
+    details: {
+      field: params.field,
+      source: params.source,
+      expression: params.segment.expression.source,
+      reference:
+        reference === undefined ? `${target.root}[computed]` : `${reference.root}.${reference.key}`,
+    },
+  });
+}
+
 function parseTemplate(params: {
   field: WorkflowInterpolationField;
   source: string;
@@ -120,14 +158,6 @@ function validateExpressionSegment(params: {
   const knownRoots = contextRoots.filter(isWorkflowContextName);
   const unknownRoots = contextRoots.filter((root) => !isWorkflowContextName(root));
 
-  const rejectedRoots = knownRoots.filter(
-    (root) => !workflowInterpolationFieldAcceptsContext(params.field, root),
-  );
-  if (rejectedRoots.length > 0) {
-    params.issues.push(untrustedContextIssue({...params, contextRoots, rejectedRoots}));
-    return undefined;
-  }
-
   const rejectedHostRoots = knownRoots.filter(
     (root) => !workflowInterpolationFieldAcceptsHost(params.field, getWorkflowContextHost(root)),
   );
@@ -151,6 +181,12 @@ function validateExpressionSegment(params: {
     return undefined;
   }
 
+  const selfReference = dynamicNameSelfReference(params);
+  if (selfReference !== undefined) {
+    params.issues.push(selfReference);
+    return undefined;
+  }
+
   const invalidReferenceIssue = validateContextKeyReferences({
     ...params,
     contextRoots,
@@ -176,14 +212,6 @@ function validateExpressionSegment(params: {
     return undefined;
   }
 
-  const rejectedPathRoots = findUntrustedPathRoots(params.segment, params.field, knownRoots);
-  if (rejectedPathRoots.length > 0) {
-    params.issues.push(
-      untrustedContextIssue({...params, contextRoots, rejectedRoots: rejectedPathRoots}),
-    );
-    return undefined;
-  }
-
   if (unknownRoots.length > 0) {
     params.issues.push(
       issue({
@@ -258,63 +286,6 @@ function validateExpressionSegment(params: {
   }
 }
 
-function findUntrustedPathRoots(
-  segment: WorkflowTemplateExprSegment,
-  field: StoredInterpolationField,
-  knownRoots: readonly WorkflowContextName[],
-): readonly WorkflowContextName[] {
-  if (!isTrustedOnlyField(field)) return [];
-
-  const untrustedPathsByRoot = new Map<string, readonly string[]>();
-  for (const root of knownRoots) {
-    const paths = getWorkflowContextUntrustedPaths(root);
-    if (paths === undefined || paths.length === 0) continue;
-    untrustedPathsByRoot.set(root, paths);
-  }
-  if (knownRoots.includes('steps')) {
-    untrustedPathsByRoot.set('steps', [
-      ...new Set([...(untrustedPathsByRoot.get('steps') ?? []), 'outputs']),
-    ]);
-  }
-  if (untrustedPathsByRoot.size === 0) return [];
-
-  return extractCelUntrustedPathAccesses({
-    source: segment.expression.source,
-    untrustedPathsByRoot,
-  }).filter(isWorkflowContextName);
-}
-
-function isTrustedOnlyField(field: StoredInterpolationField): boolean {
-  return !workflowInterpolationFieldAcceptsTrustTier(field, 'untrusted');
-}
-
-function untrustedContextIssue(params: {
-  field: WorkflowInterpolationField;
-  source: string;
-  path: readonly WorkflowModelValidationIssuePathSegment[];
-  contextRoots: readonly string[];
-  rejectedRoots: readonly WorkflowContextName[];
-}): WorkflowModelValidationIssue {
-  return issue({
-    code: 'untrusted-context-in-field',
-    message:
-      params.field === 'run'
-        ? `Run command interpolation cannot use untrusted context ${formatList(
-            params.rejectedRoots,
-          )}. Bind untrusted values to env and reference the shell variable from run instead.`
-        : `${fieldLabel(params.field)} interpolation cannot use untrusted context ${formatList(
-            params.rejectedRoots,
-          )}.`,
-    path: params.path,
-    details: {
-      field: params.field,
-      source: params.source,
-      contextRoots: params.contextRoots,
-      rejectedRoots: params.rejectedRoots,
-    },
-  });
-}
-
 function runnerContextInFieldIssue(params: {
   field: WorkflowInterpolationField;
   source: string;

package/src/core/workflow-model/validate-literal-name.ts

@@ -0,0 +1,64 @@
+import {InvalidWorkflowTemplateError, parseWorkflowTemplate} from '@shipfox/expression';
+import type {
+  WorkflowModelValidationIssue,
+  WorkflowModelValidationIssuePathSegment,
+} from './invalid-workflow-model-error.js';
+import {issue} from './validation-issue.js';
+
+/** Defense-in-depth for typed callers that bypass workflowDocumentSchema. */
+export function validateLiteralName(params: {
+  field: 'workflow.name' | 'job.name';
+  dynamicField: 'run_name' | 'execution_name';
+  source: string;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  message: string;
+  issues: WorkflowModelValidationIssue[];
+}): void {
+  try {
+    const segments = parseWorkflowTemplate(params.source);
+    if (!segments.some((segment) => segment.kind === 'expr')) return;
+  } catch (error) {
+    params.issues.push(
+      literalNameIssue({
+        ...params,
+        reason:
+          error instanceof InvalidWorkflowTemplateError
+            ? error.reason
+            : 'Template source did not parse.',
+      }),
+    );
+    return;
+  }
+
+  params.issues.push(
+    literalNameIssue({
+      ...params,
+      reason: `Static names cannot contain interpolation expressions. Use ${params.dynamicField} for runtime interpolation.`,
+    }),
+  );
+}
+
+export function unescapeLiteralName(source: string): string {
+  return source.replaceAll('$${{', '${{');
+}
+
+function literalNameIssue(params: {
+  field: 'workflow.name' | 'job.name';
+  dynamicField: 'run_name' | 'execution_name';
+  source: string;
+  path: readonly WorkflowModelValidationIssuePathSegment[];
+  message: string;
+  reason: string;
+}): WorkflowModelValidationIssue {
+  return issue({
+    code: 'invalid-interpolation-template',
+    message: params.message,
+    path: params.path,
+    details: {
+      field: params.field,
+      source: params.source,
+      dynamicField: params.dynamicField,
+      reason: params.reason,
+    },
+  });
+}

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

@@ -1,11 +1,13 @@
-import type {ExpressionTypeEnvironment} from '@shipfox/expression';
+import {
+  type ExpressionTypeEnvironment,
+  getWorkflowPredicateFieldMinimumFillTarget,
+} 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;
 }): {
@@ -16,7 +18,6 @@ function validate(params: {
   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.',
@@ -36,7 +37,7 @@ describe('validatePredicateExpression', () => {
     ['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'});
+    const result = validate({field: 'trigger.filter', source});
 
     expect(result.issues).toEqual([]);
     expect(result.expression).toMatchObject({source, check});
@@ -46,7 +47,7 @@ describe('validatePredicateExpression', () => {
     ['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'});
+    const result = validate({field: 'trigger.filter', source});
 
     expect(result.expression).toBeUndefined();
     expect(result.issues).toEqual([
@@ -64,8 +65,9 @@ describe('validatePredicateExpression', () => {
     'run.id == "run-1"',
     'inputs.env == "prod"',
     'jobs.build.status == "succeeded"',
+    'vars.ENV == "prod"',
   ])('rejects trigger filter roots that are unavailable at ingest: %s', (source) => {
-    const result = validate({field: 'trigger.filter', source, site: 'ingest'});
+    const result = validate({field: 'trigger.filter', source});
 
     expect(result.expression).toBeUndefined();
     expect(result.issues).toEqual([
@@ -78,9 +80,8 @@ describe('validatePredicateExpression', () => {
 
   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'});
+    const result = validate({field: 'trigger.filter', source});
 
     expect(result.expression).toBeUndefined();
     expect(result.issues).toEqual([
@@ -91,21 +92,98 @@ describe('validatePredicateExpression', () => {
     ]);
   });
 
+  it.each([
+    ['job.if', 'job-activation'],
+    ['step.if', 'step-dispatch'],
+    ['step.success', 'step-report'],
+    ['job.success', 'job-resolution'],
+    ['listener.on', 'job-activation'],
+    ['listener.until', 'job-activation'],
+  ] as const)('accepts vars in %s at its evaluation site', (field, site) => {
+    expect(getWorkflowPredicateFieldMinimumFillTarget(field)).toBe(site);
+    const result = validate({
+      field,
+      source: 'vars.ENABLED == "true"',
+    });
+
+    expect(result.issues).toEqual([]);
+    expect(result.expression).toMatchObject({source: 'vars.ENABLED == "true"'});
+  });
+
+  it.each([
+    ['step.success', 'step.status == "succeeded"'],
+    ['job.success', 'executions.all(e, e.status == "succeeded")'],
+    ['trigger.filter', 'event.action == "created"'],
+    ['listener.on', 'trigger.event == "pull_request"'],
+    ['listener.until', 'job.key == "await-review"'],
+    ['job.if', 'needs.exists(n, n.status == "succeeded")'],
+    ['step.if', 'execution.status == "running"'],
+  ] as const)('accepts the runtime context contract for %s', (field, source) => {
+    const result = validate({field, source});
+
+    expect(result.issues).toEqual([]);
+    expect(result.expression).toMatchObject({source});
+  });
+
+  it.each([
+    [
+      'step.success',
+      'step-report',
+      'jobs.build.status == "succeeded"',
+      'jobs',
+      'Step gate success',
+    ],
+    ['job.success', 'job-resolution', 'step.status == "succeeded"', 'step', 'Job success'],
+    ['trigger.filter', 'ingest', 'run.id == "run-1"', 'run', 'Trigger filter'],
+    [
+      'listener.on',
+      'job-activation',
+      'execution.status == "waiting"',
+      'execution',
+      'Listener on filter',
+    ],
+    [
+      'listener.until',
+      'job-activation',
+      'execution.status == "waiting"',
+      'execution',
+      'Listener until filter',
+    ],
+    ['job.if', 'job-activation', 'execution.status == "running"', 'execution', 'Job if'],
+    ['step.if', 'step-dispatch', 'run.id == "run-1"', 'run', 'Step if'],
+  ] as const)('rejects roots omitted from the %s runtime context', (field, site, source, root, label) => {
+    const result = validate({field, source});
+
+    expect(result.expression).toBeUndefined();
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        code: 'context-unavailable-at-predicate-site',
+        message: expect.stringContaining(
+          `"${root}" that is not supplied when ${label} is evaluated at`,
+        ),
+        details: expect.objectContaining({
+          field,
+          source,
+          unavailableRoots: [root],
+          site,
+        }),
+      }),
+    ]);
+  });
+
   it.each([
     ['listener.on', 'event.action == "created"', undefined],
     ['listener.on', 'run.id == "run-1"', undefined],
+    ['listener.on', 'trigger.event == "pull_request"', undefined],
     ['listener.until', 'inputs.target == event.issue.number', undefined],
+    ['listener.until', 'vars.ENABLED == "true"', 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}),
     });
 
@@ -117,7 +195,7 @@ describe('validatePredicateExpression', () => {
     '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'});
+    const result = validate({field: 'listener.on', source});
 
     expect(result.expression).toBeUndefined();
     expect(result.issues).toEqual([
@@ -128,11 +206,72 @@ describe('validatePredicateExpression', () => {
     ]);
   });
 
+  it.each([
+    ['listener.on', 'executions.size() > 0', 'executions'],
+    ['listener.until', 'execution.status == "waiting"', 'execution'],
+    ['listener.on', 'needs.size() > 0', 'needs'],
+    ['listener.until', 'matrix.os == "linux"', 'matrix'],
+    ['job.if', 'job.key == "build"', 'job'],
+    ['job.if', 'executions.size() > 0', 'executions'],
+    ['step.if', 'run.id == "run-1"', 'run'],
+    ['step.success', 'execution.status == "failed"', 'execution'],
+    ['job.success', 'run.id == "run-1"', 'run'],
+  ] as const)('rejects %s context that its runtime evaluator does not supply: %s', (field, source, unavailableRoot) => {
+    const result = validate({field, source});
+
+    expect(result.expression).toBeUndefined();
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        code: 'context-unavailable-at-predicate-site',
+        details: expect.objectContaining({
+          field,
+          source,
+          unavailableRoots: [unavailableRoot],
+        }),
+      }),
+    ]);
+  });
+
+  it.each([
+    ['step.if', 'step.exit_code == 0'],
+    ['step.success', 'step.attempt > 1'],
+    ['job.success', 'executions.exists(e, e.failed)'],
+  ] as const)('rejects %s properties absent from its runtime shape: %s', (field, source) => {
+    const result = validate({field, source, typeOverlay: {}});
+
+    expect(result.expression).toBeUndefined();
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        code: 'invalid-job-success',
+        details: expect.objectContaining({
+          field,
+          source,
+          reason: expect.stringContaining('No such key'),
+        }),
+      }),
+    ]);
+  });
+
+  it('still checks typed properties when a predicate also uses open context', () => {
+    const result = validate({
+      field: 'step.success',
+      source: 'step.attempt > 1 && vars.RETRY == "true"',
+    });
+
+    expect(result.expression).toBeUndefined();
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        details: expect.objectContaining({
+          reason: expect.stringContaining('No such key: attempt'),
+        }),
+      }),
+    ]);
+  });
+
   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']),
     });
 
@@ -149,7 +288,6 @@ describe('validatePredicateExpression', () => {
     const result = validate({
       field: 'job.success',
       source: 'jobs.build.outputs.ready',
-      site: 'job-resolution',
     });
 
     expect(result.issues).toEqual([]);