feat: oss index groups endpoint

api/src/lib/collections.ts

@@ -4,7 +4,7 @@ import { Type, type Static, type TSchema } from '@sinclair/typebox';
 
 import { nullableEnum, nullableNumber, nullableString } from '../schemas/common.js';
 import { LeaderboardType } from './leaderboards.js';
-import { HealthLabel, ImpactLabel, LifecycleLabel } from './overview.js';
+import { HealthLabel, ImpactLabel, isHealthScore, LifecycleLabel } from './overview.js';
 import { dataEnum, enumGuard, isCount, isString } from './security.js';
 
 // OpenAPI 3.0 has no type 'null', so a nullable object carries `nullable` like the scalars in schemas/common.ts.
@@ -267,15 +267,12 @@ export interface CollectionProjectRow {
 
 const isProjectType = enumGuard(CollectionProjectType);
 const isStatus = enumGuard(ProjectStatus);
-const isHealthLabel = enumGuard(HealthLabel);
 const isLifecycleLabel = enumGuard(LifecycleLabel);
 const isImpactLabel = enumGuard(ImpactLabel);
 const isLeaderboardType = enumGuard(LeaderboardType);
 
 const upTo = (value: unknown, max: number) =>
   value === null || (isCount(value) && (value as number) <= max);
-// The maxima the pipe derives from the covered categories.
-const healthMaxScores = new Set<unknown>([60, 65, 75, 100, null]);
 const isPercentage = (value: unknown) => Number.isFinite(value);
 
 const isAchievement = (value: unknown) =>
@@ -310,12 +307,7 @@ export const isCollectionProjectRow = (row: unknown): row is CollectionProjectRo
     isPercentage(candidate.organizationDependencyPercentage) &&
     Array.isArray(candidate.achievements) &&
     candidate.achievements.every(isAchievement) &&
-    upTo(candidate.healthScoreV2, 100) &&
-    isHealthLabel(candidate.healthLabel) &&
-    healthMaxScores.has(candidate.healthMaxScore) &&
-    (candidate.healthScoreV2 === null ||
-      candidate.healthMaxScore === null ||
-      (candidate.healthScoreV2 as number) <= (candidate.healthMaxScore as number)) &&
+    isHealthScore(candidate.healthScoreV2, candidate.healthLabel, candidate.healthMaxScore) &&
     upTo(candidate.maintainerHealthScoreV2, 40) &&
     upTo(candidate.securitySupplyChainScoreV2, 35) &&
     upTo(candidate.developmentActivityScoreV2, 25) &&

api/src/lib/oss-index.ts

@@ -0,0 +1,151 @@
+// Copyright (c) 2025 The Linux Foundation and each contributor.
+// SPDX-License-Identifier: MIT
+import { Type, type Static } from '@sinclair/typebox';
+
+import { nullableNumber } from '../schemas/common.js';
+import { HealthLabel, isHealthScore } from './overview.js';
+import { dataEnum, inRange, isCount, isString } from './security.js';
+
+// The pipes return positional tuples, so each slot is type-checked before the route names it. Project
+// tuples keep the v1 health score, which the API drops, and end in the nullable v2 health fields.
+export type TopCollectionTuple = [
+  id: string,
+  count: number,
+  name: string,
+  softwareValue: number,
+  avgScore: number,
+];
+
+export type TopProjectTuple = [
+  id: string,
+  count: number,
+  name: string,
+  logo: string,
+  softwareValue: number,
+  avgScore: number,
+  v1HealthScore: number,
+  description: string,
+  status: string,
+  healthScore: number | null,
+  healthLabel: string | null,
+  scaledHealthScore: number | null,
+  healthMaxScore: number | null,
+];
+
+// Counts and the UInt64 software value must be non-negative safe integers. The 0-1 averages use
+// inRange; the dropped v1 score only needs a finite number.
+const isNumber = (value: unknown) => typeof value === 'number' && Number.isFinite(value);
+const isNullableNumber = (value: unknown) => value === null || isNumber(value);
+
+export const isTopCollectionTuple = (value: unknown): value is TopCollectionTuple =>
+  Array.isArray(value) &&
+  value.length === 5 &&
+  isString(value[0]) &&
+  isCount(value[1]) &&
+  isString(value[2]) &&
+  isCount(value[3]) &&
+  inRange(value[4], 1);
+
+export const isTopProjectTuple = (value: unknown): value is TopProjectTuple =>
+  Array.isArray(value) &&
+  value.length >= 13 &&
+  isString(value[0]) &&
+  isCount(value[1]) &&
+  isString(value[2]) &&
+  isString(value[3]) &&
+  isCount(value[4]) &&
+  inRange(value[5], 1) &&
+  isNumber(value[6]) &&
+  isString(value[7]) &&
+  isString(value[8]) &&
+  isHealthScore(value[9], value[10], value[12]) &&
+  isNullableNumber(value[11]);
+
+export const TopCollection = Type.Object(
+  {
+    id: Type.String({ description: 'Identifier of the collection.' }),
+    count: Type.Integer({ minimum: 0, description: 'Contributors in the collection.' }),
+    name: Type.String({ description: 'Display name of the collection.' }),
+    softwareValue: Type.Integer({ minimum: 0, description: 'Software value of the collection.' }),
+    avgScore: Type.Number({
+      minimum: 0,
+      maximum: 1,
+      description: 'Average health score of the collection, from 0 to 1.',
+    }),
+  },
+  { title: 'TopCollection' },
+);
+export type TopCollection = Static<typeof TopCollection>;
+
+export const TopProject = Type.Object(
+  {
+    id: Type.String({ description: 'Identifier of the project.' }),
+    count: Type.Integer({ minimum: 0, description: 'Contributors to the project.' }),
+    name: Type.String({ description: 'Display name of the project.' }),
+    logoUrl: Type.String({ description: 'URL of the project logo.' }),
+    description: Type.String({ description: 'Short description of the project.' }),
+    softwareValue: Type.Integer({ minimum: 0, description: 'Software value of the project.' }),
+    avgScore: Type.Number({
+      minimum: 0,
+      maximum: 1,
+      description: 'Average score of the project, from 0 to 1.',
+    }),
+    healthScore: nullableNumber(
+      'Health score, the sum of the three category scores, from 0 to `healthMaxScore`. Null when fewer than two categories have data.',
+    ),
+    healthLabel: HealthLabel,
+    healthMaxScore: nullableNumber(
+      'Highest score the covered categories allow: 60, 65, 75 or 100. Null when unknown.',
+    ),
+    status: Type.String({ description: 'Lifecycle status of the project, for example `active`.' }),
+  },
+  { title: 'TopProject' },
+);
+export type TopProject = Static<typeof TopProject>;
+
+export const toTopCollection = ([
+  id,
+  count,
+  name,
+  softwareValue,
+  avgScore,
+]: TopCollectionTuple): TopCollection => ({ id, count, name, softwareValue, avgScore });
+
+export const toTopProject = ([
+  id,
+  count,
+  name,
+  logo,
+  softwareValue,
+  avgScore,
+  ,
+  description,
+  status,
+  healthScore,
+  healthLabel,
+  ,
+  healthMaxScore,
+]: TopProjectTuple): TopProject => ({
+  id,
+  count,
+  name,
+  logoUrl: logo,
+  description,
+  softwareValue,
+  avgScore,
+  healthScore,
+  healthLabel: healthLabel as TopProject['healthLabel'],
+  healthMaxScore,
+  status,
+});
+
+export const sortValues = ['totalContributors', 'softwareValue'] as const;
+
+export const sortQuery = Type.Object({
+  sort: Type.Optional(
+    dataEnum(
+      sortValues,
+      'Orders the results, highest first. Defaults to `totalContributors`; `softwareValue` orders by software value.',
+    ),
+  ),
+});

api/src/lib/overview.ts

@@ -3,13 +3,30 @@
 import { Type, type TObject } from '@sinclair/typebox';
 
 import { nullableEnum } from '../schemas/common.js';
+import { enumGuard, isCount } from './security.js';
 
 // Values are exposed as the data holds them, matching the Overview tab.
 export const HealthLabel = nullableEnum(
   ['excellent', 'healthy', 'fair', 'concerning', 'critical'] as const,
   'Band of the health score. Null when the score is null.',
 );
 
+const isHealthLabel = enumGuard(HealthLabel);
+// The maxima the pipes derive from the covered categories.
+const healthMaxScores = new Set<unknown>([60, 65, 75, 100, null]);
+
+// The v2 health score, band and maximum. The band is null exactly when the score is, and repo
+// records carry a score without a maximum.
+export const isHealthScore = (score: unknown, label: unknown, maxScore: unknown) =>
+  score === null
+    ? label === null && maxScore === null
+    : isCount(score) &&
+      (score as number) <= 100 &&
+      label !== null &&
+      isHealthLabel(label) &&
+      healthMaxScores.has(maxScore) &&
+      (maxScore === null || (score as number) <= (maxScore as number));
+
 export const LifecycleLabel = nullableEnum(
   ['active', 'stable', 'declining', 'inert', 'abandoned', 'archived'] as const,
   'Activity state of the project or selected repositories. Null when unknown.',

api/src/versions/v1-alpha/oss-index/groups.ts

@@ -0,0 +1,123 @@
+// Copyright (c) 2025 The Linux Foundation and each contributor.
+// SPDX-License-Identifier: MIT
+import type { FastifyPluginAsyncTypebox } from '@fastify/type-provider-typebox';
+import { Type } from '@sinclair/typebox';
+
+import { fetchPipe } from '../../../clients/tinybird.js';
+import {
+  isTopCollectionTuple,
+  isTopProjectTuple,
+  sortQuery,
+  TopCollection,
+  toTopCollection,
+  TopProject,
+  toTopProject,
+  type TopCollectionTuple,
+  type TopProjectTuple,
+} from '../../../lib/oss-index.js';
+import { inRange, isCount, isString } from '../../../lib/security.js';
+
+const pipePath = '/v0/pipes/category_groups_oss_index.json';
+
+interface Row {
+  id: string;
+  name: string;
+  type: string;
+  slug: string;
+  totalContributors: number;
+  softwareValue: number;
+  avgScore: number;
+  projectCount: number;
+  topCollections: TopCollectionTuple[];
+  topProjects: TopProjectTuple[];
+}
+
+const isRow = (row: Row) =>
+  isString(row.id) &&
+  isString(row.name) &&
+  isString(row.type) &&
+  isString(row.slug) &&
+  isCount(row.totalContributors) &&
+  isCount(row.softwareValue) &&
+  inRange(row.avgScore, 1) &&
+  isCount(row.projectCount) &&
+  Array.isArray(row.topCollections) &&
+  row.topCollections.every(isTopCollectionTuple) &&
+  Array.isArray(row.topProjects) &&
+  row.topProjects.every(isTopProjectTuple);
+
+const Query = Type.Object({
+  type: Type.Optional(
+    Type.String({
+      description: 'Keeps the groups of this type, for example `vertical` or `horizontal`.',
+    }),
+  ),
+  ...sortQuery.properties,
+});
+
+const OssIndexGroup = Type.Object(
+  {
+    id: Type.String({ description: 'Identifier of the category group.' }),
+    name: Type.String({ description: 'Display name of the category group.' }),
+    type: Type.String({
+      description: 'Type of the group, for example `vertical` or `horizontal`.',
+    }),
+    slug: Type.String({ description: 'URL slug of the category group.' }),
+    totalContributors: Type.Integer({ minimum: 0, description: 'Contributors across the group.' }),
+    softwareValue: Type.Integer({ minimum: 0, description: 'Software value of the group.' }),
+    avgScore: Type.Number({
+      minimum: 0,
+      maximum: 1,
+      description: 'Average health score of the group, from 0 to 1.',
+    }),
+    projectCount: Type.Integer({ minimum: 0, description: 'Projects in the group.' }),
+    topCollections: Type.Array(TopCollection, {
+      description: 'Leading collections of the group, ordered by contributors.',
+    }),
+    topProjects: Type.Array(TopProject, {
+      description: 'Leading projects of the group, ordered by contributors.',
+    }),
+  },
+  { title: 'OssIndexGroup' },
+);
+
+const Groups = Type.Object({
+  data: Type.Array(OssIndexGroup, {
+    description: 'Category groups in the requested order. Empty when none match `type`.',
+  }),
+});
+
+const groupRoutes: FastifyPluginAsyncTypebox = async (scope) => {
+  scope.get(
+    '/oss-index/groups',
+    {
+      schema: {
+        tags: ['OSS Index'],
+        summary: 'List the OSS Index category groups',
+        description:
+          'Returns every category group with its totals and its leading collections and projects. ' +
+          '`type` keeps one group type, and `sort` orders the groups by contributors or by software value.',
+        querystring: Query,
+        response: { 200: Groups },
+      },
+    },
+    async (request) => {
+      const { type, sort } = request.query;
+      const rows = await fetchPipe<Row>(
+        request,
+        pipePath,
+        { type: type || undefined, orderBy: sort ?? 'totalContributors' },
+        isRow,
+      );
+      return {
+        data: rows.map((row) => ({
+          ...row,
+          topCollections: row.topCollections.map(toTopCollection),
+          topProjects: row.topProjects.map(toTopProject),
+        })),
+      };
+    },
+  );
+};
+
+export default groupRoutes;

api/tests/collections-projects.test.ts

@@ -229,6 +229,33 @@ describe('response', () => {
     expect(body.data[0]).not.toHaveProperty('healthScoreV2');
   });
 
+  it.each([
+    ['a score with a null label', { healthScoreV2: 77, healthLabel: null }],
+    [
+      'a label with a null score',
+      { healthScoreV2: null, healthLabel: 'healthy', healthMaxScore: null },
+    ],
+    [
+      'a maximum with a null score',
+      { healthScoreV2: null, healthLabel: null, healthMaxScore: 100 },
+    ],
+  ])('answers 503 for %s', async (_label, patch) => {
+    all = [{ ...row(1), ...patch }];
+    const res = await get(route);
+    expect(res.statusCode).toBe(503);
+  });
+
+  it('accepts a repo row with a score and no maximum', async () => {
+    all = [{ ...row(1, 'repo'), healthScoreV2: 61, healthLabel: 'fair', healthMaxScore: null }];
+    const body = await bodyOf();
+    expect(body.data[0]).toMatchObject({
+      type: 'repo',
+      healthScore: 61,
+      healthLabel: 'fair',
+      healthMaxScore: null,
+    });
+  });
+
   it('answers 503 for rows of an unexpected shape', async () => {
     mockFetch.mockImplementation(async () => tinybirdResponse([{ id: 'x' }]));
     const res = await get(route);