@shipfox/client-workflows 15.0.0 → 16.0.0

package/src/core/run-annotation.ts

@@ -0,0 +1,238 @@
+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;
+}
+
+/** 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/hooks/api/run-annotation-mapper.ts

@@ -0,0 +1,30 @@
+import type {AnnotationDto, ReadAnnotationsResponseDto} from '@shipfox/annotations-dto';
+import type {RunAnnotationRecord} from '#core/run-annotation.js';
+
+export interface RunAnnotationPage {
+  annotations: RunAnnotationRecord[];
+  hasMore: boolean;
+  nextCursor: string | null;
+}
+
+export function toRunAnnotation(dto: AnnotationDto): RunAnnotationRecord {
+  return {
+    id: dto.id,
+    jobId: dto.job_id,
+    jobExecutionId: dto.job_execution_id,
+    originStepId: dto.origin_step_id,
+    originStepAttempt: dto.origin_step_attempt,
+    context: dto.context,
+    style: dto.style,
+    sequence: dto.sequence,
+    body: dto.body,
+  };
+}
+
+export function toRunAnnotationPage(response: ReadAnnotationsResponseDto): RunAnnotationPage {
+  return {
+    annotations: response.annotations.map(toRunAnnotation),
+    hasMore: response.has_more,
+    nextCursor: response.next_cursor,
+  };
+}

package/src/hooks/api/run-annotations.ts

@@ -0,0 +1,137 @@
+import {READ_ANNOTATIONS_MAX_LIMIT, readAnnotationsResponseSchema} from '@shipfox/annotations-dto';
+import {checkedApiRequest} from '@shipfox/client-api';
+import {
+  type InfiniteData,
+  infiniteQueryOptions,
+  type UseInfiniteQueryOptions,
+  useInfiniteQuery,
+} from '@tanstack/react-query';
+import {useMemo} from 'react';
+import {
+  type RunAnnotationRecord,
+  type RunAnnotationSummary,
+  summarizeRunAnnotations,
+} from '#core/run-annotation.js';
+import {type RunAnnotationPage, toRunAnnotationPage} from './run-annotation-mapper.js';
+
+/** Matches the run detail poll, so annotations and run state never disagree by more than a tick. */
+const ACTIVE_POLL_MS = 4_000;
+
+export const runAnnotationsQueryKeys = {
+  all: ['run-annotations'] as const,
+  list: (workflowRunId: string, runAttempt?: number | undefined) =>
+    [...runAnnotationsQueryKeys.all, 'list', workflowRunId, runAttempt ?? null] as const,
+};
+
+type RunAnnotationsQueryKey =
+  | ReturnType<typeof runAnnotationsQueryKeys.list>
+  | readonly ['run-annotations', 'list'];
+
+type RunAnnotationsQueryOptions = UseInfiniteQueryOptions<
+  RunAnnotationPage,
+  Error,
+  InfiniteData<RunAnnotationPage, string | undefined>,
+  RunAnnotationsQueryKey,
+  string | undefined
+>;
+
+async function listRunAnnotations({
+  workflowRunId,
+  runAttempt,
+  cursor,
+  signal,
+}: {
+  workflowRunId: string;
+  runAttempt: number;
+  cursor?: string | undefined;
+  signal?: AbortSignal;
+}): Promise<RunAnnotationPage> {
+  const params = new URLSearchParams({
+    workflow_run_id: workflowRunId,
+    attempt: String(runAttempt),
+    limit: String(READ_ANNOTATIONS_MAX_LIMIT),
+  });
+  if (cursor) params.set('cursor', cursor);
+
+  return toRunAnnotationPage(
+    await checkedApiRequest(readAnnotationsResponseSchema, `/annotations?${params.toString()}`, {
+      signal,
+    }),
+  );
+}
+
+export interface RunAnnotationsQueryInput {
+  workflowRunId: string | undefined;
+  runAttempt: number | undefined;
+  /** Poll while the run attempt is non-terminal, then settle. */
+  live?: boolean | undefined;
+}
+
+export function runAnnotationsQueryOptions({
+  workflowRunId,
+  runAttempt,
+  live = false,
+}: RunAnnotationsQueryInput): RunAnnotationsQueryOptions {
+  const enabled = Boolean(workflowRunId) && runAttempt !== undefined;
+
+  // Polling stops once the reader has paged past the first page: the cursor bounding page 2 was
+  // computed from page 1's last row, so a refetch that shifts that boundary can drop a range of
+  // annotations into a between-pages gap.
+  return infiniteQueryOptions({
+    queryKey: workflowRunId
+      ? runAnnotationsQueryKeys.list(workflowRunId, runAttempt)
+      : ([...runAnnotationsQueryKeys.all, 'list'] as const),
+    enabled,
+    initialPageParam: undefined as string | undefined,
+    queryFn: ({pageParam, signal}) =>
+      listRunAnnotations({
+        workflowRunId: workflowRunId ?? '',
+        runAttempt: runAttempt ?? 1,
+        cursor: pageParam,
+        signal,
+      }),
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+    staleTime: 2_000,
+    refetchOnWindowFocus: true,
+    refetchInterval: (query) => {
+      if (!live) return false;
+      const pages = query.state.data?.pages;
+      return pages && pages.length > 1 ? false : ACTIVE_POLL_MS;
+    },
+    refetchIntervalInBackground: false,
+  });
+}
+
+export interface RunAnnotationsQueryResult {
+  query: ReturnType<
+    typeof useInfiniteQuery<
+      RunAnnotationPage,
+      Error,
+      InfiniteData<RunAnnotationPage, string | undefined>,
+      RunAnnotationsQueryKey,
+      string | undefined
+    >
+  >;
+  /** `undefined` until the first page resolves, so counts never render a speculative zero. */
+  annotations: RunAnnotationRecord[] | undefined;
+  summary: RunAnnotationSummary | undefined;
+}
+
+export function useRunAnnotationsQuery(input: RunAnnotationsQueryInput): RunAnnotationsQueryResult {
+  const query = useInfiniteQuery(runAnnotationsQueryOptions(input));
+  const pages = query.data?.pages;
+
+  const annotations = useMemo(
+    () => (pages ? pages.flatMap((page) => page.annotations) : undefined),
+    [pages],
+  );
+  const summary = useMemo(
+    () =>
+      annotations
+        ? summarizeRunAnnotations(annotations, {truncated: pages?.at(-1)?.hasMore ?? false})
+        : undefined,
+    [annotations, pages],
+  );
+
+  return {query, annotations, summary};
+}

