fix: handle versioned PURLs and reject unimplemented busFactor1Only filter (CM-1220)

- Strip @Version (and ?qualifiers/#subpath) from PURLs before DB lookup in
  both detail and batch-stewardship endpoints. DB stores versionless PURLs so
  pkg:npm/lodash@4.17.21 now resolves to the same row as pkg:npm/lodash.
  Extracted shared normalizePurl() to packages/purl.ts.
- Return 400 when busFactor1Only=true is passed — filter is accepted by the
  schema but was silently ignored, giving misleading full-result responses.

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

Author: ulemons

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

@@ -7,6 +7,7 @@ import { getPackagesQx } from '@/db/packagesDb'
 import { ok } from '@/utils/api'
 import { validateOrThrow } from '@/utils/validation'
 
+import { normalizePurl } from './purl'
 import type { StewardshipSummary } from './types'
 
 const MAX_PURLS = 100
@@ -26,7 +27,7 @@ const bodySchema = z.object({
 
 export async function batchGetStewardship(req: Request, res: Response): Promise<void> {
   const { purls: rawPurls } = validateOrThrow(bodySchema, req.body)
-  const normalizedPurls = rawPurls.map((p) => p.replace(/@/g, '%40'))
+  const normalizedPurls = rawPurls.map(normalizePurl)
 
   const qx = await getPackagesQx()
   const rows = await getPackagesByStewardshipPurls(qx, normalizedPurls)

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

@@ -8,6 +8,7 @@ import { getPackagesQx } from '@/db/packagesDb'
 import { ok } from '@/utils/api'
 import { validateOrThrow } from '@/utils/validation'
 
+import { normalizePurl } from './purl'
 import type { StewardshipStatus } from './types'
 
 const querySchema = z.object({
@@ -16,7 +17,7 @@ const querySchema = z.object({
     .trim()
     .min(1)
     .refine((v) => v.startsWith('pkg:'), { message: 'purl must start with pkg:' })
-    .transform((v) => v.replace(/@/g, '%40')),
+    .transform(normalizePurl),
 })
 
 export async function getPackage(req: Request, res: Response): Promise<void> {

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

@@ -21,7 +21,9 @@ const querySchema = z.object({
   pageSize: z.coerce.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE),
   ecosystem: z.string().trim().optional(),
   lifecycle: z.enum(lifecycleValues).optional(), // TODO: filter not yet implemented in DAL
-  busFactor1Only: booleanQueryParam, // TODO: filter not yet implemented in DAL
+  busFactor1Only: booleanQueryParam.refine((v) => !v, {
+    message: 'busFactor1Only filter is not yet implemented',
+  }),
   staleOnly: booleanQueryParam,
   unstewardedOnly: booleanQueryParam,
   sortBy: z.enum(['name', 'health', 'impact', 'openVulns']).default('name'),

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

@@ -0,0 +1,20 @@
+/**
+ * Normalize a PURL for lookup against the packages table.
+ *
+ * The DB stores versionless PURLs with npm scope @ encoded as %40.
+ * Clients may send purls with versions (pkg:npm/lodash@4.17.21) and qualifiers.
+ *
+ * Transform order:
+ *   1. strip ?qualifiers and #subpath — not stored in DB
+ *   2. strip @version suffix — DB stores versionless PURLs
+ *   3. encode @ in namespace/scope (e.g. npm @babel → %40babel)
+ *
+ * The version regex matches @ followed by non-/ non-@ chars at end of string.
+ * This is always the version separator, not an npm scope (pkg:npm/@babel/core
+ * has @babel followed by /core, so it never matches the end-of-string pattern).
+ */
+export function normalizePurl(purl: string): string {
+  const withoutQualifiers = purl.replace(/[?#].*$/, '')
+  const withoutVersion = withoutQualifiers.replace(/@[^/@]+$/, '')
+  return withoutVersion.replace(/@/g, '%40')
+}