danger

danger

Version 12.3.3
Published 2 months ago
1.42 MB
37 dependencies
MIT license

Install

npm i danger

yarn add danger

pnpm add danger

Overview

Unit tests for Team Culture

Index

Variables

variable danger

const danger: DangerDSLType;

The root Danger object. This contains all of the metadata you will be looking for in order to generate useful rules.

variable peril

const peril: PerilDSL;

When Peril is running your Dangerfile, the Danger DSL is extended with additional options.

variable results

const results: DangerRuntimeContainer;

The current results of a Danger run, this can be useful if you are wanting to introspect on whether a build has already failed.

Functions

function fail

fail: (message: MarkdownString, file?: string, line?: number) => void;

Highlights critical issues. Message is shown inside a HTML table.
Parameter message
the String to output
Parameter file
a file which this message should be attached to
Parameter line
the line which this message should be attached to

function markdown

markdown: (message: MarkdownString, file?: string, line?: number) => void;

Adds raw markdown into the Danger comment, under the table
Parameter message
the String to output
Parameter file
a file which this message should be attached to
Parameter line
the line which this message should be attached to

function message

message: {
    (message: MarkdownString, file?: string, line?: number): void;
    (message: string, opts?: { file?: string; line?: number; icon?: string }): void;
};

Adds a message to the Danger table, the only difference between this and warn is the emoji which shows in the table.
Parameter message
the String to output
Parameter file
a file which this message should be attached to
Parameter line
the line which this message should be attached to
Adds a message to the Danger table, the only difference between this and warn is the default emoji which shows in the table. You can also specifiy a custom emoji to show in the table for each message
Parameter message
the String to output
Parameter opts
Parameter
opts.file a file which this message should be attached to
Parameter
opts.line the line which this message should be attached to
Parameter
opts.icon icon string or image to show in table, take care not to break table formatting

function schedule

schedule: (asyncFunction: Scheduleable) => void;

A Dangerfile, in Peril, 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 currently handles two types of arguments, either a promise or a function with a resolve arg.
Parameter asyncFunction
the function to run asynchronously

function warn

warn: (message: MarkdownString, file?: string, line?: number) => void;

Highlights low-priority issues. Message is shown inside a HTML table.
Parameter message
the String to output
Parameter file
a file which this message should be attached to
Parameter line
the line which this message should be attached to

Interfaces

interface BitBucketCloudAPIDSL

interface BitBucketCloudAPIDSL {}

method delete

delete: (path: string, headers: any, body: any) => Promise<any>;

Make a delete call against the bitbucket server API

method get

get: (path: string, headers: any, suppressErrors?: boolean) => Promise<any>;

Make a get call against the bitbucket server API

method getFileContents

getFileContents: (
    filePath: string,
    repoSlug?: string,
    refspec?: string
) => Promise<string>;

Gets the contents of a file from a repo (defaults to yours)

method post

post: (
    path: string,
    headers: any,
    body: any,
    suppressErrors?: boolean
) => Promise<any>;

Make a post call against the bitbucket server API

method put

put: (path: string, headers: any, body: any) => Promise<any>;

Make a put call against the bitbucket server API

interface BitBucketCloudCommit

interface BitBucketCloudCommit {}

A BitBucketCloud specific implementation of a git commit.

property author

author: {
    /** Format: `Foo Bar <foo@bar.com>` */
    raw: string;
    user: BitBucketCloudUser;
};

The author of the commit, assumed to be the person who wrote the code.

property date

date: string;

When the commit was committed to the project, in ISO 8601 format

property hash

hash: string;

The SHA for the commit

property links

links: BitBucketCloudLinks<'html'>;

The commit's links

property message

message: string;

The commit's message

property parents

parents: {
    /** The full SHA */
    hash: string;
}[];

The commit's parents

interface BitBucketCloudContent

interface BitBucketCloudContent {}

property html

html: string;

property markup

markup: string;

property raw

raw: string;

property type

type: 'rendered';

interface BitBucketCloudDSL

interface BitBucketCloudDSL extends BitBucketCloudJSONDSL {}

property api

api: BitBucketCloudAPIDSL;

An authenticated API so you can extend danger's behavior.

interface BitBucketCloudJSONDSL

interface BitBucketCloudJSONDSL {}

property activities

activities: BitBucketCloudPRActivity[];

The activities such as OPENING, CLOSING, MERGING or UPDATING a pull request

property comments

comments: BitBucketCloudPRComment[];

The comments on the pull request

property commits

commits: BitBucketCloudCommit[];

The commits associated with the pull request

property metadata

metadata: RepoMetaData;

The pull request and repository metadata

property pr

pr: BitBucketCloudPRDSL;

The PR metadata

interface BitBucketCloudMergeRef

interface BitBucketCloudMergeRef {}

property branch

branch: {
    name: string;
};

property commit

commit: {
    hash: string;
};

property repository

repository: BitBucketCloudRepo;

interface BitBucketCloudPagedResponse

interface BitBucketCloudPagedResponse<T> {}

property next

next: string | undefined;

property page

page: number;

property pagelen

pagelen: number;

property previous

previous: string | undefined;

property size

size: number;

property values

values: T[];

interface BitBucketCloudPRActivity

interface BitBucketCloudPRActivity {}

property comment

