Skip to content

Commit

Permalink
fix(usage): better audit/boolean flag usage output
Browse files Browse the repository at this point in the history
This adds the `audit` config item to the usage output of `npm ci`, and
also tweaks how usage flags are shown for boolean options that do not
default to false.  Their usage is shown as the `--no-x` form of the flag
to better communicate that the flag is needed to turn that normally true
option OFF.

The description of `audit` was also updated to reflect that it runs on
many different npm commands, not just install.  Because this flag is
included in the usage of those commands it's best to let the assocation
happen there instead of trying to be comprehensive in the description
itself.

A small fix to make `install-ci-test` not try to redefine its own
usage, but to inherit from `ci` was also included.

PR-URL: #3497
Credit: @wraithgar
Close: #3497
Reviewed-by: @nlf
  • Loading branch information
wraithgar committed Jul 12, 2021
1 parent c3bd10e commit 89483e8
Show file tree
Hide file tree
Showing 18 changed files with 135 additions and 87 deletions.
10 changes: 10 additions & 0 deletions docs/content/commands/npm-ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,16 @@ cache:

<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
<!-- automatically generated, do not edit manually -->
#### `audit`

* Default: true
* Type: Boolean

When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for [`npm audit`](/commands/npm-audit) for details on what is
submitted.

#### `ignore-scripts`

* Default: false
Expand Down
7 changes: 4 additions & 3 deletions docs/content/commands/npm-dedupe.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,9 +164,10 @@ will *not* run any pre- or post-scripts.
* Default: true
* Type: Boolean
When "true" submit audit reports alongside `npm install` runs to the default
registry and all registries configured for scopes. See the documentation for
[`npm audit`](/commands/npm-audit) for details on what is submitted.
When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for [`npm audit`](/commands/npm-audit) for details on what is
submitted.
#### `bin-links`
Expand Down
7 changes: 4 additions & 3 deletions docs/content/commands/npm-find-dupes.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,9 +107,10 @@ will *not* run any pre- or post-scripts.
* Default: true
* Type: Boolean

When "true" submit audit reports alongside `npm install` runs to the default
registry and all registries configured for scopes. See the documentation for
[`npm audit`](/commands/npm-audit) for details on what is submitted.
When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for [`npm audit`](/commands/npm-audit) for details on what is
submitted.

#### `bin-links`

Expand Down
10 changes: 10 additions & 0 deletions docs/content/commands/npm-install-ci-test.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,16 @@ This command runs `npm ci` followed immediately by `npm test`.

<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
<!-- automatically generated, do not edit manually -->
#### `audit`

* Default: true
* Type: Boolean

When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for [`npm audit`](/commands/npm-audit) for details on what is
submitted.

#### `ignore-scripts`

* Default: false
Expand Down
7 changes: 4 additions & 3 deletions docs/content/commands/npm-install-test.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,9 +149,10 @@ will *not* run any pre- or post-scripts.
* Default: true
* Type: Boolean

When "true" submit audit reports alongside `npm install` runs to the default
registry and all registries configured for scopes. See the documentation for
[`npm audit`](/commands/npm-audit) for details on what is submitted.
When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for [`npm audit`](/commands/npm-audit) for details on what is
submitted.

#### `bin-links`

Expand Down
7 changes: 4 additions & 3 deletions docs/content/commands/npm-install.md
Original file line number Diff line number Diff line change
Expand Up @@ -533,9 +533,10 @@ will *not* run any pre- or post-scripts.
* Default: true
* Type: Boolean
When "true" submit audit reports alongside `npm install` runs to the default
registry and all registries configured for scopes. See the documentation for
[`npm audit`](/commands/npm-audit) for details on what is submitted.
When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for [`npm audit`](/commands/npm-audit) for details on what is
submitted.
#### `bin-links`
Expand Down
7 changes: 4 additions & 3 deletions docs/content/commands/npm-link.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,9 +233,10 @@ will *not* run any pre- or post-scripts.
* Default: true
* Type: Boolean

When "true" submit audit reports alongside `npm install` runs to the default
registry and all registries configured for scopes. See the documentation for
[`npm audit`](/commands/npm-audit) for details on what is submitted.
When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for [`npm audit`](/commands/npm-audit) for details on what is
submitted.

#### `bin-links`

Expand Down
7 changes: 4 additions & 3 deletions docs/content/commands/npm-update.md
Original file line number Diff line number Diff line change
Expand Up @@ -255,9 +255,10 @@ will *not* run any pre- or post-scripts.
* Default: true
* Type: Boolean

When "true" submit audit reports alongside `npm install` runs to the default
registry and all registries configured for scopes. See the documentation for
[`npm audit`](/commands/npm-audit) for details on what is submitted.
When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for [`npm audit`](/commands/npm-audit) for details on what is
submitted.

