[NOT READY YET] Build/Test Tools: Upgrade npm to v12

.github/actions/setup-npm/action.yml

@@ -0,0 +1,54 @@
+name: 'Set up npm'
+description: 'Installs the npm version required by the devEngines field of package.json, so every job resolves dependencies identically. Keeps the bundled npm when the field is absent.'
+
+inputs:
+  working-directory:
+    description: 'Optional. The directory holding the package.json to read the required npm version from. Defaults to the workspace root.'
+    required: false
+    default: '.'
+  cache:
+    description: 'Optional. Whether to restore and save the npm cache. Defaults to true.'
+    required: false
+    default: 'true'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Install npm
+      id: npm
+      env:
+        WORKING_DIRECTORY: ${{ inputs.working-directory }}
+      run: |
+        NPM_VERSION="$(jq -r '.devEngines.packageManager.version // empty' package.json)"
+        if [ -n "$NPM_VERSION" ]; then
+          # Contributors need the floor; CI stays on that major's newest release.
+          npm install --global "npm@${NPM_VERSION/>=/^}"
+          echo "Required npm version: $NPM_VERSION"
+        else
+          echo "No devEngines.packageManager.version, keeping the bundled npm."
+        fi
+        echo "Installed npm version: $(npm --version)"
+
+        # actions/setup-node cannot restore the npm cache: it locates the
+        # directory with `npm config get cache`, which runs before this step
+        # and fails the devEngines check under the bundled npm.
+        echo "cache-dir=$(npm config get cache | tr -d '\r')" >> "$GITHUB_OUTPUT"
+
+        # Keep the hashFiles patterns workspace-relative and free of a "./"
+        # prefix, so they match the same files as every other cache key.
+        PATH_PREFIX=""
+        if [ "$WORKING_DIRECTORY" != '.' ] && [ -n "$WORKING_DIRECTORY" ]; then
+          PATH_PREFIX="${WORKING_DIRECTORY%/}/"
+        fi
+        echo "path-prefix=$PATH_PREFIX" >> "$GITHUB_OUTPUT"
+      working-directory: ${{ inputs.working-directory }}
+      shell: bash
+
+    - name: Cache npm downloads
+      if: ${{ inputs.cache == 'true' }}
+      uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+      with:
+        path: ${{ steps.npm.outputs.cache-dir }}
+        key: npm-cache-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles(format('{0}package-lock.json', steps.npm.outputs.path-prefix), format('{0}patches/**', steps.npm.outputs.path-prefix)) }}
+        restore-keys: |
+          npm-cache-${{ runner.os }}-${{ runner.arch }}-

.github/workflows/coding-standards.yml

@@ -68,6 +68,7 @@ on:
       - 'composer.*'
       - '**.jshintrc'
       - 'phpcs.xml.dist'
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/coding-standards.yml'
       - '.github/workflows/reusable-coding-standards-*.yml'
   workflow_dispatch:

.github/workflows/end-to-end-tests.yml

@@ -43,6 +43,7 @@ on:
       - 'tools/local-env/**'
       - 'tools/vendors/**'
       - 'tools/webpack/**'
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/end-to-end-tests.yml'
       - '.github/workflows/reusable-end-to-end-tests*.yml'
   workflow_dispatch:

.github/workflows/javascript-tests.yml

@@ -69,6 +69,7 @@ on:
       - 'tools/webpack/**'
       - '.jshintrc'
       - 'tests/qunit/**'
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/javascript-tests.yml'
       - '.github/workflows/reusable-javascript-tests.yml'
   workflow_dispatch:

.github/workflows/javascript-type-checking.yml

@@ -24,6 +24,7 @@ on:
       # This directory contains TypeScript definitions. Changes could affect the outcome.
       - 'typings/**'
       # Confirm any changes to relevant workflow files.
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/javascript-type-checking.yml'
       - '.github/workflows/reusable-javascript-type-checking-v1.yml'
   workflow_dispatch:

.github/workflows/local-docker-environment.yml

@@ -28,6 +28,7 @@ on:
       # These files define the versions to test.
       - '.version-support-*.json'
       # Changes to this and related workflow files should always be verified.
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/local-docker-environment.yml'
       - '.github/workflows/reusable-support-json-reader-v1.yml'
       - '.github/workflows/reusable-test-docker-environment-v1.yml'
@@ -55,6 +56,7 @@ on:
       # These files define the versions to test.
       - '.version-support-*.json'
       # Changes to this and related workflow files should always be verified.
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/local-docker-environment.yml'
       - '.github/workflows/reusable-support-json-reader-v1.yml'
       - '.github/workflows/reusable-test-docker-environment-v1.yml'

.github/workflows/performance.yml

