node-engine-sync

Maintainer tooling for Node libraries and apps that ship engines.node, pin CI with actions/setup-node, and depend on @types/node — those three majors drift silently and break contributors on the wrong runtime. Unlike Dependabot (which bumps versions) or engines alone (which only warns at install), node-engine-sync fails the check when the declared engine major, workflow node-version major, and @types/node major disagree.

60-second quickstart

bash

# from the repository root
npm install
npm test
node --import tsx src/cli.ts --help
node --import tsx src/cli.ts --root fixtures/aligned
node --import tsx src/cli.ts --root fixtures/mismatch-ci; echo "exit=$?"

PowerShell

# from the repository root
npm install
npm test
node --import tsx src/cli.ts --help
node --import tsx src/cli.ts --root fixtures/aligned
node --import tsx src/cli.ts --root fixtures/mismatch-ci; Write-Host "exit=$LASTEXITCODE"

Aligned fixture exits 0. Mismatch fixture exits 1.

What it checks

Source	Where	Contract
engines.node	package.json	Lowest numeric major (e.g. >=20 → 20)
CI node-version	.github/workflows/*.{yml,yaml} via actions/setup-node with.node-version / node-version-file, plus strategy.matrix.node-version (also node / nodejs)	Every concrete major must equal engines major
@types/node	dependencies / devDependencies / optionalDependencies	Major must equal engines major

CLI

node-engine-sync [options] [root]

  -r, --root <dir>     Repository root (default: cwd)
      --report <file>  Write markdown report
  -q, --quiet          One-line summary
  -h, --help
  -V, --version

Exit codes: 0 = aligned, 1 = mismatch/missing, 2 = usage error

GitHub Action

- uses: ./
  with:
    root: ${{ github.workspace }}
    report: node-engine-sync-report.md

Action inputs

Input	Default	Description
root	${{ github.workspace }}	Repo root to scan
report	node-engine-sync-report.md	Markdown report path

Fixtures

• fixtures/aligned — engines 20, CI 20, @types/node 20 → PASS
• fixtures/mismatch-ci — CI pinned to 18 → FAIL (ci-node-mismatch)
• fixtures/mismatch-types — @types/node 22 → FAIL (types-node-mismatch)
• fixtures/missing-engines — no engines.node → FAIL

Install / test / build

npm install
npm test
npm run build
node dist/cli.js --root fixtures/aligned

v0.2 limitations

• Does not evaluate GitHub expressions (${{ matrix.x }}, ${{ env.NODE }}); only concrete literals and readable node-version-file targets.
• Does not accept intentional multi-major matrices (e.g. test on 18+20 while engines is >=20) — every matrix major must match the engines major.
• Does not resolve lts/* / latest tags to a major.
• Does not read .nvmrc unless a workflow references it via node-version-file.
• Does not sync volta.node, mise, or container node: image tags.

License

MIT