@shipfox/api-definitions 12.3.0 → 14.0.0

package/src/db/sync-states.ts

@@ -1,11 +1,11 @@
 import {and, desc, eq} from 'drizzle-orm';
 import type {
+  DefinitionSyncDiagnostic,
   DefinitionSyncErrorCode,
   DefinitionSyncState,
   DefinitionSyncStatus,
-  DefinitionSyncWarning,
 } from '#core/entities/sync-state.js';
-import {limitDefinitionSyncWarnings} from '#core/entities/sync-state.js';
+import {limitDefinitionSyncDiagnostics} from '#core/entities/sync-state.js';
 import {db} from './db.js';
 import {definitionSyncStates, toDefinitionSyncState} from './schema/sync-states.js';
 
@@ -20,7 +20,7 @@ export interface MarkDefinitionSyncParams extends DefinitionSyncStateKey {
   status: DefinitionSyncStatus;
   lastErrorCode?: DefinitionSyncErrorCode | null | undefined;
   lastErrorMessage?: string | null | undefined;
-  warnings?: readonly DefinitionSyncWarning[] | null | undefined;
+  diagnostics?: readonly DefinitionSyncDiagnostic[] | null | undefined;
   startedAt?: Date | null | undefined;
   finishedAt?: Date | null | undefined;
 }