#### `bin-links`

Expand Down
7 changes: 4 additions & 3 deletions docs/content/using-npm/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,9 +170,10 @@ to the same value as the current version.
* Default: true
* Type: Boolean

When "true" submit audit reports alongside `npm install` runs to the default
registry and all registries configured for scopes. See the documentation for
[`npm audit`](/commands/npm-audit) for details on what is submitted.
When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for [`npm audit`](/commands/npm-audit) for details on what is
submitted.

#### `audit-level`

Expand Down
1 change: 1 addition & 0 deletions lib/ci.js
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ class CI extends ArboristWorkspaceCmd {
/* istanbul ignore next - see test/lib/load-all-commands.js */
static get params () {
return [
'audit',
'ignore-scripts',
'script-shell',
]
Expand Down
8 changes: 0 additions & 8 deletions lib/install-ci-test.js
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,6 @@ class InstallCITest extends CI {
return 'install-ci-test'
}

/* istanbul ignore next - see test/lib/load-all-commands.js */
static get params () {
return [
'ignore-scripts',
'script-shell',
]
}

exec (args, cb) {
this.npm.commands.ci(args, (er) => {
if (er)
Expand Down
32 changes: 25 additions & 7 deletions lib/utils/config/definition.js
Original file line number Diff line number Diff line change
Expand Up @@ -91,13 +91,27 @@ ${noEnvExport}`)
}

const describeUsage = (def) => {
let key = `--${def.key}`
if (def.short && typeof def.short === 'string')
key = `-${def.short}|${key}`
let key = ''

// Single type
if (!Array.isArray(def.type))
return `${key}${def.type === Boolean ? '' : ' ' + def.hint}`
if (!Array.isArray(def.type)) {
if (def.short)
key = `-${def.short}|`

if (def.type === Boolean && def.default !== false)
key = `${key}--no-${def.key}`
else
key = `${key}--${def.key}`

if (def.type !== Boolean)
key = `${key} ${def.hint}`

return key
}

key = `--${def.key}`
if (def.short)
key = `-${def.short}|--${def.key}`

// Multiple types
let types = def.type
Expand All @@ -120,8 +134,12 @@ const describeUsage = (def) => {
description = def.hint
}

if (bool)
key = `${key}|${key}`
if (bool) {
// Currently none of our multi-type configs with boolean values default to
// false so all their hints should show `--no-`, if we ever add ones that
// default to false we can branch the logic here
key = `--no-${def.key}|${key}`
}

const usage = `${key} ${description}`
if (multiple)
Expand Down
7 changes: 4 additions & 3 deletions lib/utils/config/definitions.js
Original file line number Diff line number Diff line change
Expand Up @@ -203,10 +203,10 @@ define('audit', {
default: true,
type: Boolean,
description: `
When "true" submit audit reports alongside \`npm install\` runs to the
When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for [\`npm audit\`](/commands/npm-audit) for details on
what is submitted.
documentation for [\`npm audit\`](/commands/npm-audit) for details on what
is submitted.
`,
flatten,
})
Expand Down Expand Up @@ -440,6 +440,7 @@ define('cidr', {

define('color', {
default: !process.env.NO_COLOR || process.env.NO_COLOR === '0',
usage: '--color|--no-color|--color always',
defaultDescription: `
true unless the NO_COLOR environ is set to something other than '0'
`,
Expand Down
42 changes: 21 additions & 21 deletions tap-snapshots/test/lib/load-all-commands.js.test.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Usage:
npm bugs [<pkgname>]
Options:
[--browser|--browser <browser>] [--registry <registry>]
[--no-browser|--browser <browser>] [--registry <registry>]
alias: issues
Expand Down Expand Up @@ -120,7 +120,7 @@ Usage:
npm ci
Options:
[--ignore-scripts] [--script-shell <script-shell>]
[--no-audit] [--ignore-scripts] [--script-shell <script-shell>]
aliases: clean-install, ic, install-clean, isntall-clean
Expand Down Expand Up @@ -167,9 +167,9 @@ Usage:
npm dedupe
Options:
[--global-style] [--legacy-bundling] [--strict-peer-deps] [--package-lock]
[--global-style] [--legacy-bundling] [--strict-peer-deps] [--no-package-lock]
[--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts]
[--audit] [--bin-links] [--fund] [--dry-run]
[--no-audit] [--no-bin-links] [--no-fund] [--dry-run]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[-ws|--workspaces]
Expand Down Expand Up @@ -239,7 +239,7 @@ Usage:
npm docs [<pkgname> [<pkgname> ...]]
Options:
[--browser|--browser <browser>] [--registry <registry>]
[--no-browser|--browser <browser>] [--registry <registry>]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[-ws|--workspaces]
Expand Down Expand Up @@ -337,9 +337,9 @@ Usage:
npm find-dupes
Options:
[--global-style] [--legacy-bundling] [--strict-peer-deps] [--package-lock]
[--global-style] [--legacy-bundling] [--strict-peer-deps] [--no-package-lock]
[--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts]
[--audit] [--bin-links] [--fund]
[--no-audit] [--no-bin-links] [--no-fund]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[-ws|--workspaces]
Expand All @@ -355,7 +355,7 @@ Usage:
npm fund [[<@scope>/]<pkg>]
Options:
[--json] [--browser|--browser <browser>] [--unicode]
[--json] [--no-browser|--browser <browser>] [--unicode]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[--which <fundingSourceNumber>]
Expand Down Expand Up @@ -446,9 +446,9 @@ npm install <github username>/<github project>
Options:
[-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer]
[-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling]
[--strict-peer-deps] [--package-lock]
[--strict-peer-deps] [--no-package-lock]
[--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts]
[--audit] [--bin-links] [--fund] [--dry-run]
[--no-audit] [--no-bin-links] [--no-fund] [--dry-run]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[-ws|--workspaces]
Expand All @@ -466,7 +466,7 @@ Usage:
npm install-ci-test
Options:
[--ignore-scripts] [--script-shell <script-shell>]
[--no-audit] [--ignore-scripts] [--script-shell <script-shell>]
alias: cit
Expand All @@ -493,9 +493,9 @@ npm install-test <github username>/<github project>
Options:
[-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer]
[-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling]
[--strict-peer-deps] [--package-lock]
[--strict-peer-deps] [--no-package-lock]
[--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts]
[--audit] [--bin-links] [--fund] [--dry-run]
[--no-audit] [--no-bin-links] [--no-fund] [--dry-run]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[-ws|--workspaces]
Expand All @@ -516,9 +516,9 @@ npm link [<@scope>/]<pkg>[@<version>]
Options:
[-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer]
[-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling]
[--strict-peer-deps] [--package-lock]
[--strict-peer-deps] [--no-package-lock]
[--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts]
[--audit] [--bin-links] [--fund] [--dry-run]
[--no-audit] [--no-bin-links] [--no-fund] [--dry-run]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[-ws|--workspaces]
Expand Down Expand Up @@ -768,7 +768,7 @@ Usage:
npm rebuild [[<@scope>/]<name>[@<version>] ...]
Options:
[-g|--global] [--bin-links] [--ignore-scripts]
[-g|--global] [--no-bin-links] [--ignore-scripts]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[-ws|--workspaces]
Expand All @@ -786,7 +786,7 @@ Usage:
npm repo [<pkgname> [<pkgname> ...]]
Options:
[--browser|--browser <browser>]
[--no-browser|--browser <browser>]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[-ws|--workspaces]
Expand Down Expand Up @@ -848,7 +848,7 @@ Usage:
npm search [search terms ...]
Options:
[-l|--long] [--json] [--color|--color <always>] [-p|--parseable]
[-l|--long] [--json] [--color|--no-color|--color always] [-p|--parseable]
[--no-description] [--searchopts <searchopts>] [--searchexclude <searchexclude>]
[--registry <registry>] [--prefer-online] [--prefer-offline] [--offline]
Expand Down Expand Up @@ -1059,8 +1059,8 @@ npm update [<pkg>...]
Options:
[-g|--global] [--global-style] [--legacy-bundling] [--strict-peer-deps]
[--package-lock] [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
[--ignore-scripts] [--audit] [--bin-links] [--fund] [--dry-run]
[--no-package-lock] [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
[--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[-ws|--workspaces]
Expand All @@ -1078,7 +1078,7 @@ Usage:
npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]
Options:
[--allow-same-version] [--commit-hooks] [--git-tag-version] [--json]
[--allow-same-version] [--no-commit-hooks] [--no-git-tag-version] [--json]
[--preid prerelease-id] [--sign-git-tag]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[-ws|--workspaces]
Expand Down
7 changes: 4 additions & 3 deletions tap-snapshots/test/lib/utils/config/definitions.js.test.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -218,9 +218,10 @@ exports[`test/lib/utils/config/definitions.js TAP > config description for audit
* Default: true
* Type: Boolean
When "true" submit audit reports alongside \`npm install\` runs to the default
registry and all registries configured for scopes. See the documentation for
[\`npm audit\`](/commands/npm-audit) for details on what is submitted.
When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for [\`npm audit\`](/commands/npm-audit) for details on what is
submitted.
`

exports[`test/lib/utils/config/definitions.js TAP > config description for audit-level 1`] = `
Expand Down
Loading

0 comments on commit 89483e8

Please sign in to comment.