So what does danger export? Well:

import { danger, fail, markdown, message, schedule, warn } from 'danger'

Is the entire API for writing a Dangerfile. The interesting one is danger, so let’s cover everything else first. Y'know - save the best for last. These other exports are mainly the ways in which you can communicate the status of your rules back to Danger.

#Communication

These are functions which you use in rules to provide feedback during code review. Assuming Danger has access to write a comment, then fail, warn, message and markdown will report directly inline.

// Fails a build, outputting a specific reason for failing.
fail(message: MarkdownString) => void

// Puts a message inside the Danger table
markdown(message: MarkdownString) => void

// Adds a message to the Danger table, the only difference between this and warn is the emoji which shows in the table.
message(message: MarkdownString) => void

// Highlights low-priority issues, but does not fail the build.
warn(message: MarkdownString) => void

There's also schedule which is a bit of a special case. You can find out more from inside the guide On the Dangerfile. It helps you handle async code within your Dangerfile.

// `schedule` currently handles two types of arguments, either a promise or a function with a resolve arg.

// A Dangerfile is evaluated as a script, and so async code does not work out of the box. By using the `schedule` function you can now register a section of code to evaluate across multiple tick cycles.

schedule(asyncFunction: Promise | Function with a single callback argument) => void

#The Danger DSL - Root Objects

OK, great - so now let’s look through the API. This is the data that Danger will provide so that you can build rules for your team culture.

// Details specific to the git changes within the code changes. Currently, this is just the raw file paths that have been added, removed or modified.
danger.git: GitDSL

// Also provides an authenticated API so you can work directly with the GitHub API. That is an instance of the "github" npm module.

// The GitHub metadata. This covers things like PR info, comments and reviews on the PR, label metadata, commits with GitHub user identities and some useful utility functions for displaying links to files.

danger.github: GitHubDSL

// Functions which are gloablly useful in most Dangerfiles. Right now, these functions are around making sentences of arrays, or for making hrefs easily.
danger.utils: DangerUtilsDSL

#All Types

This is meant to be the API reference, so I’ll leave the prose at this point. Below is every object inside the Danger DSL. You can jump between the objects by clicking on their types.

I’d recommend first just having a quick browse to have an overview in your head. Then I’d recommend using the editor to actually write some code with auto-complete to get a sense of what the syntax feels like.

// The Danger DSL provides the metadata for introspection in order to create your own rules.

DangerDSLType {

// Details specific to the git changes within the code changes. Currently, this is just the raw file paths that have been added, removed or modified.
git: GitDSL

// Also provides an authenticated API so you can work directly with the GitHub API. That is an instance of the "github" npm module.

// The GitHub metadata. This covers things like PR info, comments and reviews on the PR, label metadata, commits with GitHub user identities and some useful utility functions for displaying links to files.

github: GitHubDSL

// Functions which are gloablly useful in most Dangerfiles. Right now, these functions are around making sentences of arrays, or for making hrefs easily.
utils: DangerUtilsDSL

}
// In the future I'd like this to be cross process, so please do not add functions, only data to this interface.

// The representation of what running a Dangerfile generates.


DangerResults {

// Failed messages
fails: Violation

// Markdown messages to attach at the bottom of the comment
markdowns: MarkdownString

// A set of messages to show inline
messages: Violation

// Messages for info
warnings: Violation

}
// The Danger Utils DSL contains utility functions that are specific to universal Danger use-cases.

DangerUtilsDSL {

// If `href` and `text` are falsy, null is returned. If `href` is falsy and `text` is truthy, `text` is returned. If `href` is truthy and `text` is falsy, an <a> tag is returned with `href` as its href and text value. Otherwise, if `href` and `text` are truthy, an <a> tag is returned with the `href` and `text` inserted as expected.

// Creates a link using HTML.

href(href: string, text: string) => string | null

// Converts an array of strings into a sentence.
sentence(array: string) => string

}
// A platform agnostic reference to a Git commit

