docs: Drop stale Python 3<->node-gyp remark

docs/content/commands/npm-link.md

@@ -99,6 +99,16 @@ relevant metadata by running `npm install <dep> --package-lock-only`.
 If you _want_ to save the `file:` reference in your `package.json` and
 `package-lock.json` files, you can use `npm link <dep> --save` to do so.
 
+### Workspace Usage
+
+`npm link <pkg> --workspace <name>` will link the relevant package as a
+dependency of the specified workspace(s).  Note that It may actually be
+linked into the parent project's `node_modules` folder, if there are no
+conflicting dependencies.
+
+`npm link --workspace <name>` will create a global link to the specified
+workspace(s).
+
 ### Configuration
 
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
@@ -261,6 +271,38 @@ commands that modify your local installation, eg, `install`, `update`,
 Note: This is NOT honored by other network related commands, eg `dist-tags`,
 `owner`, etc.
 
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result to selecting all of the
+  nested workspaces)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also

docs/content/commands/npm-pack.md

@@ -27,6 +27,15 @@ commands that modify your local installation, eg, `install`, `update`,
 Note: This is NOT honored by other network related commands, eg `dist-tags`,
 `owner`, etc.
 
+#### `json`
+
+* Default: false
+* Type: Boolean
+
+Whether or not to output JSON data, rather than the normal output.
+
+Not supported by all npm commands.
+
 #### `workspace`
 
 * Default:

docs/content/commands/npm.md

