feat(stovepipe): Show most broken projects first

Author: prathshenoy

doc/rfc/stovepipe/project-status-api.md

@@ -64,15 +64,15 @@ The caller may supply the project IDs for which it wants recorded results. The A
 
 When project IDs are supplied, the response includes only results for those IDs, in the supplied order, and paginates that list. An implementation may record results for every requested project, only requested projects with a non-green result, or another documented subset.
 
-With no project IDs supplied, the response lists all recorded project results in project-ID order, excluding the repository fact. Results are a live view; restart pagination to discover facts recorded behind the cursor.
+With no project IDs supplied, the response lists all recorded project results by descending breakage degree, then ascending project ID, excluding the repository fact. The continuation token identifies the last project; its immutable fact supplies the degree needed to resume this ordering. A missing cursor fact returns an error. Results are a live view; restart pagination to discover facts recorded before the cursor.
 
 Each project result is an immutable validation fact keyed by queue, commit URI, and project ID. A result must identify the selected request. `project_results_complete` is false until the implementation has durably finished producing results for the supplied project IDs; a completed empty set is valid.
 
 Callers use `project_results_complete`, rather than the presence or absence of an individual project result, to determine whether the implementation has finished producing results for the requested projects. `next_page_token` is empty only on the final page. A terminal lifecycle notification is emitted only after the repository result and any applicable project completion record are durable. If notification delivery fails, consumers can recover the same result through either endpoint.
 
 ## Implementation
 
-Both endpoints return durable lifecycle summaries, the whole-repository fact when present, and recorded facts for requested projects in paginated request order, or all recorded project results in project-ID order when none are requested. `project_results_complete` remains false until a durable completion projection is available. Missing facts are omitted; an explicitly recorded zero degree remains present. `updated_at_ms` is the maximum timestamp of the summary and the facts represented on the page.
+Both endpoints return durable lifecycle summaries, the whole-repository fact when present, and recorded facts for requested projects in paginated request order, or all recorded project results by descending breakage degree then ascending project ID when none are requested. `project_results_complete` remains false until a durable completion projection is available. Missing facts are omitted; an explicitly recorded zero degree remains present. `updated_at_ms` is the maximum timestamp of the summary and the facts represented on the page.
 
 ## Errors and Authorization
 

stovepipe/controller/project_status_test.go

@@ -300,9 +300,9 @@ func TestGetProjectStatusReturnsProjectFactsInRequestedOrder(t *testing.T) {
 	summaryStore.EXPECT().Get(gomock.Any(), projectStatusID).Return(requestSummary, nil)
 	store.EXPECT().GetValidationFactStore().Return(factStore)
 	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "").Return(entity.ValidationFact{}, storage.ErrNotFound)
-	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "project-b").Return(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Project: "project-b", Degree: entity.DegreeBroken, CreatedAt: 20}, nil)
+	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "project-b").Return(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Project: "project-b", Degree: entity.DegreeGreen, CreatedAt: 20}, nil)
 	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "missing").Return(entity.ValidationFact{}, storage.ErrNotFound)
-	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "project-a").Return(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Project: "project-a", Degree: entity.DegreeGreen, CreatedAt: 30}, nil)
+	factStore.EXPECT().Get(gomock.Any(), projectStatusURI, "project-a").Return(entity.ValidationFact{URI: projectStatusURI, RequestID: projectStatusID, Project: "project-a", Degree: entity.DegreeBroken, CreatedAt: 30}, nil)
 
 	controller := NewProjectStatusController(zap.NewNop().Sugar(), tally.NoopScope, factory)
 	got, err := controller.GetProjectStatus(context.Background(), entity.GetProjectStatusRequest{Queue: projectStatusQueue, ChangeURI: projectStatusURI, Projects: []string{"project-b", "missing", "project-a"}})
