fix: distinguish WCAG violations from best practices in issue output

Addresses issue #34 - The scanner previously conflated best-practice
recommendations with actual WCAG conformance failures in auto-generated
issue titles and bodies. This led to Copilot filing PRs claiming WCAG
violations when only best-practice rules were triggered.

Changes:
- Add `ruleType` field to Finding type (wcag | best-practice | experimental)
- Extract rule type from axe-core violation tags in findForUrl
- Update issue body generator with clear type badge and description
- Update issue labels: add wcag-violation / best-practice / experimental labels
- Update tests with new label expectations
- Fix ESLint error in test plugin (unused vars)
- Add missing esbuild devDependency
- Include .js files in eslint config

Author: Hardonian

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

@@ -1,6 +1,34 @@
 import type {Finding} from './types.d.js'
 
+/**
+ * Determines if a finding is a WCAG violation or a best practice recommendation.
+ */
+function getRuleTypeLabel(ruleType?: string): { heading: string; badge: string; isWcag: boolean } {
+  if (ruleType === 'best-practice') {
+    return {
+      heading: 'Best Practice Recommendation',
+      badge: '\U0001F4A1 Best Practice',
+      isWcag: false,
+    }
+  }
+  if (ruleType === 'experimental') {
+    return {
+      heading: 'Experimental Rule',
+      badge: '\U0001F9EA Experimental',
+      isWcag: false,
+    }
+  }
+  // Default to WCAG violation
+  return {
+    heading: 'WCAG Violation',
+    badge: '\U0001F6A8 WCAG Violation',
+    isWcag: true,
+  }
+}
+
 export function generateIssueBody(finding: Finding, screenshotRepo: string): string {
+  const ruleTypeLabel = getRuleTypeLabel(finding.ruleType)
+
   const solutionLong = finding.solutionLong
     ?.split('\n')
     .map((line: string) =>
@@ -18,15 +46,27 @@ export function generateIssueBody(finding: Finding, screenshotRepo: string): str
 `
   }
 
+  const ruleTypeSection = `> **Type:** ${ruleTypeLabel.badge}
+>
+> ${ruleTypeLabel.isWcag
+    ? 'This is a **WCAG conformance failure**. Fixing this issue helps meet WCAG 2.1 accessibility requirements.'
+    : 'This is a **best practice recommendation**, not a WCAG conformance failure. Fixing it improves accessibility but is not required for WCAG compliance.'
+  }`
+
   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.
-- [ ] A test SHOULD be added to ensure this specific violation does not regress.
+- [ ] The specific issue reported in this issue is no longer reproducible.
+${ruleTypeLabel.isWcag
+    ? '- [ ] The fix MUST meet WCAG 2.1 guidelines OR the accessibility standards specified by the repository or organization.'
+    : '- [ ] The fix SHOULD follow recognized accessibility best practices to improve the user experience.'
+  }
+- [ ] A test SHOULD be added to ensure this specific issue does not regress.
 - [ ] This PR MUST NOT introduce any new accessibility issues or regressions.`
 
-  const body = `## What
+  const body = `## ${ruleTypeLabel.heading}
 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}.
 
+${ruleTypeSection}
+
 ${screenshotSection ?? ''}
 To fix this, ${finding.solutionShort}.
 ${solutionLong ? `\nSpecifically:\n\n${solutionLong}` : ''}

.github/actions/file/src/openIssue.ts

@@ -22,6 +22,17 @@ export async function openIssue(octokit: Octokit, repoWithOwner: string, finding
   const repo = repoWithOwner.split('/')[1]
 
   const labels = [`${finding.scannerType}-scanning-issue`]
+
+  // Add rule type label to distinguish WCAG violations from best practices
+  if (finding.ruleType === 'best-practice') {
+    labels.push('best-practice')
+  } else if (finding.ruleType === 'experimental') {
+    labels.push('experimental')
+  } else {
+    // Default to wcag for any WCAG-tagged rule
+    labels.push('wcag-violation')
+  }
+
   // Only include a ruleId label when it's defined
   if (finding.ruleId) {
     labels.push(`${finding.scannerType} rule: ${finding.ruleId}`)

.github/actions/file/src/types.d.ts

@@ -1,6 +1,8 @@
 export type Finding = {
   scannerType: string
   ruleId?: string
+  /** Distinguishes WCAG violations from best practices. One of: "wcag", "best-practice", "experimental" */
+  ruleType?: string
   url: string
   html?: string
   problemShort: string

.github/actions/file/tests/generateIssueBody.test.ts

@@ -23,9 +23,10 @@ describe('generateIssueBody', () => {
   it('includes acceptance criteria and omits the Specifically section when solutionLong is missing', () => {
     const body = generateIssueBody(baseFinding, 'github/accessibility-scanner')
 
-    expect(body).toContain('## What')
+    expect(body).toContain('## WCAG Violation')
+    expect(body).toContain('\U0001F6A8 WCAG Violation')
     expect(body).toContain('## Acceptance Criteria')
-    expect(body).toContain('The specific violation reported in this issue is no longer reproducible.')
+    expect(body).toContain('The specific issue reported in this issue is no longer reproducible.')
     expect(body).not.toContain('Specifically:')
   })
 

.github/actions/file/tests/openIssue.test.ts

@@ -60,7 +60,31 @@ describe('openIssue', () => {
     expect(octokit.request).toHaveBeenCalledWith(
       expect.any(String),
       expect.objectContaining({
-        labels: ['axe-scanning-issue', 'axe rule: color-contrast'],
+        labels: ['axe-scanning-issue', 'wcag-violation', 'axe rule: color-contrast'],
+      }),
+    )
+  })
+
+  it('labels best-practice findings correctly', async () => {
+    const octokit = mockOctokit()
+    await openIssue(octokit, 'org/repo', {...baseFinding, ruleType: 'best-practice'})
+
+    expect(octokit.request).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        labels: ['axe-scanning-issue', 'best-practice', 'axe rule: color-contrast'],
+      }),
+    )
+  })
+
+  it('labels experimental findings correctly', async () => {
+    const octokit = mockOctokit()
+    await openIssue(octokit, 'org/repo', {...baseFinding, ruleType: 'experimental'})
+
+    expect(octokit.request).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        labels: ['axe-scanning-issue', 'experimental', 'axe rule: color-contrast'],
       }),
     )
   })

