More docs

source/ci_source/ci_source.ts

@@ -1,14 +1,6 @@
 /** A json object that represents the outer ENV */
 export type Env = any
 
-/** Key details about a repo */
-export interface RepoMetaData {
-  /** A path like "artsy/eigen" */
-  repoSlug: string
-  /** The ID for the pull/merge request "11" */
-  pullRequestID: string
-}
-
 /** The shape of an object that represents an individual CI */
 export interface CISource {
   /** The project name, mainly for showing errors */

source/ci_source/ci_source_helpers.ts

@@ -1,11 +1,12 @@
-import { Env, RepoMetaData } from "./ci_source"
+import { Env } from "./ci_source"
 import { GitHubAPI } from "../platforms/github/GitHubAPI"
 import { GitHubPRDSL } from "../dsl/GitHubDSL"
 import * as find from "lodash.find"
 import {
   BitBucketServerAPI,
   bitbucketServerRepoCredentialsFromEnv,
 } from "../platforms/bitbucket_server/BitBucketServerAPI"
+import { RepoMetaData } from "../dsl/BitBucketServerDSL"
 
 /**
  * Validates that all ENV keys exist and have a length

source/danger.d.ts

@@ -6,6 +6,15 @@ import * as GitHub from "@octokit/rest"
 
 declare module "danger" {
   type MarkdownString = string
+
+  /** Key details about a repo */
+  interface RepoMetaData {
+    /** A path like "artsy/eigen" */
+    repoSlug: string
+    /** The ID for the pull/merge request "11" */
+    pullRequestID: string
+  }
+
   // This is `danger.bitbucket_server` inside the JSON
 
   interface BitBucketServerJSONDSL {
@@ -32,20 +41,22 @@ declare module "danger" {
    * 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.
-   *
-   * 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
    */
 
   interface BitBucketServerPRDSL {
@@ -55,7 +66,7 @@ declare module "danger" {
     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"
@@ -102,7 +113,7 @@ declare module "danger" {
     }
     /** The UNIX timestamp for when the commit was authored */
     authorTimestamp: number
-    /** The author of the commit, assumed to be the person who commit the code into a project. */
+    /** The author of the commit, assumed to be the person who commited/merged the code into a project. */
     committer: {
       /** The id of the commit committer */
       name: string
@@ -223,7 +234,7 @@ declare module "danger" {
     project: {
       /** The project unique id */
       id: number
-      /** The project's human readbale project key */
+      /** The project's human readable project key */
       key: string
       /** Is the project publicly available */
       public: boolean
@@ -410,11 +421,16 @@ declare module "danger" {
      *  module.
      *
      *  Finally, if running through Peril on an event other than a PR
-     *  this is the full JSON from the webhook. You can find the full
-     *  typings for those webhooks [at github-webhook-event-types](https://github.com/orta/github-webhook-event-types).
+     *  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.
+     */
     readonly bitbucket_server?: BitBucketServerDSL
 
     /**

source/dsl/BitBucketServerDSL.ts

@@ -1,4 +1,10 @@
-import { RepoMetaData } from "../ci_source/ci_source"
+/** Key details about a repo */
+export interface RepoMetaData {
+  /** A path like "artsy/eigen" */
+  repoSlug: string
+  /** The ID for the pull/merge request "11" */
+  pullRequestID: string
+}
 
 // This is `danger.bitbucket_server` inside the JSON
 
@@ -26,20 +32,22 @@ export interface BitBucketServerDSL extends BitBucketServerJSONDSL {}
  * This is `danger.bitbucket_server.issues` It refers to the issues that are linked to the Pull Request.
  */
 export 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.
- *
- * 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
  */
 
 export interface BitBucketServerPRDSL {
@@ -49,7 +57,7 @@ export interface BitBucketServerPRDSL {
   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"
@@ -96,7 +104,7 @@ export interface BitBucketServerCommit {
   }
   /** The UNIX timestamp for when the commit was authored */
   authorTimestamp: number
-  /** The author of the commit, assumed to be the person who commit the code into a project. */
+  /** The author of the commit, assumed to be the person who commited/merged the code into a project. */
   committer: {
     /** The id of the commit committer */
     name: string
@@ -217,7 +225,7 @@ export interface BitBucketServerRepo {
   project: {
     /** The project unique id */
     id: number
-    /** The project's human readbale project key */
+    /** The project's human readable project key */
     key: string
     /** Is the project publicly available */
     public: boolean

source/dsl/DangerDSL.ts

@@ -101,11 +101,16 @@ export interface DangerDSLType {
    *  module.
    *
    *  Finally, if running through Peril on an event other than a PR
-   *  this is the full JSON from the webhook. You can find the full
-   *  typings for those webhooks [at github-webhook-event-types](https://github.com/orta/github-webhook-event-types).
+   *  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.
+   */
   readonly bitbucket_server?: BitBucketServerDSL
 
   /**

source/platforms/_tests/_bitbucket_server.test.ts

@@ -45,7 +45,7 @@ import { BitBucketServerAPI } from "../bitbucket_server/BitBucketServerAPI"
 import { GitCommit } from "../../dsl/Commit"
 import { FakeCI } from "../../ci_source/providers/Fake"
 import * as os from "os"
-import { RepoMetaData } from "../../ci_source/ci_source"
+import { RepoMetaData } from "../../dsl/BitBucketServerDSL"
 
 const EOL = os.EOL
 

source/platforms/bitbucket_server/BitBucketServerAPI.ts

@@ -9,9 +9,10 @@ import {
   JIRAIssue,
   BitBucketServerPRActivity,
   BitBucketServerDiff,
+  RepoMetaData,
 } from "../../dsl/BitBucketServerDSL"
 
-import { RepoMetaData, Env } from "../../ci_source/ci_source"
+import { Env } from "../../ci_source/ci_source"
 import { dangerSignaturePostfix, dangerIDToString } from "../../runner/templates/bitbucketServerTemplate"
 import { api as fetch } from "../../api/fetch"
 

source/platforms/bitbucket_server/BitBucketServerGit.ts

@@ -1,5 +1,10 @@
 import { GitDSL, GitJSONDSL } from "../../dsl/GitDSL"
-import { BitBucketServerCommit, BitBucketServerDSL, BitBucketServerDiff } from "../../dsl/BitBucketServerDSL"
+import {
+  BitBucketServerCommit,
+  BitBucketServerDSL,
+  BitBucketServerDiff,
+  RepoMetaData,
+} from "../../dsl/BitBucketServerDSL"
 import { GitCommit } from "../../dsl/Commit"
 
 import { BitBucketServerAPI } from "../bitbucket_server/BitBucketServerAPI"
@@ -8,7 +13,6 @@ import { GitJSONToGitDSLConfig, gitJSONToGitDSL, GitStructuredDiff } from "../gi
 
 import * as debug from "debug"
 import { EOL } from "os"
-import { RepoMetaData } from "../../ci_source/ci_source"
 const d = debug("danger:BitBucketServerGit")
 
 /**

source/platforms/github/GitHubAPI.ts

@@ -6,9 +6,9 @@ import * as v from "voca"
 
 import { GitHubPRDSL, GitHubUser } from "../../dsl/GitHubDSL"
 
-import { RepoMetaData } from "../../ci_source/ci_source"
 import { dangerSignaturePostfix, dangerIDToString } from "../../runner/templates/githubIssueTemplate"
 import { api as fetch } from "../../api/fetch"
+import { RepoMetaData } from "../../dsl/BitBucketServerDSL"
 
 // The Handle the API specific parts of the github