feat: adding stewardship tables and small fixis (CM-1218) (#4191)

Signed-off-by: Umberto Sgueglia <usgueglia@contractor.linuxfoundation.org>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ulemons

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

@@ -5,6 +5,7 @@ import { ok } from '@/utils/api'
 import { validateOrThrow } from '@/utils/validation'
 
 import { MOCK_DETAILS } from './mockData'
+import type { OpenVulns, StewardshipSummary } from './types'
 
 const MAX_PURLS = 100
 
@@ -15,19 +16,6 @@ const bodySchema = z.object({
     .max(MAX_PURLS, `Maximum ${MAX_PURLS} purls per request`),
 })
 
-interface StewardshipSummary {
-  name: string
-  ecosystem: string
-  lifecycle: string
-  health: number
-  impact: number
-  openVulns: { low: number; medium: number; high: number; critical: number }
-  stewardship: string
-  stewards: null
-  lastActivityAt: null
-  lastActivityDescription: null
-}
-
 // TODO: replace with real DB queries once stewardship tables land
 export async function batchGetStewardship(req: Request, res: Response): Promise<void> {
   const { purls } = validateOrThrow(bodySchema, req.body)
@@ -38,11 +26,9 @@ export async function batchGetStewardship(req: Request, res: Response): Promise<
     if (!detail) {
       packages[purl] = null
     } else {
-      const openVulns = { low: 0, medium: 0, high: 0, critical: 0 }
+      const openVulns: OpenVulns = { low: 0, medium: 0, high: 0, critical: 0 }
       for (const advisory of detail.security.advisories) {
-        if (advisory.severity in openVulns) {
-          openVulns[advisory.severity] += 1
-        }
+        openVulns[advisory.severity] += 1
       }
       packages[purl] = {
         name: detail.name,
@@ -51,8 +37,8 @@ export async function batchGetStewardship(req: Request, res: Response): Promise<
         health: detail.general.healthScore.total,
         impact: detail.general.impact.impactScore,
         openVulns,
-        stewardship: 'unassigned',
-        stewards: null,
+        stewardship: detail.stewardship.status,
+        stewards: detail.stewardship.stewards,
         lastActivityAt: null,
         lastActivityDescription: null,
       }

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

@@ -47,7 +47,7 @@ export async function listPackages(req: Request, res: Response): Promise<void> {
     if (ecosystem && p.ecosystem !== ecosystem) return false
     if (lifecycle && p.lifecycle !== lifecycle) return false
     if (busFactor1Only && p.maintainerBusFactor !== 1) return false
-    if (unstewardedOnly && p.stewardship !== 'unassigned') return false
+    if (unstewardedOnly && p.stewardship !== null && p.stewardship !== 'unassigned') return false
     if (staleOnly) {
       const lastRelease = MOCK_DETAILS[p.purl]?.general.riskSignals.lastRelease
       if (!lastRelease || new Date(lastRelease) >= staleThreshold) return false

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

@@ -1,14 +1,16 @@
+import type { Lifecycle, OpenVulns, SeverityLevel, Steward, StewardshipStatus } from './types'
+
 export interface MockPackageListItem {
   purl: string
   name: string
   ecosystem: string
   health: number
   impact: number
-  lifecycle: 'active' | 'stable' | 'declining' | 'abandoned'
+  lifecycle: Lifecycle
   maintainerBusFactor: number
-  openVulns: { low: number; medium: number; high: number; critical: number }
-  stewardship: string
-  steward: null
+  openVulns: OpenVulns
+  stewardship: StewardshipStatus | null
+  stewards: Steward[] | null
 }
 
 export interface MockPackageDetail {
@@ -30,19 +32,19 @@ export interface MockPackageDetail {
       transitiveReach: string
     }
     riskSignals: {
-      lifecycle: string
+      lifecycle: Lifecycle
       maintainerBusFactor: number
       lastRelease: string
       hasSecurityFile: null
       openSSFScorecard: number
     }
   }
-  assessment: Record<string, never>
+  assessment: Record<string, unknown>
   security: {
     securityContacts: null
     advisories: Array<{
       osvId: string
-      severity: 'critical' | 'high' | 'medium' | 'low'
+      severity: SeverityLevel
       resolution: null
     }>
     cvd: {
@@ -56,7 +58,12 @@ export interface MockPackageDetail {
     repositoryMapping: { declaredRepo: string; mappingConfidence: number; lastCommitAt: string }
     supplyChainIntegrity: { buildProvenance: null; signedReleases: null }
   }
-  history: Record<string, never>
+  stewardship: {
+    status: StewardshipStatus
+    stewards: Steward[] | null
+    lastActivityAt: string | null
+  }
+  history: Record<string, unknown>
 }
 
 export const MOCK_PACKAGES: MockPackageListItem[] = [
@@ -70,7 +77,7 @@ export const MOCK_PACKAGES: MockPackageListItem[] = [
     maintainerBusFactor: 1,
     openVulns: { low: 0, medium: 0, high: 1, critical: 0 },
     stewardship: 'unassigned',
-    steward: null,
+    stewards: null,
   },
   {
     purl: 'pkg:maven/org.apache.commons/commons-lang3@3.12.0',
@@ -82,7 +89,7 @@ export const MOCK_PACKAGES: MockPackageListItem[] = [
     maintainerBusFactor: 3,
     openVulns: { low: 0, medium: 0, high: 0, critical: 0 },
     stewardship: 'unassigned',
-    steward: null,
+    stewards: null,
   },
   {
     purl: 'pkg:npm/minimist@1.2.6',
@@ -94,7 +101,7 @@ export const MOCK_PACKAGES: MockPackageListItem[] = [
     maintainerBusFactor: 1,
     openVulns: { low: 0, medium: 1, high: 0, critical: 1 },
     stewardship: 'unassigned',
-    steward: null,
+    stewards: null,
   },
 ]
 
@@ -144,6 +151,7 @@ export const MOCK_DETAILS: Record<string, MockPackageDetail> = {
       },
       supplyChainIntegrity: { buildProvenance: null, signedReleases: null },
     },
+    stewardship: { status: 'unassigned', stewards: null, lastActivityAt: null },
     history: {},
   },
   'pkg:maven/org.apache.commons/commons-lang3@3.12.0': {
@@ -191,6 +199,7 @@ export const MOCK_DETAILS: Record<string, MockPackageDetail> = {
       },
       supplyChainIntegrity: { buildProvenance: null, signedReleases: null },
     },
+    stewardship: { status: 'unassigned', stewards: null, lastActivityAt: null },
     history: {},
   },
   'pkg:npm/minimist@1.2.6': {
@@ -241,6 +250,7 @@ export const MOCK_DETAILS: Record<string, MockPackageDetail> = {
       },
       supplyChainIntegrity: { buildProvenance: null, signedReleases: null },
     },
+    stewardship: { status: 'unassigned', stewards: null, lastActivityAt: null },
     history: {},
   },
 }

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

@@ -105,7 +105,8 @@ components:
     StewardshipSummary:
       type: object
       description: Null if the purl is not found in CDP.
-      required: [name, ecosystem, stewardship, stewards, lastActivityAt, lastActivityDescription]
+      required:
+        [name, ecosystem, stewardship, stewards, openVulns, lastActivityAt, lastActivityDescription]
       properties:
         name:
           type: string
@@ -135,9 +136,11 @@ components:
         stewardship:
           $ref: '#/components/schemas/StewardshipStatus'
         stewards:
-          description: Single steward or null. Empty in v1.
+          description: Assigned stewards or null. Empty in v1.
           oneOf:
-            - $ref: '#/components/schemas/Steward'
+            - type: array
+              items:
+                $ref: '#/components/schemas/Steward'
             - type: 'null'
         lastActivityAt:
           type:
@@ -193,10 +196,12 @@ components:
             - type: 'null'
         stewardship:
           $ref: '#/components/schemas/StewardshipStatus'
-        steward:
-          description: Single assigned steward or null.
+        stewards:
+          description: Assigned stewards or null.
           oneOf:
-            - $ref: '#/components/schemas/Steward'
+            - type: array
+              items:
+                $ref: '#/components/schemas/Steward'
             - type: 'null'
 
     # ── Package detail ───────────────────────────────────────────────────────────
@@ -411,6 +416,25 @@ components:
                   type:
                     - string
                     - 'null'
+        stewardship:
+          type: object
+          description: Stewardship state. In v1 always unassigned with no stewards or activity.
+          properties:
+            status:
+              $ref: '#/components/schemas/StewardshipStatus'
+            stewards:
+              description: Assigned stewards or null. Null in v1.
+              oneOf:
+                - type: array
+                  items:
+                    $ref: '#/components/schemas/Steward'
+                - type: 'null'
+            lastActivityAt:
+              type:
+                - string
+                - 'null'
+              format: date-time
+              description: Null in v1.
         history:
           type: object
           description: Package history data. Empty in v1.
@@ -657,6 +681,10 @@ paths:
                   supplyChainIntegrity:
                     buildProvenance: null
                     signedReleases: null
+                stewardship:
+                  status: unassigned
+                  stewards: null
+                  lastActivityAt: null
                 history: {}
         '404':
           description: Package not found.

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

@@ -0,0 +1,40 @@
+export type StewardshipStatus =
+  | 'unassigned'
+  | 'open'
+  | 'assessing'
+  | 'active'
+  | 'needs_attention'
+  | 'escalated'
+  | 'blocked'
+  | 'inactive'
+
+export type Lifecycle = 'active' | 'stable' | 'declining' | 'abandoned'
+
+export type SeverityLevel = 'critical' | 'high' | 'medium' | 'low'
+
+export interface OpenVulns {
+  low: number
+  medium: number
+  high: number
+  critical: number
+}
+
+export interface Steward {
+  userId: string
+  name: string
+  role: 'lead' | 'co_steward'
+  assignedAt: string
+}
+
+export interface StewardshipSummary {
+  name: string
+  ecosystem: string
+  lifecycle: Lifecycle | null
+  health: number | null
+  impact: number | null
+  openVulns: OpenVulns | null
+  stewardship: StewardshipStatus | null
+  stewards: Steward[] | null
+  lastActivityAt: string | null
+  lastActivityDescription: string | null
+}