GitCommit {

// Who wrote the commit
author: GitCommitAuthor

// Who deployed the commit
committer: GitCommitAuthor

// The commit message
message: string

// SHAs for the commit's parents
parents?: string

// The SHA for the commit
sha: string

// Potential parent commits, and other assorted metadata
tree: any

// Link to the commit
url: string

}
// An author of a commit

GitCommitAuthor {

// ISO6801 date string
date: string

// The authors email
email: string

// The display name for the author
name: string

}
// The git specific metadata for a PR

GitDSL {

// The Git commit metadata
commits: GitCommit

// Newly created filepaths relative to the git root
created_files: string

// Removed filepaths relative to the git root
deleted_files: string

// Filepaths with changes relative to the git root
modified_files: string

// Any changed values will be represented with the same path, but with a different object instead. This object will always show a `before` and `after` for the changes. If both values are arrays or objects the `before` and `after`, then there will also be `added` and `removed` inside the object. In the case of two objects, the `added` and `removed` will be an array of keys rather than the values. This object is represented as `JSONDiffValue` but I don't know how to make TypeScript force declare that kind of type structure. This should make it really easy to do work when specific keypaths have changed inside a JSON file.

// Provides a simplified JSON diff between the two versions of a JSON file. This will always be an object whose keys represent what has changed inside a JSON file.

JSONDiffForFile(filename: string) => Promise<JSONDiff>

// Note that if you are looking to just see changes like: before, after, added or removed - you should use `JSONDiffForFile` instead, as this can be a bit unweildy for a Dangerfile.

// Provides a JSON patch (rfc6902) between the two versions of a JSON file, returns null if you don't have any changes for the file in the diff.

JSONPatchForFile(filename: string) => Promise<JSONPatch | null>

// Offers the diff for a specific file
diffForFile(filename: string) => Promise<TextDiff | null>

}
// Provides the current PR in an easily used way for params in `github.api` calls

GitHubAPIPR {

// The PR number
number: number

// The repo owner
owner: string

// The repo name
repo: string

}
// A GitHub specific implmentation of a git commit, it has GitHub user names instead of an email.

GitHubCommit {

// The GitHub user who wrote the code
author: GitHubUser

// The raw commit metadata
commit: GitCommit

// The GitHub user who shipped the code
committer: GitHubUser

// An array of parent commit shas
parents: any

// The SHA for the commit
sha: string

// the url for the commit on GitHub
url: string

}
// The GitHub metadata for your PR

GitHubDSL {

// An authenticated API so you can extend danger's behavior. An instance of the "github" npm module.
api: GitHub

// The github commit metadata for a code review session
commits: GitHubCommit

// The issue metadata for a code review session
issue: GitHubIssue

// The PR metadata for a code review session
pr: GitHubPRDSL

// The people requested to review this PR
requested_reviewers: GitHubUser

// The reviews left on this pull request
reviews: GitHubReview

// The PR metadata specifically formatted for using with the GitHub API client
thisPR: GitHubAPIPR

// A scope for useful functions related to GitHub
utils: GitHubUtilsDSL

}
// A GitHub Issue

// This is `danger.github.issue` It refers to the issue that makes up the Pull Request. GitHub treats all pull requests as a special type of issue. This DSL contains only parts of the issue that are not found in the PR DSL, however it does contain the full JSON structure.


GitHubIssue {

// The labels associated with this issue
labels: GitHubIssueLabel

}
// An exact copy of the PR's reference JSON. This interface has type'd the majority of it for tooling's sake, but any extra metadata which GitHub send will still be inside the JS object.