@@ -43,6 +43,7 @@ on:
       - 'tools/local-env/**'
       - 'tools/vendors/**'
       - 'tools/webpack/**'
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/performance.yml'
       - '.github/workflows/reusable-performance-*.yml'
   workflow_dispatch:

.github/workflows/phpstan-static-analysis.yml

@@ -20,6 +20,7 @@ on:
       - 'tests/phpstan/base.neon'
       - 'tests/phpstan/baselines/**'
       # Confirm any changes to relevant workflow files.
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/phpstan-static-analysis.yml'
       - '.github/workflows/reusable-phpstan-static-analysis-v1.yml'
   workflow_dispatch:

.github/workflows/phpunit-tests-full-matrix.yml

@@ -42,6 +42,7 @@ on:
       - 'tools/vendors/**'
       - 'tools/webpack/**'
       - 'phpunit.xml.dist'
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/phpunit-tests.yml'
       - '.github/workflows/phpunit-tests-full-matrix.yml'
       - '.github/workflows/reusable-phpunit-tests-*.yml'

.github/workflows/phpunit-tests.yml

@@ -46,6 +46,7 @@ on:
       - 'tools/vendors/**'
       - 'tools/webpack/**'
       - 'phpunit.xml.dist'
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/phpunit-tests.yml'
       - '.github/workflows/phpunit-tests-full-matrix.yml'
       - '.github/workflows/reusable-phpunit-tests-*.yml'

.github/workflows/reusable-build-package.yml

@@ -38,7 +38,12 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
-          cache: npm
+          package-manager-cache: false
+
+      - name: Set up npm
+        # Release branches run this workflow from trunk, but some older branches may lack the action.
+        if: ${{ hashFiles('.github/actions/setup-npm/action.yml') != '' }}
+        uses: ./.github/actions/setup-npm
 
       - name: Install npm Dependencies
         run: npm ci

.github/workflows/reusable-coding-standards-javascript.yml

@@ -43,7 +43,12 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
-          cache: npm
+          package-manager-cache: false
+
+      - name: Set up npm
+        # Release branches run this workflow from trunk, but some older branches may lack the action.
+        if: ${{ hashFiles('.github/actions/setup-npm/action.yml') != '' }}
+        uses: ./.github/actions/setup-npm
 
       - name: Log debug information
         run: |

.github/workflows/reusable-end-to-end-tests.yml

@@ -85,7 +85,12 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
-          cache: npm
+          package-manager-cache: false
+
+      - name: Set up npm
+        # Release branches run this workflow from trunk, but some older branches may lack the action.
+        if: ${{ hashFiles('.github/actions/setup-npm/action.yml') != '' }}
+        uses: ./.github/actions/setup-npm
 
       - name: Log debug information
         run: |

.github/workflows/reusable-javascript-tests.yml

@@ -44,7 +44,12 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
-          cache: npm
+          package-manager-cache: false
+
+      - name: Set up npm
+        # Release branches run this workflow from trunk, but some older branches may lack the action.
+        if: ${{ hashFiles('.github/actions/setup-npm/action.yml') != '' }}
+        uses: ./.github/actions/setup-npm
 
       - name: Log debug information
         run: |

.github/workflows/reusable-javascript-type-checking-v1.yml

@@ -42,7 +42,12 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
-          cache: npm
+          package-manager-cache: false
+
+      - name: Set up npm
+        # Release branches run this workflow from trunk, but some older branches may lack the action.
+        if: ${{ hashFiles('.github/actions/setup-npm/action.yml') != '' }}
+        uses: ./.github/actions/setup-npm
 
       - name: Log debug information
         run: |

.github/workflows/reusable-performance-report-v2.yml

@@ -65,7 +65,7 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
-          cache: npm
+          package-manager-cache: false
 
       - name: Download artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1

.github/workflows/reusable-performance-test-v2.yml

@@ -126,7 +126,12 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
-          cache: npm
+          package-manager-cache: false
+
+      - name: Set up npm
+        # Release branches run this workflow from trunk, but some older branches may lack the action.
+        if: ${{ hashFiles('.github/actions/setup-npm/action.yml') != '' }}
+        uses: ./.github/actions/setup-npm
 
       - name: Set up PHP
         if: ${{ inputs.subject == 'base' }}

.github/workflows/reusable-phpstan-static-analysis-v1.yml

@@ -53,7 +53,12 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
-          cache: npm
+          package-manager-cache: false
+
+      - name: Set up npm
+        # Release branches run this workflow from trunk, but some older branches may lack the action.
+        if: ${{ hashFiles('.github/actions/setup-npm/action.yml') != '' }}
+        uses: ./.github/actions/setup-npm
 
       - name: Set up PHP
         uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2

.github/workflows/reusable-phpunit-tests-v3.yml

