feat: add metrics in packages api

Signed-off-by: Umberto Sgueglia <usgueglia@contractor.linuxfoundation.org>

Author: ulemons

backend/src/api/public/v1/packages/listPackages.ts

@@ -1,7 +1,11 @@
 import type { Request, Response } from 'express'
 import { z } from 'zod'
 
-import { getPackageStatusCounts, listPackagesForApi } from '@crowd/data-access-layer'
+import {
+  computeHealthBand,
+  getPackageStatusCounts,
+  listPackagesForApi,
+} from '@crowd/data-access-layer'
 
 import { getPackagesQx } from '@/db/packagesDb'
 import { ok } from '@/utils/api'
@@ -84,9 +88,12 @@ export async function listPackages(req: Request, res: Response): Promise<void> {
     purl: r.purl,
     name: r.name,
     ecosystem: r.ecosystem,
-    health: r.scorecardScore != null ? Math.round(Number(r.scorecardScore) * 10) : null,
+    health: {
+      score: r.scorecardScore != null ? Math.round(Number(r.scorecardScore) * 10) : null,
+      label: r.healthLabel ?? computeHealthBand(r.scorecardScore),
+    },
     impact: r.criticalityScore != null ? Math.round(Number(r.criticalityScore) * 100) : null,
-    lifecycle: null,
+    lifecycle: r.lifecycleLabel,
     maintainerBusFactor: r.maintainerCount,
     openVulns: r.openVulns,
     stewardshipId: r.stewardshipId ?? null,

backend/src/api/public/v1/packages/openapi.yaml

@@ -180,10 +180,20 @@ components:
           type: string
           example: npm
         health:
-          type:
-            - integer
-            - 'null'
-          example: 18
+          type: object
+          required: [score, label]
+          properties:
+            score:
+              type:
+                - integer
+                - 'null'
+              description: Health score (0–100) derived from OpenSSF Scorecard. Null if no repo is linked.
+              example: 18
+            label:
+              type: string
+              enum: [healthy, fair, concerning, critical]
+              description: 'Derived from score: healthy ≥70, fair 50–69, concerning 30–49, critical <30 or null.'
+              example: critical
         impact:
           type:
             - integer
@@ -814,7 +824,9 @@ paths:
                     name: lodash
                     ecosystem: npm
                     lifecycle: declining
-                    health: 18
+                    health:
+                      score: 18
+                      label: critical
                     impact: 71
                     openVulns:
                       low: 0

services/libs/data-access-layer/src/osspckgs/api.ts

@@ -135,7 +135,9 @@ export interface PackageListRow {
   maxVulnSeverity: 'critical' | 'high' | 'medium' | 'low' | null
   maintainerCount: number
   scorecardScore: number | null
+  healthLabel: string | null
   latestReleaseAt: Date | null
+  lifecycleLabel: string | null
   lastActivityType?: string | null
   lastActivityContent?: string | null
   lastActivityMetadata?: Record<string, unknown> | null
@@ -551,7 +553,9 @@ export async function listPackagesForApi(
       END AS "maxVulnSeverity",
       pm_counts.cnt AS "maintainerCount",
       r_sc.scorecard_score AS "scorecardScore",
+      p.health_label AS "healthLabel",
       p.latest_release_at AS "latestReleaseAt",
+      p.lifecycle_label AS "lifecycleLabel",
       ${opts.includeLastActivity === true ? `last_act.activity_type AS "lastActivityType", last_act.content AS "lastActivityContent", last_act.metadata AS "lastActivityMetadata", last_act.created_at AS "lastActivityAt",` : ''}
       ${opts.includeStewards === true ? 'ss_agg.stewards AS stewards,' : ''}
       COUNT(*) OVER() AS total