fixup! RFC: Add npm diff

accepted/0000-npm-diff.md

@@ -2,54 +2,62 @@
 
 ## Summary
 
-Add a new command that enables diff workflows (similar to `git diff`) for packages published in the registry.
+Add a new command that enables diff workflows (similar to `git diff`) for
+packages published in the registry.
 
 ## Motivation
 
-- Complements `npm audit` and `npm outdated` workflows by providing insight on what changed across different package versions
-- Enables package authors to diff packlist-tracked-only file changes prior to publishing a new version of a package
+- Package Consumers: Complements `npm audit` and `npm 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.
 
 ## Detailed Explanation
 
-Introduce a new `npm diff` command that will fetch tarball contents for two different versions of a module and print that output in an usable format to users.
+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.
 
 ### npm diff `<spec>`
 
-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.
-
-<img alt="Demo showing npm diff pkg in a repo with an actual tree installed" src="https://ruyadorno.github.io/svg-demos/npm-diff/npm-diff-yargs.svg" />
+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.
 
 ### npm diff `<spec-a>` `<spec-b>`
 
-Fetches tarball contents of two versions of a package, represented by `<spec-a>` and `<spec-b>` and prints diff output.
-
-<img alt="Demo showing npm diff pkg in a repo with an actual tree installed" src="https://ruyadorno.github.io/svg-demos/npm-diff/npm-diff-simple-output.svg" />
-
-### npm diff --changelog
-
-Filter to only show CHANGELOG changes, makes the command more useful for printing content of larger packages.
-
-<img alt="Demo showing npm diff pkg in a repo with an actual tree installed" src="https://ruyadorno.github.io/svg-demos/npm-diff/npm-diff-changelog.svg?update=1" />
+Fetches/reads contents of two versions of a package, represented by
+`<spec-a>` and `<spec-b>` and prints diff output.
 
 ### npm diff (no arguments)
 
-Meant as a helper tool to package authors, prints diff output between the current fs (tracked by packlist) and the last published version of that package.
-
-<img alt="Demo showing npm diff pkg in a repo with an actual tree installed" src="https://ruyadorno.github.io/svg-demos/npm-diff/npm-diff-no-args.svg?foo=bar" />
+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.
 
 ## Rationale
 
-- 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.
-- Given the very long tail of packages published in the registry, a vast majority of packages sit somewhere below the 100LOC or a single function or whatever other measurement unit to define the pattern of very specialized and small packages adopted by the JavaScript ecosystem (speaking from personal experience here but maybe we can get some numbers to validate this assumption in case this is a contentious statement) - thus being perfect candidates to a simple review of the diff patches between versions.
-- It feels very natural to have a `npm diff` from the point of view of a heavy user of `git diff`s - It does provide much more quick insight on code that makes its way into our projects in a ([medium](https://en.wikipedia.org/wiki/Diff#Unified_format)) that most developers are already familiar with.
+- 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 of `git diff`s - It does provide much more quick insight and transparency
+on code that makes its way into our projects in a
+([medium](https://en.wikipedia.org/wiki/Diff#Unified_format)) that most
+developers are already familiar with.
 
 ## Alternatives
 
-- Leave the problem to userland and not ship a native `npm diff` command
+- Not have a native `npm diff` command and deffer to userland solutions tools.
 
 ## Implementation
 
-Simply fetches two different tarballs from the registry (or reads from current fs if only comparing current version) and run a simple diff of each file, providing an usable output for users to work with.
+Reads two different specs using pacote and run a diff of each file,
+providing an usable patch output for users to work with.
 
 ## Prior Art