fix: lint and consistency

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

Author: ulemons

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

@@ -263,7 +263,11 @@ components:
           description: ROUND(scorecard_score × 10). X-axis position (0–100). 0 if no repo.
           example: 52
         healthBand:
-          $ref: '#/components/schemas/HealthBand'
+          type: string
+          enum: [healthy, fair, concerning, critical]
+          description: >
+            Falls back to scorecard thresholds — never 'excellent' (scatter uses
+            scorecard score only, not Tinybird health_label).
         stewardshipStatus:
           oneOf:
             - $ref: '#/components/schemas/StewardshipStatus'

backend/src/api/public/v1/ossprey/packageList.ts

@@ -13,7 +13,7 @@ import { ok } from '@/utils/api'
 import { validateOrThrow } from '@/utils/validation'
 
 import { purlFilterSchema } from '../packages/purl'
-import { LIFECYCLE_VALUES } from '../packages/types'
+import { HEALTH_BAND_SET, HEALTH_BAND_VALUES, LIFECYCLE_VALUES } from '../packages/types'
 
 const MAX_PAGE_SIZE = 250
 const LIFECYCLE_SET = new Set<string>(LIFECYCLE_VALUES)
@@ -39,7 +39,7 @@ const querySchema = z.object({
       'inactive',
     ])
     .optional(),
-  healthBand: z.enum(['excellent', 'healthy', 'fair', 'concerning', 'critical']).optional(),
+  healthBand: z.enum(HEALTH_BAND_VALUES).optional(),
   vulnSeverity: z.enum(['any', 'high', 'critical', 'none']).optional(),
   staleOnly: boolParam,
   unstewardedOnly: boolParam,
@@ -85,7 +85,10 @@ export async function packageListHandler(req: Request, res: Response): Promise<v
       health: {
         score:
           r.healthScore ?? (r.scorecardScore != null ? Math.round(r.scorecardScore * 10) : null),
-        label: r.healthLabel ?? computeHealthBand(r.scorecardScore),
+        label:
+          r.healthLabel != null && HEALTH_BAND_SET.has(r.healthLabel)
+            ? r.healthLabel
+            : computeHealthBand(r.scorecardScore),
       },
       lifecycle:
         r.lifecycleLabel != null && LIFECYCLE_SET.has(r.lifecycleLabel) ? r.lifecycleLabel : null,

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

@@ -13,7 +13,9 @@ import { ok } from '@/utils/api'
 import { validateOrThrow } from '@/utils/validation'
 
 import { purlQuerySchema } from './purl'
