Self-documented scripts in package.json

[ncuillery]

What's the feature?

NPM could handle either an object or a string for each script in package.json. It would give you the ability to document the scripts, like this:

"scripts": {
  "pretest": {
    "description": "Prepare test credentials",
    "value": "cd whatever && cp ./auth/test.json ."
  },
  "test": "jest"
}

Then the description could be displayed when running the script:

$ npm test

> my-project@0.0.1 pretest /Users/ncuillery/xxxx/xxxxx
> Prepare test credentials
> cd whatever && cp ./auth/test.json .

> my-project@0.0.1 test /Users/ncuillery/xxxx/xxxxx
> jest

...

Here is a kind of a specification for the script object:

• Each entry under the scripts key must be a string or an object value.
• If the entry value is an object:
  • It must have a key value (better name suggestions are welcome) of type string that contains the runnable command
  • It could have a key description of type string or array of string (multiline comment) that contains a human-readable description of the script.

What problem is the feature intended to solve?

The JSON format doesn't allow comments. The need of comments is often the result of bad code or poor design, but when using the NPM scripts as the build tool, it could easily lead to a dozen of mono-line obscur shell commands that nothing can make easier to read.

I found this interesting email from @isaacs on the mailing list:
https://groups.google.com/forum/#!msg/nodejs/NmL7jdeuw0M/yTqI05DRQrIJ

It makes clear that:

• Any other format that has comments (like YAML or JSON5) will never be supported
• The "//" will never be used by NPM so users can use it to add comments in package.json

The "//" workaround is no longer acceptable because NPM5 automatically removes duplicate keys so:

"scripts": {
  "//": "This is the pretest command",
  "pretest": "cd whatever && cp ./auth/test.json .",
  "//": "This is the test command",
  "test": "jest"
}

becomes

"scripts": {
  "//": "This is the pretest command",
  "pretest": "cd whatever && cp ./auth/test.json .",
  "test": "jest"
}

after any NPM command.

That's why I'm coming with this handy, pure JSON, way to document user scripts.

Is the absence of this feature blocking you or your team? If so, how?

I can't honestly say it's "blocking". Some workarounds exist like externalizing the commands in shell scripts (it hurts the DRY principle though).

Let's say it's nice to have.

Is this feature similar to an existing feature in another tool?

As far as I know, other platforms generally support comments in their project descriptor:

• podspec: https://guides.cocoapods.org/syntax/podspec.html
• Gemfile: http://bundler.io/v1.11/man/gemfile.5.html
• Gradle: https://docs.gradle.org/current/dsl/
• ...

Is this a feature you're prepared to implement, with support from the npm CLI team?

Yes, definitely.

[KenanY]

ref. #14161, #17314