@shipfox/api-definitions 13.1.0 → 14.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-definitions",
   "license": "MIT",
-  "version": "13.1.0",
+  "version": "14.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -26,14 +26,14 @@
     "js-yaml": "^4.1.0",
     "yaml": "^2.8.3",
     "zod": "^4.4.3",
-    "@shipfox/api-agent-dto": "13.1.0",
+    "@shipfox/api-agent-dto": "14.0.0",
     "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-definitions-dto": "12.3.0",
-    "@shipfox/api-integration-core-dto": "12.2.0",
-    "@shipfox/api-projects-dto": "12.2.0",
+    "@shipfox/api-definitions-dto": "14.0.0",
+    "@shipfox/api-integration-core-dto": "14.0.0",
+    "@shipfox/api-projects-dto": "14.0.0",
     "@shipfox/api-secrets-dto": "12.0.0",
     "@shipfox/config": "1.2.4",
-    "@shipfox/expression": "2.2.0",
+    "@shipfox/expression": "2.2.1",
     "@shipfox/inter-module": "0.2.3",
     "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-fastify": "0.4.2",
@@ -44,7 +44,7 @@
     "@shipfox/node-postgres": "0.5.0",
     "@shipfox/node-temporal": "0.4.5",
     "@shipfox/runner-labels": "0.2.0",
-    "@shipfox/workflow-document": "3.0.1"
+    "@shipfox/workflow-document": "3.1.0"
   },
   "imports": {
     "#*": "./dist/*"

package/src/core/entities/index.ts

@@ -1,5 +1,5 @@
 export * from './integration-context.js';
 export * from './sync-state.js';
-export * from './validation-warning.js';
+export * from './validation-diagnostic.js';
 export * from './workflow-definition.js';
 export * from './workflow-model.js';

package/src/core/entities/integration-context.ts

@@ -25,5 +25,9 @@ export interface IntegrationValidationContext {
       readonly capabilities: readonly IntegrationCapability[];
     }
   >;
+  /** Documented event names per provider; provider-minted names are never a closed set. */
+  readonly eventCatalogs: ReadonlyMap<IntegrationProviderKind, ReadonlySet<string>>;
+  /** Providers whose single event name is Shipfox-minted (`webhook` today). */
+  readonly fixedEventProviders: ReadonlySet<IntegrationProviderKind>;
   readonly defaultConnectionSlug?: string | undefined;
 }

package/src/core/entities/sync-state.test.ts

@@ -0,0 +1,49 @@
+import {DEFINITION_SYNC_DIAGNOSTICS_MAX_COUNT} from '@shipfox/api-definitions-dto';
+import {type DefinitionSyncDiagnostic, limitDefinitionSyncDiagnostics} from './sync-state.js';
+
+describe('limitDefinitionSyncDiagnostics', () => {
+  it('orders errors before warnings while keeping the order within each severity', () => {
+    const diagnostics: DefinitionSyncDiagnostic[] = [
+      {code: 'warning-a', message: 'first warning', severity: 'warning'},
+      {code: 'error-a', message: 'first error', severity: 'error'},
+      {code: 'warning-b', message: 'second warning', severity: 'warning'},
+      {code: 'error-b', message: 'second error', severity: 'error'},
+    ];
+
+    expect(limitDefinitionSyncDiagnostics(diagnostics).map((entry) => entry.code)).toEqual([
+      'error-a',
+      'error-b',
+      'warning-a',
+      'warning-b',
+    ]);
+  });
+
+  it('drops warnings first when the list exceeds the maximum count', () => {
+    const diagnostics: DefinitionSyncDiagnostic[] = [
+      ...Array.from({length: DEFINITION_SYNC_DIAGNOSTICS_MAX_COUNT}, (_, index) => ({
+        code: `warning-${index}`,
+        message: `warning ${index}`,
+        severity: 'warning' as const,
+      })),
+      {code: 'error-last', message: 'error persisted', severity: 'error'},
+    ];
+
+    const limited = limitDefinitionSyncDiagnostics(diagnostics);
+
+    expect(limited).toHaveLength(DEFINITION_SYNC_DIAGNOSTICS_MAX_COUNT);
+    expect(limited[0]?.code).toBe('error-last');
+    expect(limited.filter((entry) => entry.severity === 'error')).toHaveLength(1);
+    expect(limited.some((entry) => entry.code === 'warning-0')).toBe(true);
+    expect(
+      limited.some(
+        (entry) => entry.code === `warning-${DEFINITION_SYNC_DIAGNOSTICS_MAX_COUNT - 1}`,
+      ),
+    ).toBe(false);
+  });
+
+  it('preserves severity and an absent path', () => {
+    expect(
+      limitDefinitionSyncDiagnostics([{code: 'code', message: 'message', severity: 'warning'}]),
+    ).toEqual([{code: 'code', message: 'message', severity: 'warning'}]);
+  });
+});

