feat(compare): add health score facet

Author: hamdibenjarrar

app/composables/useFacetSelection.ts

@@ -89,6 +89,11 @@ export function useFacetSelection(queryParam = 'facets') {
         description: t(`compare.facets.items.deprecated.description`),
         chartable: false,
       },
+      healthScore: {
+        label: t(`compare.facets.items.healthScore.label`),
+        description: t(`compare.facets.items.healthScore.description`),
+        chartable: true,
+      },
     }),
   )
 

app/composables/usePackageComparison.ts

@@ -49,6 +49,8 @@ export interface PackageComparisonData {
   }
   /** Whether this is a binary-only package (CLI without library entry points) */
   isBinaryOnly?: boolean
+  /** Computed health score (0-100) */
+  healthScore?: number
   /** Marks this as the "no dependency" column for special display */
   isNoDependency?: boolean
 }
@@ -191,11 +193,12 @@ export function usePackageComparison(packageNames: MaybeRefOrGetter<string[]>) {
         }),
       )
 
-      // Add results to cache
+      // Add results to cache (with computed health score)
       const newCache = new Map(cache.value)
       for (const [i, name] of namesToFetch.entries()) {
         const data = results[i]
         if (data) {
+          data.healthScore = computeHealthScore(data)
           newCache.set(name, data)
         }
       }
@@ -338,6 +341,60 @@ function resolveNoDependencyDisplay(
   }
 }
 
+/**
+ * Compute a health score (0-100) from already-fetched package data.
+ * Dimensions: Maintenance (35%), Quality (30%), Security (20%), Popularity (15%)
+ */
+export function computeHealthScore(data: PackageComparisonData): number {
+  // Deprecated packages get score 0 regardless
+  if (data.metadata?.deprecated) return 0
+
+  // MAINTENANCE (35%) — based on lastUpdated
+  let maintenance = 0
+  if (data.metadata?.lastUpdated) {
+    const daysSince = Math.floor(
+      (Date.now() - new Date(data.metadata.lastUpdated).getTime()) / 86400000,
+    )
+    if (daysSince < 30) maintenance = 100
+    else if (daysSince < 90) maintenance = 80
+    else if (daysSince < 180) maintenance = 60
+    else if (daysSince < 365) maintenance = 40
+    else maintenance = 10
+  }
+
+  // QUALITY (30%) — based on analysis data
+  let quality = 0
+  if (data.analysis) {
+    if (data.analysis.types?.kind === 'included' || data.analysis.types?.kind === '@types')
+      quality += 40
+    if (data.analysis.moduleFormat === 'esm' || data.analysis.moduleFormat === 'dual')
+      quality += 30
+    if (data.metadata?.license) quality += 20
+    if (data.package.description) quality += 10
+  }
+
+  // SECURITY (20%) — based on vulnerability severity
+  let security = 100
+  if (data.vulnerabilities) {
+    if (data.vulnerabilities.severity.critical > 0) security = 0
+    else if (data.vulnerabilities.severity.high > 0) security = 25
+    else if (data.vulnerabilities.severity.moderate > 0) security = 50
+    else if (data.vulnerabilities.count > 0) security = 75
+  }
+
+  // POPULARITY (15%) — based on weekly downloads
+  let popularity = 0
+  const dl = data.downloads ?? 0
+  if (dl > 1_000_000) popularity = 100
+  else if (dl > 100_000) popularity = 80
+  else if (dl > 10_000) popularity = 60
+  else if (dl > 1_000) popularity = 40
+  else if (dl > 100) popularity = 20
+  else popularity = 5
+
+  return Math.round(maintenance * 0.35 + quality * 0.3 + security * 0.2 + popularity * 0.15)
+}
+
 function computeFacetValue(
   facet: ComparisonFacet,
   data: PackageComparisonData,
@@ -538,6 +595,16 @@ function computeFacetValue(
         status: totalDepCount > 50 ? 'warning' : 'neutral',
       }
     }
+    case 'healthScore': {
+      const score = data.healthScore
+      if (score === undefined) return null
+      return {
+        raw: score,
+        display: `${score}/100`,
+        status: score >= 80 ? 'good' : score >= 60 ? 'warning' : 'bad',
+        tooltip: t('compare.facets.items.healthScore.tooltip'),
+      }
+    }
     default: {
       return null
     }

i18n/locales/ar-EG.json

@@ -277,7 +277,14 @@
       "select_all_category_facets": "تحديد جميع أوجه الفئة",
       "deselect_all_category_facets": "إلغاء تحديد جميع أوجه الفئة",
       "selected_all_category_facets": "تم تحديد جميع أوجه الفئة",
-      "deselected_all_category_facets": "تم إلغاء تحديد جميع أوجه الفئة"
+      "deselected_all_category_facets": "تم إلغاء تحديد جميع أوجه الفئة",
+      "items": {
+        "healthScore": {
+          "label": "درجة الصحة",
+          "description": "الصحة الإجمالية للحزمة بناءً على الصيانة والجودة والأمان والشعبية",
+          "tooltip": "درجة من 0 إلى 100. الحزم المهملة تحصل على 0."
+        }
+      }
     },
     "file_changes": "تغييرات الملفات",
     "files_count": "{count} ملفات | ملف واحد | ملفان | {count} ملفات | {count} ملفًا | {count} ملف",

