feat: implement resolveLatestPatch function and associated tests for stable patch resolution

Author: CasperKristiansson

docs/tasks.md

@@ -94,7 +94,7 @@ Use Context7 MCP for up to date documentation.
        Logic: GitHub tags pagination, filter out `a/b/rc/dev`.
        Verify: Unit test with mocked pages returns only stable tags.
 
-7. [ ] **Latest patch resolver for X.Y**
+7. [x] **Latest patch resolver for X.Y**
        Input: `3.13` → output highest `3.13.Z`.
        Verify: Unit test picks max.
 

src/versioning/index.ts

@@ -0,0 +1,2 @@
+export { resolveLatestPatch } from './latest-patch-resolver';
+export type { LatestPatchResult, ResolveLatestPatchOptions } from './latest-patch-resolver';

src/versioning/latest-patch-resolver.ts

@@ -0,0 +1,64 @@
+import semver from 'semver';
+
+import type { FetchStableTagsOptions, StableTag } from '../github';
+import { fetchStableCpythonTags } from '../github';
+
+export interface ResolveLatestPatchOptions extends FetchStableTagsOptions {
+  /// When true, include pre-release versions in the output. Defaults to false.
+  includePrerelease?: boolean;
+  /// Optional override for the tag list, used primarily for testing.
+  tags?: StableTag[];
+}
+
+export interface LatestPatchResult {
+  /// Resolved CPython version, e.g. 3.13.2.
+  version: string;
+  /// Underlying tag name on GitHub.
+  tagName: string;
+  /// Commit SHA associated with the tag.
+  commitSha: string;
+}
+
+function filterByTrack(tags: StableTag[], track: string, includePrerelease: boolean): StableTag[] {
+  return tags.filter((tag) => {
+    const matchesTrack = `${tag.major}.${tag.minor}` === track;
+    if (!matchesTrack) {
+      return false;
+    }
+
+    if (includePrerelease) {
+      return true;
+    }
+
+    return semver.prerelease(tag.version) === null;
+  });
+}
+
+export async function resolveLatestPatch(
+  track: string,
+  options: ResolveLatestPatchOptions = {},
+): Promise<LatestPatchResult | null> {
+  const normalizedTrack = track.trim();
+  if (!/^[0-9]+\.[0-9]+$/.test(normalizedTrack)) {
+    throw new Error(`Track "${track}" must be in the form X.Y`);
+  }
+
+  const { includePrerelease = false, tags, ...fetchOptions } = options;
+
+  const stableTags = tags ?? (await fetchStableCpythonTags(fetchOptions));
+  const candidates = filterByTrack(stableTags, normalizedTrack, includePrerelease);
+
+  if (candidates.length === 0) {
+    return null;
+  }
+
+  const latest = candidates.reduce((acc, current) =>
+    semver.gt(current.version, acc.version) ? current : acc,
+  );
+
+  return {
+    version: latest.version,
+    tagName: latest.tagName,
+    commitSha: latest.commitSha,
+  };
+}

tests/latest-patch-resolver.test.ts

@@ -0,0 +1,113 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { StableTag } from '../src/github';
+import { fetchStableCpythonTags } from '../src/github';
+import { resolveLatestPatch } from '../src/versioning/latest-patch-resolver';
+
+vi.mock('../src/github', async () => {
+  const actual = await vi.importActual<typeof import('../src/github')>('../src/github');
+  return {
+    ...actual,
+    fetchStableCpythonTags: vi.fn(),
+  };
+});
+
+describe('resolveLatestPatch', () => {
+  const mockedFetch = vi.mocked(fetchStableCpythonTags);
+
+  const sampleTags: StableTag[] = [
+    {
+      tagName: 'v3.13.3rc1',
+      version: '3.13.3-rc.1',
+      major: 3,
+      minor: 13,
+      patch: 3,
+      commitSha: 'sha-3-13-3-rc1',
+    },
+    {
+      tagName: 'v3.13.2',
+      version: '3.13.2',
+      major: 3,
+      minor: 13,
+      patch: 2,
+      commitSha: 'sha-3-13-2',
+    },
+    {
+      tagName: 'v3.13.1',
+      version: '3.13.1',
+      major: 3,
+      minor: 13,
+      patch: 1,
+      commitSha: 'sha-3-13-1',
+    },
+    {
+      tagName: 'v3.12.5',
+      version: '3.12.5',
+      major: 3,
+      minor: 12,
+      patch: 5,
+      commitSha: 'sha-3-12-5',
+    },
+  ];
+
+  beforeEach(() => {
+    mockedFetch.mockReset();
+  });
+
+  it('selects the highest stable patch for a track', async () => {
+    const result = await resolveLatestPatch('3.13', { tags: sampleTags });
+
+    expect(result).toEqual({
+      version: '3.13.2',
+      tagName: 'v3.13.2',
+      commitSha: 'sha-3-13-2',
+    });
+  });
+
+  it('returns null when no matching tags are found', async () => {
+    const result = await resolveLatestPatch('3.11', { tags: sampleTags });
+
+    expect(result).toBeNull();
+  });
+
+  it('can include prereleases when requested', async () => {
+    const result = await resolveLatestPatch('3.13', {
+      includePrerelease: true,
+      tags: sampleTags,
+    });
+
+    expect(result).toEqual({
+      version: '3.13.3-rc.1',
+      tagName: 'v3.13.3rc1',
+      commitSha: 'sha-3-13-3-rc1',
+    });
+  });
+
+  it('falls back to fetching when tags are not provided', async () => {
+    mockedFetch.mockResolvedValue(sampleTags);
+
+    const result = await resolveLatestPatch('3.13');
+
+    expect(mockedFetch).toHaveBeenCalled();
+    expect(result).toEqual({
+      version: '3.13.2',
+      tagName: 'v3.13.2',
+      commitSha: 'sha-3-13-2',
+    });
+  });
+
+  it('supports bypassing network by providing tags directly', async () => {
+    const result = await resolveLatestPatch('3.12', { tags: sampleTags });
+
+    expect(mockedFetch).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      version: '3.12.5',
+      tagName: 'v3.12.5',
+      commitSha: 'sha-3-12-5',
+    });
+  });
+
+  it('rejects invalid track values', async () => {
+    await expect(resolveLatestPatch('3')).rejects.toThrow(/Track "3" must be in the form X.Y/);
+  });
+});