@shipfox/api-definitions 12.3.0 → 14.0.0

package/src/core/validate-definition.test.ts

@@ -24,7 +24,7 @@ jobs:
 
     expect(result.valid).toBe(true);
     if (result.valid) {
-      expect(result.warnings).toEqual([]);
+      expect(result.diagnostics).toEqual([]);
       expect(result.definition.document.name).toBe('Test');
       expect(result.definition.document.jobs.build?.steps).toHaveLength(1);
       expect(result.definition.model.jobs[0]?.id).toBe('build');
@@ -36,7 +36,7 @@ jobs:
 
     expect(result.valid).toBe(false);
     if (!result.valid) {
-      expect(result).not.toHaveProperty('warnings');
+      expect(result).not.toHaveProperty('diagnostics');
       expect(result.errors).toHaveLength(1);
       expect(result.errors[0]?.message).toContain('Invalid workflow YAML syntax');
     }
@@ -159,14 +159,15 @@ jobs:
 
     expect(result.valid).toBe(true);
     if (result.valid) {
-      expect(result.warnings).toHaveLength(1);
-      expect(result.warnings[0]).toMatchObject({
+      expect(result.diagnostics).toHaveLength(1);
+      expect(result.diagnostics[0]).toMatchObject({
         code: 're-evaluating-command',
         path: 'jobs.build.steps.0.run',
+        severity: 'warning',
       });
-      expect(result.warnings[0]?.message).toContain(`$${valueName}`);
-      expect(result.warnings[0]?.message).toContain('eval');
-      expect(result.warnings[0]?.message).toContain('re-executed as code');
+      expect(result.diagnostics[0]?.message).toContain(`$${valueName}`);
+      expect(result.diagnostics[0]?.message).toContain('eval');
+      expect(result.diagnostics[0]?.message).toContain('re-executed as code');
       expect(result.definition.model.jobs[0]?.steps).toHaveLength(1);
     }
   });
@@ -189,7 +190,7 @@ jobs:
           ${run}
 `);
 
-    expect(result).toMatchObject({valid: true, warnings: []});
+    expect(result).toMatchObject({valid: true, diagnostics: []});
   });
 
   test.each([
@@ -209,13 +210,14 @@ jobs:
 
     expect(result.valid).toBe(true);
     if (result.valid) {
-      expect(result.warnings).toHaveLength(1);
-      expect(result.warnings[0]).toMatchObject({
+      expect(result.diagnostics).toHaveLength(1);
+      expect(result.diagnostics[0]).toMatchObject({
         code: 're-evaluating-command',
         path: 'jobs.build.steps.0.run',
+        severity: 'warning',
       });
-      expect(result.warnings[0]?.message).toContain('event.ref');
-      expect(result.warnings[0]?.message).toContain(construct);
+      expect(result.diagnostics[0]?.message).toContain('event.ref');
+      expect(result.diagnostics[0]?.message).toContain(construct);
     }
   });
 
@@ -234,18 +236,25 @@ jobs:
 
     expect(result.valid).toBe(true);
     if (result.valid) {
-      expect(result.warnings).toHaveLength(5);
-      expect(result.warnings.every((warning) => warning.code === 're-evaluating-command')).toBe(
-        true,
-      );
-      expect(result.warnings.every((warning) => warning.path === 'jobs.build.steps.0.run')).toBe(
-        true,
-      );
-      expect(result.warnings.filter((warning) => warning.message.includes('eval'))).toHaveLength(3);
-      expect(result.warnings.some((warning) => warning.message.includes('event.first'))).toBe(true);
-      expect(result.warnings.some((warning) => warning.message.includes('event.second'))).toBe(
+      expect(result.diagnostics).toHaveLength(5);
+      expect(
+        result.diagnostics.every((diagnostic) => diagnostic.code === 're-evaluating-command'),
+      ).toBe(true);
+      expect(
+        result.diagnostics.every((diagnostic) => diagnostic.path === 'jobs.build.steps.0.run'),
+      ).toBe(true);
+      expect(result.diagnostics.every((diagnostic) => diagnostic.severity === 'warning')).toBe(
         true,
       );
+      expect(
+        result.diagnostics.filter((diagnostic) => diagnostic.message.includes('eval')),
+      ).toHaveLength(3);
+      expect(
+        result.diagnostics.some((diagnostic) => diagnostic.message.includes('event.first')),
+      ).toBe(true);
+      expect(
+        result.diagnostics.some((diagnostic) => diagnostic.message.includes('event.second')),
+      ).toBe(true);
     }
   });
 

package/src/core/validate-definition.ts

@@ -2,7 +2,7 @@ import type {AgentValidationCatalog} from '@shipfox/api-agent-dto/inter-module';
 import {InvalidWorkflowDocumentError} from '@shipfox/workflow-document';
 import {definitionDefaultRunnerLabels} from '../config.js';
 import type {IntegrationValidationContext} from './entities/integration-context.js';
-import type {ValidationWarning} from './entities/validation-warning.js';
+import type {ValidationDiagnostic} from './entities/validation-diagnostic.js';
 import type {WorkflowDefinitionPayload} from './entities/workflow-definition.js';
 import {
   InvalidWorkflowModelError,
@@ -12,7 +12,7 @@ import {
 import {InvalidWorkflowYamlError, parseWorkflowYamlWithLocations} from './workflow-yaml/index.js';
 
 export type ValidationError = {message: string; path?: string | undefined};
-export type {ValidationWarning} from './entities/validation-warning.js';
+export type {ValidationDiagnostic} from './entities/validation-diagnostic.js';
 
 export interface DefinitionValidationOptions {
   defaultRunnerLabels?: readonly string[];
@@ -21,7 +21,7 @@ export interface DefinitionValidationOptions {
 }
 
 export type ValidationResult =
-  | {valid: true; definition: WorkflowDefinitionPayload; warnings: ValidationWarning[]}
+  | {valid: true; definition: WorkflowDefinitionPayload; diagnostics: ValidationDiagnostic[]}
   | {valid: false; errors: ValidationError[]};
 
 export function validateDefinition(
@@ -30,28 +30,33 @@ export function validateDefinition(
 ): ValidationResult {
   try {
     const {document, stepSourceLocations} = parseWorkflowYamlWithLocations(yamlContent);
-    const warnings: WorkflowModelValidationIssue[] = [];
+    const diagnostics: WorkflowModelValidationIssue[] = [];
     const model = normalizeWorkflowDocument(document, {
       defaultRunnerLabels: options.defaultRunnerLabels ?? definitionDefaultRunnerLabels,
       agentValidationCatalog: options.agentValidationCatalog,
       integrationValidationContext: options.integrationValidationContext,
       stepSourceLocations,
-      warnings,
+      diagnostics,
     });
-    return {valid: true, definition: {document, model}, warnings: validationWarningsFor(warnings)};
+    return {
+      valid: true,
+      definition: {document, model},
+      diagnostics: validationDiagnosticsFor(diagnostics),
+    };
   } catch (error) {
     return {valid: false, errors: validationErrorsFor(error)};
   }
 }
 
-function validationWarningsFor(
+function validationDiagnosticsFor(
   issues: readonly WorkflowModelValidationIssue[],
-): ValidationWarning[] {
+): ValidationDiagnostic[] {
   return issues.map((issue) =>
-    validationWarning({
+    validationDiagnostic({
       code: issue.code,
       message: issue.message,
       path: issue.path.join('.') || undefined,
+      severity: issue.severity,
     }),
   );
 }
@@ -92,11 +97,14 @@ function validationError(params: {message: string; path?: string | undefined}):
   return {message: params.message, path: params.path};
 }
 
-function validationWarning(params: {
+function validationDiagnostic(params: {
   code: string;
   message: string;
   path?: string | undefined;
-}): ValidationWarning {
-  if (params.path === undefined) return {code: params.code, message: params.message};
-  return {code: params.code, message: params.message, path: params.path};
+  severity: 'error' | 'warning';
+}): ValidationDiagnostic {
+  if (params.path === undefined) {
+    return {code: params.code, message: params.message, severity: params.severity};
+  }
+  return {code: params.code, message: params.message, path: params.path, severity: params.severity};
 }

package/src/core/workflow-model/cron-trigger.ts

@@ -8,7 +8,7 @@ const cronFieldSeparatorRegex = /\s+/;
 export function validateCronTrigger(params: {
   readonly sourceKey: string;
   readonly trigger: {
-    readonly event: string;
+    readonly event?: string | undefined;
   };
   readonly config: {
     readonly schedule?: string | undefined;
@@ -18,13 +18,14 @@ export function validateCronTrigger(params: {
 }): void {
   const {sourceKey, trigger, config, issues} = params;
 
-  if (trigger.event !== 'tick') {
+  if (trigger.event !== undefined && trigger.event !== 'tick') {
     issues.push(
       issue({
         code: 'invalid-cron-event',
         message: `A cron trigger must use event "tick"; found "${trigger.event}".`,
         path: ['triggers', sourceKey, 'event'],
         details: {event: trigger.event},
+        scope: 'trigger',
       }),
     );
   }
@@ -35,6 +36,7 @@ export function validateCronTrigger(params: {
         code: 'missing-cron-schedule',
         message: 'A cron trigger requires a schedule.',
         path: ['triggers', sourceKey, 'config', 'schedule'],
+        scope: 'trigger',
       }),
     );
   } else if (!isValidCronExpression(config.schedule)) {
@@ -44,6 +46,7 @@ export function validateCronTrigger(params: {
         message: 'Cron trigger schedule must be a valid 5-field cron expression.',
         path: ['triggers', sourceKey, 'config', 'schedule'],
         details: {schedule: config.schedule},
+        scope: 'trigger',
       }),
     );
   }
@@ -55,6 +58,7 @@ export function validateCronTrigger(params: {
         message: 'Cron trigger timezone must be a valid IANA time zone.',
         path: ['triggers', sourceKey, 'config', 'timezone'],
         details: {timezone: config.timezone},
+        scope: 'trigger',
       }),
     );
   }

package/src/core/workflow-model/index.ts

@@ -5,6 +5,7 @@ export {
   type WorkflowModelValidationIssue,
   type WorkflowModelValidationIssueCode,
   type WorkflowModelValidationIssuePathSegment,
+  type WorkflowModelValidationIssueScope,
   type WorkflowModelValidationIssueSeverity,
 } from './invalid-workflow-model-error.js';
 export {normalizeWorkflowDocument} from './normalize-workflow-document.js';

package/src/core/workflow-model/invalid-workflow-model-error.ts

@@ -34,6 +34,7 @@ export type WorkflowModelValidationIssueCode =
   | 'invalid-step-if'
   | 'job-dependency-cycle'
   | 'listening-job-missing-resolution-source'
+  | 'listening-job-no-active-matcher'
   | 'listening-timeout-exceeds-run-timeout'
   | 'missing-harness-for-tools'
   | 'missing-connection-for-integration'
@@ -58,12 +59,15 @@ export type WorkflowModelValidationIssuePathSegment = string | number;
 
 export type WorkflowModelValidationIssueSeverity = 'error' | 'warning';
 
+export type WorkflowModelValidationIssueScope = 'definition' | 'trigger';
+
 export interface WorkflowModelValidationIssue {
   readonly code: WorkflowModelValidationIssueCode;
   readonly message: string;
   readonly path: readonly WorkflowModelValidationIssuePathSegment[];
   readonly details?: Readonly<Record<string, unknown>>;
-  readonly severity?: WorkflowModelValidationIssueSeverity;
+  readonly severity: WorkflowModelValidationIssueSeverity;
+  readonly scope: WorkflowModelValidationIssueScope;
 }
 
 export class InvalidWorkflowModelError extends Error {

package/src/core/workflow-model/normalize-job-listening.ts

@@ -39,8 +39,49 @@ export function normalizeJobListening(params: {
     issues: params.issues,
   });
 
+  const on = listening.on
+    .map((trigger, index) =>
+      normalizeListeningTrigger({
+        trigger,
+        field: 'listener.on',
+        path: [...path, 'listening', 'on', index, 'filter'],
+        issues: params.issues,
+        allowedJobReferences: params.allowedJobReferences,
+      }),
+    )
+    .filter((matcher): matcher is WorkflowModelJobListening['on'][number] => matcher !== undefined);
+
+  if (on.length === 0) {
+    params.issues.push(
+      issue({
+        code: 'listening-job-no-active-matcher',
+        message: `Listening job "${params.sourceName}" has no active "on" matcher; it can never execute.`,
+        path: [...path, 'listening', 'on'],
+      }),
+    );
+  }
+
+  const until =
+    listening.until === undefined
+      ? undefined
+      : listening.until
+          .map((trigger, index) =>
+            normalizeListeningTrigger({
+              trigger,
+              field: 'listener.until',
+              path: [...path, 'listening', 'until', index, 'filter'],
+              issues: params.issues,
+              allowedJobReferences: params.allowedJobReferences,
+            }),
+          )
+          .filter(
+            (matcher): matcher is WorkflowModelJobListening['on'][number] => matcher !== undefined,
+          );
+
+  // Inert `until` matchers do not resolve the listening job; the check runs on
+  // the matchers that stay active.
   if (
-    listening.until === undefined &&
+    (until === undefined || until.length === 0) &&
     listening.timeout === undefined &&
     listening.max_executions === undefined
   ) {
@@ -63,27 +104,11 @@ export function normalizeJobListening(params: {
         };
 
   return {
-    on: listening.on.map((trigger, index) =>
-      normalizeListeningTrigger({
-        trigger,
-        field: 'listener.on',
-        path: [...path, 'listening', 'on', index, 'filter'],
-        issues: params.issues,
-        allowedJobReferences: params.allowedJobReferences,
-      }),
-    ),
-    ...(listening.until === undefined
+    on,
+    ...(until === undefined || until.length === 0
       ? {}
       : {
-          until: listening.until.map((trigger, index) =>
-            normalizeListeningTrigger({
-              trigger,
-              field: 'listener.until',
-              path: [...path, 'listening', 'until', index, 'filter'],
-              issues: params.issues,
-              allowedJobReferences: params.allowedJobReferences,
-            }),
-          ),
+          until,
         }),
     ...(timeoutMs === undefined ? {} : {timeoutMs}),
     ...(listening.max_executions === undefined ? {} : {maxExecutions: listening.max_executions}),
@@ -95,7 +120,7 @@ export function normalizeJobListening(params: {
 function normalizeListeningTrigger(params: {
   trigger: {
     readonly source: string;
-    readonly event: string;
+    readonly event?: string | undefined;
     readonly with?: Readonly<Record<string, unknown>> | undefined;
     readonly filter?: string | undefined;
   };
@@ -103,7 +128,8 @@ function normalizeListeningTrigger(params: {
   path: readonly (string | number)[];
   issues: WorkflowModelValidationIssue[];
   allowedJobReferences: ReadonlySet<string>;
-}): WorkflowModelJobListening['on'][number] {
+}): WorkflowModelJobListening['on'][number] | undefined {
+  const matcherIssues: WorkflowModelValidationIssue[] = [];
   if (params.trigger.filter !== undefined) {
     validatePredicateExpression({
       field: params.field,
@@ -111,10 +137,16 @@ function normalizeListeningTrigger(params: {
       path: params.path,
       invalidCode: 'invalid-listener-filter',
       invalidMessage: `${params.field === 'listener.on' ? 'Listener on' : 'Listener until'} filter must be a valid CEL boolean expression.`,
-      issues: params.issues,
+      issues: matcherIssues,
       allowedJobReferences: params.allowedJobReferences,
+      scope: 'trigger',
     });
   }
+  params.issues.push(...matcherIssues);
+
+  // A matcher with a trigger-scoped issue is inert: excluded from the matcher
+  // list while the authored document entry stays untouched.
+  if (matcherIssues.some((candidate) => candidate.scope === 'trigger')) return undefined;
 
   return normalizeTriggerEntry(params.trigger);
 }

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

@@ -22,17 +22,7 @@ export function normalizeTriggers(
     .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},
-      }),
-    );
-  }
+  let activeManualTriggerSeen = false;
 
   return Object.entries(triggers).flatMap(([sourceKey, trigger]) => {
     const id = stableId(sourceKey);
@@ -44,16 +34,37 @@ export function normalizeTriggers(
           message: `Trigger keys "${existingSourceKey}" and "${sourceKey}" resolve to the same stable id "${id}".`,
           path: ['triggers', sourceKey],
           details: {id, sourceKeys: [existingSourceKey, sourceKey]},
+          scope: 'trigger',
         }),
       );
       return [];
     }
     usedTriggerIds.set(id, sourceKey);
 
-    validateTriggerFilter({sourceKey, trigger, issues});
+    if (trigger.source === manualTriggerSource) {
+      if (activeManualTriggerSeen) {
+        issues.push(
+          issue({
+            code: 'multiple-manual-triggers',
+            message: `A workflow may declare at most one manual trigger; found ${manualTriggerKeys.length}: ${manualTriggerKeys.join(', ')}. This trigger is inert because it is not the first manual trigger in document order.`,
+            path: ['triggers', sourceKey],
+            details: {manualTriggerKeys},
+            scope: 'trigger',
+          }),
+        );
+        return [];
+      }
+    }
+
+    const triggerIssues: WorkflowModelValidationIssue[] = [];
+    validateTriggerFilter({sourceKey, trigger, issues: triggerIssues});
+    issues.push(...triggerIssues);
 
     const normalizedTrigger = normalizeTriggerEntry(trigger);
+    const triggerIsInert = triggerIssues.some((candidate) => candidate.scope === 'trigger');
     if (trigger.source !== cronTriggerSource) {
+      if (triggerIsInert) return [];
+      if (trigger.source === manualTriggerSource) activeManualTriggerSeen = true;
       return [
         {
           id,
@@ -70,7 +81,12 @@ export function normalizeTriggers(
       timezone: cronConfig.timezone ?? cronTriggerDefaultTimezone,
     };
 
-    validateCronTrigger({trigger, config: cronConfig, sourceKey, issues});
+    const cronIssues: WorkflowModelValidationIssue[] = [];
+    validateCronTrigger({trigger, config: cronConfig, sourceKey, issues: cronIssues});
+    issues.push(...cronIssues);
+
+    const cronIsInert = cronIssues.some((candidate) => candidate.scope === 'trigger');
+    if (triggerIsInert || cronIsInert) return [];
 
     return [
       {
@@ -99,6 +115,7 @@ function validateTriggerFilter(params: {
         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},
+        scope: 'trigger',
       }),
     );
     return;
@@ -111,19 +128,31 @@ function validateTriggerFilter(params: {
     invalidCode: 'invalid-trigger-filter',
     invalidMessage: 'Trigger filter must be a valid boolean predicate.',
     issues,
+    scope: 'trigger',
   });
 }
 
 export function normalizeTriggerEntry(trigger: {
   readonly source: string;
-  readonly event: string;
+  readonly event?: string | undefined;
   readonly with?: Readonly<Record<string, unknown>> | undefined;
   readonly filter?: string | undefined;
 }): WorkflowModelListeningTrigger {
+  // `manual` and `cron` have no delivered event to resolve against at fire
+  // time, so materialize their built-in name when the author omitted it.
+  // Integration sources keep the event absent, which becomes a source
+  // subscription (NULL row) on the write path.
+  const event = builtinEventForSource(trigger.source, trigger.event);
   return {
     source: trigger.source,
-    event: trigger.event,
+    ...(event === undefined ? {} : {event}),
     ...(trigger.with === undefined ? {} : {inputs: trigger.with}),
     ...(trigger.filter === undefined ? {} : {filter: trigger.filter}),
   };
 }
+
+function builtinEventForSource(source: string, event: string | undefined): string | undefined {
+  if (source === manualTriggerSource) return event ?? 'fire';
+  if (source === cronTriggerSource) return event ?? 'tick';
+  return event;
+}