Add a new command that enables diff workflows (similar to git diff
) for
packages published in the registry.
- Package Consumers: Complements
npm audit
andnpm outdated
workflows by providing insight on what changed across different versions of a package. - Package Authors: Enables diff packlist-tracked-only file changes prior to publishing a new version of a package, or while debugging past changes.
Introduce a new npm diff
command that accepts one or more package specs and
uses these specs to compare files and print diff patches. Contents are fetched
using pacote
, accepting any type of specs that the npm installer understands.
Using a single <spec>
allows users to retrieve diff output between an
existing valid version of a package with the same name found in the actual
dependency tree and the exact <spec>
match from the registry.
Fetches/reads contents of two versions of a package, represented by
<spec-a>
and <spec-b>
and prints diff output.
Meant as a helper tool to package authors, prints diff output between the current file system dirs/files (tracked by packlist) and the last published version of that package.
- A very common workflow is using npm outdated to figure out what dependencies need update and then manually reviewing what changed in between the current version you have in your project and whatever you can update to. That workflow involves multiple steps, some of them being extra mental hurdle (such as keeping track of the semver versions change and their meaning) some other very manual such as jumping around to repos, scanning through changelogs, veryfing semver contract is respected, etc.
- It feels very natural to have a
npm diff
from the point of view of a user ofgit diff
s - It does provide much more quick insight and transparency on code that makes its way into our projects in a (medium) that most developers are already familiar with.
- Not have a native
npm diff
command and deffer to userland tools.
Parses user args and reads package contents for two different specs and run a diff of each file, providing an usable patch output for users to work with.
What should happen if using npm diff
(no args) ?
What should be the expected behavior when using npm diff --diff=<pkg>
?
What if I use two --diff=<pkg>@<version>
arguments?
Here's some of the sketch ideas that were initially put together to try and answer these questions:
- IF NO arg:
- READ
package.json
name- IF FOUND:
- RETURN
package-json-name@tag
-file:.
- RETURN
- ELSE:
- THROW usage
- IF FOUND:
- READ
- IF arg is
package-name
only:- READ arborist load actual tree AND PARSE
package-name
- IF NOT SPEC TYPE REGISTRY:
- THROW unsupported spec type
- IF FOUND:
- RETURN
package-name@FOUND_VERSION
- RETURN
- ELSE:
- RETURN
package-name@latest
- RETURN
- IF NOT SPEC TYPE REGISTRY:
- READ arborist load actual tree AND PARSE
- IF arg is validl semver range|version:
- READ
package-name
from either arg1 or arg2- IF FOUND:
- RETURN
other-arg-parsed-name@arg
- RETURN
- ELSE:
- READ
package.json
name- IF FOUND:
- RETURN
package-json-name@arg
- RETURN
- IF NO
package.json
:- THROW error need to run from package dir to user versions
- IF FOUND:
- READ
- IF FOUND:
- READ
This argument parsing part of the implementation lives in the npm cli: