CI: windows-2025 + Node 20.x matrix always fails — msnodesqlv8 v5 has no Node 20 prebuild, node-gyp fallback can't find Visual Studio #1882

Summary

Every PR currently fails 4 checks — Run tests (windows-2025, 20.x, {2016,2017,2019,2022}) — for a reason unrelated to the PR contents. The Install msnodesqlv8 v5 step falls back to a node-gyp source build, which cannot detect Visual Studio on the windows-2025 image.

This is the "brittle node-gyp source build" case that the workflow comment added in 9ed51d2 already anticipates — the coverage table just has one cell wrong.

Root cause

From a failing job (example):

##[group]Run npm install --no-save msnodesqlv8@^5
...
npm error command C:\Windows\system32\cmd.exe /d /s /c prebuild-install || node-gyp rebuild -j 4
npm error prebuild-install warn install No prebuilt binaries found (target=20.20.2 runtime=node arch=x64 libc= platform=win32)
npm error gyp ERR! configure error
npm error gyp ERR! stack Error: Could not find any Visual Studio installation to use
npm error gyp ERR! cwd D:\a\node-mssql\node-mssql\node_modules\msnodesqlv8
npm error gyp ERR! node -v v20.20.2
npm error gyp ERR! node-gyp -v v10.1.0

Two things combine:

1. msnodesqlv8 v5 ships no prebuilt win32-x64 binary for Node 20 (target=20.20.2 … platform=win32 → No prebuilt binaries found), so prebuild-install falls through to node-gyp rebuild.
2. node-gyp 10.1.0 (bundled with Node 20's npm) cannot detect the Visual Studio on the windows-2025 image — the VS 2026 rollout referenced in the existing comment.

Either alone would be survivable; together they fail the job.

The workflow's coverage comment currently claims:

#   v2: Node 18    v3: Node 18-20    v4: Node 18-24    v5: Node 20-24

but the v5: Node 20 cell is not backed by a published prebuild.

Why the failure pattern looks the way it does

The windows-2022 + Node 20 cell is worth noting: it is silently doing a full native source build on every run. Fixing the gate speeds that up as well as fixing windows-2025.

Evidence this is not caused by any particular PR

Observed on #1881, a lockfile-only transitive fast-uri 3.1.2 → 3.1.4 bump — a pure-JS URI parser, which cannot affect whether node-gyp finds a compiler.

Temporal confirmation:

The workflow was last modified on 2026-07-02 (735c3c8), so nothing in this repo changed between those runs — the windows-2025 image did.

Suggested fix

Gate the v5 steps to Node 22/24 only, matching where prebuilds actually exist:

      - name: Install msnodesqlv8 v5
        if: ${{ matrix.node == '22.x' || matrix.node == '24.x' }}
        run: npm install --no-save msnodesqlv8@^5
      - name: Run msnodesqlv8 v5 tests
        if: ${{ matrix.node == '22.x' || matrix.node == '24.x' }}
        run: npm run test-msnodesqlv8

and update the coverage comment to v5: Node 22-24.

Node 20 keeps meaningful msnodesqlv8 coverage through the v3 and v4 steps, so this narrows the matrix without losing a supported combination.

Alternatives

• Add windows-2025 + 20.x to matrix.exclude — blunter, and would also drop the tedious/cli test coverage for that cell.
• Force a newer node-gyp (npm i -g node-gyp@latest) before the install step — restores VS detection, but keeps a slow source build on every run and re-breaks whenever the image moves again.

Gating on prebuild availability seems the most durable, and is what the existing comment already intends.

Impact

Until this is fixed, every PR shows 4 red checks. They are not required for merge (PRs sit at UNSTABLE rather than BLOCKED), but they mask genuine failures and cost a re-diagnosis on each PR.