@npmcli/arborist 5.2.3 → 5.4.0

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

@@ -484,7 +484,7 @@ Try using the package name instead, e.g:
             .catch(/* istanbul ignore next */ er => null)
           if (st && st.isSymbolicLink()) {
             const target = await readlink(dir)
-            const real = resolve(dirname(dir), target)
+            const real = resolve(dirname(dir), target).replace(/#/g, '%23')
             tree.package.dependencies[name] = `file:${real}`
           } else {
             tree.package.dependencies[name] = '*'
@@ -603,7 +603,7 @@ Try using the package name instead, e.g:
     if (filepath) {
       const { name } = spec
       const tree = this.idealTree.target
-      spec = npa(`file:${relpath(tree.path, filepath)}`, tree.path)
+      spec = npa(`file:${relpath(tree.path, filepath).replace(/#/g, '%23')}`, tree.path)
       spec.name = name
     }
     return spec
@@ -1076,9 +1076,8 @@ This is a one-time fix-up, please be patient...
           // if it fails at this point, though, dont' worry because it
           // may well be an optional dep that has gone missing.  it'll
           // fail later anyway.
-          const from = fromPath(placed)
           promises.push(...this[_problemEdges](placed).map(e =>
-            this[_fetchManifest](npa.resolve(e.name, e.spec, from))
+            this[_fetchManifest](npa.resolve(e.name, e.spec, fromPath(placed, e)))
               .catch(er => null)))
         },
       })

package/lib/arborist/index.js

@@ -74,8 +74,12 @@ class Arborist extends Base {
       cache: options.cache || `${homedir()}/.npm/_cacache`,
       packumentCache: options.packumentCache || new Map(),
       workspacesEnabled: options.workspacesEnabled !== false,
+      replaceRegistryHost: options.replaceRegistryHost,
       lockfileVersion: lockfileVersion(options.lockfileVersion),
     }
+    this.replaceRegistryHost = this.options.replaceRegistryHost =
+      (!this.options.replaceRegistryHost || this.options.replaceRegistryHost === 'npmjs') ?
+        'registry.npmjs.org' : this.options.replaceRegistryHost
 
     this[_workspacesEnabled] = this.options.workspacesEnabled
 

package/lib/arborist/load-actual.js

