feat: add change_matrix output for CI matrix fan-out support

Author: CasperKristiansson

README.md

@@ -85,6 +85,7 @@ Dockerfile
 | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
 | `new_version`    | Highest CPython patch identified during the run.                                                                           |
 | `files_changed`  | JSON array of files rewritten.                                                                                             |
+| `change_matrix`  | JSON object suitable for `strategy.matrix` fan-out (entries contain `file` and `new_version`).                             |
 | `skipped_reason` | Machine-readable reason when no PR is created (`already_latest`, `multiple_tracks_detected`, `pre_release_guarded`, etc.). |
 
 ---
@@ -147,6 +148,32 @@ with:
 
 When the keywords are provided, the action fetches the GitHub release notes for the resolved tag (or uses the optional `RELEASE_NOTES_SNAPSHOT` offline input) and skips the run unless at least one keyword is present.
 
+### Matrix fan-out for CI
+
+Use the `change_matrix` output to drive follow-up jobs that need to iterate over the files touched by the upgrade:
+
+```yaml
+jobs:
+  bump-python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - id: bump
+        uses: casperkristiansson/python-version-patch-pr@v0
+
+  targeted-tests:
+    needs: bump-python
+    if: ${{ needs.bump-python.outputs.skipped_reason == '' }}
+    strategy:
+      matrix: ${{ fromJSON(needs.bump-python.outputs.change_matrix) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm test -- ${{ matrix.file }}
+```
+
+Each matrix entry exposes `matrix.file` and `matrix.new_version`, enabling you to scope lint or test jobs to the files rewritten during the patch.
+
 ### Renovate/Dependabot coexistence
 
 If Renovate or Dependabot also try to bump CPython patch versions, they will race with this action

action.yml

@@ -37,6 +37,8 @@ outputs:
     description: Resolved CPython patch version (for example 3.13.5).
   files_changed:
     description: JSON array listing files that were updated.
+  change_matrix:
+    description: JSON object suitable for GitHub Actions matrix with changed files and new version.
   skipped_reason:
     description: Machine-readable reason describing why no update was applied.
 runs:

docs/tasks.md

@@ -255,7 +255,7 @@ Use Context7 MCP for up to date documentation.
         Input `security_keywords` to gate bumps by release notes.
         Verify: Mock notes trigger gate.
 
-43. [ ] **Matrix output for CI**
+43. [x] **Matrix output for CI**
         Output JSON of changed files and new version.
         Verify: Example consumes output.
 

src/index.ts

@@ -250,7 +250,9 @@ export async function run(): Promise<void> {
       const rawReleaseNotesSnapshot = loadJsonSnapshot('RELEASE_NOTES_SNAPSHOT');
       if (rawReleaseNotesSnapshot !== undefined) {
         if (typeof rawReleaseNotesSnapshot !== 'object' || rawReleaseNotesSnapshot === null) {
-          throw new Error('RELEASE_NOTES_SNAPSHOT must be a JSON object mapping versions or tags to release note strings.');
+          throw new Error(
+            'RELEASE_NOTES_SNAPSHOT must be a JSON object mapping versions or tags to release note strings.',
+          );
         }
 
         const entries = Object.entries(rawReleaseNotesSnapshot as Record<string, unknown>);
@@ -319,15 +321,27 @@ export async function run(): Promise<void> {
 
     summarizeResult(result);
 
+    const matrixOutput =
+      result.status === 'success'
+        ? {
+            include: result.filesChanged.map((file) => ({
+              file,
+              new_version: result.newVersion,
+            })),
+          }
+        : { include: [] as Array<Record<string, string>> };
+
     if (result.status === 'success') {
       core.setOutput('new_version', result.newVersion);
       core.setOutput('files_changed', JSON.stringify(result.filesChanged));
+      core.setOutput('change_matrix', JSON.stringify(matrixOutput));
       core.setOutput('skipped_reason', '');
       return;
     }
 
     core.setOutput('new_version', result.newVersion ?? '');
     core.setOutput('files_changed', JSON.stringify(result.filesChanged ?? []));
+    core.setOutput('change_matrix', JSON.stringify(matrixOutput));
     core.setOutput('skipped_reason', result.reason);
   } catch (error) {
     if (error instanceof Error) {

tests/index.test.ts

@@ -101,7 +101,12 @@ describe('run', () => {
       'files_changed',
       JSON.stringify(['Dockerfile']),
     );
-    expect(mockSetOutput).toHaveBeenNthCalledWith(3, 'skipped_reason', '');
+    expect(mockSetOutput).toHaveBeenNthCalledWith(
+      3,
+      'change_matrix',
+      JSON.stringify({ include: [{ file: 'Dockerfile', new_version: '3.13.1' }] }),
+    );
+    expect(mockSetOutput).toHaveBeenNthCalledWith(4, 'skipped_reason', '');
     expect(mockWarning).not.toHaveBeenCalled();
   });
 
@@ -161,7 +166,12 @@ describe('run', () => {
 
     expect(mockSetOutput).toHaveBeenNthCalledWith(1, 'new_version', '');
     expect(mockSetOutput).toHaveBeenNthCalledWith(2, 'files_changed', '[]');
-    expect(mockSetOutput).toHaveBeenNthCalledWith(3, 'skipped_reason', 'no_matches_found');
+    expect(mockSetOutput).toHaveBeenNthCalledWith(
+      3,
+      'change_matrix',
+      JSON.stringify({ include: [] }),
+    );
+    expect(mockSetOutput).toHaveBeenNthCalledWith(4, 'skipped_reason', 'no_matches_found');
   });
 
   it('reports failures when unexpected errors occur', async () => {