feat: implement action execution logic and add tests for failure modes

Author: CasperKristiansson

docs/tasks.md

@@ -225,7 +225,7 @@ Use Context7 MCP for up to date documentation.
 
 ## 9) Quality and guardrails
 
-36. [ ] **Failure modes and messages**
+36. [x] **Failure modes and messages**
         Emit `multiple_tracks_detected`, `runners_missing`, `no_matches_found`, `already_latest`, `pr_exists`, `pr_creation_failed`.
         Verify: Tests assert outputs and logs.
 

src/action-execution.ts

@@ -0,0 +1,261 @@
+import {
+  determineSingleTrack,
+  type TrackAlignmentResult,
+  type VersionMatch,
+  scanForPythonVersions,
+} from './scanning';
+import {
+  enforcePreReleaseGuard,
+  fetchLatestFromPythonOrg,
+  fetchRunnerAvailability,
+  resolveLatestPatch,
+  type LatestPatchResult,
+} from './versioning';
+import { createOrUpdatePullRequest, findExistingPullRequest, type PullRequestResult } from './git';
+
+export type SkipReason =
+  | 'no_matches_found'
+  | 'multiple_tracks_detected'
+  | 'runners_missing'
+  | 'already_latest'
+  | 'pr_exists'
+  | 'pr_creation_failed'
+  | 'pre_release_guarded';
+
+export interface ExecuteOptions {
+  workspace: string;
+  track: string;
+  includePrerelease: boolean;
+  paths: string[];
+  dryRun: boolean;
+  automerge: boolean;
+  githubToken?: string;
+  repository?: { owner: string; repo: string } | null;
+  defaultBranch?: string;
+  allowPrCreation?: boolean;
+}
+
+export interface ExecuteDependencies {
+  scanForPythonVersions: typeof scanForPythonVersions;
+  determineSingleTrack: typeof determineSingleTrack;
+  resolveLatestPatch: typeof resolveLatestPatch;
+  fetchLatestFromPythonOrg: typeof fetchLatestFromPythonOrg;
+  enforcePreReleaseGuard: typeof enforcePreReleaseGuard;
+  fetchRunnerAvailability: typeof fetchRunnerAvailability;
+  findExistingPullRequest?: typeof findExistingPullRequest;
+  createOrUpdatePullRequest?: typeof createOrUpdatePullRequest;
+}
+
+export interface SkipResult {
+  status: 'skip';
+  reason: SkipReason;
+  newVersion?: string | null;
+  filesChanged?: string[];
+  details?: Record<string, unknown>;
+}
+
+export interface SuccessResult {
+  status: 'success';
+  newVersion: string;
+  filesChanged: string[];
+  dryRun: boolean;
+  pullRequest?: PullRequestResult;
+}
+
+export type ExecuteResult = SkipResult | SuccessResult;
+
+const DEFAULT_IGNORES = ['**/node_modules/**', '**/.git/**', '**/dist/**'];
+
+function uniqueFiles(matches: VersionMatch[]): string[] {
+  return Array.from(new Set(matches.map((match) => match.file))).sort();
+}
+
+function determineMissingRunners(
+  availability: Awaited<ReturnType<typeof fetchRunnerAvailability>>,
+): string[] {
+  if (!availability) {
+    return ['linux', 'mac', 'win'];
+  }
+
+  return (Object.entries(availability.availableOn) as Array<[string, boolean]>)
+    .filter(([, isAvailable]) => !isAvailable)
+    .map(([name]) => name)
+    .sort();
+}
+
+function selectLatestVersion(
+  track: string,
+  latestPatch: LatestPatchResult | null,
+  fallback: Awaited<ReturnType<typeof fetchLatestFromPythonOrg>>,
+): string {
+  if (latestPatch) {
+    return latestPatch.version;
+  }
+
+  if (fallback) {
+    return fallback.version;
+  }
+
+  throw new Error(`Unable to resolve latest patch version for track "${track}".`);
+}
+
+export async function executeAction(
+  options: ExecuteOptions,
+  dependencies: ExecuteDependencies,
+): Promise<ExecuteResult> {
+  const {
+    workspace,
+    track,
+    includePrerelease,
+    paths,
+    dryRun,
+    githubToken,
+    repository,
+    defaultBranch = 'main',
+    allowPrCreation = false,
+  } = options;
+
+  const scanResult = await dependencies.scanForPythonVersions({
+    root: workspace,
+    patterns: paths,
+    ignore: DEFAULT_IGNORES,
+    followSymbolicLinks: false,
+  });
+
+  if (scanResult.matches.length === 0) {
+    return {
+      status: 'skip',
+      reason: 'no_matches_found',
+      filesChanged: [],
+    } satisfies SkipResult;
+  }
+
+  const alignment: TrackAlignmentResult = dependencies.determineSingleTrack(scanResult.matches);
+  if (alignment.conflicts.length > 0) {
+    return {
+      status: 'skip',
+      reason: 'multiple_tracks_detected',
+      details: { conflicts: alignment.conflicts },
+    } satisfies SkipResult;
+  }
+
+  const latestPatch = await dependencies.resolveLatestPatch(track, {
+    includePrerelease,
+    token: githubToken,
+  });
+  const fallback = await dependencies.fetchLatestFromPythonOrg({ track });
+  const latestVersion = selectLatestVersion(track, latestPatch, fallback);
+
+  const guard = dependencies.enforcePreReleaseGuard(includePrerelease, latestVersion);
+  if (!guard.allowed) {
+    return {
+      status: 'skip',
+      reason: guard.reason ?? 'pre_release_guarded',
+      newVersion: latestVersion,
+    } satisfies SkipResult;
+  }
+
+  const availability = await dependencies.fetchRunnerAvailability(latestVersion);
+  const missingRunners = determineMissingRunners(availability);
+  if (missingRunners.length > 0) {
+    return {
+      status: 'skip',
+      reason: 'runners_missing',
+      newVersion: latestVersion,
+      details: { missing: missingRunners },
+      filesChanged: uniqueFiles(scanResult.matches),
+    } satisfies SkipResult;
+  }
+
+  const matchesNeedingUpdate = scanResult.matches.filter(
+    (match) => match.matched !== latestVersion,
+  );
+
+  if (matchesNeedingUpdate.length === 0) {
+    return {
+      status: 'skip',
+      reason: 'already_latest',
+      newVersion: latestVersion,
+      filesChanged: [],
+    } satisfies SkipResult;
+  }
+
+  const filesChanged = uniqueFiles(matchesNeedingUpdate);
+
+  if (dryRun || !allowPrCreation) {
+    return {
+      status: 'success',
+      newVersion: latestVersion,
+      filesChanged,
+      dryRun: true,
+    } satisfies SuccessResult;
+  }
+
+  if (!githubToken || !repository) {
+    return {
+      status: 'success',
+      newVersion: latestVersion,
+      filesChanged,
+      dryRun: false,
+    } satisfies SuccessResult;
+  }
+
+  const branchName = `chore/bump-python-${track}`;
+
+  if (dependencies.findExistingPullRequest) {
+    const existing = await dependencies.findExistingPullRequest({
+      owner: repository.owner,
+      repo: repository.repo,
+      head: branchName,
+      authToken: githubToken,
+    });
+
+    if (existing) {
+      return {
+        status: 'skip',
+        reason: 'pr_exists',
+        newVersion: latestVersion,
+        filesChanged,
+        details: existing,
+      } satisfies SkipResult;
+    }
+  }
+
+  if (!dependencies.createOrUpdatePullRequest) {
+    return {
+      status: 'success',
+      newVersion: latestVersion,
+      filesChanged,
+      dryRun: false,
+    } satisfies SuccessResult;
+  }
+
+  try {
+    const pullRequest = await dependencies.createOrUpdatePullRequest({
+      owner: repository.owner,
+      repo: repository.repo,
+      head: branchName,
+      base: defaultBranch,
+      title: `chore: bump python ${track} to ${latestVersion}`,
+      body: `Update CPython ${track} pins to ${latestVersion}.`,
+      authToken: githubToken,
+    });
+
+    return {
+      status: 'success',
+      newVersion: latestVersion,
+      filesChanged,
+      dryRun: false,
+      pullRequest,
+    } satisfies SuccessResult;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      status: 'skip',
+      reason: 'pr_creation_failed',
+      newVersion: latestVersion,
+      filesChanged,
+      details: { message },
+    } satisfies SkipResult;
+  }
+}

src/git/index.ts

@@ -1,5 +1,5 @@
 export { createBranchAndCommit } from './branch';
 export type { BranchCommitOptions, BranchCommitResult } from './branch';
 
-export { createOrUpdatePullRequest } from './pull-request';
+export { createOrUpdatePullRequest, findExistingPullRequest } from './pull-request';
 export type { PullRequestOptions, PullRequestResult, OctokitClient } from './pull-request';

src/git/pull-request.ts

@@ -108,3 +108,29 @@ export async function createOrUpdatePullRequest(
 
   return { action: 'created', number: response.data.number, url: response.data.html_url };
 }
+
+export async function findExistingPullRequest(options: {
+  owner: string;
+  repo: string;
+  head: string;
+  authToken: string;
+  client?: OctokitClient;
+}): Promise<{ number: number; url?: string } | null> {
+  const { owner, repo, head, authToken, client } = options;
+  const octokit = client ?? createClient(authToken);
+
+  const { data } = await octokit.pulls.list({
+    owner,
+    repo,
+    head: `${owner}:${head}`,
+    state: 'open',
+    per_page: 1,
+  });
+
+  if (data.length === 0) {
+    return null;
+  }
+
+  const pull = data[0];
+  return { number: pull.number, url: pull.html_url };
+}