feat: collection popularity routes

[epipav]

Summary

Serves the 6 popularity widgets for a collection under /v1-alpha/collections/{slug}/popularity/* (IN-1413, epic IN-1146): stars, forks, mailing-lists-messages, packages, package-metrics and search-queries. It is stacked on #2348 and adopts widgetRoutes, so each collection variant reuses the project route handler and passes collectionSlug to the pipe.

• Stars, forks and mailing-lists-messages hand the scope target to fetchActivityCounts.
• New description rules make the collection docs match what the pipes return for a collection: search volume and package peaks are taken per member project and added up.
• The project routes' behaviour and OpenAPI output are unchanged.

Notes

• Pipe support for collectionSlug is taken from the Nuxt app: every popularity widget with an API route is available in collection scope and sends collectionSlug to the same pipes. No route is left out.
• Collection packages takes only search, so the shared suite skips the bad-query case for it.

Tests

• tests/project-routes.test.ts: popularity joins the pinned collection groups, so the shared collection suite covers all 6 routes.
• tests/widget-scope.test.ts: cases for each new description rule.

• main
  • feat: collection contributors routes #2347
    • feat: collection development routes #2348
      • feat: collection popularity routes 👈

[cursor]

PR Summary

Medium Risk
New public collection endpoints and Tinybird collectionSlug wiring expand API surface; aggregation semantics for search and package metrics differ from single-project routes and must match pipes.

Overview
Adds collection-scoped popularity APIs at /v1-alpha/collections/{slug}/popularity/* for stars, forks, mailing-list messages, packages, package-metrics, and search-queries by refactoring all six handlers to widgetRoutes, so each shares one handler with the existing project route and passes collectionSlug (via withTarget) instead of project bucket lookup.

collectionText / collectionSchema gain rules so collection OpenAPI docs describe aggregation correctly: search volume and package peak metrics are documented as summed across member projects, with project-only phrases (unknown project, repos, etc.) stripped or rewritten.

Tests extend the shared collection route suite to popularity, skip invalid-query checks when a route has no granularity/startDate (e.g. packages list), and add widget-scope cases for the new description rules. Project route behavior and schemas are unchanged aside from registration through the helper.

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

[Copilot]

Copilot review overview

🟡 Changes recommended

The updated route test passes a possibly undefined value where strict TypeScript requires a query record.

Review effort: Balanced
Findings: 1

Open (1)

• Handle undefined bad before passing to collectionUrl · New

What changed in this PR

Adds collection-scoped /v1-alpha popularity endpoints by reusing existing project handlers.

Changes:

• Adds collection variants for six popularity widgets.
• Rewrites collection-specific OpenAPI descriptions.
• Expands shared route and description tests.

File	Description
api/​src/​lib/​widget-scope.ts	Adds collection description transformations.
api/​src/​versions/​v1-alpha/​popularity/​stars.ts	Adds collection-scoped stars route.
api/​src/​versions/​v1-alpha/​popularity/​forks.ts	Adds collection-scoped forks route.
api/​src/​versions/​v1-alpha/​popularity/​mailing-lists-messages.ts	Adds collection-scoped message route.
api/​src/​versions/​v1-alpha/​popularity/​packages.ts	Adds collection-scoped packages route.
api/​src/​versions/​v1-alpha/​popularity/​package-metrics.ts	Adds collection-scoped package metrics route.
api/​src/​versions/​v1-alpha/​popularity/​search-queries.ts	Adds collection-scoped search route.
api/​tests/​project-routes.test.ts	Extends shared collection route coverage.
api/​tests/​widget-scope.test.ts	Tests new description rewrites.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.