comment?: BitBucketCloudPRComment;

property pull_request

pull_request: {
    id: number;
    title: string;
};

interface BitBucketCloudPRComment

interface BitBucketCloudPRComment {}

property content

content: BitBucketCloudContent;

property created_on

created_on: string;

When the comment was created, in ISO 8601 format

property deleted

deleted: boolean;

property id

id: number;

property inline

inline?: {
    to: number | null;
    from: number;
    path: string;
};

property links

links: BitBucketCloudLinks<'self' | 'html'>;

property pullrequest

pullrequest: {
    id: number;
    links: BitBucketCloudLinks<'self' | 'html'>;
    title: string;
};

property type

type: string;

property updated_on

updated_on: string;

When the comment was updated, in ISO 8601 format

property user

user: BitBucketCloudUser;

interface BitBucketCloudPRDSL

interface BitBucketCloudPRDSL {}

property author

author: BitBucketCloudUser;

The creator of the PR

property created_on

created_on: string;

When the pr was created, in ISO 8601 format

property description

description: string;

The text describing the PR

property destination

destination: BitBucketCloudMergeRef;

The PR's destination

property id

id: number;

The PR's ID

property links

links: BitBucketCloudLinks<
    | 'decline'
    | 'commits'
    | 'self'
    | 'comments'
    | 'merge'
    | 'html'
    | 'activity'
    | 'diff'
    | 'approve'
    | 'statuses'
>;

Misc links for hypermedia conformance

property participants

participants: BitBucketCloudPRParticipant[];

People who have participated in the PR

property reviewers

reviewers: BitBucketCloudUser[];

People requested as reviewers

property source

source: BitBucketCloudMergeRef;

The PR's source, The repo Danger is running on

property state

state: 'OPEN' | 'MERGED' | 'DECLINED' | 'SUPERSEDED';

The pull request's current status.

property title

title: string;

Title of the pull request.

property updated_on

updated_on: string;

When the pr was updated, in ISO 8601 format

interface BitBucketCloudPRParticipant

interface BitBucketCloudPRParticipant {}

property approved

approved: boolean;

Did they approve of the PR?

property role

role: 'REVIEWER' | 'PARTICIPANT';

How did they contribute

property user

user: BitBucketCloudUser;

interface BitBucketCloudRepo

interface BitBucketCloudRepo {}

property full_name

full_name: string;

property name

name: string;

property uuid

uuid: string;

interface BitBucketCloudUser

interface BitBucketCloudUser {}

property account_id

account_id: string;

The acount id of the commit author

property display_name

display_name: string;

The display name of the commit author

property nickname

nickname: string;

The nick name of the commit author

property uuid

uuid: string;

The uuid of the commit author

interface BitBucketServerAPIDSL

interface BitBucketServerAPIDSL {}

method delete

delete: (path: string, headers: any, body: any) => Promise<any>;

Make a delete call against the bitbucket server API

method get

get: (path: string, headers: any, suppressErrors?: boolean) => Promise<any>;

Make a get call against the bitbucket server API

method getFileContents

getFileContents: (
    filePath: string,
    repoSlug?: string,
    refspec?: string
) => Promise<string>;

Gets the contents of a file from a repo (defaults to yours)

method post

post: (
    path: string,
    headers: any,
    body: any,
    suppressErrors?: boolean
) => Promise<any>;

Make a post call against the bitbucket server API

method put

put: (path: string, headers: any, body: any) => Promise<any>;

Make a put call against the bitbucket server API

interface BitBucketServerChangesValueAddCopyModifyDelete

interface BitBucketServerChangesValueAddCopyModifyDelete {}

property path

path: {
    toString: string;
};

property type

type: 'ADD' | 'COPY' | 'MODIFY' | 'DELETE' | 'UNKNOWN';

interface BitBucketServerChangesValueMove

interface BitBucketServerChangesValueMove {}

property path

path: {
    toString: string;
};

property srcPath

srcPath: {
    toString: string;
};

property type

type: 'MOVE';

interface BitBucketServerCommit

interface BitBucketServerCommit {}

A BitBucketServer specific implementation of a git commit.

property author

author: {
    /** The id of the commit author */
    name: string;
    /** The display name of the commit author */
    displayName: string;
    /** The email of the commit author */
    emailAddress: string;
};

The author of the commit, assumed to be the person who wrote the code.

property authorTimestamp

authorTimestamp: number;

The UNIX timestamp for when the commit was authored

property committer

committer: {
    /** The id of the commit committer */
    name: string;
    /** The display name of the commit committer */
    displayName: string;
    /** The email of the commit committer */
    emailAddress: string;
};

The author of the commit, assumed to be the person who committed/merged the code into a project.

property committerTimestamp

committerTimestamp: number;

When the commit was committed to the project

property displayId

displayId: string;

The shortened SHA for the commit

property id

id: string;

The SHA for the commit

property message

message: string;

The commit's message

property parents

parents: {
    /** The full SHA */
    id: string;
    /** The simplified sha */
    displayId: string;
}[];

The commit's parents

interface BitBucketServerDiff

interface BitBucketServerDiff {}

property destination

destination?: BitBucketServerFile;

The file reference when moved

property fromHash

fromHash: string;

Last SHA where this hunk was changed

property hunks

hunks: BitBucketServerHunk[];

A set of diff changes