@@ -62,10 +62,8 @@ requires compiling of C++ Code, npm will use
 [node-gyp](https://github.com/nodejs/node-gyp) for that task.
 For a Unix system, [node-gyp](https://github.com/nodejs/node-gyp)
 needs Python, make and a buildchain like GCC. On Windows,
-Python and Microsoft Visual Studio C++ are needed. Python 3 is
-not supported by [node-gyp](https://github.com/nodejs/node-gyp).
-For more information visit
-[the node-gyp repository](https://github.com/nodejs/node-gyp) and
+Python and Microsoft Visual Studio C++ are needed. For more information
+visit [the node-gyp repository](https://github.com/nodejs/node-gyp) and
 the [node-gyp Wiki](https://github.com/nodejs/node-gyp/wiki).
 
 ### Directories

docs/content/configuring-npm/package-lock-json.md

@@ -36,8 +36,8 @@ various purposes:
 Both of these files have the same format, and perform similar functions in
 the root of a project.
 
-The difference is that `package-lock.json` is that it cannot be published,
-and it will be ignored if found in any place other than the root project.
+The difference is that `package-lock.json` cannot be published, and it will 
+be ignored if found in any place other than the root project.
 
 In contrast, [npm-shrinkwrap.json](/configuring-npm/npm-shrinkwrap-json) allows
 publication, and defines the dependency tree from the point encountered.

docs/content/using-npm/scripts.md

@@ -304,7 +304,7 @@ For example, if your package.json contains this:
 {
   "scripts" : {
     "install" : "scripts/install.js",
-    "postinstall" : "scripts/postinstall.js",
+    "postinstall" : "scripts/install.js",
     "uninstall" : "scripts/uninstall.js"
   }
 }

lib/base-command.js

@@ -7,6 +7,7 @@ class BaseCommand {
     this.wrapWidth = 80
     this.npm = npm
     this.workspaces = null
+    this.workspacePaths = null
   }
 
   get name () {

lib/link.js

@@ -10,8 +10,8 @@ const semver = require('semver')
 
 const reifyFinish = require('./utils/reify-finish.js')
 
-const BaseCommand = require('./base-command.js')
-class Link extends BaseCommand {
+const ArboristWorkspaceCmd = require('./workspaces/arborist-cmd.js')
+class Link extends ArboristWorkspaceCmd {
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get description () {
     return 'Symlink a package folder'
@@ -46,6 +46,7 @@ class Link extends BaseCommand {
       'bin-links',
       'fund',
       'dry-run',
+      ...super.params,
     ]
   }
 
@@ -143,12 +144,16 @@ class Link extends BaseCommand {
       log: this.npm.log,
       add: names.map(l => `file:${resolve(globalTop, 'node_modules', l)}`),
       save,
+      workspaces: this.workspaces,
     })
 
     await reifyFinish(this.npm, localArb)
   }
 
   async linkPkg () {
+    const wsp = this.workspacePaths
+    const paths = wsp && wsp.length ? wsp : [this.npm.prefix]
+    const add = paths.map(path => `file:${path}`)
     const globalTop = resolve(this.npm.globalDir, '..')
     const arb = new Arborist({
       ...this.npm.flatOptions,
@@ -157,7 +162,7 @@ class Link extends BaseCommand {
       global: true,
     })
     await arb.reify({
-      add: [`file:${this.npm.prefix}`],
+      add,
       log: this.npm.log,
     })
     await reifyFinish(this.npm, arb)

lib/ls.js

@@ -1,4 +1,5 @@
-const { resolve } = require('path')
+const { resolve, relative, sep } = require('path')
+const relativePrefix = `.${sep}`
 const { EOL } = require('os')
 
 const archy = require('archy')
@@ -298,6 +299,9 @@ const getHumanOutputItem = (node, { args, color, global, long }) => {
     ? chalk.yellow.bgBlack
     : chalk.red.bgBlack
   const missingMsg = `UNMET ${isOptional(node) ? 'OPTIONAL ' : ''}DEPENDENCY`
+  const targetLocation = node.root
+    ? relative(node.root.realpath, node.realpath)
+    : node.targetLocation
   const label =
     (
       node[_missing]
@@ -321,7 +325,7 @@ const getHumanOutputItem = (node, { args, color, global, long }) => {
         : ''
     ) +
     (isGitNode(node) ? ` (${node.resolved})` : '') +
-    (node.isLink ? ` -> ${node.realpath}` : '') +
+    (node.isLink ? ` -> ${relativePrefix}${targetLocation}` : '') +
     (long ? `${EOL}${node.package.description || ''}` : '')
 
   return augmentItemWithIncludeMetadata(node, { label, nodes: [] })
@@ -445,6 +449,9 @@ const augmentNodesWithMetadata = ({
   // revisit that node in tree traversal logic, so we make it so that
   // we have a diff obj for deduped nodes:
   if (seenNodes.has(node.path)) {
+    const { realpath, root } = node
+    const targetLocation = root ? relative(root.realpath, realpath)
+      : node.targetLocation
     node = {
       name: node.name,
       version: node.version,
@@ -453,6 +460,7 @@ const augmentNodesWithMetadata = ({
       path: node.path,
       isLink: node.isLink,
       realpath: node.realpath,
+      targetLocation,
       [_type]: node[_type],
       [_invalid]: node[_invalid],
       [_missing]: node[_missing],

lib/utils/completion.sh

@@ -18,11 +18,15 @@ if type complete &>/dev/null; then
     fi
 
     local si="$IFS"
-    IFS=$'\n' COMPREPLY=($(COMP_CWORD="$cword" \
+    if ! IFS=$'\n' COMPREPLY=($(COMP_CWORD="$cword" \
                            COMP_LINE="$COMP_LINE" \
                            COMP_POINT="$COMP_POINT" \
                            npm completion -- "${words[@]}" \
-                           2>/dev/null)) || return $?
+                           2>/dev/null)); then
+      local ret=$?
+      IFS="$si"
+      return $ret
+    fi
     IFS="$si"
     if type __ltrim_colon_completions &>/dev/null; then
       __ltrim_colon_completions "${words[cword]}"
@@ -49,11 +53,16 @@ elif type compctl &>/dev/null; then
     read -l line
     read -ln point
     si="$IFS"
-    IFS=$'\n' reply=($(COMP_CWORD="$cword" \
+    if ! IFS=$'\n' reply=($(COMP_CWORD="$cword" \
                        COMP_LINE="$line" \
                        COMP_POINT="$point" \
                        npm completion -- "${words[@]}" \
-                       2>/dev/null)) || return $?
+                       2>/dev/null)); then
+
+      local ret=$?
+      IFS="$si"
+      return $ret
+    fi
     IFS="$si"
   }
   compctl -K _npm_completion npm

lib/utils/reify-output.js

@@ -18,17 +18,20 @@ const auditError = require('./audit-error.js')
 
 // TODO: output JSON if flatOptions.json is true
 const reifyOutput = (npm, arb) => {
-  // don't print any info in --silent mode
-  if (log.levels[log.level] > log.levels.error)
-    return
-
   const { diff, actualTree } = arb
 
   // note: fails and crashes if we're running audit fix and there was an error
   // which is a good thing, because there's no point printing all this other
   // stuff in that case!
   const auditReport = auditError(npm, arb.auditReport) ? null : arb.auditReport
 
+  // don't print any info in --silent mode, but we still need to
+  // set the exitCode properly from the audit report, if we have one.
+  if (log.levels[log.level] > log.levels.error) {
+    getAuditReport(npm, auditReport)
+    return
+  }
+
   const summary = {
     added: 0,
     removed: 0,
@@ -68,6 +71,8 @@ const reifyOutput = (npm, arb) => {
 
   if (npm.flatOptions.json) {
     if (auditReport) {
+      // call this to set the exit code properly
+      getAuditReport(npm, auditReport)
       summary.audit = npm.command === 'audit' ? auditReport
         : auditReport.toJSON().metadata
     }
@@ -83,11 +88,25 @@ const reifyOutput = (npm, arb) => {
 // at the end if there's still stuff, because it's silly for `npm audit`
 // to tell you to run `npm audit` for details.  otherwise, use the summary
 // report.  if we get here, we know it's not quiet or json.
+// If the loglevel is set higher than 'error', then we just run the report
+// to get the exitCode set appropriately.
 const printAuditReport = (npm, report) => {
+  const res = getAuditReport(npm, report)
+  if (!res || !res.report)
+    return
+  npm.output(`\n${res.report}`)
+}
+
+const getAuditReport = (npm, report) => {
   if (!report)
     return
 
-  const reporter = npm.command !== 'audit' ? 'install' : 'detail'
+  // when in silent mode, we print nothing.  the JSON output is
+  // going to just JSON.stringify() the report object.
+  const reporter = log.levels[log.level] > log.levels.error ? 'quiet'
+    : npm.flatOptions.json ? 'quiet'
+    : npm.command !== 'audit' ? 'install'
+    : 'detail'
   const defaultAuditLevel = npm.command !== 'audit' ? 'none' : 'low'
   const auditLevel = npm.flatOptions.auditLevel || defaultAuditLevel
 
@@ -96,8 +115,9 @@ const printAuditReport = (npm, report) => {
     ...npm.flatOptions,
     auditLevel,
   })
-  process.exitCode = process.exitCode || res.exitCode
-  npm.output('\n' + res.report)
+  if (npm.command === 'audit')
+    process.exitCode = process.exitCode || res.exitCode
+  return res
 }
 
 const packagesChangedMessage = (npm, { added, removed, changed, audited }) => {

lib/workspaces/arborist-cmd.js

@@ -17,6 +17,7 @@ class ArboristCmd extends BaseCommand {
     getWorkspaces(filters, { path: this.npm.localPrefix })
       .then(workspaces => {
         this.workspaces = [...workspaces.keys()]
+        this.workspacePaths = [...workspaces.values()]
         this.exec(args, cb)
       })
       .catch(er => cb(er))