@npmcli/arborist 4.0.3 → 4.1.1

package/LICENSE.md

@@ -0,0 +1,20 @@
+<!-- This file is automatically added by @npmcli/template-oss. Do not edit. -->
+
+ISC License
+
+Copyright npm, Inc.
+
+Permission to use, copy, modify, and/or distribute this
+software for any purpose with or without fee is hereby
+granted, provided that the above copyright notice and this
+permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND NPM DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL NPM BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
+USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -2,10 +2,10 @@
 
 Inspect and manage `node_modules` trees.
 
-![a tree with the word ARBORIST superimposed on it](https://raw.githubusercontent.com/npm/arborist/main/logo.svg?sanitize=true)
+![a tree with the word ARBORIST superimposed on it](https://raw.githubusercontent.com/npm/arborist/main/docs/logo.svg?sanitize=true)
 
-There's more documentation [in the notes
-folder](https://github.com/npm/arborist/tree/main/notes).
+There's more documentation [in the docs
+folder](https://github.com/npm/arborist/tree/main/docs).
 
 ## USAGE
 

package/bin/prune.js

@@ -6,7 +6,7 @@ require('./lib/logging.js')
 require('./lib/timers.js')
 
 const printDiff = diff => {
-  const {depth} = require('treeverse')
+  const { depth } = require('treeverse')
   depth({
     tree: diff,
     visit: d => {

package/bin/reify.js

@@ -6,7 +6,7 @@ require('./lib/logging.js')
 require('./lib/timers.js')
 
 const printDiff = diff => {
-  const {depth} = require('treeverse')
+  const { depth } = require('treeverse')
   depth({
     tree: diff,
     visit: d => {

package/lib/add-rm-pkg-deps.js

@@ -2,9 +2,9 @@
 
 const localeCompare = require('@isaacs/string-locale-compare')('en')
 
-const add = ({pkg, add, saveBundle, saveType, log}) => {
+const add = ({ pkg, add, saveBundle, saveType, log }) => {
   for (const spec of add) {
-    addSingle({pkg, spec, saveBundle, saveType, log})
+    addSingle({ pkg, spec, saveBundle, saveType, log })
   }
 
   return pkg
@@ -20,7 +20,7 @@ const saveTypeMap = new Map([
   ['peer', 'peerDependencies'],
 ])
 
-const addSingle = ({pkg, spec, saveBundle, saveType, log}) => {
+const addSingle = ({ pkg, spec, saveBundle, saveType, log }) => {
   const { name, rawSpec } = spec
 
   // if the user does not give us a type, we infer which type(s)

package/lib/arborist/build-ideal-tree.js

@@ -31,7 +31,7 @@ const Node = require('../node.js')
 const Link = require('../link.js')
 const addRmPkgDeps = require('../add-rm-pkg-deps.js')
 const optionalSet = require('../optional-set.js')
-const {checkEngine, checkPlatform} = require('npm-install-checks')
+const { checkEngine, checkPlatform } = require('npm-install-checks')
 
 const relpath = require('../relpath.js')
 
@@ -311,7 +311,7 @@ module.exports = cls => class IdealTreeBuilder extends cls {
         ? Shrinkwrap.reset({
           path: this.path,
           lockfileVersion: this.options.lockfileVersion,
-        }).then(meta => Object.assign(root, {meta}))
+        }).then(meta => Object.assign(root, { meta }))
         : this.loadVirtual({ root }))
 
       // if we don't have a lockfile to go from, then start with the
@@ -379,6 +379,7 @@ module.exports = cls => class IdealTreeBuilder extends cls {
       optional: false,
       global: this[_global],
       legacyPeerDeps: this.legacyPeerDeps,
+      loadOverrides: true,
     })
     if (root.isLink) {
       root.target = new Node({
@@ -492,7 +493,7 @@ module.exports = cls => class IdealTreeBuilder extends cls {
 
   // This returns a promise because we might not have the name yet,
   // and need to call pacote.manifest to find the name.
-  [_add] (tree, {add, saveType = null, saveBundle = false}) {
+  [_add] (tree, { add, saveType = null, saveBundle = false }) {
     // get the name for each of the specs in the list.
     // ie, doing `foo@bar` we just return foo
     // but if it's a url or git, we don't know the name until we
@@ -676,6 +677,7 @@ module.exports = cls => class IdealTreeBuilder extends cls {
     // calls rather than walking over everything in the tree.
     const set = this.idealTree.inventory
       .filter(n => this[_shouldUpdateNode](n))
+    // XXX add any invalid edgesOut to the queue
     for (const node of set) {
       for (const edge of node.edgesIn) {
         this.addTracker('idealTree', edge.from.name, edge.from.location)
@@ -772,7 +774,10 @@ This is a one-time fix-up, please be patient...
   [_buildDeps] () {
     process.emit('time', 'idealTree:buildDeps')
     const tree = this.idealTree.target
+    tree.assertRootOverrides()
     this[_depsQueue].push(tree)
+    // XXX also push anything that depends on a node with a name
+    // in the override list
     this.log.silly('idealTree', 'buildDeps')
     this.addTracker('idealTree', tree.name, '')
     return this[_buildDepStep]()
@@ -936,7 +941,7 @@ This is a one-time fix-up, please be patient...
         }
       })
 
-      tasks.push({edge, dep})
+      tasks.push({ edge, dep })
     }
 
     const placeDeps = tasks
@@ -1112,6 +1117,7 @@ This is a one-time fix-up, please be patient...
       path: node.realpath,
       sourceReference: node,
       legacyPeerDeps: this.legacyPeerDeps,
+      overrides: node.overrides,
     })
 
     // also need to set up any targets from any link deps, so that
@@ -1271,7 +1277,7 @@ This is a one-time fix-up, please be patient...
       // we typically only install non-optional peers, but we have to
       // factor them into the peerSet so that we can avoid conflicts
       .filter(e => e.peer && !(e.valid && e.to))
-      .sort(({name: a}, {name: b}) => localeCompare(a, b))
+      .sort(({ name: a }, { name: b }) => localeCompare(a, b))
 
     for (const edge of peerEdges) {
       // already placed this one, and we're happy with it.
@@ -1280,7 +1286,7 @@ This is a one-time fix-up, please be patient...
       }
 
       const parentEdge = node.parent.edgesOut.get(edge.name)
-      const {isProjectRoot, isWorkspace} = node.parent.sourceReference
+      const { isProjectRoot, isWorkspace } = node.parent.sourceReference
       const isMine = isProjectRoot || isWorkspace
       const conflictOK = this[_force] || !isMine && !this[_strictPeerDeps]
 

package/lib/arborist/index.js

@@ -26,9 +26,10 @@
 // the base class, so that the overall voltron class is easier to test and
 // cover, and separation of concerns can be maintained.
 
-const {resolve} = require('path')
-const {homedir} = require('os')
+const { resolve } = require('path')
+const { homedir } = require('os')
 const procLog = require('proc-log')
+const { depth } = require('treeverse')
 const { saveTypeMap } = require('../add-rm-pkg-deps.js')
 
 const mixins = [
@@ -88,6 +89,9 @@ class Arborist extends Base {
     process.emit('timeEnd', 'arborist:ctor')
   }
 
+  // TODO: We should change these to static functions instead
+  //   of methods for the next major version
+
   // returns an array of the actual nodes for all the workspaces
   workspaceNodes (tree, workspaces) {
     return getWorkspaceNodes(tree, workspaces, this.log)
@@ -103,15 +107,15 @@ class Arborist extends Base {
         }
       }
     }
-    const set = new Set(wsNodes)
+    const wsDepSet = new Set(wsNodes)
     const extraneous = new Set()
-    for (const node of set) {
+    for (const node of wsDepSet) {
       for (const edge of node.edgesOut.values()) {
         const dep = edge.to
         if (dep) {
-          set.add(dep)
+          wsDepSet.add(dep)
           if (dep.isLink) {
-            set.add(dep.target)
+            wsDepSet.add(dep.target)
           }
         }
       }
@@ -122,28 +126,36 @@ class Arborist extends Base {
       }
     }
     for (const extra of extraneous) {
-      set.add(extra)
+      wsDepSet.add(extra)
     }
 
-    return set
+    return wsDepSet
   }
 
+  // returns a set of root dependencies, excluding depdencies that are
+  // exclusively workspace dependencies
   excludeWorkspacesDependencySet (tree) {
-    const set = new Set()
-    for (const edge of tree.edgesOut.values()) {
-      if (edge.type !== 'workspace' && edge.to) {
-        set.add(edge.to)
-      }
-    }
-    for (const node of set) {
-      for (const edge of node.edgesOut.values()) {
-        if (edge.to) {
-          set.add(edge.to)
+    const rootDepSet = new Set()
+    depth({
+      tree,
+      visit: node => {
+        for (const { to } of node.edgesOut.values()) {
+          if (!to || to.isWorkspace) {
+            continue
+          }
+          for (const edgeIn of to.edgesIn.values()) {
+            if (edgeIn.from.isRoot || rootDepSet.has(edgeIn.from)) {
+              rootDepSet.add(to)
+            }
+          }
         }
-      }
-    }
-
-    return set
+        return node
+      },
+      filter: node => node,
+      getChildren: (node, tree) =>
+        [...tree.edgesOut.values()].map(edge => edge.to),
+    })
+    return rootDepSet
   }
 }
 

package/lib/arborist/load-actual.js

@@ -1,9 +1,9 @@
 // mix-in implementing the loadActual method
 
-const {relative, dirname, resolve, join, normalize} = require('path')
+const { relative, dirname, resolve, join, normalize } = require('path')
 
 const rpj = require('read-package-json-fast')
-const {promisify} = require('util')
+const { promisify } = require('util')
 const readdir = promisify(require('readdir-scoped-modules'))
 const walkUp = require('walk-up-path')
 const ancestorPath = require('common-ancestor-path')
@@ -127,16 +127,20 @@ module.exports = cls => class ActualLoader extends cls {
         realpath: real,
         pkg: {},
         global,
+        loadOverrides: true,
       })
-      return this[_loadActualActually]({root, ignoreMissing, global})
+      return this[_loadActualActually]({ root, ignoreMissing, global })
     }
 
     // not in global mode, hidden lockfile is allowed, load root pkg too
     this[_actualTree] = await this[_loadFSNode]({
       path: this.path,
       real: await realpath(this.path, this[_rpcache], this[_stcache]),
+      loadOverrides: true,
     })
 
+    this[_actualTree].assertRootOverrides()
+
     // Note: hidden lockfile will be rejected if it's not the latest thing
     // in the folder, or if any of the entries in the hidden lockfile are
     // missing.
@@ -163,7 +167,7 @@ module.exports = cls => class ActualLoader extends cls {
     // we can't easily get a ref to Arborist in this module, without
     // creating a circular reference, since this class is a mixin used
     // to build up the Arborist class itself.
-    await new this.constructor({...this.options}).loadVirtual({
+    await new this.constructor({ ...this.options }).loadVirtual({
       root: this[_actualTree],
     })
     await this[_loadWorkspaces](this[_actualTree])
@@ -236,13 +240,26 @@ module.exports = cls => class ActualLoader extends cls {
     this[_actualTree] = root
   }
 
-  [_loadFSNode] ({ path, parent, real, root }) {
+  [_loadFSNode] ({ path, parent, real, root, loadOverrides }) {
     if (!real) {
       return realpath(path, this[_rpcache], this[_stcache])
         .then(
-          real => this[_loadFSNode]({ path, parent, real, root }),
+          real => this[_loadFSNode]({
+            path,
+            parent,
+            real,
+            root,
+            loadOverrides,
+          }),
           // if realpath fails, just provide a dummy error node
-          error => new Node({ error, path, realpath: path, parent, root })
+          error => new Node({
+            error,
+            path,
+            realpath: path,
+            parent,
+            root,
+            loadOverrides,
+          })
         )
     }
 
@@ -271,6 +288,7 @@ module.exports = cls => class ActualLoader extends cls {
           error,
           parent,
           root,
+          loadOverrides,
         })
       })
       .then(node => {

package/lib/arborist/load-virtual.js

@@ -1,7 +1,7 @@
 // mixin providing the loadVirtual method
 const localeCompare = require('@isaacs/string-locale-compare')('en')
 
-const {resolve} = require('path')
+const { resolve } = require('path')
 
 const nameFromFolder = require('@npmcli/name-from-folder')
 const consistentResolve = require('../consistent-resolve.js')
@@ -72,6 +72,7 @@ module.exports = cls => class VirtualLoader extends cls {
     this[rootOptionProvided] = options.root
 
     await this[loadFromShrinkwrap](s, root)
+    root.assertRootOverrides()
     return treeCheck(this.virtualTree)
   }
 
@@ -97,7 +98,7 @@ module.exports = cls => class VirtualLoader extends cls {
     this[checkRootEdges](s, root)
     root.meta = s
     this.virtualTree = root
-    const {links, nodes} = this[resolveNodes](s, root)
+    const { links, nodes } = this[resolveNodes](s, root)
     await this[resolveLinks](links, nodes)
     if (!(s.originalLockfileVersion >= 2)) {
       this[assignBundles](nodes)
@@ -208,7 +209,7 @@ module.exports = cls => class VirtualLoader extends cls {
         nodes.set(location, this[loadNode](location, meta))
       }
     }
-    return {links, nodes}
+    return { links, nodes }
   }
 
   // links is the set of metadata, and nodes is the map of non-Link nodes
@@ -240,7 +241,7 @@ module.exports = cls => class VirtualLoader extends cls {
       if (!location || node.isLink && !node.target.location) {
         continue
       }
-      const { name, parent, package: { inBundle }} = node
+      const { name, parent, package: { inBundle } } = node
 
       if (!parent) {
         continue

package/lib/arborist/rebuild.js

@@ -2,13 +2,13 @@
 // bundle building needed.  Called by reify, and by `npm rebuild`.
 
 const localeCompare = require('@isaacs/string-locale-compare')('en')
-const {depth: dfwalk} = require('treeverse')
+const { depth: dfwalk } = require('treeverse')
 const promiseAllRejectLate = require('promise-all-reject-late')
 const rpj = require('read-package-json-fast')
 const binLinks = require('bin-links')
 const runScript = require('@npmcli/run-script')
 const promiseCallLimit = require('promise-call-limit')
-const {resolve} = require('path')
+const { resolve } = require('path')
 const {
   isNodeGypPackage,
   defaultGypInstallScript,
@@ -220,7 +220,7 @@ module.exports = cls => class Builder extends cls {
     }
 
     if (this[_oldMeta] === null) {
-      const {root: {meta}} = node
+      const { root: { meta } } = node
       this[_oldMeta] = meta && meta.loadedFromDisk &&
         !(meta.originalLockfileVersion >= 2)
     }
@@ -242,7 +242,7 @@ module.exports = cls => class Builder extends cls {
       const pkg = await rpj(node.path + '/package.json').catch(() => ({}))
       set.delete(node)
 
-      const {scripts = {}} = pkg
+      const { scripts = {} } = pkg
       node.package.scripts = scripts
       return this[_addToBuildSet](node, set, true)
     }
@@ -319,9 +319,9 @@ module.exports = cls => class Builder extends cls {
       }
       const p = runScript(runOpts).catch(er => {
         const { code, signal } = er
-        this.log.info('run', pkg._id, event, {code, signal})
+        this.log.info('run', pkg._id, event, { code, signal })
         throw er
-      }).then(({args, code, signal, stdout, stderr}) => {
+      }).then(({ args, code, signal, stdout, stderr }) => {
         this.scriptsRun.add({
           pkg,
           path,
@@ -333,7 +333,7 @@ module.exports = cls => class Builder extends cls {
           stdout,
           stderr,
         })
-        this.log.info('run', pkg._id, event, {code, signal})
+        this.log.info('run', pkg._id, event, { code, signal })
       })
 
       await (this[_doHandleOptionalFailure]

package/lib/arborist/reify.js

@@ -3,15 +3,15 @@
 const onExit = require('../signal-handling.js')
 const pacote = require('pacote')
 const AuditReport = require('../audit-report.js')
-const {subset, intersects} = require('semver')
+const { subset, intersects } = require('semver')
 const npa = require('npm-package-arg')
 const debug = require('../debug.js')
 const walkUp = require('walk-up-path')
 
-const {dirname, resolve, relative} = require('path')
-const {depth: dfwalk} = require('treeverse')
+const { dirname, resolve, relative } = require('path')
+const { depth: dfwalk } = require('treeverse')
 const fs = require('fs')
-const {promisify} = require('util')
+const { promisify } = require('util')
 const lstat = promisify(fs.lstat)
 const symlink = promisify(fs.symlink)
 const mkdirp = require('mkdirp-infer-owner')
@@ -188,7 +188,7 @@ module.exports = cls => class Reifier extends cls {
     // ok, we're about to start touching the fs.  need to roll back
     // if we get an early termination.
     let reifyTerminated = null
-    const removeHandler = onExit(({signal}) => {
+    const removeHandler = onExit(({ signal }) => {
       // only call once.  if signal hits twice, we just terminate
       removeHandler()
       reifyTerminated = Object.assign(new Error('process terminated'), {
@@ -352,7 +352,7 @@ module.exports = cls => class Reifier extends cls {
       if (includeRootDeps) {
         // add all non-workspace nodes to filterNodes
         for (const tree of [this.idealTree, this.actualTree]) {
-          for (const {type, to} of tree.edgesOut.values()) {
+          for (const { type, to } of tree.edgesOut.values()) {
             if (type !== 'workspace' && to) {
               filterNodes.push(to)
             }
@@ -686,7 +686,7 @@ module.exports = cls => class Reifier extends cls {
   }
 
   [_warnDeprecated] (node) {
-    const {_id, deprecated} = node.package
+    const { _id, deprecated } = node.package
     if (deprecated) {
       this.log.warn('deprecated', `${_id}: ${deprecated}`)
     }
@@ -1159,7 +1159,7 @@ module.exports = cls => class Reifier extends cls {
         const edge = addTree.edgesOut.get(name)
         const pkg = addTree.package
         const req = npa.resolve(name, edge.spec, addTree.realpath)
-        const {rawSpec, subSpec} = req
+        const { rawSpec, subSpec } = req
 
         const spec = subSpec ? subSpec.rawSpec : rawSpec
         const child = edge.to
@@ -1173,6 +1173,10 @@ module.exports = cls => class Reifier extends cls {
         }
 
         let newSpec
+        // True if the dependency is getting installed from a local file path
+        // In this case it is not possible to do the normal version comparisons
+        // as the new version will be a file path
+        const isLocalDep = req.type === 'directory' || req.type === 'file'
         if (req.registry) {
           const version = child.version
           const prefixRange = version ? this[_savePrefix] + version : '*'
@@ -1204,7 +1208,7 @@ module.exports = cls => class Reifier extends cls {
           } else {
             newSpec = h.shortcut(opt)
           }
-        } else if (req.type === 'directory' || req.type === 'file') {
+        } else if (isLocalDep) {
           // save the relative path in package.json
           // Normally saveSpec is updated with the proper relative
           // path already, but it's possible to specify a full absolute
@@ -1233,11 +1237,11 @@ module.exports = cls => class Reifier extends cls {
           if (hasSubKey(pkg, 'devDependencies', name)) {
             pkg.devDependencies[name] = newSpec
             // don't update peer or optional if we don't have to
-            if (hasSubKey(pkg, 'peerDependencies', name) && !intersects(newSpec, pkg.peerDependencies[name])) {
+            if (hasSubKey(pkg, 'peerDependencies', name) && (isLocalDep || !intersects(newSpec, pkg.peerDependencies[name]))) {
               pkg.peerDependencies[name] = newSpec
             }
 
-            if (hasSubKey(pkg, 'optionalDependencies', name) && !intersects(newSpec, pkg.optionalDependencies[name])) {
+            if (hasSubKey(pkg, 'optionalDependencies', name) && (isLocalDep || !intersects(newSpec, pkg.optionalDependencies[name]))) {
               pkg.optionalDependencies[name] = newSpec
             }
           } else {

package/lib/audit-report.js

@@ -265,7 +265,7 @@ class AuditReport extends Map {
         avoid: vuln.range,
         avoidStrict: true,
       })
-      return {name, version, isSemVerMajor}
+      return { name, version, isSemVerMajor }
     } catch (er) {
       return false
     }
@@ -285,7 +285,7 @@ class AuditReport extends Map {
     }
 
     const bulk = {}
-    const {advisories} = report
+    const { advisories } = report
     for (const advisory of Object.values(advisories)) {
       const {
         id,
@@ -296,7 +296,7 @@ class AuditReport extends Map {
         module_name: name,
       } = advisory
       bulk[name] = bulk[name] || []
-      bulk[name].push({id, url, title, severity, vulnerable_versions})
+      bulk[name].push({ id, url, title, severity, vulnerable_versions })
     }
 
     return bulk

package/lib/calc-dep-flags.js

@@ -38,7 +38,7 @@ const calcDepFlagsStep = (node) => {
     return calcDepFlagsStep(node.target)
   }
 
-  node.edgesOut.forEach(({peer, optional, dev, to}) => {
+  node.edgesOut.forEach(({ peer, optional, dev, to }) => {
     // if the dep is missing, then its flags are already maximally unset
     if (!to) {
       return

package/lib/can-place-dep.js

@@ -78,7 +78,7 @@ class CanPlaceDep {
       }
 
       this._treeSnapshot = JSON.stringify([...target.root.inventory.entries()]
-        .map(([loc, {packageName, version, resolved}]) => {
+        .map(([loc, { packageName, version, resolved }]) => {
           return [loc, packageName, version, resolved]
         }).sort(([a], [b]) => localeCompare(a, b)))
     })
@@ -118,7 +118,7 @@ class CanPlaceDep {
 
     debug(() => {
       const treeSnapshot = JSON.stringify([...target.root.inventory.entries()]
-        .map(([loc, {packageName, version, resolved}]) => {
+        .map(([loc, { packageName, version, resolved }]) => {
           return [loc, packageName, version, resolved]
         }).sort(([a], [b]) => localeCompare(a, b)))
       /* istanbul ignore if */

package/lib/dep-valid.js

@@ -6,7 +6,7 @@
 
 const semver = require('semver')
 const npa = require('npm-package-arg')
-const {relative} = require('path')
+const { relative } = require('path')
 const fromPath = require('./from-path.js')
 
 const depValid = (child, requested, requestor) => {

package/lib/diff.js

@@ -5,13 +5,13 @@
 // Thus, the root Diff node is the shallowest change required
 // for a given branch of the tree being mutated.
 
-const {depth} = require('treeverse')
-const {existsSync} = require('fs')
+const { depth } = require('treeverse')
+const { existsSync } = require('fs')
 
 const ssri = require('ssri')
 
 class Diff {
-  constructor ({actual, ideal, filterSet, shrinkwrapInflated}) {
+  constructor ({ actual, ideal, filterSet, shrinkwrapInflated }) {
     this.filterSet = filterSet
     this.shrinkwrapInflated = shrinkwrapInflated
     this.children = []
@@ -94,14 +94,14 @@ class Diff {
     }
 
     return depth({
-      tree: new Diff({actual, ideal, filterSet, shrinkwrapInflated}),
+      tree: new Diff({ actual, ideal, filterSet, shrinkwrapInflated }),
       getChildren,
       leave,
     })
   }
 }
 
-const getAction = ({actual, ideal}) => {
+const getAction = ({ actual, ideal }) => {
   if (!ideal) {
     return 'REMOVE'
   }
@@ -237,7 +237,7 @@ const diffNode = ({
     return
   }
 
-  const action = getAction({actual, ideal})
+  const action = getAction({ actual, ideal })
 
   // if it's a match, then get its children
   // otherwise, this is the child diff node
@@ -245,7 +245,7 @@ const diffNode = ({
     if (action === 'REMOVE') {
       removed.push(actual)
     }
-    children.push(new Diff({actual, ideal, filterSet, shrinkwrapInflated}))
+    children.push(new Diff({ actual, ideal, filterSet, shrinkwrapInflated }))
   } else {
     unchanged.push(ideal)
     // !*! Weird dirty hack warning !*!

package/lib/edge.js

@@ -29,6 +29,7 @@ class ArboristEdge {}
 const printableEdge = (edge) => {
   const edgeFrom = edge.from && edge.from.location
   const edgeTo = edge.to && edge.to.location
+  const override = edge.overrides && edge.overrides.value
 
   return Object.assign(new ArboristEdge(), {
     name: edge.name,
@@ -38,12 +39,13 @@ const printableEdge = (edge) => {
     ...(edgeTo ? { to: edgeTo } : {}),
     ...(edge.error ? { error: edge.error } : {}),
     ...(edge.peerConflicted ? { peerConflicted: true } : {}),
+    ...(override ? { overridden: override } : {}),
   })
 }
 
 class Edge {
   constructor (options) {
-    const { type, name, spec, accept, from } = options
+    const { type, name, spec, accept, from, overrides } = options
 
     if (typeof spec !== 'string') {
       throw new TypeError('must provide string spec')
@@ -55,6 +57,10 @@ class Edge {
 
     this[_spec] = spec
 
+    if (overrides !== undefined) {
+      this.overrides = overrides
+    }
+
     if (accept !== undefined) {
       if (typeof accept !== 'string') {
         throw new TypeError('accept field must be a string if provided')
@@ -82,8 +88,11 @@ class Edge {
   }
 
   satisfiedBy (node) {
-    return node.name === this.name &&
-      depValid(node, this.spec, this.accept, this.from)
+    if (node.name !== this.name) {
+      return false
+    }
+
+    return depValid(node, this.spec, this.accept, this.from)
   }
 
   explain (seen = []) {
@@ -101,6 +110,10 @@ class Edge {
       type: this.type,
       name: this.name,
       spec: this.spec,
+      ...(this.rawSpec !== this.spec ? {
+        rawSpec: this.rawSpec,
+        overridden: true,
+      } : {}),
       ...(bundled ? { bundled } : {}),
       ...(error ? { error } : {}),
       ...(from ? { from: from.explain(null, seen) } : {}),
@@ -143,7 +156,28 @@ class Edge {
     return this[_name]
   }
 
+  get rawSpec () {
+    return this[_spec]
+  }
+
   get spec () {
+    if (this.overrides && this.overrides.value && this.overrides.name === this.name) {
+      if (this.overrides.value.startsWith('$')) {
+        const ref = this.overrides.value.slice(1)
+        const pkg = this.from.root.package
+        const overrideSpec = (pkg.devDependencies && pkg.devDependencies[ref]) ||
+            (pkg.optionalDependencies && pkg.optionalDependencies[ref]) ||
+            (pkg.dependencies && pkg.dependencies[ref]) ||
+            (pkg.peerDependencies && pkg.peerDependencies[ref])
+
+        if (overrideSpec) {
+          return overrideSpec
+        }
+
+        throw new Error(`Unable to resolve reference ${this.overrides.value}`)
+      }
+      return this.overrides.value
+    }
     return this[_spec]
   }
 
@@ -213,6 +247,7 @@ class Edge {
     if (node.edgesOut.has(this.name)) {
       node.edgesOut.get(this.name).detach()
     }
+
     node.addEdgeOut(this)
     this.reload()
   }

package/lib/from-path.js

@@ -3,7 +3,7 @@
 // end up getting installed.  directory (ie, symlink) deps also need
 // to be resolved based on their targets, but that's what realpath is
 
-const {dirname} = require('path')
+const { dirname } = require('path')
 const npa = require('npm-package-arg')
 
 const fromPath = (node, spec) =>

package/lib/link.js

@@ -3,7 +3,7 @@ const relpath = require('./relpath.js')
 const Node = require('./node.js')
 const _loadDeps = Symbol.for('Arborist.Node._loadDeps')
 const _target = Symbol.for('_target')
-const {dirname} = require('path')
+const { dirname } = require('path')
 // defined by Node class
 const _delistFromMeta = Symbol.for('_delistFromMeta')
 const _refreshLocation = Symbol.for('_refreshLocation')

package/lib/node.js

@@ -32,15 +32,16 @@ const semver = require('semver')
 const nameFromFolder = require('@npmcli/name-from-folder')
 const Edge = require('./edge.js')
 const Inventory = require('./inventory.js')
-const {normalize} = require('read-package-json-fast')
-const {getPaths: getBinPaths} = require('bin-links')
+const OverrideSet = require('./override-set.js')
+const { normalize } = require('read-package-json-fast')
+const { getPaths: getBinPaths } = require('bin-links')
 const npa = require('npm-package-arg')
 const debug = require('./debug.js')
 const gatherDepSet = require('./gather-dep-set.js')
 const treeCheck = require('./tree-check.js')
 const walkUp = require('walk-up-path')
 
-const {resolve, relative, dirname, basename} = require('path')
+const { resolve, relative, dirname, basename } = require('path')
 const util = require('util')
 const _package = Symbol('_package')
 const _parent = Symbol('_parent')
@@ -88,6 +89,8 @@ class Node {
       legacyPeerDeps = false,
       linksIn,
       hasShrinkwrap,
+      overrides,
+      loadOverrides = false,
       extraneous = true,
       dev = true,
       optional = true,
@@ -190,6 +193,17 @@ class Node {
     // because this.package is read when adding to inventory
     this[_package] = pkg && typeof pkg === 'object' ? pkg : {}
 
+    if (overrides) {
+      this.overrides = overrides
+    } else if (loadOverrides) {
+      const overrides = this[_package].overrides || {}
+      if (Object.keys(overrides).length > 0) {
+        this.overrides = new OverrideSet({
+          overrides: this[_package].overrides,
+        })
+      }
+    }
+
     // only relevant for the root and top nodes
     this.meta = meta
 
@@ -291,8 +305,8 @@ class Node {
   }
 
   get hasInstallScript () {
-    const {hasInstallScript, scripts} = this.package
-    const {install, preinstall, postinstall} = scripts || {}
+    const { hasInstallScript, scripts } = this.package
+    const { install, preinstall, postinstall } = scripts || {}
     return !!(hasInstallScript || install || preinstall || postinstall)
   }
 
@@ -376,7 +390,7 @@ class Node {
     }
 
     if (this.root.sourceReference) {
-      const {name, version} = this.root.package
+      const { name, version } = this.root.package
       why.whileInstalling = {
         name,
         version,
@@ -963,6 +977,11 @@ class Node {
       return false
     }
 
+    // XXX need to check for two root nodes?
+    if (node.overrides !== this.overrides) {
+      return false
+    }
+
     ignorePeers = new Set(ignorePeers)
 
     // gather up all the deps of this node and that are only depended
@@ -1208,6 +1227,10 @@ class Node {
       this[_changePath](newPath)
     }
 
+    if (parent.overrides) {
+      this.overrides = parent.overrides.getNodeRule(this)
+    }
+
     // clobbers anything at that path, resets all appropriate references
     this.root = parent.root
   }
@@ -1279,11 +1302,33 @@ class Node {
     }
   }
 
+  assertRootOverrides () {
+    if (!this.isProjectRoot || !this.overrides) {
+      return
+    }
+
+    for (const edge of this.edgesOut.values()) {
+      // if these differ an override has been applied, those are not allowed
+      // for top level dependencies so throw an error
+      if (edge.spec !== edge.rawSpec && !edge.spec.startsWith('$')) {
+        throw Object.assign(new Error(`Override for ${edge.name}@${edge.rawSpec} conflicts with direct dependency`), { code: 'EOVERRIDE' })
+      }
+    }
+  }
+
   addEdgeOut (edge) {
+    if (this.overrides) {
+      edge.overrides = this.overrides.getEdgeRule(edge)
+    }
+
     this.edgesOut.set(edge.name, edge)
   }
 
   addEdgeIn (edge) {
+    if (edge.overrides) {
+      this.overrides = edge.overrides
+    }
+
     this.edgesIn.add(edge)
 
     // try to get metadata from the yarn.lock file

package/lib/override-set.js

@@ -0,0 +1,123 @@
+const npa = require('npm-package-arg')
+const semver = require('semver')
+
+class OverrideSet {
+  constructor ({ overrides, key, parent }) {
+    this.parent = parent
+    this.children = new Map()
+
+    if (typeof overrides === 'string') {
+      overrides = { '.': overrides }
+    }
+
+    // change a literal empty string to * so we can use truthiness checks on
+    // the value property later
+    if (overrides['.'] === '') {
+      overrides['.'] = '*'
+    }
+
+    if (parent) {
+      const spec = npa(key)
+      if (!spec.name) {
+        throw new Error(`Override without name: ${key}`)
+      }
+
+      this.name = spec.name
+      spec.name = ''
+      this.key = key
+      this.keySpec = spec.rawSpec === '' ? '' : spec.toString()
+      this.value = overrides['.'] || this.keySpec
+    }
+
+    for (const [key, childOverrides] of Object.entries(overrides)) {
+      if (key === '.') {
+        continue
+      }
+
+      const child = new OverrideSet({
+        parent: this,
+        key,
+        overrides: childOverrides,
+      })
+
+      this.children.set(child.key, child)
+    }
+  }
+
+  getEdgeRule (edge) {
+    for (const rule of this.ruleset.values()) {
+      if (rule.name !== edge.name) {
+        continue
+      }
+
+      if (rule.keySpec === '' ||
+        semver.intersects(edge.spec, rule.keySpec)) {
+        return rule
+      }
+    }
+
+    return this
+  }
+
+  getNodeRule (node) {
+    for (const rule of this.ruleset.values()) {
+      if (rule.name !== node.name) {
+        continue
+      }
+
+      if (rule.keySpec === '' ||
+        semver.satisfies(node.version, rule.keySpec) ||
+        semver.satisfies(node.version, rule.value)) {
+        return rule
+      }
+    }
+
+    return this
+  }
+
+  getMatchingRule (node) {
+    for (const rule of this.ruleset.values()) {
+      if (rule.name !== node.name) {
+        continue
+      }
+
+      if (rule.keySpec === '' ||
+        semver.satisfies(node.version, rule.keySpec) ||
+        semver.satisfies(node.version, rule.value)) {
+        return rule
+      }
+    }
+
+    return null
+  }
+
+  * ancestry () {
+    for (let ancestor = this; ancestor; ancestor = ancestor.parent) {
+      yield ancestor
+    }
+  }
+
+  get isRoot () {
+    return !this.parent
+  }
+
+  get ruleset () {
+    const ruleset = new Map()
+
+    for (const override of this.ancestry()) {
+      for (const kid of override.children.values()) {
+        if (!ruleset.has(kid.key)) {
+          ruleset.set(kid.key, kid)
+        }
+      }
+
+      if (!override.isRoot && !ruleset.has(override.key)) {
+        ruleset.set(override.key, override)
+      }
+    }
+
+    return ruleset
+  }
+}
+
+module.exports = OverrideSet

package/lib/place-dep.js

@@ -295,6 +295,7 @@ class PlaceDep {
       integrity: dep.integrity,
       legacyPeerDeps: this.legacyPeerDeps,
       error: dep.errors[0],
+      ...(dep.overrides ? { overrides: dep.overrides } : {}),
       ...(dep.isLink ? { target: dep.target, realpath: dep.realpath } : {}),
     })
 
@@ -407,11 +408,12 @@ class PlaceDep {
       for (const entryEdge of peerEntrySets(edge.from).keys()) {
         // either this one needs to be pruned and re-evaluated, or marked
         // as peerConflicted and warned about.  If the entryEdge comes in from
-        // the root, then we have to leave it alone, and in that case, it
-        // will have already warned or crashed by getting to this point.
+        // the root or a workspace, then we have to leave it alone, and in that
+        // case, it will have already warned or crashed by getting to this point
         const entryNode = entryEdge.to
         const deepestTarget = deepestNestingTarget(entryNode)
-        if (deepestTarget !== target && !entryEdge.from.isRoot) {
+        if (deepestTarget !== target &&
+            !(entryEdge.from.isProjectRoot || entryEdge.from.isWorkspace)) {
           prunePeerSets.push(...gatherDepSet([entryNode], e => {
             return e.to !== entryNode && !e.peerConflicted
           }))

package/lib/printable.js

@@ -1,6 +1,5 @@
 // helper function to output a clearer visualization
 // of the current node and its descendents
-
 const localeCompare = require('@isaacs/string-locale-compare')('en')
 const util = require('util')
 const relpath = require('./relpath.js')
@@ -65,6 +64,11 @@ class ArboristNode {
       this.errors = tree.errors.map(treeError)
     }
 
+    if (tree.overrides) {
+      this.overrides = new Map([...tree.overrides.ruleset.values()]
+        .map((override) => [override.key, override.value]))
+    }
+
     // edgesOut sorted by name
     if (tree.edgesOut.size) {
       this.edgesOut = new Map([...tree.edgesOut.entries()]
@@ -87,7 +91,7 @@ class ArboristNode {
     // fsChildren sorted by path
     if (tree.fsChildren.size) {
       this.fsChildren = new Set([...tree.fsChildren]
-        .sort(({path: a}, {path: b}) => localeCompare(a, b))
+        .sort(({ path: a }, { path: b }) => localeCompare(a, b))
         .map(tree => printableTree(tree, path)))
     }
 
@@ -114,7 +118,7 @@ class ArboristLink extends ArboristNode {
   }
 }
 
-const treeError = ({code, path}) => ({
+const treeError = ({ code, path }) => ({
   code,
   ...(path ? { path } : {}),
 })
@@ -126,7 +130,10 @@ class Edge {
   constructor (edge) {
     this.type = edge.type
     this.name = edge.name
-    this.spec = edge.spec || '*'
+    this.spec = edge.rawSpec || '*'
+    if (edge.rawSpec !== edge.spec) {
+      this.override = edge.spec
+    }
     if (edge.error) {
       this.error = edge.error
     }
@@ -145,6 +152,8 @@ class EdgeOut extends Edge {
 
   [util.inspect.custom] () {
     return `{ ${this.type} ${this.name}@${this.spec}${
+      this.override ? ` overridden:${this.override}` : ''
+    }${
       this.to ? ' -> ' + this.to : ''
     }${
       this.error ? ' ' + this.error : ''

package/lib/relpath.js

@@ -1,3 +1,3 @@
-const {relative} = require('path')
+const { relative } = require('path')
 const relpath = (from, to) => relative(from, to).replace(/\\/g, '/')
 module.exports = relpath

package/lib/retire-path.js

@@ -1,5 +1,5 @@
 const crypto = require('crypto')
-const {dirname, basename, resolve} = require('path')
+const { dirname, basename, resolve } = require('path')
 
 // use sha1 because it's faster, and collisions extremely unlikely anyway
 const pathSafeHash = s =>

package/lib/shrinkwrap.js

@@ -35,7 +35,7 @@ const mismatch = (a, b) => a && b && a !== b
 
 const procLog = require('proc-log')
 const YarnLock = require('./yarn-lock.js')
-const {promisify} = require('util')
+const { promisify } = require('util')
 const rimraf = promisify(require('rimraf'))
 const fs = require('fs')
 const readFile = promisify(fs.readFile)
@@ -180,7 +180,7 @@ const assertNoNewer = async (path, data, lockTime, dir = path, seen = null) => {
 
   const parent = isParent ? dir : resolve(dir, 'node_modules')
   const children = dir === path
-    ? Promise.resolve([{name: 'node_modules', isDirectory: () => true }])
+    ? Promise.resolve([{ name: 'node_modules', isDirectory: () => true }])
     : readdir(parent, { withFileTypes: true })
 
   return children.catch(() => [])
@@ -366,7 +366,7 @@ class Shrinkwrap {
     if (fromYarn && fromYarn.version) {
       // if it's the yarn or npm default registry, use the version as
       // our effective spec.  if it's any other kind of thing, use that.
-      const {resolved, version, integrity} = fromYarn
+      const { resolved, version, integrity } = fromYarn
       const isYarnReg = spec.registry && yarnRegRe.test(resolved)
       const isnpmReg = spec.registry && !isYarnReg && npmRegRe.test(resolved)
       const isReg = isnpmReg || isYarnReg
@@ -1062,7 +1062,7 @@ class Shrinkwrap {
     }
 
     // now we walk the children, putting them in the 'dependencies' object
-    const {children} = node.target
+    const { children } = node.target
     if (!children.size) {
       delete lock.dependencies
     } else {

package/lib/version-from-tgz.js

@@ -1,7 +1,7 @@
 /* eslint node/no-deprecated-api: "off" */
 const semver = require('semver')
-const {basename} = require('path')
-const {parse} = require('url')
+const { basename } = require('path')
+const { parse } = require('url')
 module.exports = (name, tgz) => {
   const base = basename(tgz)
   if (!base.endsWith('.tgz')) {

package/lib/vuln.js

@@ -11,7 +11,7 @@
 //   @npmcli/metavuln-calculator
 // - via: dependency vulns which cause this one
 
-const {satisfies, simplifyRange} = require('semver')
+const { satisfies, simplifyRange } = require('semver')
 const semverOpt = { loose: true, includePrerelease: true }
 
 const localeCompare = require('@isaacs/string-locale-compare')('en')

package/lib/yarn-lock.js

@@ -30,8 +30,8 @@
 
 const localeCompare = require('@isaacs/string-locale-compare')('en')
 const consistentResolve = require('./consistent-resolve.js')
-const {dirname} = require('path')
-const {breadth} = require('treeverse')
+const { dirname } = require('path')
+const { breadth } = require('treeverse')
 
 // sort a key/value object into a string of JSON stringified keys and vals
 const sortKV = obj => Object.keys(obj)

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@npmcli/arborist",
-  "version": "4.0.3",
+  "version": "4.1.1",
   "description": "Manage node_modules trees",
   "dependencies": {
-    "@isaacs/string-locale-compare": "^1.0.1",
+    "@isaacs/string-locale-compare": "^1.1.0",
     "@npmcli/installed-package-contents": "^1.0.7",
     "@npmcli/map-workspaces": "^2.0.0",
     "@npmcli/metavuln-calculator": "^2.0.0",
     "@npmcli/move-file": "^1.1.0",
     "@npmcli/name-from-folder": "^1.0.1",
-    "@npmcli/node-gyp": "^1.0.1",
+    "@npmcli/node-gyp": "^1.0.3",
     "@npmcli/package-json": "^1.0.1",
     "@npmcli/run-script": "^2.0.0",
     "bin-links": "^2.3.0",
@@ -23,8 +23,8 @@
     "npm-package-arg": "^8.1.5",
     "npm-pick-manifest": "^6.1.0",
     "npm-registry-fetch": "^11.0.0",
-    "pacote": "^12.0.0",
-    "parse-conflict-json": "^1.1.1",
+    "pacote": "^12.0.2",
+    "parse-conflict-json": "^2.0.1",
     "proc-log": "^1.0.0",
     "promise-all-reject-late": "^1.0.0",
     "promise-call-limit": "^1.0.1",
@@ -37,11 +37,12 @@
     "walk-up-path": "^1.0.0"
   },
   "devDependencies": {
-    "@npmcli/lint": "^1.0.2",
+    "@npmcli/template-oss": "^2.3.1",
     "benchmark": "^2.1.4",
     "chalk": "^4.1.0",
     "minify-registry-metadata": "^2.1.0",
-    "tap": "^15.0.9",
+    "nock": "^13.2.0",
+    "tap": "^15.1.2",
     "tcompare": "^5.0.6"
   },
   "scripts": {
@@ -54,21 +55,22 @@
     "postversion": "npm publish",
     "prepublishOnly": "git push origin --follow-tags",
     "eslint": "eslint",
-    "lint": "npm run npmclilint -- \"lib/**/*.*js\" \"bin/**/*.*js\" \"test/*.*js\" \"test/arborist/*.*js\"",
+    "lint": "eslint '**/*.js'",
     "lintfix": "npm run lint -- --fix",
     "benchmark": "node scripts/benchmark.js",
     "benchclean": "rm -rf scripts/benchmark/*/",
-    "npmclilint": "npmcli-lint"
+    "npmclilint": "npmcli-lint",
+    "postlint": "npm-template-check"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/npm/arborist"
   },
-  "author": "Isaac Z. Schlueter <i@izs.me> (http://blog.izs.me/)",
+  "author": "GitHub Inc.",
   "license": "ISC",
   "files": [
-    "lib/**/*.js",
-    "bin/**/*.js"
+    "bin",
+    "lib"
   ],
   "main": "lib/index.js",
   "bin": {
@@ -91,5 +93,10 @@
   },
   "engines": {
     "node": "^12.13.0 || ^14.15.0 || >=16"
-  }
+  },
+  "templateVersion": "2.3.1",
+  "eslintIgnore": [
+    "test/fixtures/",
+    "!test/fixtures/*.js"
+  ]
 }

package/LICENSE

@@ -1,22 +0,0 @@
-The ISC License
-
-Copyright npm, Inc.
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND NPM DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL NPM BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
-OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
-
----
-
-Files and metadata contained in `test/fixtures/registry-mocks/content` are
-downloaded from the public npm registry.  These are the property of their
-respective owners.  The use and distribution of said artifacts are covered by
-their associated licenses.