[BUG] Man pages are deleted, but not reinstalled

[remcohaszing]

Current Behavior:

When upgrading npm using npm 7, the man pages are gone.

Expected Behavior:

Man pages are installed.

Steps To Reproduce:

1. Install NodeJS from the nodesource PPA
2. Given the following .npmrc (adapt to your own home directory):

   prefix=/home/remco/.local
   

3. Running npm install -g npm@7.6.0 installs npm 7. Man pages appear in ~/.local/share/man
4. Now running npm install -g npm@latest installs updates npm 7, but npm man pages are removed from in ~/.local/share/man.

Environment:

• OS: Ubuntu 10
• Node: 14.16.0
• npm: 7.x

[Zordrak]

I am of the opinion that man pages are completely broken in npmv7, and this is just a symptom - using npmv7 to install anything, including npm, will result in no man pages.

I have been trawling the code all day long, adding debug statements and learning Arborist to try to understand why my package's man page isn't getting installed, and the most I have been able to understand is:

• Everything happens under Arborist now
• The Node object constructed in Arborist gets given bin paths, but not man paths, from the raw package.json. I still haven't quite worked out where the raw package.json becomes the package object that is passed into the Node class constructor.
• Nowhere in Arborist is there any defined reference or support for a man path meaning that it expects it to be either provided in the package object that is used to first populate the node object in the constructor, or it's expecting it to be populated dynamically by a subsequent call to bin-links/get-paths.getPaths()
• The Arborist Node object is granted a getter called binPaths that calls bin-links/get-paths.getPaths() (aliased as getBinPaths)
• However, Node.binPaths is only ever used twice in Arborist
  • once in lib/diff.js to confirm all the paths exist
  • once in lib/arborist/reify.js under _addNodeToTrashList to make sure the binPaths are deleted on removal

I believe that somewhere there is supposed to be a call to Node.binPaths that doesn't seem to exist. This call would return both the bin and man paths into the Node.package property that would be used later in bin-links/index.binLinks() to link both bins and man pages - but instead of calling Node.binPaths, it is just relying on the Node object having been instantiated with the bin property in the constructor's source data, rather than getting it through Node.binPaths.

It should be noted that if Arborist was doing what I think it is supposed to be doing to get the paths and link them using bin-links; bin-links does not follow the NPM documentation which states that man paths can be a string or an Array, as there is a hard-check in bin-links/get-paths.getPaths() for an Array: (manTarg && pkg.man && Array.isArray(pkg.man) && pkg.man.length)

Additionally, I have seen documentation stating that you can also use package.json sugar to include a man directory in the directories property, which should include all man pages in the directory - but I see no support for that in Arborist or in bin-links.

[wraithgar]

See #4276 for more context