[#5] Add docstrings to feature/lint-fixes

Author: richardgaunt

src/interactive.js

@@ -15,6 +15,11 @@ import {
 import { logAction } from './logger';
 import { configureSshKey } from './lagoon-ssh-key-configurator';
 
+/**
+ * Launches the interactive Lagoon CLI wrapper, allowing users to manage projects and environments through a guided command-line interface.
+ *
+ * Presents menus for selecting Lagoon instances and projects, and provides options to list environments or users, delete environments, generate login links, clear Drupal cache, configure SSH keys, and change selections. Handles errors gracefully and logs major actions throughout the session.
+ */
 export async function startInteractiveMode() {
   console.log(chalk.green('Welcome to the Lagoon CLI Wrapper!'));
   logAction('Application Start', 'N/A', 'Interactive mode started');
@@ -152,6 +157,13 @@ async function selectProjectWithDetails(instance) {
   };
 }
 
+/**
+ * Displays the main menu for the interactive CLI and prompts the user to select an action.
+ *
+ * @param {string} instance - The name of the currently selected Lagoon instance.
+ * @param {string} project - The name of the currently selected project.
+ * @returns {Promise<string>} The action selected by the user.
+ */
 async function showMainMenu(instance, project) {
   console.log(chalk.blue(`\nCurrent Instance: ${chalk.bold(instance)}`));
   console.log(chalk.blue(`Current Project: ${chalk.bold(project)}\n`));

src/lagoon-api.js

@@ -114,7 +114,18 @@ export async function getUsers(instance, project) {
   }
 }
 
-// Delete an environment
+/**
+ * Deletes a Lagoon environment unless it is protected.
+ *
+ * Throws an error if the environment is protected (such as 'production', 'master', 'develop', or names starting with 'project/'). Executes the Lagoon CLI to delete the specified environment and returns true if successful.
+ *
+ * @param {string} instance - The Lagoon instance name.
+ * @param {string} project - The project name.
+ * @param {string} environment - The environment name to delete.
+ * @returns {boolean} True if the environment was deleted successfully.
+ *
+ * @throws {Error} If the environment is protected or if the deletion fails.
+ */
 export async function deleteEnvironment(instance, project, environment) {
   // Check if environment is protected
   if (
@@ -158,7 +169,12 @@ export async function generateLoginLink(instance, project, environment) {
   }
 }
 
-// Helper function to convert git URL to GitHub URL
+/**
+ * Converts a Git SSH or HTTPS URL to a standard GitHub HTTPS URL without the `.git` suffix.
+ *
+ * @param {string} gitUrl - The Git repository URL to convert.
+ * @returns {string|null} The corresponding GitHub HTTPS URL, or {@code null} if the input is not a GitHub URL.
+ */
 export function gitUrlToGithubUrl(gitUrl) {
   // Handle SSH URLs like git@github.com:org/repo.git
   if (gitUrl.startsWith('git@github.com:')) {

src/logger.js

@@ -22,10 +22,11 @@ function getLogFilePath() {
 }
 
 /**
- * Log a message to the daily log file
- * @param {string} action - The action being performed in the CLI
- * @param {string} command - The Lagoon CLI command being executed
- * @param {string} [result] - Optional result of the command
+ * Appends an action entry with timestamp, action, command, and optional result to the current day's log file.
+ *
+ * @param {string} action - Description of the action performed.
+ * @param {string} command - The CLI command executed.
+ * @param {string} [result] - Optional result of the command.
  */
 export function logAction(action, command, result = null) {
   const timestamp = new Date().toISOString(); // ISO8601 timestamp
@@ -37,10 +38,11 @@ export function logAction(action, command, result = null) {
 }
 
 /**
- * Log an error to the daily log file
- * @param {string} action - The action being performed in the CLI
- * @param {string} command - The Lagoon CLI command being executed
- * @param {Error} error - The error that occurred
+ * Appends an error entry to the current day's log file with a timestamp, action, command, and error message.
+ *
+ * @param {string} action - Description of the action being performed.
+ * @param {string} command - The CLI command that was executed.
+ * @param {Error} error - The error encountered during execution.
  */
 export function logError(action, command, error) {
   const timestamp = new Date().toISOString(); // ISO8601 timestamp