@shipfox/client-workflows 15.0.0 → 17.0.0

package/src/core/run-annotation.test.ts

@@ -0,0 +1,315 @@
+import {
+  workflowJob,
+  workflowJobExecutionDto,
+  workflowStepAttemptDto,
+  workflowStepDto,
+} from '#test/fixtures/workflow-run.js';
+import {
+  buildRunAnnotationList,
+  highestRunAnnotationSeverity,
+  type RunAnnotationRecord,
+  type RunAnnotationStyle,
+  summarizeJobAnnotations,
+  summarizeRunAnnotations,
+} from './run-annotation.js';
+import type {Job} from './workflow-run.js';
+
+const BUILD_JOB_ID = '44444444-4444-4444-8444-00000000000b';
+const TEST_JOB_ID = '44444444-4444-4444-8444-00000000000c';
+const BUILD_EXECUTION_ID = '77777777-7777-4777-8777-00000000000b';
+const TEST_EXECUTION_ONE_ID = '77777777-7777-4777-8777-00000000000c';
+const TEST_EXECUTION_TWO_ID = '77777777-7777-4777-8777-00000000000d';
+const BUILD_STEP_ID = '55555555-5555-4555-8555-00000000000b';
+const TEST_STEP_ID = '55555555-5555-4555-8555-00000000000c';
+const BUILD_ATTEMPT_ID = '66666666-6666-4666-8666-00000000000b';
+
+describe('summarizeRunAnnotations', () => {
+  test('counts every annotation in the total and only severities per severity', () => {
+    const annotations = [
+      annotation({id: 'a', style: 'error'}),
+      annotation({id: 'b', style: 'warning'}),
+      annotation({id: 'c', style: 'default'}),
+      annotation({id: 'd', style: 'error'}),
+    ];
+
+    const summary = summarizeRunAnnotations(annotations);
+
+    expect(summary).toEqual({
+      total: 4,
+      error: 2,
+      warning: 1,
+      info: 0,
+      success: 0,
+      truncated: false,
+    });
+  });
+
+  test('carries truncation so counts read as a lower bound', () => {
+    const summary = summarizeRunAnnotations([annotation({id: 'a', style: 'info'})], {
+      truncated: true,
+    });
+
+    expect(summary.truncated).toBe(true);
+  });
+});
+
+describe('summarizeJobAnnotations', () => {
+  test('counts only the annotations owned by one job', () => {
+    const annotations = [
+      annotation({id: 'a', style: 'error', jobId: BUILD_JOB_ID}),
+      annotation({id: 'b', style: 'warning', jobId: TEST_JOB_ID}),
+      annotation({id: 'c', style: 'info', jobId: TEST_JOB_ID}),
+    ];
+
+    const summary = summarizeJobAnnotations(annotations, TEST_JOB_ID);
+
+    expect(summary.total).toBe(2);
+    expect(summary.error).toBe(0);
+    expect(summary.warning).toBe(1);
+  });
+});
+
+describe('highestRunAnnotationSeverity', () => {
+  test('reports the loudest severity present', () => {
+    const summary = summarizeRunAnnotations([
+      annotation({id: 'a', style: 'success'}),
+      annotation({id: 'b', style: 'warning'}),
+    ]);
+
+    expect(highestRunAnnotationSeverity(summary)).toBe('warning');
+  });
+
+  test('reports nothing when only unstyled annotations exist', () => {
+    const summary = summarizeRunAnnotations([annotation({id: 'a', style: 'default'})]);
+
+    expect(highestRunAnnotationSeverity(summary)).toBeNull();
+  });
+});
+
+describe('buildRunAnnotationList', () => {
+  test('ranks by severity before emission order', () => {
+    const annotations = [
+      annotation({id: 'a', style: 'success', sequence: 1}),
+      annotation({id: 'b', style: 'error', sequence: 2}),
+      annotation({id: 'c', style: 'default', sequence: 3}),
+      annotation({id: 'd', style: 'warning', sequence: 4}),
+      annotation({id: 'e', style: 'info', sequence: 5}),
+    ];
+
+    const entries = buildRunAnnotationList({annotations, jobs: jobs()});
+
+    expect(entries.map((entry) => entry.annotation.id)).toEqual(['b', 'd', 'e', 'a', 'c']);
+  });
+
+  test('breaks a severity tie by job position before sequence', () => {
+    // `sequence` restarts per execution, so the later job's lower sequence must not lead.
+    const annotations = [
+      annotation({id: 'late-job', style: 'error', sequence: 1, jobId: TEST_JOB_ID}),
+      annotation({id: 'early-job', style: 'error', sequence: 9, jobId: BUILD_JOB_ID}),
+    ];
+
+    const entries = buildRunAnnotationList({annotations, jobs: jobs()});
+
+    expect(entries.map((entry) => entry.annotation.id)).toEqual(['early-job', 'late-job']);
+  });
+
+  test('breaks a job tie by execution sequence', () => {
+    const annotations = [
+      annotation({
+        id: 'second-execution',
+        style: 'error',
+        sequence: 1,
+        jobId: TEST_JOB_ID,
+        jobExecutionId: TEST_EXECUTION_TWO_ID,
+      }),
+      annotation({
+        id: 'first-execution',
+        style: 'error',
+        sequence: 2,
+        jobId: TEST_JOB_ID,
+        jobExecutionId: TEST_EXECUTION_ONE_ID,
+      }),
+    ];
+
+    const entries = buildRunAnnotationList({annotations, jobs: jobs()});
+
+    expect(entries.map((entry) => entry.annotation.id)).toEqual([
+      'first-execution',
+      'second-execution',
+    ]);
+  });
+
+  test('resolves provenance and an origin the run can route back to', () => {
+    const annotations = [annotation({id: 'a', style: 'error'})];
+
+    const [entry] = buildRunAnnotationList({annotations, jobs: jobs()});
+
+    expect(entry?.jobName).toBe('build');
+    expect(entry?.stepLabel).toBe('compile');
+    expect(entry?.attemptLabel).toBe('attempt 1');
+    expect(entry?.origin).toEqual({
+      jobId: BUILD_JOB_ID,
+      jobExecutionId: BUILD_EXECUTION_ID,
+      stepId: BUILD_STEP_ID,
+      stepAttemptId: BUILD_ATTEMPT_ID,
+    });
+  });
+
+  test('names an execution only when the job ran more than once', () => {
+    const annotations = [
+      annotation({id: 'single', style: 'info'}),
+      annotation({
+        id: 'multi',
+        style: 'info',
+        jobId: TEST_JOB_ID,
+        jobExecutionId: TEST_EXECUTION_TWO_ID,
+        originStepId: TEST_STEP_ID,
+      }),
+    ];
+
+    const entries = buildRunAnnotationList({annotations, jobs: jobs()});
+    const byId = new Map(entries.map((entry) => [entry.annotation.id, entry]));
+
+    expect(byId.get('single')?.executionLabel).toBeNull();
+    expect(byId.get('multi')?.executionLabel).toBe('execution #2');
+  });
+
+  test('keeps an annotation whose step the run attempt no longer holds, without an origin', () => {
+    const annotations = [
+      annotation({
+        id: 'orphan',
+        style: 'error',
+        originStepId: '55555555-5555-4555-8555-0000000000ff',
+      }),
+    ];
+
+    const [entry] = buildRunAnnotationList({annotations, jobs: jobs()});
+
+    expect(entry?.annotation.id).toBe('orphan');
+    expect(entry?.jobName).toBe('build');
+    expect(entry?.stepLabel).toBeNull();
+    expect(entry?.origin).toBeNull();
+  });
+
+  test('sorts an annotation from an unknown job last rather than first', () => {
+    const annotations = [
+      annotation({
+        id: 'unknown-job',
+        style: 'error',
+        jobId: '44444444-4444-4444-8444-0000000000ff',
+      }),
+      annotation({id: 'known-job', style: 'error'}),
+    ];
+
+    const entries = buildRunAnnotationList({annotations, jobs: jobs()});
+
+    expect(entries.map((entry) => entry.annotation.id)).toEqual(['known-job', 'unknown-job']);
+  });
+
+  test('filters by severity and by job', () => {
+    const annotations = [
+      annotation({id: 'build-error', style: 'error'}),
+      annotation({id: 'build-info', style: 'info'}),
+      annotation({id: 'test-error', style: 'error', jobId: TEST_JOB_ID}),
+    ];
+
+    expect(
+      buildRunAnnotationList({annotations, jobs: jobs(), severity: 'error'}).map(
+        (entry) => entry.annotation.id,
+      ),
+    ).toEqual(['build-error', 'test-error']);
+    expect(
+      buildRunAnnotationList({annotations, jobs: jobs(), jobId: BUILD_JOB_ID}).map(
+        (entry) => entry.annotation.id,
+      ),
+    ).toEqual(['build-error', 'build-info']);
+  });
+
+  test('never selects an unstyled annotation with a severity filter', () => {
+    const annotations = [annotation({id: 'plain', style: 'default'})];
+
+    expect(buildRunAnnotationList({annotations, jobs: jobs(), severity: 'info'})).toEqual([]);
+  });
+});
+
+function annotation(
+  overrides: Partial<RunAnnotationRecord> & {id: string; style: RunAnnotationStyle},
+): RunAnnotationRecord {
+  return {
+    jobId: BUILD_JOB_ID,
+    jobExecutionId: BUILD_EXECUTION_ID,
+    originStepId: BUILD_STEP_ID,
+    originStepAttempt: 1,
+    context: `context-${overrides.id}`,
+    sequence: 1,
+    body: 'Body',
+    ...overrides,
+  };
+}
+
+function jobs(): Job[] {
+  return [
+    workflowJob({
+      id: BUILD_JOB_ID,
+      key: 'build',
+      name: 'build',
+      position: 0,
+      job_executions: [
+        workflowJobExecutionDto({
+          id: BUILD_EXECUTION_ID,
+          job_id: BUILD_JOB_ID,
+          sequence: 1,
+          steps: [
+            workflowStepDto({
+              id: BUILD_STEP_ID,
+              job_execution_id: BUILD_EXECUTION_ID,
+              name: 'compile',
+              attempts: [
+                workflowStepAttemptDto({
+                  id: BUILD_ATTEMPT_ID,
+                  step_id: BUILD_STEP_ID,
+                  attempt: 1,
+                  status: 'succeeded',
+                }),
+              ],
+            }),
+          ],
+        }),
+      ],
+    }),
+    workflowJob({
+      id: TEST_JOB_ID,
+      key: 'test',
+      name: 'test',
+      position: 1,
+      job_executions: [
+        workflowJobExecutionDto({
+          id: TEST_EXECUTION_ONE_ID,
+          job_id: TEST_JOB_ID,
+          sequence: 1,
+          steps: [
+            workflowStepDto({
+              id: TEST_STEP_ID,
+              job_execution_id: TEST_EXECUTION_ONE_ID,
+              name: 'run tests',
+              attempts: [],
+            }),
+          ],
+        }),
+        workflowJobExecutionDto({
+          id: TEST_EXECUTION_TWO_ID,
+          job_id: TEST_JOB_ID,
+          sequence: 2,
+          steps: [
+            workflowStepDto({
+              id: TEST_STEP_ID,
+              job_execution_id: TEST_EXECUTION_TWO_ID,
+              name: 'run tests',
+              attempts: [],
+            }),
+          ],
+        }),
+      ],
+    }),
+  ];
+}

