deps: upgrade npm to 10.3.0

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:

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:

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
 ```

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

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.
 
 

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,

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
 

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.

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

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
 

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.
 
 

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: '<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->',
+ USAGE: '<!-- AUTOGENERATED USAGE DESCRIPTIONS -->',
+ SHORTHANDS: '<!-- AUTOGENERATED CONFIG 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,
+}