Add group_by option to the accessibility scanner

[taarikashenafi]

Tracking issue with context: https://github.com/github/accessibility/issues/10753

Based on feedback from @joseinthearena: with many open scanner issues across a handful of rules (e.g. color-contrast ×11, heading-order ×6) there was no way to consolidate. The gh-cache branch maps each finding's fingerprint → issue URL 1:1, so re-routing N findings to a single "umbrella" issue meant editing gh-cache JSON by hand — brittle, and a typo silently breaks dedup. This adds a group_by input that controls how findings are consolidated into issues: finding (default, current behavior — one issue per violation), rule (one issue per rule), or rule+url (one issue per rule per scanned URL). When grouping, each duplicate occurrence is appended to the single issue as a checklist item rather than spawning a new issue. Because the default is finding, existing workflows behave exactly as before.

Changes

• action.yml (root) — New group_by input (default finding); forwarded to the file step
• .github/actions/file/action.yml — New group_by input declared (default finding)
• file/src/types.d.ts — New GroupBy type ('finding' | 'rule' | 'rule+url')
• file/src/updateFilingsWithNewFindings.ts — The 1:1 dedup behavior lived entirely in getFindingKey; it's now group-aware, computing a coarser key for rule / rule+url so multiple findings collapse into a single filing carrying multiple findings (a shape the pipeline already supported). New findings in the same group are also de-duplicated into one new filing
• file/src/index.ts — Reads and validates group_by (fails fast via setFailed on an invalid value), threads it into updateFilingsWithNewFindings, and passes each filing's full findings array to the open/reopen helpers
• file/src/generateIssueBody.ts / openIssue.ts / reopenIssue.ts — When a filing groups multiple findings, each occurrence is rendered as a checklist item under an Occurrences section, and the issue title reflects the occurrence count; single-finding output is unchanged
• README.md — group_by input documented in the inputs table and getting-started example
• .github/actions/file/README.md — group_by input documented

Test Updates

• Added file/tests/updateFilingsWithNewFindings.test.ts — asserts finding yields one filing per violation (default), rule collapses all occurrences of a rule into a single filing, rule+url yields one filing per rule per URL, new occurrences attach to an existing cached filing instead of opening a new issue, and distinct rules stay separate
• Updated file/tests/openIssue.test.ts, generateIssueBody.test.ts, and reopenIssue.test.ts for the findings-array signature and the Occurrences checklist rendering
• Updated file/tests/dryRun.test.ts to cover grouped dry-run behavior and invalid-group_by handling

Usage

- uses: github/accessibility-scanner@v3
  with:
    urls: |
      https://example.com
    repository: owner/repo
    token: ${{ secrets.GH_TOKEN }}
    cache_key: cached_results.json
    group_by: rule # 'finding' (default, one issue per violation), 'rule' (one per rule), or 'rule+url' (one per rule per scanned URL)

When group_by is not provided, the scanner behaves exactly as before (one issue per finding).

Notes

• kept the existing open_grouped_issues option as-is instead of removing it. It's similar but not the same (it still files every issue and adds a separate tracking issue, while group_by files one combined issue). Removing it would be a breaking change, so I left it for a follow-up — happy to go either way.
• For a grouped issue, the title shows the occurrence count, e.g. … (3 occurrences), since the findings can span multiple URLs.

[Copilot]

Pull request overview

This PR adds a new group_by input to the accessibility scanner so users can consolidate many similar findings into fewer “umbrella” issues (by individual finding, by rule, or by rule+URL), reducing issue spam while keeping the default behavior unchanged.

Changes:

• Introduces a group_by input (default finding) and wires it through the top-level action into the file action.
• Updates filing/dedup logic to support grouping and renders grouped occurrences as a checklist in issue bodies (with occurrence count in the title).
• Adds/updates Vitest coverage for grouping behavior and invalid group_by handling.

Show a summary per file

File	Description
README.md	Documents the new group_by input and its behavior.
action.yml	Declares group_by on the composite action and forwards it to the file step.
.github/actions/file/action.yml	Declares group_by input for the file action.
.github/actions/file/README.md	Documents group_by behavior for the file action.
.github/actions/file/src/types.d.ts	Adds the GroupBy union type.
.github/actions/file/src/updateFilingsWithNewFindings.ts	Makes dedup/grouping key computation group_by-aware and groups new filings by key.
.github/actions/file/src/index.ts	Reads/validates group_by, threads it into filing updates, and passes full findings arrays into open/reopen helpers.
.github/actions/file/src/openIssue.ts	Accepts findings arrays, updates title to include occurrence counts when grouped, and passes arrays to body generation.
.github/actions/file/src/reopenIssue.ts	Accepts findings arrays and regenerates bodies from the full set when reopening.
.github/actions/file/src/generateIssueBody.ts	Adds an Occurrences checklist section when there are multiple findings.
.github/actions/file/tests/updateFilingsWithNewFindings.test.ts	Adds tests covering finding vs rule vs rule+url grouping behavior.
.github/actions/file/tests/openIssue.test.ts	Updates tests for findings-array signature and grouped title behavior.
.github/actions/file/tests/reopenIssue.test.ts	Updates tests for findings-array signature.
.github/actions/file/tests/generateIssueBody.test.ts	Adds coverage for Occurrences rendering behavior.
.github/actions/file/tests/dryRun.test.ts	Adds dry-run coverage for grouping and invalid group_by fail-fast behavior.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 14/15 changed files
• Comments generated: 2