i18n/locales/en.json

@@ -1200,6 +1200,11 @@
         "vulnerabilities": {
           "label": "Vulnerabilities",
           "description": "Known security vulnerabilities"
+        },
+        "healthScore": {
+          "label": "Health Score",
+          "description": "Overall package health based on maintenance, quality, security and popularity",
+          "tooltip": "Score 0–100. Deprecated packages score 0."
         }
       },
       "values": {

i18n/locales/fr-FR.json

@@ -1196,6 +1196,11 @@
         "vulnerabilities": {
           "label": "Vulnérabilités",
           "description": "Vulnérabilités de sécurité connues"
+        },
+        "healthScore": {
+          "label": "Score de santé",
+          "description": "Santé globale du paquet basée sur la maintenance, la qualité, la sécurité et la popularité",
+          "tooltip": "Score 0–100. Les paquets dépréciés obtiennent 0."
         }
       },
       "values": {

i18n/schema.json

@@ -3606,6 +3606,21 @@
                     }
                   },
                   "additionalProperties": false
+                },
+                "healthScore": {
+                  "type": "object",
+                  "properties": {
+                    "label": {
+                      "type": "string"
+                    },
+                    "description": {
+                      "type": "string"
+                    },
+                    "tooltip": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false
                 }
               },
               "additionalProperties": false

shared/types/comparison.ts

@@ -17,6 +17,7 @@ export type ComparisonFacet =
   | 'totalDependencies'
   | 'deprecated'
   | 'totalLikes'
+  | 'healthScore'
 
 /** Facet metadata for UI display */
 export interface FacetInfo {
@@ -56,6 +57,9 @@ export const FACET_INFO: Record<ComparisonFacet, Omit<FacetInfo, 'id'>> = {
   deprecated: {
     category: 'health',
   },
+  healthScore: {
+    category: 'health',
+  },
   // Compatibility
   engines: {
     category: 'compatibility',

test/nuxt/components/compare/FacetSelector.spec.ts

@@ -32,6 +32,10 @@ const facetLabels: Record<ComparisonFacet, { label: string; description: string
   },
   deprecated: { label: 'Deprecated?', description: 'Whether the package is deprecated' },
   totalLikes: { label: 'Likes', description: 'Number of likes' },
+  healthScore: {
+    label: 'Health Score',
+    description: 'Overall package health based on maintenance, quality, security and popularity',
+  },
 }
 
 const categoryLabels: Record<string, string> = {

test/nuxt/composables/use-package-comparison.spec.ts

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { mountSuspended } from '@nuxt/test-utils/runtime'
 import type { PackageComparisonData } from '~/composables/usePackageComparison'
+import { computeHealthScore } from '~/composables/usePackageComparison'
 
 /**
  * Helper to test usePackageComparison by wrapping it in a component.
@@ -127,6 +128,75 @@ describe('usePackageComparison', () => {
     })
   })
 
+  describe('computeHealthScore', () => {
+    function makeData(overrides: Partial<PackageComparisonData> = {}): PackageComparisonData {
+      return {
+        package: { name: 'test', version: '1.0.0' },
+        directDeps: 2,
+        ...overrides,
+      }
+    }
+
+    it('returns score 0 for deprecated packages', () => {
+      const score = computeHealthScore(
+        makeData({ metadata: { deprecated: 'Use something else' } }),
+      )
+      expect(score).toBe(0)
+    })
+
+    it('returns high score for a perfect package', () => {
+      const score = computeHealthScore(
+        makeData({
+          metadata: {
+            lastUpdated: new Date().toISOString(),
+            license: 'MIT',
+          },
+          downloads: 2_000_000,
+          directDeps: 1,
+          analysis: {
+            package: 'test',
+            version: '1.0.0',
+            moduleFormat: 'esm',
+            types: { kind: 'included' },
+            devDependencySuggestion: { recommended: false },
+          } as PackageComparisonData['analysis'],
+          vulnerabilities: {
+            count: 0,
+            severity: { critical: 0, high: 0, moderate: 0, low: 0 },
+          },
+        }),
+      )
+      expect(score).toBeGreaterThanOrEqual(85)
+    })
+
+    it('sets security to 0 for critical vulnerabilities', () => {
+      const safe = computeHealthScore(
+        makeData({
+          vulnerabilities: {
+            count: 0,
+            severity: { critical: 0, high: 0, moderate: 0, low: 0 },
+          },
+        }),
+      )
+      const critical = computeHealthScore(
+        makeData({
+          vulnerabilities: {
+            count: 1,
+            severity: { critical: 1, high: 0, moderate: 0, low: 0 },
+          },
+        }),
+      )
+      expect(safe).toBeGreaterThan(critical)
+    })
+
+    it('handles missing/undefined fields gracefully', () => {
+      const score = computeHealthScore(makeData())
+      expect(typeof score).toBe('number')
+      expect(score).toBeGreaterThanOrEqual(0)
+      expect(score).toBeLessThanOrEqual(100)
+    })
+  })
+
   describe('staleness detection', () => {
     it('marks packages not published in 2+ years as stale', async () => {
       vi.stubGlobal(