Fix NPM plugin module resolution (#252)

v3.4.0 installs NPM plugins from the consumer workspace, then imports
them from the Find action. The install succeeds, but Node can't resolve
the package from `dist/pluginManager/pluginNpmLoader.js`.

This happened in [the alt text plugin
workflow](https://github.com/github/accessibility-scanner-alt-text-plugin/actions/runs/30406827436)
after switching to the new package object in #62.

This installs the package beside the loader module with an explicit npm
prefix. In the action that's `dist/pluginManager/node_modules`, so the
bare ESM import finds it without using `GITHUB_WORKSPACE`. Keeping the
install out of the Find action root also avoids npm re-resolving the
action's own dependencies.

The allowlist, version pinning, `--ignore-scripts`, `--no-save`,
`--no-package-lock`, duplicate handling, and warnings are unchanged.

I tested the exact input from #62:

```yaml
scans: |
  ["axe", {"name": "alt-text-scan", "package": "@github/accessibility-scanner-alt-text-plugin", "version": "1.1.0"}]
```

In a clean scanner copy with a separate consumer cwd, the published
1.1.0 package loaded from the compiled action. A local page produced
both the plugin's `placeholder-alt-text` finding and Axe's `button-name`
finding. The Find action's dependency versions were unchanged after the
install.

Also ran all 82 action tests, lint, format check, and the Find build. I
updated the scanner docs that still showed plugin 1.0.0 or described
`scans` as strings only.

This needs a scanner v3.4.1 after merge. The plugin stays on v1.1.0,
then its workflow pin can move from the v3.4.0 commit to the v3.4.1
commit.

Author: taarikashenafi

.github/actions/find/README.md

@@ -37,7 +37,9 @@ configuration option.
 
 #### `scans`
 
-**Optional** Stringified JSON array of scans (string) to perform. If not provided, only Axe will be performed.
+**Optional** Stringified JSON array of scans to perform. Core engines and local plugins use string names.
+Allowlisted NPM plugins use an object with `name`, `package`, and optional `version`. If not provided, only Axe
+will be performed. See [the plugin docs](../../../PLUGINS.md#loading-plugins-from-npm-packages) for an example.
 
 ### Outputs
 

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

@@ -1,10 +1,16 @@
 import {execFileSync} from 'child_process'
+import {fileURLToPath} from 'url'
 import * as core from '@actions/core'
 import type {NpmPluginRequest, Plugin} from './types.js'
 
+const pluginRoot = fileURLToPath(new URL('.', import.meta.url))
+
 // Install the package at runtime.
 export function installNpmPackage(spec: string) {
-  execFileSync('npm', ['install', spec, '--no-save', '--no-package-lock', '--ignore-scripts'], {stdio: 'inherit'})
+  execFileSync('npm', ['install', spec, '--prefix', pluginRoot, '--no-save', '--no-package-lock', '--ignore-scripts'], {
+    cwd: pluginRoot,
+    stdio: 'inherit',
+  })
 }
 
 // Install and import a single NPM-published plugin

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

@@ -163,11 +163,19 @@ describe('findForUrl', () => {
 
     it('runs plugins when a scans entry is an object-form NPM plugin', async () => {
       loadedPlugins = []
-      actionInput = JSON.stringify([{name: 'alt-text-scan', package: '@github/accessibility-scanner-alt-text-plugin'}])
+      actionInput = JSON.stringify([
+        'axe',
+        {
+          name: 'alt-text-scan',
+          package: '@github/accessibility-scanner-alt-text-plugin',
+          version: '1.1.0',
+        },
+      ])
       clearAll()
 
       await findForUrl('test.com')
       expect(pluginManager.loadPlugins).toHaveBeenCalledTimes(1)
+      expect(AxeBuilder.prototype.analyze).toHaveBeenCalledTimes(1)
     })
   })
 

.github/actions/find/tests/pluginNpmLoader.integration.test.ts

@@ -0,0 +1,47 @@
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+import {fileURLToPath} from 'url'
+import {describe, expect, it} from 'vitest'
+
+import {loadPluginViaNpm} from '../src/pluginManager/pluginNpmLoader.js'
+
+const PLUGIN_ROOT = fileURLToPath(new URL('../src/pluginManager/', import.meta.url))
+const PLUGIN_NODE_MODULES = path.join(PLUGIN_ROOT, 'node_modules')
+
+describe('npmPluginLoader integration', () => {
+  it('installs and loads a released plugin outside the consumer workspace', {timeout: 120_000}, async () => {
+    const originalCwd = process.cwd()
+    const originalMinimumReleaseAge = process.env.npm_config_min_release_age
+    const consumerWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), 'accessibility-scanner-consumer-'))
+
+    try {
+      process.chdir(consumerWorkspace)
+      process.env.npm_config_min_release_age = '0'
+      expect(process.cwd()).not.toBe(PLUGIN_ROOT)
+
+      const plugin = await loadPluginViaNpm({
+        name: 'alt-text-scan',
+        package: '@github/accessibility-scanner-alt-text-plugin',
+        version: '1.1.0',
+      })
+
+      expect(plugin?.name).toBe('alt-text-scan')
+      expect(plugin?.default).toBeTypeOf('function')
+      expect(
+        fs.existsSync(
+          path.join(PLUGIN_NODE_MODULES, '@github', 'accessibility-scanner-alt-text-plugin', 'package.json'),
+        ),
+      ).toBe(true)
+    } finally {
+      process.chdir(originalCwd)
+      if (originalMinimumReleaseAge === undefined) {
+        delete process.env.npm_config_min_release_age
+      } else {
+        process.env.npm_config_min_release_age = originalMinimumReleaseAge
+      }
+      fs.rmSync(consumerWorkspace, {recursive: true, force: true})
+      fs.rmSync(PLUGIN_NODE_MODULES, {recursive: true, force: true})
+    }
+  })
+})

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

