@shipfox/api-definitions 2.0.0

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

@@ -0,0 +1,12 @@
+export function normalizeNeeds(value: string | readonly string[] | undefined): readonly string[] {
+  return uniqueStrings(normalizeStringArray(value));
+}
+
+function normalizeStringArray(value: string | readonly string[] | undefined): readonly string[] {
+  if (value === undefined) return [];
+  return typeof value === 'string' ? [value] : value;
+}
+
+function uniqueStrings(values: readonly string[]): readonly string[] {
+  return [...new Set(values)];
+}

package/src/core/workflow-model/normalize-step-gate.ts

@@ -0,0 +1,90 @@
+import type {ExpressionTypeEnvironment, WorkflowExpression} from '@shipfox/expression';
+import type {WorkflowDocumentStep} from '@shipfox/workflow-document';
+import type {WorkflowModelStepGate} from '../entities/workflow-model.js';
+import type {WorkflowModelValidationIssue} from './invalid-workflow-model-error.js';
+import {parseInterpolationField} from './parse-interpolation-field.js';
+import {validatePredicateExpression} from './validate-predicate-expression.js';
+import {issue} from './validation-issue.js';
+
+export function normalizeStepGate(params: {
+  step: WorkflowDocumentStep;
+  sourceName: string;
+  stepIndex: number;
+  stepId: string;
+  previousStepKeys: ReadonlySet<string>;
+  issues: WorkflowModelValidationIssue[];
+  allowedJobReferences: ReadonlySet<string>;
+  typeOverlay?: ExpressionTypeEnvironment | undefined;
+}): WorkflowModelStepGate | undefined {
+  const gate = params.step.gate;
+  if (gate === undefined) return undefined;
+
+  const success = normalizeGateSuccess({
+    source: gate.success,
+    sourceName: params.sourceName,
+    stepIndex: params.stepIndex,
+    issues: params.issues,
+    allowedJobReferences: params.allowedJobReferences,
+    typeOverlay: params.typeOverlay,
+  });
+  const feedbackTemplate =
+    gate.on_failure?.feedback === undefined
+      ? undefined
+      : parseInterpolationField({
+          field: 'step.feedback',
+          source: gate.on_failure.feedback,
+          path: ['jobs', params.sourceName, 'steps', params.stepIndex, 'gate', 'on_failure'],
+          issues: params.issues,
+          fillSite: 'step-report',
+          typeOverlay: params.typeOverlay,
+        });
+  const onFailure =
+    gate.on_failure === undefined
+      ? undefined
+      : {
+          restartFrom: gate.on_failure.restart_from,
+          ...(gate.on_failure.feedback === undefined ? {} : {feedback: gate.on_failure.feedback}),
+          ...(feedbackTemplate === undefined ? {} : {feedbackTemplate}),
+        };
+
+  if (gate.on_failure !== undefined && !params.previousStepKeys.has(gate.on_failure.restart_from)) {
+    params.issues.push(
+      issue({
+        code: 'invalid-step-gate-restart-from',
+        message: `Step "${params.stepId}" must restart from an earlier keyed step; found "${gate.on_failure.restart_from}".`,
+        path: ['jobs', params.sourceName, 'steps', params.stepIndex, 'gate', 'on_failure'],
+        details: {stepId: params.stepId, restartFrom: gate.on_failure.restart_from},
+      }),
+    );
+  }
+
+  if (success === undefined && onFailure === undefined) return undefined;
+
+  return {
+    ...(success === undefined ? {} : {success}),
+    ...(onFailure === undefined ? {} : {onFailure}),
+  };
+}
+
+function normalizeGateSuccess(params: {
+  source: string | undefined;
+  sourceName: string;
+  stepIndex: number;
+  issues: WorkflowModelValidationIssue[];
+  allowedJobReferences: ReadonlySet<string>;
+  typeOverlay?: ExpressionTypeEnvironment | undefined;
+}): WorkflowExpression | undefined {
+  if (params.source === undefined) return undefined;
+
+  return validatePredicateExpression({
+    field: 'step.success',
+    source: params.source,
+    site: 'step-report',
+    path: ['jobs', params.sourceName, 'steps', params.stepIndex, 'gate', 'success'],
+    invalidCode: 'invalid-step-gate-success',
+    invalidMessage: 'Step gate success must be a valid CEL boolean expression.',
+    issues: params.issues,
+    allowedJobReferences: params.allowedJobReferences,
+    typeOverlay: params.typeOverlay,
+  });
+}

package/src/core/workflow-model/normalize-step-outputs.ts

@@ -0,0 +1,36 @@
+import {type OutputDeclarations, validateJsonSchema} from '@shipfox/expression';
+import type {WorkflowDocumentStep} from '@shipfox/workflow-document';
+import type {WorkflowModelValidationIssue} from './invalid-workflow-model-error.js';
+import {issue} from './validation-issue.js';
+
+export function normalizeStepOutputs(params: {
+  step: WorkflowDocumentStep;
+  sourceName: string;
+  stepIndex: number;
+  issues: WorkflowModelValidationIssue[];
+}): OutputDeclarations | undefined {
+  const outputs = params.step.outputs;
+  if (outputs === undefined) return undefined;
+
+  for (const [key, declaration] of Object.entries(outputs)) {
+    const schema = 'schema' in declaration ? declaration.schema : undefined;
+    if (declaration.type !== 'json' || schema === undefined) continue;
+
+    const validation = validateJsonSchema(schema);
+    if (validation.ok) continue;
+
+    params.issues.push(
+      issue({
+        code: 'invalid-output-schema',
+        message: `Step output "${key}" must declare a valid JSON Schema.`,
+        path: ['jobs', params.sourceName, 'steps', params.stepIndex, 'outputs', key, 'schema'],
+        details: {
+          output: key,
+          reason: validation.reason,
+        },
+      }),
+    );
+  }
+
+  return outputs;
+}

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

