Descriptions for npm Scripts

[bayleedev]

It would be handy to add descriptions to NPM scripts. Having a list of commands using npm run is helpful, but only allows me to find the command I'm looking for specifically. Knowing what all exists could help me prune the list and make modifications to one instead of creating a new one.

Example syntax:

"scripts": {
  "code-coverage": {
    "cmd": "karma start --browsers Chrome --single-run",
    "description": "Runs the tests without disabling code coverage utility."
  }
}

Maybe there is a better way to accomplish what I'm looking for? Either way, I'd be happy to pr if this is something the community wants.

Related lines of code

[scottaddie]

+1
This would be especially useful on larger development teams.

[mike-engel]

+1. I'll work on getting a PR in for this.

[mike-engel]

@blainesch @scottaddie How do you both feel about this? There's a lot more added whitespace to make it more readable, so let me know if it's too much.

Markup:

"scripts": {
  "dumpconf": "env | grep npm | sort | uniq",
  "prepublish": "bash scripts/installable.sh && node bin/npm-cli.js prune --prefix=. --no-global && rimraf test/*/*/node_modules && make -j4 doc",
  "preversion": "bash scripts/update-authors.sh && git add AUTHORS && git commit -m \"update AUTHORS\" || true",
  "tap": "tap --timeout 240",
  "test": {
    "script": "standard && npm run test-tap",
    "description": "Our required test suite to ensure great success."
  },
  "test-all": {
    "script": "standard && npm run test-legacy && npm run test-tap",
    "description": "Run all of the tests against your changes and the rest of the npm cli codebase. This should be really long so it wraps"
  },
  "test-legacy": "node ./test/run.js",
  "test-tap": "npm run tap -- \"test/tap/*.js\""
}

Before:

Lifecycle scripts included in npm:
  prepublish
    bash scripts/installable.sh && node bin/npm-cli.js prune --prefix=. --no-global && rimraf test/*/*/node_modules && make -j4 doc
  preversion
    bash scripts/update-authors.sh && git add AUTHORS && git commit -m "update AUTHORS" || true

available via `npm run-script`:
  dumpconf
    env | grep npm | sort | uniq
  tap
    tap --timeout 240
  test-legacy
    node ./test/run.js
  test-tap
    npm run tap -- "test/tap/*.js"

After:

Lifecycle scripts included in npm:
  prepublish
    `bash scripts/installable.sh && node bin/npm-cli.js prune --prefix=. --no-global && rimraf
    test/*/*/node_modules && make -j4 doc`

  preversion
    `bash scripts/update-authors.sh && git add AUTHORS && git commit -m "update AUTHORS" || true`

  test
    `standard && npm run test-tap`

    Our required test suite to ensure great success.


available via `npm run-script`:
  dumpconf
    `env | grep npm | sort | uniq`

  tap
    `tap --timeout 240`

  test-all
    `standard && npm run test-legacy && npm run test-tap`

    Run all of the tests against your changes and the rest of the npm cli
    codebase. This should be really long so it wraps

  test-legacy
    `node ./test/run.js`

  test-tap
    `npm run tap -- "test/tap/*.js"`

[bayleedev]

I like it!

[othiym23]

Is the value of adding a description worth the complexity of adding yet another case where the value of a key in a package.json entry can be either a string or an object? I'm not convinced that it is, so somebody should convince me if they want to see a PR based on this land. I prefer the "before" output to npm run-script above – being able to see the description is enough for me, especially with the separation of lifecycle and user scripts.

[scottaddie]

I would definitely use this. This description would prove beneficial to IDEs such as Visual Studio 2015. It has a feature called Task Runner Explorer, which can be extended to discover and execute npm scripts. Currently, no description is provided in the UI next to each script name. By including this new property, that becomes a possibility. In fact, I would personally submit a pull request to make that integration happen in Visual Studio. In cases where there are a plethora of scripts defined, the value increases significantly.

[mike-engel]

@othiym23 Just to clarify, it sounds like you're generally in favor of the idea of having a way to describe what a script does. It sounds like maybe you're not so keen on having to account for a string and an object. On that point, do you feel it would be better to force them all to be objects? Would you rather see the description somewhere else? As far as the code changes go, it's not a lot. Most of the work is here, with a line change or two in two other packages used by this one.

For your second point on preferring the current output, is that because it's short, or because you don't want to see the description there? Whitespace can be removed if that's the issue, but I feel like if a description will be included in the package.json, it's important to have it in the output as well. It could be behind the -l option, similar to npm help -l.

[othiym23]

@mike-engel I'm not a big fan of the descriptions. I think they add clutter and don't really have much additional value on top of seeing what the script itself is doing (i.e. the current behavior of npm run-script is the behavior I like). I'm +0 on the whitespace – my issue is with the descriptions themselves. What's a use case where you see them having significant value to users? Any package.json where there are enough package scripts that they need careful descriptions is probably going to generate a fairly hefty amount of output for the script descriptions, which seems like it would negate the value of having the descriptions in the first place.

The rest of my concerns are about controlling the amount of clutter around dealing with package.json (it was a banner day when we finally simplified the license field to only be a string containing an SPDX expression, and I'd like to see more of that kind of thing, rather than adding special-case logic. Switching to forcing the use of objects for the scripts field is much harder, because it's a backwards-compatible breaking feature and would require a lengthy deprecation cycle (which we are now starting to use for things, and which are cumbersome, given the care with which npm needs to handle breaking compatibility).

[mike-engel]

@othiym23 Ah, I see. I think it would be useful to have descriptions for a) onboarding new devs to the project (especially with all this commotion of replacing gulp with npm scripts), b) explaining to users without a technical background what a script does, and c) just to have some sort of documentation on the intent and purpose of a script.

There are a couple of people in this thread who feel it would be useful, then there's this thread on twitter with some asking for the ability to document scripts. I understand where you're coming from though, as it is added complexity to a project. Another solution, while not as good I feel but would be 100% backwards compatible, would be a new "scriptsDescriptions" key, separate from the "scripts" key.

How would you feel about asking the community about this? Maybe in NPM weekly or a quick poll on twitter?

[mike-engel]

I'm wondering if, as npm's new documentation human, @ashleygwilliams has any thoughts on this. I feel like it's somewhat related to documentation, but maybe not.

[othiym23]

After thinking about this for a bit, I don't think the complexity is justified by the usefulness of this idea, so I'm going to close this feature request out. If your package scripts are complicated enough that they need descriptions, they probably ought to be broken down into smaller pieces, or broken out into separate tools. Thanks for walking through this with me, and thanks for your time!