feat: add context documentation and implement API throttling for pull request handling

Author: CasperKristiansson

docs/context.md

@@ -0,0 +1,101 @@
+# Project Context Overview
+
+This document captures the current state of the **CPython Patch PR Action** repository, the key
+capabilities that have been implemented so far, and any manual configuration that enables the
+nightly workflows to run end-to-end.
+
+---
+
+## Action capabilities
+
+- **Version detection**
+  - GitHub tag fetcher with python.org fallback.
+  - Runner availability validation against `actions/python-versions`.
+  - Pre-release guard (opt-in via `include_prerelease`).
+  - Track alignment + idempotence helpers.
+- **Scanning & rewriting**
+  - Globs for common Python version files.
+  - Regex matchers covering workflows, Dockerfiles, runtime files, `pyproject.toml`, `Pipfile`,
+    Conda `environment.yml`, etc.
+  - Dry-run summaries and targeted patch computation that preserves Docker suffixes.
+- **Git / PR integration**
+  - Branch+commit helper (`chore/bump-python-<track>`).
+  - Pull-request helper with Octokit throttling & duplicate-PR prevention.
+- **Testing & coverage**
+  - Vitest suite with >90% coverage (run `npm run test -- --coverage`).
+  - Git-based integration tests using temporary repositories.
+- **Documentation & metadata**
+  - README with SEO-friendly quick start and advanced configuration.
+  - CHANGELOG (Keep a Changelog format).
+  - SECURITY policy outlining required permissions and endpoints.
+
+---
+
+## GitHub workflows
+
+### `.github/workflows/fixtures.yml`
+Runs the action in **dry-run** mode against local fixtures:
+
+- CI jobs: install, build (`npm run build`), bundle (`npm run bundle`), then `uses: ./` with
+  `dry_run: true`.
+- Fixture matrix (`fixtures/basic`, `fixtures/workflow`) ensures core scanners stay stable.
+- No secrets required (read-only `GITHUB_TOKEN` is sufficient).
+
+### `.github/workflows/nightly.yml`
+Weekly **Monday 03:00 UTC** E2E run against a sandbox repository:
+
+- Builds/bundles this repo.
+- Clones the sandbox repo and executes the action in non-dry-run mode (`dry_run: false`).
+- Writes a summary containing repository, branch, track, automerge flag, files changed,
+  and `skipped_reason`.
+- Requires secrets and optional variables (see next section).
+
+---
+
+## Sandbox configuration
+
+Set the following in **Settings → Secrets and variables → Actions**:
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `SANDBOX_REPO` | Secret | ✅ | Repo slug e.g. `username/python-sandbox`. |
+| `SANDBOX_TOKEN` | Secret | ✅ | PAT with `contents: read/write` and `pull-requests: read/write` scopes for the sandbox repo. |
+| `SANDBOX_TRACK` | Variable | Optional (`3.11` default) | CPython minor to track. |
+| `SANDBOX_DEFAULT_BRANCH` | Variable | Optional (`main` default) | Branch to check out before running. |
+| `SANDBOX_AUTOMERGE` | Variable | Optional (`false` default) | Pass-through to the action’s `automerge` input. |
+
+### Sandbox repo content
+
+Include deliberate CPython version pins (e.g. Dockerfile, `.github/workflows/*.yml`,
+`runtime.txt`, `pyproject.toml`, `Pipfile`, `environment.yml`). A sample prompt for scaffolding
+the sandbox is captured in the main discussion and can be reused to populate example files.
+
+---
+
+## Running locally
+
+```bash
+npm ci
+npm run lint
+npm run test -- --coverage
+npm run bundle
+node dist/index.js   # Placeholder run output
+```
+
+Use `node dist/index.js` to confirm the bundled action executes; currently it only logs
+configuration and emits `skipped_reason: not_implemented`.
+
+---
+
+## Roadmap snapshot (docs/tasks.md)
+
+Tasks 1–31 are marked complete, covering scaffolding, metadata, docs, scanning engine,
+rewrite logic, branch/PR automation, dry-run workflows, sandbox nightly job, and Octokit
+throttling. Task 32 onward focuses on bundling `dist/`, release workflows, CodeQL,
+example consumer repos, and additional guardrails.
+
+Refer to `docs/tasks.md` for the full list of upcoming work.
+
+---
+
+_Last updated: 2025-10-09_

