feat: add metrics in packages api (CM-1285)

[ulemons]

Summary

Adds impact, lifecycle, and health: { score, label } to the /v1/packages list API response. These fields were already computed and stored in the packages table but not exposed in the list endpoint. No new JOINs or queries are added — it's a pure SELECT extension on an already-touched table.

health.label uses the Tinybird-enriched health_label when available, falling back to
computeHealthBand(scorecardScore) — consistent with the detail endpoint behaviour.

Changes

• listPackages.ts — health reshaped from number | null to { score, label }; lifecycle now populated from p.lifecycle_label instead of hardcoded null; health.label uses Tinybird field with scorecard fallback
• api.ts (DAL) — PackageListRow interface gains lifecycleLabel and healthLabel; listPackagesForApi SELECT extended with p.lifecycle_label and p.health_label
• openapi.yaml — PackageListItem.health schema updated from integer | null to { score, label } object; inline example updated

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Performance improvement
• Chore / dependency update
• Documentation

CM-1285

---

Note

Medium Risk
Breaking JSON shape for /v1/packages list health (integer → object) and OSSPREY healthBand → health; clients must update. Filter semantics for lifecycle and excellent health band change query results.

Overview
Package list responses now surface Tinybird-enriched health_score, health_label, and lifecycle_label from the packages table (SELECT-only in the DAL), with OpenAPI aligned for both OSSPREY and /v1/packages.

health is no longer a bare integer or top-level healthBand: list rows return { score, label }, preferring stored Tinybird values and falling back to Scorecard × 10 and computeHealthBand. impact is added as a 0–100 display field; lifecycle is populated when the label is in the allowed set (now including archived). Detail getPackage applies the same label validation for healthBand and riskSignals.lifecycle.

Query validation and filtering share HEALTH_BAND_VALUES / LIFECYCLE_VALUES; healthBand=excellent filters on p.health_label, and lifecycle filters on p.lifecycle_label instead of the previous p.status IS NOT NULL placeholder.

^{Reviewed by Cursor Bugbot for commit 3079df4. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Pull request overview

This PR extends the public packages list API (GET /v1/packages) to expose already-computed package metrics: impact, lifecycle, and health (now shaped as { score, label }). It updates the DAL list query to select the additional columns and updates the OpenAPI schema/example accordingly.

Changes:

• Extend listPackagesForApi SELECT + PackageListRow typing to include packages.health_label and packages.lifecycle_label.
• Change list response health from integer | null to { score, label }, with label coming from Tinybird-enriched health_label or falling back to computeHealthBand(scorecardScore).
• Update OpenAPI PackageListItem.health schema and the batch-stewardship example.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
services/libs/data-access-layer/src/osspckgs/api.ts	Adds healthLabel/lifecycleLabel fields to PackageListRow and selects p.health_label/p.lifecycle_label in listPackagesForApi.
backend/src/api/public/v1/packages/listPackages.ts	Reshapes health into { score, label } and returns lifecycle from the DB label.
backend/src/api/public/v1/packages/openapi.yaml	Updates PackageListItem.health to an object schema and adjusts an example payload.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6b4b120. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

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

• HealthBand now includes 'excellent', but buildHealthBandCondition can only build conditions for scorecard-derived bands. As written, passing 'excellent' would fall through to the “critical” branch, which is incorrect and makes the helper’s contract unsafe now that the type includes 'excellent'. Narrow the helper’s band parameter to exclude 'excellent' (or introduce a separate scorecard-only band type) so TypeScript prevents accidental misuse.

export type HealthBand = 'excellent' | 'healthy' | 'fair' | 'concerning' | 'critical'
export type VulnSeverityFilter = 'any' | 'high' | 'critical' | 'none'

export function computeHealthBand(scorecardScore: number | null): HealthBand {
  if (scorecardScore === null || scorecardScore < 3.0) return 'critical'