Add support for Issues (#56)

Add support for Issues

Author: Adam Braimbridge

README.md

@@ -2,7 +2,7 @@
 
 ## A human-friendly<sup>1</sup> command line tool for the GitHub API.
 
-<sup>1</sup> It's script-friendly too. 
+<sup>1</sup> It's script-friendly too.
 
 ![image](https://user-images.githubusercontent.com/224547/57764890-42704180-76fc-11e9-9256-2be2037e2fdf.png)
 
@@ -59,77 +59,73 @@ ika --version
 ### Working with GitHub Projects
 
 ```bash
-ika add-pull-request [--column-url] [--pull-request-url]
+ika projects add [--column-url] [--url]
 
 # Add a pull request to a GitHub project column.
 ```
 
 ```bash
-ika close-project <github-url>
+ika projects close <github-url>
 
 # Set the state of an existing project board to `closed`.
 ```
 
 ```bash
-ika create-project <github-url> [--body]
+ika projects create <github-url> [--body]
 
 # Create a new project.
 ```
 
-@see: [`src/commands/projects/README.md`](https://github.com/Financial-Times/ika/blob/master/src/commands/projects/README.md) for more details.
-
 ### Working with GitHub Pull Requests
 
 ```bash
-ika close-pull-request <github-url>
+ika pulls close <github-url>
 
 # Set the state of an existing pull request to `closed`.
 ```
 
 ```bash
-ika create-comment <github-url> [--body]
+ika pulls create-comment <github-url> [--body]
 
 # Create a comment on an existing pull request.
 ```
 
 ```bash
-ika create-review-request <github-url> [reviewers|team-reviewers]
+ika pulls create-review-request <github-url> [reviewers|team-reviewers]
 
 # Request a review for a pull request.
 ```
 
 ```bash
-ika create-pull-request <github-url> [--base] [--body] [--title]
+ika pulls create <github-url> [--base] [--body] [--title]
 
 # Create a new pull request.
 ```
 
 ```bash
-ika delete-comment <github-url>
+ika pulls delete-comment <github-url>
 
 # Delete a comment on an existing pull request.
 ```
 
 ```bash
-ika delete-review-request <github-url> [reviewers|team-reviewers]
+ika pulls delete-review-request <github-url> [reviewers|team-reviewers]
 
 # Delete a review for a pull request.
 ```
 
 ```bash
-ika merge-pull-request <github-url> [--method]
+ika pulls merge <github-url> [--method]
 
 # Merge an existing pull request.
 ```
 
 ```bash
-ika open-pull-request <github-url>
+ika pulls open <github-url>
 
 # Set the state of an existing pull request to `open`.
 ```
 
-@see: [`src/commands/pulls/README.md`](https://github.com/Financial-Times/ika/blob/master/src/commands/pulls/README.md) for more details.
-
 ### Global Options
 
 ```bash
@@ -145,7 +141,7 @@ ika open-pull-request <github-url>
 # Generate one at https://github.com/settings/tokens
 ```
 
-> Note: You can omit the `--token` argument, because it will default to  `$GITHUB_PERSONAL_ACCESS_TOKEN`.
+> Note: You can omit the `--token` argument, because it will default to `$GITHUB_PERSONAL_ACCESS_TOKEN`.
 >
 > In that case you will need to export the token to your environment:
 

bin/ika.js

@@ -17,17 +17,19 @@ const baseOptions = flow([
 ])
 baseOptions(yargs)
 	.scriptName('ika')
+	.usage('$0 <command> <subcommand> [...options]')
 	/**
 	 * The --version argument only makes sense as an option for the main `ika` command.
 	 */
 	.command('[--version]', 'Show the version number.')
 	.hide('version')
+	.completion('completion', 'Output a generated script. To enable bash/zsh completions: \n 1. Install ika globally. \n 2. Add the script to your .bashrc or .bash_profile (or .zshrc for zsh).')
 	/**
 	 * Load our yargs command modules from a directory.
 	 *
 	 * @see https://github.com/yargs/yargs/blob/master/docs/advanced.md#commanddirdirectory-opts
 	 */
-	.commandDir(yargsCommandsDirectoryPath, { recurse: true })
+	.commandDir(yargsCommandsDirectoryPath)
 	/**
 	 * Maximize the width of yargs’ usage instructions.
 	 */

package.json

@@ -18,6 +18,7 @@
 	"license": "MIT",
 	"dependencies": {
 		"@adambraimbridge/prettierrc-2019-05": "^1.0.0",
+		"@octokit/plugin-throttling": "^2.6.0",
 		"@octokit/rest": "^16.16.3",
 		"lodash.flow": "^3.5.0",
 		"update-notifier": "^3.0.0",

src/commands/allowance.js

@@ -0,0 +1,24 @@
+/**
+ * @see: https://octokit.github.io/rest.js/#octokit-routes-rateLimit
+ */
+const printOutput = require('../lib/print-output')
+const authenticatedOctokit = require('../lib/octokit')
+
+const handler = async ({ token, json }) => {
+	try {
+		const octokit = await authenticatedOctokit({ personalAccessToken: token })
+		const result = await octokit.rateLimit.get()
+		Object.keys(result.data.resources).forEach(row => {
+			console.log(`${row} \n • Remaining = ${result.data.resources[row].remaining} / ${result.data.resources[row].limit} \n • Reset     = ${new Date(result.data.resources[row].reset * 1000)}\n`)
+		})
+		printOutput({ json, resource: result.data })
+	} catch (error) {
+		printOutput({ json, error })
+	}
+}
+
+module.exports = {
+	command: 'allowance',
+	desc: 'Display current GitHub API rate-limiting allowance.',
+	handler,
+}

src/commands/issues.js

@@ -0,0 +1,10 @@
+/**
+ * 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
+ */
+exports.command = 'issues <subcommand> [...options]'
+exports.desc = 'Manage GitHub issues.'
+exports.builder = function(yargs) {
+	return yargs.commandDir('issues')
+}
+exports.handler = function() {}

src/commands/issues/close.js

@@ -0,0 +1,55 @@
+/**
+ * @see: https://octokit.github.io/rest.js/#octokit-routes-issues-update
+ * There is no "closed" endpoint in the Octokit API. We use "update" with a `state` of "closed".
+ * const result = await octokit.issues.update({owner, repo, issue_number})
+ */
+const flow = require('lodash.flow')
+const commonYargs = require('../../lib/common-yargs')
+const printOutput = require('../../lib/print-output')
+const authenticatedOctokit = require('../../lib/octokit')
+
+/**
+ * yargs builder function.
+ *
+ * @param {import('yargs').Yargs} yargs - Instance of yargs
+ */
+const builder = yargs => {
+	const baseOptions = flow([
+		commonYargs.withGitHubUrl({
+			describe: 'The URL of the GitHub issue to close.',
+		}),
+	])
+	return baseOptions(yargs).example('github-url', 'Pattern: [https://][github.com]/[owner]/[repository]/issue/[number]')
+}
+
+/**
+ * Update an issue.
+ *
+ * @param {object} argv - argv parsed and filtered by yargs
+ * @param {string} argv.token
+ * @param {string} argv.json
+ * @param {object} argv.githubUrl - The GitHub url parsed in the withGitHubUrl() yarg option into appropriate properties, such as `owner` and `repo`.
+ */
+const handler = async ({ token, json, githubUrl }) => {
+	const { owner, repo, value } = githubUrl
+	const inputs = {
+		owner,
+		repo,
+		issue_number: value,
+		state: 'closed',
+	}
+	try {
+		const octokit = await authenticatedOctokit({ personalAccessToken: token })
+		const result = await octokit.issues.update(inputs)
+		printOutput({ json, resource: result })
+	} catch (error) {
+		printOutput({ json, error })
+	}
+}
+
+module.exports = {
+	command: 'close <github-url>',
+	desc: 'Set the state of an existing issue to `closed`',
+	builder,
+	handler,
+}

src/commands/issues/create.js

@@ -0,0 +1,65 @@
+/**
+ * @see: https://octokit.github.io/rest.js/#octokit-routes-issues-create
+ * const result = await octokit.issues.create({ owner, repo, title, [body], [assignees] })
+ */
+const flow = require('lodash.flow')
+const commonYargs = require('../../lib/common-yargs')
+const printOutput = require('../../lib/print-output')
+const authenticatedOctokit = require('../../lib/octokit')
+
+/**
+ * yargs builder function.
+ *
+ * @param {import('yargs').Yargs} yargs - Instance of yargs
+ */
+const builder = yargs => {
+	const baseOptions = flow([
+		commonYargs.withGitHubUrl({
+			describe: 'The URL of the GitHub repository to add an issue to.',
+		}),
+		commonYargs.withBody(),
+		commonYargs.withTitle({ demandOption: true }),
+	])
+	return baseOptions(yargs)
+		.option('assignees', {
+			type: 'array',
+			describe: 'GitHub user names to assign to the issue',
+		})
+		.example('github-url', 'Pattern: https://github.com/[owner]/[repository]')
+}
+
+/**
+ * Return the contents of a pull request body and create a pull request.
+ *
+ * @param {object} argv - argv parsed and filtered by yargs
+ * @param {string} argv.token
+ * @param {string} argv.json
+ * @param {string} argv.title
+ * @param {string} argv.bodyContent — This is created in the withBody() yarg option middleware.
+ * @param {array} argv.assignees — GitHub user names to assign to this issue.
+ * @param {object} argv.githubUrl - The GitHub url parsed in the withGitHubUrl() yarg option into appropriate properties, such as `owner` and `repo`.
+ */
+const handler = async ({ token, json, title, bodyContent, assignees, githubUrl }) => {
+	const { owner, repo } = githubUrl
+	const inputs = {
+		owner,
+		repo,
+		title,
+		body: bodyContent,
+		assignees,
+	}
+	try {
+		const octokit = await authenticatedOctokit({ personalAccessToken: token })
+		const result = await octokit.issues.create(inputs)
+		printOutput({ json, resource: result })
+	} catch (error) {
+		printOutput({ json, error })
+	}
+}
+
+module.exports = {
+	command: 'create <github-url> [--title] [--body] [--assignees]',
+	desc: 'Create a new issue',
+	builder,
+	handler,
+}

src/commands/issues/list-for-repo.js

@@ -0,0 +1,65 @@
+/**
+ * @see: https://octokit.github.io/rest.js/#octokit-routes-issues-list-for-repo
+ * List all issues assigned to the authenticated user across all visible repositories.
+ * const result = await octokit.issues.list([filter])
+ */
+const flow = require('lodash.flow')
+const commonYargs = require('../../lib/common-yargs')
+const printOutput = require('../../lib/print-output')
+const authenticatedOctokit = require('../../lib/octokit')
+
+/**
+ * yargs builder function.
+ *
+ * @param {import('yargs').Yargs} yargs - Instance of yargs
+ */
+const builder = yargs => {
+	const baseOptions = flow([
+		commonYargs.withGitHubUrl({
+			describe: 'The URL of the GitHub repository, the issues whence to glean.',
+		}),
+	])
+	return baseOptions(yargs).example('github-url', 'Pattern: https://github.com/[owner]/[repository]')
+}
+
+/**
+ * List all issues for a repository.
+ *
+ * @param {object} argv - argv parsed and filtered by yargs
+ * @param {string} argv.token
+ * @param {string} argv.json
+ */
+const handler = async ({ token, json, githubUrl }) => {
+	try {
+		const { owner, repo } = githubUrl
+		const octokit = await authenticatedOctokit({ personalAccessToken: token })
+
+		// @see https://github.com/octokit/rest.js/blob/master/docs/src/pages/api/00_usage.md#pagination
+		const request = octokit.issues.listForRepo.endpoint.merge({ owner, repo })
+		const result = await octokit.paginate(request)
+		if (json) {
+			printOutput({ json, resource: result })
+		} else {
+			result.forEach(issue => {
+				const { title, created_at, html_url, assignees } = issue
+				const assigneeString = assignees.map(user => user.login).join(', ')
+				console.log(
+					// Prettier-ignore
+					`\x1b[36m${created_at}\x1b[0m`,
+					title,
+					`\x1b[33m${assigneeString || 'unassigned'}\x1b[0m`,
+					`\x1b[2m${html_url}\x1b[0m`
+				)
+			})
+		}
+	} catch (error) {
+		printOutput({ json, error })
+	}
+}
+
+module.exports = {
+	command: 'list-for-repo <github-url>',
+	desc: 'List all issues in a repository.',
+	builder,
+	handler,
+}