feat: oss index categories endpoint

[epipav]

Summary

Adds GET /v1-alpha/oss-index/categories (IN-1415, epic IN-1146). It returns one category group's details and its categories, each with its top collections and top projects.

• categoryGroupSlug picks the group and is required. sort (totalContributors or softwareValue, default totalContributors) orders the categories.
• The route reads the group from category_groups_list first. An unknown slug answers 404 not_found, and the categories pipe is then skipped.
• Categories come from categories_oss_index, with tuples mapped through the shared module from the groups endpoint.
• A malformed row from either pipe answers 503 upstream_unavailable.

Notes

• This pipe's project tuples carry 8 slots without status, so src/lib/oss-index.ts gains CategoryTopProject and its guard and mapper. The groups route's shape is unchanged.
• The response is { name, slug, type, categories }, a single group with its child list.
• Stacked on feat: oss index groups endpoint #2350.

Tests

• tests/oss-index-categories.test.ts: both pipe calls and their params, 404 for an unknown slug, 400 for a missing slug or an invalid sort, tuple mapping, 503 for malformed rows, empty categories, and the OpenAPI entry.
• tests/oss-index.test.ts: the 8-slot guard and mapper.

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

[cursor]

PR Summary

Medium Risk
New public read API with two Tinybird pipes and a second project tuple shape; behavior is guarded and tested but expands the OSS Index surface area.

Overview
Adds GET /v1-alpha/oss-index/categories, which returns one category group (name, slug, type) and its categories with totals, top collections, and top projects. Callers pass required categoryGroupSlug and optional sort (totalContributors or softwareValue); the handler loads the group from category_groups_list, returns 404 when the slug is missing, then loads categories from categories_oss_index with orderBy forwarded from sort.

Because the categories pipe emits 8-slot project tuples (no status), oss-index.ts introduces CategoryTopProject, isCategoryTopProjectTuple, and toCategoryTopProject, and isTopProjectTuple now validates the first eight slots via the category guard plus the trailing status field. Full 9-slot group responses stay unchanged.

Tests cover mapping, pipe call order and query params, empty lists, 400/404/503 cases, OpenAPI tagging, and the new tuple guard/mapper in oss-index.test.ts.

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

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation matches the described contract and includes comprehensive validation and test coverage.

Review effort: Balanced
Findings: None

What changed in this PR

Adds the /v1-alpha/oss-index/categories endpoint for retrieving a category group and its categories.

Changes:

• Adds validated Tinybird queries and response schemas.
• Adds 8-slot project tuple mapping.
• Adds comprehensive endpoint and mapper tests.

File	Description
api/​src/​versions/​v1-alpha/​oss-index/​categories.ts	Implements the endpoint.
api/​src/​lib/​oss-index.ts	Adds category project guards, schema, and mapper.
api/​tests/​oss-index-categories.test.ts	Tests endpoint behavior and validation.
api/​tests/​oss-index.test.ts	Tests tuple mapping and guards.

---

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

[Copilot]

Copilot review overview

🟡 Changes recommended

Score guards permit values outside the ranges promised by the API contract.

Review effort: Balanced
Findings: 1

Open (1)

• Enforce documented bounds for category, collection, and project scores · New

[gaspergrom]

Looks good to me. The 8-slot guard composes cleanly into the 9-slot one, and the tests cover the 404 short-circuit and the malformed-row 503 paths.

[themarolt]

lgtm