packages keys do not appear to be true paths

[craxal]

Documentation for the keys of the packages property in package-lock.json files describes them as "relative paths from the root project folder". This does not appear to be entirely true.

Consider the following package.json:

package.json:

{
  "name": "my-project",
  "dependencies": {
    "@scope/package-a": "^1.0.0",
  }
}

Assume also that "@scope/package-a" has a dependency on a package called "@scope.package-b". When npm installs dependencies, the project directory structure looks like this:

my-project
├─node_modules
│ └─@scope
│   ├─package-a
│   └─package-b
├─package.json
└─package-lock.json

However, package-lock.json has the following entry under packages:

"node_modules/@scope/package-a/node_modules/@scope/package-b": {
  "version": "1.0.0",
  ...
},

Notice the path does not actually exist in the directory.

Documentation should be clear about whether this is expected or whether the relative paths, as described, are true paths.

[ljharb]

They're paths into the ideal tree, I believe, not the actual tree on disk.

[craxal]

@ljhard I figured. But that's not clear in the documentation. A project I'm on requires information from the package lock file, and I would have been saved a lot of frustration if the documentation had been clearer about that on this point.

[ljharb]

I'd suggest using arborist, rather than directly accessing a lockfile or node_modules.

[craxal]

@ljhard Thank you for the suggestion. I can consider that. Regardless, this issue is about having clearer npm documentation.