Updated comments, added exports for secret consts

src/helpers/SecretReader.ts

@@ -15,8 +15,8 @@ import { getLogger, isNodeErr } from './logger';
 import fs from 'fs';
 import { Logger } from 'winston';
 
-const DEFAULT_FILE_ENCODING: string = 'utf-8';
-const DEFAULT_SECRET_LOCATION: string = '/run/secrets/';
+export const DEFAULT_FILE_ENCODING: string = 'utf-8';
+export const DEFAULT_SECRET_LOCATION: string = '/run/secrets/';
 
 export interface SecretReaderConfig {
   root?: string;

src/scripts/gl/AxiosRequester.ts

+/**
+ * Original source: https://github.com/jdalrymple/gitbeaker/blob/6a3292b03342326a98b595a70ab26eb12ddb7ba4/packages/node/src/GotRequester.ts
+ * 
+ * Source modified to reduce rewrite where possible to implement a layer using axios which is our
+ * known+used HTTP wrapper impl. Changes include mapping Got params to axios params, and removing the 
+ * `delay` package dependency as there is a more typescript-y way to do it. 
+ */
+
 import axios from 'axios';
 import { decamelizeKeys } from 'xcase';
 import {

src/scripts/gl/GitlabSync.ts

@@ -63,6 +63,9 @@ let args = yargs(process.argv)
   .epilog('Copyright 2019 Eclipse Foundation inc.').argv;
 run();
 
+/**
+ * runs the sync process using the CLI args as configuration items to pass to the sync runner.
+ */
 async function run() {
   const argv = await args;
   await new GitlabSyncRunner({

src/scripts/gl/GitlabSyncRunner.ts

@@ -270,7 +270,16 @@ export class GitlabSyncRunner {
     }
   }
 
-  async removeAdditionalUsers(expectedUsers: Record<string, EclipseUser>, group: GroupSchema, ...projectIDs: string[]) {
+  /**
+   * Removes users not tracked in the expectedUsers map from the passed group. Project IDs are used to look up bot user
+   * account names as they are exempt from being removed as they are used for CI ops.
+   *
+   * @param expectedUsers map of usernames to their EclipseUser entry
+   * @param group the Gitlab group that is being cleaned of extra users.
+   * @param projectIDs list of project IDs that impact the given group
+   * @returns a promise that completes once all additional users are removed or the check finishes
+   */
+  async removeAdditionalUsers(expectedUsers: Record<string, EclipseUser>, group: GroupSchema, ...projectIDs: string[]): Promise<void> {
     if (this.config.verbose) {
       this.logger.debug(
         `GitlabSync:removeAdditionalUsers(expectedUsers = ${JSON.stringify(expectedUsers)}, group = ${
@@ -438,6 +447,14 @@ export class GitlabSyncRunner {
     return null;
   }
 
+  /**
+   * Retrieves a Gitlab user object for the given Eclipse user given their username and access URL. If the
+   * user does not yet exist, a new user is created, cached, and returned for use.
+   *
+   * @param uname the Eclipse username of user to retrieve from Gitlab
+   * @param url the Eclipse user access URL
+   * @returns the gitlab user, or null if it can't be found or created.
+   */
   async getUser(uname: string, url: string): Promise<UserSchema | null> {
     if (this.config.verbose) {
       this.logger.debug(`GitlabSync:getUser(uname = ${uname}, url = ${url})`);
@@ -501,6 +518,12 @@ export class GitlabSyncRunner {
     return u;
   }
 
+  /**
+   * Retrieves the list of direct members for a given group, ignoring inherited users.
+   *
+   * @param group the Gitlab group to retrieve members for
+   * @returns a list of Gitlab group members for the given group, or null if there is an error while fetching.
+   */
   async getGroupMembers(group: GroupSchema): Promise<MemberSchema[] | null> {
     if (this.config.verbose) {
       this.logger.debug(`GitlabSync:getGroupMembers(group = ${group?.full_path})`);
@@ -525,6 +548,10 @@ export class GitlabSyncRunner {
 
   /** HELPERS */
 
+  /**
+   * Generate the nested group cache using the raw Gitlab group definitions.
+   * @param rawGroups
+   */
   generateGroupsCache(rawGroups: GroupSchema[]): void {
     if (this.config.verbose) {
       this.logger.debug(`GitlabSync:generateGroupsCache(projects = count->${rawGroups.length})`);
@@ -538,10 +565,13 @@ export class GitlabSyncRunner {
 
     // iterate through groups and insert into the nested cache
     for (let i = 0; i < rawGroups.length; i++) {
-      this.addGroup(rawGroups[i], this.groupCache);
+      this.addGroup(rawGroups[i]);
     }
   }
 
+  /**
+   * @returns the root group cache for the current sync operation if it exists. If missing, the script ends processing.
+   */
   getRootGroup(): GroupCache {
     let rootGroupCache = this.groupCache.children[this.config.rootGroup];
     if (rootGroupCache === undefined) {
@@ -551,6 +581,14 @@ export class GitlabSyncRunner {
     return rootGroupCache;
   }
 
+  /**
+   * Retrieves the group for the given namespace path. This namespace path should be formatted such that each group path is separated
+   * by a slash, eg. eclipse/sample/group. This will be split and used to iterate through the nested cache, returning the group once
+   * each namespace path part is used.
+   *
+   * @param namespace the full path of the group namespace to retrieve.
+   * @returns the group cache for the group indicated by the namespace string, or null if there is no matching group.
+   */
   getCachedGroup(namespace: string): GroupCache | null {
     if (this.config.verbose) {
       this.logger.debug(`GitlabSync:getCachedGroup(${namespace})`);
@@ -562,26 +600,39 @@ export class GitlabSyncRunner {
     return this.tunnelAndRetrieve(namespace.split('/'), this.groupCache);
   }
 
-  addGroup(g: GroupSchema, parent: GroupCache = this.groupCache): GroupCache | null {
+  /**
+   * Adds a group to the nested group cache, using the groups full_path property to discover how to insert the
+   * entry into the nested cache. Any cache nodes that do not exist yet will be created as the group is inserted.
+   *
+   * @param g the Gitlab group that is being inserted into the group cache.
+   * @returns the group cache entry for the cached gitlab group
+   */
+  addGroup(g: GroupSchema): GroupCache {
     if (this.config.verbose) {
       this.logger.debug(`GitlabSync:addGroup(g = ${g.id})`);
     }
-    // type the namespace as it is a raw type, make sure its the type we expect
-    if (typeof g.full_path !== 'string') {
-      this.logger.error(`Could not cast namespace to string: ${g.full_path}`);
-      return null;
-    }
     let namespace = g.full_path;
     // split into group namespace paths (eclipse/sample/group.path into ['eclipse','sample','group.path'])
     let namespaceParts = namespace.split('/');
     return this.tunnelAndInsert(namespaceParts, g, this.groupCache);
   }
 
+  /**
+   * Recursive function for inserting groups into the nested group cache. Will tunnel through cache, creating
+   * entries as necessary before inserting the group at the nesting level representing the final group in the
+   * full path of the group.
+   *
+   * @param namespaceParts the parts of the full_path left to process for group nesting
+   * @param g  the group to be inserted into the group cache.
+   * @param parent the parent level for the current level of insertion
+   * @returns the group cache entry for the group once inserted.
+   */
   tunnelAndInsert(namespaceParts: string[], g: GroupSchema, parent: GroupCache): GroupCache {
     if (this.config.verbose) {
       this.logger.debug(`GitlabSync:tunnelAndInsert(namespaceParts = '${namespaceParts}', g = ${g.id})`);
     }
 
+    // get the next level cache if it exists, creating it if it doesn't
     let child = parent.children[namespaceParts[0]];
     if (child === undefined) {
       child = {