property source

source?: BitBucketServerFile;

The original file reference

property toHash

toHash: string;

The commit SHA which changed this hunk

property truncated

truncated: boolean;

If the hunk is massive, then it will be truncated

property whitespace

whitespace: 'SHOW' | 'IGNORE_ALL';

The settings for the whitespace

interface BitBucketServerDSL

interface BitBucketServerDSL extends BitBucketServerJSONDSL {}

The BitBucketServer metadata for your PR

property api

api: BitBucketServerAPIDSL;

An authenticated API so you can extend danger's behavior.

interface BitBucketServerFile

interface BitBucketServerFile {}

property components

components: string[];

property name

name: string;

property parent

parent: string;

property toString

toString: string;

interface BitBucketServerHunk

interface BitBucketServerHunk {}

property destinationLine

destinationLine: number;

property destinationSpan

destinationSpan: number;

property segments

segments: BitBucketServerSegment[];

property sourceLine

sourceLine: number;

property sourceSpan

sourceSpan: number;

property truncated

truncated: boolean;

interface BitBucketServerJSONDSL

interface BitBucketServerJSONDSL {}

property activities

activities: BitBucketServerPRActivity[];

The activities such as OPENING, CLOSING, MERGING or UPDATING a pull request

property comments

comments: BitBucketServerPRActivity[];

The comments on the pull request

property commits

commits: BitBucketServerCommit[];

The commits associated with the pull request

property issues

issues: JIRAIssue[];

The related JIRA issues

property metadata

metadata: RepoMetaData;

The pull request and repository metadata

property pr

pr: BitBucketServerPRDSL;

The PR metadata

interface BitBucketServerLine

interface BitBucketServerLine {}

property commentIds

commentIds?: number[];

property conflictMarker

conflictMarker?: 'OURS';

property destination

destination: number;

property line

line: string;

property source

source: number;

property truncated

truncated: boolean;

interface BitBucketServerMergeRef

interface BitBucketServerMergeRef {}

property displayId

displayId: string;

property id

id: string;

property latestCommit

latestCommit: string;

property repository

repository: BitBucketServerRepo;

interface BitBucketServerPagedResponse

interface BitBucketServerPagedResponse<T> {}

property filter

filter: never | null;

property isLastPage

isLastPage: boolean;

property limit

limit: number;

property nextPageStart

nextPageStart: number | null;

property size

size: number;

property start

start: number;

property values

values: T;

interface BitBucketServerPRActivity

interface BitBucketServerPRActivity {}

property action

action: 'COMMENTED' | 'OPENED' | 'MERGED' | 'DECLINED' | 'UPDATED';

property comment

comment?: BitBucketServerPRComment;

property commentAction

commentAction?: 'ADDED' | 'UPDATED';

property commentAnchor

commentAnchor?: {
    diffType: 'COMMIT' | 'EFFECTIVE' | 'REQUIRED' | 'RANGE';
    line: number;
    lineType: 'CONTEXT' | 'ADDED' | 'REMOVED';
    fileType: 'FROM' | 'TO';
    fromHash: string;
    path: string;
    srcPath: string;
    toHash: string;
};

property createdDate

createdDate: number;

property id

id: number;

property user

user: BitBucketServerUser;

interface BitBucketServerPRComment

interface BitBucketServerPRComment {}

property author

author: BitBucketServerUser;

property comments

comments: BitBucketServerPRActivity[];

property createdDate

createdDate: number;

property id

id: number;

property parent

parent?: {
    id: number;
};

property permittedOperations

permittedOperations: {
    deletable: boolean;
    editable: boolean;
};

property text

text: string;

property updatedDate

updatedDate: number;

property version

version: number;

interface BitBucketServerPRDSL

interface BitBucketServerPRDSL {}

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 BitBucket Server send will still be inside the JS object.

property author

author: BitBucketServerPRParticipant & { role: 'AUTHOR' };

The creator of the PR

property closed

closed: boolean;

Is the PR closed?

property createdDate

createdDate: number;

Date PR created as number of milliseconds since the unix epoch

property description

description: string;

The text describing the PR

property fromRef

fromRef: BitBucketServerMergeRef;

The PR submitter's reference

property id

id: number;

The PR's ID

property links

links: BitBucketServerLinks<'self'>;

Misc links for hypermedia conformance

property locked

locked: boolean;

Was this PR locked?

property open

open: boolean;

Is the PR open?

property participants

participants: (BitBucketServerPRParticipant & { role: 'PARTICIPANT' })[];

People who have participated in the PR

property reviewers

reviewers: (BitBucketServerPRParticipant & { role: 'REVIEWER' })[];

People requested as reviewers

property state

state: 'OPEN' | 'MERGED' | 'DECLINED' | 'SUPERSEDED';

The pull request's current status.

property title

title: string;

Title of the pull request.

property toRef

toRef: BitBucketServerMergeRef;

The repo Danger is running on

property updatedDate

updatedDate: number;

Date PR updated as number of milliseconds since the unix epoch

property version

version: number;

The API version

interface BitBucketServerPRParticipant

interface BitBucketServerPRParticipant {}

property approved

approved: boolean;

Did they approve of the PR?

property role

role: 'AUTHOR' | 'REVIEWER' | 'PARTICIPANT';

How did they contribute

property status

