push all website files

website/node_modules/npm/doc/spec/file-specifiers.md

@@ -0,0 +1,151 @@
+# `file:` specifiers
+
+`specifier` refers to the value part of the `package.json`'s `dependencies`
+object.  This is a semver expression for registry dependencies and
+URLs and URL-like strings for other types.
+
+### Dependency Specifiers
+
+* A `file:` specifier is either an absolute path (eg `/path/to/thing`, `d:\path\to\thing`):
+  * An absolute `file:///absolute/path` with any number of leading slashes
+    being treated as a single slash. That is, `file:/foo/bar` and
+    `file:///foo/bar` reference the same package.
+* … or a relative path (eg `../path/to/thing`, `path\to\subdir`).  Leading
+  slashes on a file specifier will be removed, that is 'file://../foo/bar`
+  references the same package as same as `file:../foo/bar`.  The latter is
+  considered canonical.
+* Attempting to install a specifier that has a windows drive letter will
+  produce an error on non-Windows systems.
+* A valid `file:` specifier points is:
+  * a valid package file. That is, a `.tar`, `.tar.gz` or `.tgz` containing
+  `<dir>/package.json`.
+  * OR, a directory that contains a `package.json`
+
+Relative specifiers are relative to the file they were found in, or, if
+provided on the command line, the CWD that the command was run from.
+
+An absolute specifier found in a `package.json` or `npm-shrinkwrap.json` is
+probably an error as it's unlikely to be portable between computers and
+should warn.
+
+A specifier provided as a command line argument that is on a different drive
+is an error.  That is, `npm install file:d:/foo/bar` is an error if the
+current drive is `c`.  The point of this rule is that if we can't produce a
+relative path then it's an error.
+
+### Specifier Disambiguation
+
+On the command line, plain paths are allowed.  These paths can be ambiguous
+as they could be a path, a plain package name or a github shortcut.  This
+ambiguity is resolved by checking to see if either a directory exists that
+contains a `package.json`.  If either is the case then the specifier is a
+file specifier, otherwise it's a registry or github specifier.
+
+### Specifier Matching
+
+A specifier is considered to match a dependency on disk when the `realpath`
+of the fully resolved specifier matches the `realpath` of the package on disk.
+
+### Saving File Specifiers
+
+When saving to both `package.json` and `npm-shrinkwrap.json` they will be
+saved using the `file:../relative/path` form, and the relative path will be
+relative to the project's root folder.  This is particularly important to
+note for the `npm-shrinkwrap.json` as it means the specifier there will
+be different then the original `package.json` (where it was relative to that
+`package.json`).
+
+When shrinkwrapping file specifiers, the contents of the destination
+package's `node_modules` WILL NOT be included in the shrinkwrap. If you want to lock
+down the destination package's `node_modules` you should create a shrinkwrap for it
+separately.
+
+This is necessary to support the mono repo use case where many projects file
+to the same package.  If each project included its own `npm-shrinkwrap.json`
+then they would each have their own distinct set of transitive dependencies
+and they'd step on each other any time you ran an install in one or the other.
+
+NOTE: This should not have an effect on shrinkwrapping of other sorts of
+shrinkwrapped packages.
+
+### Installation
+
+#### File type specifiers pointing at tarballs
+
+File-type specifiers pointing at a `.tgz` or `.tar.gz` or `.tar` file will
+install it as a package file in the same way we would a remote tarball.  The
+checksum of the package file should be recorded so that we can check for updates.
+
+#### File type specifers pointing at directories
+
+File-type specifiers that point at directories will necessarily not do
+anything for `fetch` and `extract` phases.
+
+The symlink should be created during the `finalize` phase.
+
+The `preinstall` for file-type specifiers MUST be run AFTER the
+`finalize` phase as the symlink may be a relative path reaching outside the
+current project root and a symlink that resolves in `.staging` won't resolve
+in the package's final resting place.
+
+If the module is inside the package root that we're running the install for then
+dependencies of the linked package will be hoisted to the top level as usual.
+
+If the module is outside the package root then dependencies will be installed inside
+the linked module's `node_modules` folder.
+
+### Removal
+
+Removal should remove the symlink.
+
+Removal MUST NOT remove the transitive dependencies IF they're installed in
+the linked module's `node_modules` folder.
+
+### Listing
+
+In listings they should not include a version as the version is not
+something `npm` is concerned about.  This also makes them easily
+distinguishable from symlinks of packages that have other dependency
+specifiers.
+
+If you had run:
+
+```
+npm install --save file:../a
+```
+
+And then run:
+```
+npm ls
+```
+
+You would see:
+
+```
+example-package@1.0.0 /path/to/example-package
+└── a → file:../a
+```
+
+```
+example-package@1.0.0 /path/to/example-package
++-- a -> file:../a
+```
+
+Of note here: No version is included as the relevant detail is WHERE the
+package came from, not what version happened to be in that path.
+
+### Outdated
+
+Local specifiers should only show up in `npm outdated` if they're missing
+and when they do, they should be reported as:
+
+```
+Package  Current  Wanted  Latest  Location
+a        MISSING   LOCAL   LOCAL  example-package
+```
+
+### Updating
+
+If a dependency with a local specifier is already installed then `npm
+update` shouldn't do anything.  If one is missing then it should be
+installed as if you ran `npm install`.