.github/actions/find/src/findForUrl.ts

@@ -79,13 +79,25 @@ async function runAxeScan({
 
   if (rawFindings) {
     for (const violation of rawFindings.violations) {
+      // Determine rule type from axe-core tags
+      const tags = violation.tags ?? []
+      let ruleType: string | undefined
+      if (tags.some((tag: string) => tag.startsWith('wcag'))) {
+        ruleType = 'wcag'
+      } else if (tags.includes('best-practice')) {
+        ruleType = 'best-practice'
+      } else if (tags.includes('experimental')) {
+        ruleType = 'experimental'
+      }
+
       await addFinding({
         scannerType: 'axe',
         url,
         html: violation.nodes[0].html.replace(/'/g, '''),
         problemShort: violation.help.toLowerCase().replace(/'/g, '''),
         problemUrl: violation.helpUrl.replace(/'/g, '''),
         ruleId: violation.id,
+        ruleType,
         solutionShort: violation.description.toLowerCase().replace(/'/g, '''),
         solutionLong: violation.nodes[0].failureSummary?.replace(/'/g, '''),
       })

.github/actions/find/src/types.d.ts

@@ -8,6 +8,8 @@ export type Finding = {
   solutionLong?: string
   screenshotId?: string
   ruleId?: string
+  /** Distinguishes WCAG violations from best practices. One of: "wcag", "best-practice", "experimental" */
+  ruleType?: string
 }
 
 export type Cookie = {

.github/scanner-plugins/test-js-file-plugin-loading/index.js

@@ -1,7 +1,7 @@
 // - this exist as a test to verify that loading plugins
 //   via js files still works and there are no regressions
 
-export default async function TestJsFilePluginLoad({ page, addFinding } = {}) {
+export default async function TestJsFilePluginLoad() {
   console.log('testing plugin load using js file')
 }
 

eslint.config.js

@@ -2,7 +2,7 @@ import tseslint from "typescript-eslint";
 import prettierConfig from "eslint-config-prettier";
 
 export default tseslint.config(...tseslint.configs.recommended, prettierConfig, {
-  files: ["**/*.ts"],
+  files: ["**/*.ts", "**/*.js"],
   rules: {
     "@typescript-eslint/no-unused-vars": [
       "error",