package/src/pages/workflow-job-detail-page.test.tsx

@@ -33,8 +33,59 @@ const BACK_TO_SUMMARY_PATTERN = /Back to run summary/;
 const RUN_MOVED_ON_PATTERN = /Run moved on to/;
 const LINT_LINK_PATTERN = /lint/;
 const RELEASE_LINK_PATTERN = /release/;
+const ANNOTATION_LINK_PATTERN = /annotation/;
 
 describe('WorkflowJobDetailPage', () => {
+  beforeEach(() => {
+    jobAnnotations.value = [];
+  });
+
+  test('links the job to its annotations without rendering one', async () => {
+    jobAnnotations.value = [
+      {
+        id: 'aaaaaaaa-1111-4aaa-8aaa-000000000001',
+        job_id: JOB_ID,
+        job_execution_id: EXECUTION_ID,
+        origin_step_id: STEP_ID,
+        origin_step_attempt: 2,
+        context: 'smoke check',
+        style: 'error',
+        sequence: 1,
+        body: 'Task nine failed.',
+      },
+      {
+        id: 'aaaaaaaa-1111-4aaa-8aaa-000000000002',
+        job_id: SIBLING_JOB_ID,
+        job_execution_id: EXECUTION_ID,
+        origin_step_id: STEP_ID,
+        origin_step_attempt: 1,
+        context: 'other job',
+        style: 'info',
+        sequence: 2,
+        body: 'Not this job.',
+      },
+    ];
+    configureApiClient({fetchImpl: vi.fn(jobDetailFetch)});
+
+    renderJobPath(`?jobExecution=${EXECUTION_ID}&runAttempt=1`);
+
+    const chip = await screen.findByRole('link', {
+      name: 'View 1 annotation, highest severity error',
+    });
+    expect(chip.getAttribute('href')).toContain(`tab=annotations`);
+    expect(chip.getAttribute('href')).toContain(`job=${JOB_ID}`);
+    expect(screen.queryByText('Task nine failed.')).not.toBeInTheDocument();
+  });
+
+  test('omits the annotation chip when the job produced none', async () => {
+    configureApiClient({fetchImpl: vi.fn(jobDetailFetch)});
+
+    renderJobPath(`?jobExecution=${EXECUTION_ID}&runAttempt=1`);
+
+    await screen.findByRole('heading', {name: 'release'});
+    expect(screen.queryByRole('link', {name: ANNOTATION_LINK_PATTERN})).not.toBeInTheDocument();
+  });
+
   test('resolves an exact job execution and step attempt from a deep link', async () => {
     configureApiClient({fetchImpl: vi.fn(jobDetailFetch)});
 
@@ -247,10 +298,21 @@ function renderJobPath(path = '', jobId = JOB_ID) {
   );
 }
 
+/** Annotations for the job page, which renders their count and never their bodies. */
+const jobAnnotations: {value: unknown[]} = {value: []};
+
+function annotationsResponse() {
+  return {annotations: jobAnnotations.value, has_more: false, next_cursor: null};
+}
+
 function jobDetailFetch(input: RequestInfo | URL) {
   const request = input as Request;
   const url = new URL(request.url);
 
+  if (url.pathname.endsWith('/annotations')) {
+    return Promise.resolve(jsonResponse(annotationsResponse()));
+  }
+
   if (url.pathname.endsWith('/attempts')) {
     return Promise.resolve(
       jsonResponse(
@@ -287,6 +349,10 @@ function newerAttemptJobDetailFetch(input: RequestInfo | URL) {
   const request = input as Request;
   const url = new URL(request.url);
 
+  if (url.pathname.endsWith('/annotations')) {
+    return Promise.resolve(jsonResponse(annotationsResponse()));
+  }
+
   if (url.pathname.endsWith('/attempts')) {
     return Promise.resolve(
       jsonResponse(

package/src/routes/inputs.ts

@@ -1,3 +1,4 @@
+import {RUN_ANNOTATION_SEVERITIES, type RunAnnotationSeverity} from '#core/run-annotation.js';
 import type {WorkflowRunSelectionInput} from '#core/workflow-run-url-state.js';
 
 /**
@@ -12,9 +13,13 @@ export const WORKFLOW_RUN_TABS = ['summary', 'jobs', 'annotations', 'source'] as
 
 export type WorkflowRunTab = (typeof WORKFLOW_RUN_TABS)[number];
 
-export const WORKFLOW_RUN_ANNOTATION_SEVERITIES = ['error', 'warning', 'info', 'success'] as const;
+/**
+ * The `severity` parameter's vocabulary is the display severity set, not a second list: a URL
+ * that could name a severity the list cannot rank would be a filter with no matching rows.
+ */
+export const WORKFLOW_RUN_ANNOTATION_SEVERITIES = RUN_ANNOTATION_SEVERITIES;
 
-export type WorkflowRunAnnotationSeverity = (typeof WORKFLOW_RUN_ANNOTATION_SEVERITIES)[number];
+export type WorkflowRunAnnotationSeverity = RunAnnotationSeverity;
 
 export interface WorkflowRunsSearch extends WorkflowRunSelectionInput {
   search?: string;