Merge pull request #13 from vegaprotocol/feat/help

Add more helpful help

.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npm run lint -- --fix

.husky/pre-push

@@ -0,0 +1,5 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npm run test
+npm run lint

README.md

@@ -1,5 +1,5 @@
 # approbation
-Coverage matrix for [specifications](https://github.com/vegaprotocol/specs)
+Scripts for producing a coverage matrix for Vega [specifications](https://github.com/vegaprotocol/specs)
 
 ## Specification file names
 Each protocol specification receives a sequence number when it is merged in to master. 
@@ -61,11 +61,39 @@ set of tests, to produce a coverage number
 
 # Running these checks
 
+## v2.0.0 onwards
+_All_ checks take a `--specs` argument, which is a [glob](https://www.npmjs.com/package/glob) specifying the specification files to check.
+
+```bash
+npx @vegaprotocol/[email protected] check-codes --specs='./protocol/*.md'
+```
+
+`check-references` also requires a `--tests` glob, specifying the tests to cross-reference with the `--specs`:
+
+```bash
+npx @vegaprotocol/[email protected] check-references --specs='./protocol/*.md' --tests='{./feature/*.feature,./system-tests/**/*.py}'
+```
+
+This second example shows how to use globs to specify multiple paths containing tests. For more complex examples, check the 
+ [glob](https://www.npmjs.com/package/glob) documentation.
+
+### Defaults
+Default paths will be removed in v3.0.0, but exist in v2.0.0 for legacy support. If not specified, for `check-codes` & `check-filenames`:
+```
+--specs='{./non-protocol-specs/**/*.md,./protocol/**/*.md}'
+```
+
+And for `check-references`:
 ```
-npx @vegaprotocol/approbation check-references
+--specs='{./non-protocol-specs/**/*.md,./protocol/**/*.md}'
+--tests'{./qa-scenarios/**/*.{feature,py}}'
+  
 ```
 
 # Development
+- Linting uses [standard](https://www.npmjs.com/package/standard)
+- Tests are run pre-push by [Husky](https://www.npmjs.com/package/husky)
+- Tags are pushed to npm
 
 # [License](./LICENSE)
 The Unlicense

bin/approbation.js

@@ -1,28 +1,65 @@
 #!/usr/bin/env node
 
+const packageJson = require('../package.json')
 const { checkFilenames } = require('../src/check-filenames')
 const { checkCodes } = require('../src/check-codes')
 const { checkReferences } = require('../src/check-references')
-
-require('../src/check-filenames')
+const pc = require('picocolors')
 
 const argv = require('minimist')(process.argv.slice(2))
 const command = argv._[0]
 
+function warn (lines) {
+  console.warn('')
+  lines.map(l => console.warn(pc.yellow(`! ${l}`)))
+  console.warn('')
+}
+
 let res
 
+console.log(pc.bold(`Approbation ${packageJson.version}`))
+console.log('')
+
 if (command === 'check-filenames') {
-  const paths = argv.specs ? argv.specs : '{./non-protocol-specs/**/*.md,./protocol/**/*.md}'
+  let paths = '{./non-protocol-specs/**/*.md,./protocol/**/*.md}'
+
+  if (!argv.specs) {
+    warn(['No --specs argument provided, defaulting to:', `--specs="${paths}"`, '(This behaviour will be deprecated in 3.0.0)'])
+  } else {
+    paths = argv.specs
+  }
+
   res = checkFilenames(paths)
   process.exit(res.exitCode)
 } else if (command === 'check-codes') {
-  const paths = argv.specs ? argv.specs : '{./non-protocol-specs/**/*.md,./protocol/**/*.md}'
+  let paths = '{./non-protocol-specs/**/*.md,./protocol/**/*.md}'
+
+  if (!argv.specs) {
+    warn(['No --specs argument provided, defaulting to:', `--specs="${paths}"`, '(This behaviour will be deprecated in 3.0.0)'])
+  } else {
+    paths = argv.specs
+  }
+
   res = checkCodes(paths)
   process.exit(res.exitCode)
 } else if (command === 'check-references') {
-  const specsGlob = argv.specs ? argv.specs : '{./non-protocol-specs/**/*.md,./protocol/**/*.md}'
-  const testsGlob = argv.tests ? argv.specs : '{./qa-scenarios/**/*.{feature,py}}'
+  let specsGlob = '{./non-protocol-specs/**/*.md,./protocol/**/*.md}'
+  let testsGlob = '{./qa-scenarios/**/*.{feature,py}}'
+
+  if (!argv.specs) {
+    warn(['No --specs argument provided, defaulting to:', `--specs="${specsGlob}"`, '(This behaviour will be deprecated in 3.0.0)'])
+  } else {
+    specsGlob = argv.specs
+  }
+
+  if (!argv.tests) {
+    warn(['No --tests argument provided, defaulting to:', `--specs="${testsGlob}"`, '(This behaviour will be deprecated in 3.0.0)'])
+  } else {
+    testsGlob = argv.tests
+  }
+
   res = checkReferences(specsGlob, testsGlob)
+
   process.exit(res.exitCode)
 } else {
   console.error('Please choose a command')
@@ -34,7 +71,7 @@ if (command === 'check-filenames') {
   console.log('--specs="{**/*.md}"')
   console.groupEnd('Arguments')
   console.groupEnd('check-codes')
-  
+
   console.group('check-filenames')
   console.log('Check that spec filenames are valid')
   console.group('Arguments')
@@ -49,5 +86,4 @@ if (command === 'check-filenames') {
   console.log('--tests="tests/**/*.{py,feature}"')
   console.groupEnd('Arguments')
   console.groupEnd('check-references')
-
 }

package.json

@@ -1,13 +1,14 @@
 {
   "name": "@vegaprotocol/approbation",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Match Acceptance Criteria Codes with the tests that test them",
   "main": "./bin/approbation.js",
   "engine": ">= 16",
   "bin": "./bin/approbation.js",
   "scripts": {
     "test": "tape test/*.js",
-    "lint": "standard **/*.js"
+    "lint": "standard **/*.js",
+    "prepare": "husky install"
   },
   "repository": {
     "type": "git",
@@ -20,6 +21,8 @@
   },
   "homepage": "https://github.com/vegaprotocol/approbation#readme",
   "devDependencies": {
+    "husky": "^7.0.4",
+    "picocolors": "^1.0.0",
     "standard": "16.0.4",
     "tape": "5.5.2"
   },

src/check-codes.js

@@ -28,6 +28,7 @@ const glob = require('glob')
 const path = require('path')
 const { validSpecificationPrefix } = require('./lib')
 const { minimumAcceptableACsPerSpec } = require('./config')
+const pc = require('picocolors')
 
 /**
  * Generator to chunk array by defined size, defaulting to 3
@@ -140,7 +141,7 @@ function checkCodes (paths) {
       exitCode = 0
     }
   } else {
-    console.error('glob matched no files')
+    console.error(pc.red(`glob matched no files (${paths})`))
     exitCode = 1
   }
 

src/check-filenames.js

@@ -12,6 +12,7 @@ const fs = require('fs')
 const glob = require('glob')
 const path = require('path')
 const { validSpecificationFilename } = require('./lib')
+const pc = require('picocolors')
 
 // Configure the acc
 const maxInvalidFilenames = 0
@@ -90,17 +91,18 @@ function checkFilenames (paths) {
       countValidFilenames: p.countValidFilenames
     }
 
-    console.log('\r\n--------------------------------------------------')
-    console.log(`Correctly named    ${total.countValidFilenames}`)
-    console.log(`Errors             ${total.countInvalidFilenames}`)
-    console.log('\r\n\r\n')
+    console.log()
+    console.log(pc.bold(pc.green('Correctly named')) + '    ' + pc.bold(total.countValidFilenames))
+    console.log(pc.bold(pc.red('Errors')) + '             ' + pc.bold(total.countInvalidFilenames))
+    console.log()
 
     if (total.countInvalidFilenames > maxInvalidFilenames) {
       exitCode = 1
     } else {
       exitCode = 0
     }
   } else {
+    console.error(pc.red(`glob matched no files (${paths})`))
     exitCode = 1
   }