feat: oss index groups endpoint

[epipav]

Summary

Adds GET /v1-alpha/oss-index/groups (IN-1414, epic IN-1146). It returns the OSS Index category groups with their top collections and top projects.

• api/src/lib/oss-index.ts holds the shared pieces for the OSS Index routes: guards and mappers that turn the pipe's positional topCollections and topProjects tuples into named objects, their schemas, and the sort query param.
• oss-index/groups.ts reads category_groups_oss_index. type filters the groups and sort (totalContributors or softwareValue, default totalContributors) orders them.
• Project tuples map their logo slot to logoUrl.
• A malformed row or tuple answers 503 upstream_unavailable. An invalid sort answers 400.

Notes

• The tuple columns are non-nullable in the pipe, so a null slot counts as a malformed row.
• The response is { data: [...] }, matching the leaderboards routes.
• The categories and collections endpoints stack on this branch and reuse the shared module.

Tests

• tests/oss-index.test.ts: tuple guards and mappers.
• tests/oss-index-groups.test.ts: response shape, sort and type forwarding, 400 for an invalid sort, 503 for malformed rows, empty list, and the OpenAPI entry.

• main
  • feat: oss index groups endpoint 👈
    • feat: oss index categories endpoint #2351
      • feat: oss index collections endpoint #2352

[cursor]

PR Summary

Low Risk
New read-only v1-alpha endpoint with input validation and upstream row checks; no changes to auth or mutable data paths.

Overview
Adds GET /v1-alpha/oss-index/groups, a read-only OSS Index API that returns category groups (totals plus nested top collections and projects) from the Tinybird category_groups_oss_index pipe. Optional type filters groups; sort (totalContributors default or softwareValue) is passed through as orderBy. Responses use { data: [...] } like other leaderboard-style routes.

Introduces api/src/lib/oss-index.ts for reuse by future OSS Index endpoints: TypeBox schemas, runtime guards for pipe positional tuples, mappers to named objects (project logo → logoUrl), and shared sort query validation. The route validates full rows and nested tuples; invalid sort returns 400 without calling Tinybird; bad upstream shape returns 503 upstream_unavailable.

Vitest coverage exercises tuple guards/mappers and the route (mapping, query forwarding, empty results, OpenAPI tag).

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

[Copilot]

Copilot review overview

🟡 Changes recommended

Numeric guards currently accept counts and scores that violate the documented response contract.

Review effort: Balanced
Findings: 2

Open (2)

• Validate contributor counts and score ranges · New
• Enforce count and avgScore schema constraints · New

What changed in this PR

Adds the OSS Index category groups API with validated tuple mapping and Tinybird integration.

Changes:

• Adds GET /v1-alpha/oss-index/groups.
• Introduces shared OSS Index schemas, guards, and mappers.
• Adds unit and integration coverage.

File	Description
api/​src/​lib/​oss-index.ts	Defines shared tuple guards, mappers, schemas, and sorting.
api/​src/​versions/​v1-alpha/​oss-index/​groups.ts	Implements the groups endpoint.
api/​tests/​oss-index.test.ts	Tests tuple validation and mapping.
api/​tests/​oss-index-groups.test.ts	Tests routing, filtering, errors, and OpenAPI registration.

---

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

[Copilot]

Copilot review overview

🔵 Needs a closer look

Score guards accept values outside documented ranges, allowing malformed upstream data to return 200 instead of 503.

Review effort: Balanced
Findings: None

Resolved since last review (2)

• Enforce count and avgScore schema constraints
• Validate contributor counts and score ranges

Previously missed (1)

In code that hasn't changed since last review

Use “accepts” for grammatical consistency

api/​tests/​oss-index.test.ts:54

Use “accepts” so this test description is grammatically consistent with the surrounding it(...) cases.

[gaspergrom]

LGTM. The tuple guards and slot mapping match the pipe's column order, and the sort and type params line up with what the pipe accepts.

[themarolt]

looks good - one question on projectCount, if the pipe doesn't send it every row fails the guard