Add plugins (#133)

## New Context
After validating the plugins idea, we have decided to move forward with
this approach.

This PR introduces the idea of 'Plugins' to the scanner. A plugin (as
described in the [PLUGINS
doc](https://github.com/github/accessibility-scanner/pull/133/changes#diff-8286e7365a5a84367dd51372b6b4565edb1146925ff6f5fc126a9d7d39fc94a9))
is a custom script that performs an accessibility test/scan. It allows
teams to specify their own tests in their own repos to surface
accessibility issues. These plugins can be used in combination with
existing scans. For example, a team can perform interactions on a page
before the axe scan runs.

There will also be built-in scans that will ship with the scanner.


## Original Context

This is a very minimal proof of concept around the idea of using plugins
to make additional scans and tests modular. Looking for feedback on
general approach, pros/cons, etc...

this currently works with the plugins defined in the scanner repo. I'm
still working on making this work with plugins defined in the workflow
repo (the repo that uses the action). There might be some issues with
using absolute paths with the dynamic import() feature - but i'm still
testing.

I've taken @lindseywild’s reflow test and added it as a plugin for
testing. the idea is each plugin lives under a new folder under the
scanner-plugins folder (which lives under .github like actions). and
each plugin has a primary index.js file, which we will use to interface
with the plugin.

all of this is just how I've built it as a proposal - we can tweak
naming/folder-structure, etc... if we feel something else makes more
sense

Author: abdulahmad307

.github/actions/file/src/index.ts

@@ -100,7 +100,7 @@ export default async function () {
         )
       }
     } catch (error) {
-      core.setFailed(`Failed on filing: ${filing}\n${error}`)
+      core.setFailed(`Failed on filing: ${JSON.stringify(filing, null, 2)}\n${error}`)
       process.exit(1)
     }
   }

.github/actions/find/README.md

@@ -31,6 +31,14 @@ configuration option.
 [`colorScheme`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-color-scheme)
 configuration option.
 
+#### `include_screenshots`
+
+**Optional** Bool - whether to capture screenshots of scanned pages and include links to them in the issue
+
+#### `scans`
+
+**Optional** Stringified JSON array of scans (string) to perform. If not provided, only Axe will be performed.
+
 ### Outputs
 
 #### `findings`

.github/actions/find/action.yml

@@ -1,33 +1,36 @@
-name: "Find"
-description: "Finds potential accessibility gaps."
+name: 'Find'
+description: 'Finds potential accessibility gaps.'
 
 inputs:
   urls:
-    description: "Newline-delimited list of URLs to check for accessibility issues"
+    description: 'Newline-delimited list of URLs to check for accessibility issues'
     required: true
     multiline: true
   auth_context:
     description: "Stringified JSON object containing 'username', 'password', 'cookies', and/or 'localStorage' from an authenticated session"
     required: false
   include_screenshots:
-    description: "Whether to capture screenshots of scanned pages and include links to them in the issue"
+    description: 'Whether to capture screenshots of scanned pages and include links to them in the issue'
+    required: false
+    default: 'false'
+  scans:
+    description: 'Stringified JSON array of scans to perform. If not provided, only Axe will be performed'
     required: false
-    default: "false"
   reduced_motion:
-    description: "Playwright reducedMotion setting: https://playwright.dev/docs/api/class-browser#browser-new-page-option-reduced-motion"
+    description: 'Playwright reducedMotion setting: https://playwright.dev/docs/api/class-browser#browser-new-page-option-reduced-motion'
     required: false
   color_scheme:
-    description: "Playwright colorScheme setting: https://playwright.dev/docs/api/class-browser#browser-new-context-option-color-scheme"
+    description: 'Playwright colorScheme setting: https://playwright.dev/docs/api/class-browser#browser-new-context-option-color-scheme'
     required: false
 
 outputs:
   findings:
-    description: "List of potential accessibility gaps, as stringified JSON"
+    description: 'List of potential accessibility gaps, as stringified JSON'
 
 runs:
-  using: "node24"
-  main: "bootstrap.js"
+  using: 'node24'
+  main: 'bootstrap.js'
 
 branding:
-  icon: "compass"
-  color: "blue"
+  icon: 'compass'
+  color: 'blue'

.github/actions/find/src/dynamicImport.ts

@@ -0,0 +1,21 @@
+// - this exists because it looks like there's no straight-forward
+//   way to mock the dynamic import function, so mocking this instead
+//   (also, if it _is_ possible to mock the dynamic import,
+//   there's the risk of altering/breaking the behavior of imports
+//   across the board - including non-dynamic imports)
+//
+// - also, vitest has a limitation on mocking:
+//   https://vitest.dev/guide/mocking/modules.html#mocking-modules-pitfalls
+//
+// - basically if a function is called by another function in the same file
+//   it can't be mocked. So this was extracted into a separate file
+//
+// - one thing to note is vitest does the same thing here:
+//   https://github.com/vitest-dev/vitest/blob/main/test/core/src/dynamic-import.ts
+// - and uses that with tests here:
+//   https://github.com/vitest-dev/vitest/blob/main/test/core/test/mock-internals.test.ts#L27
+//
+// - so this looks like a reasonable approach
+export function dynamicImport(path: string) {
+  return import(path)
+}

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

