new release (v3.3.0)

.github/actions/auth/package.json

@@ -17,7 +17,7 @@
     "playwright": "^1.60.0"
   },
   "devDependencies": {
-    "@types/node": "^25.7.0",
+    "@types/node": "^25.9.0",
     "typescript": "^6.0.3"
   }
 }

.github/actions/file/README.md

@@ -11,6 +11,7 @@ Files GitHub issues to track potential accessibility gaps.
 **Required** Path to a JSON file containing the list of potential accessibility gaps. The path can be absolute or relative to the working directory (which defaults to `GITHUB_WORKSPACE`). For example: `findings.json`.
 
 The file should contain a JSON array of finding objects. For example:
+
 ```json
 []
 ```
@@ -28,27 +29,49 @@ The file should contain a JSON array of finding objects. For example:
 **Optional** Path to a JSON file containing cached filings from previous runs. The path can be absolute or relative to the working directory (which defaults to `GITHUB_WORKSPACE`). Without this, duplicate issues may be filed. For example: `cached-filings.json`.
 
 The file should contain a JSON array of filing objects. For example:
+
 ```json
 [
   {
     "findings": [],
-    "issue": {"id":1,"nodeId":"SXNzdWU6MQ==","url":"https://github.com/github/docs/issues/123","title":"Accessibility issue: 1"}
+    "issue": {
+      "id": 1,
+      "nodeId": "SXNzdWU6MQ==",
+      "url": "https://github.com/github/docs/issues/123",
+      "title": "Accessibility issue: 1"
+    }
   }
 ]
 ```
 
+#### `group_by`
+
+**Optional** How to consolidate findings into issues. One of:
+
+- `finding` (default): one issue per individual violation — current behavior, unchanged.
+- `rule`: one issue per rule (`ruleId`/`scannerType`), aggregating every occurrence across all scanned URLs.
+- `rule+url`: one issue per rule per scanned URL.
+
+When grouping, each additional occurrence is appended to the single "umbrella" issue body as a checklist item under an **Occurrences** section rather than spawning a new issue. This is the preferred mechanism for consolidating issues over `open_grouped_issues`.
+
 ### Outputs
 
 #### `filings_file`
 
 Absolute path to a JSON file containing the list of issues filed (and their associated finding(s)). The action writes this file to a temporary directory and returns the absolute path. For example: `$RUNNER_TEMP/filings-<uuid>.json`.
 
 The file will contain a JSON array of filing objects. For example:
+
 ```json
 [
   {
     "findings": [],
-    "issue": {"id":1,"nodeId":"SXNzdWU6MQ==","url":"https://github.com/github/docs/issues/123","title":"Accessibility issue: 1"}
+    "issue": {
+      "id": 1,
+      "nodeId": "SXNzdWU6MQ==",
+      "url": "https://github.com/github/docs/issues/123",
+      "title": "Accessibility issue: 1"
+    }
   }
 ]
 ```

.github/actions/file/action.yml

@@ -1,38 +1,54 @@
-name: "File"
-description: "Files GitHub issues to track potential accessibility gaps."
+name: 'File'
+description: 'Files GitHub issues to track potential accessibility gaps.'
 
 inputs:
   findings_file:
-    description: "Path to a JSON file containing the list of potential accessibility gaps"
+    description: 'Path to a JSON file containing the list of potential accessibility gaps'
     required: true
   repository:
-    description: "Repository (with owner) to file issues in"
+    description: 'Repository (with owner) to file issues in'
     required: true
   token:
     description: "Token with fine-grained permission 'issues: write'"
     required: true
   base_url:
-    description: "Optional base URL to pass into Octokit for the GitHub API (for example, `https://YOUR_HOSTNAME/api/v3` for GitHub Enterprise Server)"
+    description: 'Optional base URL to pass into Octokit for the GitHub API (for example, `https://YOUR_HOSTNAME/api/v3` for GitHub Enterprise Server)'
     required: false
   cached_filings_file:
-    description: "Path to a JSON file containing cached filings from previous runs. Without this, duplicate issues may be filed."
+    description: 'Path to a JSON file containing cached filings from previous runs. Without this, duplicate issues may be filed.'
     required: false
   screenshot_repository:
     description: "Repository (with owner) where screenshots are stored on the gh-cache branch. Defaults to the 'repository' input if not set. Required if issues are open in a different repo to construct proper screenshot URLs."
     required: false
   open_grouped_issues:
     description: "In the 'file' step, also open grouped issues which link to all issues with the same root cause"
     required: false
-    default: "false"
+    default: 'false'
+  group_by:
+    description: "How to group findings into issues: 'finding' (one issue per violation, default), 'rule' (one issue per rule), or 'rule+url' (one issue per rule per scanned URL)."
+    required: false
+    default: 'finding'
+  dry_run:
+    description: 'When true, log the issues that would be filed without opening, closing, or reopening any issues.'
+    required: false
+    default: 'false'
+  file_best_practice_issues:
+    description: 'File issues for best-practice findings (accessibility recommendations that are not hard WCAG failures). Disabling only suppresses new issues; existing ones are left untouched.'
+    required: false
+    default: 'true'
+  file_experimental_issues:
+    description: 'File issues for experimental findings (checks that are not yet stable). Disabling only suppresses new issues; existing ones are left untouched.'
+    required: false
+    default: 'true'
 
 outputs:
   filings_file:
-    description: "Path to a JSON file containing the list of issues filed (and their associated finding(s))"
+    description: 'Path to a JSON file containing the list of issues filed (and their associated finding(s))'
 
 runs:
-  using: "node24"
-  main: "bootstrap.js"
+  using: 'node24'
+  main: 'bootstrap.js'
 
 branding:
-  icon: "compass"
-  color: "blue"
+  icon: 'compass'
+  color: 'blue'

.github/actions/file/package.json

@@ -18,7 +18,7 @@
     "@octokit/plugin-throttling": "^11.0.3"
   },
   "devDependencies": {
-    "@types/node": "^25.7.0",
+    "@types/node": "^25.9.0",
     "typescript": "^6.0.3"
   }
 }

.github/actions/file/src/generateIssueBody.ts

@@ -1,6 +1,9 @@
 import type {Finding} from './types.d.js'
 
-export function generateIssueBody(finding: Finding, screenshotRepo: string): string {
+export function generateIssueBody(occurrences: Finding | Finding[], screenshotRepo: string): string {
+  const findings = Array.isArray(occurrences) ? occurrences : [occurrences]
+  const finding = findings[0]
+
   const solutionLong = finding.solutionLong
     ?.split('\n')
     .map((line: string) =>
@@ -18,21 +21,64 @@ export function generateIssueBody(finding: Finding, screenshotRepo: string): str
 `
   }
 
+  let occurrencesSection = ''
+  if (findings.length > 1) {
+    const items = findings.map(f => `- [ ] ${f.html ? `\`${f.html}\` on ${f.url}` : f.url}`).join('\n')
+    occurrencesSection = `
+## ${findings.length} Other Occurrences:
+
+${items}
+`
+  }
+
+  const categoryNotice =
+    finding.category && finding.category !== 'wcag'
+      ? `> [!NOTE]\n> This is ${
+          finding.category === 'experimental' ? 'an experimental check' : 'a best-practice recommendation'
+        }, not a definite WCAG failure.\n\n`
+      : ''
+
+  const standardsLine =
+    finding.category && finding.category !== 'wcag'
+      ? '- [ ] The fix MUST meet the accessibility standards specified by the repository or organization (WCAG 2.2 if applicable).'
+      : '- [ ] The fix MUST meet WCAG 2.2 guidelines OR the accessibility standards specified by the repository or organization.'
+
   const acceptanceCriteria = `## Acceptance Criteria
 - [ ] The specific violation reported in this issue is no longer reproducible.
-- [ ] The fix MUST meet WCAG 2.1 guidelines OR the accessibility standards specified by the repository or organization.
+${standardsLine}
 - [ ] A test SHOULD be added to ensure this specific violation does not regress.
 - [ ] This PR MUST NOT introduce any new accessibility issues or regressions.`
 
-  const body = `## What
-An accessibility scan ${finding.html ? `flagged the element \`${finding.html}\`` : `found an issue on ${finding.url}`} because ${finding.problemShort}. Learn more about why this was flagged by visiting ${finding.problemUrl}.
+  const body = `${categoryNotice}## What
+${describeFinding(finding)}
 
 ${screenshotSection ?? ''}
 To fix this, ${finding.solutionShort}.
 ${solutionLong ? `\nSpecifically:\n\n${solutionLong}` : ''}
-
+${occurrencesSection}
 ${acceptanceCriteria}
 `
 
   return body
 }
+
+function describeFinding(finding: Finding): string {
+  const reason = `because ${finding.problemShort}. Learn more about why this was flagged by visiting ${finding.problemUrl}.`
+
+  // Axe carries every failing element; list them all, not just the first.
+  if (finding.nodes && finding.nodes.length > 0) {
+    const count = finding.nodes.length
+    const subject = count === 1 ? 'an element' : `${count} elements`
+    const elementList = finding.nodes
+      .map(node => `- \`${node.html}\`${node.target ? ` (selector: \`${node.target}\`)` : ''}`)
+      .join('\n')
+    const heading = count === 1 ? 'The following element needs' : 'The following elements need'
+    return `An accessibility scan flagged ${subject} on ${finding.url} ${reason}\n\n${heading} attention:\n\n${elementList}`
+  }
+
+  if (finding.html) {
+    return `An accessibility scan flagged the element \`${finding.html}\` ${reason}`
+  }
+
+  return `An accessibility scan found an issue on ${finding.url} ${reason}`
+}

.github/actions/file/src/groupBy.ts

@@ -0,0 +1,7 @@
+export const GROUP_BY_VALUES = ['finding', 'rule', 'rule+url'] as const
+
+export type GroupBy = (typeof GROUP_BY_VALUES)[number]
+
+export function isGroupBy(value: string): value is GroupBy {
+  return (GROUP_BY_VALUES as readonly string[]).includes(value)
+}