-import type { StewardshipStatus } from './types'
+import { HEALTH_BAND_SET, LIFECYCLE_VALUES, type StewardshipStatus } from './types'
+
+const LIFECYCLE_SET = new Set<string>(LIFECYCLE_VALUES)
 
 function snakeToCamelKeys(obj: Record<string, unknown> | null): Record<string, unknown> | null {
   if (obj === null) return null
@@ -47,7 +49,6 @@ export async function getPackage(req: Request, res: Response): Promise<void> {
   const scorecardScore = pkg.scorecardScore != null ? Number(pkg.scorecardScore) : null
   const mappingConfidence =
     pkg.repoMappingConfidence != null ? Number(pkg.repoMappingConfidence) : null
-  const healthBandScore = pkg.healthScore !== null ? pkg.healthScore / 10 : scorecardScore
 
   ok(res, {
     purl: pkg.purl,
@@ -58,22 +59,28 @@ export async function getPackage(req: Request, res: Response): Promise<void> {
       healthScore: pkg.healthScore,
       healthScoreDetails: {
         total: pkg.healthScore,
-        label: pkg.healthLabel,
+        label:
+          pkg.healthLabel != null && HEALTH_BAND_SET.has(pkg.healthLabel) ? pkg.healthLabel : null,
         maintainerHealth: pkg.maintainerHealthScore,
         securitySupplyChain: pkg.securitySupplyChainScore,
         developmentActivity: pkg.developmentActivityScore,
       },
-      healthBand: computeHealthBand(healthBandScore),
+      healthBand:
+        pkg.healthLabel != null && HEALTH_BAND_SET.has(pkg.healthLabel)
+          ? pkg.healthLabel
+          : computeHealthBand(scorecardScore),
       impact: {
-        impactScore:
-          pkg.criticalityScore != null ? Math.round(Number(pkg.criticalityScore) * 100) : null,
+        impactScore: pkg.criticalityScore != null ? Math.round(pkg.criticalityScore * 100) : null,
         downloadsLastMonth: pkg.downloadsLast30d ?? null,
         dependentPackages: pkg.dependentPackagesCount ?? null,
         dependentRepos: pkg.dependentReposCount ?? null,
         transitiveReach: pkg.transitiveReach,
       },
       riskSignals: {
-        lifecycle: pkg.lifecycleLabel,
+        lifecycle:
+          pkg.lifecycleLabel != null && LIFECYCLE_SET.has(pkg.lifecycleLabel)
+            ? pkg.lifecycleLabel
+            : null,
         maintainerBusFactor: pkg.maintainerCount,
         lastRelease: pkg.latestReleaseAt ? pkg.latestReleaseAt.toISOString() : null,
         hasSecurityFile: pkg.hasSecurityFile,

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

@@ -12,15 +12,20 @@ import { ok } from '@/utils/api'
 import { validateOrThrow } from '@/utils/validation'
 
 import { purlFilterSchema } from './purl'
-import { LIFECYCLE_VALUES, STEWARDSHIP_STATUS_VALUES, type StewardshipStatus } from './types'
+import {
+  HEALTH_BAND_SET,
+  HEALTH_BAND_VALUES,
+  LIFECYCLE_VALUES,
+  STEWARDSHIP_STATUS_VALUES,
+  type StewardshipStatus,
+} from './types'
 
 const DEFAULT_PAGE_SIZE = 20
 const MAX_PAGE_SIZE = 100
 
 const booleanQueryParam = z.preprocess((v) => v === 'true', z.boolean()).default(false)
 
 const LIFECYCLE_SET = new Set<string>(LIFECYCLE_VALUES)
-const healthBandValues = ['excellent', 'healthy', 'fair', 'concerning', 'critical'] as const
 const vulnSeverityValues = ['any', 'high', 'critical', 'none'] as const
 
 const querySchema = z.object({
@@ -31,7 +36,7 @@ const querySchema = z.object({
   name: z.string().trim().optional(),
   purl: purlFilterSchema,
   status: z.enum(STEWARDSHIP_STATUS_VALUES).optional(),
-  healthBand: z.enum(healthBandValues).optional(),
+  healthBand: z.enum(HEALTH_BAND_VALUES).optional(),
   vulnSeverity: z.enum(vulnSeverityValues).optional(),
   busFactor1Only: booleanQueryParam,
   staleOnly: booleanQueryParam,
@@ -90,7 +95,10 @@ export async function listPackages(req: Request, res: Response): Promise<void> {
     ecosystem: r.ecosystem,
     health: {
       score: r.healthScore ?? (r.scorecardScore != null ? Math.round(r.scorecardScore * 10) : null),
-      label: r.healthLabel ?? computeHealthBand(r.scorecardScore),
+      label:
+        r.healthLabel != null && HEALTH_BAND_SET.has(r.healthLabel)
+          ? r.healthLabel
+          : computeHealthBand(r.scorecardScore),
     },
     impact: r.criticalityScore != null ? Math.round(r.criticalityScore * 100) : null,
     lifecycle:

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

@@ -15,6 +15,18 @@ export const LIFECYCLE_VALUES = ['active', 'stable', 'declining', 'abandoned', '
 
 export type Lifecycle = (typeof LIFECYCLE_VALUES)[number]
 
+export const HEALTH_BAND_VALUES = [
+  'excellent',
+  'healthy',
+  'fair',
+  'concerning',
+  'critical',
+] as const
+
+export type HealthBand = (typeof HEALTH_BAND_VALUES)[number]
+
+export const HEALTH_BAND_SET = new Set<string>(HEALTH_BAND_VALUES)
+
 export type SeverityLevel = 'critical' | 'high' | 'medium' | 'low'
 
 export interface OpenVulns {

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

@@ -11,7 +11,7 @@ export interface PackageMetrics {
   criticalPackages: number
 }
 
-export async function getPackageMetrics(qx: QueryExecutor): Promise {
+export async function getPackageMetrics(qx: QueryExecutor): Promise<PackageMetrics> {
   const row: { total: string; critical: string } = await qx.selectOne(`
     SELECT
       COUNT(*) AS total,
@@ -34,7 +34,10 @@ export interface PackageStewardshipRow {
   stewardshipStatus: string | null
 }
 
-export async function getPackagesByStewardshipPurls(qx: QueryExecutor, purls: string[]): Promise {
+export async function getPackagesByStewardshipPurls(
+  qx: QueryExecutor,
+  purls: string[],
+): Promise<PackageStewardshipRow[]> {
   if (purls.length === 0) return []
   return qx.select(
     `
@@ -65,7 +68,7 @@ export interface OsspreyMetrics {
 }
 
 // TODO[deprecate]: rename to getAkritesMetrics once /v1/ossprey is removed
-export async function getOsspreyMetrics(qx: QueryExecutor): Promise {
+export async function getOsspreyMetrics(qx: QueryExecutor): Promise<OsspreyMetrics> {
   const [counts, stewardRow]: [
     {
       totalPackages: string
@@ -138,7 +141,7 @@ export interface PackageListRow {
   lifecycleLabel: string | null
   lastActivityType?: string | null
   lastActivityContent?: string | null
-  lastActivityMetadata?: Record | null
+  lastActivityMetadata?: Record<string, unknown> | null
   lastActivityAt?: Date | null
   stewards?: StewardEntry[]
   total: string
@@ -196,7 +199,10 @@ export interface PackageStatusCounts {
   inactive: number
 }
 
-export type StatusCountsOptions = Omit
+export type StatusCountsOptions = Omit<
+  ListPackagesOptions,
+  'status' | 'page' | 'pageSize' | 'sortBy' | 'sortDir'
+>
 
 const ALL_STEWARDSHIP_STATUSES = [
   'unassigned',
@@ -216,9 +222,9 @@ const ALL_STEWARDSHIP_STATUSES = [
 export async function getPackageStatusCounts(
   qx: QueryExecutor,
   opts: StatusCountsOptions,
-): Promise {
+): Promise<PackageStatusCounts> {
   const conditions: string[] = ['p.is_critical = true']
-  const params: Record = {}
+  const params: Record<string, unknown> = {}
 
   if (opts.ecosystem) {
     conditions.push('p.ecosystem = $(ecosystem)')
@@ -315,7 +321,7 @@ export async function getPackageStatusCounts(
     params,
   )
 
-  const countsMap: Record = {}
+  const countsMap: Record<string, number> = {}
   let all = 0
   for (const row of rows) {
     countsMap[row.status] = row.count
@@ -339,9 +345,12 @@ export async function getPackageStatusCounts(
   return result
 }
 
-export async function listPackagesForApi(qx: QueryExecutor, opts: ListPackagesOptions): Promise {
+export async function listPackagesForApi(
+  qx: QueryExecutor,
+  opts: ListPackagesOptions,
+): Promise<{ rows: PackageListRow[]; total: number }> {
   const conditions: string[] = ['p.is_critical = true']
-  const params: Record = {}
+  const params: Record<string, unknown> = {}
 
   if (opts.ecosystem) {
     conditions.push('p.ecosystem = $(ecosystem)')
@@ -444,7 +453,7 @@ export async function listPackagesForApi(qx: QueryExecutor, opts: ListPackagesOp
   const sortDir = opts.sortDir === 'desc' ? 'DESC' : 'ASC'
 
   // Separate paginated params from filter-only params used by the fallback COUNT query
-  const queryParams: Record = {
+  const queryParams: Record<string, unknown> = {
     ...params,
     limit: opts.pageSize,
     offset: (opts.page - 1) * opts.pageSize,
@@ -551,8 +560,8 @@ export async function listPackagesForApi(qx: QueryExecutor, opts: ListPackagesOp
       r_sc.scorecard_score AS "scorecardScore",
       p.health_score AS "healthScore",
       p.health_label AS "healthLabel",
-      p.latest_release_at AS "latestReleaseAt",
       p.lifecycle_label AS "lifecycleLabel",
+      p.latest_release_at AS "latestReleaseAt",
       ${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
@@ -626,7 +635,7 @@ export interface PackageDetailRow {
   securitySupplyChainScore: number | null
   developmentActivityScore: number | null
   lifecycleLabel: string | null
-  signalCoverageHealth: Record | null
+  signalCoverageHealth: Record<string, unknown> | null
 }
 
 export interface AdvisoryRow {
@@ -636,7 +645,10 @@ export interface AdvisoryRow {
   isCritical: boolean
 }
 
-export async function getPackageDetailByPurl(qx: QueryExecutor, purl: string): Promise {
+export async function getPackageDetailByPurl(
+  qx: QueryExecutor,
+  purl: string,
+): Promise<PackageDetailRow | null> {
   return qx.selectOneOrNone(
     `
     SELECT
@@ -727,7 +739,7 @@ export interface ScatterPoint {
 export async function listPackagesForScatter(
   qx: QueryExecutor,
   options: { status?: string[]; ecosystem?: string } = {},
-): Promise {
+): Promise<ScatterPoint[]> {
   const { status, ecosystem } = options
 
   // 'unassigned' covers packages with no stewardship row (s.id IS NULL) in addition
@@ -739,7 +751,16 @@ export async function listPackagesForScatter(
     : ''
   const ecosystemFilter = ecosystem ? `AND p.ecosystem = $(ecosystem)` : ''
 
-  const rows: Array = await qx.select(
+  const rows: Array<{
+    purl: string
+    name: string
+    criticalityScore: number
+    healthScore: number
+    scorecardScoreRaw: number | null
+    stewardshipId: string | null
+    stewardshipStatus: string | null
+    openVulns: number
+  }> = await qx.select(
     `
     SELECT
       p.purl,
@@ -795,7 +816,7 @@ export async function getAdvisoriesByPackageId(
     resolutions?: ('open' | 'patched')[]
     critical?: boolean
   },
-): Promise {
+): Promise<{ rows: AdvisoryRow[]; total: number }> {
   const cte = `
     WITH advisory_data AS (
       SELECT