Add plugins

.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 async function dynamicImport(path: string) {
+  return import(path)
+}

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

@@ -3,11 +3,14 @@ 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 core from '@actions/core'
 
 export async function findForUrl(
   url: string,
   authContext?: AuthContext,
-  includeScreenshots: boolean = false,
+  includeScreenshotsInput: boolean = false,
   reducedMotion?: ReducedMotionPreference,
   colorScheme?: ColorSchemePreference,
 ): Promise<Finding[]> {
@@ -23,32 +26,82 @@ 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[] = []
+  const findings: Finding[] = []
+  const addFinding = async (
+    findingData: Finding,
+    {includeScreenshots = false}: {includeScreenshots?: boolean} = {},
+  ) => {
+    let screenshotId
+    if (includeScreenshotsInput || includeScreenshots) {
+      screenshotId = await generateScreenshots(page)
+    }
+    findings.push({...findingData, screenshotId})
+  }
+
   try {
-    const rawFindings = await new AxeBuilder({page}).analyze()
+    const scansContext = getScansContext()
 
-    let screenshotId: string | undefined
-    if (includeScreenshots) {
-      screenshotId = await generateScreenshots(page)
+    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,
+            // - this will be coming soon
+            // runAxeScan: () => runAxeScan({page, includeScreenshots: includeScreenshotsInput, findings}),
+          })
+        } 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, '&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;'),
-      screenshotId,
-    }))
+    if (scansContext.shouldPerformAxeScan) {
+      runAxeScan({
+        includeScreenshots: includeScreenshotsInput,
+        page,
+        findings,
+      })
+    }
   } 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({
+  includeScreenshots,
+  page,
+  findings,
+}: {
+  includeScreenshots: boolean
+  page: playwright.Page
+  findings: Finding[]
+}) {
+  const url = page.url()
+  core.info(`Scanning ${url}`)
+  const rawFindings = await new AxeBuilder({page}).analyze()
+  let screenshotId: string | undefined
+  if (includeScreenshots) {
+    screenshotId = await generateScreenshots(page)
+  }
+
+  const axeFindings = rawFindings?.violations.map(violation => ({
+    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;'),
+    screenshotId,
+  }))
+  findings.push(...(axeFindings || []))
+}

.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 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,103 @@
+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 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
+  // - this will be coming soon
+  // runAxeScan: (options: {includeScreenshots: boolean; page: playwright.Page; findings: Finding[]}) => Promise<void>
+}
+
+export type Plugin = {
+  name: string
+  default: (options: PluginDefaultParams) => Promise<void>
+}
+
+const plugins: Plugin[] = []
+let pluginsLoaded = false
+
+export async function loadPlugins() {
+  core.info('loading plugins')
+
+  try {
+    if (!pluginsLoaded) {
+      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 = '../../../scanner-plugins/'
+  await loadPluginsFromPath({
+    readPath: path.join(__dirname, pluginsPath),
+    importPath: pluginsPath,
+  })
+}
+
+// exported for mocking/testing. not for actual use
+export async function loadCustomPlugins() {
+  core.info('Loading custom plugins')
+
+  const pluginsPath = process.cwd() + '/.github/scanner-plugins/'
+  await loadPluginsFromPath({
+    readPath: pluginsPath,
+    importPath: pluginsPath,
+  })
+}
+
+// exported for mocking/testing. not for actual use
+export async function loadPluginsFromPath({readPath, importPath}: {readPath: string; importPath: string}) {
+  try {
+    const res = fs.readdirSync(readPath)
+    for (const pluginFolder of res) {
+      const pluginFolderPath = path.join(importPath, pluginFolder)
+      if (fs.lstatSync(pluginFolderPath).isDirectory()) {
+        core.info(`Found plugin: ${pluginFolder}`)
+        plugins.push(await dynamicImport(path.join(importPath, 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 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
+}