feat!: native dependency patching (npm patch add/commit/update/ls/rm)

DEPENDENCIES.md

@@ -529,6 +529,7 @@ graph LR;
   npmcli-arborist-->bin-links;
   npmcli-arborist-->cacache;
   npmcli-arborist-->common-ancestor-path;
+  npmcli-arborist-->diff;
   npmcli-arborist-->gar-promise-retry["@gar/promise-retry"];
   npmcli-arborist-->hosted-git-info;
   npmcli-arborist-->isaacs-string-locale-compare["@isaacs/string-locale-compare"];

docs/lib/content/commands/npm-patch.md

@@ -0,0 +1,69 @@
+---
+title: npm-patch
+section: 1
+description: Apply local patches to installed dependencies
+---
+
+### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS -->
+
+### Description
+
+`npm patch` lets you apply small, local modifications to an installed
+dependency and have them re-applied automatically on every install. Patches
+are declared in the `patchedDependencies` field of your root `package.json`,
+stored as plain unified diffs under the `patches/` directory, and recorded with
+a content hash in `package-lock.json`.
+
+Because patches are applied during the install itself, they work regardless of
+`install-strategy`, apply to transitive dependencies, and are **not** disabled
+by `--ignore-scripts`.
+
+The bare form `npm patch <pkg>` is shorthand for `npm patch add <pkg>`. A
+package literally named like a subcommand must use the explicit form, e.g.
+`npm patch add add`.
+
+* `npm patch add <pkg>[@<version>]`
+
+    Prepares a package for editing. npm extracts a clean copy of the resolved
+    package tarball into a temporary directory outside `node_modules` and prints
+    its path. Edit the files there, then run `npm patch commit`.
+
+    If more than one version of `<pkg>` is installed, re-run with an exact
+    selector such as `npm patch add lodash@4.17.21`.
+
+* `npm patch commit <edit-dir>`
+
+    Diffs the edited directory against a clean copy of the original tarball,
+    writes the unified diff to `<patches-dir>/<name>@<version>.patch`, adds the
+    entry to `patchedDependencies`, and updates `package-lock.json`.
+
+* `npm patch ls`
+
+    Lists registered patches and how many installed nodes each one matches.
+
+* `npm patch rm <pkg>[@<version>]`
+
+    Removes the matching entries from `patchedDependencies`, deletes the patch
+    file when no other entry references it, and updates `package-lock.json`. If
+    `<version>` is omitted, all entries for `<pkg>` are removed.
+
+### Failure modes
+
+By default any patch problem is a hard error that aborts the install: a patch
+that fails to apply, a registered patch that matches no installed package, a
+missing patch file, or a patch whose hash does not match the lockfile.
+
+Two CLI-only flags relax this for one-off cases: `--allow-unused-patches` and
+`--ignore-patch-failures`.
+
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->
+## See Also
+
+* [npm install](/commands/npm-install)
+* [npm ci](/commands/npm-ci)
+* [package-lock.json](/configuring-npm/package-lock-json)
+* [config](/commands/npm-config)

docs/lib/content/nav.yml

@@ -120,6 +120,9 @@
   - title: npm pack
     url: /commands/npm-pack
     description: Create a tarball from a package
+  - title: npm patch
+    url: /commands/npm-patch
+    description: Apply local patches to installed dependencies
   - title: npm ping
     url: /commands/npm-ping
     description: Ping npm registry

lib/commands/audit.js

@@ -4,6 +4,7 @@ const auditError = require('../utils/audit-error.js')
 const { log, output } = require('proc-log')
 const reifyFinish = require('../utils/reify-finish.js')
 const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
