diff --git a/deps/npm/docs/README.md b/deps/npm/docs/README.md deleted file mode 100644 index 5fc7ccf6cd60ac..00000000000000 --- a/deps/npm/docs/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# docs - -[![CI - docs](https://github.com/npm/cli/actions/workflows/ci-docs.yml/badge.svg)](https://github.com/npm/cli/actions/workflows/ci-docs.yml) - -Scripts to build the npm docs. diff --git a/deps/npm/docs/content/commands/npm-install-test.md b/deps/npm/docs/content/commands/npm-install-test.md index 3b94ea27763f8f..b73614de2d4f42 100644 --- a/deps/npm/docs/content/commands/npm-install-test.md +++ b/deps/npm/docs/content/commands/npm-install-test.md @@ -290,6 +290,16 @@ field of package.json, which comes from `process.platform`. +#### `libc` + +* Default: null +* Type: null or String + +Override libc of native modules to install. Acceptable values are same as +`libc` field of package.json + + + #### `workspace` * Default: diff --git a/deps/npm/docs/content/commands/npm-install.md b/deps/npm/docs/content/commands/npm-install.md index 738ca3372c8e9f..36496954270b30 100644 --- a/deps/npm/docs/content/commands/npm-install.md +++ b/deps/npm/docs/content/commands/npm-install.md @@ -680,6 +680,16 @@ field of package.json, which comes from `process.platform`. +#### `libc` + +* Default: null +* Type: null or String + +Override libc of native modules to install. Acceptable values are same as +`libc` field of package.json + + + #### `workspace` * Default: diff --git a/deps/npm/docs/content/commands/npm-ls.md b/deps/npm/docs/content/commands/npm-ls.md index 4ad025dbb5b08e..a21d14e577df61 100644 --- a/deps/npm/docs/content/commands/npm-ls.md +++ b/deps/npm/docs/content/commands/npm-ls.md @@ -27,7 +27,7 @@ packages will *also* show the paths to the specified packages. For example, running `npm ls promzard` in npm's source tree will show: ```bash -npm@10.2.4 /path/to/npm +npm@10.3.0 /path/to/npm └─┬ init-package-json@0.0.4 └── promzard@0.1.5 ``` diff --git a/deps/npm/docs/content/commands/npm-publish.md b/deps/npm/docs/content/commands/npm-publish.md index 0e18cddf8b36d4..a9c368e218543f 100644 --- a/deps/npm/docs/content/commands/npm-publish.md +++ b/deps/npm/docs/content/commands/npm-publish.md @@ -22,7 +22,7 @@ scope-configured registry (see A `package` is interpreted the same way as other commands (like -`npm install` and can be: +`npm install`) and can be: * a) a folder containing a program described by a [`package.json`](/configuring-npm/package-json) file diff --git a/deps/npm/docs/content/commands/npm-sbom.md b/deps/npm/docs/content/commands/npm-sbom.md index ee0d60c6fde790..6e8033b96aedc7 100644 --- a/deps/npm/docs/content/commands/npm-sbom.md +++ b/deps/npm/docs/content/commands/npm-sbom.md @@ -266,7 +266,7 @@ SBOM format to use when generating SBOMs. * Type: "library", "application", or "framework" The type of package described by the generated SBOM. For SPDX, this is the -value for the `primaryPackagePurpose` fieled. For CycloneDX, this is the +value for the `primaryPackagePurpose` field. For CycloneDX, this is the value for the `type` field. diff --git a/deps/npm/docs/content/commands/npm-unpublish.md b/deps/npm/docs/content/commands/npm-unpublish.md index 8ab976e96cb6c7..2421e102325363 100644 --- a/deps/npm/docs/content/commands/npm-unpublish.md +++ b/deps/npm/docs/content/commands/npm-unpublish.md @@ -27,8 +27,12 @@ removing the tarball. The npm registry will return an error if you are not [logged in](/commands/npm-adduser). -If you do not specify a version or if you remove all of a package's -versions then the registry will remove the root package entry entirely. +If you do not specify a package name at all, the name and version to be +unpublished will be pulled from the project in the current directory. + +If you specify a package name but do not specify a version or if you +remove all of a package's versions then the registry will remove the +root package entry entirely. Even if you unpublish a package version, that specific name and version combination can never be reused. In order to publish the package again, diff --git a/deps/npm/docs/content/commands/npm.md b/deps/npm/docs/content/commands/npm.md index 1528614f69a69a..d92e83e5ccdd19 100644 --- a/deps/npm/docs/content/commands/npm.md +++ b/deps/npm/docs/content/commands/npm.md @@ -14,7 +14,7 @@ Note: This command is unaware of workspaces. ### Version -10.2.4 +10.3.0 ### Description diff --git a/deps/npm/docs/content/commands/npx.md b/deps/npm/docs/content/commands/npx.md index 5ce300e724b103..e596baa5da4793 100644 --- a/deps/npm/docs/content/commands/npx.md +++ b/deps/npm/docs/content/commands/npx.md @@ -150,7 +150,8 @@ This resulted in some shifts in its functionality: always present in the executed process `PATH`. - The `--npm` option is removed. `npx` will always use the `npm` it ships with. -- The `--node-arg` and `-n` options are removed. +- The `--node-arg` and `-n` options have been removed. Use [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#node_optionsoptions) instead: e.g., + `NODE_OPTIONS="--trace-warnings --trace-exit" npx foo --random=true` - The `--always-spawn` option is redundant, and thus removed. - The `--shell` option is replaced with `--script-shell`, but maintained in the `npx` executable for backwards compatibility. diff --git a/deps/npm/docs/content/configuring-npm/npmrc.md b/deps/npm/docs/content/configuring-npm/npmrc.md index 8cd532abc1c2db..0aa99fc271013b 100644 --- a/deps/npm/docs/content/configuring-npm/npmrc.md +++ b/deps/npm/docs/content/configuring-npm/npmrc.md @@ -19,10 +19,10 @@ For a list of available configuration options, see The four relevant files are: -* per-project config file (/path/to/my/project/.npmrc) -* per-user config file (~/.npmrc) -* global config file ($PREFIX/etc/npmrc) -* npm builtin config file (/path/to/npm/npmrc) +* per-project config file (`/path/to/my/project/.npmrc`) +* per-user config file (`~/.npmrc`) +* global config file (`$PREFIX/etc/npmrc`) +* npm builtin config file (`/path/to/npm/npmrc`) All npm config files are an ini-formatted list of `key = value` parameters. Environment variables can be replaced using `${VARIABLE_NAME}`. For diff --git a/deps/npm/docs/content/configuring-npm/package-json.md b/deps/npm/docs/content/configuring-npm/package-json.md index 630ad453196a0a..2ef888fe1a4d64 100644 --- a/deps/npm/docs/content/configuring-npm/package-json.md +++ b/deps/npm/docs/content/configuring-npm/package-json.md @@ -291,25 +291,39 @@ Certain files are always included, regardless of settings: `README` & `LICENSE` can have any case and extension. -Conversely, some files are always ignored: +Some files are always ignored by default: +* `*.orig` +* `.*.swp` +* `.DS_Store` +* `._*` * `.git` -* `CVS` -* `.svn` * `.hg` * `.lock-wscript` +* `.npmrc` +* `.svn` * `.wafpickle-N` -* `.*.swp` -* `.DS_Store` -* `._*` +* `CVS` +* `config.gypi` +* `node_modules` * `npm-debug.log` +* `package-lock.json` (use + [`npm-shrinkwrap.json`](/configuring-npm/npm-shrinkwrap-json) + if you wish it to be published) +* `pnpm-lock.yaml` +* `yarn.lock` + +Most of these ignored files can be included specifically if included in +the `files` globs. Exceptions to this are: + +* `.git` * `.npmrc` * `node_modules` -* `config.gypi` -* `*.orig` -* `package-lock.json` (use - [`npm-shrinkwrap.json`](/configuring-npm/npm-shrinkwrap-json) if you wish - it to be published) +* `package-lock.json` +* `pnpm-lock.yaml` +* `yarn.lock` + +These can not be included. ### main diff --git a/deps/npm/docs/content/using-npm/config.md b/deps/npm/docs/content/using-npm/config.md index 80969ee23e5355..93c820ab3b45ad 100644 --- a/deps/npm/docs/content/using-npm/config.md +++ b/deps/npm/docs/content/using-npm/config.md @@ -855,6 +855,16 @@ Use of `legacy-peer-deps` is not recommended, as it will not enforce the +#### `libc` + +* Default: null +* Type: null or String + +Override libc of native modules to install. Acceptable values are same as +`libc` field of package.json + + + #### `link` * Default: false @@ -1373,7 +1383,7 @@ SBOM format to use when generating SBOMs. * Type: "library", "application", or "framework" The type of package described by the generated SBOM. For SPDX, this is the -value for the `primaryPackagePurpose` fieled. For CycloneDX, this is the +value for the `primaryPackagePurpose` field. For CycloneDX, this is the value for the `type` field. diff --git a/deps/npm/docs/lib/index.js b/deps/npm/docs/lib/index.js new file mode 100644 index 00000000000000..5d4ae7af3457bb --- /dev/null +++ b/deps/npm/docs/lib/index.js @@ -0,0 +1,189 @@ +const localeCompare = require('@isaacs/string-locale-compare')('en') +const { join, basename, resolve } = require('path') +const transformHTML = require('./transform-html.js') +const { version } = require('../../lib/npm.js') +const { aliases } = require('../../lib/utils/cmd-list') +const { shorthands, definitions } = require('@npmcli/config/lib/definitions') + +const DOC_EXT = '.md' + +const TAGS = { + CONFIG: '', + USAGE: '', + SHORTHANDS: '', +} + +const assertPlaceholder = (src, path, placeholder) => { + if (!src.includes(placeholder)) { + throw new Error( + `Cannot replace ${placeholder} in ${path} due to missing placeholder` + ) + } + return placeholder +} + +const getCommandByDoc = (docFile, docExt) => { + // Grab the command name from the *.md filename + // NOTE: We cannot use the name property command file because in the case of + // `npx` the file being used is `lib/commands/exec.js` + const name = basename(docFile, docExt).replace('npm-', '') + + if (name === 'npm') { + return { + name, + params: null, + usage: 'npm', + } + } + + // special case for `npx`: + // `npx` is not technically a command in and of itself, + // so it just needs the usage of npm exex + const srcName = name === 'npx' ? 'exec' : name + const { params, usage = [''], workspaces } = require(`../../lib/commands/${srcName}`) + const usagePrefix = name === 'npx' ? 'npx' : `npm ${name}` + if (params) { + for (const param of params) { + if (definitions[param].exclusive) { + for (const e of definitions[param].exclusive) { + if (!params.includes(e)) { + params.splice(params.indexOf(param) + 1, 0, e) + } + } + } + } + } + + return { + name, + workspaces, + params: name === 'npx' ? null : params, + usage: usage.map(u => `${usagePrefix} ${u}`.trim()).join('\n'), + } +} + +const replaceVersion = (src) => src.replace(/@VERSION@/g, version) + +const replaceUsage = (src, { path }) => { + const replacer = assertPlaceholder(src, path, TAGS.USAGE) + const { usage, name, workspaces } = getCommandByDoc(path, DOC_EXT) + + const synopsis = ['```bash', usage] + + const cmdAliases = Object.keys(aliases).reduce((p, c) => { + if (aliases[c] === name) { + p.push(c) + } + return p + }, []) + + if (cmdAliases.length === 1) { + synopsis.push('', `alias: ${cmdAliases[0]}`) + } else if (cmdAliases.length > 1) { + synopsis.push('', `aliases: ${cmdAliases.join(', ')}`) + } + + synopsis.push('```') + + if (!workspaces) { + synopsis.push('', 'Note: This command is unaware of workspaces.') + } + + return src.replace(replacer, synopsis.join('\n')) +} + +const replaceParams = (src, { path }) => { + const { params } = getCommandByDoc(path, DOC_EXT) + const replacer = params && assertPlaceholder(src, path, TAGS.CONFIG) + + if (!params) { + return src + } + + const paramsConfig = params.map((n) => definitions[n].describe()) + + return src.replace(replacer, paramsConfig.join('\n\n')) +} + +const replaceConfig = (src, { path }) => { + const replacer = assertPlaceholder(src, path, TAGS.CONFIG) + + // sort not-deprecated ones to the top + /* istanbul ignore next - typically already sorted in the definitions file, + * but this is here so that our help doc will stay consistent if we decide + * to move them around. */ + const sort = ([keya, { deprecated: depa }], [keyb, { deprecated: depb }]) => { + return depa && !depb ? 1 + : !depa && depb ? -1 + : localeCompare(keya, keyb) + } + + const allConfig = Object.entries(definitions).sort(sort) + .map(([_, def]) => def.describe()) + .join('\n\n') + + return src.replace(replacer, allConfig) +} + +const replaceShorthands = (src, { path }) => { + const replacer = assertPlaceholder(src, path, TAGS.SHORTHANDS) + + const sh = Object.entries(shorthands) + .sort(([shorta, expansiona], [shortb, expansionb]) => + // sort by what they're short FOR + localeCompare(expansiona.join(' '), expansionb.join(' ')) || localeCompare(shorta, shortb) + ) + .map(([short, expansion]) => { + // XXX: this is incorrect. we have multicharacter flags like `-iwr` that + // can only be set with a single dash + const dash = short.length === 1 ? '-' : '--' + return `* \`${dash}${short}\`: \`${expansion.join(' ')}\`` + }) + + return src.replace(replacer, sh.join('\n')) +} + +const replaceHelpLinks = (src) => { + // replaces markdown links with equivalent-ish npm help commands + return src.replace( + /\[`?([\w\s-]+)`?\]\(\/(?:commands|configuring-npm|using-npm)\/(?:[\w\s-]+)\)/g, + (_, p1) => { + const term = p1.replace(/npm\s/g, '').replace(/\s+/g, ' ').trim() + const help = `npm help ${term.includes(' ') ? `"${term}"` : term}` + return help + } + ) +} + +const transformMan = (src, { data, unified, remarkParse, remarkMan }) => unified() + .use(remarkParse) + .use(remarkMan) + .processSync(`# ${data.title}(${data.section}) - ${data.description}\n\n${src}`) + .toString() + +const manPath = (name, { data }) => join(`man${data.section}`, `${name}.${data.section}`) + +const transformMd = (src, { frontmatter }) => ['---', frontmatter, '---', '', src].join('\n') + +module.exports = { + DOC_EXT, + TAGS, + paths: { + content: resolve(__dirname, 'content'), + nav: resolve(__dirname, 'content', 'nav.yml'), + template: resolve(__dirname, 'template.html'), + man: resolve(__dirname, '..', '..', 'man'), + html: resolve(__dirname, '..', 'output'), + md: resolve(__dirname, '..', 'content'), + }, + usage: replaceUsage, + params: replaceParams, + config: replaceConfig, + shorthands: replaceShorthands, + version: replaceVersion, + helpLinks: replaceHelpLinks, + man: transformMan, + manPath: manPath, + md: transformMd, + html: transformHTML, +} diff --git a/deps/npm/docs/output/commands/npm-install-test.html b/deps/npm/docs/output/commands/npm-install-test.html index dd78090d2a5db3..b6b16aba6a5ca0 100644 --- a/deps/npm/docs/output/commands/npm-install-test.html +++ b/deps/npm/docs/output/commands/npm-install-test.html @@ -142,7 +142,7 @@

