feat: document in readme

Author: bahmutov

README.md

@@ -14,11 +14,76 @@
 Requires [Node](https://nodejs.org/en/) version 6 or above.
 
 ```sh
-npm install --save stop-upper
+npm install --save-dev stop-upper
 ```
 
 ## Use
 
+### basic
+
+Assuming all interesting files are in the folders "src" and "bin", I recommend create an NPM run script. Use `--folder` or `-f` to pass the folder(s) to search.
+
+```json
+{
+  "scripts": {
+    "stop-upper": "stop-upper --folder src --folder bin"
+  }
+}
+```
+
+Exits with 1 if there is a file with uppercase somewhere inside the folders. Also checks folder names.
+
+### warn
+
+If you just want to warn on found uppercase names, use `stop-upper --warn <folder>` syntax. Alias `-w`.
+
+### Pre-commit or pre-push hook
+
+If using [pre-git][pre-git] to configure Git hooks, run this tool as a command
+
+```json
+{
+  "config": {
+    "pre-git": {
+      "pre-push": ["npm run stop-upper"]
+    }
+  }
+}
+```
+
+See [package.json](package.json) (note here we have just local script name).
+
+**tip** you can warn on commit hook, while fail in pre-push hook.
+
+[pre-git]: github.com/bahmutov/pre-git#readme
+
+### Commas
+
+You can pass multiple folder names as separate arguments or comma-separated. These are equivalent
+
+```
+stop-upper --folder foo --folder bar
+stop-upper -f foo -f bar
+stop-upper -f foo,bar
+```
+
+### Debugging
+
+You can see additional diagnostic output from this command by running with environment variable `DEBUG=stop-upper`
+
+### CI
+
+On CI run the tool after install, for example see [.travis.yml](.travis.yml),
+(note here we have just local script name).
+
+```
+- npm run stop-upper
+```
+
+## Related
+
+- [stop-only](https://github.com/bahmutov/stop-only)
+
 ### Small print
 
 Author: Gleb Bahmutov &lt;gleb.bahmutov@gmail.com&gt; &copy; 2018

bin/stop-upper.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+const debug = require('debug')('stop-upper')
+const globby = require('globby')
+const { filter, flatten, uniq } = require('ramda')
+
+const argv = require('minimist')(process.argv.slice(2), {
+  string: ['folder', 'skip', 'exclude'],
+  boolean: 'warn',
+  alias: {
+    warn: 'w',
+    folder: 'f',
+    skip: 's',
+    exclude: 'e'
+  }
+})
+
+if (debug.enabled) {
+  console.log('stop-upper arguments')
+  console.log(argv)
+}
+
+if (!argv.folder || !argv.folder.length) {
+  console.error(
+    '🔥 stop-upper: pass at least a single folder with --folder, -f argument'
+  )
+  process.exit(1)
+}
+
+const toArray = x => (Array.isArray(x) ? x : [x])
+
+const normalizeStrings = listOrString => {
+  const strings = toArray(listOrString)
+  // ? can we just split and flatten result array?
+  let normalized = []
+  strings.forEach(s => {
+    if (s === undefined || s === null) {
+      return
+    }
+
+    if (s.includes(',')) {
+      normalized = normalized.concat(s.split(','))
+    } else {
+      normalized.push(s)
+    }
+  })
+  return normalized
+}
+
+// user should be able to pass multiple folders with single argument separated by commas
+// like "--folder foo,bar,baz"
+// next code block splits these arguments and normalizes everything into list of strings
+const splitFolders = normalizeStrings(argv.folder)
+debug('split folders', splitFolders)
+
+const folders = flatten(splitFolders)
+
+if (debug.enabled) {
+  console.log('stop only in folders')
+  console.log(folders)
+}
+
+const searchFinished = foundUpperCaseFilename => {
+  if (foundUpperCaseFilename.length === 0) {
+    debug('could not find upper case filenames')
+    process.exit(0)
+  }
+
+  // found uppercase filename somewhere
+  if (argv.warn) {
+    console.log('⚠️ Found uppercase filenames')
+    console.log(foundUpperCaseFilename.join('\n'))
+    process.exit(0)
+  } else {
+    console.log('Found uppercase filenames 👎')
+    console.log(foundUpperCaseFilename.join('\n'))
+    process.exit(1)
+  }
+}
+
+const hasUpper = s => s.match(/[A-Z]/)
+
+const onError = e => {
+  console.error(e.message)
+  process.exit(1)
+}
+
+globby(folders)
+  .then(flatten)
+  .then(filter(hasUpper))
+  .then(uniq)
+  .then(searchFinished)
+  .catch(onError)