fix: filters (CM-1259) (#4249)

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

Author: ulemons

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

@@ -12,6 +12,8 @@ import { getPackagesQx } from '@/db/packagesDb'
 import { ok } from '@/utils/api'
 import { validateOrThrow } from '@/utils/validation'
 
+import { purlFilterSchema } from '../packages/purl'
+
 const MAX_PAGE_SIZE = 250
 
 const boolParam = z.preprocess((v) => v === 'true', z.boolean()).default(false)
@@ -22,6 +24,7 @@ const querySchema = z.object({
   ecosystem: z.string().trim().optional(),
   lifecycle: z.enum(['active', 'stable', 'declining', 'abandoned']).optional(),
   name: z.string().trim().optional(),
+  purl: purlFilterSchema,
   status: z
     .enum([
       'unassigned',
@@ -50,6 +53,7 @@ export async function packageListHandler(req: Request, res: Response): Promise<v
     ecosystem: params.ecosystem,
     lifecycle: params.lifecycle,
     name: params.name,
+    purl: params.purl,
     healthBand: params.healthBand,
     vulnSeverity: params.vulnSeverity,
     staleOnly: params.staleOnly,

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

@@ -7,6 +7,7 @@ import { getPackagesQx } from '@/db/packagesDb'
 import { ok } from '@/utils/api'
 import { validateOrThrow } from '@/utils/validation'
 
+import { purlFilterSchema } from './purl'
 import { STEWARDSHIP_STATUS_VALUES, type StewardshipStatus } from './types'
 
 const DEFAULT_PAGE_SIZE = 20
@@ -24,6 +25,7 @@ const querySchema = z.object({
   ecosystem: z.string().trim().optional(),
   lifecycle: z.enum(lifecycleValues).optional(),
   name: z.string().trim().optional(),
+  purl: purlFilterSchema,
   status: z.enum(STEWARDSHIP_STATUS_VALUES).optional(),
   healthBand: z.enum(healthBandValues).optional(),
   vulnSeverity: z.enum(vulnSeverityValues).optional(),
@@ -41,6 +43,7 @@ export async function listPackages(req: Request, res: Response): Promise<void> {
     ecosystem,
     lifecycle,
     name,
+    purl,
     status,
     healthBand,
     vulnSeverity,
@@ -55,6 +58,7 @@ export async function listPackages(req: Request, res: Response): Promise<void> {
     ecosystem,
     lifecycle,
     name,
+    purl,
     healthBand,
     vulnSeverity,
     staleOnly,
@@ -91,6 +95,7 @@ export async function listPackages(req: Request, res: Response): Promise<void> {
       ecosystem: ecosystem ?? null,
       lifecycle: lifecycle ?? null,
       name: name ?? null,
+      purl: purl ?? null,
       status: status ?? null,
       healthBand: healthBand ?? null,
       vulnSeverity: vulnSeverity ?? null,

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

@@ -15,6 +15,12 @@
  */
 import { z } from 'zod'
 
+export function normalizePurl(purl: string): string {
+  const withoutQualifiers = purl.replace(/[?#].*$/, '')
+  const withoutVersion = withoutQualifiers.replace(/@[^/@]+$/, '')
+  return withoutVersion.replace(/@/g, '%40')
+}
+
 export const purlFieldSchema = z
   .string()
   .trim()
@@ -24,8 +30,6 @@ export const purlFieldSchema = z
 
 export const purlQuerySchema = z.object({ purl: purlFieldSchema })
 
-export function normalizePurl(purl: string): string {
-  const withoutQualifiers = purl.replace(/[?#].*$/, '')
-  const withoutVersion = withoutQualifiers.replace(/@[^/@]+$/, '')
-  return withoutVersion.replace(/@/g, '%40')
-}
+// Loose schema for search filters: normalizes without requiring the pkg: prefix,
+// so partial inputs (e.g. "@babel/core" or "lodash") are accepted.
+export const purlFilterSchema = z.string().trim().transform(normalizePurl).optional()

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

@@ -154,6 +154,7 @@ export interface ListPackagesOptions {
   ecosystem?: string
   lifecycle?: string
   name?: string
+  purl?: string
   status?: string
   healthBand?: HealthBand
   vulnSeverity?: VulnSeverityFilter
@@ -226,6 +227,11 @@ export async function getPackageStatusCounts(
     params.name = `%${opts.name}%`
   }
 
+  if (opts.purl) {
+    conditions.push('p.purl ILIKE $(purl)')
+    params.purl = `%${opts.purl}%`
+  }
+
   if (opts.lifecycle) {
     conditions.push('p.status IS NOT NULL')
   }
@@ -344,6 +350,11 @@ export async function listPackagesForApi(
     params.name = `%${opts.name}%`
   }
 
+  if (opts.purl) {
+    conditions.push('p.purl ILIKE $(purl)')
+    params.purl = `%${opts.purl}%`
+  }
+
   // Exclude packages with no registry status when a lifecycle filter is active.
   // Full lifecycle column support is pending; this prevents null-lifecycle rows
   // from leaking into filtered results.
@@ -429,7 +440,24 @@ export async function listPackagesForApi(
   const sortDir = opts.sortDir === 'desc' ? 'DESC' : 'ASC'
 
   // Separate paginated params from filter-only params used by the fallback COUNT query
-  const queryParams = { ...params, limit: opts.pageSize, offset: (opts.page - 1) * opts.pageSize }
+  const queryParams: Record<string, unknown> = {
+    ...params,
+    limit: opts.pageSize,
+    offset: (opts.page - 1) * opts.pageSize,
+  }
+
+  // Float exact name/purl matches to the top while still returning all partial matches via ILIKE.
+  const exactParts: string[] = []
+  if (opts.name) {
+    exactParts.push('p.name ILIKE $(name_exact)')
+    queryParams.name_exact = opts.name
+  }
+  if (opts.purl) {
+    exactParts.push('p.purl ILIKE $(purl_exact)')
+    queryParams.purl_exact = opts.purl
+  }
+  const exactSort =
+    exactParts.length > 0 ? `CASE WHEN ${exactParts.join(' OR ')} THEN 0 ELSE 1 END` : ''
 
   // Laterals needed for WHERE filter conditions — included in both the main query and the COUNT fallback.
   const filterLaterals = `
@@ -522,7 +550,7 @@ export async function listPackagesForApi(
     FROM packages p
     ${laterals}
     ${where}
-    ORDER BY ${sortExpr} ${sortDir} NULLS LAST, p.purl ${sortDir}
+    ORDER BY ${[exactSort, `${sortExpr} ${sortDir} NULLS LAST`, `p.purl ${sortDir}`].filter(Boolean).join(', ')}
     LIMIT $(limit) OFFSET $(offset)
     `,
     queryParams,