feat: implement fetchStableCpythonTags function and associated tests for stable tag retrieval

Author: CasperKristiansson

docs/tasks.md

@@ -89,7 +89,7 @@ Use Context7 MCP for up to date documentation.
 
 ## 2) Core version discovery
 
-6. [ ] **CPython stable tag fetcher**
+6. [x] **CPython stable tag fetcher**
        Libs: `undici`, `semver`.
        Logic: GitHub tags pagination, filter out `a/b/rc/dev`.
        Verify: Unit test with mocked pages returns only stable tags.

eslint.config.mjs

@@ -19,6 +19,9 @@ export default [
       globals: {
         require: 'readonly',
         module: 'readonly',
+        URL: 'readonly',
+        AbortController: 'readonly',
+        AbortSignal: 'readonly',
       },
     },
     plugins: {

package-lock.json

@@ -38,10 +38,13 @@
   },
   "homepage": "https://github.com/CasperKristiansson/python-version-patch-pr#readme",
   "dependencies": {
-    "@actions/core": "^1.10.1"
+    "@actions/core": "^1.10.1",
+    "semver": "^7.7.3",
+    "undici": "^7.16.0"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",
+    "@types/semver": "^7.7.1",
     "@typescript-eslint/eslint-plugin": "^8.46.0",
     "@typescript-eslint/parser": "^8.46.0",
     "@vercel/ncc": "^0.38.4",

package.json

@@ -0,0 +1,135 @@
+import { fetch as undiciFetch, RequestInit, Response } from 'undici';
+import semver, { SemVer } from 'semver';
+
+const CPYTHON_TAGS_URL = 'https://api.github.com/repos/python/cpython/tags';
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface StableTag {
+  tagName: string;
+  version: string;
+  major: number;
+  minor: number;
+  patch: number;
+  commitSha: string;
+}
+
+export interface FetchStableTagsOptions {
+  token?: string;
+  perPage?: number;
+  fetchImpl?: FetchLike;
+  signal?: AbortSignal;
+  userAgent?: string;
+}
+
+const defaultFetch = (globalThis.fetch ?? undiciFetch) as FetchLike;
+
+interface GitHubTag {
+  name?: unknown;
+  commit?: {
+    sha?: unknown;
+  };
+}
+
+function buildHeaders(token?: string, userAgent?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: 'application/vnd.github+json',
+    'User-Agent': userAgent ?? 'python-version-patch-pr/0.1.0',
+  };
+
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+
+  return headers;
+}
+
+function parseStableVersion(tagName: string): SemVer | null {
+  let normalized = tagName.trim();
+  if (normalized.startsWith('refs/tags/')) {
+    normalized = normalized.substring('refs/tags/'.length);
+  }
+  if (normalized.startsWith('v')) {
+    normalized = normalized.substring(1);
+  }
+
+  const parsed = semver.parse(normalized);
+  if (!parsed || parsed.prerelease.length > 0) {
+    return null;
+  }
+
+  return parsed;
+}
+
+export async function fetchStableCpythonTags(
+  options: FetchStableTagsOptions = {},
+): Promise<StableTag[]> {
+  const { token, perPage = 100, fetchImpl = defaultFetch, signal, userAgent } = options;
+
+  if (perPage <= 0) {
+    throw new Error('perPage must be greater than zero.');
+  }
+
+  const results: StableTag[] = [];
+  let page = 1;
+
+  while (true) {
+    const url = new URL(CPYTHON_TAGS_URL);
+    url.searchParams.set('per_page', String(perPage));
+    url.searchParams.set('page', String(page));
+
+    const response = await fetchImpl(url.toString(), {
+      method: 'GET',
+      headers: buildHeaders(token, userAgent),
+      signal,
+    } satisfies RequestInit);
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch CPython tags from GitHub (status ${response.status}).`);
+    }
+
+    const payload = (await response.json()) as unknown;
+
+    if (!Array.isArray(payload)) {
+      throw new Error('Unexpected payload when fetching CPython tags from GitHub.');
+    }
+
+    let addedForPage = 0;
+
+    for (const entry of payload) {
+      const tag = entry as GitHubTag;
+      if (typeof tag.name !== 'string' || typeof tag.commit?.sha !== 'string') {
+        continue;
+      }
+
+      const parsed = parseStableVersion(tag.name);
+      if (!parsed) {
+        continue;
+      }
+
+      results.push({
+        tagName: tag.name,
+        version: parsed.version,
+        major: parsed.major,
+        minor: parsed.minor,
+        patch: parsed.patch,
+        commitSha: tag.commit.sha,
+      });
+      addedForPage += 1;
+    }
+
+    if (payload.length < perPage) {
+      break;
+    }
+
+    // Guard against infinite loops if GitHub returns empty arrays equal to perPage.
+    if (payload.length === 0 || addedForPage === 0) {
+      break;
+    }
+
+    page += 1;
+  }
+
+  results.sort((a, b) => semver.rcompare(a.version, b.version));
+  return results;
+}

src/github/cpython-tags.ts

@@ -0,0 +1,2 @@
+export { fetchStableCpythonTags } from './cpython-tags';
+export type { FetchStableTagsOptions, StableTag } from './cpython-tags';

src/github/index.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Response } from 'undici';
+
+import { fetchStableCpythonTags } from '../src/github/cpython-tags';
+
+const createResponse = (body: unknown, status = 200): Response => {
+  const serialized = typeof body === 'string' ? body : JSON.stringify(body);
+  return new Response(serialized, {
+    status,
+    headers: {
+      'content-type': 'application/json',
+    },
+  });
+};
+
+describe('fetchStableCpythonTags', () => {
+  it('returns only stable tags across paginated responses', async () => {
+    const fetchMock = vi.fn(async (input: string) => {
+      const url = new URL(input);
+      const page = url.searchParams.get('page');
+
+      switch (page) {
+        case '1':
+          return createResponse([
+            { name: 'v3.13.2', commit: { sha: 'sha-3-13-2' } },
+            { name: 'v3.13.2rc1', commit: { sha: 'sha-3-13-2-rc1' } },
+          ]);
+        case '2':
+          return createResponse([
+            { name: 'v3.13.1', commit: { sha: 'sha-3-13-1' } },
+            { name: 'v3.13.1a1', commit: { sha: 'sha-3-13-1-a1' } },
+          ]);
+        case '3':
+          return createResponse([{ name: 'v3.13.0', commit: { sha: 'sha-3-13-0' } }]);
+        default:
+          return createResponse([]);
+      }
+    });
+
+    const tags = await fetchStableCpythonTags({ perPage: 2, fetchImpl: fetchMock });
+
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(tags.map((tag) => tag.version)).toEqual(['3.13.2', '3.13.1', '3.13.0']);
+    expect(tags.map((tag) => tag.commitSha)).toEqual(['sha-3-13-2', 'sha-3-13-1', 'sha-3-13-0']);
+  });
+
+  it('throws when GitHub responds with a non-OK status', async () => {
+    const fetchMock = vi.fn(async () => createResponse({ message: 'oops' }, 500));
+
+    await expect(fetchStableCpythonTags({ fetchImpl: fetchMock })).rejects.toThrow(/status 500/);
+  });
+
+  it('throws when GitHub returns an unexpected payload', async () => {
+    const fetchMock = vi.fn(async () => createResponse({ tag: 'invalid' }));
+
+    await expect(fetchStableCpythonTags({ fetchImpl: fetchMock })).rejects.toThrow(
+      /Unexpected payload/,
+    );
+  });
+});