docs/tasks.md

@@ -194,14 +194,14 @@ Use Context7 MCP for up to date documentation.
     Verify: Snapshot outputs stable.
 
 29. [x] **Dry-run CI job on fixtures**
-       Upload `GITHUB_STEP_SUMMARY` artifacts.
-       Verify: Artifacts contain expected diffs.
+        Upload `GITHUB_STEP_SUMMARY` artifacts.
+        Verify: Artifacts contain expected diffs.
 
 30. [x] **E2E sandbox nightly**
         Nightly scheduled PR cycle in a sandbox repo.
         Verify: PR created and closes as expected.
 
-31. [ ] **API throttling**
+31. [x] **API throttling**
         Use Octokit throttling plugin. Retry with backoff.
         Verify: Tests assert retries and clear messages.
 

package-lock.json

@@ -39,6 +39,7 @@
   "homepage": "https://github.com/CasperKristiansson/python-version-patch-pr#readme",
   "dependencies": {
     "@actions/core": "^1.10.1",
+    "@octokit/plugin-throttling": "^11.0.2",
     "@octokit/rest": "^22.0.0",
     "cheerio": "^1.1.2",
     "fast-glob": "^3.3.3",

package.json

@@ -1,4 +1,7 @@
 import { Octokit } from '@octokit/rest';
+import { throttling } from '@octokit/plugin-throttling';
+
+const ThrottledOctokit = Octokit.plugin(throttling);
 
 export interface OctokitClient {
   pulls: {
@@ -52,7 +55,14 @@ export interface PullRequestResult {
 const USER_AGENT = 'python-version-patch-pr/0.1.0';
 
 function createClient(authToken: string): OctokitClient {
-  return new Octokit({ auth: authToken, userAgent: USER_AGENT });
+  return new ThrottledOctokit({
+    auth: authToken,
+    userAgent: USER_AGENT,
+    throttle: {
+      onRateLimit: (_retryAfter, options) => options.request.retryCount === 0,
+      onSecondaryRateLimit: () => true,
+    },
+  });
 }
 
 export async function createOrUpdatePullRequest(

src/git/pull-request.ts

@@ -4,8 +4,20 @@ const octokitModule = vi.hoisted(() => {
   const list = vi.fn();
   const create = vi.fn();
   const update = vi.fn();
-  const Octokit = vi.fn().mockImplementation(() => ({ pulls: { list, create, update } }));
-  return { Octokit, list, create, update };
+  const OctokitBase = vi
+    .fn()
+    .mockImplementation((options: { throttle?: Record<string, unknown> }) => {
+      if (options.throttle && typeof options.throttle.onRateLimit === 'function') {
+        options.throttle.onRateLimit(1, { method: 'GET', url: 'test', request: { retryCount: 0 } });
+      }
+      if (options.throttle && typeof options.throttle.onSecondaryRateLimit === 'function') {
+        options.throttle.onSecondaryRateLimit(1, { method: 'GET', url: 'test' });
+      }
+      return { pulls: { list, create, update } };
+    });
+  const plugin = vi.fn(() => OctokitBase);
+  Object.assign(OctokitBase, { plugin });
+  return { Octokit: OctokitBase, list, create, update, plugin };
 });
 
 vi.mock('@octokit/rest', () => ({
@@ -121,10 +133,16 @@ describe('createOrUpdatePullRequest', () => {
 
     const result = await createOrUpdatePullRequest(baseOptions);
 
-    expect(octokitModule.Octokit).toHaveBeenCalledWith({
-      auth: 'token',
-      userAgent: 'python-version-patch-pr/0.1.0',
-    });
+    expect(octokitModule.Octokit).toHaveBeenCalledWith(
+      expect.objectContaining({
+        auth: 'token',
+        userAgent: 'python-version-patch-pr/0.1.0',
+        throttle: expect.objectContaining({
+          onRateLimit: expect.any(Function),
+          onSecondaryRateLimit: expect.any(Function),
+        }),
+      }),
+    );
     expect(result).toEqual({ action: 'created', number: 5, url: undefined });
   });
 });