File Explorer

1const { explainNode } = require('../utils/explain-dep.js')2const npa = require('npm-package-arg')3const semver = require('semver')4const { relative, resolve } = require('node:path')5const validName = require('validate-npm-package-name')6const { output } = require('proc-log')7const ArboristWorkspaceCmd = require('../arborist-cmd.js')8 9class Explain extends ArboristWorkspaceCmd {10  static description = 'Explain installed packages'11  static name = 'explain'12  static usage = ['<package-spec>']13  static params = [14    'json',15    'workspace',16  ]17 18  static ignoreImplicitWorkspace = false19 20  static async completion (opts, npm) {21    const completion = require('../utils/installed-deep.js')22    return completion(npm, opts)23  }24 25  async exec (args) {26    if (!args.length) {27      throw this.usageError()28    }29 30    const Arborist = require('@npmcli/arborist')31    const arb = new Arborist({ path: this.npm.prefix, ...this.npm.flatOptions })32    const tree = await arb.loadActual()33 34    if (this.npm.flatOptions.workspacesEnabled35      && this.workspaceNames36      && this.workspaceNames.length37    ) {38      this.filterSet = arb.workspaceDependencySet(tree, this.workspaceNames)39    } else if (!this.npm.flatOptions.workspacesEnabled) {40      this.filterSet =41        arb.excludeWorkspacesDependencySet(tree)42    }43 44    const nodes = new Set()45    for (const arg of args) {46      for (const node of this.getNodes(tree, arg)) {47        const filteredOut = this.filterSet48          && this.filterSet.size > 049          && !this.filterSet.has(node)50        if (!filteredOut) {51          nodes.add(node)52        }53      }54    }55    if (nodes.size === 0) {56      throw new Error(`No dependencies found matching ${args.join(', ')}`)57    }58 59    const expls = []60    for (const node of nodes) {61      const { extraneous, dev, optional, devOptional, peer, inBundle, overridden } = node62      const expl = node.explain()63      if (extraneous) {64        expl.extraneous = true65      } else {66        expl.dev = dev67        expl.optional = optional68        expl.devOptional = devOptional69        expl.peer = peer70        expl.bundled = inBundle71        expl.overridden = overridden72      }73      expls.push(expl)74    }75 76    if (this.npm.flatOptions.json) {77      output.buffer(expls)78    } else {79      output.standard(expls.map(expl => {80        return explainNode(expl, Infinity, this.npm.chalk)81      }).join('\n\n'))82    }83  }84 85  getNodes (tree, arg) {86    // if it's just a name, return packages by that name87    const { validForOldPackages: valid } = validName(arg)88    if (valid) {89      return tree.inventory.query('packageName', arg)90    }91 92    // if it's a location, get that node93    const maybeLoc = arg.replace(/\\/g, '/').replace(/(?<!\/)\/+$/, '')94    const nodeByLoc = tree.inventory.get(maybeLoc)95    if (nodeByLoc) {96      return [nodeByLoc]97    }98 99    // maybe a path to a node_modules folder100    const maybePath = relative(this.npm.prefix, resolve(maybeLoc))101      .replace(/\\/g, '/').replace(/(?<!\/)\/+$/, '')102    const nodeByPath = tree.inventory.get(maybePath)103    if (nodeByPath) {104      return [nodeByPath]105    }106 107    // otherwise, try to select all matching nodes108    try {109      return this.getNodesByVersion(tree, arg)110    } catch {111      return []112    }113  }114 115  getNodesByVersion (tree, arg) {116    const spec = npa(arg, this.npm.prefix)117    if (spec.type !== 'version' && spec.type !== 'range') {118      return []119    }120 121    return tree.inventory.filter(node => {122      return node.package.name === spec.name &&123        semver.satisfies(node.package.version, spec.rawSpec)124    })125  }126}127 128module.exports = Explain129