PROPOSAL: Explicitly use npm-shrinkwrap.json for us and our users

[plocket]

For historical reference, #697 implemented shrinkwrap. If discussions could be "accepted", this would be the accepted answer. Gonna close the discussion for now, as new issues that arise with shrinkwrap can be made as normal issues.

Quote from #532 (reply in thread)

Proposal: Explicitly use npm-shrinkwrap.json for us and our users

[Give your feedback in Slack pinned post. See fist to 5 process linked in Slack.]

We use npm ci instead of npm install to install using our package-lock.json in both our repo for development and also in our user's packages through our action.yml.

Update from comment suggestion:
We create an npm-shrinkwrap.json and use that in place of package-lock.json in both our repo for development and also in our user's packages through our action.yml.

Problem

We need to align with what our users experience and possibly increase security.

Currently, our action.yml installs packages using only package.json meaning that our user's tests will use dependencies that are actually slightly different on every install (for every test).

Do we want to use our own package-lock.json (exclusively) for both situations instead to increase security? Or do we want to remove ours completely?

Note that just having a package-lock.json is not enough:

That means that package.json can override package-lock.json whenever a newer version is found for a dependency in package.json...package-lock.json alone no longer locks the root level dependencies!

• https://stackoverflow.com/a/45566871/14144258 (updated 2019)

Increase security

Have a package-lock.json and use npm ci to install files based on it. (From what I can tell npm ci is the right way)

In our action.yml, we could copy our own package-lock.json. We'd use npm ci to install packages based on it. It would mean we would only be vulnerable when we update the lock file explicitly.

We'd need to:

• Make sure all alkiln devs uses the right command. Can we somehow prevent people from using plain npm install? I haven't been able to find a way.
• npm audit more regularly perhaps?

Research:
npm ci instead of npm install

It will install the project dependencies based on the package-lock.json file instead of the lenient package.json file dependencies.

• https://stackoverflow.com/a/53680257/14144258 (2018)

npm ci will only use the lock file and disregard the package.json. It's more useful in, well, CI, and when building Docker images. You'd still want to use npm install for local development.

• Add option: npm install --from-lock-file npm/npm#18286 (comment)

Some lock-file only flag (I think this was possibly never implemented)

In the future, you will be able to use a --from-lock-file (or similar) flag to install only from the package-lock.json without modifying it.

• https://stackoverflow.com/a/46613465/14144258 (2017)

Alternative: Remove

As an alternative, if we're not sticking to the package-lock.json I propose we get rid of our own and add it to the .gitignore so that we'll have an experience that's closer to the one our users have.

Proposal History

2022/03/26

• Proposal changed to reflect updated goals addressing concerns
• @BryceStevenWilley responded 1 with concerns
• @plocket responded 5
• Proposal made

[plocket]

I'm a 5, willing to be one of leaders, but my bandwidth is limited. I'll post that in the Slack as well, where the visual feedback takes place.

[BryceStevenWilley]

I'm a 1: Question: how exactly do we "copy our own package-lock.json" into the Github action? It's much too big to include the contents of it in the action.yml like we do now, and I'm not sure we'd want to download it from github or something. I just discovered that package-lock.jsons aren't uploaded with the package to the npm registry (aka "published"). After reading through the docs for a bit, I think what we want is to publish an npm-shrinkwrap.json file with the package: "Unlike package-lock.json, npm-shrinkwrap.json may be included when publishing a package.". The docs say that it's useful for cli tools and applications, and discouraged for libraries. I think we fall under a cli-tool, and definitely not an application.

I think some of the confusion between all of the posts talking about npm ci and npm install behavior is that most are talking about development on a package (i.e. you have downloaded a copy of source and are editing it locally when you run npm install), and they aren't talking about downloading a package from scratch.

To clarify, I am a 4 on the spirit of the idea: we should be more strict with version pinning, I'm just not sure how it would work.

[plocket]

Thanks for that research! I see a number of concerns brought up.

1. package-lock.json is too big to include in our own action.yml.
2. npm ci is often used when talking about a package that is already installed - one that already has a package-lock.json.
3. package-lock.json isn't uploaded to the npm registry, so we wouldn't be able to copy it from the installed package (and that was my previous plan). We might need to use npm-shrinkwrap.json instead.

I totally agree with 1.

2 is exactly what the previous plan would have hoped to address. Providing a package-lock.json would behave as if the package had already been installed sometime in the past.

3 sounds like a great solution as long as we can figure out the workflow for it. I'll update the proposal to reflect following that thread instead.

Edit:
npm-shrinkwrap.json research questions to add to an issue or other discussion:

• How do we update npm-shrinkwrap.json when needed?
• How do we prevent updating npm-shrinkwrap.json at other times?

Research

• npm docs
• Someone's confusing 2018 gist discussion

My understanding of the flow so far:

1. npm install updates the package-lock.json. I'm not completely sure of this. It may update npm-shrinkwrap.json instead if that's present. We'll have to test this out over time if we can't find more information.
2. npm shrinkwrap copies package-lock.json into npm-shrinkwrap.json.
3. A package that runs npm install using our package will defer to npm-shrinkwrap.json

I think we should be able to copy our shrinkwrap into our users' files without breaking things so that they install the same versions of everything (since they do need their own version of cucumber).

Further research

update command will [bring in files] using package.json while install command will use npm-shrinkwrap.json.

• https://stackoverflow.com/a/41103942/14144258 (2016)

The three rules I listed above conflict, so let's try again, summarizing 2016 https://stackoverflow.com/a/41103942/14144258:

1. npm install will use npm-shrinkwrap.json
2. npm install newPkg --save "will change both package.json and npm-shrinkwrap.json file as well"
3. npm update pkg --save will, if I understand correctly, use package.json to update npm-shrinkwrap.json according to semver

That stackoverflow is very old, so I'm not sure how close current behavior is to that.

More info:

EDIT: I figured out that npm install --no-shrinkwrap prevents the file from being updated

• npm-shrinkwrap is updated and versions are changed erroneously npm/npm#18722 (comment) (2018) (nodejs 8.9.4/ npm 5.6.0)

We can't use our own shrinkwrap to update the user's shrinkwrap because our shrinkwrap won't include our own package. We'll have to get it from installing the latest version on a dependency.

Note:

[unmet dependency] will be considered hard errors by shrinkwrap

• Someone's confusing 2018 gist discussion

[BryceStevenWilley]

For historical reference, #697 implemented shrinkwrap. If discussions could be "accepted", this would be the accepted answer. Gonna close the discussion for now, as new issues that arise with shrinkwrap can be made as normal issues.

[plocket]

When ready, folks should update their response to the proposal changes in Slack.