status: 'APPROVED' | 'UNAPPROVED' | 'NEEDS_WORK';

Their review feedback

property user

user: BitBucketServerUser;

interface BitBucketServerRepo

interface BitBucketServerRepo {}

A BitBucket Server Repo

property forkable

forkable: boolean;

Can someone fork this repo?

property links

links: BitBucketServerLinks<'self' | 'clone'>;

Links for the projects

property name

name?: string;

The repo name

property project

project: {
    /** The project unique id */
    id: number;
    /** The project's human readable project key */
    key: string;
    /** Is the project publicly available */
    public: boolean;
    /** The name of the project */
    name: string;
    /** The project's type */
    type: string;
    /** Hyperlinks for the project */
    links: BitBucketServerLinks<'self'>;
};

An abstraction for grouping repos

property public

public: boolean;

Is the repo public?

property scmId

scmId: string;

The type of SCM tool, probably "git"

property slug

slug: string;

The slug for the repo

interface BitBucketServerSegment

interface BitBucketServerSegment {}

property lines

lines: BitBucketServerLine[];

property truncated

truncated: boolean;

property type

type: 'ADDED' | 'REMOVED' | 'CONTEXT';

interface BitBucketServerUser

interface BitBucketServerUser {}

A BitBucketServer user account.

property active

active: boolean;

Is the account active

property displayName

displayName: string;

The name to use when referencing the user

property emailAddress

emailAddress: string;

The email for the user

property id

id: number;

The unique user ID

property name

name: string;

The name of the user

property slug

slug: string;

The user's slug for URLs

property type

type: 'NORMAL' | 'SERVICE';

The type of a user, "NORMAL" being a typical user3

interface CliArgs

interface CliArgs {}

Describes the possible arguments that could be used when calling the CLI

property base

base: string;

The base reference used by danger PR (e.g. not master)

property dangerfile

dangerfile: string;

A custom path for the dangerfile (can also be a remote reference)

property externalCiProvider

externalCiProvider: string;

Used by danger-js o allow having a custom CI

property id

id: string;

So you can have many danger runs in one code review

property staging

staging?: boolean;

Use staged changes

property textOnly

textOnly: string;

Use SDTOUT instead of posting to the code review side

property verbose

verbose: string;

For debugging

interface DangerDSLJSONType

interface DangerDSLJSONType {}

The root of the Danger JSON DSL.

property bitbucket_cloud

bitbucket_cloud?: BitBucketCloudJSONDSL;

The data only version of BitBucket Cloud DSL

property bitbucket_server

bitbucket_server?: BitBucketServerJSONDSL;

The data only version of BitBucket Server DSL

property git

git: GitJSONDSL;

The data only version of Git DSL

property github

github?: GitHubDSL;

The data only version of GitHub DSL

property gitlab

gitlab?: GitLabDSL;

The data only version of GitLab DSL

property settings

settings: {
    /**
     * Saves each client re-implementing logic to grab these vars
     * for their API clients
     */
    github: {
        /** API token for the GitHub client to use */
        accessToken: string;
        /** Optional URL for enterprise GitHub */
        baseURL: string | undefined;
        /** Optional headers to add to a request */
        additionalHeaders: any;
    };
    /**
     * This is still a bit of a WIP, but this should
     * pass args/opts from the original CLI call through
     * to the process.
     */
    cliArgs: CliArgs;
};

Used in the Danger JSON DSL to pass metadata between processes. It will be undefined when used inside the Danger DSL

interface DangerDSLType

interface DangerDSLType {}

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

property bitbucket_cloud

readonly bitbucket_cloud: BitBucketCloudDSL;

The BitBucket Cloud metadata. This covers things like PR info, comments and reviews on the PR, commits, comments, and activities.
Strictly speaking, bitbucket_cloud is a nullable type, if you are not using BitBucket Cloud then it will be undefined. For the DSL convenience sake though, it is classed as non-nullable

property bitbucket_server

readonly bitbucket_server: BitBucketServerDSL;

The BitBucket Server metadata. This covers things like PR info, comments and reviews on the PR, related issues, commits, comments and activities.
Strictly speaking, bitbucket_server is a nullable type, if you are not using BitBucket Server then it will be undefined. For the DSL convenience sake though, it is classed as non-nullable

property git

readonly git: GitDSL;

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.

property github