@@ -29,7 +29,7 @@ export async function markDefinitionSyncState(
   params: MarkDefinitionSyncParams,
 ): Promise<DefinitionSyncState> {
   const now = new Date();
-  const warnings = limitDefinitionSyncWarnings(params.warnings ?? []);
+  const diagnostics = limitDefinitionSyncDiagnostics(params.diagnostics ?? []);
   const [row] = await db()
     .insert(definitionSyncStates)
     .values({
@@ -40,7 +40,7 @@ export async function markDefinitionSyncState(
       status: params.status,
       lastErrorCode: params.lastErrorCode ?? null,
       lastErrorMessage: params.lastErrorMessage ?? null,
-      warnings,
+      warnings: diagnostics,
       startedAt: params.startedAt ?? null,
       finishedAt: params.finishedAt ?? null,
       updatedAt: now,
@@ -56,7 +56,7 @@ export async function markDefinitionSyncState(
         status: params.status,
         lastErrorCode: params.lastErrorCode ?? null,
         lastErrorMessage: params.lastErrorMessage ?? null,
-        warnings,
+        warnings: diagnostics,
         ...(params.startedAt !== undefined ? {startedAt: params.startedAt} : {}),
         ...(params.finishedAt !== undefined ? {finishedAt: params.finishedAt} : {}),
         updatedAt: now,

package/src/db/workflow-lineage-migration.test.ts

@@ -0,0 +1,158 @@
+import {randomUUID} from 'node:crypto';
+import {readFile} from 'node:fs/promises';
+import path from 'node:path';
+import pg from 'pg';
+import {migrationsPath} from '#db/index.js';
+
+const ADMIN_DATABASE = process.env.POSTGRES_DATABASE ?? 'api_test';
+
+function connectTo(database: string): Promise<pg.Client> {
+  const client = new pg.Client({
+    host: process.env.POSTGRES_DIRECT_HOST ?? process.env.POSTGRES_HOST ?? 'localhost',
+    port: Number(process.env.POSTGRES_PORT ?? 5432),
+    database,
+    user: process.env.POSTGRES_USERNAME ?? 'shipfox',
+    password: process.env.POSTGRES_PASSWORD ?? 'password',
+  });
+  return client.connect().then(() => client);
+}
+
+async function applyMigration(client: pg.Client, fileName: string): Promise<void> {
+  const source = await readFile(path.join(migrationsPath, fileName), 'utf8');
+  const statements = source
+    .split('--> statement-breakpoint')
+    .map((statement) => statement.trim())
+    .filter((statement) => statement.length > 0);
+  for (const statement of statements) {
+    await client.query(statement);
+  }
+}
+
+async function insertDefinition(
+  client: pg.Client,
+  params: {
+    id: string;
+    projectId: string;
+    configPath?: string | null;
+    source?: 'manual' | 'vcs';
+    ref?: string | null;
+    deleted?: boolean;
+  },
+): Promise<void> {
+  await client.query(
+    `INSERT INTO "definitions_workflow_definitions"
+       ("id", "project_id", "config_path", "source", "ref", "name", "definition", "deleted_at")
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+    [
+      params.id,
+      params.projectId,
+      params.configPath ?? null,
+      params.source ?? 'manual',
+      params.ref ?? null,
+      `Workflow ${params.id.slice(0, 8)}`,
+      JSON.stringify({document: {name: 'x'}, model: {}}),
+      params.deleted ? new Date().toISOString() : null,
+    ],
+  );
+}
+
+describe('workflow lineage schema migration (0003)', () => {
+  test('adds nullable lineage storage without backfilling existing definitions', async () => {
+    const scratch = `api_test_lineage_${randomUUID().replaceAll('-', '')}`;
+    const admin = await connectTo(ADMIN_DATABASE);
+    let target: pg.Client | undefined;
+    try {
+      await admin.query(`CREATE DATABASE "${scratch}"`);
+      target = await connectTo(scratch);
+
+      await applyMigration(target, '0000_initial.sql');
+      await applyMigration(target, '0001_definition_list_pagination.sql');
+      await applyMigration(target, '0002_lumpy_ben_parker.sql');
+
+      const projectA = randomUUID();
+      const projectB = randomUUID();
+      const rowA = randomUUID();
+      const rowManual = randomUUID();
+      const rowVcs = randomUUID();
+      const rowBranchMain = randomUUID();
+      const rowBranchDev = randomUUID();
+      const rowGone = randomUUID();
+      const rowNoPath = randomUUID();
+      const rowNoPathSecond = randomUUID();
+
+      await insertDefinition(target, {
+        id: rowA,
+        projectId: projectA,
+        configPath: 'a.yml',
+        source: 'vcs',
+        ref: 'main',
+      });
+      await insertDefinition(target, {
+        id: rowManual,
+        projectId: projectA,
+        configPath: 'shared.yml',
+      });
+      await insertDefinition(target, {
+        id: rowVcs,
+        projectId: projectA,
+        configPath: 'shared.yml',
+        source: 'vcs',
+        ref: 'main',
+      });
+      await insertDefinition(target, {
+        id: rowBranchMain,
+        projectId: projectA,
+        configPath: 'branches.yml',
+        source: 'vcs',
+        ref: 'main',
+      });
+      await insertDefinition(target, {
+        id: rowBranchDev,
+        projectId: projectA,
+        configPath: 'branches.yml',
+        source: 'vcs',
+        ref: 'dev',
+      });
+      await insertDefinition(target, {
+        id: rowGone,
+        projectId: projectA,
+        configPath: 'gone.yml',
+        source: 'vcs',
+        ref: 'main',
+        deleted: true,
+      });
+      await insertDefinition(target, {id: rowNoPath, projectId: projectB});
+      await insertDefinition(target, {id: rowNoPathSecond, projectId: projectB});
+
+      await applyMigration(target, '0003_nebulous_nemesis.sql');
+
+      const rows = (
+        await target.query<{id: string; workflow_id: string | null; config_path: string | null}>(
+          `SELECT "id", "workflow_id", "config_path"
+           FROM "definitions_workflow_definitions" ORDER BY "id"`,
+        )
+      ).rows;
+      const workflows = (
+        await target.query<{id: string; config_path: string | null}>(
+          `SELECT "id", "config_path" FROM "definitions_workflows" ORDER BY "id"`,
+        )
+      ).rows;
+
+      expect(rows).toHaveLength(8);
+      expect(rows.every((row) => row.workflow_id === null)).toBe(true);
+      expect(workflows).toHaveLength(0);
+
+      // The unique (project_id, config_path) constraint accepts a second project
+      // with the same path.
+      await target.query(
+        `INSERT INTO "definitions_workflows" ("id", "project_id", "config_path")
+         VALUES ($1, $2, 'a.yml')`,
+        [randomUUID(), projectB],
+      );
+    } finally {
+      await target?.end();
+      await admin.query(`DROP DATABASE IF EXISTS "${scratch}" WITH (FORCE)`);
+      await admin.end();
+    }
+  });
+});

package/src/index.ts

@@ -98,6 +98,8 @@ export function createDefinitionsModule({
         workflows: [],
       },
     ],
-    interModulePresentations: [createDefinitionsInterModulePresentation()],
+    interModulePresentations: [
+      createDefinitionsInterModulePresentation({projects, agent, integrations}),
+    ],
   };
 }

package/src/metrics/index.ts

@@ -0,0 +1 @@
+export {recordDefinitionRefResolution} from './instance.js';

package/src/metrics/instance.test.ts

@@ -0,0 +1,50 @@
+const metricMocks = vi.hoisted(() => {
+  const counters = new Map<string, {add: ReturnType<typeof vi.fn>}>();
+  const createCounter = vi.fn((name: string) => {
+    const counter = {add: vi.fn()};
+    counters.set(name, counter);
+    return counter;
+  });
+
+  return {counters, createCounter};
+});
+
+vi.mock('@shipfox/node-opentelemetry', () => ({
+  instanceMetrics: {
+    getMeter: () => ({createCounter: metricMocks.createCounter}),
+  },
+}));
+
+const metrics = await import('./instance.js');
+
+function counterAdd(name: string): ReturnType<typeof vi.fn> {
+  const counter = metricMocks.counters.get(name);
+  if (!counter) throw new Error(`Missing counter: ${name}`);
+  return counter.add;
+}
+
+describe('definition at-ref metrics', () => {
+  beforeEach(() => {
+    counterAdd('definitions_ref_resolutions').mockReset();
+  });
+
+  test.each([
+    'resolved',
+    'ref-moved',
+    'content-too-large',
+    'too-many-files',
+    'source-unavailable',
+  ] as const)('records the %s outcome', (outcome) => {
+    metrics.recordDefinitionRefResolution(outcome);
+
+    expect(counterAdd('definitions_ref_resolutions')).toHaveBeenCalledWith(1, {outcome});
+  });
+
+  test('does not let metric failures affect resolution callers', () => {
+    counterAdd('definitions_ref_resolutions').mockImplementationOnce(() => {
+      throw new Error('metrics unavailable');
+    });
+
+    expect(() => metrics.recordDefinitionRefResolution('resolved')).not.toThrow();
+  });
+});

package/src/metrics/instance.ts

@@ -0,0 +1,23 @@
+import {instanceMetrics} from '@shipfox/node-opentelemetry';
+import type {DefinitionAtRefErrorCode} from '#core/errors.js';
+
+const meter = instanceMetrics.getMeter('definitions');
+
+export type DefinitionRefResolutionOutcome = DefinitionAtRefErrorCode | 'resolved';
+
+const refResolutionCount = meter.createCounter<{outcome: DefinitionRefResolutionOutcome}>(
+  'definitions_ref_resolutions',
+  {description: 'Workflow definition resolutions at a git ref by outcome'},
+);
+
+function recordMetric(record: () => void): void {
+  try {
+    record();
+  } catch {
+    // Metrics must not affect definition resolution outcomes.
+  }
+}
+
+export function recordDefinitionRefResolution(outcome: DefinitionRefResolutionOutcome): void {
+  recordMetric(() => refResolutionCount.add(1, {outcome}));
+}

package/src/presentation/dto/definition.test.ts

@@ -1,7 +1,8 @@
+import type {DefinitionSyncState} from '#core/entities/sync-state.js';
 import type {WorkflowDefinition} from '#core/entities/workflow-definition.js';
 import {normalizeWorkflowDocument} from '#core/workflow-model/index.js';
 import {agentValidationCatalog} from '#test/agent-validation-catalog.js';
-import {toDefinitionDto} from './definition.js';
+import {toDefinitionDto, toDefinitionSyncSummaryDto} from './definition.js';
 
 describe('toDefinitionDto', () => {
   it('maps the workflow definition entity to the public DTO shape', () => {
@@ -22,6 +23,7 @@ describe('toDefinitionDto', () => {
     };
     const definition: WorkflowDefinition = {
       id: '019e98ab-6656-7ca1-b9ad-1ca4442c479d',
+      workflowId: '019e98ab-6656-7ca1-b9ad-1ca4442c479e',
       projectId: '019e98ab-b90f-7265-b13c-8b441c991381',
       configPath: '.shipfox/workflows/manual.yml',
       source: 'manual',
@@ -57,4 +59,90 @@ describe('toDefinitionDto', () => {
       updated_at: '2026-06-09T10:00:02.000Z',
     });
   });
+
+  it('computes manual_trigger from the model so an inert manual trigger hides the Run button', () => {
+    const document = {
+      name: 'Manual workflow',
+      runner: 'ubuntu-latest',
+      triggers: {
+        run_now: {
+          source: 'manual',
+          event: 'fire',
+          filter: 'event.ref == "refs/heads/main"',
+        },
+      },
+      jobs: {
+        build: {
+          steps: [{run: 'pnpm build'}],
+        },
+      },
+    };
+    const definition: WorkflowDefinition = {
+      id: '019e98ab-6656-7ca1-b9ad-1ca4442c479d',
+      workflowId: '019e98ab-6656-7ca1-b9ad-1ca4442c479e',
+      projectId: '019e98ab-b90f-7265-b13c-8b441c991381',
+      configPath: '.shipfox/workflows/manual.yml',
+      source: 'manual',
+      sha: null,
+      ref: null,
+      name: document.name,
+      definition: document,
+      document,
+      // The manual trigger is inert: it carries a trigger-scoped error and is
+      // excluded from the model, while the document keeps the authored entry.
+      model: normalizeWorkflowDocument(document, {agentValidationCatalog}),
+      sourceSnapshot: null,
+      contentHash: null,
+      fetchedAt: new Date('2026-06-09T10:00:00.000Z'),
+      createdAt: new Date('2026-06-09T10:00:01.000Z'),
+      updatedAt: new Date('2026-06-09T10:00:02.000Z'),
+      deletedAt: null,
+    };
+
+    const result = toDefinitionDto(definition);
+
+    expect(result.workflow_document).toEqual(document);
+    expect((result.workflow_model as {triggers: readonly unknown[]}).triggers).toEqual([]);
+    expect(result.manual_trigger).toBeNull();
+  });
+});
+
+describe('toDefinitionSyncSummaryDto', () => {
+  it('maps the workflow file path to the public DTO field', () => {
+    const syncState = {
+      id: '019e98ab-6656-7ca1-b9ad-1ca4442c479d',
+      projectId: '019e98ab-b90f-7265-b13c-8b441c991381',
+      sourceConnectionId: '019e98ab-b90f-7265-b13c-8b441c991382',
+      sourceExternalRepositoryId: 'gitea:owner/platform',
+      ref: 'main',
+      status: 'succeeded',
+      lastErrorCode: null,
+      lastErrorMessage: null,
+      diagnostics: [
+        {
+          code: 'warning-code',
+          message: 'Warning',
+          path: 'jobs.build.steps.0.run',
+          filePath: '.shipfox/workflows/ci.yml',
+          severity: 'warning',
+        },
+      ],
+      startedAt: new Date('2026-06-09T10:00:00.000Z'),
+      finishedAt: new Date('2026-06-09T10:00:01.000Z'),
+      createdAt: new Date('2026-06-09T10:00:00.000Z'),
+      updatedAt: new Date('2026-06-09T10:00:01.000Z'),
+    } satisfies DefinitionSyncState;
+
+    expect(toDefinitionSyncSummaryDto(syncState)).toMatchObject({
+      diagnostics: [
+        {
+          code: 'warning-code',
+          message: 'Warning',
+          path: 'jobs.build.steps.0.run',
+          file_path: '.shipfox/workflows/ci.yml',
+          severity: 'warning',
+        },
+      ],
+    });
+  });
 });

package/src/presentation/dto/definition.ts

@@ -4,9 +4,9 @@ import type {WorkflowDefinition} from '#core/entities/workflow-definition.js';
 import {UNRESOLVED_SYNC_REF} from '#core/sync-definitions.js';
 
 export function toDefinitionDto(definition: WorkflowDefinition): DefinitionDto {
-  const manualEntry = Object.entries(definition.document.triggers ?? {}).find(
-    ([, trigger]) => trigger.source === 'manual',
-  );
+  // The model excludes inert triggers, so an inert manual trigger yields no Run
+  // button instead of a fire-route 404. The document keeps the authored entry.
+  const manualTrigger = definition.model.triggers.find((trigger) => trigger.source === 'manual');
   return {
     id: definition.id,
     project_id: definition.projectId,
@@ -17,7 +17,7 @@ export function toDefinitionDto(definition: WorkflowDefinition): DefinitionDto {
     name: definition.name,
     workflow_document: definition.document,
     workflow_model: definition.model,
-    manual_trigger: manualEntry ? {name: manualEntry[0]} : null,
+    manual_trigger: manualTrigger ? {name: manualTrigger.key} : null,
     fetched_at: definition.fetchedAt.toISOString(),
     created_at: definition.createdAt.toISOString(),
     updated_at: definition.updatedAt.toISOString(),
@@ -37,6 +37,9 @@ export function toDefinitionSyncSummaryDto(
     finished_at: syncState.finishedAt?.toISOString() ?? null,
     last_error_code: syncState.lastErrorCode,
     last_error_message: syncState.lastErrorMessage,
-    warnings: syncState.warnings,
+    diagnostics: syncState.diagnostics.map(({filePath, ...diagnostic}) => ({
+      ...diagnostic,
+      ...(filePath === undefined ? {} : {file_path: filePath}),
+    })),
   };
 }

package/src/presentation/inter-module.test.ts

@@ -0,0 +1,177 @@
+import {definitionsInterModuleContract} from '@shipfox/api-definitions-dto/inter-module';
+import {isInterModuleKnownError} from '@shipfox/inter-module';
+import {DefinitionAtRefError} from '#core/errors.js';
+import {createDefinitionsInterModulePresentation} from './inter-module.js';
+
+const mocks = vi.hoisted(() => ({
+  getDefinitionById: vi.fn(),
+  listDefinitionsAtRef: vi.fn(),
+  resolveDefinitionAtRef: vi.fn(),
+}));
+
+vi.mock('#db/definitions.js', () => ({
+  getDefinitionById: mocks.getDefinitionById,
+}));
+
+vi.mock('#core/index.js', async (importOriginal) => {
+  const original = await importOriginal<typeof import('#core/index.js')>();
+  return {
+    ...original,
+    listDefinitionsAtRef: mocks.listDefinitionsAtRef,
+    resolveDefinitionAtRef: mocks.resolveDefinitionAtRef,
+  };
+});
+
+const PROJECT_ID = '00000000-0000-4000-8000-000000000001';
+const REF = 'fix-branch';
+const CONFIG_PATH = '.shipfox/workflows/ci.yml';
+const COMMIT = 'a1b2c3d4e5f6a7b8c9d0a1b2c3d4e5f6a7b8c9d0';
+
+function presentation() {
+  return createDefinitionsInterModulePresentation({
+    projects: {} as never,
+    agent: {} as never,
+    integrations: {} as never,
+  });
+}
+
+async function rejection(promise: Promise<unknown> | unknown): Promise<unknown> {
+  return await Promise.resolve(promise).catch((error: unknown) => error);
+}
+
+describe('definitions inter-module presentation', () => {
+  beforeEach(() => {
+    mocks.resolveDefinitionAtRef.mockReset();
+    mocks.listDefinitionsAtRef.mockReset();
+    mocks.getDefinitionById.mockReset();
+  });
+
+  it('resolves a definition at a ref through the core method', async () => {
+    const resolved = {
+      workflow: {id: '00000000-0000-4000-8000-000000000002', configPath: CONFIG_PATH},
+      commit: COMMIT,
+      model: {
+        version: 2,
+        model: {kind: 'workflow', name: 'CI', triggers: [], jobs: [], dependencies: []},
+      },
+      sourceSnapshot: {content: 'name: CI', format: 'yaml'},
+      triggers: {},
+      warnings: [],
+    };
+    mocks.resolveDefinitionAtRef.mockResolvedValue(resolved);
+    const controller = new AbortController();
+
+    const result = await presentation().handlers.resolveDefinitionAtRef(
+      {projectId: PROJECT_ID, ref: REF, configPath: CONFIG_PATH},
+      {signal: controller.signal},
+    );
+
+    expect(result).toEqual(resolved);
+    expect(mocks.resolveDefinitionAtRef).toHaveBeenCalledWith(
+      expect.objectContaining({
+        projectId: PROJECT_ID,
+        ref: REF,
+        configPath: CONFIG_PATH,
+        signal: controller.signal,
+      }),
+    );
+  });
+
+  it('maps every resolution domain error to its known error details', async () => {
+    const method = definitionsInterModuleContract.methods.resolveDefinitionAtRef;
+    const cases: Array<{
+      code: DefinitionAtRefError['code'];
+      details: Record<string, unknown>;
+      expected: Record<string, unknown>;
+    }> = [
+      {
+        code: 'project-not-found',
+        details: {projectId: PROJECT_ID},
+        expected: {projectId: PROJECT_ID},
+      },
+      {code: 'ref-not-found', details: {ref: REF}, expected: {ref: REF}},
+      {code: 'ref-invalid', details: {ref: REF}, expected: {ref: REF}},
+      {
+        code: 'ref-moved',
+        details: {ref: REF, expectedCommit: COMMIT},
+        expected: {ref: REF, expectedCommit: COMMIT},
+      },
+      {
+        code: 'file-not-found',
+        details: {ref: REF, configPath: CONFIG_PATH},
+        expected: {ref: REF, configPath: CONFIG_PATH},
+      },
+      {
+        code: 'content-too-large',
+        details: {configPath: CONFIG_PATH},
+        expected: {configPath: CONFIG_PATH},
+      },
+      {
+        code: 'invalid-definition',
+        details: {errors: [{message: 'Invalid YAML', path: 'jobs'}]},
+        expected: {errors: [{message: 'Invalid YAML', path: 'jobs'}]},
+      },
+      {code: 'source-unavailable', details: {}, expected: {}},
+    ];
+
+    for (const {code, details, expected} of cases) {
+      mocks.resolveDefinitionAtRef.mockRejectedValueOnce(
+        new DefinitionAtRefError(code, `boom: ${code}`, details),
+      );
+      const error = await rejection(
+        presentation().handlers.resolveDefinitionAtRef(
+          {projectId: PROJECT_ID, ref: REF, configPath: CONFIG_PATH},
+          {signal: new AbortController().signal},
+        ),
+      );
+      expect(isInterModuleKnownError(method, error)).toBe(true);
+      expect((error as {code: string}).code).toBe(code);
+      expect((error as {details: unknown}).details).toEqual(expected);
+    }
+  });
+
+  it('re-throws unknown errors without mapping them', async () => {
+    const boom = new Error('unexpected');
+    mocks.resolveDefinitionAtRef.mockRejectedValue(boom);
+    const error = await rejection(
+      presentation().handlers.resolveDefinitionAtRef(
+        {projectId: PROJECT_ID, ref: REF, configPath: CONFIG_PATH},
+        {signal: new AbortController().signal},
+      ),
+    );
+    expect(error).toBe(boom);
+  });
+
+  it('lists definitions at a ref with only the declared listing errors', async () => {
+    const method = definitionsInterModuleContract.methods.listDefinitionsAtRef;
+    mocks.listDefinitionsAtRef.mockRejectedValueOnce(
+      new DefinitionAtRefError('ref-not-found', 'boom', {ref: REF}),
+    );
+    const error = await rejection(
+      presentation().handlers.listDefinitionsAtRef(
+        {projectId: PROJECT_ID, ref: REF},
+        {signal: new AbortController().signal},
+      ),
+    );
+    expect(isInterModuleKnownError(method, error)).toBe(true);
+    expect((error as {code: string}).code).toBe('ref-not-found');
+  });
+
+  it('maps the listing file-limit failure to its known error', async () => {
+    const method = definitionsInterModuleContract.methods.listDefinitionsAtRef;
+    mocks.listDefinitionsAtRef.mockRejectedValueOnce(
+      new DefinitionAtRefError('too-many-files', 'too many files'),
+    );
+
+    const error = await rejection(
+      presentation().handlers.listDefinitionsAtRef(
+        {projectId: PROJECT_ID, ref: REF},
+        {signal: new AbortController().signal},
+      ),
+    );
+
+    expect(isInterModuleKnownError(method, error)).toBe(true);
+    expect((error as {code: string}).code).toBe('too-many-files');
+    expect((error as {details: unknown}).details).toEqual({});
+  });
+});