Set up JSDoc strings for the code (#24)

* Add eslint-plugin-jsdoc and fix ESLint plugin config

* Fix all the "strict" eslint errors

* Add JSDoc strings for all the checkers

* Create a typedef for more accurate docs

* Split typedefs out to their own module for global reference

* Add documentation for the membership config loading

* Add documentation for the fixers

* Document the documentation! <inception gong>

Author: tarkatronic

.eslintrc

@@ -2,11 +2,14 @@
   "root": true,
   "extends": [
     "godaddy",
-    "plugin:mocha/recommended"
+    "plugin:jsdoc/recommended",
+    "plugin:mocha/recommended",
+    "plugin:node/recommended"
   ],
   "plugins": [
-    "eslint-plugin-mocha",
-    "eslint-plugin-node"
+    "jsdoc",
+    "mocha",
+    "node"
   ],
   "env": {
     "node": true

CHANGELOG.md

@@ -1,6 +1,7 @@
 # `orglinter`
 
 - Fixed #16 - New users were causing an error in findPromotions
+- Fixed #20 - Added full JSDoc coverage across the code
 
 ## 0.1.0
 

bin/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 /* eslint-disable no-console, no-process-env, max-statements */
+'use strict';
 
 require('dotenv').config();
 const path = require('path');

package-lock.json

@@ -28,6 +28,7 @@
     "assume": "^2.3.0",
     "eslint": "^7.15.0",
     "eslint-config-godaddy": "^4.0.1",
+    "eslint-plugin-jsdoc": "^31.6.1",
     "eslint-plugin-mocha": "^6.3.0",
     "eslint-plugin-node": "^11.1.0",
     "mocha": "^8.2.1",

package.json

@@ -1,17 +1,44 @@
 /* eslint-disable no-console */
+'use strict';
 
+const typedefs = require('./typedefs');
+
+/**
+ * Find users who currently belong to the organization, but not who are not
+ * expected by config.
+ *
+ * @param {string[]} configured - An array of usernames expected to exist in the org
+ * @param {string[]} retrieved - An array of usernames actually belong to the org currently
+ * @returns {string[]} An array of usernames which are not expected to belong to the org
+ */
 function findUndocumentedMembers(configured, retrieved) {
   const undocumented = retrieved.filter(member => !configured.includes(member));
   console.log(`${undocumented.length} undocumented memberships found: `, undocumented);
   return undocumented;
 }
 
+/**
+ * Find users who are expected by config, but who do not (yet) belong to the
+ * organization.
+ *
+ * @param {string[]} configured - An array of usernames expected to exist in the org
+ * @param {string[]} retrieved - An array of usernames actually belong to the org currently
+ * @returns {string[]} An array of usernames which are expected to belong to the org
+ */
 function findNewMembers(configured, retrieved) {
   const newMembers = configured.filter(member => !retrieved.includes(member));
   console.log(`${newMembers.length} new memberships requested: `, newMembers);
   return newMembers;
 }
 
+/**
+ * Find users who are currently admins of the org, but should not be, according
+ * to config.
+ *
+ * @param {object.<string, string>} configured - Configured usernames and their associated roles
+ * @param {typedefs.MemberSet} retrieved - User list retrieved from GitHub
+ * @returns {string[]} An array of usernames who are admins, but should not be
+ */
 function findDemotions(configured, retrieved) {
   const demotions = Object.keys(retrieved).filter(
     (member) => retrieved[member].role === 'ADMIN' && configured[member] === 'MEMBER'
@@ -20,6 +47,13 @@ function findDemotions(configured, retrieved) {
   return demotions;
 }
 
+/**
+ * Find users who are currently regular members of the org, but are configured as admins
+ *
+ * @param {object.<string, string>} configured - Configured usernames and their associated roles
+ * @param {typedefs.MemberSet} retrieved - User list retrieved from GitHub
+ * @returns {string[]} An array of usernames who are not admins, but should be
+ */
 function findPromotions(configured, retrieved) {
   const promotions = Object.keys(configured).filter(
     (member) => configured[member] === 'ADMIN' && retrieved[member] && retrieved[member].role === 'MEMBER'
@@ -28,12 +62,24 @@ function findPromotions(configured, retrieved) {
   return promotions;
 }
 
+/**
+ * Find org members who do not have two-factor authentication enabled
+ *
+ * @param {typedefs.MemberSet} members - User list retrieved from GitHub
+ * @returns {string[]} An array of usernames who are 2FA violators.
+ */
 function validateTwoFactor(members) {
   const violators = Object.keys(members).filter((member) => members[member].twoFactorAuth === false);
   console.log(`${violators.length} two factor auth violators found: `, violators);
   return violators;
 }
 
+/**
+ * Ensure that the org's current settings match those expected by the config
+ *
+ * @param {object.<string, *>} organization - The full collection of org settings collected from GitHub
+ * @param {object.<string, *>} config - The full collection of org settings expected by config
+ */
 function validateOrgSettings(organization, config) {
   let failed = false;
   for (const key of Object.keys(config)) {

src/lib/checkers.js

@@ -1,6 +1,18 @@
 /* eslint-disable no-console */
+'use strict';
+
 const { request } = require('@octokit/request');
 
+/**
+ * Invite a user to join an org
+ *
+ * @param {object} invitation - The details of the user invitation to be sent
+ * @param {string} invitation.username - The username to be invited
+ * @param {string} invitation.organization - The login name of the org where the user will be invited
+ * @param {string} invitation.token - A personal access token for interacting with the GitHub API
+ * @param {string} [invitation.role=member] - The role to invite the user as; "admin" or "member"
+ * @param {boolean} [invitation.dryRun=false] - If true, don't actually execute this operation
+ */
 async function inviteUser({ username, organization, token, role = 'member', dryRun = false }) {
   console.log(`Setting ${username} up as a(n) ${role} for ${organization}.`);
   if (dryRun) return;
@@ -20,6 +32,15 @@ async function inviteUser({ username, organization, token, role = 'member', dryR
   }
 }
 
+/**
+ * Remove a user from an org
+ *
+ * @param {object} removal - The details of the user removal to be initiated
+ * @param {string} removal.username - The username to be removed from the org
+ * @param {string} removal.organization - The login name of the org to remove the user from
+ * @param {string} removal.token - A personal access token for interacting with the GitHub API
+ * @param {boolean} removal.dryRun - If true, don't actally execute this operation
+ */
 async function removeMember({ username, organization, token, dryRun = false }) {
   console.log(`Removing ${username} from ${organization}.`);
   if (dryRun === true) return;
@@ -38,13 +59,31 @@ async function removeMember({ username, organization, token, dryRun = false }) {
   }
 }
 
+/**
+ * Promote a user from member to admin of an org
+ *
+ * @param {object} promotion - The details of the user promotion to be sent
+ * @param {string} promotion.username - The username to be promoted
+ * @param {string} promotion.organization - The login name of the org to promote the user in
+ * @param {string} promotion.token - A personal access token for interacting with the GitHub API
+ * @param {boolean} promotion.dryRun - If true, don't actally execute this operation
+ */
 async function promoteMember({ username, organization, token, dryRun = false }) {
   console.log(`Promoting ${username} to admin in ${organization}.`);
   if (dryRun) return;
   // Do the thing!
   await inviteUser({ username, organization, token, role: 'admin' });
 }
 
+/**
+ * Demote a user from admin to member of an org
+ *
+ * @param {object} demotion - The details of the user demotion to be sent
+ * @param {string} demotion.username - The username to be demoted
+ * @param {string} demotion.organization - The login name of the org to demote the user in
+ * @param {string} demotion.token - A personal access token for interacting with the GitHub API
+ * @param {boolean} demotion.dryRun - If true, don't actally execute this operation
+ */
 async function demoteMember({ username, organization, token, dryRun = false }) {
   console.log(`Demoting ${username} to member in ${organization}.`);
   if (dryRun) return;