feat: enhance report annotation action pr commenting and per-type limits

- Introduced per-type limits for annotations (error/warning/notice) to better manage output.
- Updated action inputs and outputs in action.yml to reflect new functionality.
- Enhanced error handling for PR comment creation and added comments for skipped annotations.
- Updated dependencies to include @actions/github for improved GitHub API interactions.

Author: villelahdenvuo

README.md

@@ -12,6 +12,9 @@ tests, linters, etc.
 ## Usage Example
 
 ```yml
+permissions:
+  pull-requests: write  # Required for creating comments on skipped annotations
+
 steps:
   - name: Checkout
     id: checkout
@@ -29,7 +32,6 @@ steps:
         junit|reports/junit-generic.xml
         junit-eslint|reports/*-eslint.xml
         junit-jest|reports/junit-jest.xml
-      max-annotations: 20 # Keep the clutter down (50 is max by GitHub)
       ignore: node_modules/**,dist/** # Ignore patterns for the report search (default).
 
    - name: Annotations created
@@ -41,6 +43,34 @@ steps:
          echo "Notices: ${{ steps.annotate.outputs.notices }}"
 ```
 
+## Inputs
+
+| Name              | Description                                                                                                                       | Default                          |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| `reports`         | Reports to annotate: `"format\|glob1, glob2, ..."`<br>For example: `"junit-eslint\|junit/lint.xml"`                               | `["junit\|junit/*.xml"]`         |
+| `ignore`          | Ignore files from report search: `"[glob1, glob2...]"`                                                                            | `['node_modules/**', 'dist/**']` |
+| `max-annotations` | Maximum number of annotations per type (error/warning/notice)                                                                     | `10`                             |
+| `custom-matchers` | Custom matchers to use for parsing reports in JSON format: `{ "matcher-name": ReportMatcher }`<br>See ./src/matchers for examples |                                  |
+| `token`           | GitHub token for creating PR comments when annotations are skipped                                                                | `${{ github.token }}`            |
+
+## Skipped Annotations
+
+When the maximum number of annotations per type is reached, additional
+annotations are not displayed as GitHub annotations to avoid clutter. Instead,
+they are added as a comment on the pull request using GitHub's markdown box
+syntax:
+
+- **Error** boxes for skipped error annotations
+- **Warning** boxes for skipped warning annotations
+- **Note** boxes for skipped notice annotations
+
+This ensures that all issues are still visible to developers without
+overwhelming the GitHub UI.
+
+> [!NOTE] For more information about GitHub Actions annotation limitations, see
+> the
+> [official documentation](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md#limitations).
+
 > [!NOTE]
 >
 > You'll need to have a reasonably modern version of

__tests__/main.test.ts

@@ -1,5 +1,11 @@
 import { jest } from '@jest/globals';
 
+// Type for mutable context in tests
+type MutableContext = Omit<Context, 'payload' | 'repo'> & {
+	payload: Context['payload'] & Record<string, unknown>;
+	repo: Context['repo'];
+};
+
 // In Jest 30 with ESM, directly spying on re-exported ESM bindings of '@actions/core'
 // and assigning implementations (jest.spyOn(core, 'debug').mockImplementation(...))
 // can throw "Cannot assign to read only property" because the ESM named exports are
@@ -9,6 +15,7 @@ import { jest } from '@jest/globals';
 // read-only export objects.
 
 const coreMocks: Record<string, jest.Mock> = {};
+const githubMocks: Record<string, jest.Mock> = {};
 
 await jest.unstable_mockModule('@actions/core', async () => {
 	const original =
@@ -34,12 +41,35 @@ await jest.unstable_mockModule('@actions/core', async () => {
 	} as typeof import('@actions/core');
 });
 
+await jest.unstable_mockModule('@actions/github', async () => {
+	const original =
+		await jest.requireActual<typeof import('@actions/github')>(
+			'@actions/github',
+		);
+	const make = <T extends keyof typeof original>(key: T) => {
+		const fn = jest.fn();
+		githubMocks[key as string] = fn;
+		return fn;
+	};
+	return {
+		...original,
+		getOctokit: make('getOctokit'),
+		context: {
+			payload: {},
+			repo: { owner: 'test-owner', repo: 'test-repo' },
+		},
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	} as any;
+});
+
 // Dynamically import after mocking so the SUT picks up mocked module.
 const main = await import('../src/main');
+const github = await import('@actions/github');
+
+type Context = typeof github.context;
 
 // Mock the GitHub Actions core library
 // Logs & Annotations.
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
 let infoMock: jest.Mock;
 let errorMock: jest.Mock;
 let warningMock: jest.Mock;
@@ -49,10 +79,24 @@ let testInputs: Record<string, string | string[]>;
 // Outputs
 let setFailedMock: jest.Mock;
 let setOutputMock: jest.Mock;
+// GitHub API
+let mockOctokit: {
+	rest: {
+		issues: {
+			createComment: jest.Mock;
+		};
+	};
+};
 
 describe('action', () => {
 	beforeEach(() => {
 		jest.clearAllMocks();
+		// Reset GitHub context
+		(github.context as MutableContext).payload = {};
+		(github.context as MutableContext).repo = {
+			owner: 'test-owner',
+			repo: 'test-repo',
+		};
 		// Simple logging mock (can redirect to stdout for debugging if desired)
 		const logMock = jest.fn();
 		coreMocks.debug.mockImplementation(logMock);
@@ -91,6 +135,15 @@ describe('action', () => {
 		// Outputs
 		setFailedMock = coreMocks.setFailed;
 		setOutputMock = coreMocks.setOutput;
+		// GitHub API
+		mockOctokit = {
+			rest: {
+				issues: {
+					createComment: jest.fn(),
+				},
+			},
+		};
+		githubMocks.getOctokit.mockReturnValue(mockOctokit);
 	});
 
 	it('should parse report correctly', async () => {
@@ -220,26 +273,21 @@ at Tests.Registration.main(Registration.java:202)`,
 		expect(setOutputMock).toHaveBeenCalledWith('total', 3);
 	});
 
-	it('should respect maxAnnotations', async () => {
+	it('should respect per-type annotation limits', async () => {
 		testInputs.reports = ['junit|fixtures/junit-generic.xml'];
-		testInputs['max-annotations'] = '1';
 		await main.run();
-		expect(warningMock).toHaveBeenCalledWith(
-			'Maximum number of annotations reached (1). 2 annotations were not shown.',
-		);
-		expect(setOutputMock).toHaveBeenCalledWith('errors', 1);
+		expect(setOutputMock).toHaveBeenCalledWith('errors', 2);
 		expect(setOutputMock).toHaveBeenCalledWith('warnings', 0);
-		expect(setOutputMock).toHaveBeenCalledWith('notices', 0);
-		expect(setOutputMock).toHaveBeenCalledWith('total', 1);
+		expect(setOutputMock).toHaveBeenCalledWith('notices', 1);
+		expect(setOutputMock).toHaveBeenCalledWith('total', 3);
 	});
 
-	it('should prioritize errors over warnings and notices when maxAnnotations is reached', async () => {
+	it('should show annotations up to per-type limits', async () => {
 		// This test uses junit-eslint fixture which has both errors and warnings
 		testInputs.reports = ['junit-eslint|fixtures/junit-eslint.xml'];
-		testInputs['max-annotations'] = '1';
 		await main.run();
 
-		// Should show the error first, not the warning
+		// Should show the error
 		expect(errorMock).toHaveBeenCalledWith(
 			'["Bucket"] is better written in dot notation.',
 			{
@@ -252,16 +300,16 @@ at Tests.Registration.main(Registration.java:202)`,
 			},
 		);
 
-		// Warning should not be called since we only allow 1 annotation and error has priority
-		expect(warningMock).not.toHaveBeenCalledWith(
+		// Warning should also be called since we allow 10 of each type
+		expect(warningMock).toHaveBeenCalledWith(
 			'Missing JSDoc comment.',
 			expect.any(Object),
 		);
 
 		expect(setOutputMock).toHaveBeenCalledWith('errors', 1);
-		expect(setOutputMock).toHaveBeenCalledWith('warnings', 0);
+		expect(setOutputMock).toHaveBeenCalledWith('warnings', 1);
 		expect(setOutputMock).toHaveBeenCalledWith('notices', 0);
-		expect(setOutputMock).toHaveBeenCalledWith('total', 1);
+		expect(setOutputMock).toHaveBeenCalledWith('total', 2);
 	});
 
 	it('should support jest junit files', async () => {
@@ -288,4 +336,100 @@ at Tests.Registration.main(Registration.java:202)`,
 		expect(setOutputMock).toHaveBeenCalledWith('notices', 0);
 		expect(setOutputMock).toHaveBeenCalledWith('total', 2);
 	});
+
+	it('should handle unsupported matcher format', async () => {
+		testInputs.reports = ['unsupported|fixtures/junit-generic.xml'];
+		testInputs['custom-matchers'] = `{
+			"unsupported": {
+				"format": "json",
+				"item": "//testcase",
+				"message": "text()",
+				"file": "@file"
+			}
+		}`;
+		await expect(main.run()).rejects.toThrow(
+			'Unsupported matcher format in unsupported: json',
+		);
+	});
+
+	it('should handle reports with no items', async () => {
+		testInputs.reports = ['junit|fixtures/empty-report.xml'];
+		await main.run();
+		expect(errorMock).not.toHaveBeenCalled();
+		expect(setOutputMock).toHaveBeenCalledWith('errors', 0);
+		expect(setOutputMock).toHaveBeenCalledWith('warnings', 0);
+		expect(setOutputMock).toHaveBeenCalledWith('notices', 0);
+		expect(setOutputMock).toHaveBeenCalledWith('total', 0);
+	});
+
+	it('should handle yaml config file', async () => {
+		testInputs.configPath = 'fixtures/test-config.yml';
+		testInputs.reports = []; // Will use yaml config
+		await main.run();
+		expect(infoMock).toHaveBeenCalledWith(
+			'Using config file at fixtures/test-config.yml',
+		);
+	});
+
+	it('should handle skipped annotations', async () => {
+		testInputs.reports = ['junit|fixtures/junit-many-errors.xml'];
+		testInputs['max-annotations'] = '2'; // Force skipping
+		await main.run();
+		expect(warningMock).toHaveBeenCalledWith(
+			'Maximum number of annotations per type reached (2). 1 annotations were not shown.',
+		);
+		expect(setOutputMock).toHaveBeenCalledWith('errors', 2);
+		expect(setOutputMock).toHaveBeenCalledWith('warnings', 0);
+		expect(setOutputMock).toHaveBeenCalledWith('notices', 0);
+		expect(setOutputMock).toHaveBeenCalledWith('total', 2);
+	});
+
+	it('should skip PR comment when not on a pull request', async () => {
+		// Mock GitHub context to not be on a PR
+		(github.context as MutableContext).payload = {};
+		testInputs.reports = ['junit|fixtures/junit-many-errors.xml'];
+		testInputs['max-annotations'] = '2';
+		await main.run();
+		expect(infoMock).toHaveBeenCalledWith(
+			'Not running on a pull request, skipping comment creation.',
+		);
+		expect(mockOctokit.rest.issues.createComment).not.toHaveBeenCalled();
+	});
+
+	it('should create PR comment when annotations are skipped', async () => {
+		// Mock GitHub context to be on a PR
+		(github.context as MutableContext).payload = {
+			pull_request: { number: 123 },
+		};
+		testInputs.reports = ['junit|fixtures/junit-many-errors.xml'];
+		testInputs['max-annotations'] = '2';
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		(mockOctokit.rest.issues.createComment as any).mockResolvedValue({});
+		await main.run();
+		expect(mockOctokit.rest.issues.createComment).toHaveBeenCalledWith({
+			owner: 'test-owner',
+			repo: 'test-repo',
+			issue_number: 123,
+			body: expect.stringContaining('## Skipped Annotations'),
+		});
+		expect(infoMock).toHaveBeenCalledWith(
+			'Created PR comment with skipped annotations.',
+		);
+	});
+
+	it('should handle PR comment API failure', async () => {
+		// Mock GitHub context to be on a PR
+		(github.context as MutableContext).payload = {
+			pull_request: { number: 123 },
+		};
+		testInputs.reports = ['junit|fixtures/junit-many-errors.xml'];
+		testInputs['max-annotations'] = '2';
+		const apiError = new Error('API Error');
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		(mockOctokit.rest.issues.createComment as any).mockRejectedValue(apiError);
+		await main.run();
+		expect(errorMock).toHaveBeenCalledWith(
+			`Failed to create PR comment: ${apiError}`,
+		);
+	});
 });

action.yml

@@ -11,19 +11,25 @@ inputs:
     description: |-
       Reports to annotate: "format|glob1, glob2, ..."
       For example: "junit-eslint|junit/lint.xml"
-      Default: ["junit|junit/*.xml"]
+    default: |
+      junit|junit/*.xml
   ignore:
     description: |-
       Ignore files from report search: "[glob1, glob2...]"
-      Default: ['node_modules', 'dist']
+    default: |
+      node_modules/**
+      dist/**
   max-annotations:
     description: |-
-      Maximum number of annotations to create
-      Default: 50
+      Maximum number of annotations per type (error/warning/notice)
+    default: '10'
   custom-matchers:
     description: |-
       Custom matchers to use for parsing reports in JSON format: { "matcher-name": ReportMatcher }
       See ./src/matchers for examples
+  token:
+    description: GitHub token for creating PR comments
+    default: ${{ github.token }}
 
 outputs:
   errors:
@@ -33,7 +39,7 @@ outputs:
   notices:
     description: Notices found in reports
   total:
-    description: Total annotations created (limited by max-annotations)
+    description: Total annotations created
 
 runs:
   using: node24