@shipfox/client-workflows 15.0.0 → 16.0.0

package/src/components/workflow-run-view/workflow-run-view.tsx

@@ -10,11 +10,13 @@ import {
   SelectValue,
 } from '@shipfox/react-ui/select';
 import {toast} from '@shipfox/react-ui/toast';
+import {Text} from '@shipfox/react-ui/typography';
 import {useNavigate} from '@tanstack/react-router';
-import {type ReactNode, useEffect} from 'react';
-import type {Job, WorkflowRunRerunMode} from '#core/workflow-run.js';
-import type {RunAnnotationSummary} from '#core/workflow-run-tabs.js';
+import {type ReactNode, useEffect, useMemo} from 'react';
+import {buildRunAnnotationList, type RunAnnotationSummary} from '#core/run-annotation.js';
+import {isWorkflowRunTerminal, type Job, type WorkflowRunRerunMode} from '#core/workflow-run.js';
 import {withoutWorkflowRunSelectionSearch} from '#core/workflow-run-url-state.js';
+import {useRunAnnotationsQuery} from '#hooks/api/run-annotations.js';
 import {
   useCancelWorkflowRunMutation,
   useRerunWorkflowRunMutation,
@@ -30,7 +32,7 @@ import {
 import {JobGraph} from '../job-graph/index.js';
 import type {JobGraphSelectionSource} from '../job-graph/types.js';
 import {WorkflowRunSummary} from '../workflow-run-summary/index.js';
-import {RunAnnotationSummaryLine, RunAnnotationsEmpty} from '../workflow-run-tabs/index.js';
+import {RunAnnotationList, RunAnnotationSummaryLine} from '../workflow-run-tabs/index.js';
 import {WorkflowSourceContent} from '../workflow-source-panel/index.js';
 import {RunWorkspaceNav} from './run-workspace-nav.js';
 import {resolveWorkflowRunSelection} from './workflow-run-selection.js';
@@ -51,7 +53,6 @@ export interface WorkflowRunViewProps {
   runAttempt?: number | undefined;
   selection?: WorkflowRunsSearch | undefined;
   tab?: WorkflowRunTab | undefined;
-  annotationSummary?: RunAnnotationSummary | undefined;
   activeJobId?: string | undefined;
   jobSearch?: WorkflowJobSearch | undefined;
   jobContent?: ReactNode | undefined;
@@ -69,7 +70,6 @@ export function WorkflowRunView({
   runAttempt,
   selection,
   tab,
-  annotationSummary,
   activeJobId,
   jobSearch,
   jobContent,
@@ -79,6 +79,22 @@ export function WorkflowRunView({
     runAttempt: selection?.runAttempt ?? runAttempt,
   });
   const rerunMutation = useRerunWorkflowRunMutation(projectId);
+  // Annotations are read on their own cadence rather than hydrated into the run, so the two
+  // modules stay decoupled. The key is shared, so the job page's count chip costs no extra fetch.
+  //
+  // Polling is scoped to the surface that renders bodies. The read has no counts-only mode, so
+  // every poll transfers whole Markdown bodies; doing that every four seconds behind Summary,
+  // Source, and the job log spends megabytes to keep one rail number warm. Off that surface the
+  // counts still refresh on navigation and on window focus.
+  const annotationsQuery = useRunAnnotationsQuery({
+    workflowRunId,
+    runAttempt: runQuery.data?.runAttempt.attempt,
+    live:
+      runWorkspaceSection(tab) === 'annotations' &&
+      !activeJobId &&
+      Boolean(runQuery.data) &&
+      !isWorkflowRunTerminal(runQuery.data?.runAttempt.status ?? 'pending'),
+  });
 
   return (
     <RelativeTimeProvider>
@@ -87,11 +103,11 @@ export function WorkflowRunView({
           workspaceSlug={workspaceSlug}
           projectSlug={projectSlug}
           query={runQuery}
+          annotations={annotationsQuery}
           rerunMutation={rerunMutation}
           runAttempt={runAttempt}
           selection={selection}
           tab={tab}
-          annotationSummary={annotationSummary}
           activeJobId={activeJobId}
           jobSearch={jobSearch}
           jobContent={jobContent}
@@ -105,11 +121,11 @@ function RunViewContent({
   workspaceSlug,
   projectSlug,
   query,
+  annotations,
   rerunMutation,
   runAttempt,
   selection,
   tab,
-  annotationSummary,
   activeJobId,
   jobSearch,
   jobContent,
@@ -117,17 +133,18 @@ function RunViewContent({
   workspaceSlug: string | undefined;
   projectSlug: string | undefined;
   query: ReturnType<typeof useWorkflowRunAttemptQuery>;
+  annotations: ReturnType<typeof useRunAnnotationsQuery>;
   rerunMutation: ReturnType<typeof useRerunWorkflowRunMutation>;
   runAttempt: number | undefined;
   selection: WorkflowRunsSearch | undefined;
   tab: WorkflowRunTab | undefined;
-  annotationSummary: RunAnnotationSummary | undefined;
   activeJobId: string | undefined;
   jobSearch: WorkflowJobSearch | undefined;
   jobContent: ReactNode | undefined;
 }) {
   const navigate = useNavigate();
   const runData = query.data;
+  const annotationSummary = annotations.summary;
   const activeSection = runWorkspaceSection(tab);
   const cancelMutation = useCancelWorkflowRunMutation(runData);
   const sourceSnapshot = runData?.sourceSnapshot ?? null;
@@ -228,6 +245,24 @@ function RunViewContent({
     });
   }
 
+  function clearAnnotationFilters() {
+    if (!runData || !workspaceSlug || !projectSlug) return;
+    const nextSearch: WorkflowRunsSearch = {...selection, tab: 'annotations'};
+    delete nextSearch.jobId;
+    delete nextSearch.jobExecutionId;
+    delete nextSearch.stepId;
+    delete nextSearch.stepAttemptId;
+    delete nextSearch.severity;
+    delete nextSearch.annotation;
+
+    void navigate({
+      to: '/w/$workspaceSlug/p/$projectSlug/runs/$workflowRunId',
+      params: {workspaceSlug, projectSlug, workflowRunId: runData.id},
+      search: workflowRunSearchParams(nextSearch, nextSearch) as never,
+      replace: true,
+    });
+  }
+
   function cancelRun() {
     cancelMutation.mutate(undefined, {
       onError: (error) => toast.error(cancelErrorMessage(error)),
@@ -291,6 +326,7 @@ function RunViewContent({
             <RunSectionContent
               section={activeSection}
               run={runData}
+              annotations={annotations}
               annotationSummary={annotationSummary}
               workspaceSlug={workspaceSlug}
               projectSlug={projectSlug}
@@ -298,6 +334,7 @@ function RunViewContent({
               selectedJobId={selection?.jobId}
               onSelectGraphJob={selectGraphJob}
               onSelectAnnotationJob={selectAnnotationJob}
+              onClearAnnotationFilters={clearAnnotationFilters}
               sourceSnapshot={sourceSnapshot}
               highlightedLineRange={highlightedLineRange}
             />
@@ -313,6 +350,7 @@ function RunViewContent({
 function RunSectionContent({
   section,
   run,
+  annotations,
   annotationSummary,
   workspaceSlug,
   projectSlug,
@@ -320,11 +358,13 @@ function RunSectionContent({
   selectedJobId,
   onSelectGraphJob,
   onSelectAnnotationJob,
+  onClearAnnotationFilters,
   sourceSnapshot,
   highlightedLineRange,
 }: {
   section: RunWorkspaceSection;
   run: NonNullable<ReturnType<typeof useWorkflowRunAttemptQuery>['data']>;
+  annotations: ReturnType<typeof useRunAnnotationsQuery>;
   annotationSummary: RunAnnotationSummary | undefined;
   workspaceSlug: string | undefined;
   projectSlug: string | undefined;
@@ -332,6 +372,7 @@ function RunSectionContent({
   selectedJobId: string | undefined;
   onSelectGraphJob: (jobId: string | undefined, source?: JobGraphSelectionSource) => void;
   onSelectAnnotationJob: (jobId: string | undefined) => void;
+  onClearAnnotationFilters: () => void;
   sourceSnapshot: NonNullable<
     ReturnType<typeof useWorkflowRunAttemptQuery>['data']
   >['sourceSnapshot'];
@@ -343,6 +384,9 @@ function RunSectionContent({
     return (
       <section aria-label="All jobs summary" className="min-h-0 flex-1 overflow-auto pb-24 pt-16">
         <div className="mx-auto flex w-full max-w-[1120px] flex-col gap-16 px-24">
+          <Text as="h2" className="sr-only">
+            All jobs summary
+          </Text>
           <JobGraph
             run={run}
             selectedJobId={selectedJobId}
@@ -355,33 +399,27 @@ function RunSectionContent({
   }
 
   if (section === 'annotations') {
-    const selectedJob = run.jobs.find((job) => job.id === selectedJobId);
     return (
-      <section aria-label="Run annotations" className="min-h-0 flex-1 overflow-auto pb-24 pt-16">
-        <div className="mx-auto flex w-full max-w-[1120px] flex-col gap-16 px-24">
-          <div className="flex flex-wrap items-center justify-between gap-8">
-            <RunAnnotationSummaryLine
-              summary={annotationSummary}
-              workspaceSlug={workspaceSlug}
-              projectSlug={projectSlug}
-              workflowRunId={run.id}
-              search={selection}
-            />
-            <AnnotationJobFilter
-              jobs={run.jobs}
-              selectedJobId={selectedJob?.id}
-              onSelect={onSelectAnnotationJob}
-            />
-          </div>
-          <RunAnnotationsEmpty jobName={selectedJob?.displayName} />
-        </div>
-      </section>
+      <RunAnnotationsSection
+        run={run}
+        annotations={annotations}
+        annotationSummary={annotationSummary}
+        workspaceSlug={workspaceSlug}
+        projectSlug={projectSlug}
+        selection={selection}
+        selectedJobId={selectedJobId}
+        onSelectAnnotationJob={onSelectAnnotationJob}
+        onClearAnnotationFilters={onClearAnnotationFilters}
+      />
     );
   }
 
   return (
     <section aria-label="Workflow source" className="min-h-0 flex-1 overflow-auto pb-24 pt-16">
-      <div className="mx-auto flex min-h-full w-full max-w-[1120px] px-24">
+      <div className="mx-auto flex min-h-full w-full max-w-[1120px] flex-col px-24">
+        <Text as="h2" className="sr-only">
+          Workflow source
+        </Text>
         {sourceSnapshot ? (
           <WorkflowSourceContent
             source={sourceSnapshot}
@@ -405,6 +443,86 @@ function RunSectionContent({
   );
 }
 
+function RunAnnotationsSection({
+  run,
+  annotations,
+  annotationSummary,
+  workspaceSlug,
+  projectSlug,
+  selection,
+  selectedJobId,
+  onSelectAnnotationJob,
+  onClearAnnotationFilters,
+}: {
+  run: NonNullable<ReturnType<typeof useWorkflowRunAttemptQuery>['data']>;
+  annotations: ReturnType<typeof useRunAnnotationsQuery>;
+  annotationSummary: RunAnnotationSummary | undefined;
+  workspaceSlug: string | undefined;
+  projectSlug: string | undefined;
+  selection: WorkflowRunsSearch | undefined;
+  selectedJobId: string | undefined;
+  onSelectAnnotationJob: (jobId: string | undefined) => void;
+  onClearAnnotationFilters: () => void;
+}) {
+  const selectedJob = run.jobs.find((job) => job.id === selectedJobId);
+  const severity = selection?.severity;
+  const records = annotations.annotations;
+
+  const entries = useMemo(
+    () =>
+      records
+        ? buildRunAnnotationList({
+            annotations: records,
+            jobs: run.jobs,
+            severity,
+            jobId: selectedJob?.id,
+          })
+        : undefined,
+    [records, run.jobs, selectedJob?.id, severity],
+  );
+
+  return (
+    <section aria-label="Run annotations" className="min-h-0 flex-1 overflow-auto pb-24 pt-16">
+      <div className="mx-auto flex w-full max-w-[1120px] flex-col gap-16 px-24">
+        <Text as="h2" className="sr-only">
+          Annotations
+        </Text>
+        <div className="flex flex-wrap items-center justify-between gap-8">
+          <RunAnnotationSummaryLine
+            summary={annotationSummary}
+            workspaceSlug={workspaceSlug}
+            projectSlug={projectSlug}
+            workflowRunId={run.id}
+            search={selection}
+          />
+          <AnnotationJobFilter
+            jobs={run.jobs}
+            selectedJobId={selectedJob?.id}
+            onSelect={onSelectAnnotationJob}
+          />
+        </div>
+        <RunAnnotationList
+          // Remounting on a filter or run-attempt change resets the render window, so the next
+          // list never inherits a "show more" position from different data.
+          key={`${run.id}:${run.runAttempt.attempt}:${severity ?? 'all'}:${selectedJob?.id ?? 'all'}`}
+          query={annotations.query}
+          entries={entries}
+          workspaceSlug={workspaceSlug}
+          projectSlug={projectSlug}
+          workflowRunId={run.id}
+          runAttempt={run.runAttempt.attempt}
+          // A run with no annotations at all offers no filter to clear, whatever the URL says.
+          filtered={Boolean((severity || selectedJob) && (annotationSummary?.total ?? 0) > 0)}
+          filteredJobName={selectedJob?.displayName}
+          filteredSeverity={severity}
+          onClearFilters={onClearAnnotationFilters}
+          selectedAnnotationId={selection?.annotation}
+        />
+      </div>
+    </section>
+  );
+}
+
 const ALL_ANNOTATION_JOBS = 'all-jobs';
 
 function AnnotationJobFilter({

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: [],
+            }),
+          ],
+        }),
+      ],
+    }),
+  ];
+}