@@ -3,6 +3,9 @@ import {AxeBuilder} from '@axe-core/playwright'
 import playwright from 'playwright'
 import {AuthContext} from './AuthContext.js'
 import {generateScreenshots} from './generateScreenshots.js'
+import {loadPlugins, invokePlugin} from './pluginManager.js'
+import {getScansContext} from './scansContextProvider.js'
+import * as core from '@actions/core'
 
 export async function findForUrl(
   url: string,
@@ -23,32 +26,69 @@ export async function findForUrl(
   const context = await browser.newContext(contextOptions)
   const page = await context.newPage()
   await page.goto(url)
-  console.log(`Scanning ${page.url()}`)
 
-  let findings: Finding[] = []
-  try {
-    const rawFindings = await new AxeBuilder({page}).analyze()
-
-    let screenshotId: string | undefined
+  const findings: Finding[] = []
+  const addFinding = async (findingData: Finding) => {
+    let screenshotId
     if (includeScreenshots) {
       screenshotId = await generateScreenshots(page)
     }
+    findings.push({...findingData, screenshotId})
+  }
+
+  try {
+    const scansContext = getScansContext()
+
+    if (scansContext.shouldRunPlugins) {
+      const plugins = await loadPlugins()
+      for (const plugin of plugins) {
+        if (scansContext.scansToPerform.includes(plugin.name)) {
+          core.info(`Running plugin: ${plugin.name}`)
+          await invokePlugin({
+            plugin,
+            page,
+            addFinding,
+          })
+        } else {
+          core.info(`Skipping plugin ${plugin.name} because it is not included in the 'scans' input`)
+        }
+      }
+    }
 
-    findings = rawFindings.violations.map(violation => ({
-      scannerType: 'axe',
-      url,
-      html: violation.nodes[0].html.replace(/'/g, '''),
-      problemShort: violation.help.toLowerCase().replace(/'/g, '''),
-      problemUrl: violation.helpUrl.replace(/'/g, '''),
-      ruleId: violation.id,
-      solutionShort: violation.description.toLowerCase().replace(/'/g, '''),
-      solutionLong: violation.nodes[0].failureSummary?.replace(/'/g, '''),
-      screenshotId,
-    }))
+    if (scansContext.shouldPerformAxeScan) {
+      await runAxeScan({page, addFinding})
+    }
   } catch (e) {
-    console.error('Error during accessibility scan:', e)
+    core.error(`Error during accessibility scan: ${e}`)
   }
   await context.close()
   await browser.close()
   return findings
 }
+
+async function runAxeScan({
+  page,
+  addFinding,
+}: {
+  page: playwright.Page
+  addFinding: (findingData: Finding, options?: {includeScreenshots?: boolean}) => Promise<void>
+}) {
+  const url = page.url()
+  core.info(`Scanning ${url}`)
+  const rawFindings = await new AxeBuilder({page}).analyze()
+
+  if (rawFindings) {
+    for (const violation of rawFindings.violations) {
+      await addFinding({
+        scannerType: 'axe',
+        url,
+        html: violation.nodes[0].html.replace(/'/g, '&apos;'),
+        problemShort: violation.help.toLowerCase().replace(/'/g, '&apos;'),
+        problemUrl: violation.helpUrl.replace(/'/g, '&apos;'),
+        ruleId: violation.id,
+        solutionShort: violation.description.toLowerCase().replace(/'/g, '&apos;'),
+        solutionLong: violation.nodes[0].failureSummary?.replace(/'/g, '&apos;'),
+      })
+    }
+  }
+}

.github/actions/find/src/generateScreenshots.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import crypto from 'node:crypto'
 import type {Page} from 'playwright'
+import * as core from '@actions/core'
 
 // Use GITHUB_WORKSPACE to ensure screenshots are saved in the workflow workspace root
 // where the artifact upload step can find them
@@ -12,9 +13,9 @@ export const generateScreenshots = async function (page: Page) {
   // Ensure screenshot directory exists
   if (!fs.existsSync(SCREENSHOT_DIR)) {
     fs.mkdirSync(SCREENSHOT_DIR, {recursive: true})
-    console.log(`Created screenshot directory: ${SCREENSHOT_DIR}`)
+    core.info(`Created screenshot directory: ${SCREENSHOT_DIR}`)
   } else {
-    console.log(`Using existing screenshot directory ${SCREENSHOT_DIR}`)
+    core.info(`Using existing screenshot directory ${SCREENSHOT_DIR}`)
   }
 
   try {
@@ -28,9 +29,9 @@ export const generateScreenshots = async function (page: Page) {
     const filepath = path.join(SCREENSHOT_DIR, filename)
 
     fs.writeFileSync(filepath, screenshotBuffer)
-    console.log(`Screenshot saved: ${filename}`)
+    core.info(`Screenshot saved: ${filename}`)
   } catch (error) {
-    console.error('Failed to capture/save screenshot:', error)
+    core.error(`Failed to capture/save screenshot: ${error}`)
     screenshotId = undefined
   }
 

.github/actions/find/src/pluginManager.ts

@@ -0,0 +1,95 @@
+import * as fs from 'fs'
+import * as path from 'path'
+import {fileURLToPath} from 'url'
+import {dynamicImport} from './dynamicImport.js'
+import type {Finding} from './types.d.js'
+import playwright from 'playwright'
+import * as core from '@actions/core'
+
+// Helper to get __dirname equivalent in ES Modules
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+type PluginDefaultParams = {
+  page: playwright.Page
+  addFinding: (findingData: Finding) => void
+}
+
+type Plugin = {
+  name: string
+  default: (options: PluginDefaultParams) => Promise<void>
+}
+
+const plugins: Plugin[] = []
+let pluginsLoaded = false
+
+export async function loadPlugins() {
+  try {
+    if (!pluginsLoaded) {
+      core.info('loading plugins')
+      await loadBuiltInPlugins()
+      await loadCustomPlugins()
+    }
+  } catch {
+    plugins.length = 0
+    core.error(abortError)
+  } finally {
+    pluginsLoaded = true
+    return plugins
+  }
+}
+
+export const abortError = `
+There was an error while loading plugins.
+Clearing all plugins and aborting custom plugin scans.
+Please check the logs for hints as to what may have gone wrong.
+`
+
+export function clearCache() {
+  pluginsLoaded = false
+  plugins.length = 0
+}
+
+// exported for mocking/testing. not for actual use
+export async function loadBuiltInPlugins() {
+  core.info('Loading built-in plugins')
+
+  const pluginsPath = path.join(__dirname, '../../../scanner-plugins/')
+  await loadPluginsFromPath({pluginsPath})
+}
+
+// exported for mocking/testing. not for actual use
+export async function loadCustomPlugins() {
+  core.info('Loading custom plugins')
+
+  const pluginsPath = path.join(process.cwd(), '/.github/scanner-plugins/')
+  await loadPluginsFromPath({pluginsPath})
+}
+
+// exported for mocking/testing. not for actual use
+export async function loadPluginsFromPath({pluginsPath}: {pluginsPath: string}) {
+  try {
+    const res = fs.readdirSync(pluginsPath)
+    for (const pluginFolder of res) {
+      const pluginFolderPath = path.join(pluginsPath, pluginFolder)
+
+      if (fs.existsSync(pluginFolderPath) && fs.lstatSync(pluginFolderPath).isDirectory()) {
+        core.info(`Found plugin: ${pluginFolder}`)
+        plugins.push(await dynamicImport(path.join(pluginsPath, pluginFolder, '/index.js')))
+      }
+    }
+  } catch (e) {
+    // - log errors here for granular info
+    core.error('error: ')
+    core.error(e as Error)
+    // - throw error to handle aborting the plugin scans
+    throw e
+  }
+}
+
+type InvokePluginParams = PluginDefaultParams & {
+  plugin: Plugin
+}
+export function invokePlugin({plugin, page, addFinding}: InvokePluginParams) {
+  return plugin.default({page, addFinding})
+}

.github/actions/find/src/scansContextProvider.ts

@@ -0,0 +1,36 @@
+import * as core from '@actions/core'
+
+type ScansContext = {
+  scansToPerform: Array<string>
+  shouldPerformAxeScan: boolean
+  shouldRunPlugins: boolean
+}
+let scansContext: ScansContext | undefined
+
+export function getScansContext() {
+  if (!scansContext) {
+    const scansInput = core.getInput('scans', {required: false})
+    const scansToPerform = JSON.parse(scansInput || '[]')
+    // - if we don't have a scans input
+    //   or we do have a scans input, but it only has 1 item and its 'axe'
+    //   then we only want to run 'axe' and not the plugins
+    // - keep in mind, 'onlyAxeScan' is not the same as 'shouldPerformAxeScan'
+    const onlyAxeScan = scansToPerform.length === 0 || (scansToPerform.length === 1 && scansToPerform[0] === 'axe')
+
+    scansContext = {
+      scansToPerform,
+      // - if no 'scans' input is provided, we default to the existing behavior
+      //   (only axe scan) for backwards compatability.
+      // - we can enforce using the 'scans' input in a future major release and
+      //   mark it as required
+      shouldPerformAxeScan: !scansInput || scansToPerform.includes('axe'),
+      shouldRunPlugins: scansToPerform.length > 0 && !onlyAxeScan,
+    }
+  }
+
+  return scansContext
+}
+
+export function clearCache() {
+  scansContext = undefined
+}

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

@@ -1,11 +1,13 @@
 export type Finding = {
+  scannerType: string
   url: string
   html: string
   problemShort: string
   problemUrl: string
   solutionShort: string
   solutionLong?: string
   screenshotId?: string
+  ruleId?: string
 }
 
 export type Cookie = {