Merge pull request #48 from Financial-Times/adambraimbridge/pull-requests

Commands for GitHub pull requests

Author: Adam Braimbridge

.huskyrc.json

@@ -1,5 +1,6 @@
 {
-  "hooks": {
-    "pre-commit": "npm run lint"
-  }
+	"hooks": {
+		"pre-commit": "npm run lint",
+		"pre-push": "npm run test"
+	}
 }

README.md

@@ -44,6 +44,18 @@ const github = require("@financial-times/github")({
 });
 ```
 
-See [`examples/examples.js`](https://github.com/Financial-Times/github/blob/master/examples/examples.js) for a full set of usage examples.
+# Developers
 
-See [`src/lib/github.js`](https://github.com/Financial-Times/github/blob/master/src/lib/github.js) for all available methods.
+## Command hierarchy and directory structure
+
+This project follows the example provided in the Yargs documentation for command hierarchy and directory structure. 
+
+ - @see: https://github.com/yargs/yargs/blob/master/docs/advanced.md#commanddirdirectory-opts
+ - @see: [`src/commands`](https://github.com/Financial-Times/github/blob/master/src/commands/) for all available commands.
+
+## Conventions: CamelCase and under_scores
+
+All commands and variables are consistent with the Ocktokit and GitHub APIs documentation, respectively:
+
+ - https://octokit.github.io/rest.js/#api-Pulls <-- Instead of camelCaseFormat, we use hyphen-format. 
+ - https://developer.github.com/v3/pulls <-- Variables are under_score_format.

__mocks__/@octokit/fixtures/create.json

@@ -12,5 +12,6 @@ module.exports = {
 				outputName: "results.xml"
 			}
 		]
-	]
+	],
+	verbose: true,
 };

__mocks__/@octokit/fixtures/createCard.json

@@ -0,0 +1,90 @@
+/**
+ * These descriptions are exported so that they can be used to group global options in usage output.
+ */
+const descriptions = {
+	token: "GitHub personal access token (uses `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable by default). Generate one at https://github.com/settings/tokens.",
+	json: "Format command output as JSON string",
+}
+
+const withToken = yargs => yargs.option("token", {
+
+	// IMPORTANT: We use a function here so the token is not output on the command line.
+	default: () => process.env.GITHUB_PERSONAL_ACCESS_TOKEN,
+	describe: descriptions.token,
+	type: "string",
+	coerce: value => {
+		if (!value) {
+			throw new Error(
+				"Error: `--token` option is required as a valid GITHUB_PERSONAL_ACCESS_TOKEN environment variable does not exist"
+			)
+		}
+		return value
+	}
+})
+
+const withJson = yargs => yargs.option("json", {
+	describe: descriptions.json,
+	type: "boolean",
+})
+
+const withBase = yargs => yargs.option("base", {
+	describe: "Base branch",
+	type: "string",
+	default: "master",
+})
+
+const withOwner = yargs => yargs.option("owner", {
+	alias: "o",
+	describe: "Owner",
+	type: "string",
+	demandOption: true,
+})
+
+const withRepo = yargs => yargs.option("repo", {
+	alias: "r",
+	describe: "Repository",
+	type: "string",
+	demandOption: true,
+})
+
+const withNumber = yargs => yargs.option("number", {
+	alias: "n",
+	describe: "Number",
+	type: "integer",
+	demandOption: true,
+})
+
+const withReviewers = yargs => yargs.option("reviewers", {
+	describe: "Reviewers",
+	type: "string",
+})
+
+const withTeamReviewers = yargs => yargs.option("team_reviewers", {
+	describe: "Team reviewers",
+	type: "string",
+})
+
+const withBody = yargs => yargs.option("body", {
+	describe: "Path to pull request body",
+	type: "string",
+})
+
+const withTitle = yargs => yargs.option("title", {
+	alias: "t",
+	describe: "Pull request title",
+	type: "string",
+})
+
+module.exports = {
+	descriptions,
+	withToken,
+	withJson,
+	withBase,
+	withOwner,
+	withRepo,
+	withNumber,
+	withReviewers,
+	withTeamReviewers,
+	withBody,
+	withTitle,
+}

__mocks__/@octokit/fixtures/createColumn.json

@@ -0,0 +1,35 @@
+const Octokit = require('@octokit/rest')
+
+module.exports = async ({ personalAccessToken }) => {
+	if (!personalAccessToken) {
+		throw new Error(
+			'github tooling helper: Missing personalAccessToken option - https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/'
+		)
+	}
+
+	/**
+	* Return an authenticated instance of Octokit
+	*/
+	try {
+		return await new Octokit({
+			previews: [
+				/**
+				 * Access Projects API while it is under preview
+				 *
+				 * @see https://developer.github.com/v3/projects
+				 */
+				'inertia-preview',
+			],
+			/**
+			 * Authenticate GitHub API calls using GitHub personal access token
+			 *
+			 * @see https://github.com/octokit/rest.js#authentication
+			 */
+			auth: `token ${personalAccessToken}`,
+
+			// Todo: Allow emojis. @see https://developer.github.com/v3/pulls/review_requests/#create-a-review-request
+			// header: 'application / vnd.github.symmetra - preview + json',
+		})
+	}
+	catch (error) { throw new Error(error) }
+}

__mocks__/@octokit/fixtures/createForOrg.json

@@ -0,0 +1,23 @@
+/* eslint-disable no-console */
+
+/**
+ * Helper for formatting and printing GitHub resources.
+ *
+ * @param {object} options
+ * @param {string} options.json
+ * @param {object} options.resource
+ */
+module.exports = function printOutput({ json, resource, error }) {
+	if (error) {
+		console.log(`⚠️	Error response from GitHub. ${JSON.stringify(error.errors)}`)
+	}
+	else if (json === true) {
+		const jsonOutput = JSON.stringify({
+			type: "resource",
+			resource
+		});
+		console.log(jsonOutput);
+	} else {
+		console.log(resource.html_url || "OK");
+	}
+};

__mocks__/@octokit/rest.js

@@ -30,7 +30,8 @@
     "eslint-plugin-no-only-tests": "^2.1.0",
     "husky": "^1.3.1",
     "jest": "^24.1.0",
-    "jest-junit": "^6.3.0"
+    "jest-junit": "^6.3.0",
+    "nock": "^10.0.6"
   },
   "engines": {
     "node": "^8.15.1 || ^10.15.3"