package/src/core/run-annotation.ts

@@ -0,0 +1,244 @@
+import type {Job} from './workflow-run.js';
+
+export type RunAnnotationStyle = 'default' | 'info' | 'success' | 'warning' | 'error';
+
+/**
+ * The severities the run surfaces rank and filter by. The `default` style carries no severity:
+ * it counts toward the total and sorts last, but no severity filter selects it.
+ */
+export const RUN_ANNOTATION_SEVERITIES = ['error', 'warning', 'info', 'success'] as const;
+
+export type RunAnnotationSeverity = (typeof RUN_ANNOTATION_SEVERITIES)[number];
+
+const SEVERITY_RANK: Record<RunAnnotationStyle, number> = {
+  error: 0,
+  warning: 1,
+  info: 2,
+  success: 3,
+  default: 4,
+};
+
+const SEVERITY_SET = new Set<string>(RUN_ANNOTATION_SEVERITIES);
+
+export interface RunAnnotation {
+  id: string;
+  jobId: string;
+  jobExecutionId: string;
+  originStepId: string;
+  originStepAttempt: number;
+  context: string;
+  style: RunAnnotationStyle;
+  sequence: number;
+}
+
+export interface RunAnnotationRecord extends RunAnnotation {
+  body: string;
+}
+
+/** Counts shown by the run rail and the severity summary line. */
+export interface RunAnnotationSummary {
+  total: number;
+  error: number;
+  warning: number;
+  info: number;
+  success: number;
+  /** True when the read hit its page budget, so every count is a lower bound. */
+  truncated: boolean;
+  /** Optional per-step counts used by the step inspector without loading annotation bodies. */
+  stepCounts?: readonly {
+    stepId: string;
+    attempt: number;
+    total: number;
+  }[];
+}
+
+/** Everything the annotations list needs to route back to the step that emitted an annotation. */
+export interface RunAnnotationOrigin {
+  jobId: string;
+  jobExecutionId: string;
+  stepId: string;
+  stepAttemptId: string;
+}
+
+export interface RunAnnotationEntry {
+  annotation: RunAnnotationRecord;
+  jobName: string | null;
+  /** Only set when the job ran more than once, so a single-execution job stays uncluttered. */
+  executionLabel: string | null;
+  stepLabel: string | null;
+  attemptLabel: string;
+  /** `null` when the run attempt no longer contains the emitting step, so no link is offered. */
+  origin: RunAnnotationOrigin | null;
+}
+
+export function annotationSeverity(style: RunAnnotationStyle): RunAnnotationSeverity | null {
+  return SEVERITY_SET.has(style) ? (style as RunAnnotationSeverity) : null;
+}
+
+export function summarizeRunAnnotations(
+  annotations: readonly RunAnnotation[],
+  {truncated = false}: {truncated?: boolean | undefined} = {},
+): RunAnnotationSummary {
+  const summary: RunAnnotationSummary = {
+    total: annotations.length,
+    error: 0,
+    warning: 0,
+    info: 0,
+    success: 0,
+    truncated,
+  };
+
+  for (const annotation of annotations) {
+    const severity = annotationSeverity(annotation.style);
+    if (severity) summary[severity] += 1;
+  }
+
+  return summary;
+}
+
+export interface BuildRunAnnotationListInput {
+  annotations: readonly RunAnnotationRecord[];
+  jobs: readonly Job[];
+  severity?: RunAnnotationSeverity | undefined;
+  jobId?: string | undefined;
+}
+
+/**
+ * Ranks annotations for display.
+ *
+ * Severity leads: emission order is a log affordance, not a summary affordance. `sequence` is
+ * only stable within one job execution, so the tie-break walks down job position and execution
+ * sequence before using it, and ends on the id so the order never depends on input order.
+ */
+export function buildRunAnnotationList({
+  annotations,
+  jobs,
+  severity,
+  jobId,
+}: BuildRunAnnotationListInput): RunAnnotationEntry[] {
+  const index = indexJobs(jobs);
+  const entries: RunAnnotationEntry[] = [];
+
+  for (const annotation of annotations) {
+    if (jobId && annotation.jobId !== jobId) continue;
+    const annotationSeverityValue = annotationSeverity(annotation.style);
+    if (severity && annotationSeverityValue !== severity) continue;
+    entries.push(toEntry(annotation, index));
+  }
+
+  return entries.sort((left, right) => compareEntries(left, right, index));
+}
+
+/** Counts annotations owned by one job, for the job page's bounded reference chip. */
+export function summarizeJobAnnotations(
+  annotations: readonly RunAnnotation[],
+  jobId: string,
+  options: {truncated?: boolean | undefined} = {},
+): RunAnnotationSummary {
+  return summarizeRunAnnotations(
+    annotations.filter((annotation) => annotation.jobId === jobId),
+    options,
+  );
+}
+
+/** The loudest severity present, which tints a count chip. */
+export function highestRunAnnotationSeverity(
+  summary: RunAnnotationSummary,
+): RunAnnotationSeverity | null {
+  return RUN_ANNOTATION_SEVERITIES.find((severity) => summary[severity] > 0) ?? null;
+}
+
+interface JobIndexEntry {
+  position: number;
+  name: string;
+  executionCount: number;
+  executions: Map<string, JobExecutionIndexEntry>;
+}
+
+interface JobExecutionIndexEntry {
+  sequence: number;
+  steps: Map<string, {label: string; attemptIds: Map<number, string>}>;
+}
+
+function indexJobs(jobs: readonly Job[]): Map<string, JobIndexEntry> {
+  const index = new Map<string, JobIndexEntry>();
+
+  for (const job of jobs) {
+    const executions = new Map<string, JobExecutionIndexEntry>();
+    for (const execution of job.jobExecutions) {
+      const steps = new Map<string, {label: string; attemptIds: Map<number, string>}>();
+      for (const step of execution.steps) {
+        const attemptIds = new Map<number, string>();
+        for (const attempt of step.attempts) attemptIds.set(attempt.attempt, attempt.id);
+        steps.set(step.id, {label: step.name || step.key || step.id, attemptIds});
+      }
+      executions.set(execution.id, {sequence: execution.sequence, steps});
+    }
+
+    index.set(job.id, {
+      position: job.position,
+      name: job.displayName,
+      executionCount: job.jobExecutions.length,
+      executions,
+    });
+  }
+
+  return index;
+}
+
+function toEntry(
+  annotation: RunAnnotationRecord,
+  index: Map<string, JobIndexEntry>,
+): RunAnnotationEntry {
+  const job = index.get(annotation.jobId);
+  const execution = job?.executions.get(annotation.jobExecutionId);
+  const step = execution?.steps.get(annotation.originStepId);
+  const stepAttemptId = step?.attemptIds.get(annotation.originStepAttempt);
+
+  return {
+    annotation,
+    jobName: job?.name ?? null,
+    executionLabel:
+      execution && job && job.executionCount > 1 ? `execution #${execution.sequence}` : null,
+    stepLabel: step?.label ?? null,
+    attemptLabel: `attempt ${annotation.originStepAttempt}`,
+    origin: stepAttemptId
+      ? {
+          jobId: annotation.jobId,
+          jobExecutionId: annotation.jobExecutionId,
+          stepId: annotation.originStepId,
+          stepAttemptId,
+        }
+      : null,
+  };
+}
+
+function compareEntries(
+  left: RunAnnotationEntry,
+  right: RunAnnotationEntry,
+  index: Map<string, JobIndexEntry>,
+): number {
+  const bySeverity = SEVERITY_RANK[left.annotation.style] - SEVERITY_RANK[right.annotation.style];
+  if (bySeverity !== 0) return bySeverity;
+
+  const byJob = jobPosition(left, index) - jobPosition(right, index);
+  if (byJob !== 0) return byJob;
+
+  const byExecution = executionSequence(left, index) - executionSequence(right, index);
+  if (byExecution !== 0) return byExecution;
+
+  const bySequence = left.annotation.sequence - right.annotation.sequence;
+  if (bySequence !== 0) return bySequence;
+
+  return left.annotation.id.localeCompare(right.annotation.id);
+}
+
+/** An unmatched job sorts last rather than first, so known provenance leads the list. */
+function jobPosition(entry: RunAnnotationEntry, index: Map<string, JobIndexEntry>): number {
+  return index.get(entry.annotation.jobId)?.position ?? Number.MAX_SAFE_INTEGER;
+}
+
+function executionSequence(entry: RunAnnotationEntry, index: Map<string, JobIndexEntry>): number {
+  const job = index.get(entry.annotation.jobId);
+  return job?.executions.get(entry.annotation.jobExecutionId)?.sequence ?? Number.MAX_SAFE_INTEGER;
+}

