update

package/node_modules/@npmcli/installed-package-contents/README.md

@@ -0,0 +1,109 @@
+# @npmcli/installed-package-contents
+
+Get the list of files installed in a package in node_modules, including
+bundled dependencies.
+
+This is useful if you want to remove a package node from the tree _without_
+removing its child nodes, for example to extract a new version of the
+dependency into place safely.
+
+It's sort of the reflection of [npm-packlist](http://npm.im/npm-packlist),
+but for listing out the _installed_ files rather than the files that _will_
+be installed.  This is of course a much simpler operation, because we don't
+have to handle ignore files or package.json `files` lists.
+
+## USAGE
+
+```js
+// programmatic usage
+const pkgContents = require('@npmcli/installed-package-contents')
+
+pkgContents({ path: 'node_modules/foo', depth: 1 }).then(files => {
+  // files is an array of items that need to be passed to
+  // rimraf or moved out of the way to make the folder empty
+  // if foo bundled dependencies, those will be included.
+  // It will not traverse into child directories, because we set
+  // depth:1 in the options.
+  // If the folder doesn't exist, this returns an empty array.
+})
+
+pkgContents({ path: 'node_modules/foo', depth: Infinity }).then(files => {
+  // setting depth:Infinity tells it to keep walking forever
+  // until it hits something that isn't a directory, so we'll
+  // just get the list of all files, but not their containing
+  // directories.
+})
+```
+
+As a CLI:
+
+```bash
+$ installed-package-contents node_modules/bundle-some -d1
+node_modules/.bin/some
+node_modules/bundle-some/package.json
+node_modules/bundle-some/node_modules/@scope/baz
+node_modules/bundle-some/node_modules/.bin/foo
+node_modules/bundle-some/node_modules/foo
+```
+
+CLI options:
+
+```
+Usage:
+  installed-package-contents <path> [-d<n> --depth=<n>]
+
+Lists the files installed for a package specified by <path>.
+
+Options:
+  -d<n> --depth=<n>   Provide a numeric value ("Infinity" is allowed)
+                      to specify how deep in the file tree to traverse.
+                      Default=1
+  -h --help           Show this usage information
+```
+
+## OPTIONS
+
+* `depth` Number, default `1`.  How deep to traverse through folders to get
+    contents.  Typically you'd want to set this to either `1` (to get the
+    surface files and folders) or `Infinity` (to get all files), but any
+    other positive number is supported as well.  If set to `0` or a
+    negative number, returns the path provided and (if it is a package) its
+    set of linked bins.
+* `path` Required.  Path to the package in `node_modules` where traversal
+    should begin.
+
+## RETURN VALUE
+
+A Promise that resolves to an array of fully-resolved files and folders
+matching the criteria.  This includes all bundled dependencies in
+`node_modules`, and any linked executables in `node_modules/.bin` that the
+package caused to be installed.
+
+An empty or missing package folder will return an empty array.  Empty
+directories _within_ package contents are listed, even if the `depth`
+argument would cause them to be traversed into.
+
+## CAVEAT
+
+If using this module to generate a list of files that should be recursively
+removed to clear away the package, note that this will leave empty
+directories behind in certain cases:
+
+- If all child packages are bundled dependencies, then the
+    `node_modules` folder will remain.
+- If all child packages within a given scope were bundled dependencies,
+    then the `node_modules/@scope` folder will remain.
+- If all linked bin scripts were removed, then an empty `node_modules/.bin`
+    folder will remain.
+
+In the interest of speed and algorithmic complexity, this module does _not_
+do a subsequent readdir to see if it would remove all directory entries,
+though it would be easier to look at if it returned `node_modules` or
+`.bin` in that case rather than the contents.  However, if the intent is to
+pass these arguments to `rimraf`, it hardly makes sense to do _two_
+`readdir` calls just so that we can have the luxury of having to make a
+third.
+
+Since the primary use case is to delete a package's contents so that they
+can be re-filled with a new version of that package, this caveat does not
+pose a problem.  Empty directories are already ignored by both npm and git.