Add topics management (#58)

Add topics management

Author: Tak Tran

README.md

@@ -4,23 +4,26 @@
 
 <sup>1</sup> It's script-friendly too.
 
-![image](https://user-images.githubusercontent.com/224547/58557351-1a153680-8216-11e9-9ebc-f25471405ea3.png)
+![asari command](https://user-images.githubusercontent.com/79451/59847137-986a8180-9359-11e9-84b9-ac60e1b205fa.png)
 
 > Above: Use `npx asari` in your shell to manage your work in GitHub.
 
 "Asari" (あさり) is [Japanese for "clam"](https://translate.google.com/#view=home&op=translate&sl=en&tl=ja&text=clam). Like a clam, `asari` is happiest when it's inside a shell.
 
 🐚 `asari` lets you work with GitHub from your command line, and is delicious when lightly fried with garlic and spices.
 
-![image](https://user-images.githubusercontent.com/224547/58558164-010d8500-8218-11e9-9279-9b93307989a7.png)
+![asari command line tool help](https://user-images.githubusercontent.com/79451/59781793-7965e400-92b4-11e9-9646-bfc60a9927a2.png)
 
 _Above: Running `npx asari` from your command line shows you the top level of options and commands._
 
-![image](https://user-images.githubusercontent.com/224547/58558212-213d4400-8218-11e9-8b46-42be9ea9d0e9.png)
+![asari issues command help](https://user-images.githubusercontent.com/224547/58558212-213d4400-8218-11e9-8b46-42be9ea9d0e9.png)
 
-![image](https://user-images.githubusercontent.com/224547/58558194-15518200-8218-11e9-8d48-0832558413ad.png)
+![asari projects command help](https://user-images.githubusercontent.com/224547/58558194-15518200-8218-11e9-8d48-0832558413ad.png)
+
+![asari pulls command help](https://user-images.githubusercontent.com/224547/58558179-0c60b080-8218-11e9-8e17-d5823b55c5ad.png)
+
+![asari repos command help](https://user-images.githubusercontent.com/79451/59847162-aa4c2480-9359-11e9-9807-61a1c572bc69.png)
 
-![image](https://user-images.githubusercontent.com/224547/58558179-0c60b080-8218-11e9-8e17-d5823b55c5ad.png)
 
 _Above: Running `npx asari <command>` shows you options for working with GitHub [issues](#working-with-github-issues), [projects](#working-with-github-projects) and [pull requests](#working-with-github-pull-requests)._
 
@@ -182,6 +185,26 @@ npx asari pulls open <github-url>
 # Set the state of an existing pull request to `open`.
 ```
 
+### Working with GitHub Repositories
+
+```bash
+npx asari repos list-topics <github-url>
+
+# List all topics.
+```
+
+```bash
+npx asari repos <add-topics|remove-topics> <github-url> --topic new-app
+
+# Add/Remove a topic
+
+npx asari repos <add-topics|remove-topics> <github-url> --topic new-app --topic good-one
+npx asari repos <add-topics|remove-topics> <github-url> --topics new-app,good-one
+npx asari repos <add-topics|remove-topics> <github-url> --topics "new-app,  good-one"
+
+# Add/Remove multiple topics
+```
+
 ### Global Options
 
 ```bash

package.json

@@ -20,7 +20,11 @@
 		"@adambraimbridge/prettierrc-2019-05": "^1.0.0",
 		"@octokit/plugin-throttling": "^2.6.0",
 		"@octokit/rest": "^16.16.3",
+		"lodash.flatmap": "^4.5.0",
 		"lodash.flow": "^3.5.0",
+		"lodash.isequal": "^4.5.0",
+		"lodash.uniq": "^4.5.0",
+		"lodash.without": "^4.4.0",
 		"update-notifier": "^3.0.0",
 		"yargs": "^13.2.1"
 	},

src/commands/repos.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 = 'repos <subcommand> [...options]'
+exports.desc = 'Manage GitHub repositories'
+exports.builder = function(yargs) {
+	return yargs.commandDir('repos')
+}
+exports.handler = function() {}

src/commands/repos/add-topics.js

@@ -0,0 +1,56 @@
+/**
+ * @see: https://octokit.github.io/rest.js/#octokit-routes-repos-replace-topics
+ * Add topics to a repository.
+ * const result = await octokit.repos.replaceTopics()
+ */
+const flow = require('lodash.flow')
+const { withGitHubUrl, withTopics } = require('../../lib/common-yargs')
+const printOutput = require('../../lib/print-output')
+const { addTopics } = require('../../lib/topics')
+
+/**
+ * yargs builder function.
+ *
+ * @param {import('yargs').Yargs} yargs - Instance of yargs
+ */
+const builder = yargs => {
+	const baseOptions = flow([
+		withGitHubUrl({
+			describe: 'The URL of the GitHub repository to list the topics of.',
+		}),
+		withTopics({
+			required: true,
+		}),
+	])
+	return baseOptions(yargs).example('github-url', 'Pattern: https://github.com/[owner]/[repository]')
+}
+
+/**
+ * Add topics to a repository.
+ *
+ * @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`.
+ * @param {array} argv.topics - The topics to add
+ */
+const handler = async ({ token, json, githubUrl, topics: topicsToAdd }) => {
+	try {
+		const topics = await addTopics({ githubUrl, token, topics: topicsToAdd })
+		if (json) {
+			printOutput({ json, resource: topics })
+		} else {
+			const output = topics.join('\n')
+			console.log(output)
+		}
+	} catch (error) {
+		printOutput({ json, error })
+	}
+}
+
+module.exports = {
+	command: 'add-topics <github-url>',
+	desc: 'Add topics to a repository.',
+	builder,
+	handler,
+}

src/commands/repos/list-topics.js

@@ -0,0 +1,53 @@
+/**
+ * @see: https://octokit.github.io/rest.js/#octokit-routes-repos-list-topics
+ * List all topics of a repository.
+ * const result = await octokit.repos.listTopics()
+ */
+const flow = require('lodash.flow')
+const commonYargs = require('../../lib/common-yargs')
+const printOutput = require('../../lib/print-output')
+const { getTopics } = require('../../lib/topics')
+
+/**
+ * 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 list the topics of.',
+		}),
+	])
+	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
+ * @param {object} argv.githubUrl - The GitHub url parsed in the withGitHubUrl() yarg option into appropriate properties, such as `owner` and `repo`.
+ */
+const handler = async args => {
+	const { token, json, githubUrl } = args
+	try {
+		const topics = await getTopics({ githubUrl, token })
+		if (json) {
+			printOutput({ json, resource: topics })
+		} else {
+			const output = topics.join('\n')
+			console.log(output)
+		}
+	} catch (error) {
+		printOutput({ json, error })
+	}
+}
+
+module.exports = {
+	command: 'list-topics <github-url>',
+	desc: 'List all topics of a repository.',
+	builder,
+	handler,
+}

src/commands/repos/remove-topics.js

@@ -0,0 +1,56 @@
+/**
+ * @see: https://octokit.github.io/rest.js/#octokit-routes-repos-replace-topics
+ * Remove topics from a repository.
+ * const result = await octokit.repos.replaceTopics()
+ */
+const flow = require('lodash.flow')
+const { withGitHubUrl, withTopics } = require('../../lib/common-yargs')
+const printOutput = require('../../lib/print-output')
+const { removeTopics } = require('../../lib/topics')
+
+/**
+ * yargs builder function.
+ *
+ * @param {import('yargs').Yargs} yargs - Instance of yargs
+ */
+const builder = yargs => {
+	const baseOptions = flow([
+		withGitHubUrl({
+			describe: 'The URL of the GitHub repository to list the topics of.',
+		}),
+		withTopics({
+			required: true,
+		}),
+	])
+	return baseOptions(yargs).example('github-url', 'Pattern: https://github.com/[owner]/[repository]')
+}
+
+/**
+ * Remove topics from a repository.
+ *
+ * @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`.
+ * @param {array} argv.topics - The topics to remove
+ */
+const handler = async ({ token, json, githubUrl, topics: topicsToRemove }) => {
+	try {
+		const topics = await removeTopics({ githubUrl, token, topics: topicsToRemove })
+		if (json) {
+			printOutput({ json, resource: topics })
+		} else {
+			const output = topics.join('\n')
+			console.log(output)
+		}
+	} catch (error) {
+		printOutput({ json, error })
+	}
+}
+
+module.exports = {
+	command: 'remove-topics <github-url>',
+	desc: 'Remove topics from a repository.',
+	builder,
+	handler,
+}

src/lib/common-yargs.js

@@ -1,5 +1,6 @@
 const fs = require('fs')
 const parseGitHubURL = require('./parse-github-url')
+const convertToFlattenedArrayOfValues = require('./convert-to-flattened-array-of-values')
 
 const withToken = options => yargs =>
 	yargs
@@ -179,6 +180,22 @@ const withGitHubUrl = options => yargs => {
 	)
 }
 
+const withTopics = options => yargs => {
+	return yargs
+		.option(
+			'topics',
+			Object.assign(
+				{
+					alias: ['topic'],
+					type: 'string',
+					describe: 'GitHub topics to add. To add more than one, add multiple options or a comma separated list',
+				},
+				options
+			)
+		)
+		.coerce('topic', convertToFlattenedArrayOfValues)
+}
+
 module.exports = {
 	withToken,
 	withJson,
@@ -188,4 +205,5 @@ module.exports = {
 	withReviewers,
 	withTeamReviewers,
 	withGitHubUrl,
+	withTopics,
 }

src/lib/convert-to-flattened-array-of-values.js

@@ -0,0 +1,18 @@
+const flatMap = require('lodash.flatmap')
+
+const expandCommaSeparatedValues = array => flatMap(array, (item = '') => item.split(','))
+
+/**
+ * Converts strings, strings of comma separated values and arrays of these
+ * into a flattened array of values
+ *
+ * @param {string|array} input - The input string or array of values
+ * @return {array} Array of values
+ */
+const convertToFlattenedArrayOfValues = input => {
+	const values = Array.isArray(input) ? input : [input]
+
+	return expandCommaSeparatedValues(values).map(value => value.trim())
+}
+
+module.exports = convertToFlattenedArrayOfValues

src/lib/octokit.js

@@ -20,6 +20,12 @@ module.exports = async ({ personalAccessToken }) => {
 				 * @see https://developer.github.com/v3/projects
 				 */
 				'inertia-preview',
+				/**
+				 * Access Topics API while it is under preview
+				 *
+				 * @see https://developer.github.com/v3/repos/#list-all-topics-for-a-repository
+				 */
+				`mercy-preview`,
 			],
 			/**
 			 * Authenticate GitHub API calls using GitHub personal access token

src/lib/topics.js

@@ -0,0 +1,54 @@
+const authenticatedOctokit = require('./octokit')
+const uniq = require('lodash.uniq')
+const isEqual = require('lodash.isequal')
+const without = require('lodash.without')
+
+const getTopics = async ({ githubUrl, token }) => {
+	const { owner, repo } = githubUrl
+	const octokit = await authenticatedOctokit({ personalAccessToken: token })
+
+	const request = octokit.repos.listTopics({ owner, repo })
+	const { data: { names: topics = [] } = {} } = await request
+
+	return topics
+}
+
+const addTopics = async ({ githubUrl, token, topics: newTopics }) => {
+	const initialTopics = await getTopics({ githubUrl, token })
+	const { owner, repo } = githubUrl
+
+	const octokit = await authenticatedOctokit({ personalAccessToken: token })
+	const topics = uniq(initialTopics.concat(newTopics))
+
+	if (isEqual(initialTopics, topics)) {
+		return initialTopics
+	}
+
+	const request = octokit.repos.replaceTopics({ owner, repo, names: topics })
+	const { data: { names: allTopics = [] } = {} } = await request
+
+	return allTopics
+}
+
+const removeTopics = async ({ githubUrl, token, topics: topicsToRemove }) => {
+	const initialTopics = await getTopics({ githubUrl, token })
+	const { owner, repo } = githubUrl
+
+	const octokit = await authenticatedOctokit({ personalAccessToken: token })
+	const topics = without(initialTopics, ...topicsToRemove)
+
+	if (isEqual(initialTopics, topics)) {
+		return initialTopics
+	}
+
+	const request = octokit.repos.replaceTopics({ owner, repo, names: topics })
+	const { data: { names: allTopics = [] } = {} } = await request
+
+	return allTopics
+}
+
+module.exports = {
+	getTopics,
+	addTopics,
+	removeTopics,
+}