package/src/core/entities/sync-state.ts

@@ -1,24 +1,47 @@
 import {
+  DEFINITION_SYNC_DIAGNOSTIC_FILE_PATH_MAX_LENGTH,
+  DEFINITION_SYNC_DIAGNOSTICS_MAX_COUNT,
   DEFINITION_SYNC_WARNING_CODE_MAX_LENGTH,
   DEFINITION_SYNC_WARNING_MESSAGE_MAX_LENGTH,
   DEFINITION_SYNC_WARNING_PATH_MAX_LENGTH,
-  DEFINITION_SYNC_WARNINGS_MAX_COUNT,
 } from '@shipfox/api-definitions-dto';
-import type {ValidationWarning} from './validation-warning.js';
+import type {ValidationDiagnostic} from './validation-diagnostic.js';
 
 export type DefinitionSyncStatus = 'pending' | 'syncing' | 'succeeded' | 'failed';
 
-export type DefinitionSyncWarning = ValidationWarning;
+export interface DefinitionSyncDiagnostic extends ValidationDiagnostic {
+  filePath?: string | undefined;
+}
+
+/**
+ * Orders errors before warnings and bounds the list so truncation at
+ * `DEFINITION_SYNC_DIAGNOSTICS_MAX_COUNT` drops warnings first.
+ */
+export function limitDefinitionSyncDiagnostics(
+  diagnostics: readonly DefinitionSyncDiagnostic[],
+): DefinitionSyncDiagnostic[] {
+  const ordered: DefinitionSyncDiagnostic[] = [];
+  for (const severity of ['error', 'warning'] as const) {
+    for (const diagnostic of diagnostics) {
+      if (diagnostic.severity !== severity) continue;
+      ordered.push(diagnostic);
+      if (ordered.length === DEFINITION_SYNC_DIAGNOSTICS_MAX_COUNT) break;
+    }
+    if (ordered.length === DEFINITION_SYNC_DIAGNOSTICS_MAX_COUNT) break;
+  }
 
-export function limitDefinitionSyncWarnings(
-  warnings: readonly DefinitionSyncWarning[],
-): DefinitionSyncWarning[] {
-  return warnings.slice(0, DEFINITION_SYNC_WARNINGS_MAX_COUNT).map((warning) => ({
-    code: warning.code.slice(0, DEFINITION_SYNC_WARNING_CODE_MAX_LENGTH),
-    message: warning.message.slice(0, DEFINITION_SYNC_WARNING_MESSAGE_MAX_LENGTH),
-    ...(warning.path === undefined
+  return ordered.map((diagnostic) => ({
+    code: diagnostic.code.slice(0, DEFINITION_SYNC_WARNING_CODE_MAX_LENGTH),
+    message: diagnostic.message.slice(0, DEFINITION_SYNC_WARNING_MESSAGE_MAX_LENGTH),
+    severity: diagnostic.severity,
+    ...(diagnostic.path === undefined
+      ? {}
+      : {path: diagnostic.path.slice(0, DEFINITION_SYNC_WARNING_PATH_MAX_LENGTH)}),
+    ...(diagnostic.filePath === undefined
       ? {}
-      : {path: warning.path.slice(0, DEFINITION_SYNC_WARNING_PATH_MAX_LENGTH)}),
+      : {
+          filePath: diagnostic.filePath.slice(0, DEFINITION_SYNC_DIAGNOSTIC_FILE_PATH_MAX_LENGTH),
+        }),
   }));
 }
 
@@ -55,7 +78,7 @@ export interface DefinitionSyncState {
   status: DefinitionSyncStatus;
   lastErrorCode: DefinitionSyncErrorCode | null;
   lastErrorMessage: string | null;
-  warnings: DefinitionSyncWarning[];
+  diagnostics: DefinitionSyncDiagnostic[];
   startedAt: Date | null;
   finishedAt: Date | null;
   createdAt: Date;

package/src/core/entities/validation-diagnostic.ts

@@ -0,0 +1,8 @@
+export type ValidationDiagnosticSeverity = 'error' | 'warning';
+
+export interface ValidationDiagnostic {
+  code: string;
+  message: string;
+  path?: string | undefined;
+  severity: ValidationDiagnosticSeverity;
+}

package/src/core/entities/workflow-definition.ts

@@ -13,6 +13,8 @@ export interface WorkflowDefinitionPayload {
 
 export interface WorkflowDefinition {
   id: string;
+  /** Stable identity per project and config path; pathless manual rows share a project lineage. */
+  workflowId: string;
   projectId: string;
   configPath: string | null;
   source: 'manual' | 'vcs';

package/src/core/errors.ts

@@ -19,3 +19,29 @@ export class DefinitionSyncPermanentError extends Error {
     this.name = 'DefinitionSyncPermanentError';
   }
 }
+
+export type DefinitionAtRefErrorCode =
+  | 'project-not-found'
+  | 'ref-not-found'
+  | 'ref-invalid'
+  | 'ref-moved'
+  | 'file-not-found'
+  | 'content-too-large'
+  | 'invalid-definition'
+  | 'too-many-files'
+  | 'source-unavailable';
+
+/**
+ * Rejects a definition resolution or listing at a git ref. `details` carries
+ * the bounded context the presentation translates into known-error details.
+ */
+export class DefinitionAtRefError extends Error {
+  constructor(
+    public readonly code: DefinitionAtRefErrorCode,
+    message: string,
+    public readonly details: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = 'DefinitionAtRefError';
+  }
+}

package/src/core/index.ts

@@ -1,9 +1,21 @@
 export type * from './entities/index.js';
 export {
+  DefinitionAtRefError,
+  type DefinitionAtRefErrorCode,
   DefinitionParseError,
   DefinitionSyncPermanentError,
 } from './errors.js';
 export {parseDefinition} from './parse-definition.js';
+export {
+  type DefinitionAtRefFile,
+  type DefinitionsAtRefListing,
+  type ListDefinitionsAtRefParams,
+  listDefinitionsAtRef,
+  type ResolveDefinitionAtRefParams,
+  type ResolvedDefinitionAtRef,
+  resolveDefinitionAtRef,
+  type ValidationWarning,
+} from './resolve-definition-at-ref.js';
 export {
   classifySyncFailure,
   DEFAULT_WORKFLOW_PATH,

package/src/core/integrations.test.ts

@@ -0,0 +1,38 @@
+import type {IntegrationsModuleClient} from '@shipfox/api-integration-core-dto/inter-module';
+import {loadIntegrationValidationContext} from './integrations.js';
+
+describe('loadIntegrationValidationContext', () => {
+  it('materializes provider event catalogs and fixed-provider metadata', async () => {
+    const getAgentToolsContext = vi.fn<IntegrationsModuleClient['getAgentToolsContext']>(
+      async () => ({
+        selectionCatalogs: [],
+        catalogs: [],
+        workspaceConnections: [],
+        eventCatalogs: [
+          {provider: 'github', events: ['push', 'pull_request.opened']},
+          {provider: 'gitea', events: ['push']},
+        ],
+        fixedEventProviders: ['webhook'],
+        defaultConnection: null,
+      }),
+    );
+    const integrations = {getAgentToolsContext} as unknown as IntegrationsModuleClient;
+    const workspaceId = crypto.randomUUID();
+    const defaultConnectionId = crypto.randomUUID();
+
+    const context = await loadIntegrationValidationContext(
+      integrations,
+      workspaceId,
+      defaultConnectionId,
+    );
+
+    expect(getAgentToolsContext).toHaveBeenCalledWith({workspaceId, defaultConnectionId});
+    expect(context.eventCatalogs).toEqual(
+      new Map([
+        ['github', new Set(['push', 'pull_request.opened'])],
+        ['gitea', new Set(['push'])],
+      ]),
+    );
+    expect(context.fixedEventProviders).toEqual(new Set(['webhook']));
+  });
+});

package/src/core/integrations.ts

@@ -23,8 +23,13 @@ export async function loadIntegrationValidationContext(
   integrations: IntegrationsModuleClient,
   workspaceId: string,
   defaultConnectionId: string,
+  signal?: AbortSignal,
 ) {
-  const context = await integrations.getAgentToolsContext({workspaceId, defaultConnectionId});
+  const input = {workspaceId, defaultConnectionId};
+  const context =
+    signal === undefined
+      ? await integrations.getAgentToolsContext(input)
+      : await integrations.getAgentToolsContext(input, {signal});
   return {
     agentToolSelectionCatalogs: new Map(
       context.selectionCatalogs.map(({provider, selectors}) => [provider, {selectors}]),
@@ -32,6 +37,10 @@ export async function loadIntegrationValidationContext(
     workspaceConnectionSnapshot: new Map(
       context.workspaceConnections.map(({slug, ...connection}) => [slug, connection]),
     ),
+    eventCatalogs: new Map(
+      context.eventCatalogs.map(({provider, events}) => [provider, new Set(events)]),
+    ),
+    fixedEventProviders: new Set(context.fixedEventProviders),
     defaultConnectionSlug: context.defaultConnection?.slug,
   };
 }

package/src/core/parse-definition-diagnostics.test.ts

@@ -0,0 +1,47 @@
+import {agentValidationCatalog} from '#test/agent-validation-catalog.js';
+import {parseDefinitionWithDiagnostics} from './parse-definition.js';
+import {validateDefinition} from './validate-definition.js';
+
+vi.mock('./validate-definition.js', () => ({
+  validateDefinition: vi.fn(),
+}));
+
+describe('parseDefinitionWithDiagnostics', () => {
+  it('returns diagnostics from successful validation', () => {
+    vi.mocked(validateDefinition).mockReturnValue({
+      valid: true,
+      definition: {document: {}, model: {}} as never,
+      diagnostics: [
+        {
+          code: 'synthetic-warning',
+          message: 'A non-fatal validation warning',
+          path: 'jobs.build.steps.0.run',
+          severity: 'warning',
+        },
+        {
+          code: 'synthetic-error',
+          message: 'A trigger-scoped validation error',
+          path: 'triggers.on_demand',
+          severity: 'error',
+        },
+      ],
+    });
+
+    const parsed = parseDefinitionWithDiagnostics('name: Workflow', {agentValidationCatalog});
+
+    expect(parsed.diagnostics).toEqual([
+      {
+        code: 'synthetic-warning',
+        message: 'A non-fatal validation warning',
+        path: 'jobs.build.steps.0.run',
+        severity: 'warning',
+      },
+      {
+        code: 'synthetic-error',
+        message: 'A trigger-scoped validation error',
+        path: 'triggers.on_demand',
+        severity: 'error',
+      },
+    ]);
+  });
+});

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

@@ -3,7 +3,10 @@ import {dirname, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {agentValidationCatalog} from '#test/agent-validation-catalog.js';
 import {DefinitionParseError} from './errors.js';
-import {parseDefinition as parseDefinitionBase} from './parse-definition.js';
+import {
+  parseDefinition as parseDefinitionBase,
+  parseDefinitionWithDiagnostics as parseDefinitionWithDiagnosticsBase,
+} from './parse-definition.js';
 
 const fixturesDir = resolve(dirname(fileURLToPath(import.meta.url)), '../../test/fixtures');
 
@@ -11,6 +14,10 @@ function parseDefinition(yaml: string, options = {}) {
   return parseDefinitionBase(yaml, {agentValidationCatalog, ...options});
 }
 
+function parseDefinitionWithDiagnostics(yaml: string, options = {}) {
+  return parseDefinitionWithDiagnosticsBase(yaml, {agentValidationCatalog, ...options});
+}
+
 function readFixture(name: string): string {
   return readFileSync(resolve(fixturesDir, name), 'utf-8');
 }
@@ -177,7 +184,7 @@ jobs:
     expect(() => parseDefinition(yaml)).toThrow(DefinitionParseError);
   });
 
-  test('manual trigger requires an explicit event', () => {
+  test('manual trigger without an explicit event parses and materializes fire', () => {
     const yaml = `name: Manual only
 runner: ubuntu-latest
 triggers:
@@ -189,10 +196,19 @@ jobs:
       - run: echo hello
 `;
 
-    expect(() => parseDefinition(yaml)).toThrow(DefinitionParseError);
+    const definition = parseDefinition(yaml);
+
+    expect(definition.model.triggers).toEqual([
+      {
+        id: 'on-demand',
+        key: 'on_demand',
+        source: 'manual',
+        event: 'fire',
+      },
+    ]);
   });
 
-  test('declaring more than one manual trigger throws DefinitionParseError', () => {
+  test('keeps the first manual trigger active and makes later ones inert', () => {
     const yaml = `name: Multi manual
 runner: ubuntu-latest
 triggers:
@@ -206,6 +222,14 @@ jobs:
       - run: echo hello
 `;
 
-    expect(() => parseDefinition(yaml)).toThrow(DefinitionParseError);
+    const definition = parseDefinitionWithDiagnostics(yaml);
+
+    expect(definition.diagnostics).toEqual([
+      expect.objectContaining({
+        code: 'multiple-manual-triggers',
+        path: 'triggers.rollback',
+      }),
+    ]);
+    expect(definition.model.triggers.map((trigger) => trigger.key)).toEqual(['deploy']);
   });
 });

package/src/core/parse-definition.ts

@@ -1,15 +1,15 @@
-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 {DefinitionParseError} from './errors.js';
 import {type DefinitionValidationOptions, validateDefinition} from './validate-definition.js';
 
 export interface ParsedDefinition extends WorkflowDefinitionPayload {
-  warnings: ValidationWarning[];
+  diagnostics: ValidationDiagnostic[];
 }
 
 export type ParseDefinitionOptions = DefinitionValidationOptions;
 
-export function parseDefinitionWithWarnings(
+export function parseDefinitionWithDiagnostics(
   yamlString: string,
   options: ParseDefinitionOptions,
 ): ParsedDefinition {
@@ -25,7 +25,7 @@ export function parseDefinitionWithWarnings(
   return {
     ...result.definition,
     sourceSnapshot: {content: yamlString, format: 'yaml'},
-    warnings: result.warnings,
+    diagnostics: result.diagnostics,
   };
 }
 
@@ -33,11 +33,11 @@ export function parseDefinition(
   yamlString: string,
   options: ParseDefinitionOptions,
 ): WorkflowDefinitionPayload {
-  const parsed = parseDefinitionWithWarnings(yamlString, options);
-  return stripDefinitionWarnings(parsed);
+  const parsed = parseDefinitionWithDiagnostics(yamlString, options);
+  return stripDefinitionDiagnostics(parsed);
 }
 
-export function stripDefinitionWarnings(parsed: ParsedDefinition): WorkflowDefinitionPayload {
+export function stripDefinitionDiagnostics(parsed: ParsedDefinition): WorkflowDefinitionPayload {
   return {
     document: parsed.document,
     model: parsed.model,