Feature/project readme generator (#144)

* first preparation for multiple templates and the new command

* first draft

* update readme

* check if plugin fn was created from fastify-plugin

* omit error prefix, print executed command because of levensthein, rename commands

* rename commands, update readme

* check min fastify version

* [skip ci] improve readme

Author: StarpTech

README.md

@@ -24,10 +24,11 @@ Will print an help:
 ```
 Fastify command line interface, available commands are:
 
-  * start       start a server
-  * generate    generate a new project
-  * version     the current fastify-cli version
-  * help        help about commands
+  * start         start a server
+  * generate      generate a new project
+  * readme        generate a README.md for the plugin
+  * version       the current fastify-cli version
+  * help          help about commands
 
 Launch 'fastify help [command]' to know more about the commands.
 
@@ -179,6 +180,23 @@ You will find three different folders:
 Finally there will be an `app.js` file, which is your entry point.
 It is a standard Fastify plugin and you will not need to add the `listen` method to run the server, just run it with one of the scripts above.
 
+### readme
+
+`fastify-cli` can also help with generating a concise and informative readme for your plugin. If no `package.json` was provided a new one is generated automatically.
+To use it:
+
+1. `cd yourplugin`
+2. `fastify readme <path-to-your-plugin-file>`
+
+Finally there will be a new `README.md` file, which provides internal informations about your plugin e.g:
+
+* Install instructions
+* Example usage
+* Plugin dependencies
+* Exposed decorators
+* Encapsulation semantic
+* Compatible Fastify version
+
 ### linting
 
 `fastify-cli` is unopinionated on the choice of linter. We recommend you to add a linter, like so:

cli.js

@@ -10,9 +10,11 @@ const help = require('help-me')({
 })
 const start = require('./start')
 const generate = require('./generate')
+const generateReadme = require('./generate-readme')
 
 commist.register('start', start.cli)
 commist.register('generate', generate.cli)
+commist.register('readme', generateReadme.cli)
 commist.register('help', help.toStdout)
 commist.register('version', function () {
   console.log(require('./package.json').version)

generate-readme.js

@@ -0,0 +1,139 @@
+'use strict'
+
+const { readFileSync, existsSync } = require('fs')
+const path = require('path')
+const generify = require('generify')
+const argv = require('yargs-parser')
+const { execSync } = require('child_process')
+const log = require('./log')
+
+function toMarkdownList (a) {
+  return a.map(d => `- ${d}`).join('\n')
+}
+function generate (dir, { pluginMeta, encapsulated, pluginFileName }, cb) {
+  process.chdir(dir)
+
+  if (!existsSync(path.join(dir, 'package.json'))) {
+    execSync('npm init -y')
+    log('info', `generated package.json in ${dir}`)
+  }
+
+  log('info', `reading package.json in ${dir}`)
+  let pkg = readFileSync('package.json')
+  try {
+    pkg = JSON.parse(pkg)
+  } catch (err) {
+    return cb(err)
+  }
+
+  pluginMeta.decorators = pluginMeta.decorators ? pluginMeta.decorators : { fastify: [], reply: [] }
+  pluginMeta.dependencies = pluginMeta.dependencies ? pluginMeta.dependencies : []
+
+  const peerDepFastify = pkg.peerDependencies ? pkg.peerDependencies.fastify : ''
+  const depFastify = pkg.dependencies ? pkg.dependencies.fastify : ''
+  const minFastify = pluginMeta.fastify || peerDepFastify || depFastify
+
+  let accessibilityTemplate = ''
+  if (!encapsulated) {
+    accessibilityTemplate = `- [X] Accessible in the same context where you require them\n- [ ] Accessible only in a child context\n`
+  } else {
+    accessibilityTemplate = `- [ ] Accessible in the same context where you require them\n- [X] Accessible only in a child context\n`
+  }
+
+  let fastifyDecorators = toMarkdownList(pluginMeta.decorators.fastify)
+  let replyDecorators = toMarkdownList(pluginMeta.decorators.reply)
+  let pluginDeps = toMarkdownList(pluginMeta.dependencies)
+
+  generify(
+    path.join(__dirname, 'templates', 'readme'),
+    dir,
+    {
+      accessibilityTemplate,
+      fastifyDecorators,
+      replyDecorators,
+      pluginDeps,
+      packageName: pkg.name,
+      pluginFileName,
+      minFastify
+    },
+    function (file) {
+      log('debug', `generated ${file}`)
+    },
+    function (err) {
+      if (err) {
+        return cb(err)
+      }
+
+      log('info', `README for plugin ${pkg.name} generated successfully`)
+    }
+  )
+}
+
+function stop (error) {
+  if (error) {
+    console.log(error)
+    process.exit(1)
+  }
+  process.exit()
+}
+
+function showHelp () {
+  console.log(
+    readFileSync(path.join(__dirname, 'help', 'readme.txt'), 'utf8')
+  )
+  return stop()
+}
+
+function cli (args) {
+  const opts = argv(args)
+
+  const dir = process.cwd()
+
+  if (opts._.length !== 1) {
+    log('error', 'Missing the required file parameter\n')
+    return showHelp()
+  }
+
+  if (existsSync(path.join(dir, 'README.md'))) {
+    log('error', 'a README.md file already exists in target directory')
+    process.exit(1)
+  }
+
+  const pluginPath = path.join(dir, path.basename(opts._[0], '.js'))
+
+  let plugin
+  try {
+    plugin = require(pluginPath)
+  } catch (err) {
+    log('error', 'plugin could not be loaded', err)
+    process.exit(1)
+  }
+
+  const pluginMeta = plugin[Symbol.for('plugin-meta')]
+
+  if (!pluginMeta) {
+    log('error', 'no plugin metadata could be found. Are you sure that you use https://github.com/fastify/fastify-plugin ?')
+    process.exit(1)
+  }
+
+  let encapsulated = !plugin[Symbol.for('skip-override')]
+  const pluginFileName = path.basename(opts._[0])
+
+  generate(dir, { pluginMeta, encapsulated, pluginFileName }, function (
+    err
+  ) {
+    if (err) {
+      log('error', err.message)
+      process.exit(1)
+    }
+  })
+}
+
+module.exports = {
+  generate,
+  cli
+}
+
+if (require.main === module) {
+  cli(process.argv.slice(2))
+}

generate.js

@@ -5,20 +5,16 @@ const {
   writeFile,
   existsSync
 } = require('fs')
-const chalk = require('chalk')
 const path = require('path')
+const chalk = require('chalk')
 const generify = require('generify')
 const argv = require('yargs-parser')
 const cliPkg = require('./package')
 const { execSync } = require('child_process')
+const log = require('./log')
 
-function generate (dir, log, cb) {
-  if (!cb) {
-    cb = log
-    log = () => {}
-  }
-
-  generify(path.join(__dirname, 'app_template'), dir, {}, function (file) {
+function generate (dir, cb) {
+  generify(path.join(__dirname, 'templates', 'app'), dir, {}, function (file) {
     log('debug', `generated ${file}`)
   }, function (err) {
     if (err) {
@@ -78,18 +74,6 @@ function generate (dir, log, cb) {
   })
 }
 
-const levels = {
-  'debug': 0,
-  'info': 1,
-  'error': 2
-}
-
-const colors = [
-  (l) => l,
-  chalk.green,
-  chalk.red
-]
-
 function cli (args) {
   const opts = argv(args)
 
@@ -105,20 +89,12 @@ function cli (args) {
     process.exit(1)
   }
 
-  generate(dir, log, function (err) {
+  generate(dir, function (err) {
     if (err) {
       log('error', err.message)
       process.exit(1)
     }
   })
-
-  function log (severity, line) {
-    const level = levels[severity] || 0
-    if (level === 1) {
-      line = '--> ' + line
-    }
-    console.log(colors[level](line))
-  }
 }
 
 module.exports = {

help/help.txt

@@ -1,8 +1,9 @@
 Fastify command line interface available commands are:
 
-  * start       start a server
-  * generate    generate a new project
-  * version     the current fastify-cli version
-  * help        help about commands
+  * start         start a server
+  * generate      generate a new project
+  * readme        generate a README.md for the plugin
+  * version       the current fastify-cli version
+  * help          help about commands
 
 Launch 'fastify help [command]' to learn more about each command.

help/readme.txt

@@ -0,0 +1,5 @@
+Usage: fastify readme <path-to-plugin-file>
+
+Sets up project with `npm init -y` and
+generates a sample README.md file
+from the <path-to-plugin-file>.

log.js

@@ -0,0 +1,21 @@
+'use strict'
+
+const chalk = require('chalk')
+
+const levels = {
+  debug: 0,
+  info: 1,
+  error: 2
+}
+
+const colors = [l => l, chalk.green, chalk.red]
+
+function log (severity, line) {
+  const level = levels[severity] || 0
+  if (level === 1) {
+    line = '--> ' + line
+  }
+  console.log(colors[level](line))
+}
+
+module.exports = log

package.json

@@ -8,8 +8,8 @@
   },
   "scripts": {
     "lint": "standard",
-    "test": "tap test/*.test.js app_template/test/*/*.test.js",
-    "pretest": "standard"
+    "unit": "tap test/*.test.js templates/app/test/*/*.test.js",
+    "test": "npm run lint && npm run unit"
   },
   "keywords": [
     "fastify",

start.js

@@ -41,7 +41,7 @@ function start (args, cb) {
   }
 
   if (opts._.length !== 1) {
-    console.error('Error: Missing the required file parameter\n')
+    console.error('Missing the required file parameter\n')
     return showHelp()
   }
 

app_template/__gitignore templates/app/__gitignore

@@ -0,0 +1,52 @@
+# __packageName__
+
+Short description of the purpose of your plugin.
+
+## Install
+
+```
+npm install __packageName__ --save
+yarn add __packageName__
+```
+
+## Example
+
+```js
+const fastify = require('fastify')()
+fastify.register(require('__packageName__'))
+fastify.listen(3000)
+```
+
+You can also start any Fastify plugin with the [Fastify-cli](https://github.com/fastify/fastify-cli):
+
+```
+fastify start __pluginFileName__
+```
+
+## Plugin
+
+### Accessibility
+<!-- Is your plugin fully encapsulated? If you use fastify-plugin or the hidden property 'skip-override' it's not -->
+
+__accessibilityTemplate__
+
+### Decorators
+<!-- A list of all exposed decorators in your plugin -->
+
+#### Fastify
+<!-- Please define the method signature in typescript because it's well known and easy to write -->
+
+__fastifyDecorators__
+
+#### Reply
+<!-- Please define the method signature in typescript because it's well known and easy to write -->
+
+__replyDecorators__
+
+## Dependencies
+
+__pluginDeps__
+
+## Compatible Fastify version
+
+__minFastify__