@@ -0,0 +1,130 @@
+import {triggerSourceConfigSchemas, type WorkflowDocument} from '@shipfox/workflow-document';
+import type {
+  WorkflowModelListeningTrigger,
+  WorkflowModelTrigger,
+} from '../entities/workflow-model.js';
+import {cronTriggerDefaultTimezone, validateCronTrigger} from './cron-trigger.js';
+import type {WorkflowModelValidationIssue} from './invalid-workflow-model-error.js';
+import {stableId} from './stable-id.js';
+import {validatePredicateExpression} from './validate-predicate-expression.js';
+import {issue} from './validation-issue.js';
+
+const manualTriggerSource = 'manual';
+const cronTriggerSource = 'cron';
+type WorkflowDocumentTrigger = NonNullable<WorkflowDocument['triggers']>[string];
+
+export function normalizeTriggers(
+  document: WorkflowDocument,
+  issues: WorkflowModelValidationIssue[],
+): readonly WorkflowModelTrigger[] {
+  const triggers = document.triggers ?? {};
+  const manualTriggerKeys = Object.entries(triggers)
+    .filter(([, trigger]) => trigger.source === manualTriggerSource)
+    .map(([sourceKey]) => sourceKey);
+  const usedTriggerIds = new Map<string, string>();
+
+  if (manualTriggerKeys.length > 1) {
+    issues.push(
+      issue({
+        code: 'multiple-manual-triggers',
+        message: `A workflow may declare at most one manual trigger; found ${manualTriggerKeys.length}: ${manualTriggerKeys.join(', ')}.`,
+        path: ['triggers'],
+        details: {manualTriggerKeys},
+      }),
+    );
+  }
+
+  return Object.entries(triggers).flatMap(([sourceKey, trigger]) => {
+    const id = stableId(sourceKey);
+    const existingSourceKey = usedTriggerIds.get(id);
+    if (existingSourceKey !== undefined) {
+      issues.push(
+        issue({
+          code: 'duplicate-trigger-id',
+          message: `Trigger keys "${existingSourceKey}" and "${sourceKey}" resolve to the same stable id "${id}".`,
+          path: ['triggers', sourceKey],
+          details: {id, sourceKeys: [existingSourceKey, sourceKey]},
+        }),
+      );
+      return [];
+    }
+    usedTriggerIds.set(id, sourceKey);
+
+    validateTriggerFilter({sourceKey, trigger, issues});
+
+    const normalizedTrigger = normalizeTriggerEntry(trigger);
+    if (trigger.source !== cronTriggerSource) {
+      return [
+        {
+          id,
+          key: sourceKey,
+          ...normalizedTrigger,
+          ...(trigger.config === undefined ? {} : {config: trigger.config}),
+        },
+      ];
+    }
+
+    const cronConfig = triggerSourceConfigSchemas.cron.parse(trigger.config ?? {});
+    const normalizedCronConfig = {
+      ...cronConfig,
+      timezone: cronConfig.timezone ?? cronTriggerDefaultTimezone,
+    };
+
+    validateCronTrigger({trigger, config: cronConfig, sourceKey, issues});
+
+    return [
+      {
+        id,
+        key: sourceKey,
+        ...normalizedTrigger,
+        config: normalizedCronConfig,
+      },
+    ];
+  });
+}
+
+function validateTriggerFilter(params: {
+  sourceKey: string;
+  trigger: WorkflowDocumentTrigger;
+  issues: WorkflowModelValidationIssue[];
+}): void {
+  const {sourceKey, trigger, issues} = params;
+  if (trigger.filter === undefined) return;
+
+  const path = ['triggers', sourceKey, 'filter'] as const;
+  if (trigger.source === manualTriggerSource || trigger.source === cronTriggerSource) {
+    issues.push(
+      issue({
+        code: 'invalid-trigger-filter',
+        message: `A ${trigger.source} trigger cannot define a filter because it does not receive an event payload.`,
+        path,
+        details: {source: trigger.filter, triggerSource: trigger.source},
+      }),
+    );
+    return;
+  }
+
+  validatePredicateExpression({
+    field: 'trigger.filter',
+    source: trigger.filter,
+    site: 'ingest',
+    path,
+    invalidCode: 'invalid-trigger-filter',
+    invalidMessage: 'Trigger filter must be a valid boolean predicate.',
+    issues,
+  });
+}
+
+export function normalizeTriggerEntry(trigger: {
+  readonly source: string;
+  readonly event: string;
+  readonly with?: Readonly<Record<string, unknown>> | undefined;
+  readonly filter?: string | undefined;
+}): WorkflowModelListeningTrigger {
+  return {
+    source: trigger.source,
+    event: trigger.event,
+    ...(trigger.with === undefined ? {} : {inputs: trigger.with}),
+    ...(trigger.filter === undefined ? {} : {filter: trigger.filter}),
+  };
+}