website/node_modules/npm/doc/spec/package-lock.md

@@ -0,0 +1,276 @@
+# package-lock and npm-shrinkwrap
+
+`npm` can have one of two different lock files:
+
+* `package-lock.json`, which is ordinarily always present and is never published.
+* `npm-shrinkwrap.json`, which is created with `npm shrinkwrap` and usually published.
+
+You can only have one of them and in the event that you have both,
+`npm-shrinkwrap.json` takes precedence.  The files are exactly the same
+format and in fact all the `npm shrinkwrap` command does is rename your
+`package-lock.json`.
+
+Through the rest of this document we will refer to the package-lock and
+`package-lock.json` but everything also applies to `npm-shrinkwrap.json`.
+
+## File Format
+
+### name
+
+The name of the package this is a package-lock for. This must match what's in `package.json`.
+
+### version
+
+The version of the package this is a package-lock for. This must match what's in `package.json`.
+
+### lockfileVersion *(new)*
+
+An integer version, starting at `1` with the version number of this document
+whose semantics were used when generating this `package-lock.json`.
+
+### preserveSymlinks *(new)*
+
+Indicates that the install was done with the environment variable
+`NODE_PRESERVE_SYMLINKS` enabled. The installer should insist that the value of this
+property match that environment variable.
+
+### dependencies
+
+These are the modules installed in the `node_modules`.  Some of these are
+dependencies some of these are transitive dependencies (that is,
+dependencies of our dependencies).
+
+This is a mapping of package name to dependency object.  Dependency objects have the
+following properties:
+
+#### version *(changed)*
+
+This is a specifier that uniquely identifies this package and should be
+usable in fetching a new copy of it.
+
+* bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes.
+* registry sources: This is a version number. (eg, `1.2.3`)
+* git sources: This is a git specifier with resolved committish. (eg, `git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`)
+* http tarball sources: This is the URL of the tarball. (eg, `https://example.com/example-1.3.0.tgz`)
+* local tarball sources: This is the file URL of the tarball. (eg `file:///opt/storage/example-1.3.0.tgz`)
+* local link sources: This is the file URL of the link. (eg `file:libs/our-module`)
+
+#### integrity *(new)*
+
+This is a [Standard Subresource
+Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) for
+this resource.
+
+* For bundled dependencies this is not included, regardless of source.
+* For registry sources, this is the `integrity` that the registry provided, or if one wasn't provided the SHA1 in `shasum`.
+* For git sources this is the specific commit hash we cloned from.
+* For remote tarball sources this is an integrity based on a SHA512 of
+  the file.
+* For local tarball sources: This is an integrity field based on the SHA512 of the file.
+
+#### resolved
+
+* For bundled dependencies this is not included, regardless of source.
+* For registry sources this is path of the tarball relative to the registry
+  URL.  If the tarball URL isn't on the same server as the registry URL then
+  this is a complete URL.
+
+#### link *(new)*
+
+If this module was symlinked in development but had semver in the
+`package.json` then this is the relative path of that link.
+
+Discussion of the semantics of this will go in the symlinks RFC.
+
+Implementation note: To be implemented post npm@5.
+
+#### bundled *(new)*
+
+If true, this is the bundled dependency and will be installed by the parent
+module.  When installing, this module will be extracted from the parent
+module during the extract phase, not installed as a separate dependency.
+
+#### dev
+
+If true then this dependency is either a development dependency ONLY of the
+top level module or a transitive dependency of one.  This is false for
+dependencies that are both a development dependency of the top level and a
+transitive dependency of a non-development dependency of the top level.
+
+#### optional
+
+If true then this dependency is either an optional dependency ONLY of the
+top level module or a transitive dependency of one.  This is false for
+dependencies that are both an optional dependency of the top level and a
+transitive dependency of a non-optional dependency of the top level.
+
+All optional dependencies should be included even if they're uninstallable
+on the current platform.
+
+#### from
+
+This is a record of what specifier was used to originally install this
+package.  This should be used only for git dependencies.
+
+#### requires
+
+This is a mapping of module name to version.  This is a list of everything
+this module requires, regardless of where it will be installed.  The version
+should match via normal matching rules a dependency either in our
+`dependencies` or in a level higher than us.
+
+#### dependencies
+
+Exactly like `dependencies` at the top level, this is a list of modules to
+install in the `node_modules` of this module.
+
+## Generating
+
+### `npm init`
+
+If neither a `package-lock.json` nor an `npm-shrinkwrap.json` exist then
+`npm init` will create a `package-lock.json`.  This is functionally
+equivalent to running `npm shrinkwrap` after the current init completes and
+renaming the result to `package-lock.json`.
+
+### `npm install --save`
+
+If either an `npm-shrinkwrap.json` or a `package-lock.json` exists then it
+will be updated.
+
+If neither exist then a `package-lock.json` should be generated.
+
+If a `package.json` does not exist, it should be generated.  The generated
+`package.json` should be empty, as in:
+
+```
+{
+   "dependencies": {
+   }
+}
+```
+
+If the user wants to get a default package name/version added they can run `npm init`.
+
+### `npm shrinkwrap`
+
+If a `package-lock.json` exists, rename it to `npm-shrinkwrap.json`.
+Refresh the data from the installer's ideal tree.
+
+The top level `name` and `version` come from the `package.json`.  It is an
+error if either are missing or invalid.
+
+#### dependencies.dev
+
+This is `true` if this dependency is ONLY installed to fulfill either a top
+level development dependency, or one of its transitive dependencies.
+
+Given:
+```
+B (Dev) → C
+```
+
+Then both B and C would be `dev: true`.
+
+Given:
+```
+A → B → C
+B (Dev) -> C
+```
+
+Then all dependencies would be `dev: false`.
+
+#### dependencies.optional
+
+This is `true` if this dependency is ONLY ever either an optional dependency
+or a transitive dependency of optional dependencies.
+
+Given:
+```
+A (Opt) → B → C
+```
+
+Then all three of A, B and C would be flagged as optional.
+
+Given:
+```
+A (Opt) → B → C
+D → C
+```
+
+Then A and B would be flagged as optional, but C would not be.
+
+Given:
+```
+A (Opt) → B → C
+D → A
+```
+
+Then none would be flagged as optional.
+
+## Installing
+
+If the `packageIntegrity` in the `package-lock.json` differs from the one
+computed from the `package.json` then places where the `package.json` is
+incompatible with the `package-lock.json` a new module should be installed.
+That is, while the `package-lock.json` ordinarily defines the state of your
+project, if your `package.json` is edited independently it will take
+precedence.
+
+The `package-lock.json` describes the exact tree that `npm` should create.
+Any deviation between the `package.json` and the shrinkwrap/lock should
+result in a warning be issued.  This includes:
+
+* Modules in `package.json` but missing from the `package-lock.json`
+* Modules in the `package-lock.json` but missing from the `package.json`.
+* Modules in `package.json` whose specifiers don't match the version in `package-lock.json`.
+
+Warn if the `lockfileVersion` in the `package-lock.json` is for a different
+major version than we implement.
+
+Module resolution from package-lock data works as such:
+
+* If install was run with `--resolve-links` and a dependency has a `link`
+  property then a symlink is made using that.  If the version of the
+  destination can not be matched to the package-lock and/or the package.json
+  then a warning will be issued.
+
+* Otherwise, if a `integrity` is available then we try to install it from the cache using it.
+
+If `integrity` is unavailable or we are unable to locate a module from the `integrity` then:
+
+* If `lockfileVersion` is set:
+  * Install using the value of `version` and validate the result against the
+    `integrity`.
+* Otherwise, try these in turn and validate the result against the `integrity`:
+  * `resolved`, then `from`, then `version.
+  * `from` can be either `package@specifier` or just `specifier`.
+
+Regardless of how the module is installed the metadata in the installed
+module should be identical to what it would have been if the module were
+installed w/o a package-lock.
+
+## Implied Changes To Other Commands
+
+### `npm rm --save`
+
+Currently if you ask to remove a package that's both a direct and a
+transitive dependency, we'll remove the package from `node_modules` even if
+this results in a broken tree.  This was chosen at the time because we felt
+that users would expect `npm rm pkgname` to be equivalent of
+`rm -rf node_modules/pkgname`.
+
+As you are no longer going to be allowed to put your `node_modules` in a
+state that's not a valid package-lock, this means this behavior is no longer
+valid.  Instead we should follow normal rules, removing it from the
+dependencies for the top level but only removing the module on disk if
+nothing requires it any more.
+
+## Additional fields / Adding new fields
+
+Installers should ignore any field they aren't aware of.  It's not an error
+to have additional properties in the package-lock or lock file.
+
+Installers that want to add new fields should either have one added via RFC
+in the npm issue tracker and an accompanying documentation PR, or should prefix
+it with the name of their project.