@@ -219,7 +219,12 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
-          cache: npm
+          package-manager-cache: false
+
+      - name: Set up npm
+        # Release branches run this workflow from trunk, but some older branches may lack the action.
+        if: ${{ hashFiles('.github/actions/setup-npm/action.yml') != '' }}
+        uses: ./.github/actions/setup-npm
 
       ##
       # This allows Composer dependencies to be installed using a single step.

.github/workflows/reusable-prepare-gutenberg.yml

@@ -74,6 +74,7 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
+          package-manager-cache: false
 
       - name: Download and verify Gutenberg build
         id: download

.github/workflows/reusable-test-core-build-process.yml

@@ -94,7 +94,12 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
-          cache: npm
+          package-manager-cache: false
+
+      - name: Set up npm
+        # Release branches run this workflow from trunk, but some older branches may lack the action.
+        if: ${{ hashFiles('.github/actions/setup-npm/action.yml') != '' }}
+        uses: ./.github/actions/setup-npm
 
       - name: Log debug information
         run: |

.github/workflows/reusable-test-local-docker-environment-v1.yml

@@ -95,7 +95,12 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
-          cache: npm
+          package-manager-cache: false
+
+      - name: Set up npm
+        # Release branches run this workflow from trunk, but some older branches may lack the action.
+        if: ${{ hashFiles('.github/actions/setup-npm/action.yml') != '' }}
+        uses: ./.github/actions/setup-npm
 
       ##
       # This allows Composer dependencies to be installed using a single step.

.github/workflows/test-and-zip-default-themes.yml

@@ -10,6 +10,7 @@ on:
       # Changing the preferred version of Node.js could affect themes with build processes.
       - '.npmrc'
       - '.nvmrc'
+      - '.github/actions/setup-npm/**'
       # Changes to any themes with a build script should be confirmed.
       - 'src/wp-content/themes/twentynineteen/**'
       - 'src/wp-content/themes/twentytwenty/**'
@@ -27,6 +28,7 @@ on:
       # Changing the preferred version of Node.js could affect themes with build processes.
       - '.npmrc'
       - '.nvmrc'
+      - '.github/actions/setup-npm/**'
       # Changes to any themes with a build script should be confirmed.
       - 'src/wp-content/themes/twentynineteen/**'
       - 'src/wp-content/themes/twentytwenty/**'
@@ -161,8 +163,12 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: 'src/wp-content/themes/${{ matrix.theme }}/.nvmrc'
-          cache: npm
-          cache-dependency-path: src/wp-content/themes/${{ matrix.theme }}/package-lock.json
+          package-manager-cache: false
+
+      - name: Set up npm
+        uses: ./.github/actions/setup-npm
+        with:
+          working-directory: src/wp-content/themes/${{ matrix.theme }}
 
       - name: Install npm dependencies
         run: npm ci
@@ -246,8 +252,13 @@ jobs:
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: 'src/wp-content/themes/${{ matrix.theme }}/.nvmrc'
-          cache: npm
-          cache-dependency-path: src/wp-content/themes/${{ matrix.theme }}/package-lock.json
+          package-manager-cache: false
+
+      - name: Set up npm
+        if: matrix.theme == 'twentytwentytwo' || matrix.theme == 'twentytwentyfive'
+        uses: ./.github/actions/setup-npm
+        with:
+          working-directory: src/wp-content/themes/${{ matrix.theme }}
 
       - name: Install npm dependencies
         if: matrix.theme == 'twentytwentytwo' || matrix.theme == 'twentytwentyfive'

.github/workflows/test-build-processes.yml

@@ -43,6 +43,7 @@ on:
       - 'tools/gutenberg/**'
       - 'tools/vendors/**'
       - 'tools/webpack/**'
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/test-build-processes.yml'
       - '.github/workflows/reusable-test-core-build-process.yml'
   workflow_dispatch:

.github/workflows/test-coverage.yml

@@ -6,6 +6,7 @@ on:
     branches:
       - trunk
     paths:
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/test-coverage.yml'
       - '.github/workflows/reusable-phpunit-tests-v3.yml'
       - '.github/workflows/reusable-prepare-gutenberg.yml'
@@ -19,6 +20,7 @@ on:
     branches:
       - trunk
     paths:
+      - '.github/actions/setup-npm/**'
       - '.github/workflows/test-coverage.yml'
       - '.github/workflows/reusable-phpunit-tests-v3.yml'
       - '.github/workflows/reusable-prepare-gutenberg.yml'

.npmrc

@@ -3,3 +3,7 @@ legacy-peer-deps = true
 lockfile-version = 3
 prefer-dedupe = true
 save-exact = true
+# fail the install on any dependency script not covered by allowScripts in package.json
+strict-allow-scripts = true
+# npm v12 already refuses git and remote URL dependencies; extend that to local tarballs
+allow-file = none