GitHubPRDSL {

// The number of additional lines in the PR
additions: number

// The User who is assigned the PR
assignee: GitHubUser

// The Users who are assigned to the PR
assignees: GitHubUser

// Merge reference for _this_ repo.
base: GitHubMergeRef

// The markdown body message of the PR
body: string

// The number of changed files in the PR
changed_files: number

// optional ISO6801 Date string for when PR was closed
closed_at: string | null

// The number of comments on the PR
comments: number

// The number of commits in the PR
commits: number

// ISO6801 Date string for when PR was created
created_at: string

// The number of deleted lines in the PR
deletions: number

// Merge reference for the _other_ repo.
head: GitHubMergeRef

// Has the PR been locked to contributors only?
locked: boolean

// Has the PR been merged yet?
merged: boolean

// Optional ISO6801 Date string for when PR was merged. Danger probably shouldn't be running in this state.
merged_at: string | null

// The UUID for the PR
number: number

// The number of review-specific comments on the PR
review_comments: number

// The state for the PR
state: "closed" | "open" | "locked" | "merged"

// The title of the PR
title: string

// ISO6801 Date string for when PR was updated
updated_at: string

// The User who submitted the PR
user: GitHubUser

}
// A GitHub Repo

GitHubRepo {

// Is someone assigned to this PR?
assignee: GitHubUser

// Are there people assigned to this PR?
assignees: GitHubUser

// The textual description of the repo
description: string

// Is the repo a fork?
fork: boolean

// The full name of the owner + repo, e.g. "Danger/Danger-JS"
full_name: string

// The root web URL for the repo, e.g. https://github.com/artsy/emission
html_url: string

// Generic UUID
id: number

// The name of the repo, e.g. "Danger-JS"
name: string

// The owner of the repo
owner: GitHubUser

// Is the repo publicly accessible?
private: boolean

}
// GitHubReview While a review is pending, it will only have a user. Once a review is complete, the rest of the review attributes will be present

GitHubReview {

// If there is a review, the body of the review
body?: string

// If there is a review, the commit ID this review was made on
commit_id?: string

// If there is a review, this provides the ID for it
id?: number

// The state of the review APPROVED, REQUEST_CHANGES, COMMENT or PENDING
state?: "APPROVED" | "REQUEST_CHANGES" | "COMMENT" | "PENDING"

// The user requested to review, or the user who has completed the review
user: GitHubUser

}
// A GitHub user account.

GitHubUser {

// Generic UUID
id: number

// The handle for the user/org
login: string

// Whether the user is an org, or a user
type: "User" | "Organization"

}
// Useful functions for GitHub related work

GitHubUtilsDSL {

// Creates HTML for a sentence of clickable links for an array of paths. This uses the source of the PR as the target, not the destination repo. You can manually set the target repo and branch however, to make it work how you want.
fileLinks(paths: string, useBasename?: true | false, repoSlug?: string, branch?: string) => string

}
// A map of string keys to JSONDiffValue

JSONDiff {

// A map of string keys to JSONDiffValue
}
// All JSON diff values will be this shape

JSONDiffValue {

// If both before & after are arrays, then you optionally get what is added. Empty if no additional objects.
added?: any

// The value after the PR's applied changes
after: any

// The value before the PR's applied changes
before: any

// If both before & after are arrays, then you optionally get what is removed. Empty ig no removed objects.
removed?: any

}
// The results of running a JSON patch

JSONPatch {

// The JSON in a file from the PR submitter
after: any

// The JSON in a file at the PR merge base
before: any

// The set of operations to go from one JSON to another JSON
diff: JSONPatchOperation

}
// An individual operation inside an rfc6902 JSON Patch

JSONPatchOperation {

// An operation type
op: string

// The JSON keypath which the operation applies on
path: string

// The changes for applied
value: string

}
// All Text diff values will be this shape

TextDiff {

// A string containing just the added lines
added: string

// The value after the PR's applied changes
after: string

// The value before the PR's applied changes
before: string

// A string containing the full set of changes
diff: string

// A string containing just the removed lines
removed: string

}
// The result of user doing warn, message or fail.

Violation {

// The string representation
message: string

}