From 7326ff9939dc7aad3009614716425bcc3c72af4c Mon Sep 17 00:00:00 2001
From: Andy Edwards <jedwards@fastmail.com>
Date: Wed, 6 Dec 2017 23:47:08 -0600
Subject: [PATCH] feat: support task descriptions

---
 README.md                | 41 ++++++++++++++++++++++++++++++++++++++++
 package.json             |  1 +
 src/Promake.js           |  7 ++++++-
 src/Rule.js              |  8 ++++++++
 test/index.js            |  8 ++++----
 test/integration/promake |  8 ++++----
 yarn.lock                |  4 ++++
 7 files changed, 68 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 3e51349..1091feb 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ Promise-based JS make clone that can target anything, not just files
     + [`targets`](#targets)
     + [`prerequisites`](#prerequisites)
     + [`args`](#args)
+    + [`description([newDescription])`](#descriptionnewdescription)
     + [`then(onResolved, [onRejected])`](#thenonresolved-onrejected)
     + [`catch(onRejected)`](#catchonrejected)
   * [The `Resource` interface](#the-resource-interface)
@@ -36,6 +37,7 @@ Promise-based JS make clone that can target anything, not just files
   * [Pass args through to a shell command](#pass-args-through-to-a-shell-command)
   * [Make Tasks Prerequisites of Other Tasks](#make-tasks-prerequisites-of-other-tasks)
   * [Depend on Values of Environment Variables](#depend-on-values-of-environment-variables)
+  * [List available tasks](#list-available-tasks)
 - [Examples](#examples)
   * [Transpiling files with Babel](#transpiling-files-with-babel)
   * [Basic Webapp](#basic-webapp)
@@ -149,6 +151,15 @@ actual file that exists, similar to a [phony target in `make`](https://www.gnu.o
 
 Task names take precedence over file names when specifying what to build in CLI options.
 
+You can set the description for the task by calling [`.description()`](#descriptionnewdescription)
+on the returned `Rule`.  This description will be printed alongside the task
+if you call the CLI without any targets.  For example:
+```js
+task('clean', () =>
+  require('fs-extra').remove('build')
+).description('removes build output')
+```
+
 ##### `name`
 The name of the task
 
@@ -275,6 +286,12 @@ The normalized array of resources that must be made before running this rule.
 
 Any args for this rule (from the [CLI](#cliargv--processargv-options), usually)
 
+### `description([newDescription])`
+
+Gets or sets the description of this rule.  If you provide an argument,
+sets the description and returns this rule.  Otherwise, returns the
+description.
+
 ### `then(onResolved, [onRejected])`
 
 Starts running this rule if it isn't already, and calls `onResolved` when it finishes or `onReject` when it fails.
@@ -425,6 +442,30 @@ envRule(buildEnv, ['NODE_ENV', 'BABEL_ENV'])
 rule(lib, [...src, buildEnv], () => exec('babel src/ --out-dir lib'))
 ```
 
+## List available tasks
+
+Run the CLI without specifying any targets.  For instance if your
+build file is `promake`, run:
+
+```
+> ./promake
+promake CLI, version X.X.X
+https://github.com/jcoreio/promake/tree/vX.X.X
+
+Usage:
+  ./<script> [options...] [tasks...]
+
+Options:
+  -q, --quiet       suppress output
+  -v, --verbose     verbose output
+
+Tasks:
+  build             build server and client
+  build:client
+  build:server
+  clean             remove all build output
+```
+
 # Examples
 
 ## Transpiling files with Babel
diff --git a/package.json b/package.json
index 8e67bc9..e08687e 100644
--- a/package.json
+++ b/package.json
@@ -92,6 +92,7 @@
     "chalk": "^2.3.0",
     "es6-promisify": "^5.0.0",
     "flow-runtime": "^0.16.0",
+    "lodash.padend": "^4.6.1",
     "promisify-child-process": "^1.0.0"
   }
 }
diff --git a/src/Promake.js b/src/Promake.js
index 16f353e..36333ab 100644
--- a/src/Promake.js
+++ b/src/Promake.js
@@ -12,6 +12,7 @@ import type {ChildProcess} from 'child_process'
 import Verbosity from './Verbosity'
 import type {VerbosityLevel} from './Verbosity'
 import type {Readable} from 'stream'
+import padEnd from 'lodash.padend'
 
 type Resources = Array<string | Resource> | string | Resource
 
@@ -170,6 +171,8 @@ class Promake {
 
   printUsage = () => {
     const {version, homepage} = require('../package.json')
+    const tasks = [...this.taskResources.keys()].sort()
+    const taskColumnWidth = Math.max(16, ...tasks.map(name => name.length)) + 2
     process.stderr.write(`promake CLI, version ${version}
 ${homepage}/tree/v${version}
 
@@ -181,7 +184,9 @@ Options:
   -v, --verbose     verbose output
 
 Tasks:
-  ${[...this.taskResources.keys()].sort().join('\n  ') || '(No tasks defined)'}
+  ${tasks.map(task =>
+      `${padEnd(task, taskColumnWidth)}${this.task(task).description() || ''}`
+    ).join('\n  ') || '(No tasks defined)'}
 `)
   }
 
diff --git a/src/Rule.js b/src/Rule.js
index 7670223..87416eb 100644
--- a/src/Rule.js
+++ b/src/Rule.js
@@ -24,6 +24,8 @@ class Rule {
   lastFinishTime: ?number
   promise: ?Promise<any>
 
+  _description: ?string
+
   constructor(props: Props) {
     Object.assign(this, props)
   }
@@ -57,6 +59,12 @@ class Rule {
     return this.promise = this._make()
   }
 
+  description: (() => ?string) & ((newDescription: string) => Rule) = function (newDescription?: string): any {
+    if (!arguments.length) return this._description
+    this._description = newDescription
+    return this
+  }.bind(this)
+
   then = (onResolve: ?(() => any), onReject?: (error: Error) => any): Promise<any> => {
     let {promise} = this
     if (!promise) promise = this.make()
diff --git a/test/index.js b/test/index.js
index b4a8fda..8bcfe00 100644
--- a/test/index.js
+++ b/test/index.js
@@ -268,10 +268,10 @@ describe('Promake', () => {
       const {stderr} = await exec('babel-node promake -v', {cwd})
       expect(stderr).to.contain(`
 Tasks:
-  build
-  clean
-  client
-  server
+  build             build server and client
+  build:client      
+  build:server      
+  clean             remove all build output
 `)
     })
     it('throws an error when run with an invalid target', async () => {
diff --git a/test/integration/promake b/test/integration/promake
index 7b76534..d100880 100755
--- a/test/integration/promake
+++ b/test/integration/promake
@@ -34,11 +34,11 @@ rule(clientBuildFiles, clientPrerequisites, async () => {
 })
 
 task('build', [
-  task('server', [...serverBuildFiles, ...universalBuildFiles]),
-  task('client', clientBuildFiles),
-])
+  task('build:server', [...serverBuildFiles, ...universalBuildFiles]),
+  task('build:client', clientBuildFiles),
+]).description('build server and client')
 
-task('clean', () => fs.remove('build'))
+task('clean', () => fs.remove('build')).description('remove all build output')
 
 cli()
 
diff --git a/yarn.lock b/yarn.lock
index 8d778c0..096e8ef 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3427,6 +3427,10 @@ lodash.keys@^3.0.0:
     lodash.isarguments "^3.0.0"
     lodash.isarray "^3.0.0"
 
+lodash.padend@^4.6.1:
+  version "4.6.1"
+  resolved "https://registry.npmjs.org/lodash.padend/-/lodash.padend-4.6.1.tgz#53ccba047d06e158d311f45da625f4e49e6f166e"
+
 lodash.restparam@^3.0.0:
   version "3.6.1"
   resolved "https://registry.yarnpkg.com/lodash.restparam/-/lodash.restparam-3.6.1.tgz#936a4e309ef330a7645ed4145986c85ae5b20805"