package/src/core/workflow-run.ts

@@ -46,6 +46,10 @@ export {
   STEP_ERROR_REASONS,
 } from './entities/step.js';
 export type {
+  EvaluationTraceEntry,
+  EvaluationTraceLimitEntry,
+  EvaluationTraceValueEntry,
+  StepAttemptDetail,
   StepAttemptDisplayDuration,
   StepGateResult,
 } from './entities/step-attempt.js';

package/src/hooks/api/annotations.test.ts

@@ -0,0 +1,84 @@
+import {
+  workflowRunAnnotationSummaryQueryOptions,
+  workflowRunAnnotationsQueryOptions,
+} from './annotations.js';
+
+const WORKFLOW_RUN_ID = '11111111-1111-4111-8111-111111111111';
+
+describe('annotation query polling', () => {
+  it('polls enabled list and summary queries by default', () => {
+    const summary = workflowRunAnnotationSummaryQueryOptions(WORKFLOW_RUN_ID, 1);
+    const list = workflowRunAnnotationsQueryOptions(WORKFLOW_RUN_ID, 1);
+
+    expect(summary.refetchInterval).toBe(5_000);
+    expect(refetchIntervalForPages(list, 1)).toBe(5_000);
+  });
+
+  it('polls when enabled explicitly for both query builders', () => {
+    const summary = workflowRunAnnotationSummaryQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      polling: true,
+    });
+    const list = workflowRunAnnotationsQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      polling: true,
+    });
+
+    expect(summary.refetchInterval).toBe(5_000);
+    expect(refetchIntervalForPages(list, 1)).toBe(5_000);
+  });
+
+  it('does not poll disabled query builders', () => {
+    const summary = workflowRunAnnotationSummaryQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      enabled: false,
+    });
+    const list = workflowRunAnnotationsQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      enabled: false,
+    });
+
+    expect(summary.refetchInterval).toBe(false);
+    expect(list.refetchInterval).toBe(false);
+  });
+
+  it('stops summary polling when the owning run is terminal', () => {
+    const options = workflowRunAnnotationSummaryQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      polling: false,
+    });
+
+    expect(options.refetchInterval).toBe(false);
+  });
+
+  it('stops annotation list polling when the owning run is terminal', () => {
+    const options = workflowRunAnnotationsQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      polling: false,
+    });
+
+    expect(options.refetchInterval).toBe(false);
+  });
+
+  it('stops annotation list polling after the first page has been loaded', () => {
+    const options = workflowRunAnnotationsQueryOptions(WORKFLOW_RUN_ID, 1);
+
+    expect(refetchIntervalForPages(options, 2)).toBe(false);
+  });
+
+  it('keeps execution-scoped summaries on a distinct reusable query key', () => {
+    const runSummary = workflowRunAnnotationSummaryQueryOptions(WORKFLOW_RUN_ID, 1);
+    const executionSummary = workflowRunAnnotationSummaryQueryOptions(
+      WORKFLOW_RUN_ID,
+      1,
+      '22222222-2222-4222-8222-222222222222',
+    );
+
+    expect(runSummary.queryKey).not.toEqual(executionSummary.queryKey);
+  });
+});
+
+function refetchIntervalForPages(
+  options: ReturnType<typeof workflowRunAnnotationsQueryOptions>,
+  pageCount: number,
+) {
+  if (typeof options.refetchInterval !== 'function') return options.refetchInterval;
+
+  return options.refetchInterval({
+    state: {data: {pages: Array.from({length: pageCount}, () => ({}))}},
+  } as never);
+}