danger
Version:
Unit tests for Team Culture
1,651 lines (1,467 loc) • 45.6 kB
TypeScript
//
// Autogenerated from scripts/danger-dts.ts
//
import { Octokit as GitHub } from "@octokit/rest"
import { Gitlab, Types } from "@gitbeaker/node"
import { Types as CoreTypes } from "@gitbeaker/core/dist"
import { File } from "parse-diff"
type MarkdownString = string
interface BitBucketCloudJSONDSL {
/** The pull request and repository metadata */
metadata: RepoMetaData
/** The PR metadata */
pr: BitBucketCloudPRDSL
/** The commits associated with the pull request */
commits: BitBucketCloudCommit[]
/** The comments on the pull request */
comments: BitBucketCloudPRComment[]
/** The activities such as OPENING, CLOSING, MERGING or UPDATING a pull request */
activities: BitBucketCloudPRActivity[]
}
interface BitBucketCloudAPIDSL {
/** Gets the contents of a file from a repo (defaults to yours) */
getFileContents(filePath: string, repoSlug?: string, refspec?: string): Promise<string>
/** Make a get call against the bitbucket server API */
get(path: string, headers: any, suppressErrors?: boolean): Promise<any>
/** Make a post call against the bitbucket server API */
post(path: string, headers: any, body: any, suppressErrors?: boolean): Promise<any>
/** Make a put call against the bitbucket server API */
put(path: string, headers: any, body: any): Promise<any>
/** Make a delete call against the bitbucket server API */
delete(path: string, headers: any, body: any): Promise<any>
}
interface BitBucketCloudDSL extends BitBucketCloudJSONDSL {
/**
* An authenticated API so you can extend danger's behavior.
*/
api: BitBucketCloudAPIDSL
}
interface BitBucketCloudPagedResponse<T> {
pagelen: number
size: number
page: number
next: string | undefined
previous: string | undefined
values: T[]
}
interface BitBucketCloudPRDSL {
/** The PR's ID */
id: number
/** Title of the pull request. */
title: string
/** The text describing the PR */
description: string
/** The pull request's current status. */
state: "OPEN" | "MERGED" | "DECLINED" | "SUPERSEDED"
/** When the pr was created, in ISO 8601 format */
created_on: string
/** When the pr was updated, in ISO 8601 format */
updated_on: string
/** The PR's source, The repo Danger is running on */
source: BitBucketCloudMergeRef
/** The PR's destination */
destination: BitBucketCloudMergeRef
/** The creator of the PR */
author: BitBucketCloudUser
/** People requested as reviewers */
reviewers: BitBucketCloudUser[]
/** People who have participated in the PR */
participants: BitBucketCloudPRParticipant[]
/** Misc links for hypermedia conformance */
links: BitBucketCloudLinks<
"decline" | "commits" | "self" | "comments" | "merge" | "html" | "activity" | "diff" | "approve" | "statuses"
>
}
interface BitBucketCloudMergeRef {
commit: {
hash: string
}
branch: {
name: string
}
repository: BitBucketCloudRepo
}
type BitBucketCloudLinks<Names extends string> = {
[key in Names]: {
href: string
}
}
interface BitBucketCloudPRParticipant {
/*The user who participated in this PR */
user: BitBucketCloudUser
/** How did they contribute */
role: "REVIEWER" | "PARTICIPANT"
/** Did they approve of the PR? */
approved: boolean
}
interface BitBucketCloudRepo {
name: string
full_name: string
uuid: string
}
interface BitBucketCloudUser {
/** The uuid of the commit author */
uuid: string
/** The display name of the commit author */
display_name: string
/** The nick name of the commit author */
nickname: string
/** The acount id of the commit author */
account_id: string
}
/** A BitBucketCloud specific implementation of a git commit. */
interface BitBucketCloudCommit {
/** The SHA for the commit */
hash: string
/** The author of the commit, assumed to be the person who wrote the code. */
author: {
/** Format: `Foo Bar <foo@bar.com>` */
raw: string
user: BitBucketCloudUser
}
/** When the commit was committed to the project, in ISO 8601 format */
date: string
/** The commit's message */
message: string
/** The commit's parents */
parents: {
/** The full SHA */
hash: string
}[]
/** The commit's links */
links: BitBucketCloudLinks<"html">
}
interface BitBucketCloudContent {
raw: string
markup: string
html: string
type: "rendered"
}
interface BitBucketCloudPRComment {
deleted: boolean
links: BitBucketCloudLinks<"self" | "html">
pullrequest: {
id: number
links: BitBucketCloudLinks<"self" | "html">
title: string
}
content: BitBucketCloudContent
/** When the comment was created, in ISO 8601 format */
created_on: string
user: BitBucketCloudUser
/** When the comment was updated, in ISO 8601 format */
updated_on: string
type: string
id: number
inline?: {
to: number | null
from: number
path: string
}
}
interface BitBucketCloudPRActivity {
comment?: BitBucketCloudPRComment
pull_request: {
id: number
title: string
}
}
// This is `danger.bitbucket_server` inside the JSON
interface BitBucketServerJSONDSL {
/** The pull request and repository metadata */
metadata: RepoMetaData
/** The related JIRA issues */
issues: JIRAIssue[]
/** The PR metadata */
pr: BitBucketServerPRDSL
/** The commits associated with the pull request */
commits: BitBucketServerCommit[]
/** The comments on the pull request */
comments: BitBucketServerPRActivity[]
/** The activities such as OPENING, CLOSING, MERGING or UPDATING a pull request */
activities: BitBucketServerPRActivity[]
}
interface BitBucketServerAPIDSL {
/** Gets the contents of a file from a repo (defaults to yours) */
getFileContents(filePath: string, repoSlug?: string, refspec?: string): Promise<string>
/** Make a get call against the bitbucket server API */
get(path: string, headers: any, suppressErrors?: boolean): Promise<any>
/** Make a post call against the bitbucket server API */
post(path: string, headers: any, body: any, suppressErrors?: boolean): Promise<any>
/** Make a put call against the bitbucket server API */
put(path: string, headers: any, body: any): Promise<any>
/** Make a delete call against the bitbucket server API */
delete(path: string, headers: any, body: any): Promise<any>
}
// This is `danger.bitbucket_server`
/** The BitBucketServer metadata for your PR */
interface BitBucketServerDSL extends BitBucketServerJSONDSL {
/**
* An authenticated API so you can extend danger's behavior.
*/
api: BitBucketServerAPIDSL
}
/**
* This is `danger.bitbucket_server.issues` It refers to the issues that are linked to the Pull Request.
*/
interface JIRAIssue {
/** The unique key for the issue e.g. JRA-11 */
key: string
/** The user-facing URL for that issue */
url: string
}
// This is `danger.bitbucket_server.pr`
//
// References:
// - https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Busername%7D/%7Brepo_slug%7D/pullrequests/%7Bpull_request_id%7D
// - https://docs.atlassian.com/bitbucket-server/javadoc/4.3.2/api/reference/classes.html
/**
* 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.
*/
interface BitBucketServerPRDSL {
/** The PR's ID */
id: number
/** The API version */
version: number
/** Title of the pull request. */
title: string
/** The text describing the PR */
description: string
/** The pull request's current status. */
state: "OPEN" | "MERGED" | "DECLINED" | "SUPERSEDED"
/** Is the PR open? */
open: boolean
/** Is the PR closed? */
closed: boolean
/** Date PR created as number of milliseconds since the unix epoch */
createdDate: number
/** Date PR updated as number of milliseconds since the unix epoch */
updatedDate: number
/** The PR submitter's reference */
fromRef: BitBucketServerMergeRef
/** The repo Danger is running on */
toRef: BitBucketServerMergeRef
/** Was this PR locked? */
locked: boolean
/** The creator of the PR */
author: BitBucketServerPRParticipant & { role: "AUTHOR" }
/** People requested as reviewers */
reviewers: (BitBucketServerPRParticipant & { role: "REVIEWER" })[]
/** People who have participated in the PR */
participants: (BitBucketServerPRParticipant & { role: "PARTICIPANT" })[]
/** Misc links for hypermedia conformance */
links: BitBucketServerLinks<"self">
}
// These are the individual subtypes of objects inside the larger DSL objects above.
/** A BitBucketServer specific implementation of a git commit. */
interface BitBucketServerCommit {
/** The SHA for the commit */
id: string
/** The shortened SHA for the commit */
displayId: string
/** The author of the commit, assumed to be the person who wrote the code. */
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 UNIX timestamp for when the commit was authored */
authorTimestamp: number
/** The author of the commit, assumed to be the person who committed/merged the code into a project. */
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
}
/** When the commit was committed to the project */
committerTimestamp: number
/** The commit's message */
message: string
/** The commit's parents */
parents: {
/** The full SHA */
id: string
/** The simplified sha */
displayId: string
}[]
}
interface BitBucketServerDiff {
/** The file reference when moved */
destination?: BitBucketServerFile
/** The original file reference */
source?: BitBucketServerFile
/** A set of diff changes */
hunks: BitBucketServerHunk[]
/** If the hunk is massive, then it will be truncated */
truncated: boolean
/** The commit SHA which changed this hunk */
toHash: string
/** Last SHA where this hunk was changed */
fromHash: string
/** The settings for the whitespace */
whitespace: "SHOW" | "IGNORE_ALL"
}
interface BitBucketServerFile {
components: string[]
name: string
parent: string
toString: string
}
interface BitBucketServerHunk {
destinationLine: number
destinationSpan: number
segments: BitBucketServerSegment[]
sourceLine: number
sourceSpan: number
truncated: boolean
}
interface BitBucketServerSegment {
lines: BitBucketServerLine[]
truncated: boolean
type: "ADDED" | "REMOVED" | "CONTEXT"
}
interface BitBucketServerLine {
source: number
destination: number
line: string
truncated: boolean
conflictMarker?: "OURS"
commentIds?: number[]
}
interface BitBucketServerPRParticipant {
/*The user for */
user: BitBucketServerUser
/** How did they contribute */
role: "AUTHOR" | "REVIEWER" | "PARTICIPANT"
/** Did they approve of the PR? */
approved: boolean
/** Their review feedback */
status: "APPROVED" | "UNAPPROVED" | "NEEDS_WORK"
}
/**
* A BitBucketServer user account.
*/
interface BitBucketServerUser {
/** The name of the user */
name: string
/** The email for the user */
emailAddress: string
/** The unique user ID */
id: number
/** The name to use when referencing the user */
displayName: string
/** Is the account active */
active: boolean
/** The user's slug for URLs */
slug: string
/** The type of a user, "NORMAL" being a typical user3 */
type: "NORMAL" | "SERVICE"
}
/**
* A BitBucket Server Repo
*/
interface BitBucketServerRepo {
/** The slug for the repo */
slug: string
/** The repo name */
name?: string
/** The type of SCM tool, probably "git" */
scmId: string
/** Is the repo public? */
public: boolean
/** Can someone fork this repo? */
forkable: boolean
/** Links for the projects */
links: BitBucketServerLinks<"self" | "clone">
/** An abstraction for grouping repos */
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">
}
}
type BitBucketServerLinks<Names> = {
[key in keyof Names]: {
href: string
name?: string
}[]
}
interface BitBucketServerMergeRef {
id: string
displayId: string
latestCommit: string
repository: BitBucketServerRepo
}
interface BitBucketServerPRActivity {
action: "COMMENTED" | "OPENED" | "MERGED" | "DECLINED" | "UPDATED"
comment?: BitBucketServerPRComment
commentAction?: "ADDED" | "UPDATED"
commentAnchor?: {
diffType: "COMMIT" | "EFFECTIVE" | "REQUIRED" | "RANGE"
line: number
lineType: "CONTEXT" | "ADDED" | "REMOVED"
fileType: "FROM" | "TO"
fromHash: string
path: string
srcPath: string
toHash: string
}
createdDate: number
id: number
user: BitBucketServerUser
}
interface BitBucketServerPRComment {
author: BitBucketServerUser
comments: BitBucketServerPRActivity[]
createdDate: number
updatedDate: number
id: number
permittedOperations: {
deletable: boolean
editable: boolean
}
text: string
version: number
parent?: {
id: number
}
}
interface BitBucketServerPagedResponse<T> {
size: number
limit: number
isLastPage: boolean
start: number
filter: never | null // TODO: remove never
nextPageStart: number | null
values: T
}
interface BitBucketServerChangesValueAddCopyModifyDelete {
type: "ADD" | "COPY" | "MODIFY" | "DELETE" | "UNKNOWN"
path: {
toString: string
}
}
interface BitBucketServerChangesValueMove {
type: "MOVE"
path: {
toString: string
}
srcPath: {
toString: string
}
}
// prettier-ignore
type BitBucketServerChangesValue = BitBucketServerChangesValueAddCopyModifyDelete | BitBucketServerChangesValueMove
/** A platform agnostic reference to a Git commit */
interface GitCommit {
/** The SHA for the commit */
sha: string
/** Who wrote the commit */
author: GitCommitAuthor
/** Who deployed the commit */
committer: GitCommitAuthor
/** The commit message */
message: string
/** Potential parent commits, and other assorted metadata */
tree: any
/** SHAs for the commit's parents */
parents?: string[]
/** Link to the commit */
url: string
}
/** An author of a commit */
interface GitCommitAuthor {
/** The display name for the author */
name: string
/** The authors email */
email: string
/** ISO6801 date string */
date: string
}
/**
* The shape of the JSON passed between Danger and a subprocess. It's built
* to be expanded in the future.
*/
interface DangerJSON {
danger: DangerDSLJSONType
}
/**
* 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.
*/
interface PerilDSL {
/**
* A set of key:value string based on ENV vars that have
* been set to be exposed to your Peril config
*/
env: any
/**
* 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.
* @param taskName the name found in your Peril config
* @param time the time interval (uses human-internal module)
* @param data data which will be passed through to the script
*/
runTask: (taskName: string, time: string, data: any) => void
/**
* 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.
*/
data?: any
}
/**
* The root of the Danger JSON DSL.
*/
interface DangerDSLJSONType {
/** The data only version of Git DSL */
git: GitJSONDSL
/** The data only version of GitHub DSL */
github?: GitHubDSL
/** The data only version of BitBucket Server DSL */
bitbucket_server?: BitBucketServerJSONDSL
/** The data only version of BitBucket Cloud DSL */
bitbucket_cloud?: BitBucketCloudJSONDSL
/** The data only version of GitLab DSL */
gitlab?: GitLabDSL
/**
* Used in the Danger JSON DSL to pass metadata between
* processes. It will be undefined when used inside the Danger DSL
*/
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
}
}
/**
* The Danger DSL provides the metadata for introspection
* in order to create your own rules.
*/
interface 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.
*/
readonly git: GitDSL
/**
* 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.
*/
readonly github: GitHubDSL
/**
* 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
*/
readonly bitbucket_server: BitBucketServerDSL
/**
* 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
*/
readonly bitbucket_cloud: BitBucketCloudDSL
/**
* 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
*/
readonly gitlab: GitLabDSL
/**
* 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.
*/
readonly utils: DangerUtilsDSL
}
/**
* The representation of what running a Dangerfile generates.
* This needs to be passed between processes, so data only please.
*/
interface DangerResults {
/**
* Failed messages
*/
fails: Violation[]
/**
* Messages for info
*/
warnings: Violation[]
/**
* A set of messages to show inline
*/
messages: Violation[]
/**
* Markdown messages to attach at the bottom of the comment
*/
markdowns: Violation[]
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
}
/** Meta information about the runtime evaluation */
meta?: {
/** E.g. "dangerJS", or "Danger Swift" */
runtimeName: string
/** e.g. "https://danger.systems/js" */
runtimeHref: string
}
}
interface DangerRuntimeContainer extends DangerResults {
/**
* Asynchronous functions to be run after parsing
*/
scheduled?: any[]
}
interface DangerInlineResults {
/**
* Path to the file
*/
file: string
/**
* Line in the file
*/
line: number
/**
* Failed messages
*/
fails: string[]
/**
* Messages for info
*/
warnings: string[]
/**
* A set of messages to show inline
*/
messages: string[]
/**
* Markdown messages to attach at the bottom of the comment
*/
markdowns: string[]
}
/**
* The Danger Utils DSL contains utility functions
* that are specific to universal Danger use-cases.
*/
interface DangerUtilsDSL {
/**
* 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 <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.
*
* @param {string} href The HTML link's destination.
* @param {string} text The HTML link's text.
* @returns {string|null} The HTML <a> tag.
*/
href(href: string, text: string): string | null
/**
* Converts an array of strings into a sentence.
*
* @param {string[]} array The array of strings.
* @returns {string} The sentence.
*/
sentence(array: string[]): string
}
/** All Text diff values will be this shape */
interface TextDiff {
/** The value before the PR's applied changes */
before: string
/** The value after the PR's applied changes */
after: string
/** A string containing the full set of changes */
diff: string
/** A string containing just the added lines */
added: string
/** A string containing just the removed lines */
removed: string
}
/** Git diff sliced into chunks */
interface StructuredDiff {
/** Git diff chunks */
chunks: File["chunks"]
}
/** The results of running a JSON patch */
interface JSONPatch {
/** The JSON in a file at the PR merge base */
before: any
/** The JSON in a file from the PR submitter */
after: any
/** The set of operations to go from one JSON to another JSON */
diff: JSONPatchOperation[]
}
/** An individual operation inside an rfc6902 JSON Patch */
interface JSONPatchOperation {
/** An operation type */
op: string
/** The JSON keypath which the operation applies on */
path: string
/** The changes for applied */
value: string
}
/** All JSON diff values will be this shape */
interface JSONDiffValue {
/** The value before the PR's applied changes */
before: any
/** The value after the PR's applied changes */
after: any
/** If both before & after are arrays, then you optionally get what is added. Empty if no additional objects. */
added?: any[]
/** If both before & after are arrays, then you optionally get what is removed. Empty if no removed objects. */
removed?: any[]
}
/** A map of string keys to JSONDiffValue */
interface JSONDiff {
[name: string]: JSONDiffValue
}
// This is `danger.git`
/**
*
* The Git Related Metadata which is available inside the Danger DSL JSON
*
* @namespace JSONDSL
*/
interface GitJSONDSL {
/**
* Filepaths with changes relative to the git root
*/
readonly modified_files: string[]
/**
* Newly created filepaths relative to the git root
*/
readonly created_files: string[]
/**
* Removed filepaths relative to the git root
*/
readonly deleted_files: string[]
/** The Git commit metadata */
readonly commits: GitCommit[]
}
/** The shape of the Chainsmoker response */
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 git specific metadata for a PR */
interface GitDSL extends GitJSONDSL {
/**
* The git commit Danger is comparing from.
*/
base: string
/**
* The git commit Danger is comparing to.
*/
head: string
/**
* 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
* 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
* 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.")
* }
*/
fileMatch: Chainsmoker<GitMatchResult>
/**
* Offers the diff for a specific file
*
* @param {string} filename the path to the json file
*/
diffForFile(filename: string): Promise<TextDiff | null>
/**
* Offers the structured diff for a specific file
*
* @param {string} filename the path to the json file
*/
structuredDiffForFile(filename: string): Promise<StructuredDiff | 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.
*
* @param {string} filename the path to the json file
*/
JSONPatchForFile(filename: string): Promise<JSONPatch | null>
/**
* 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.
*
* @param {string} filename the path to the json file
*/
JSONDiffForFile(filename: string): Promise<JSONDiff>
/**
* Offers the overall lines of code added/removed in the diff
*
* @param {string} pattern an option glob pattern to filer files that will considered for lines of code.
*/
linesOfCode(pattern?: string): Promise<number | null>
}
// This is `danger.github` inside the JSON
interface GitHubJSONDSL {
/** The issue metadata for a code review session */
issue: GitHubIssue
/** The PR metadata for a code review session */
pr: GitHubPRDSL
/** The PR metadata specifically formatted for using with the GitHub API client */
thisPR: GitHubAPIPR
/** The github commit metadata for a code review session */
commits: GitHubCommit[]
/** The reviews left on this pull request */
reviews: GitHubReview[]
/** The people/teams requested to review this PR */
requested_reviewers: GitHubReviewers
}
// This is `danger.github`
/** The GitHub metadata for your PR */
interface GitHubDSL extends GitHubJSONDSL {
/**
* 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/).
*/
api: GitHub
/** A scope for useful functions related to GitHub */
utils: GitHubUtilsDSL
/**
* 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/
*/
setSummaryMarkdown: (markdown: string) => void
}
/** Useful functions for GitHub related work */
interface 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.
*
* @param {string} paths A list of strings representing file paths
* @param {string} useBasename Show either the file name, or the full path - defaults to just file name e.g. true.
* @param {string} repoSlug An optional override for the repo slug, ex: "orta/ORStackView"
* @param {string} branch An optional override for the branch, ex: "v3"
* @returns {string} A HTML string of <a>'s built as a sentence.
*/
fileLinks(paths: string[], useBasename?: boolean, repoSlug?: string, branch?: string): 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.
*
* @param {string} path The path fo the file that exists
* @param {string} repoSlug An optional reference to the repo's slug: e.g. danger/danger-js
* @param {string} ref An optional reference to a branch/sha
*/
fileContents(path: string, repoSlug?: string, ref?: 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.
*
* @param {string} id The unique ID for the message to create, close
* @param {string} content the content of the message
* @param {any} config settings for the issue
* @returns {string} A HTML string of <a>'s built as a sentence.
*/
createUpdatedIssueWithID: (
id: string,
content: string,
config: { title: string; open: boolean; owner: string; repo: string }
) => Promise<string>
/**
* An API for creating, or setting a label to an issue. Usable from Peril
* by adding an additional param for settings about a repo.
*
* @param {obj} labelConfig The config for the label
* @param {obj | undefined} Optional: the config for the issue
* @returns {Promise<undefined>} No return value.
*/
createOrAddLabel: (
labelConfig: { name: string; color: string; description: string },
repoConfig?: { owner: string; repo: string; id: number }
) => Promise<void>
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>
}
/**
* 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
*/
interface GitHubIssue {
/**
* The labels associated with this issue
*/
labels: GitHubIssueLabel[]
}
// Subtypes specific to issues
interface GitHubIssueLabel {
/** The identifying number of this label */
id: number
/** The URL that links to this label */
url: string
/** The name of the label */
name: string
/** The color associated with this label */
color: string
}
interface GitHubIssueComment {
/**
* UUID for the comment
*/
id: string
/**
* The User who made the comment
*/
user: GitHubUser
/**
* Textual representation of comment
*/
body: string
}
// This is `danger.github.pr`
/**
* 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.
*/
interface GitHubPRDSL {
/**
* The UUID for the PR
*/
number: number
/**
* The state for the PR
*/
state: "closed" | "open" | "locked" | "merged"
/**
* Has the PR been locked to contributors only?
*/
locked: boolean
/**
* The title of the PR
*/
title: string
/**
* The markdown body message of the PR
*/
body: string
/**
* ISO6801 Date string for when PR was created
*/
created_at: string
/**
* ISO6801 Date string for when PR was updated
*/
updated_at: string
/**
* optional ISO6801 Date string for when PR was closed
*/
closed_at: string | null
/**
* Optional ISO6801 Date string for when PR was merged.
* Danger probably shouldn't be running in this state.
*/
merged_at: string | null
/**
* Merge reference for the _other_ repo.
*/
head: GitHubMergeRef
/**
* Merge reference for _this_ repo.
*/
base: GitHubMergeRef
/**
* The User who submitted the PR
*/
user: GitHubUser
/**
* The User who is assigned the PR
*/
assignee: GitHubUser
/**
* The Users who are assigned to the PR
*/
assignees: GitHubUser[]
/**
* Is in draft state?
*/
draft: boolean
/**
* Has the PR been merged yet?
*/
merged: boolean
/**
* The number of comments on the PR
*/
comments: number
/**
* The number of review-specific comments on the PR
*/
review_comments: number
/**
* The number of commits in the PR
*/
commits: number
/**
* The number of additional lines in the PR
*/
additions: number
/**
* The number of deleted lines in the PR
*/
deletions: number
/**
* The number of changed files in the PR
*/
changed_files: number
/**
* The link back to this PR as user-facing
*/
html_url: string
/** How does the PR author relate to this repo/org? */
author_association:
| "COLLABORATOR"
| "CONTRIBUTOR"
| "FIRST_TIMER"
| "FIRST_TIME_CONTRIBUTOR"
| "MEMBER"
| "NONE"
| "OWNER"
}
// These are the individual subtypes of objects inside the larger DSL objects above.
/** A GitHub specific implementation of a git commit, it has GitHub user names instead of an email. */
interface GitHubCommit {
/** The raw commit metadata */
commit: GitCommit
/** The SHA for the commit */
sha: string
/** the url for the commit on GitHub */
url: string
/** The GitHub user who wrote the code */
author: GitHubUser
/** The GitHub user who shipped the code */
committer: GitHubUser
/** An array of parent commit shas */
parents: any[]
}
/**
* A GitHub user account.
*/
interface 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" | "Bot"
/**
* The url for a users's image
*/
avatar_url: string
/**
* The href for a users's page
*/
href: string
}
/**
* A GitHub Repo
*/
interface GitHubRepo {
/**
* Generic UUID
*/
id: number
/**
* The name of the repo, e.g. "Danger-JS"
*/
name: string
/**
* The full name of the owner + repo, e.g. "Danger/Danger-JS"
*/
full_name: string
/**
* The owner of the repo
*/
owner: GitHubUser
/**
* Is the repo publicly accessible?
*/
private: boolean
/**
* The textual description of the repo
*/
description: string
/**
* Is the repo a fork?
*/
fork: boolean
/**
* Is someone assigned to this PR?
*/
assignee: GitHubUser
/**
* Are there people assigned to this PR?
*/
assignees: GitHubUser[]
/**
* The root web URL for the repo, e.g. https://github.com/artsy/emission
*/
html_url: string
}
interface GitHubMergeRef {
/**
* The human display name for the merge reference, e.g. "artsy:master"
*/
label: string
/**
* The reference point for the merge, e.g. "master"
*/
ref: string
/**
* The reference point for the merge, e.g. "704dc55988c6996f69b6873c2424be7d1de67bbe"
*/
sha: string
/**
* The user that owns the merge reference e.g. "artsy"
*/
user: GitHubUser
/**
* The repo from whch the reference comes from
*/
repo: GitHubRepo
}
/**
* 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
* @export
* @interface GitHubReview
*/
interface GitHubReview {
/**
* The user requested to review, or the user who has completed the review
*/
user: GitHubUser
/**
* If there is a review, this provides the ID for it
*/
id?: number
/**
* 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
/**
* The state of the review
* APPROVED, REQUEST_CHANGES, COMMENT or PENDING
*/
state?: "APPROVED" | "REQUEST_CHANGES" | "COMMENT" | "PENDING"
}
/** Provides the current PR in an easily used way for params in `github.api` calls */
interface GitHubAPIPR {
/** The repo owner */
owner: string
/** The repo name */
repo: string
/**
* The PR number
* @deprecated use `pull_number` instead
*/
number: number
/** The PR number */
pull_number: number
}
interface GitHubReviewers {
/** Users that have been requested */
users: GitHubUser[]
/** Teams that have been requested */
teams: any[]
}
// getPlatformReviewDSLRepresentation
interface GitLabJSONDSL {
/** Info about the repo */
metadata: RepoMetaData
/** Info about the merge request */
mr: CoreTypes.ExpandedMergeRequestSchema
/** All the individual commits in the merge request */
commits: Types.CommitSchema[]
/** Merge Request-level MR approvals Configuration */
approvals: Types.MergeRequestLevelMergeRequestApprovalSchema
}
// danger.gitlab
/** The GitLab metadata for your MR */
interface GitLabDSL extends GitLabJSONDSL {
utils: {
fileContents(path: string, repoSlug?: string, ref?: string): Promise<string>
addLabels(...labels: string[]): Promise<boolean>
removeLabels(...labels: string[]): Promise<boolean>
}
api: InstanceType<typeof Gitlab>
}
/** Key details about a repo */
interface RepoMetaData {
/** A path like "artsy/eigen" */
repoSlug: string
/** The ID for the pull/merge request "11" */
pullRequestID: string
}
/**
* The result of user doing warn, message or fail, built this way for
* expansion later.
*/
interface Violation {
/** The string representation */
message: string
/** Optional path to the file */
file?: string
/** Optional line in the file */
line?: number
/** Optional icon for table (Only valid for messages) */
icon?: string
}
/**
* Describes the possible arguments that
* could be used when calling the CLI
*/
interface CliArgs {
/** The base reference used by danger PR (e.g. not master) */
base: string
/** For debugging */
verbose: string
/** Used by danger-js o allow having a custom CI */
externalCiProvider: string
/** Use SDTOUT instead of posting to the code review side */
textOnly: string
/** A custom path for the dangerfile (can also be a remote reference) */
dangerfile: string
/** So you can have many danger runs in one code review */
id: string
/** Use staged changes */
staging?: boolean
}
// NOTE: if add something new here, you need to change dslGenerator.ts
/** A function with a callback function, which Danger wraps in a Promise */
type CallbackableFn = (callback: (done: any) => void) => void
/**
* 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.
*/
type Scheduleable = Promise<any> | Promise<void> | CallbackableFn
/**
* 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.
*
* @param {Function} asyncFunction the function to run asynchronously
*/
declare function schedule(asyncFunction: Scheduleable): void
/**
* Highlights critical issues. Message is shown inside a HTML table.
*
* @param {MarkdownString} message the String to output
* @param {string | undefined} file a file which this message should be attached to
* @param {number | undefined} line the line which this message should be attached to
*/
declare function fail(message: MarkdownString, file?: string, line?: number): void
/**
* Highlights low-priority issues. Message is shown inside a HTML table.
*
* @param {MarkdownString} message the String to output
* @param {string | undefined} file a file which this message should be attached to
* @param {number | undefined} line the line which this message should be attached to
*/
declare function warn(message: MarkdownString, file?: string, line?: number): void
/**
* Adds a message to the Danger table, the only difference between this
* and warn is the emoji which shows in the table.
*
* @param {MarkdownString} message the String to output
* @param {string | undefined} file a file which this message should be attached to
* @param {number | undefined} line the line which this message should be attached to
*/
declare function message(message: MarkdownString, file?: string, line?: number): void
/**
* 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
*
* @param {MarkdownString} message the String to output
* @param {{file?: string, line?: string, icon?: MarkdownString}} [opts]
* @param opts.file a file which this message should be attached to
* @param opts.line the line which this message should be attached to
* @param opts.icon icon string or image to show in table, take care not to break table formatting
*/
declare function message(message: MarkdownString, opts?: { file?: string; line?: number; icon?: MarkdownString }): void
/**
* Adds raw markdown into the Danger comment, under the table
*
* @param {MarkdownString} message the String to output
* @param {string | undefined} file a file which this message should be attached to
* @param {number | undefined} line the line which this message should be attached to
*/
declare function markdown(message: MarkdownString, file?: string, line?: number): void
/**
* The root Danger object. This contains all of the metadata you
* will be looking for in order to generate useful rules.
*/
declare const danger: DangerDSLType
/**
* When Peril is running your Dangerfile, the Danger DSL is
* extended with additional options.
*/
declare const peril: PerilDSL
/**
* The current results of a Danger run, this can be useful if you
* are wanting to introspect on whether a build has already failed.
*/
declare const results: DangerRuntimeContainer
export declare type Pattern = string
export declare type Path = string
export declare type KeyedPatterns<T> = {
readonly [K in keyof T]: Pattern[]
}
export declare type KeyedPaths<T> = {
readonly [K in keyof T]: Path[]
}
export declare type _MatchResult<T> = {
readonly [K in keyof T]: boolean
}
export declare type MatchResult<T> = _MatchResult<T> & {
/** Returns an object containing arrays of matched files instead of the usual boolean values. */
getKeyedPaths(): KeyedPaths<T>
}
/** A vendored copy of the Chainsmoker module on NPM */
export declare type Chainsmoker<T> = (...patterns: Pattern[]) => MatchResult<T>