@@ -196,7 +196,7 @@ module.exports = cls => class ActualLoader extends cls {
       const actualRoot = tree.isLink ? tree.target : tree
       const { dependencies = {} } = actualRoot.package
       for (const [name, kid] of actualRoot.children.entries()) {
-        const def = kid.isLink ? `file:${kid.realpath}` : '*'
+        const def = kid.isLink ? `file:${kid.realpath.replace(/#/g, '%23')}` : '*'
         dependencies[name] = dependencies[name] || def
       }
       actualRoot.package = { ...actualRoot.package, dependencies }

package/lib/arborist/load-virtual.js

@@ -162,7 +162,7 @@ module.exports = cls => class VirtualLoader extends cls {
       lockfile: s.data,
     })
     for (const [name, path] of workspaces.entries()) {
-      lockWS.push(['workspace', name, `file:${path}`])
+      lockWS.push(['workspace', name, `file:${path.replace(/#/g, '%23')}`])
     }
 
     const lockEdges = [

package/lib/arborist/reify.js

@@ -22,6 +22,7 @@ const moveFile = require('@npmcli/move-file')
 const rimraf = promisify(require('rimraf'))
 const PackageJson = require('@npmcli/package-json')
 const packageContents = require('@npmcli/installed-package-contents')
+const runScript = require('@npmcli/run-script')
 const { checkEngine, checkPlatform } = require('npm-install-checks')
 const _force = Symbol.for('force')
 
@@ -711,13 +712,19 @@ module.exports = cls => class Reifier extends cls {
   [_registryResolved] (resolved) {
     // the default registry url is a magic value meaning "the currently
     // configured registry".
+    // `resolved` must never be falsey.
     //
     // XXX: use a magic string that isn't also a valid value, like
     // ${REGISTRY} or something.  This has to be threaded through the
     // Shrinkwrap and Node classes carefully, so for now, just treat
     // the default reg as the magical animal that it has been.
-    return resolved && resolved
-      .replace(/^https?:\/\/registry\.npmjs\.org\//, this.registry)
+    const resolvedURL = new URL(resolved)
+    if ((this.options.replaceRegistryHost === resolvedURL.hostname)
+      || this.options.replaceRegistryHost === 'always') {
+      // this.registry always has a trailing slash
+      resolved = `${this.registry.slice(0, -1)}${resolvedURL.pathname}${resolvedURL.searchParams}`
+    }
+    return resolved
   }
 
   // bundles are *sort of* like shrinkwraps, in that the branch is defined
@@ -1240,7 +1247,7 @@ module.exports = cls => class Reifier extends cls {
             // path initially, in which case we can end up with the wrong
             // thing, so just get the ultimate fetchSpec and relativize it.
             const p = req.fetchSpec.replace(/^file:/, '')
-            const rel = relpath(addTree.realpath, p)
+            const rel = relpath(addTree.realpath, p).replace(/#/g, '%23')
             newSpec = `file:${rel}`
           }
         } else {
@@ -1516,6 +1523,30 @@ module.exports = cls => class Reifier extends cls {
 
     if (!this[_global]) {
       await this.actualTree.meta.save()
+      const ignoreScripts = !!this.options.ignoreScripts
+      // if we aren't doing a dry run or ignoring scripts and we actually made changes to the dep
+      // tree, then run the dependencies scripts
+      if (!this[_dryRun] && !ignoreScripts && this.diff && this.diff.children.length) {
+        const { path, package: pkg } = this.actualTree.target
+        const stdio = this.options.foregroundScripts ? 'inherit' : 'pipe'
+        const { scripts = {} } = pkg
+        for (const event of ['predependencies', 'dependencies', 'postdependencies']) {
+          if (Object.prototype.hasOwnProperty.call(scripts, event)) {
+            const timer = `reify:run:${event}`
+            process.emit('time', timer)
+            log.info('run', pkg._id, event, scripts[event])
+            await runScript({
+              event,
+              path,
+              pkg,
+              stdioString: true,
+              stdio,
+              scriptShell: this.options.scriptShell,
+            })
+            process.emit('timeEnd', timer)
+          }
+        }
+      }
     }
   }
 }

package/lib/consistent-resolve.js

@@ -20,8 +20,8 @@ const consistentResolve = (resolved, fromPath, toPath, relPaths = false) => {
       raw,
     } = npa(resolved, fromPath)
     const isPath = type === 'file' || type === 'directory'
-    return isPath && !relPaths ? `file:${fetchSpec}`
-      : isPath ? 'file:' + (toPath ? relpath(toPath, fetchSpec) : fetchSpec)
+    return isPath && !relPaths ? `file:${fetchSpec.replace(/#/g, '%23')}`
+      : isPath ? 'file:' + (toPath ? relpath(toPath, fetchSpec.replace(/#/g, '%23')) : fetchSpec.replace(/#/g, '%23'))
       : hosted ? `git+${
         hosted.auth ? hosted.https(hostedOpt) : hosted.sshurl(hostedOpt)
       }`

package/lib/dep-valid.js

@@ -20,7 +20,7 @@ const depValid = (child, requested, requestor) => {
       // file: deps that depend on other files/dirs, we must resolve the
       // location based on the *requestor* file/dir, not where it ends up.
       // '' is equivalent to '*'
-      requested = npa.resolve(child.name, requested || '*', fromPath(requestor))
+      requested = npa.resolve(child.name, requested || '*', fromPath(requestor, requestor.edgesOut.get(child.name)))
     } catch (er) {
       // Not invalid because the child doesn't match, but because
       // the spec itself is not supported.  Nothing would match,

package/lib/edge.js

@@ -169,7 +169,11 @@ class Edge {
     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
+        // we may be a virtual root, if we are we want to resolve reference overrides
+        // from the real root, not the virtual one
+        const pkg = this.from.sourceReference
+          ? this.from.sourceReference.root.package
+          : this.from.root.package
         const overrideSpec = (pkg.devDependencies && pkg.devDependencies[ref]) ||
             (pkg.optionalDependencies && pkg.optionalDependencies[ref]) ||
             (pkg.dependencies && pkg.dependencies[ref]) ||

package/lib/from-path.js

@@ -6,8 +6,19 @@
 const { dirname } = require('path')
 const npa = require('npm-package-arg')
 
-const fromPath = (node, spec) =>
-  spec && spec.type === 'file' ? dirname(spec.fetchSpec)
-  : node.realpath
+const fromPath = (node, spec, edge) => {
+  if (edge && edge.overrides && edge.overrides.name === edge.name && edge.overrides.value) {
+    // fromPath could be called with a node that has a virtual root, if that happens
+    // we want to make sure we get the real root node when overrides are in use. this
+    // is to allow things like overriding a dependency with a tarball file that's a
+    // relative path from the project root
+    return node.sourceReference
+      ? node.sourceReference.root.realpath
+      : node.root.realpath
+  }
 
-module.exports = node => fromPath(node, node.resolved && npa(node.resolved))
+  return spec && spec.type === 'file' ? dirname(spec.fetchSpec)
+    : node.realpath
+}
+
+module.exports = (node, edge) => fromPath(node, node.resolved && npa(node.resolved), edge)

package/lib/link.js

@@ -118,7 +118,7 @@ class Link extends Node {
     // the path/realpath guard is there for the benefit of setting
     // these things in the "wrong" order
     return this.path && this.realpath
-      ? `file:${relpath(dirname(this.path), this.realpath)}`
+      ? `file:${relpath(dirname(this.path), this.realpath).replace(/#/g, '%23')}`
       : null
   }
 

package/lib/node.js

@@ -69,6 +69,8 @@ const consistentResolve = require('./consistent-resolve.js')
 const printableTree = require('./printable.js')
 const CaseInsensitiveMap = require('./case-insensitive-map.js')
 
+const querySelectorAll = require('./query-selector-all.js')
+
 class Node {
   constructor (options) {
     // NB: path can be null if it's a link target
@@ -824,7 +826,7 @@ class Node {
     }
 
     for (const [name, path] of this[_workspaces].entries()) {
-      new Edge({ from: this, name, spec: `file:${path}`, type: 'workspace' })
+      new Edge({ from: this, name, spec: `file:${path.replace(/#/g, '%23')}`, type: 'workspace' })
     }
   }
 
@@ -1446,6 +1448,12 @@ class Node {
     return base === name && basename(nm) === 'node_modules' ? dir : false
   }
 
+  // maybe accept both string value or array of strings
+  // seems to be what dom API does
+  querySelectorAll (query) {
+    return querySelectorAll(this, query)
+  }
+
   toJSON () {
     return printableTree(this)
   }

package/lib/query-selector-all.js

@@ -0,0 +1,561 @@
+'use strict'
+
+const { resolve } = require('path')
+const { parser, arrayDelimiter } = require('@npmcli/query')
+const localeCompare = require('@isaacs/string-locale-compare')('en')
+const npa = require('npm-package-arg')
+const minimatch = require('minimatch')
+const semver = require('semver')
+
+// handle results for parsed query asts, results are stored in a map that has a
+// key that points to each ast selector node and stores the resulting array of
+// arborist nodes as its value, that is essential to how we handle multiple
+// query selectors, e.g: `#a, #b, #c` <- 3 diff ast selector nodes
+class Results {
+  #currentAstSelector
+  #initialItems
+  #inventory
+  #pendingCombinator
+  #results = new Map()
+  #targetNode
+
+  constructor (opts) {
+    this.#currentAstSelector = opts.rootAstNode.nodes[0]
+    this.#inventory = opts.inventory
+    this.#initialItems = opts.initialItems
+    this.#targetNode = opts.targetNode
+
+    this.currentResults = this.#initialItems
+
+    // reset by rootAstNode walker
+    this.currentAstNode = opts.rootAstNode
+  }
+
+  get currentResults () {
+    return this.#results.get(this.#currentAstSelector)
+  }
+
+  set currentResults (value) {
+    this.#results.set(this.#currentAstSelector, value)
+  }
+
+  // retrieves the initial items to which start the filtering / matching
+  // for most of the different types of recognized ast nodes, e.g: class (aka
+  // depType), id, *, etc in different contexts we need to start with the
+  // current list of filtered results, for example a query for `.workspace`
+  // actually means the same as `*.workspace` so we want to start with the full
+  // inventory if that's the first ast node we're reading but if it appears in
+  // the middle of a query it should respect the previous filtered results,
+  // combinators are a special case in which we always want to have the
+  // complete inventory list in order to use the left-hand side ast node as a
+  // filter combined with the element on its right-hand side
+  get initialItems () {
+    const firstParsed =
+      (this.currentAstNode.parent.nodes[0] === this.currentAstNode) &&
+      (this.currentAstNode.parent.parent.type === 'root')
+
+    if (firstParsed) {
+      return this.#initialItems
+    }
+    if (this.currentAstNode.prev().type === 'combinator') {
+      return this.#inventory
+    }
+    return this.currentResults
+  }
+
+  // combinators need information about previously filtered items along
+  // with info of the items parsed / retrieved from the selector right
+  // past the combinator, for this reason combinators are stored and
+  // only ran as the last part of each selector logic
+  processPendingCombinator (nextResults) {
+    if (this.#pendingCombinator) {
+      const res = this.#pendingCombinator(this.currentResults, nextResults)
+      this.#pendingCombinator = null
+      this.currentResults = res
+    } else {
+      this.currentResults = nextResults
+    }
+  }
+
+  // when collecting results to a root astNode, we traverse the list of child
+  // selector nodes and collect all of their resulting arborist nodes into a
+  // single/flat Set of items, this ensures we also deduplicate items
+  collect (rootAstNode) {
+    return new Set(rootAstNode.nodes.flatMap(n => this.#results.get(n)))
+  }
+
+  // selector types map to the '.type' property of the ast nodes via `${astNode.type}Type`
+  //
+  // attribute selector [name=value], etc
+  attributeType () {
+    const nextResults = this.initialItems.filter(node =>
+      attributeMatch(this.currentAstNode, node.package)
+    )
+    this.processPendingCombinator(nextResults)
+  }
+
+  // dependency type selector (i.e. .prod, .dev, etc)
+  // css calls this class, we interpret is as dependency type
+  classType () {
+    const depTypeFn = depTypes[String(this.currentAstNode)]
+    if (!depTypeFn) {
+      throw Object.assign(
+        new Error(`\`${String(this.currentAstNode)}\` is not a supported dependency type.`),
+        { code: 'EQUERYNODEPTYPE' }
+      )
+    }
+    const nextResults = depTypeFn(this.initialItems)
+    this.processPendingCombinator(nextResults)
+  }
+
+  // combinators (i.e. '>', ' ', '~')
+  combinatorType () {
+    this.#pendingCombinator = combinators[String(this.currentAstNode)]
+  }
+
+  // name selectors (i.e. #foo, #foo@1.0.0)
+  // css calls this id, we interpret it as name
+  idType () {
+    const spec = npa(this.currentAstNode.value)
+    const nextResults = this.initialItems.filter(node =>
+      (node.name === spec.name || node.package.name === spec.name) &&
+      (semver.satisfies(node.version, spec.fetchSpec) || !spec.rawSpec))
+    this.processPendingCombinator(nextResults)
+  }
+
+  // pseudo selectors (prefixed with :)
+  pseudoType () {
+    const pseudoFn = `${this.currentAstNode.value.slice(1)}Pseudo`
+    if (!this[pseudoFn]) {
+      throw Object.assign(
+        new Error(`\`${this.currentAstNode.value
+        }\` is not a supported pseudo selector.`),
+        { code: 'EQUERYNOPSEUDO' }
+      )
+    }
+    const nextResults = this[pseudoFn]()
+    this.processPendingCombinator(nextResults)
+  }
+
+  selectorType () {
+    this.#currentAstSelector = this.currentAstNode
+    // starts a new array in which resulting items
+    // can be stored for each given ast selector
+    if (!this.currentResults) {
+      this.currentResults = []
+    }
+  }
+
+  universalType () {
+    this.processPendingCombinator(this.initialItems)
+  }
+
+  // pseudo selectors map to the 'value' property of the pseudo selectors in the ast nodes
+  // via selectors via `${value.slice(1)}Pseudo`
+  attrPseudo () {
+    const { lookupProperties, attributeMatcher } = this.currentAstNode
+
+    return this.initialItems.filter(node => {
+      let objs = [node.package]
+      for (const prop of lookupProperties) {
+        // if an isArray symbol is found that means we'll need to iterate
+        // over the previous found array to basically make sure we traverse
+        // all its indexes testing for possible objects that may eventually
+        // hold more keys specified in a selector
+        if (prop === arrayDelimiter) {
+          objs = objs.flat()
+          continue
+        }
+
+        // otherwise just maps all currently found objs
+        // to the next prop from the lookup properties list,
+        // filters out any empty key lookup
+        objs = objs.flatMap(obj => obj[prop] || [])
+
+        // in case there's no property found in the lookup
+        // just filters that item out
+        const noAttr = objs.every(obj => !obj)
+        if (noAttr) {
+          return false
+        }
+      }
+
+      // if any of the potential object matches
+      // that item should be in the final result
+      return objs.some(obj => attributeMatch(attributeMatcher, obj))
+    })
+  }
+
+  emptyPseudo () {
+    return this.initialItems.filter(node => node.edgesOut.size === 0)
+  }
+
+  extraneousPseudo () {
+    return this.initialItems.filter(node => node.extraneous)
+  }
+
+  hasPseudo () {
+    const found = []
+    for (const item of this.initialItems) {
+      const res = retrieveNodesFromParsedAst({
+        // This is the one time initialItems differs from inventory
+        initialItems: [item],
+        inventory: this.#inventory,
+        rootAstNode: this.currentAstNode.nestedNode,
+        targetNode: item,
+      })
+      if (res.size > 0) {
+        found.push(item)
+      }
+    }
+    return found
+  }
+
+  invalidPseudo () {
+    const found = []
+    for (const node of this.initialItems) {
+      for (const edge of node.edgesIn) {
+        if (edge.invalid) {
+          found.push(node)
+          break
+        }
+      }
+    }
+    return found
+  }
+
+  isPseudo () {
+    const res = retrieveNodesFromParsedAst({
+      initialItems: this.initialItems,
+      inventory: this.#inventory,
+      rootAstNode: this.currentAstNode.nestedNode,
+      targetNode: this.currentAstNode,
+    })
+    return [...res]
+  }
+
+  linkPseudo () {
+    return this.initialItems.filter(node => node.isLink || (node.isTop && !node.isRoot))
+  }
+
+  missingPseudo () {
+    return this.#inventory.reduce((res, node) => {
+      for (const edge of node.edgesOut.values()) {
+        if (edge.missing) {
+          const pkg = { name: edge.name, version: edge.spec }
+          res.push(new this.#targetNode.constructor({ pkg }))
+        }
+      }
+      return res
+    }, [])
+  }
+
+  notPseudo () {
+    const res = retrieveNodesFromParsedAst({
+      initialItems: this.initialItems,
+      inventory: this.#inventory,
+      rootAstNode: this.currentAstNode.nestedNode,
+      targetNode: this.currentAstNode,
+    })
+    const internalSelector = new Set(res)
+    return this.initialItems.filter(node =>
+      !internalSelector.has(node))
+  }
+
+  pathPseudo () {
+    return this.initialItems.filter(node => {
+      if (!this.currentAstNode.pathValue) {
+        return true
+      }
+      return minimatch(
+        node.realpath.replace(/\\+/g, '/'),
+        resolve(node.root.realpath, this.currentAstNode.pathValue).replace(/\\+/g, '/')
+      )
+    })
+  }
+
+  privatePseudo () {
+    return this.initialItems.filter(node => node.package.private)
+  }
+
+  rootPseudo () {
+    return this.initialItems.filter(node => node === this.#targetNode.root)
+  }
+
+  scopePseudo () {
+    return this.initialItems.filter(node => node === this.#targetNode)
+  }
+
+  semverPseudo () {
+    if (!this.currentAstNode.semverValue) {
+      return this.initialItems
+    }
+    return this.initialItems.filter(node =>
+      semver.satisfies(node.version, this.currentAstNode.semverValue))
+  }
+
+  typePseudo () {
+    if (!this.currentAstNode.typeValue) {
+      return this.initialItems
+    }
+    return this.initialItems
+      .flatMap(node => {
+        const found = []
+        for (const edge of node.edgesIn) {
+          if (npa(`${edge.name}@${edge.spec}`).type === this.currentAstNode.typeValue) {
+            found.push(edge.to)
+          }
+        }
+        return found
+      })
+  }
+
+  dedupedPseudo () {
+    return this.initialItems.filter(node => node.target.edgesIn.size > 1)
+  }
+}
+
+// operators for attribute selectors
+const attributeOperators = {
+  // attribute value is equivalent
+  '=' ({ attr, value, insensitive }) {
+    return attr === value
+  },
+  // attribute value contains word
+  '~=' ({ attr, value, insensitive }) {
+    return (attr.match(/\w+/g) || []).includes(value)
+  },
+  // attribute value contains string
+  '*=' ({ attr, value, insensitive }) {
+    return attr.includes(value)
+  },
+  // attribute value is equal or starts with
+  '|=' ({ attr, value, insensitive }) {
+    return attr.startsWith(`${value}-`)
+  },
+  // attribute value starts with
+  '^=' ({ attr, value, insensitive }) {
+    return attr.startsWith(value)
+  },
+  // attribute value ends with
+  '$=' ({ attr, value, insensitive }) {
+    return attr.endsWith(value)
+  },
+}
+
+const attributeOperator = ({ attr, value, insensitive, operator }) => {
+  if (typeof attr === 'number') {
+    attr = String(attr)
+  }
+  if (typeof attr !== 'string') {
+    // It's an object or an array, bail
+    return false
+  }
+  if (insensitive) {
+    attr = attr.toLowerCase()
+  }
+  return attributeOperators[operator]({
+    attr,
+    insensitive,
+    value,
+  })
+}
+
+const attributeMatch = (matcher, obj) => {
+  const insensitive = !!matcher.insensitive
+  const operator = matcher.operator || ''
+  const attribute = matcher.qualifiedAttribute
+  let value = matcher.value || ''
+  // return early if checking existence
+  if (operator === '') {
+    return Boolean(obj[attribute])
+  }
+  if (insensitive) {
+    value = value.toLowerCase()
+  }
+  // in case the current object is an array
+  // then we try to match every item in the array
+  if (Array.isArray(obj[attribute])) {
+    return obj[attribute].find((i, index) => {
+      const attr = obj[attribute][index] || ''
+      return attributeOperator({ attr, value, insensitive, operator })
+    })
+  } else {
+    const attr = obj[attribute] || ''
+    return attributeOperator({ attr, value, insensitive, operator })
+  }
+}
+
+const edgeIsType = (node, type, seen = new Set()) => {
+  for (const edgeIn of node.edgesIn) {
+    // TODO Need a test with an infinite loop
+    if (seen.has(edgeIn)) {
+      continue
+    }
+    seen.add(edgeIn)
+    if (edgeIn.type === type || edgeIn.from[type] || edgeIsType(edgeIn.from, type, seen)) {
+      return true
+    }
+  }
+  return false
+}
+
+const filterByType = (nodes, type) => {
+  const found = []
+  for (const node of nodes) {
+    if (node[type] || edgeIsType(node, type)) {
+      found.push(node)
+    }
+  }
+  return found
+}
+
+const depTypes = {
+  // dependency
+  '.prod' (prevResults) {
+    const found = []
+    for (const node of prevResults) {
+      if (!node.dev) {
+        found.push(node)
+      }
+    }
+    return found
+  },
+  // devDependency
+  '.dev' (prevResults) {
+    return filterByType(prevResults, 'dev')
+  },
+  // optionalDependency
+  '.optional' (prevResults) {
+    return filterByType(prevResults, 'optional')
+  },
+  // peerDependency
+  '.peer' (prevResults) {
+    return filterByType(prevResults, 'peer')
+  },
+  // workspace
+  '.workspace' (prevResults) {
+    return prevResults.filter(node => node.isWorkspace)
+  },
+  // bundledDependency
+  '.bundled' (prevResults) {
+    return prevResults.filter(node => node.inBundle)
+  },
+}
+
+// checks if a given node has a direct parent in any of the nodes provided in
+// the compare nodes array
+const hasParent = (node, compareNodes) => {
+  // All it takes is one so we loop and return on the first hit
+  for (const compareNode of compareNodes) {
+    // follows logical parent for link anscestors
+    if (node.isTop && (node.resolveParent === compareNode)) {
+      return true
+    }
+    // follows edges-in to check if they match a possible parent
+    for (const edge of node.edgesIn) {
+      if (edge && edge.from === compareNode) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+// checks if a given node is a descendant of any of the nodes provided in the
+// compareNodes array
+const hasAscendant = (node, compareNodes, seen = new Set()) => {
+  // TODO (future) loop over ancestry property
+  if (hasParent(node, compareNodes)) {
+    return true
+  }
+
+  if (node.isTop && node.resolveParent) {
+    return hasAscendant(node.resolveParent, compareNodes)
+  }
+  for (const edge of node.edgesIn) {
+    // TODO Need a test with an infinite loop
+    if (seen.has(edge)) {
+      continue
+    }
+    seen.add(edge)
+    if (edge && edge.from && hasAscendant(edge.from, compareNodes, seen)) {
+      return true
+    }
+  }
+  return false
+}
+
+const combinators = {
+  // direct descendant
+  '>' (prevResults, nextResults) {
+    return nextResults.filter(node => hasParent(node, prevResults))
+  },
+  // any descendant
+  ' ' (prevResults, nextResults) {
+    return nextResults.filter(node => hasAscendant(node, prevResults))
+  },
+  // sibling
+  '~' (prevResults, nextResults) {
+    // Return any node in nextResults that is a sibling of (aka shares a
+    // parent with) a node in prevResults
+    const parentNodes = new Set() // Parents of everything in prevResults
+    for (const node of prevResults) {
+      for (const edge of node.edgesIn) {
+        // edge.from always exists cause it's from another node's edgesIn
+        parentNodes.add(edge.from)
+      }
+    }
+    return nextResults.filter(node =>
+      !prevResults.includes(node) && hasParent(node, [...parentNodes])
+    )
+  },
+}
+
+const retrieveNodesFromParsedAst = (opts) => {
+  // when we first call this it's the parsed query.  all other times it's
+  // results.currentNode.nestedNode
+  const rootAstNode = opts.rootAstNode
+
+  if (!rootAstNode.nodes) {
+    return new Set()
+  }
+
+  const results = new Results(opts)
+
+  rootAstNode.walk((nextAstNode) => {
+    // This is the only place we reset currentAstNode
+    results.currentAstNode = nextAstNode
+    const updateFn = `${results.currentAstNode.type}Type`
+    if (typeof results[updateFn] !== 'function') {
+      throw Object.assign(
+        new Error(`\`${results.currentAstNode.type}\` is not a supported selector.`),
+        { code: 'EQUERYNOSELECTOR' }
+      )
+    }
+    results[updateFn]()
+  })
+
+  return results.collect(rootAstNode)
+}
+
+// We are keeping this async in the event that we do add async operators, we
+// won't have to have a breaking change on this function signature.
+const querySelectorAll = async (targetNode, query) => {
+  // This never changes ever we just pass it around. But we can't scope it to
+  // this whole file if we ever want to support concurrent calls to this
+  // function.
+  const inventory = [...targetNode.root.inventory.values()]
+  // res is a Set of items returned for each parsed css ast selector
+  const res = retrieveNodesFromParsedAst({
+    initialItems: inventory,
+    inventory,
+    rootAstNode: parser(query),
+    targetNode,
+  })
+
+  // returns nodes ordered by realpath
+  return [...res].sort((a, b) => localeCompare(a.location, b.location))
+}
+
+module.exports = querySelectorAll

package/lib/shrinkwrap.js

@@ -815,7 +815,7 @@ class Shrinkwrap {
       const pathFixed = !resolved ? null
         : !/^file:/.test(resolved) ? resolved
         // resolve onto the metadata path
-        : `file:${resolve(this.path, resolved.slice(5))}`
+        : `file:${resolve(this.path, resolved.slice(5)).replace(/#/g, '%23')}`
 
       // if we have one, only set the other if it matches
       // otherwise it could be for a completely different thing.
@@ -996,7 +996,7 @@ class Shrinkwrap {
       : npa.resolve(node.name, edge.spec, edge.from.realpath)
 
     if (node.isLink) {
-      lock.version = `file:${relpath(this.path, node.realpath)}`
+      lock.version = `file:${relpath(this.path, node.realpath).replace(/#/g, '%23')}`
     } else if (spec && (spec.type === 'file' || spec.type === 'remote')) {
       lock.version = spec.saveSpec
     } else if (spec && spec.type === 'git' || rSpec.type === 'git') {
@@ -1074,7 +1074,7 @@ class Shrinkwrap {
             // this especially shows up with workspace edges when the root
             // node is also a workspace in the set.
             const p = resolve(node.realpath, spec.slice('file:'.length))
-            set[k] = `file:${relpath(node.realpath, p)}`
+            set[k] = `file:${relpath(node.realpath, p).replace(/#/g, '%23')}`
           } else {
             set[k] = spec
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npmcli/arborist",
-  "version": "5.2.3",
+  "version": "5.4.0",
   "description": "Manage node_modules trees",
   "dependencies": {
     "@isaacs/string-locale-compare": "^1.1.0",
@@ -11,12 +11,14 @@
     "@npmcli/name-from-folder": "^1.0.1",
     "@npmcli/node-gyp": "^2.0.0",
     "@npmcli/package-json": "^2.0.0",
+    "@npmcli/query": "^1.1.1",
     "@npmcli/run-script": "^4.1.3",
     "bin-links": "^3.0.0",
     "cacache": "^16.0.6",
     "common-ancestor-path": "^1.0.1",
     "json-parse-even-better-errors": "^2.3.1",
     "json-stringify-nice": "^1.1.4",
+    "minimatch": "^5.1.0",
     "mkdirp": "^1.0.4",
     "mkdirp-infer-owner": "^2.0.0",
     "nopt": "^5.0.0",