RHIDP-16658: Consume backend-provided color for scalar aggregation KPI cards

workspaces/scorecard/.changeset/hungry-walls-burn.md

@@ -0,0 +1,7 @@
+---
+'@red-hat-developer-hub/backstage-plugin-scorecard': patch
+'@red-hat-developer-hub/backstage-plugin-scorecard-backend': patch
+'@red-hat-developer-hub/backstage-plugin-scorecard-common': patch
+---
+
+Skip scalar aggregation threshold coloring when no successful samples contributed (`total` is 0); return a null display color and keep the card grey fallback.

workspaces/scorecard/plugins/scorecard-backend/__fixtures__/mockAggregatedMetricResult.ts

@@ -53,6 +53,7 @@ export const mockScalarAggregationResult: ScalarAggregationResult = {
   timestamp: '2025-01-01T10:30:00.000Z',
   entitiesConsidered: 2,
   calculationErrorCount: 0,
+  aggregationChartDisplayColor: 'warning.main',
 };
 
 export const mockWeightedStatusScoreAggregationResult: WeightedStatusScoreAggregationResult =

workspaces/scorecard/plugins/scorecard-backend/src/constants/aggregationKPIs.ts

@@ -46,3 +46,28 @@ export const DEFAULT_WEIGHTED_STATUS_SCORE_KPI_RESULT_THRESHOLDS: ThresholdConfi
       },
     ],
   };
+
+/**
+ * Default applied by `ScalarAggregationStrategy` when `options.thresholds` is omitted
+ * from app-config. Higher value = better. Evaluated in order; first match wins.
+ */
+export const DEFAULT_SCALAR_AGGREGATION_KPI_RESULT_THRESHOLDS: ThresholdConfig =
+  {
+    rules: [
+      {
+        key: 'success',
+        expression: '<10',
+        color: ScorecardThresholdRuleColors.SUCCESS,
+      },
+      {
+        key: 'warning',
+        expression: '10-50',
+        color: ScorecardThresholdRuleColors.WARNING,
+      },
+      {
+        key: 'error',
+        expression: '>50',
+        color: ScorecardThresholdRuleColors.ERROR,
+      },
+    ],
+  };

workspaces/scorecard/plugins/scorecard-backend/src/service/aggregations/strategies/ScalarAggregationStrategy.ts

@@ -31,6 +31,8 @@ import type { AggregationStrategy } from './types';
 import { isScalarAggregationConfig } from '../../../utils/aggregation/isScalarAggregationConfig';
 import { classifyNumberAgainstThresholds } from '../../../utils/aggregation/classifyNumberAgainstThresholds';
 import { ThresholdEvaluator } from '../../../threshold/ThresholdEvaluator';