@@ -452,9 +452,9 @@ func TestParseProjectStatusPageTokenRejectsMismatches(t *testing.T) {
 func TestGetProjectStatusPaginatesStoredProjects(t *testing.T) {
 	summary := entity.RequestSummary{RequestID: projectStatusID, Queue: projectStatusQueue, URI: projectStatusURI, StateTimestampMs: 10}
 	stored := []entity.ValidationFact{
+		{URI: projectStatusURI, RequestID: projectStatusID, Project: "c", Degree: 1, CreatedAt: 60},
 		{URI: projectStatusURI, RequestID: projectStatusID, Project: "a", Degree: 0.5, CreatedAt: 20},
 		{URI: projectStatusURI, RequestID: projectStatusID, Project: "b", Degree: 0, CreatedAt: 50},
-		{URI: projectStatusURI, RequestID: projectStatusID, Project: "c", Degree: 1, CreatedAt: 60},
 	}
 
 	ctrl := gomock.NewController(t)
@@ -469,15 +469,15 @@ func TestGetProjectStatusPaginatesStoredProjects(t *testing.T) {
 	store.EXPECT().GetValidationFactStore().Return(facts).Times(2)
 	facts.EXPECT().Get(gomock.Any(), projectStatusURI, "").Return(entity.ValidationFact{}, storage.ErrNotFound).Times(2)
 	facts.EXPECT().ListProjects(gomock.Any(), projectStatusURI, "", 3).Return(stored, nil)
-	facts.EXPECT().ListProjects(gomock.Any(), projectStatusURI, "b", defaultProjectStatusPageSize+1).Return(stored[2:], nil)
+	facts.EXPECT().ListProjects(gomock.Any(), projectStatusURI, "a", defaultProjectStatusPageSize+1).Return(stored[2:], nil)
 
 	controller := NewProjectStatusController(zap.NewNop().Sugar(), tally.NoopScope, factory)
 	req := entity.GetProjectStatusRequest{Queue: projectStatusQueue, RequestID: projectStatusID, PageSize: 2}
 
 	first, err := controller.GetProjectStatus(context.Background(), req)
 	require.NoError(t, err)
 	assert.Equal(t, stored[:2], first.ProjectValidationFacts)
-	assert.Equal(t, int64(50), first.UpdatedAtMs)
+	assert.Equal(t, int64(60), first.UpdatedAtMs)
 	require.NotEmpty(t, first.NextPageToken)
 
 	req.PageToken = first.NextPageToken
@@ -487,7 +487,7 @@ func TestGetProjectStatusPaginatesStoredProjects(t *testing.T) {
 	second, err := controller.GetProjectStatus(context.Background(), req)
 	require.NoError(t, err)
 	assert.Equal(t, stored[2:], second.ProjectValidationFacts)
-	assert.Equal(t, int64(60), second.UpdatedAtMs)
+	assert.Equal(t, int64(50), second.UpdatedAtMs)
 	assert.Empty(t, second.NextPageToken)
 }
 

stovepipe/entity/project_status.go

@@ -40,7 +40,7 @@ type GetProjectStatusResult struct {
 	HasRepositoryValidationFact bool
 	// ProjectResultsComplete reports whether the implementation has finished its project-result set.
 	ProjectResultsComplete bool
-	// ProjectValidationFacts contains recorded results in request order, or project-ID order when Projects is empty.
+	// ProjectValidationFacts contains recorded results in request order, or descending degree then ascending project ID when Projects is empty.
 	ProjectValidationFacts []ValidationFact
 	// NextPageToken continues requested-project result pagination when another page exists.
 	NextPageToken string

stovepipe/extension/storage/mysql/validation_fact_store.go

@@ -101,12 +101,21 @@ func (v *validationFactStore) ListProjects(ctx context.Context, uri, afterProjec
 	if limit <= 0 {
 		return nil, fmt.Errorf("validation fact list limit must be positive")
 	}
-	rows, err := v.db.QueryContext(ctx, `
+	query := `
 		SELECT uri, project, degree, request_id, created_at FROM validation_fact
-		WHERE queue = ? AND uri = ? AND project > ?
-		ORDER BY project ASC LIMIT ?`,
-		v.queue, uri, afterProject, limit,
-	)
+		WHERE queue = ? AND uri = ? AND project <> ''`
+	args := []any{v.queue, uri}
+	if afterProject != "" {
+		cursor, err := v.Get(ctx, uri, afterProject)
+		if err != nil {
+			return nil, fmt.Errorf("failed to load project cursor queue=%s uri=%s project=%s: %w", v.queue, uri, afterProject, err)
+		}
+		query += ` AND (degree < ? OR (degree = ? AND project > ?))`
+		args = append(args, cursor.Degree, cursor.Degree, afterProject)
+	}
+	query += ` ORDER BY degree DESC, project ASC LIMIT ?`
+	args = append(args, limit)
+	rows, err := v.db.QueryContext(ctx, query, args...)
 	if err != nil {
 		return nil, fmt.Errorf("failed to list project facts queue=%s uri=%s: %w", v.queue, uri, err)
 	}

stovepipe/extension/storage/mysql/validation_fact_store_test.go

@@ -184,38 +184,71 @@ func TestValidationFactStore_ListProjects(t *testing.T) {
 	readErr := fmt.Errorf("connection reset")
 	columns := []string{"uri", "project", "degree", "request_id", "created_at"}
 	want := entity.ValidationFact{URI: testFactURI, Project: "project-b", Degree: 0.5, RequestID: "2", CreatedAt: 20}
-	tests := []struct {
-		name     string
-		rows     *sqlmock.Rows
-		queryErr error
-		wantErr  bool
-		want     []entity.ValidationFact
-	}{
-		{name: "found", rows: sqlmock.NewRows(columns).AddRow(want.URI, want.Project, want.Degree, want.RequestID, want.CreatedAt), want: []entity.ValidationFact{want}},
-		{name: "empty", rows: sqlmock.NewRows(columns)},
-		{name: "query failure", queryErr: readErr, wantErr: true},
-		{name: "scan failure", rows: sqlmock.NewRows(columns).AddRow(want.URI, want.Project, "invalid", want.RequestID, want.CreatedAt), wantErr: true},
-		{name: "iteration failure", rows: sqlmock.NewRows(columns).AddRow(want.URI, want.Project, want.Degree, want.RequestID, want.CreatedAt).RowError(0, readErr), wantErr: true},
+	for _, afterProject := range []string{"", "project-z"} {
+		tests := []struct {
+			name     string
+			rows     *sqlmock.Rows
+			queryErr error
+			wantErr  bool
+			want     []entity.ValidationFact
+		}{
+			{name: "found", rows: sqlmock.NewRows(columns).AddRow(want.URI, want.Project, want.Degree, want.RequestID, want.CreatedAt), want: []entity.ValidationFact{want}},
+			{name: "empty", rows: sqlmock.NewRows(columns)},
+			{name: "query failure", queryErr: readErr, wantErr: true},
+			{name: "scan failure", rows: sqlmock.NewRows(columns).AddRow(want.URI, want.Project, "invalid", want.RequestID, want.CreatedAt), wantErr: true},
+			{name: "iteration failure", rows: sqlmock.NewRows(columns).AddRow(want.URI, want.Project, want.Degree, want.RequestID, want.CreatedAt).RowError(0, readErr), wantErr: true},
+		}
+		for _, tt := range tests {
+			t.Run(tt.name+"/"+afterProject, func(t *testing.T) {
+				db, mock, store := setupValidationFactStoreTest(t)
+				defer db.Close()
+				queryPattern := `SELECT uri, project, degree, request_id, created_at FROM validation_fact\s+WHERE queue = \? AND uri = \? AND project <> ''`
+				if afterProject != "" {
+					mock.ExpectQuery("SELECT uri, project, degree, request_id, created_at FROM validation_fact").
+						WithArgs(testFactQueue, testFactURI, afterProject).
+						WillReturnRows(sqlmock.NewRows(columns).AddRow(testFactURI, afterProject, 1.0, "2", 10))
+					queryPattern += ` AND \(degree < \? OR \(degree = \? AND project > \?\)\)`
+				}
+				query := mock.ExpectQuery(queryPattern + ` ORDER BY degree DESC, project ASC LIMIT \?`)
+				if afterProject == "" {
+					query.WithArgs(testFactQueue, testFactURI, 3)
+				} else {
+					query.WithArgs(testFactQueue, testFactURI, 1.0, 1.0, afterProject, 3)
+				}
+				if tt.queryErr != nil {
+					query.WillReturnError(tt.queryErr)
+				} else {
+					query.WillReturnRows(tt.rows)
+				}
+				got, err := store.ListProjects(context.Background(), testFactURI, afterProject, 3)
+				if tt.wantErr {
+					require.Error(t, err)
+					if tt.queryErr != nil {
+						assert.ErrorIs(t, err, tt.queryErr)
+					}
+				} else {
+					require.NoError(t, err)
+					assert.Equal(t, tt.want, got)
+				}
+				require.NoError(t, mock.ExpectationsWereMet())
+			})
+		}
 	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+}
+
+func TestValidationFactStore_ListProjectsCursorFailure(t *testing.T) {
+	for _, lookupErr := range []error{sql.ErrNoRows, fmt.Errorf("connection reset")} {
+		t.Run(lookupErr.Error(), func(t *testing.T) {
 			db, mock, store := setupValidationFactStoreTest(t)
 			defer db.Close()
-			query := mock.ExpectQuery(`SELECT uri, project, degree, request_id, created_at FROM validation_fact\s+WHERE queue = \? AND uri = \? AND project > \?\s+ORDER BY project ASC LIMIT \?`).WithArgs(testFactQueue, testFactURI, "project-a", 3)
-			if tt.queryErr != nil {
-				query.WillReturnError(tt.queryErr)
-			} else {
-				query.WillReturnRows(tt.rows)
-			}
-			got, err := store.ListProjects(context.Background(), testFactURI, "project-a", 3)
-			if tt.wantErr {
-				require.Error(t, err)
-				if tt.queryErr != nil {
-					assert.ErrorIs(t, err, tt.queryErr)
-				}
-			} else {
-				require.NoError(t, err)
-				assert.Equal(t, tt.want, got)
+			mock.ExpectQuery("SELECT uri, project, degree, request_id, created_at FROM validation_fact").
+				WithArgs(testFactQueue, testFactURI, "cursor").
+				WillReturnError(lookupErr)
+
+			_, err := store.ListProjects(context.Background(), testFactURI, "cursor", 3)
+			require.ErrorIs(t, err, lookupErr)
+			if lookupErr == sql.ErrNoRows {
+				assert.ErrorIs(t, err, storage.ErrNotFound)
 			}
 			require.NoError(t, mock.ExpectationsWereMet())
 		})

stovepipe/extension/storage/validation_fact_store.go

@@ -36,8 +36,10 @@ type ValidationFactStore interface {
 	// fact exists, which means the scope was never validated rather than validated green.
 	Get(ctx context.Context, uri, project string) (entity.ValidationFact, error)
 
-	// ListProjects returns at most limit project facts for uri in ascending project-ID
-	// order, excluding the repository fact. afterProject is an exclusive cursor (empty
-	// for the first page); limit must be positive. No matches returns an empty slice.
+	// ListProjects returns at most limit project facts for uri by descending degree,
+	// then ascending project ID, excluding the repository fact. afterProject identifies
+	// the exclusive cursor fact (empty for the first page); its immutable degree is
+	// resolved internally. A missing cursor returns ErrNotFound. limit must be positive;
+	// no matches returns an empty slice.
 	ListProjects(ctx context.Context, uri, afterProject string, limit int) ([]entity.ValidationFact, error)
 }

test/integration/stovepipe/extension/storage/suite.go

@@ -688,29 +688,39 @@ func (s *ValidationFactStoreContractSuite) TestValidationFactStore_ListProjects(
 	store := s.storeFor(queue)
 	failedA := entity.ValidationFact{URI: uri, Project: "a", Degree: 0.25, RequestID: "1", CreatedAt: 10}
 	failedC := entity.ValidationFact{URI: uri, Project: "c", Degree: 1, RequestID: "1", CreatedAt: 20}
+	failedD := entity.ValidationFact{URI: uri, Project: "d", Degree: 1, RequestID: "1", CreatedAt: 25}
 	greenB := entity.ValidationFact{URI: uri, Project: "b", Degree: 0, RequestID: "1", CreatedAt: 30}
 	for _, fact := range []entity.ValidationFact{
-		failedC, failedA,
+		failedD, failedC, failedA,
 		greenB,
 		{URI: uri, Degree: 1, RequestID: "1", CreatedAt: 40},
 		{URI: uri + "-other", Project: "other-uri", Degree: 1, RequestID: "2", CreatedAt: 50},
 	} {
 		require.NoError(t, store.Create(s.ctx, fact))
 	}
 	require.NoError(t, s.storeFor(queue+"-other").Create(s.ctx, entity.ValidationFact{URI: uri, Project: "other-queue", Degree: 1, RequestID: "1", CreatedAt: 60}))
-	first, err := store.ListProjects(s.ctx, uri, "", 1)
-	require.NoError(t, err)
-	assert.Equal(t, []entity.ValidationFact{failedA}, first)
+	want := []entity.ValidationFact{failedC, failedD, failedA, greenB}
+	afterProject := ""
+	for _, fact := range want {
+		page, err := store.ListProjects(s.ctx, uri, afterProject, 1)
+		require.NoError(t, err)
+		require.Equal(t, []entity.ValidationFact{fact}, page)
+		afterProject = page[0].Project
+	}
 	second, err := store.ListProjects(s.ctx, uri, "a", 10)
 	require.NoError(t, err)
-	assert.Equal(t, []entity.ValidationFact{greenB, failedC}, second)
+	assert.Equal(t, []entity.ValidationFact{greenB}, second)
 	all, err := store.ListProjects(s.ctx, uri, "", 10)
 	require.NoError(t, err)
-	assert.Equal(t, []entity.ValidationFact{failedA, greenB, failedC}, all)
-	empty, err := store.ListProjects(s.ctx, uri, "c", 10)
+	assert.Equal(t, want, all)
+	empty, err := store.ListProjects(s.ctx, uri, "b", 10)
 	require.NoError(t, err)
 	assert.Empty(t, empty)
 	missing, err := store.ListProjects(s.ctx, "missing", "", 10)
 	require.NoError(t, err)
 	assert.Empty(t, missing)
+	for _, cursor := range []string{"missing", "other-uri", "other-queue"} {
+		_, err := store.ListProjects(s.ctx, uri, cursor, 10)
+		assert.ErrorIs(t, err, storage.ErrNotFound)
+	}
 }

test/integration/stovepipe/suite_test.go

@@ -352,20 +352,20 @@ func (s *StovepipeIntegrationSuite) TestProjectStatusAPI() {
 	})
 	require.NoError(t, err)
 	require.Len(t, firstPage.Projects, 1)
-	assert.Equal(t, "project-a", firstPage.Projects[0].GetProject())
-	assert.Equal(t, 0.5, firstPage.Projects[0].GetBreakageDegree())
-	assert.Equal(t, int64(3000), firstPage.GetUpdatedAtMs())
+	assert.Equal(t, "project-b", firstPage.Projects[0].GetProject())
+	assert.Equal(t, 1.0, firstPage.Projects[0].GetBreakageDegree())
+	assert.Equal(t, int64(5000), firstPage.GetUpdatedAtMs())
 	require.NotEmpty(t, firstPage.NextPageToken)
 	remaining, err := s.client.GetProjectStatusByID(s.ctx, &pb.GetProjectStatusByIDRequest{
 		Queue: queue, RequestId: id, PageToken: firstPage.NextPageToken,
 	})
 	require.NoError(t, err)
 	require.Len(t, remaining.Projects, 2)
-	assert.Equal(t, "project-b", remaining.Projects[0].GetProject())
-	assert.Equal(t, 1.0, remaining.Projects[0].GetBreakageDegree())
+	assert.Equal(t, "project-a", remaining.Projects[0].GetProject())
+	assert.Equal(t, 0.5, remaining.Projects[0].GetBreakageDegree())
 	assert.Equal(t, "project-green", remaining.Projects[1].GetProject())
 	assert.Zero(t, remaining.Projects[1].GetBreakageDegree())
-	assert.Equal(t, int64(5000), remaining.GetUpdatedAtMs())
+	assert.Equal(t, int64(4000), remaining.GetUpdatedAtMs())
 	assert.Empty(t, remaining.NextPageToken)
 	assert.False(t, remaining.ProjectResultsComplete)