Merge pull request #134 from danger/danger-utils-dsl

Add danger.utils DSL

changelog.md

@@ -2,6 +2,18 @@
 
 //  Add your own contribution below
 
+* Add `danger.utils` DSL, which includes `danger.utils.href()` and `danger.utils.sentence()` - macklinu
+
+  We were finding that a lot of Dangerfiles needed similar functions, so we've added a `utils` object
+  to offer functions that are going to be used across the board. If you can think of more 
+  functions you use, we'd love to add them. Ideally you shouldn't need to use anything but Danger + utils
+  to write your Dangerfiles.
+
+```js
+danger.utils.href("http://danger.systems", "Danger") // <a href="http://danger.systems">Danger</a>
+danger.utils.sentence(["A", "B", "C"]) // "A, B and C"
+```
+
 ### 0.12.1
 
 * Add support for [Drone](http://readme.drone.io) - gabro

source/dsl/DangerDSL.ts

@@ -1,5 +1,6 @@
 import { GitDSL } from "../dsl/GitDSL"
 import { GitHubDSL } from "../dsl/GitHubDSL"
+import { DangerUtilsDSL } from "./DangerUtilsDSL"
 
 /**
  *  The Danger DSL provides the metadata for introspection
@@ -16,14 +17,19 @@ export interface DangerDSLType {
    *  The GitHub metadata.
    */
   readonly github: Readonly<GitHubDSL>
+
+  /**
+   * Danger utils
+   */
+  readonly utils: Readonly<DangerUtilsDSL>
 }
 
 /* END FLOWTYPE EXPORT */
 
 export class DangerDSL {
   public readonly github: Readonly<GitHubDSL>
 
-  constructor(platformDSL: any, public readonly git: GitDSL) {
+  constructor(platformDSL: any, public readonly git: GitDSL, public readonly utils: DangerUtilsDSL) {
     // As GitLab etc support is added this will need to be changed
     this.github = platformDSL
   }

source/dsl/DangerUtilsDSL.ts

@@ -0,0 +1,28 @@
+/**
+ * The Danger Utils DSL contains utility functions
+ * that are specific to universal Danger use-cases.
+ */
+export interface DangerUtilsDSL {
+
+  /**
+   * Creates an HTML link.
+   *
+   * 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 {Array<string>} array The array of strings.
+   * @returns {string} The sentence.
+   */
+  sentence(array: Array<string>): string
+}

source/runner/DangerUtils.ts

@@ -0,0 +1,19 @@
+export function sentence(array: Array<string>): string {
+  if ((array || []).length === 0) {
+    return ""
+  }
+  if (array.length === 1) {
+    return array[0]
+  }
+  return array.slice(0, array.length - 1).join(", ") + " and " + array.pop()
+}
+
+export function href(href: string, text: string): string | null {
+  if (!href && !text) {
+    return null
+  }
+  if (!href && text) {
+    return text
+  }
+  return `<a href="${href}">${text || href}</a>`
+}

source/runner/Executor.ts

@@ -7,6 +7,7 @@ import { template as githubResultsTemplate } from "./templates/githubIssueTempla
 import { createDangerfileRuntimeEnvironment, runDangerfileEnvironment } from "./DangerfileRunner"
 import { DangerfileRuntimeEnv } from "./types"
 import * as debug from "debug"
+import { sentence, href } from "./DangerUtils"
 // This is still badly named, maybe it really should just be runner?
 
 export class Executor {
@@ -53,7 +54,8 @@ export class Executor {
   async dslForDanger(): Promise<DangerDSL> {
     const git = await this.platform.getReviewDiff()
     const platformDSL = await this.platform.getPlatformDSLRepresentation()
-    return new DangerDSL(platformDSL, git)
+    const utils = { sentence, href }
+    return new DangerDSL(platformDSL, git, utils)
   }
 
   /**

source/runner/_tests/DangerUtils.test.ts

@@ -0,0 +1,33 @@
+import { href, sentence } from "../DangerUtils"
+
+describe("sentence()", () => {
+  it("handles falsy input", () => {
+    expect(sentence(null)).toEqual("")
+  })
+  it("handles empty array", () => {
+    expect(sentence([])).toEqual("")
+  })
+  it("handles array with one item", () => {
+    expect(sentence(["Hello"])).toEqual("Hello")
+  })
+  it("handles array with multiple items", () => {
+    expect(sentence(["This", "that", "the other thing"]))
+      .toEqual("This, that and the other thing")
+  })
+})
+
+describe("href()", () => {
+  it("returns null when href and text are falsy", () => {
+    expect(href("", "")).toEqual(null)
+  })
+  it("returns just the text when the href is missing", () => {
+    expect(href("", "Some text")).toEqual("Some text")
+  })
+  it("returns <a> tag with href as text when text is missing", () => {
+    expect(href("/path/to/file", "")).toEqual(`<a href="/path/to/file">/path/to/file</a>`)
+  })
+  it("returns <a> tag for supplied href and text", () => {
+    expect(href("http://danger.systems", "Danger"))
+      .toEqual(`<a href="http://danger.systems">Danger</a>`)
+  })
+})