+import { getRequiredAggregationChartDisplayColor } from '../../../utils/aggregation/getAggregationChartDisplayColor';
+import { DEFAULT_SCALAR_AGGREGATION_KPI_RESULT_THRESHOLDS } from '../../../constants';
 
 export class ScalarAggregationStrategy implements AggregationStrategy {
   constructor(
@@ -50,8 +52,7 @@ export class ScalarAggregationStrategy implements AggregationStrategy {
       );
     }
 
-    const { thresholds: headlineThresholds = DEFAULT_NUMBER_THRESHOLDS } =
-      aggregationConfig.options ?? {};
+    const { thresholds: headlineThresholds } = aggregationConfig.options ?? {};
 
     const {
       value,
@@ -66,13 +67,24 @@ export class ScalarAggregationStrategy implements AggregationStrategy {
       aggregationConfig.filter,
     );
 
+    const aggregationChartDisplayColor =
+      total > 0
+        ? getRequiredAggregationChartDisplayColor(
+            value,
+            headlineThresholds ??
+              DEFAULT_SCALAR_AGGREGATION_KPI_RESULT_THRESHOLDS,
+            `The color for value '${value}' metric '${metric.id}' is not configured. Check the 'scorecard.aggregationKPIs.${aggregationConfig.id}.options.thresholds' configuration.`,
+          )
+        : null;
+
     const result = {
       value,
       total,
       entitiesConsidered,
       calculationErrorCount,
       timestamp,
-      thresholds: headlineThresholds,
+      aggregationChartDisplayColor,
+      thresholds: headlineThresholds ?? DEFAULT_NUMBER_THRESHOLDS,
     } satisfies ScalarAggregationResult;
 
     return AggregatedMetricMapper.toAggregatedMetricResult(

workspaces/scorecard/plugins/scorecard-backend/src/service/aggregations/strategies/WeightedStatusScoreAggregationStrategy.ts

@@ -18,7 +18,6 @@ import {
   type AggregatedMetric,
   type WeightedStatusScoreAggregationResult,
   type AggregatedMetricResult,
-  type ThresholdConfig,
   ThresholdRule,
   aggregationTypes,
   type StatusScoreAggregationOption,
@@ -29,7 +28,7 @@ import type { AggregatedMetricLoader } from '../AggregatedMetricLoader';
 import type { AggregationOptions } from '../types';
 import type { AggregationStrategy } from './types';
 import { LoggerService } from '@backstage/backend-plugin-api';
-import { ThresholdEvaluator } from '../../../threshold/ThresholdEvaluator';
+import { getRequiredAggregationChartDisplayColor } from '../../../utils/aggregation/getAggregationChartDisplayColor';
 
 export class WeightedStatusScoreAggregationStrategy
   implements AggregationStrategy
@@ -77,16 +76,14 @@ export class WeightedStatusScoreAggregationStrategy
         weightedSum,
       );
 
-    const aggregationChartDisplayColor = this.getAggregationChartDisplayColor(
-      weightedStatusScore,
-      headlineThresholds,
-    );
-
-    if (!aggregationChartDisplayColor) {
-      throw new Error(
-        `The color for percentage '${weightedStatusScore}' metric '${metric.id}' is not configured. Check the 'scorecard.aggregationKPIs.${aggregationConfig.id}.options.thresholds' configuration.`,
-      );
-    }
+    const aggregationChartDisplayColor =
+      aggregatedMetric.total > 0
+        ? getRequiredAggregationChartDisplayColor(
+            weightedStatusScore,
+            headlineThresholds,
+            `The color for percentage '${weightedStatusScore}' metric '${metric.id}' is not configured. Check the 'scorecard.aggregationKPIs.${aggregationConfig.id}.options.thresholds' configuration.`,
+          )
+        : null;
 
     const result = {
       total: aggregatedMetric.total,
@@ -131,21 +128,6 @@ export class WeightedStatusScoreAggregationStrategy
     return weightedSum;
   }
 
-  private getAggregationChartDisplayColor(
-    scorePercent: number,
-    thresholds: ThresholdConfig,
-  ): string | undefined {
-    const thresholdEvaluator = new ThresholdEvaluator();
-
-    const matchedThresholdKey = thresholdEvaluator.getFirstMatchingThreshold(
-      scorePercent,
-      'number',
-      thresholds,
-    );
-
-    return thresholds.rules.find(r => r.key === matchedThresholdKey)?.color;
-  }
-
   private prepareWeightedStatusScoreValues(
     numberOfEntities: Pick<AggregatedMetric, 'total'>['total'],
     statusScores: StatusScoreAggregationOption,

workspaces/scorecard/plugins/scorecard-backend/src/service/aggregations/strategies/scalarAggregationStrategy.test.ts

@@ -129,7 +129,11 @@ describe('ScalarAggregationStrategy', () => {
 
     expect(spyMethods.toAggregatedMetricResultSpy).toHaveBeenCalledWith(
       metric,
-      { ...loadedScalarMetric, thresholds: DEFAULT_NUMBER_THRESHOLDS },
+      {
+        ...loadedScalarMetric,
+        thresholds: DEFAULT_NUMBER_THRESHOLDS,
+        aggregationChartDisplayColor: 'error.main',
+      },
       defaultAggregationConfig,
     );
   });
@@ -144,7 +148,64 @@ describe('ScalarAggregationStrategy', () => {
 
     expect(spyMethods.toAggregatedMetricResultSpy).toHaveBeenCalledWith(
       metric,
-      { ...loadedScalarMetric, thresholds: mockHigherIsBetterThresholds },
+      {
+        ...loadedScalarMetric,
+        thresholds: mockHigherIsBetterThresholds,
+        aggregationChartDisplayColor: 'green',
+      },
+      aggregationConfig,
+    );
+  });
+
+  it('should throw when aggregation chart display color is not configured', async () => {
+    const aggregationConfigWithoutColors = mockScalarAggregationConfig(
+      aggregationTypes.sum,
+      {
+        id: 'totalOpenPrs',
+        metricId: metric.id,
+        options: {
+          thresholds: {
+            rules: [{ key: 'success', expression: '<10' }],
+          },
+        },
+      },
+    );
+
+    await expect(() =>
+      strategy.aggregate({
+        metric,
+        entityRefs,
+        thresholds: mockHigherIsBetterThresholds,
+        aggregationConfig: aggregationConfigWithoutColors,
+      }),
+    ).rejects.toThrow(
+      `The color for value '${loadedScalarMetric.value}' metric '${metric.id}' is not configured. Check the 'scorecard.aggregationKPIs.totalOpenPrs.options.thresholds' configuration.`,
+    );
+  });
+
+  it('should set aggregationChartDisplayColor to null when total is 0', async () => {
+    (loader.loadScalarMetricByEntityRefs as jest.Mock).mockResolvedValueOnce({
+      ...loadedScalarMetric,
+      value: 0,
+      total: 0,
+    });
+
+    await strategy.aggregate({
+      metric,
+      entityRefs,
+      thresholds: mockHigherIsBetterThresholds,
+      aggregationConfig,
+    });
+
+    expect(spyMethods.toAggregatedMetricResultSpy).toHaveBeenCalledWith(
+      metric,
+      {
+        ...loadedScalarMetric,
+        value: 0,
+        total: 0,
+        thresholds: mockHigherIsBetterThresholds,
+        aggregationChartDisplayColor: null,
+      },
       aggregationConfig,
     );
   });
@@ -200,7 +261,11 @@ describe('ScalarAggregationStrategy', () => {
 
     expect(spyMethods.toAggregatedMetricResultSpy).toHaveBeenCalledWith(
       metric,
-      { ...loadedScalarMetric, thresholds: mockHigherIsBetterThresholds },
+      {
+        ...loadedScalarMetric,
+        thresholds: mockHigherIsBetterThresholds,
+        aggregationChartDisplayColor: 'green',
+      },
       aggregationConfig,
     );
   });

workspaces/scorecard/plugins/scorecard-backend/src/service/aggregations/strategies/weightedStatusScoreAggregationStrategy.test.ts

@@ -193,6 +193,40 @@ describe('WeightedStatusScoreAggregationStrategy', () => {
     );
   });
 
+  it('should set aggregationChartDisplayColor to null when total is 0', async () => {
+    (
+      loader.loadStatusGroupedMetricByEntityRefs as jest.Mock
+    ).mockResolvedValueOnce({
+      ...loadedStatusGroupedMetric,
+      values: {},
+      total: 0,
+    });
+
+    await strategy.aggregate({
+      metric,
+      entityRefs,
+      thresholds: mockHigherIsBetterThresholds,
+      aggregationConfig,
+    });
+
+    expect(spyMethods.toAggregatedMetricResultSpy).toHaveBeenCalledWith(
+      metric,
+      {
+        ...mappedWeightedResult,
+        values: [
+          { name: 'success', count: 0, score: 100 },
+          { name: 'error', count: 0, score: 0 },
+        ],
+        weightedStatusScore: 0,
+        weightedStatusSum: 0,
+        weightedStatusMaxPossible: 0,
+        aggregationChartDisplayColor: null,
+        total: 0,
+      },
+      aggregationConfig,
+    );
+  });
+
   it('should get aggregation result', async () => {
     const result = await strategy.aggregate({
       metric,

workspaces/scorecard/plugins/scorecard-backend/src/service/mappers.test.ts

@@ -348,6 +348,7 @@ describe('AggregatedMetricMapper', () => {
           calculationErrorCount: 1,
           timestamp: '2024-01-15T10:00:00.000Z',
           thresholds,
+          aggregationChartDisplayColor: 'warning.main',
         },
         aggregationConfig,
       );
@@ -369,6 +370,7 @@ describe('AggregatedMetricMapper', () => {
           calculationErrorCount: 1,
           timestamp: '2024-01-15T10:00:00.000Z',
           thresholds,
+          aggregationChartDisplayColor: 'warning.main',
         },
         aggregationConfig,
       );

workspaces/scorecard/plugins/scorecard-backend/src/service/router.test.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Config } from '@backstage/config';
+import type { Config } from '@backstage/config';
 import {
   mockErrorHandler,
   mockServices,
@@ -1619,6 +1619,7 @@ describe('createRouter', () => {
         entitiesConsidered: 45,
         calculationErrorCount: 3,
         timestamp: '2025-01-01T10:30:00.000Z',
+        aggregationChartDisplayColor: 'error.main',
         thresholds: DEFAULT_NUMBER_THRESHOLDS,
       });
     });