fix: rename npm-shrinkwrap.json to package-lock.json

[MikeMcC399]

• closes npm 12 - drops npm-shrinkwrap.json #1117

Situation

npm 12 drops npm-shrinkwrap.json used in this repo as a published lockfile.

The npm 12.0.0 changelog states:

npm shrinkwrap is removed, the shrinkwrap config alias is removed, and npm-shrinkwrap.json is no longer loaded or honored at the project root or from inside dependency tarballs. Rename project-root npm-shrinkwrap.json to package-lock.json; use bundleDependencies if you need to ship a locked dependency tree.

npm install under npm 12 installs dependencies according to their SemVer range specified in package.json and ignores the lower locked versions specified in npm-shrinkwrap.json.

Change

To ensure that dependencies are consistently installed by downstream consumers of citgm, whichever version of npm is being used to execute the Installation instructions npm install -g citgm, rename:

npm-shrinkwrap.json to package-lock.json.

This should be considered a breaking change (semver-major) when the next release is cut.

Checklist

• npm test passes (for currently bundled versions of npm 10.x & 11.x)
• contribution guidelines followed
  here

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.20%. Comparing base (eef880d) to head (93baef8).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1129   +/-   ##
=======================================
  Coverage   96.20%   96.20%           
=======================================
  Files          29       29           
  Lines        2213     2213           
=======================================
  Hits         2129     2129           
  Misses         84       84           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[MikeMcC399]

@targos

This would need a review, if you are available.

I imagine that npm 12 will at some stage land on main in nodejs/node, and then when builds for Node.js 27 Alpha start to be tested in Sept / Oct 2026, they would be using npm 12, which ignores npm-shrinkwrap.json and so global installs of citgm would fallback to using package.json.

Making this change now would make sure that any issues resulting from installing with package.json are surfaced now instead of later when npm 12 starts being used. I'm not aware of any such issues, so this move would be purely defensive for the future.

[targos]

I think we should solve it the same way as in node-core-utils for consistency: nodejs/node-core-utils#1135

[MikeMcC399]

I think we should solve it the same way as in node-core-utils for consistency: nodejs/node-core-utils#1135

I'm not sure that is the best way for citgm if the objective is to catch compatibility issues early, although bundleDependencies is one of the alternatives suggested by the warning message:

Rename project-root npm-shrinkwrap.json to package-lock.json; use bundleDependencies if you need to ship a locked dependency tree.

Allowing global installs to use only package.json would re-evaluate the SemVer ranges each time citgm is installed, for instance in Jenkins. That means testing against latest of the configured ranges, rather than being pinned to older versions.

I don't have the history in this repo to judge what is best, so if this PR doesn't fit the needs then please go ahead and close it. I'll leave it to the citgm team then to resolve the issue as it sees best.

[targos]

citgm is run on relatively sensitive infrastructure. We are using shrinkwrap to lock down the dependencies so that in case of compromise, we stay unaffected. My opinion is that safety is more important but I would like to hear what other people from @nodejs/citgm think about it.

[MikeMcC399]

citgm is run on relatively sensitive infrastructure. We are using shrinkwrap to lock down the dependencies so that in case of compromise, we stay unaffected. My opinion is that safety is more important but I would like to hear what other people from @nodejs/citgm think about it.

citgm is pulling in unpinned packages listed in lib/lookup.json, any of which could be potentially compromised, so citgm should be run in a sandboxed environment where it cannot cause damage. I'm not sure that pinning the dependencies that citgm itself uses would provide a security advantage in that case. @nodejs/citgm will have their own views on that I expect.

Independent of this discussion, perhaps .npmrc should start using min-release-age? A typical value would be 3, 5 or 7 days.

[MikeMcC399]

I'm going to close this PR, since the current npm-shrinkwrap.json is outdated and causes:

32 vulnerabilities (1 low, 6 moderate, 24 high, 1 critical)

to be installed with citgm. The use of npm-shrinkwrap.json also means that npm audit fix can't remediate the vulnerabilities on a downstream system.

I suggest first to update the pinned dependencies before moving them to any other variation including bundleDependencies.