npm-install-test

Table of contents

-
+

Synopsis

@@ -350,6 +350,13 @@

os

Override OS of native modules to install. Acceptable values are same as os field of package.json, which comes from process.platform.

+

libc

+ +

Override libc of native modules to install. Acceptable values are same as +libc field of package.json

workspace

Override OS of native modules to install. Acceptable values are same as os field of package.json, which comes from process.platform.

+

libc

+ +

Override libc of native modules to install. Acceptable values are same as +libc field of package.json

workspace

README & LICENSE can have any case and extension.

-

Conversely, some files are always ignored:

+

Some files are always ignored by default:

+

Most of these ignored files can be included specifically if included in +the files globs. Exceptions to this are:

+ +

These can not be included.

main

The main field is a module ID that is the primary entry point to your program. That is, if your package is named foo, and a user installs it, diff --git a/deps/npm/docs/output/using-npm/config.html b/deps/npm/docs/output/using-npm/config.html index c80d3342fc9049..3015e5d066b473 100644 --- a/deps/npm/docs/output/using-npm/config.html +++ b/deps/npm/docs/output/using-npm/config.html @@ -142,7 +142,7 @@

config

Table of contents

-
+

Description

@@ -764,6 +764,13 @@

legacy-peer-deps

peerDependencies could be unpacked in a correct place.

Use of legacy-peer-deps is not recommended, as it will not enforce the peerDependencies contract that meta-dependencies may rely on.

+

libc

+ +

Override libc of native modules to install. Acceptable values are same as +libc field of package.json

The type of package described by the generated SBOM. For SPDX, this is the -value for the primaryPackagePurpose fieled. For CycloneDX, this is the +value for the primaryPackagePurpose field. For CycloneDX, this is the value for the type field.

scope