fix: warn on invalid single-hyphen cli flags (#8076)

wraithgar · web-flow · commit 593c84921b0d · 2025-01-30T11:16:27.000-08:00
Single hyphen cli flags traditionally are single-character only, so they
can be combined. npm already supports combining single-hyphen flags
together, so it eventually needs stop supporting multi-character ones.

Also re-added -ws to undocumented shorthands, it was accidentally
removed from the main config and not re-added to the internal one.

Finally, warnings on a few env configs that npm tosses around were
suppressed for now.
diff --git a/tap-snapshots/test/lib/docs.js.test.cjs b/tap-snapshots/test/lib/docs.js.test.cjs
@@ -2547,6 +2547,7 @@ exports[`test/lib/docs.js TAP shorthands > docs 1`] = `
 * \`--help\`: \`--usage\`
 * \`-v\`: \`--version\`
 * \`-w\`: \`--workspace\`
+* \`--ws\`: \`--workspaces\`
 * \`-y\`: \`--yes\`
 `
 
diff --git a/workspaces/config/lib/definitions/index.js b/workspaces/config/lib/definitions/index.js
@@ -55,6 +55,7 @@ const shorthands = {
   readonly: ['--read-only'],
   reg: ['--registry'],
   iwr: ['--include-workspace-root'],
+  ws: ['--workspaces'],
   ...definitionProps.shorthands,
 }
 
diff --git a/workspaces/config/lib/index.js b/workspaces/config/lib/index.js
@@ -15,6 +15,14 @@ const {
   mkdir,
 } = require('node:fs/promises')
 
+// TODO these need to be either be ignored when parsing env, formalized as config, or not exported to the env in the first place. For now this list is just to suppress warnings till we can pay off this tech debt.
+const internalEnv = [
+  'global-prefix',
+  'local-prefix',
+  'npm-version',
+  'node-gyp',
+]
+
 const fileExists = (...p) => stat(resolve(...p))
   .then((st) => st.isFile())
   .catch(() => false)
@@ -349,6 +357,11 @@ class Config {
   }
 
   loadCLI () {
+    for (const s of Object.keys(this.shorthands)) {
+      if (s.length > 1 && this.argv.includes(`-${s}`)) {
+        log.warn(`-${s} is not a valid single-hyphen cli flag and will be removed in the future`)
+      }
+    }
     nopt.invalidHandler = (k, val, type) =>
       this.invalidHandler(k, val, type, 'command line options', 'cli')
     const conf = nopt(this.types, this.shorthands, this.argv)
@@ -580,6 +593,9 @@ class Config {
 
   #checkUnknown (where, key) {
     if (!this.definitions[key]) {
+      if (internalEnv.includes(key)) {
+        return
+      }
       if (!key.includes(':')) {
         log.warn(`Unknown ${where} config "${where === 'cli' ? '--' : ''}${key}". This will stop working in the next major version of npm.`)
         return
diff --git a/workspaces/config/test/index.js b/workspaces/config/test/index.js
@@ -1519,3 +1519,26 @@ t.test('catch project config prefix error', async t => {
     'error', 'config', `prefix cannot be changed from project config: ${path}`,
   ]], 'Expected error logged')
 })
+
+t.test('invalid single hyphen warnings', async t => {
+  const path = t.testdir()
+  const logs = []
+  const logHandler = (...args) => logs.push(args)
+  process.on('log', logHandler)
+  t.teardown(() => process.off('log', logHandler))
+  const config = new Config({
+    npmPath: `${path}/npm`,
+    env: {},
+    argv: [process.execPath, __filename, '-ws', '-iwr'],
+    cwd: path,
+    shorthands,
+    definitions,
+    nerfDarts,
+  })
+  await config.load()
+  const filtered = logs.filter(l => l[0] === 'warn')
+  t.match(filtered, [
+    ['warn', '-iwr is not a valid single-hyphen cli flag and will be removed in the future'],
+    ['warn', '-ws is not a valid single-hyphen cli flag and will be removed in the future'],
+  ], 'Warns about single hyphen configs')
+})

Original file line number	Diff line number	Diff line change
@@ -2547,6 +2547,7 @@ exports[`test/lib/docs.js TAP shorthands > docs 1`] = `
`2547`	`2547`	* \`--help\`: \`--usage\`
`2548`	`2548`	* \`-v\`: \`--version\`
`2549`	`2549`	* \`-w\`: \`--workspace\`
	`2550`	+* \`--ws\`: \`--workspaces\`
`2550`	`2551`	* \`-y\`: \`--yes\`
`2551`	`2552`	`
`2552`	`2553`
Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,7 @@ const shorthands = {`
`55`	`55`	`readonly: ['--read-only'],`
`56`	`56`	`reg: ['--registry'],`
`57`	`57`	`iwr: ['--include-workspace-root'],`
	`58`	`+ ws: ['--workspaces'],`
`58`	`59`	`...definitionProps.shorthands,`
`59`	`60`	`}`
`60`	`61`