Merge branch 'dev'

* dev: (39 commits)
  Use the Slack bot's configured name for the web template title
  Add simple default message on receiving an unknown command
  Add 'help' and 'thankyou' commands'
  Update CHANGELOG after merge of feature/leaderboard
  Minor: remove empty tests that weren't supposed to make it in yet
  Hotfix: prevent missing request data in events test
  Minor cleanups, incl docs
  Rename leaderboard retrieval functions + simplify HTML rendering by only requiring template filename to be passed
  Rename 'send' functions to 'slack' because they now do more than just sending
  Minor tweaks and cleanups
  Leaderboard: complete web-viewable leaderboard with user name retrieval
  Hotfix: ensure token on verification is an integer to avoid concatenation
  WIP: Minor tweaks and fixes for web leaderboard
  WIP: Templates and structure for full web-viewable leaderboard
  Leaderboard: split ranking into separate function
  Leaderboard: extract URL + token building functionality + add tests
  WIP: Leaderboard functionality (working, no tests, no 'full leaderboard')
  Minor docs
  Simplify integration tests to not actually partially be end-to-end tests
  Add function to retrieve top scores from the DB
  ...

CHANGELOG.md

@@ -1,9 +1,21 @@
 # Changelog
-All notable changes to this project will be documented in this file.
+All notable changes to this project will be documented in this file.  
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+- Leaderboard functionality when `@WorkingPlusPlus leaderboard` is sent (requires additional app permissions - see step 6 of the installation instructions), including a link to a full web-based leaderboard with a time-based token to protect your team's data
+- Help message when `@WorkingPlusPlus help` is sent (requires the same additional app permissions as above)
+- Contributors: a raft of new helper functions including `isUser`, `isPlural` and many more
+- Contributors: additional tests to cover all previously added functionality (leaderboard functionality is not covered yet)
+
+### Changed
+- Contributors: another set of significant structural re-organisations to set the app up for handling more 'direct commands' in future
+
+### Fixed
+- Prevented +- or -+ from being interpreted as valid commands ([`005b69c`](https://github.com/tdmalone/working-plusplus/commit/005b69c6b297abf5c1014fd2dedc7db9e54b2900))
+
 ## [0.0.3] - 2018-08-11
 
 ### Added
@@ -26,7 +38,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 - Contributors: quite a bit of reorganising to make it easier both to grow and to test the app
 
 ### Fixed
-- Scores of -1 are now referred to as -1 point, rather than -1 points
+- Scores of -1 are now referred to as -1 point, rather than -1 points ([`d7d92be`](https://github.com/tdmalone/working-plusplus/commit/d7d92be0cd31aed26afcac1d189d17381330f418))
 
 ## [0.0.1] - 2018-08-06
 

CONTRIBUTING.md

@@ -53,8 +53,6 @@ You can run just a subset of tests:
 - Integration tests with `yarn integration-tests`
 - End-to-end tests with `yarn e2e-tests`
 
-It is normal to see _some_ errors while running the integration and end-to-end tests, but keep an eye on the exit code of the process to determine if it is successful (run `echo $?` immediately after running `yarn test` - you're looking for an exit code of `0` for a pass).
-
 You can modify the default testing behaviour by adjusting the relevant `scripts` in [`package.json`](package.json) or in some cases by passing additional [Jest configuration parameters](https://jestjs.io/docs/en/configuration.html) at the end of the test commands above.
 
 If you come across annoying *stylistic* linting rules, feel free to [change them](https://eslint.org/docs/rules/) in [`.eslintrc.js`](.eslintrc.js) as part of your pull request, providing they don't cause an adverse effect on existing code.

README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://travis-ci.com/tdmalone/working-plusplus.svg?branch=master)](https://travis-ci.com/tdmalone/working-plusplus)
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/d0d9b6c1d1c4430e9fad61bb60b5dc4e)](https://www.codacy.com/project/tdmalone/working-plusplus/dashboard)
-[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/d0d9b6c1d1c4430e9fad61bb60b5dc4e)](https://www.codacy.com/project/tdmalone/working-plusplus/files)
+[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/d0d9b6c1d1c4430e9fad61bb60b5dc4e)](https://www.codacy.com/app/tdmalone/working-plusplus/files)
 
 Like [plusplus.chat](https://plusplus.chat/), except this one actually works - because you can host it yourself! 😉
 
@@ -68,16 +68,40 @@ Completely open source, so do with it what you like. Or if you don't want to mak
 
    Via *Event Subscriptions* in the left menu. After switching on, enter your new Heroku app address - eg. `https://my-plusplus.herokuapp.com` - as the request URL.
 
-   Scroll down and, under *Subscribe to Bot Events*, add the `message.channels` and `message.groups` events, then click *Save Changes*.
+   Scroll down and, under *Subscribe to Bot Events*, select the relevant events for the features you want the app to support:
+
+   * Select `message.channels` to support all general features in _public_ channels it is invited to
+   * Select `message.groups` to support all general features in _private_ channels it is invited to
+   * Select `app_mention` to support extended features such as leaderboards
+
+   Finally, click *Save Changes*. If you wish, you can come back to this screen later and add or change the events the app handles.
 
 1. **Invite your new bot to any channel in your Slack team.**
 
 1. **Think of someone who's been awesome lately and send `@Someone++`!**
 
-## Detailed Instructions
+### More Information
 
 Further instructions, such as hosting elsewhere, upgrading, etc. are coming soon.
 
+## Usage
+
+**Working PlusPlus++** will listen out for messages, in channels it has been invited to, for valid commands. Commands are accepted anywhere in a message - at the beginning, middle, or end - and are currently limited to one command per message (if multiple commands are sent, only the first one found will be handled).
+
+Currently supported general commands are:
+
+* `@Someone++`: Adds points to a user or a thing
+* `@Someone--`: Subtracts points from a user or a thing
+
+Currently supported extended commands are:
+
+* `@WorkingPlusPlus leaderboard`: Displays the leaderboard for your Slack workspace
+* `@WorkingPlusPlus help`: Displays a help message showing these commands
+
+If you set a different name for your bot when adding the app to your Slack workspace, use that name instead.
+
+ℹ️ _Extended commands are supported if you've subscribed to the `app_mentions` event in your Slack app settings. See **Step 6** in the installation instructions above for further details._
+
 ## Contributing
 
 Your contributions are welcome! [Create an issue](https://github.com/tdmalone/working-plusplus/issues/new) if there's something you'd like to see or [send a pull request](https://github.com/tdmalone/working-plusplus/compare) if you can implement it yourself.
@@ -89,18 +113,19 @@ For full details on contributing, including getting a local environment set up,
 Although it works, it's very basic. Potential enhancements include:
 
 * A way to retrieve the current version/git hash from Slack, for sanity-checking of deployments
-* Leaderboard functionality (either, or both, via a full leaderboard on the web - with some sort of token or oauth - and a shorter leaderboard via a command in Slack)
 * The ability to customise the messages the bot sends back at runtime (eg. via environment variables)
 * Move to the newer, more secure method of calculating signatures for incoming Slack hooks
 * A way to look up someone's karma without necessarily `++`'ing or `--`'ing them (eg. `@username==`)
 * Support for posting back messages within threads, rather than automatically jumping back out to the channel
-* Support for detecting multiple actions within one message
+* Support for detecting multiple commands within one message
 * Natural language processing to figure out positive and negative sentiment automatically
 * Option to deduct karma instead of adding karma when someone tries to give themselves karma
 * Option to deduct karma automatically for swearing (with customisable word list?)
 * Record and make accessible how many karma points someone has _given_
 * Set up a Dockerfile to make local development easier (i.e. to not require Node, Yarn or Postgres)
 * Improve error handling
+* The ability to customise some of the leaderboard web functionality, such as colours and perhaps imagery as well
+* Additional linting tools for CSS and HTML
 
 ## License
 

index.js

@@ -9,10 +9,14 @@
 
 'use strict';
 
-const express = require( 'express' ),
-      slack = require( '@slack/client' ),
+const app = require( './src/app' ),
+      slack = require( './src/slack' );
+
+const fs = require( 'fs' ),
+      mime = require( 'mime' ),
+      express = require( 'express' ),
       bodyParser = require( 'body-parser' ),
-      app = require( './src/app' );
+      slackClient = require( '@slack/client' );
 
 /* eslint-disable no-process-env, no-magic-numbers */
 const PORT = process.env.PORT || 80; // Let Heroku set the port.
@@ -33,18 +37,30 @@ const bootstrap = ( options = {}) => {
 
   // Allow alternative implementations of both Express and Slack to be passed in.
   const server = options.express || express();
-  app.setSlackClient( options.slack || new slack.WebClient( SLACK_OAUTH_ACCESS_TOKEN ) );
+  slack.setSlackClient( options.slack || new slackClient.WebClient( SLACK_OAUTH_ACCESS_TOKEN ) );
 
   server.use( bodyParser.json() );
   server.enable( 'trust proxy' );
   server.get( '/', app.handleGet );
   server.post( '/', app.handlePost );
 
+  // Static assets.
+  server.get( '/assets/*', ( request, response ) => {
+    const path = 'src/' + request._parsedUrl.path,
+          type = mime.getType( path );
+
+    response.setHeader( 'Content-Type', type );
+    response.send( fs.readFileSync( path ) );
+  });
+
+  // Additional routes.
+  server.get( '/leaderboard', app.handleGet );
+
   return server.listen( PORT, () => {
     console.log( 'Listening on port ' + PORT + '.' );
   });
 
-};
+}; // Bootstrap.
 
 // If module was called directly, bootstrap now.
 if ( require.main === module ) {

jest.config.js

@@ -8,7 +8,7 @@
 
 const config = {
   collectCoverage: true,
-  setupTestFrameworkScriptFile: 'jest-chain',
+  setupTestFrameworkScriptFile: './jest.plugins',
   testEnvironment: 'node',
 
   testMatch: [

jest.plugins.js

@@ -0,0 +1,15 @@
+/**
+ * Defines plugins for use with Jest.
+ *
+ * @see https://jestjs.io/docs/en/configuration.html#setuptestframeworkscriptfile-string
+ */
+
+'use strict';
+
+// Allows assertions to be chained together, to reduce repetition.
+// @see https://github.com/mattphillips/jest-chain#usage
+require( 'jest-chain' );
+
+// Adds a bunch of additional matchers to Jest.
+// @see https://github.com/jest-community/jest-extended#api
+require( 'jest-extended' );

package.json

@@ -10,7 +10,7 @@
     "lint": "eslint --color --ignore-pattern '/coverage/' --ignore-pattern '!.*.js' \"**/*.js\"",
     "fix": "yarn lint --fix",
     "test": "jest --forceExit --runInBand",
-    "unit-tests": "SKIP_INTEGRATION_TESTS=true SKIP_E2E_TESTS=true jest",
+    "unit-tests": "SKIP_INTEGRATION_TESTS=true SKIP_E2E_TESTS=true jest --forceExit",
     "integration-tests": "SKIP_E2E_TESTS=true jest --forceExit integration-tests",
     "e2e-tests": "SKIP_INTEGRATION_TESTS=true jest --forceExit e2e-tests",
     "report-coverage": "codecov && cat ./coverage/lcov.info | codacy-coverage"
@@ -29,6 +29,9 @@
     "@slack/client": "^4.3.1",
     "body-parser": "^1.18.3",
     "express": "^4.16.3",
+    "handlebars": "^4.0.11",
+    "lodash.camelcase": "^4.3.0",
+    "mime": "^2.3.1",
     "pg": "^7.4.3"
   },
   "devDependencies": {
@@ -39,6 +42,7 @@
     "eslint-plugin-jest": "^21.18.0",
     "jest": "^23.4.2",
     "jest-chain": "^1.0.3",
+    "jest-extended": "^0.8.1",
     "object-assign-deep": "^0.4.0"
   }
 }