Add plugins

.github/actions/find/README.md

@@ -19,6 +19,14 @@ https://primer.style/octicons/
 
 **Optional** Stringified JSON object containing `username`, `password`, `cookies`, and/or `localStorage` from an authenticated session. For example: `{"username":"some-user","password":"correct-horse-battery-staple","cookies":[{"name":"theme-preference","value":"light","domain":"primer.style","path":"/"}],"localStorage":{"https://primer.style":{"theme-preference":"light"}}}`
 
+#### `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. Valid options currently include 'axe'
+
 ### Outputs
 
 #### `findings`

.github/actions/find/action.yml

@@ -1,27 +1,30 @@
-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"
 
 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 I'm not sure how 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,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} from './pluginManager.js'
+import {getScansContext} from './scansContextProvider.js'
+import axe from 'axe-core'
 
 export async function findForUrl(
   url: string,
@@ -19,16 +22,45 @@ export async function findForUrl(
   await page.goto(url)
   console.log(`Scanning ${page.url()}`)
 
-  let findings: Finding[] = []
+  const findings: Finding[] = []
+  const addFinding = (findingData: Finding) => {
+    findings.push(findingData)
+  }
+
   try {
-    const rawFindings = await new AxeBuilder({page}).analyze()
+    const scansContext = getScansContext()
+
+    let rawFindings: axe.AxeResults | undefined
+    if (scansContext.shouldPerformAxeScan) {
+      rawFindings = await new AxeBuilder({page}).analyze()
+    }
+
+    // - this if condition is not required, but makes it easier to make assertions
+    //   in unit tests on whether 'loadPlugins' was called or not (it does have the added
+    //   benefit of completely skipping plugin loading if we just want axe - so thats
+    //   a minor performance boost)
+    // - alternatively, we can wrap the 'plugin.default(...)' call in another function
+    //   and make assertions on whether that function was called or not
+    // - the other option is to wrap each plugin in a class instance
+    //   and make assertions on something like 'plugin.run' being called or not
+    if (scansContext.shouldRunPlugins) {
+      const plugins = await loadPlugins()
+      for (const plugin of plugins) {
+        if (scansContext.scansToPerform.includes(plugin.name)) {
+          console.log('Running plugin: ', plugin.name)
+          await plugin.default({page, addFinding, url})
+        } else {
+          console.log(`Skipping plugin ${plugin.name} because it is not included in the 'scans' input`)
+        }
+      }
+    }
 
     let screenshotId: string | undefined
     if (includeScreenshots) {
       screenshotId = await generateScreenshots(page)
     }
 
-    findings = rawFindings.violations.map(violation => ({
+    const axeFindings = rawFindings?.violations.map(violation => ({
       scannerType: 'axe',
       url,
       html: violation.nodes[0].html.replace(/'/g, '''),
@@ -39,6 +71,7 @@ export async function findForUrl(
       solutionLong: violation.nodes[0].failureSummary?.replace(/'/g, '''),
       screenshotId,
     }))
+    findings.push(...(axeFindings || []))
   } catch (e) {
     console.error('Error during accessibility scan:', e)
   }

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

@@ -0,0 +1,88 @@
+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'
+
+// Helper to get __dirname equivalent in ES Modules
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+export type Plugin = {
+  name: string
+  default: (options: {page: playwright.Page; addFinding: (findingData: Finding) => void; url: string}) => Promise<void>
+}
+
+const plugins: Plugin[] = []
+let pluginsLoaded = false
+
+export async function loadPlugins() {
+  console.log('loading plugins')
+
+  try {
+    if (!pluginsLoaded) {
+      await loadBuiltInPlugins()
+      await loadCustomPlugins()
+    }
+  } catch {
+    plugins.length = 0
+    console.log(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() {
+  console.log('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() {
+  console.log('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()) {
+        console.log('Found plugin: ', pluginFolder)
+        plugins.push(await dynamicImport(path.join(importPath, pluginFolder, '/index.js')))
+      }
+    }
+  } catch (e) {
+    // - log errors here for granular info
+    console.log('error: ')
+    console.log(e)
+    // - throw error to handle aborting the plugin scans
+    throw e
+  }
+}

.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 scansJson = core.getInput('scans', {required: false})
+    const scansToPerform = JSON.parse(scansJson || '[]')
+    // - 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: !scansJson || scansToPerform.includes('axe'),
+      shouldRunPlugins: scansToPerform.length > 0 && !onlyAxeScan,
+    }
+  }
+
+  return scansContext
+}
+
+export function clearCache() {
+  scansContext = undefined
+}

.github/actions/find/tests/findForUrl.test.ts

@@ -0,0 +1,104 @@
+import {describe, it, expect, vi} from 'vitest'
+import core from '@actions/core'
+import {findForUrl} from '../src/findForUrl.js'
+import AxeBuilder from '@axe-core/playwright'
+import axe from 'axe-core'
+import * as pluginManager from '../src/pluginManager.js'
+import {clearCache} from '../src/scansContextProvider.js'
+
+vi.mock('playwright', () => ({
+  default: {
+    chromium: {
+      launch: () => ({
+        newContext: () => ({
+          newPage: () => ({
+            pageUrl: '',
+            goto: () => {},
+            url: () => {},
+          }),
+          close: () => {},
+        }),
+        close: () => {},
+      }),
+    },
+  },
+}))
+
+vi.mock('@axe-core/playwright', () => {
+  const AxeBuilderMock = vi.fn()
+  const rawFinding = {violations: []} as unknown as axe.AxeResults
+  AxeBuilderMock.prototype.analyze = vi.fn(() => Promise.resolve(rawFinding))
+  return {default: AxeBuilderMock}
+})
+
+let actionInput: string = ''
+let loadedPlugins: pluginManager.Plugin[] = []
+
+function clearAll() {
+  clearCache()
+  vi.clearAllMocks()
+}
+
+describe('findForUrl', () => {
+  vi.spyOn(core, 'getInput').mockImplementation(() => actionInput)
+  vi.spyOn(pluginManager, 'loadPlugins').mockImplementation(() => Promise.resolve(loadedPlugins))
+
+  async function axeOnlyTest() {
+    clearAll()
+
+    await findForUrl('test.com')
+    expect(AxeBuilder.prototype.analyze).toHaveBeenCalledTimes(1)
+    expect(pluginManager.loadPlugins).toHaveBeenCalledTimes(0)
+  }
+
+  describe('when no scans list is provided', () => {
+    it('defaults to running only axe scan', async () => {
+      actionInput = ''
+      await axeOnlyTest()
+    })
+  })
+
+  describe('when a scans list is provided', () => {
+    describe('and the list _only_ includes axe', () => {
+      it('runs only the axe scan', async () => {
+        actionInput = JSON.stringify(['axe'])
+        await axeOnlyTest()
+      })
+    })
+
+    describe('and the list includes axe and other scans', () => {
+      it('runs axe and plugins', async () => {
+        actionInput = JSON.stringify(['axe', 'custom-scan'])
+        clearAll()
+
+        await findForUrl('test.com')
+        expect(AxeBuilder.prototype.analyze).toHaveBeenCalledTimes(1)
+        expect(pluginManager.loadPlugins).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    describe('and the list does not include axe', () => {
+      it('only runs plugins', async () => {
+        actionInput = JSON.stringify(['custom-scan'])
+        clearAll()
+
+        await findForUrl('test.com')
+        expect(AxeBuilder.prototype.analyze).toHaveBeenCalledTimes(0)
+        expect(pluginManager.loadPlugins).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('should only run scans that are included in the list', async () => {
+      loadedPlugins = [
+        {name: 'custom-scan-1', default: vi.fn()},
+        {name: 'custom-scan-2', default: vi.fn()},
+      ]
+      actionInput = JSON.stringify(['custom-scan-1'])
+      clearAll()
+
+      await findForUrl('test.com')
+      expect(loadedPlugins[0].default).toHaveBeenCalledTimes(1)
+      expect(loadedPlugins[1].default).toHaveBeenCalledTimes(0)
+    })
+  })
+})