@@ -1,6 +1,7 @@
 import {describe, it, expect, vi, beforeEach} from 'vitest'
 
 import * as childProcess from 'child_process'
+import {fileURLToPath} from 'url'
 import * as core from '@actions/core'
 import * as pluginManager from '../src/pluginManager/index.js'
 import * as npmPluginLoader from '../src/pluginManager/pluginNpmLoader.js'
@@ -13,6 +14,7 @@ vi.mock('../src/pluginManager/pluginNpmLoader.js', {spy: true})
 vi.mock('../src/scansContextProvider.js', {spy: true})
 
 const ALLOWED = '@github/accessibility-scanner-alt-text-plugin'
+const PLUGIN_ROOT = fileURLToPath(new URL('../src/pluginManager/', import.meta.url))
 
 function mockNpmPlugins(npmPlugins: NpmPluginRequest[]) {
   vi.spyOn(scansContextProvider, 'getScansContext').mockReturnValue({
@@ -35,8 +37,9 @@ describe('npmPluginLoader', () => {
       npmPluginLoader.installNpmPackage('some-pkg@1.0.0')
       expect(execSpy).toHaveBeenCalledWith(
         'npm',
-        ['install', 'some-pkg@1.0.0', '--no-save', '--no-package-lock', '--ignore-scripts'],
+        ['install', 'some-pkg@1.0.0', '--prefix', PLUGIN_ROOT, '--no-save', '--no-package-lock', '--ignore-scripts'],
         {
+          cwd: PLUGIN_ROOT,
           stdio: 'inherit',
         },
       )
@@ -49,8 +52,16 @@ describe('npmPluginLoader', () => {
       await npmPluginLoader.loadPluginViaNpm({name: 'p', package: 'nonexistent-pkg-xyz', version: '2.3.4'})
       expect(execSpy).toHaveBeenCalledWith(
         'npm',
-        ['install', 'nonexistent-pkg-xyz@2.3.4', '--no-save', '--no-package-lock', '--ignore-scripts'],
-        {stdio: 'inherit'},
+        [
+          'install',
+          'nonexistent-pkg-xyz@2.3.4',
+          '--prefix',
+          PLUGIN_ROOT,
+          '--no-save',
+          '--no-package-lock',
+          '--ignore-scripts',
+        ],
+        {cwd: PLUGIN_ROOT, stdio: 'inherit'},
       )
     })
 

PLUGINS.md

@@ -46,6 +46,7 @@ jobs:
 ## Loading plugins from NPM packages
 
 In addition to local plugins under `./.github/scanner-plugins`, the scanner can install and load plugins published as NPM packages. This avoids having to vendor a plugin's source into your repo.
+NPM package loading requires scanner v3.4.1 or later.
 
 To use an NPM plugin, pass an object (instead of a plain string) in the `scans` input with the following fields:
 
@@ -64,7 +65,7 @@ jobs:
       - uses: github/accessibility-scanner@v3
         with:
           scans: |
-            ["axe", {"name": "alt-text-scan", "package": "@github/accessibility-scanner-alt-text-plugin", "version": "1.0.0"}]
+            ["axe", {"name": "alt-text-scan", "package": "@github/accessibility-scanner-alt-text-plugin", "version": "1.1.0"}]
 ```
 
 Notes:

README.md

@@ -188,7 +188,7 @@ The [Alt Text Plugin](https://github.com/github/accessibility-scanner-alt-text-p
 
 ```yaml
 scans: |
-  ["axe", {"name": "alt-text-scan", "package": "@github/accessibility-scanner-alt-text-plugin", "version": "1.0.0"}]
+  ["axe", {"name": "alt-text-scan", "package": "@github/accessibility-scanner-alt-text-plugin", "version": "1.1.0"}]
 ```
 
 See the [plugin README](https://github.com/github/accessibility-scanner-alt-text-plugin#getting-started) for the current release version, full rule list, and setup instructions.

action.yml

@@ -64,7 +64,7 @@ inputs:
     description: 'Playwright colorScheme setting: https://playwright.dev/docs/api/class-browser#browser-new-context-option-color-scheme'
     required: false
   scans:
-    description: 'Stringified JSON array of scans to perform. If not provided, only Axe will be performed'
+    description: "Stringified JSON array of scans to perform. Core engines and local plugins use string names. Allowlisted NPM plugins use an object with 'name', 'package', and optional 'version'. If not provided, only Axe will be performed"
     required: false
   dry_run:
     description: 'When true, scan and log the issues that would be filed without opening, closing, reopening, or assigning any issues, and without writing to the cache.'