Merge pull request #517 from danger/docs_2

Updating docs and adds architecture doc

CONTRIBUTING.md

@@ -22,6 +22,10 @@ yarn lint
 The fixers for both tslint and prettier will be applied when you commit, and on a push your code will be verified
 that it compiles.
 
+### How does Danger JS work?
+
+Check the [architecture doc](https://github.com/danger/danger-js/blob/master/docs/architecture.md).
+
 ### What is the TODO?
 
 Check the issues, I try and keep my short term perspective there. Long term is in the [VISION.md](VISION.md).
@@ -30,12 +34,12 @@ Check the issues, I try and keep my short term perspective there. Long term is i
 
 Following [this commit](https://github.com/danger/danger-js/commit/a26ac3b3bd4f002acd37f6a363c8e74c9d5039ab) as a model:
 
--   Checkout the `master` branch. Ensure your working tree is clean, and make sure you have the latest changes by running `git pull`.
--   Update `package.json` with the new version - for the sake of this example, the new version is **0.21.0**.
--   Modify `changelog.md`, adding a new `### 0.21.0` heading under the `### Master` heading at the top of the file.
--   Commit both changes with the commit message **Version bump**.
--   Tag this commit - `git tag 0.21.0`.
--   Push the commit and tag to master - `git push origin master --follow-tags`. Travis CI will build the tagged commit and publish that tagged version to NPM.
+* Checkout the `master` branch. Ensure your working tree is clean, and make sure you have the latest changes by running `git pull`.
+* Update `package.json` with the new version - for the sake of this example, the new version is **0.21.0**.
+* Modify `changelog.md`, adding a new `### 0.21.0` heading under the `### Master` heading at the top of the file.
+* Commit both changes with the commit message **Version bump**.
+* Tag this commit - `git tag 0.21.0`.
+* Push the commit and tag to master - `git push origin master --follow-tags`. Travis CI will build the tagged commit and publish that tagged version to NPM.
 
 :ship:
 
@@ -48,4 +52,3 @@ We try to keep as much discussion as possible in GitHub issues, but also have a
 > This project subscribes to the [Moya Contributors Guidelines](https://github.com/Moya/contributors) which TLDR: means we give out push access easily and often.
 >
 > Contributors subscribe to the [Contributor Code of Conduct](http://contributor-covenant.org/version/1/3/0/) based on the [Contributor Covenant](http://contributor-covenant.org) version 1.3.0.
-

VISION.md

@@ -1,56 +1,37 @@
 # Danger for JS
 
-Two years in, and [Danger](https://github.com/danger/danger) Ruby is doing just fine. See the [original vision file](https://github.com/danger/danger/blob/master/VISION.md). This document assumes you have read it. 
+Danger JS is a tool to creating complex per-project rules, and messages in Code Review. One of it's key aims is to be
+able to run on a server, and not need direct access to the filesystem to do its work.
 
-The amount of issues we get in comparison to the number of downloads on Rubygems makes me feel pretty confident about her state of production quality and maturity. I wanted to start thinking about the larger patterns in software, because at Artsy, we are starting to use JavaScript in [for many teams](http://artsy.github.io/blog/2016/08/15/React-Native-at-Artsy/).
+It was started in mid-2016, and has fleshed out into a considerable set of useful tools.
 
-I've explored [running JavaScript](https://github.com/danger/danger/pull/423) from the ruby Danger, ([example](https://github.com/artsy/emission/blob/d58b3d57bf41100e3cce3c2c1b1c4d6c19581a68/Dangerfile.js) from production) but this pattern isn't going to work on the larger scale: You cannot use npm modules, nor work with babel/tsc to transpile your `Dangerfile.js` and the requirements on the integrating project to [feel weird](https://github.com/artsy/emission/pull/233). Running JS in Ruby isn't going to work for me.
-
-This realization came at the same time as serious thinking on a hosted version of Danger. With a JavaScript versions we can limit the exposed Danger DSL to only something that can be obtained over the API remotely. By doing this, a hosted Danger does not need to clone and run the associated projects. This is essential for my sanity. I cannot run multiple [servers like CocoaDocs](http://cocoadocs.org). So far, I'm calling this Peril. You can consult the [vision file for Peril](https://github.com/danger/peril/blob/master/VISION.md) if you'd like.
-
-# Where is Danger JS going?
+* You can fake running on CI for any PR with `danger pr`.
+* You can run Danger rules inside git hooks, or without pull requests metadata via `danger local`.
+* You can share code using [danger plugins][plugins].
+* You can get started in a fun way via `danger init`.
+* Danger can run independently of CI via Peril.
 
-You can see the roadmap for features for Danger JS by looking at things the Ruby version supports.
+## Future Plans
 
--   Inline comments in PRs
--   GitLab / BitBucket support
--   Bigger plugin ecosystem
+There are only really two big targets for the future of Danger JS:
 
-However because of the addition of Peril, Danger JS should also look at:
+* Inline comments in PRs
+* GitLab / BitBucket support
 
--   Module or function whitelisting
--   Callback based Danger runs
+I don't plan on really using either of those features, so I expect both to come from the community instead.
 
-### Example of a Dangerfile.js
+My focus is going to be mainly in the Peril side of Danger. Moving to making it trivial to add Danger to any GitHub
+project and really unlocking some complex culture systems. Examples of these can be found on [the Artsy blog][peril].
 
-```js
-import danger from 'danger'
-import _ from 'lodash'
+# Why Danger JS? What about Danger Ruby?
 
-const hasAppChanges = _.filter(danger.git.modified_files, (path) => {
-  return _.includes(path, 'lib/');
-}).length > 0
+When I started Danger JS, Danger Ruby was two years old, is still doing just fine. See the [original vision file](https://github.com/danger/danger/blob/master/VISION.md). This document assumes you have read it.
 
-if (hasAppChanges && _.includes(danger.git.modified_files, "CHANGELOG.md") === false) {
-  fail("No CHANGELOG added.")
-}
+The amount of issues we get in comparison to the number of downloads on Rubygems makes me feel pretty confident about Danger Ruby's state of production quality and maturity. I wanted to start thinking about the larger patterns in software, because at Artsy, we are starting to use JavaScript in [for many teams](http://artsy.github.io/blog/2016/08/15/React-Native-at-Artsy/).
 
-const testFiles = _.filter(danger.git.modified_files, (path) => {
-  return _.includes(path, '__tests__/');
-})
-
-const logicalTestPaths = _.map(testFiles, (path) => {
-  // turns "lib/__tests__/i-am-good-tests.js" into "lib/i-am-good.js"
-  return path.replace(/__tests__\//, '').replace(/-tests\./, '.')
-})
+I've explored [running JavaScript](https://github.com/danger/danger/pull/423) from the ruby Danger, ([example](https://github.com/artsy/emission/blob/d58b3d57bf41100e3cce3c2c1b1c4d6c19581a68/Dangerfile.js) from production) but this pattern isn't going to work on the larger scale: You cannot use npm modules, nor work with babel/tsc to transpile your `Dangerfile.js` and the requirements on the integrating project to [feel weird](https://github.com/artsy/emission/pull/233). Running JS in Ruby isn't going to work for me.
 
-const sourcePaths = _.filter(danger.git.modified_files, (path) => {
-  return _.includes(path, 'lib/') &&  !_.includes(path, '__tests__/');
-})
+This realization came at the same time as serious thinking on a hosted version of Danger. With a JavaScript versions we can limit the exposed Danger DSL to only something that can be obtained over the API remotely. By doing this, a hosted Danger does not need to clone and run the associated projects. This is essential for my sanity. I cannot run multiple [servers like CocoaDocs](http://cocoadocs.org). So far, I'm calling this Peril. You can consult the [vision file for Peril](https://github.com/danger/peril/blob/master/VISION.md) if you'd like.
 
-// Check that any new file has a corresponding tests file
-const untestedFiles = _.difference(sourcePaths, logicalTestPaths)
-if (untestedFiles.length > 0) {
-  warn("The following files do not have tests: " + danger.github.html_link(untestedFiles))
-}
-```
+[plugins]: https://www.npmjs.com/search?q=keywords:danger-plugin&page=1&ranking=optimal
+[peril]: http://artsy.github.io/blog/2017/09/04/Introducing-Peril/

docs/architecture.md

@@ -0,0 +1,34 @@
+## How does Danger JS work?
+
+Danger provides an evaluation system for creating per-application rules. Basically, it is running arbitrary JavaScript with some extra PR metadata added in at runtime.
+
+Actually doing that though, is a bit of a process.
+
+## Setup
+
+**Step 1: CI**. Danger needs to figure out what CI we're running on. You can see them all [in `source/ci_source/providers`][provs]. These use
+ENV VARs to figure out which CI `danger ci` is running on and validate whether it is a pull request.
+
+**Step 2: Platform**. Danger needs to know which platform the code review is happening in. Today it's just GitHub, but BitBucket Server is around the corner.
+
+**Step 3: JSON DSL**. To allow for all of:
+
+* `danger ci` to evaluate async code correctly
+* `danger process` to work with other languages
+* `peril` to arbitrarily sandbox danger per-run on a unique docker container
+
+Danger first generates a JSON DSL. This can be passed safely between processes, or servers. For `danger ci` the exposed DSL is created
+as a [DangerDSLJSONType][dangerdsl] and this is passed into the hidden [command `danger runner`][runner].
+
+**Step 4: DSL**. The JSON DSL is picked up from STDIN in `danger runner` and then converted into a [DangerDSLType][dangerdsl]. This is basically where
+functions are added into the DSL.
+
+**Step 5: Evaluation**. With the DSL ready, the [inline runner][in_runner] sets up a transpiled environment for evaluating your code, and adds the DSL attributes into the global evaluation context. The Dangerfile has the `import {...} from 'danger'` stripped, and then is executed inline.
+
+**Step 6: Results**. Once the `danger runner` process is finished with evaluation, the results are passed back to the the plaform. The platform then
+chooses whether to create/delete/edit any messages in core review.
+
+[provs]: https://github.com/danger/danger-js/tree/master/source/ci_source/providers
+[dangerdsl]: https://github.com/danger/danger-js/blob/master/sourformace/dsl/DangerDSL.ts
+[runner]: https://github.com/danger/danger-js/blob/master/source/commands/danger-runner.ts
+[in_runner]: https://github.com/danger/danger-js/blob/master/source/runner/runners/inline.ts

package.json

@@ -99,7 +99,7 @@
     "ts-jest": "^22.0.1",
     "ts-node": "^4.1.0",
     "tslint": "^5.9.1",
-    "tslint-config-prettier": "^1.6.0",
+    "tslint-config-prettier": "^1.8.0",
     "typedoc": "0.9.0",
     "typescript": "^2.6.2"
   },

source/runner/runners/inline.ts

@@ -79,7 +79,7 @@ export async function runDangerfileEnvironment(
 
     return environment.results
   } catch (error) {
-    console.error("Unable to evaluate the Dangerfile")
+    console.error("Unable to evaluate the Dangerfile\n", error)
     d("Got a parse error: ", error)
     environment.results = resultsForCaughtError(filename, content, error)
     return environment.results