+const { patchRelaxOpts } = require('../utils/cli-only-flag.js')
 const VerifySignatures = require('../utils/verify-signatures.js')
 
 class Audit extends ArboristWorkspaceCmd {
@@ -62,6 +63,8 @@ class Audit extends ArboristWorkspaceCmd {
     const { policy: allowScriptsPolicy } = await resolveAllowScripts(this.npm)
     const opts = {
       ...this.npm.flatOptions,
+      // audit fix reifies, so honor the cli-only patch relax flags
+      ...patchRelaxOpts(this.npm.config),
       audit: true,
       path: this.npm.prefix,
       reporter,

lib/commands/ci.js

@@ -44,6 +44,15 @@ class CI extends ArboristWorkspaceCmd {
       })
     }
 
+    // npm ci is always strict about patches; the relax flags are not accepted
+    for (const flag of ['allow-unused-patches', 'ignore-patch-failures']) {
+      if (this.npm.config.find(flag) === 'cli') {
+        throw Object.assign(new Error(`The --${flag} flag is not allowed with \`npm ci\`.`), {
+          code: 'ECIPATCHFLAG',
+        })
+      }
+    }
+
     const dryRun = this.npm.config.get('dry-run')
     const ignoreScripts = this.npm.config.get('ignore-scripts')
     const where = this.npm.prefix

lib/commands/dedupe.js

@@ -1,5 +1,6 @@
 const reifyFinish = require('../utils/reify-finish.js')
 const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
+const { patchRelaxOpts } = require('../utils/cli-only-flag.js')
 const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 
 // dedupe duplicated packages, or find them in the tree
@@ -47,6 +48,7 @@ class Dedupe extends ArboristWorkspaceCmd {
       save: false,
       workspaces: this.workspaceNames,
       allowScripts: allowScriptsPolicy,
+      ...patchRelaxOpts(this.npm.config),
     }
     const arb = new Arborist(opts)
     await arb.dedupe(opts)

lib/commands/install.js

@@ -7,6 +7,7 @@ const checks = require('npm-install-checks')
 const reifyFinish = require('../utils/reify-finish.js')
 const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
 const strictAllowScriptsPreflight = require('../utils/strict-allow-scripts-preflight.js')
+const { patchRelaxOpts } = require('../utils/cli-only-flag.js')
 const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 
 class Install extends ArboristWorkspaceCmd {
@@ -151,6 +152,8 @@ class Install extends ArboristWorkspaceCmd {
       add: args,
       workspaces: this.workspaceNames,
       allowScripts: allowScriptsPolicy,
+      // patch relax flags are honored only when passed on the command line
+      ...patchRelaxOpts(this.npm.config),
     }
 
     // Root lifecycle scripts only run for a bare `npm install` in a local project. `preinstall` runs *before* Arborist touches the filesystem so that scripts can bootstrap the environment (e.g. set up private-registry auth, generate files consumed during resolution) before dependencies are fetched or unpacked. The remaining scripts run after reify as they did before.

lib/commands/link.js

@@ -5,6 +5,7 @@ const pkgJson = require('@npmcli/package-json')
 const semver = require('semver')
 const reifyFinish = require('../utils/reify-finish.js')
 const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
+const { patchRelaxOpts } = require('../utils/cli-only-flag.js')
 const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 
 class Link extends ArboristWorkspaceCmd {
@@ -70,6 +71,7 @@ class Link extends ArboristWorkspaceCmd {
     const Arborist = require('@npmcli/arborist')
     const globalOpts = {
       ...this.npm.flatOptions,
+      ...patchRelaxOpts(this.npm.config),
       Arborist,
       path: globalTop,
       global: true,
@@ -119,6 +121,7 @@ class Link extends ArboristWorkspaceCmd {
     const { policy: allowScriptsPolicy } = await resolveAllowScripts(this.npm)
     const localArb = new Arborist({
       ...this.npm.flatOptions,
+      ...patchRelaxOpts(this.npm.config),
       prune: false,
       path: this.npm.prefix,
       save,
@@ -145,6 +148,7 @@ class Link extends ArboristWorkspaceCmd {
     const Arborist = require('@npmcli/arborist')
     const arb = new Arborist({
       ...this.npm.flatOptions,
+      ...patchRelaxOpts(this.npm.config),
       Arborist,
       path: globalTop,
       global: true,

lib/commands/ls.js

@@ -333,6 +333,11 @@ const getHumanOutputItem = (node, { args, chalk, global, long }) => {
         ? ' ' + chalk.dim('overridden')
         : ''
     ) +
+    (
+      node.patched
+        ? ' ' + chalk.cyan(`[patched: ${node.patched.path}]`)
+        : ''
+    ) +
     (isGitNode(node) ? ` (${node.resolved})` : '') +
     (node.isLink ? ` -> ${relativePrefix}${targetLocation}` : '') +
     (long ? `\n${node.package.description || ''}` : '')
@@ -389,6 +394,10 @@ const getJsonOutputItem = (node, { global, long }) => {
     item.invalid = node[_invalid]
   }
 
+  if (node.patched) {
+    item.patched = node.patched.path
+  }
+
   if (node[_missing] && !isOptional(node)) {
     item.required = node[_required]
     item.missing = true