readonly github: GitHubDSL;

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.
Strictly speaking, github is a nullable type, if you are not using GitHub then it will be undefined. For the DSL convenience sake though, it is classed as non-nullable
Provides an authenticated API so you can work directly with the GitHub API. This is an instance of the "@octokit/rest" npm module.
Finally, if running through Peril on an event other than a PR this is the full JSON from the webhook. [github-webhook-event-types](https://github.com/orta/github-webhook-event-types) has the full typings for those webhooks.

property gitlab

readonly gitlab: GitLabDSL;

The GitLab metadata. This covers things like PR info, comments and reviews on the MR, commits, comments and activities.
Strictly speaking, gitlab is a nullable type, if you are not using GitLab then it will be undefined. For the DSL convenience sake though, it is classed as non-nullable

property utils

readonly utils: DangerUtilsDSL;

Functions which are globally useful in most Dangerfiles. Right now, these functions are around making sentences of arrays, or for making a like of href links easily.

interface DangerInlineResults

interface DangerInlineResults {}

property fails

fails: string[];

Failed messages

property file

file: string;

Path to the file

property line

line: number;

Line in the file

property markdowns

markdowns: string[];

Markdown messages to attach at the bottom of the comment

property messages

messages: string[];

A set of messages to show inline

property warnings

warnings: string[];

Messages for info

interface DangerJSON

interface DangerJSON {}

The shape of the JSON passed between Danger and a subprocess. It's built to be expanded in the future.

property danger

danger: DangerDSLJSONType;

interface DangerResults

interface DangerResults {}

The representation of what running a Dangerfile generates. This needs to be passed between processes, so data only please.

property fails

fails: Violation[];

Failed messages

property github

github?: {
    /**
     * Markdown text which gets added as a summary in the first
     * page which you see when you click through to the PR results.
     *
     * https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/ */
    stepSummary?: string;
};

property markdowns

markdowns: Violation[];

Markdown messages to attach at the bottom of the comment

property messages

messages: Violation[];

A set of messages to show inline

property meta

meta?: {
    /** E.g. "dangerJS", or "Danger Swift" */
    runtimeName: string;
    /** e.g. "https://danger.systems/js" */
    runtimeHref: string;
};

Meta information about the runtime evaluation

property warnings

warnings: Violation[];

Messages for info

interface DangerRuntimeContainer

interface DangerRuntimeContainer extends DangerResults {}

property scheduled

scheduled?: any[];

Asynchronous functions to be run after parsing

interface DangerUtilsDSL

interface DangerUtilsDSL {}

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

method href

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

Creates a link using HTML.
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 tag is returned with href as its href and text value. Otherwise, if href and text are truthy, an tag is returned with the href and text inserted as expected.
Parameter href
The HTML link's destination.
Parameter text
The HTML link's text.
Returns
{string|null} The HTML tag.

method sentence

sentence: (array: string[]) => string;

Converts an array of strings into a sentence.
Parameter array
The array of strings.
Returns
{string} The sentence.

interface GitCommit

interface GitCommit {}

A platform agnostic reference to a Git commit

property author

author: GitCommitAuthor;

Who wrote the commit

property committer

committer: GitCommitAuthor;

Who deployed the commit

property message

message: string;

The commit message

property parents

parents?: string[];

SHAs for the commit's parents

property sha

sha: string;

The SHA for the commit

property tree

tree: any;

Potential parent commits, and other assorted metadata

property url

url: string;

Link to the commit

interface GitCommitAuthor

interface GitCommitAuthor {}

An author of a commit

property date

date: string;

ISO6801 date string

property email

email: string;

The authors email

property name

name: string;

The display name for the author

interface GitDSL

interface GitDSL extends GitJSONDSL {}

The git specific metadata for a PR

property base

base: string;

The git commit Danger is comparing from.

property fileMatch

fileMatch: Chainsmoker<GitMatchResult>;

A Chainsmoker object to help match paths as an elegant DSL. It lets you write a globbed string and then get booleans on whether there are matches within a certain part of the git DSL.
Use this to create an object which has booleans set on 4 keys modified, created, edited (created + modified) and deleted.
Example 1
const packageJSON = danger.git.fileMatch("package.json") const lockfile = danger.git.fileMatch("yarn.lock")
if (packageJSON.modified && !lockfile.modified) { warn("You might have forgotten to run yarn.") }
Example 2
const needsSchemaChange = danger.git.fileMatch("src/app/analytics/*.ts") const schema = danger.git.fileMatch("src/app/analytics/schema.ts")
if (needsSchemaChange.edited && !schema.modified) { fail("Changes to the analytics files need to edit update the schema.") }

property head

head: string;

The git commit Danger is comparing to.

method diffForFile

diffForFile: (filename: string) => Promise<TextDiff | null>;

Offers the diff for a specific file
Parameter filename
the path to the json file

method JSONDiffForFile

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

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.
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.
Parameter filename
the path to the json file

method JSONPatchForFile

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

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.
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 unwieldy for a Dangerfile.
Parameter filename
the path to the json file

method linesOfCode

linesOfCode: (pattern?: string) => Promise<number | null>;

Offers the overall lines of code added/removed in the diff
Parameter pattern
an option glob pattern to filer files that will considered for lines of code.

method structuredDiffForFile

structuredDiffForFile: (filename: string) => Promise<StructuredDiff | null>;

Offers the structured diff for a specific file
Parameter filename
the path to the json file

interface GitHubAPIPR

interface GitHubAPIPR {}

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

property number

number: number;

The PR number
Deprecated
use pull_number instead

property owner

owner: string;

The repo owner

property pull_number

pull_number: number;

The PR number

property repo

repo: string;

The repo name

interface GitHubCommit

interface GitHubCommit {}

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

property author

author: GitHubUser;

The GitHub user who wrote the code

property commit

commit: GitCommit;

The raw commit metadata

property committer

committer: GitHubUser;

The GitHub user who shipped the code

property parents

parents: any[];

An array of parent commit shas

property sha

sha: string;

The SHA for the commit

property url

url: string;

the url for the commit on GitHub

interface GitHubDSL

interface GitHubDSL extends GitHubJSONDSL {}

The GitHub metadata for your PR

property api

api: GitHub;

An authenticated API so you can extend danger's behavior by using the [GitHub v3 API](https://developer.github.com/v3/).
A set up instance of the "github" npm module. You can get the full [API here](https://octokit.github.io/node-github/).

property setSummaryMarkdown

setSummaryMarkdown: (markdown: string) => void;

Sets a markdown summary which shows on the overview page for the results of all steps in your CI job.
See: https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/

property utils

utils: GitHubUtilsDSL;

A scope for useful functions related to GitHub

interface GitHubIssue

interface GitHubIssue {}

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.
A GitHub Issue

property labels

labels: GitHubIssueLabel[];

The labels associated with this issue

interface GitHubIssueComment

interface GitHubIssueComment {}

property body

body: string;

Textual representation of comment

property id

id: string;

UUID for the comment

property user

user: GitHubUser;

The User who made the comment

interface GitHubIssueLabel

interface GitHubIssueLabel {}

property color

color: string;

The color associated with this label

property id

id: number;

The identifying number of this label

property name

name: string;

The name of the label

property url

url: string;

The URL that links to this label

interface GitHubJSONDSL

interface GitHubJSONDSL {}

property commits

commits: GitHubCommit[];

The github commit metadata for a code review session

property issue

issue: GitHubIssue;

The issue metadata for a code review session

property pr

pr: GitHubPRDSL;

The PR metadata for a code review session

property requested_reviewers

requested_reviewers: GitHubReviewers;

The people/teams requested to review this PR

property reviews

reviews: GitHubReview[];

The reviews left on this pull request

property thisPR

thisPR: GitHubAPIPR;

The PR metadata specifically formatted for using with the GitHub API client

interface GitHubMergeRef

interface GitHubMergeRef {}

property label

label: string;

The human display name for the merge reference, e.g. "artsy:master"

property ref

ref: string;

The reference point for the merge, e.g. "master"

property repo

repo: GitHubRepo;

The repo from whch the reference comes from

property sha

sha: string;

The reference point for the merge, e.g. "704dc55988c6996f69b6873c2424be7d1de67bbe"

property user

user: GitHubUser;

The user that owns the merge reference e.g. "artsy"

interface GitHubPRDSL

interface GitHubPRDSL {}

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.

property additions

additions: number;

The number of additional lines in the PR

property assignee

assignee: GitHubUser;

The User who is assigned the PR

property assignees

assignees: GitHubUser[];

The Users who are assigned to the PR

property author_association

author_association:
    | 'COLLABORATOR'
    | 'CONTRIBUTOR'
    | 'FIRST_TIMER'
    | 'FIRST_TIME_CONTRIBUTOR'
    | 'MEMBER'
    | 'NONE'
    | 'OWNER';

How does the PR author relate to this repo/org?

property base

base: GitHubMergeRef;

Merge reference for _this_ repo.

property body

body: string;

The markdown body message of the PR

property changed_files

changed_files: number;

The number of changed files in the PR

property closed_at

closed_at: string | null;

optional ISO6801 Date string for when PR was closed

property comments

comments: number;

The number of comments on the PR

property commits

commits: number;

The number of commits in the PR

property created_at

created_at: string;

ISO6801 Date string for when PR was created

property deletions

deletions: number;

The number of deleted lines in the PR

property draft

draft: boolean;

Is in draft state?

property head

head: GitHubMergeRef;

Merge reference for the _other_ repo.

property html_url

html_url: string;

The link back to this PR as user-facing

property locked

locked: boolean;

Has the PR been locked to contributors only?

property merged

merged: boolean;

Has the PR been merged yet?

property merged_at

merged_at: string | null;

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

property number

number: number;

The UUID for the PR

property review_comments

review_comments: number;

The number of review-specific comments on the PR

property state

state: 'closed' | 'open' | 'locked' | 'merged';

The state for the PR

property title

title: string;

The title of the PR

property updated_at

updated_at: string;

ISO6801 Date string for when PR was updated

property user

user: GitHubUser;

The User who submitted the PR

interface GitHubRepo

interface GitHubRepo {}

A GitHub Repo

property assignee

assignee: GitHubUser;

Is someone assigned to this PR?

property assignees

assignees: GitHubUser[];

Are there people assigned to this PR?

property description

description: string;

The textual description of the repo

property fork

fork: boolean;

Is the repo a fork?

property full_name

full_name: string;

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

property html_url

html_url: string;

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

property id

id: number;

Generic UUID

property name

name: string;

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

property owner

owner: GitHubUser;

The owner of the repo

property private

private: boolean;

Is the repo publicly accessible?

interface GitHubReview

interface GitHubReview {}

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

property body

body?: string;

If there is a review, the body of the review

property commit_id

commit_id?: string;

If there is a review, the commit ID this review was made on

property id

id?: number;

If there is a review, this provides the ID for it

property state

state?: 'APPROVED' | 'REQUEST_CHANGES' | 'COMMENT' | 'PENDING';

The state of the review APPROVED, REQUEST_CHANGES, COMMENT or PENDING

property user

user: GitHubUser;

The user requested to review, or the user who has completed the review

interface GitHubReviewers

interface GitHubReviewers {}

property teams

teams: any[];

Teams that have been requested

property users

users: GitHubUser[];

Users that have been requested

interface GitHubUser

interface GitHubUser {}

A GitHub user account.

property avatar_url

avatar_url: string;

The url for a users's image

property href

href: string;

The href for a users's page

property id

id: number;

Generic UUID

login: string;

The handle for the user/org

property type

type: 'User' | 'Organization' | 'Bot';

Whether the user is an org, or a user

interface GitHubUtilsDSL

interface GitHubUtilsDSL {}

Useful functions for GitHub related work

property createOrAddLabel

createOrAddLabel: (
    labelConfig: { name: string; color: string; description: string },
    repoConfig?: { owner: string; repo: string; id: number }
) => Promise<void>;

An API for creating, or setting a label to an issue. Usable from Peril by adding an additional param for settings about a repo.
Parameter labelConfig
The config for the label
Parameter Optional
: the config for the issue
Returns
{Promise} No return value.

property createOrUpdatePR

createOrUpdatePR: (
    config: {
        /** PR title */
        title: string;
        /** PR body */
        body: string;
        /** The danger in danger/danger-js - defaults to the PR base name if undefined */
        owner?: string;
        /** The danger-js in danger/danger-js - defaults to the PR base repo if undefined */
        repo?: string;
        /** A message for the commit */
        commitMessage: string;
        /** The name of the branch on the repo */
        newBranchName: string;
        /** Base branch for the new branch e.g. what should Danger create the new branch from */
        baseBranch: string;
    },
    fileMap: any
) => Promise<any>;

property createUpdatedIssueWithID

createUpdatedIssueWithID: (
    id: string,
    content: string,
    config: { title: string; open: boolean; owner: string; repo: string }
) => Promise<string>;

An API for creating, updating and closing an issue. Basically this is really useful for reporting back via a separate issue that you may want to keep up to date at all times.
Parameter id
The unique ID for the message to create, close
Parameter content
the content of the message
Parameter config
settings for the issue
Returns
{string} A HTML string of 's built as a sentence.

method fileContents

fileContents: (path: string, repoSlug?: string, ref?: string) => Promise<string>;

Downloads a file's contents via the GitHub API. You'll want to use this instead of fs.readFile when aiming to support working with Peril.
Parameter path
The path fo the file that exists
Parameter repoSlug
An optional reference to the repo's slug: e.g. danger/danger-js
Parameter ref
An optional reference to a branch/sha

method fileLinks

fileLinks: (
    paths: string[],
    useBasename?: boolean,
    repoSlug?: string,
    branch?: string
) => string;

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.
Parameter paths
A list of strings representing file paths
Parameter useBasename
Show either the file name, or the full path - defaults to just file name e.g. true.
Parameter repoSlug
An optional override for the repo slug, ex: "orta/ORStackView"
Parameter branch
An optional override for the branch, ex: "v3"
Returns
{string} A HTML string of 's built as a sentence.

interface GitJSONDSL

interface GitJSONDSL {}

The Git Related Metadata which is available inside the Danger DSL JSON
JSONDSL

property commits

readonly commits: GitCommit[];

The Git commit metadata

property created_files

readonly created_files: string[];

Newly created filepaths relative to the git root

property deleted_files

readonly deleted_files: string[];

Removed filepaths relative to the git root

property modified_files

readonly modified_files: string[];

Filepaths with changes relative to the git root

interface GitLabDSL

interface GitLabDSL extends GitLabJSONDSL {}

The GitLab metadata for your MR

property api

api: InstanceType<typeof Types.Gitlab>;

property utils

utils: {
    fileContents(path: string, repoSlug?: string, ref?: string): Promise<string>;
    addLabels(...labels: string[]): Promise<boolean>;
    removeLabels(...labels: string[]): Promise<boolean>;
};

interface GitLabJSONDSL

interface GitLabJSONDSL {}

property approvals

approvals: Types.MergeRequestLevelMergeRequestApprovalSchema;

Merge Request-level MR approvals Configuration

property commits

commits: Types.CommitSchema[];

All the individual commits in the merge request

property metadata

metadata: RepoMetaData;

Info about the repo

property mr

mr: Types.ExpandedMergeRequestSchema;

Info about the merge request

interface JIRAIssue

interface JIRAIssue {}

This is danger.bitbucket_server.issues It refers to the issues that are linked to the Pull Request.

property key

key: string;

The unique key for the issue e.g. JRA-11

property url

url: string;

The user-facing URL for that issue

interface JSONDiff

interface JSONDiff {}

A map of string keys to JSONDiffValue

index signature

[name: string]: JSONDiffValue;

interface JSONDiffValue

interface JSONDiffValue {}

All JSON diff values will be this shape

property added

added?: any[];

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

property after

after: any;

The value after the PR's applied changes

property before

before: any;

The value before the PR's applied changes

property removed

removed?: any[];

If both before & after are arrays, then you optionally get what is removed. Empty if no removed objects.

interface JSONPatch

interface JSONPatch {}

The results of running a JSON patch

property after

after: any;

The JSON in a file from the PR submitter

property before

before: any;

The JSON in a file at the PR merge base

property diff

diff: JSONPatchOperation[];

The set of operations to go from one JSON to another JSON

interface JSONPatchOperation

interface JSONPatchOperation {}

An individual operation inside an rfc6902 JSON Patch

property op

op: string;

An operation type

property path

path: string;

The JSON keypath which the operation applies on

property value

value: string;

The changes for applied

interface PerilDSL

interface PerilDSL {}

The available Peril interface, it is possible that this is not always up to date with true DSL in Peril, but I'll be giving it a good shot.

property data

data?: any;

When running a task, the data passed in when the task was originally scheduled, you can also get this as the first argument in a default function. Deprecated, use a default export function. I'll remove this sometime.

property env

env: any;

A set of key:value string based on ENV vars that have been set to be exposed to your Peril config

property runTask

runTask: (taskName: string, time: string, data: any) => void;

Allows you to schedule a task declared in your Peril config to run in a certain time-frame, e.g runTask("reminder_pr_merge", "in 2 days", { number: 2 }). For more details on how this works, see the Peril documentation.
Parameter taskName
the name found in your Peril config
Parameter time
the time interval (uses human-internal module)
Parameter data
data which will be passed through to the script

interface RepoMetaData

interface RepoMetaData {}

Key details about a repo

property pullRequestID

pullRequestID: string;

The ID for the pull/merge request "11"

property repoSlug

repoSlug: string;

A path like "artsy/eigen"

interface StructuredDiff

interface StructuredDiff {}

Git diff sliced into chunks

property chunks

chunks: File['chunks'];

Git diff chunks

property fromPath

fromPath: string | undefined;

The file path pre-change

interface TextDiff

interface TextDiff {}

All Text diff values will be this shape

property added

added: string;

A string containing just the added lines

property after

after: string;

The value after the PR's applied changes

property before

before: string;

The value before the PR's applied changes

property diff

diff: string;

A string containing the full set of changes

property removed

removed: string;

A string containing just the removed lines

interface Violation

interface Violation {}

The result of user doing warn, message or fail, built this way for expansion later.

property file

file?: string;

Optional path to the file

property icon

icon?: string;

Optional icon for table (Only valid for messages)

property line

line?: number;

Optional line in the file

property message

message: string;

The string representation

Type Aliases

type BitBucketCloudLinks

type BitBucketCloudLinks<Names extends string> = {
    [key in Names]: {
        href: string;
    };
};

type BitBucketServerChangesValue

type BitBucketServerChangesValue =
    | BitBucketServerChangesValueAddCopyModifyDelete
    | BitBucketServerChangesValueMove;

type BitBucketServerLinks

type BitBucketServerLinks<Names> = {
    [key in keyof Names]: {
        href: string;
        name?: string;
    }[];
};

type CallbackableFn

type CallbackableFn = (callback: (done: any) => void) => void;

A function with a callback function, which Danger wraps in a Promise

type Chainsmoker

type Chainsmoker<T> = (...patterns: Pattern[]) => MatchResult<T>;

A vendored copy of the Chainsmoker module on NPM

type GitMatchResult

type GitMatchResult = {
    /** Did any file paths match from the git modified list? */
    modified: any;
    /** Did any file paths match from the git created list? */
    created: any;
    /** Did any file paths match from the combination of the git modified and created list? */
    edited: any;
    /** Did any file paths match from the git deleted list? */
    deleted: any;
};

The shape of the Chainsmoker response

type KeyedPaths

type KeyedPaths<T> = {
    readonly [K in keyof T]: Path[];
};

type KeyedPatterns

type KeyedPatterns<T> = {
    readonly [K in keyof T]: Pattern[];
};

type MarkdownString

type MarkdownString = string;

type MatchResult

type MatchResult<T> = _MatchResult<T> & {
    /** Returns an object containing arrays of matched files instead of the usual boolean values. */
    getKeyedPaths(): KeyedPaths<T>;
};

type Path

type Path = string;

type Pattern

type Pattern = string;

type Scheduleable

type Scheduleable = Promise<any> | Promise<void> | CallbackableFn;

Types of things which Danger will schedule for you, it's recommended that you just throw in an async () => { [...] } function. Can also handle a function that has a single 'done' arg.

Package Files (1)

distribution/danger.d.ts

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/danger.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/danger)

HTML

<a href="https://www.jsdocs.io/package/danger"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 1 month ago.
Package analyzed in 8666 ms.
Missing or incorrect documentation? Open an issue for this package.

danger

Install

Overview

Index

Variables

Functions

Interfaces

Type Aliases

Variables

variable danger

variable peril

variable results

Functions

function fail

Parameter message

Parameter file

Parameter line

function markdown

Parameter message

Parameter file

Parameter line

function message

Parameter message

Parameter file

Parameter line

Parameter message

Parameter opts

Parameter

Parameter

Parameter

function schedule

Parameter asyncFunction

function warn

Parameter message

Parameter file

Parameter line

Interfaces

interface BitBucketCloudAPIDSL

method delete

method get

method getFileContents

method post

method put

interface BitBucketCloudCommit

property author

property date

property hash

property links

property message

property parents

interface BitBucketCloudContent

property html

property markup

property raw

property type

interface BitBucketCloudDSL

property api

interface BitBucketCloudJSONDSL

property activities

property comments

property commits

property metadata

property pr

interface BitBucketCloudMergeRef

property branch

property commit

property repository

interface BitBucketCloudPagedResponse

property next

property page

property pagelen

property previous

property size

property values

interface BitBucketCloudPRActivity

property comment

property pull_request

interface BitBucketCloudPRComment

property content

property created_on