deps: upgrade npm to 10.3.0

PR-URL: #51431
Reviewed-By: Luke Karrys <luke@lukekarrys.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>

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,
+}