From 2be130b63bfa7b5a873c56badf39fc49598c8472 Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 07:59:13 -0500 Subject: [PATCH 01/16] Fix jsdoc issues in data_router --- core/database/foxx/api/data_router.js | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/core/database/foxx/api/data_router.js b/core/database/foxx/api/data_router.js index 9dfed1b92..1058c1dfc 100644 --- a/core/database/foxx/api/data_router.js +++ b/core/database/foxx/api/data_router.js @@ -1464,8 +1464,26 @@ router .summary("Toggle data record lock") .description("Toggle data record lock"); -/** @brief Get raw data path for local direct access, if possible from specified domain +/** + * @function + * @description Gets the raw data path for local direct access from the specified domain, + * if available, for a given data ID and client. + * + * The method checks the client's permissions for the data ID and returns the path to the data + * if the client has the required permissions and the data exists in the specified domain. * + * @param {Object} req - The request object, containing the query parameters. + * @param {Object} req.queryParams - The query parameters provided in the request. + * @param {string} req.queryParams.client - The client ID for the request. + * @param {string} req.queryParams.id - The data ID (not alias) associated with the data. + * @param {string} req.queryParams.domain - The domain from which the data is being requested. + * @param {Object} res - The response object, used to send the raw data path or error. + * + * @throws {Error} g_lib.ERR_PERM_DENIED - If the client does not have permission to read the data. + * @throws {Error} g_lib.ERR_NO_RAW_DATA - If the raw data is not found. + * @throws {Error} g_lib.ERR_INVALID_PARAM - If the data belongs to a different domain than specified. + * + * @returns {void} - Returns the raw data path in the response if the request is successful. */ router .get("/path", function (req, res) { From dfa1db53579bd3bc9ef2541aad070c145ec072d3 Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 08:04:50 -0500 Subject: [PATCH 02/16] Fix JSDOc issues in process.js fiel --- core/database/foxx/api/process.js | 74 ++++++++++++++++++++++--------- 1 file changed, 54 insertions(+), 20 deletions(-) diff --git a/core/database/foxx/api/process.js b/core/database/foxx/api/process.js index 1fe294e60..ad2bc9d75 100644 --- a/core/database/foxx/api/process.js +++ b/core/database/foxx/api/process.js @@ -6,15 +6,46 @@ const g_lib = require("./support"); module.exports = (function () { var obj = {}; - /** @brief Pre-process data/collection IDs for permissions and required data - * - * Examine data and collections for proper permissions for the given mode and - * recursively process items (data/collections) in included collections. Does - * not resolve IDs. On success, returns lists of data records for globus and - * external data, as well as records without data. Also returns a flat list of - * all collections. In delete mode, for data records in collections, only data - * that isn't linked elsewhere are returned. - */ + /** + * @function + * @description Pre-processes data and collection IDs for permissions and required data. + * This function examines the specified data and collections for the appropriate permissions + * based on the given mode and recursively processes items (data/collections) in included collections. + * It does not resolve IDs. On success, it returns lists of data records for Globus and external data, + * as well as records without data. Additionally, it returns a flat list of all collections. + * + * In delete mode, only data that is not linked elsewhere will be returned for data records within collections. + * + * @param {Object} a_client - The client object containing the client ID and admin status. + * @param {string} a_client._id - The unique identifier of the client. + * @param {boolean} a_client.is_admin - A flag indicating if the client is an administrator. + * @param {string} a_new_owner_id - The ID of the new owner to assign. + * @param {Array} a_ids - An array of data and collection IDs to process. + * @param {string} a_mode - The mode in which the operation is being performed. It can be one of the following: + * - `g_lib.TT_DATA_GET`: Read data permissions. + * - `g_lib.TT_DATA_PUT`: Write data permissions. + * - `g_lib.TT_REC_ALLOC_CHG`: Allocate/change record permissions. + * - `g_lib.TT_REC_OWNER_CHG`: Change record owner permissions. + * - `g_lib.TT_REC_DEL`: Delete record permissions. + * - `g_lib.TT_DATA_EXPORT`: Export data permissions. + * + * @returns {Object} ctxt - An object containing the following properties: + * - `client`: The client information. + * - `new_owner`: The ID of the new owner. + * - `mode`: The mode for the operation. + * - `coll_perm`: The collection permission level. + * - `data_perm`: The data permission level. + * - `coll`: A list of collections. + * - `glob_data`: A list of Globus data records. + * - `ext_data`: A list of external data records. + * - `visited`: A record of visited items during recursion. + * + * @throws {Error} g_lib.ERR_INVALID_MODE - If an invalid mode is passed. + * + * @example + * const result = obj.preprocessItems(client, newOwnerId, dataIds, g_lib.TT_DATA_GET); + * console.log(result.glob_data); + */ obj.preprocessItems = function (a_client, a_new_owner_id, a_ids, a_mode) { //console.log( "preprocessItems start" ); var ctxt = { @@ -112,17 +143,20 @@ module.exports = (function () { }; /** - * @brief Recursive preprocessing of data/collections for data operations - * @param a_ctxt - Recursion context object - * @param a_ids - Current list of data/collection IDs to process - * @param a_perm - Inherited permission (undefined initially) - * - * This function pre-processes with optimized permission verification by - * using a depth-first analysis of collections. If the required permission - * is satisfied via inherited ACLs, then no further permission checks are - * required below that point. The end result is a flat list of collections - * and data segregated into those with Globus data (regardless of data - * size) and those with external data. + * Recursively preprocesses data and collections for data operations. + * + * This function performs a depth-first analysis of collections, verifying permissions. + * It ensures that if the required permission is satisfied via inherited ACLs, no further + * permission checks are needed below that point. The function segregates collections and + * data into two categories: those with Globus data (regardless of data size) and those + * with external data. The final result is a flat list of collections and data. + * + * @param {Object} a_ctxt - The recursion context object, containing relevant state such as permissions and mode. + * @param {Array} a_ids - The current list of data/collection IDs to process. + * @param {number} [a_data_perm] - The inherited data permission (undefined initially). + * @param {number} [a_coll_perm] - The inherited collection permission (undefined initially). + * + * @throws {Array} Throws error with permission or parameter issues. */ obj._preprocessItemsRecursive = function (a_ctxt, a_ids, a_data_perm, a_coll_perm) { var i, id, ids, is_coll, doc, perm, ok, data_perm, coll_perm; From 5d102c9a26af1fdcccdc9a2d70f7e2f07619467b Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 08:06:59 -0500 Subject: [PATCH 03/16] Fix JSDOc issues in repo_router.js --- core/database/foxx/api/repo_router.js | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/core/database/foxx/api/repo_router.js b/core/database/foxx/api/repo_router.js index d54b45f08..0aed93881 100644 --- a/core/database/foxx/api/repo_router.js +++ b/core/database/foxx/api/repo_router.js @@ -362,11 +362,19 @@ router .summary("Delete repo server record") .description("Delete repo server record"); -/** @brief Calculate the total, per-repo size of selected items +/** + * @function + * @description Calculates the total, per-repo size of selected items. + * Recursively analyzes collections but only counts each data record once regardless of how many places it is linked. + * This function is used for pre-processing data move operations (e.g., changing allocation or owner). * - * Recursively analyzes collections but only counts each data record once - * regardless of how many places it is linked. Used for pre-processing - * data move operations (change alloc or owner). + * @param {Object} req - The request object, containing the query parameters. + * @param {Object} res - The response object used to send the results. + * @returns {void} Sends an array of repository size statistics to the response. + * + * @example + * // Sample usage: + * router.get("/calc_size", function(req, res) { ... }); */ router .get("/calc_size", function (req, res) { From 51c6508c44789deb0be28059d2c8adf0370ff77b Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 08:17:05 -0500 Subject: [PATCH 04/16] Address JSDoc in tasks.js --- core/database/foxx/api/tasks.js | 59 +++++++++++++++++++++++---------- 1 file changed, 42 insertions(+), 17 deletions(-) diff --git a/core/database/foxx/api/tasks.js b/core/database/foxx/api/tasks.js index 91cbb6483..78ed6a18e 100644 --- a/core/database/foxx/api/tasks.js +++ b/core/database/foxx/api/tasks.js @@ -1498,14 +1498,21 @@ var tasks_func = (function () { // ----------------------- External Support Functions --------------------- - /** @brief Delete projects and associated data + /** + * Deletes one or more projects and associated data. If a project has no allocations, it can + * be deleted immediately. If a project has allocations and raw data, a task must be initialized + * to delete the allocations. Deletion is exclusive—if any other tasks are using the project or + * associated data, the operation will be denied. * - * Delete one or more projects. If a project has no allocations, - * it can be deleted immediately. If a project has allocations and - * raw data, the project can be deleted, but a task must be initialized - * to delete the allocations. Deletion is an exclusive operation - if - * any other tasks are using the project or associated data, the delete - * operation will be denied. + * @param {Object} a_client - The client object that contains user details and permissions. + * @param {Array} a_proj_ids - An array of project IDs to be deleted. + * @returns {Object} An object containing the task to delete the projects and allocations. + * @throws {Array} Throws an error array containing a code and message if the project does + * not exist or the client lacks permissions. + * + * @example + * const result = obj.taskInitProjDelete(client, ['proj_id_1', 'proj_id_2']); + * console.log(result); */ obj.taskInitProjDelete = function (a_client, a_proj_ids) { var i, proj_id; @@ -2178,11 +2185,16 @@ var tasks_func = (function () { return doc; }; - /** @brief Deletes a collection record + /** + * Deletes a collection record. This function should not be called directly and is used + * only by task or process code. The function does not recursively delete contained items. * - * NOTE: DO NOT CALL THIS DIRECTLY - USED ONLY BY TASK/PROCESS CODE + * @param {string} a_id - The ID of the collection to delete. + * @throws {Error} Throws an error if the collection or associated graph objects cannot be deleted. * - * Does not recursively delete contained items. + * @note This function will delete aliases, notes, topics, and tags associated with the collection, + * but it will not recursively delete contained items. + * @note Use this function only within tasks or process code. */ obj._deleteCollection = function (a_id) { // Delete alias @@ -2215,10 +2227,15 @@ var tasks_func = (function () { g_graph.c.remove(a_id); }; - /** @brief Deletes data records + /** + * Deletes a data record and its associated graph objects. This function does not delete raw + * data but adjusts the allocation accordingly. + * + * @param {string} a_id - The ID of the data record to delete. + * @throws {Error} Throws an error if the data record or associated graph objects cannot be deleted. * - * Deletes record and associated graph objects. Does not delete raw data - * but does adjust allocation. + * @note This function will delete aliases, notes, tags, and update schema counts and allocations. + * @note It will not delete raw data, but it will adjust the allocation associated with the data record. */ obj._deleteDataRecord = function (a_id) { //console.log( "delete rec", a_id ); @@ -2365,11 +2382,19 @@ var tasks_func = (function () { //console.log( "deleting records finished", Date.now() ); }; - /** @brief Deletes project immediately - * - * Deletes projects and associated graph objects. + /** + * Deletes a project and all associated graph objects immediately. + * + * This function deletes allocations, owned records (e.g., data, collections, groups), + * and the project itself. It performs a direct deletion of the project and its related + * items, and should **NOT** be used on projects containing raw data. * - * DO NOT USE ON PROJECTS WITH RAW DATA!!!! + * @param {string} a_proj_id - The ID of the project to delete. + * @throws {Error} Throws an error if the project or associated items cannot be deleted. + * + * @note Use this function with caution, as it will permanently delete allocations, data, + * collections, groups, and the project. It should not be used for projects that + * contain raw data. */ obj._projectDelete = function (a_proj_id) { console.log("_projectDelete", a_proj_id); From d13579a16c19471bb449dca25d74c84bb153a4c3 Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 08:23:29 -0500 Subject: [PATCH 05/16] Address JSDoc linting issues --- core/database/foxx/api/task_router.js | 17 ++++++-- eslint.config.js | 1 + web/static/main_browse_tab.js | 16 ++++++-- web/static/util.js | 57 +++++++++++++-------------- 4 files changed, 54 insertions(+), 37 deletions(-) diff --git a/core/database/foxx/api/task_router.js b/core/database/foxx/api/task_router.js index ff66ff6f8..b817f9fef 100644 --- a/core/database/foxx/api/task_router.js +++ b/core/database/foxx/api/task_router.js @@ -207,10 +207,21 @@ router "Run an initialized task. Step param confirms last command. Error message indicates external permanent failure.", ); -/** @brief Clean-up a task and remove it from task dependency graph +/** + * @function + * @description Cleans up a task by removing it from the task dependency graph. + * It removes dependency locks and patches the task dependency graph both upstream and downstream. + * It returns a list of new runnable tasks if available. * - * Removes dependency locks and patches task dependency graph (up and down - * stream). Returns list of new runnable tasks if available. + * @param {Object} req - The request object containing the task ID in the query parameters and other relevant data in the body. + * @param {Object} res - The response object used to send the result or an error message. + * @returns {void} Sends a list of new runnable tasks to the response. + * + * @throws {Error} Throws an error if the task does not exist or if there's an issue processing the transaction. + * + * @example + * // Sample usage: + * router.post("/abort", function(req, res) { ... }); */ router .post("/abort", function (req, res) { diff --git a/eslint.config.js b/eslint.config.js index 188afcfa1..2021f8257 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -3,6 +3,7 @@ const jsdocPlugin = require("eslint-plugin-jsdoc"); module.exports = [ { + ignorePatterns: ['docs/_static'], languageOptions: { globals: { ...globals.jquery, diff --git a/web/static/main_browse_tab.js b/web/static/main_browse_tab.js index a3e884958..2af3cbafd 100644 --- a/web/static/main_browse_tab.js +++ b/web/static/main_browse_tab.js @@ -2078,11 +2078,19 @@ function treeSelectRange(a_tree, a_node) { } } -/** @brief Check if past is allowed to specified node - * @param dest_node - Candidate paste destination node - * @param src_node - Node being dragged +/** + * @brief Check if pasting is allowed to the specified node. * - * There is additional source information in pasteXXX + * This function checks whether a paste operation is allowed based on various conditions, + * such as whether the destination node is valid, whether the source and destination nodes + * belong to the same scope, and other restrictions like node types and parent-child relationships. + * + * @param {Object} dest_node - The candidate destination node where the paste operation is being attempted. + * @param {Object} src_node - The node being dragged or copied to the destination. + * + * @returns {string|boolean} Returns "over" if the paste is allowed, otherwise returns `false`. + * + * @note There is additional source information in the pasteSourceParent and pasteCollections variables. */ function pasteAllowed(dest_node, src_node) { //console.log("pasteAllowed:",dest_node, src_node); diff --git a/web/static/util.js b/web/static/util.js index f5b5faf20..c55c92b19 100644 --- a/web/static/util.js +++ b/web/static/util.js @@ -769,37 +769,34 @@ export function dataGet(a_ids, a_cb) { }); } -// Only works on schema records with valid JSON schema definitions -/* -export function schemaResolveRefs( a_schema ){ - var refs = {}; - _schemaResolveRefs( a_schema.def.properties, refs ); -} - -function _schemaResolveRefs( a_props, a_refs ){ - var v, p; - for ( var k in a_props ){ - v = a_props[k]; - - if ( "$ref" in v ){ - }else if (( p = v.properties ) != undefined ) { - _schemaResolveRefs( p, a_refs ); - } - } -} -*/ - /** - * Basic implementation of get_authorize_url from Globus SDK - * @param {UUID} client_id The UUID of the Globus authentication client - * @param {string} redirect_uri The URI safe application-wide Globus Auth redirect URI. - * @param {Array}requested_scopes The scopes on the token(s) being requested - * In the case of accessing a mapped collection, this should include the mapped collection's UUID - * like so: https://auth.globus.org/scopes/YOUR-UUID-HERE/data_access - * @param {string} state Allows the application to pass information back to itself - * @param {boolean} refresh_tokens Request refresh tokens in addition to access tokens - * @param {object} query_params Additional params - * @returns {string} The URL a user can follow to provide authorization and consent via Globus + * Basic implementation of `get_authorize_url` from the Globus SDK. + * + * This function generates the authorization URL that a user can follow to provide + * authorization and consent via Globus Auth. + * + * @param {UUID} client_id - The UUID of the Globus authentication client. + * @param {string} redirect_uri - The URI-safe application-wide Globus Auth redirect URI. + * @param {Array} [requested_scopes=[]] - The scopes on the token(s) being requested. + * In the case of accessing a mapped collection, this should include the mapped + * collection's UUID, such as: `https://auth.globus.org/scopes/YOUR-UUID-HERE/data_access`. + * @param {string} [state="_default"] - Allows the application to pass information back to itself. + * @param {boolean} [refresh_tokens=false] - Request refresh tokens in addition to access tokens. + * @param {object} [query_params={}] - Additional parameters to be included in the authorization URL. + * + * @returns {string} The URL a user can follow to provide authorization and consent via Globus. + * + * @throws {Error} If either `client_id` or `redirect_uri` are not provided. + * + * @example + * const url = globusGetAuthorizeURL( + * 'your-client-id', + * 'your-redirect-uri', + * ['openid', 'email'], + * 'custom-state', + * true, + * { custom_param: 'value' } + * ); */ export function globusGetAuthorizeURL( client_id, From 2e46fade38a947255a24fdd3570b40d9047eef30 Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 08:25:06 -0500 Subject: [PATCH 06/16] Switch to ignores statement --- eslint.config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eslint.config.js b/eslint.config.js index 2021f8257..40aa8b9b9 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -3,7 +3,7 @@ const jsdocPlugin = require("eslint-plugin-jsdoc"); module.exports = [ { - ignorePatterns: ['docs/_static'], + ignores: ['docs/_static'], languageOptions: { globals: { ...globals.jquery, From 93de85441e349eae2ce7d160bab64c6c1c4382b6 Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 08:34:28 -0500 Subject: [PATCH 07/16] Address more eslint jsdoc items --- core/database/foxx/api/data_router.js | 6 ++--- core/database/foxx/api/process.js | 38 +++++++++++++-------------- core/database/foxx/api/repo_router.js | 4 +-- core/database/foxx/api/task_router.js | 4 +-- core/database/foxx/api/tasks.js | 16 +++++------ eslint.config.js | 2 +- 6 files changed, 35 insertions(+), 35 deletions(-) diff --git a/core/database/foxx/api/data_router.js b/core/database/foxx/api/data_router.js index 1058c1dfc..23e310301 100644 --- a/core/database/foxx/api/data_router.js +++ b/core/database/foxx/api/data_router.js @@ -1472,12 +1472,12 @@ router * The method checks the client's permissions for the data ID and returns the path to the data * if the client has the required permissions and the data exists in the specified domain. * - * @param {Object} req - The request object, containing the query parameters. - * @param {Object} req.queryParams - The query parameters provided in the request. + * @param {object} req - The request object, containing the query parameters. + * @param {object} req.queryParams - The query parameters provided in the request. * @param {string} req.queryParams.client - The client ID for the request. * @param {string} req.queryParams.id - The data ID (not alias) associated with the data. * @param {string} req.queryParams.domain - The domain from which the data is being requested. - * @param {Object} res - The response object, used to send the raw data path or error. + * @param {object} res - The response object, used to send the raw data path or error. * * @throws {Error} g_lib.ERR_PERM_DENIED - If the client does not have permission to read the data. * @throws {Error} g_lib.ERR_NO_RAW_DATA - If the raw data is not found. diff --git a/core/database/foxx/api/process.js b/core/database/foxx/api/process.js index ad2bc9d75..c15cd2114 100644 --- a/core/database/foxx/api/process.js +++ b/core/database/foxx/api/process.js @@ -8,7 +8,7 @@ module.exports = (function () { /** * @function - * @description Pre-processes data and collection IDs for permissions and required data. + * Pre-processes data and collection IDs for permissions and required data. * This function examines the specified data and collections for the appropriate permissions * based on the given mode and recursively processes items (data/collections) in included collections. * It does not resolve IDs. On success, it returns lists of data records for Globus and external data, @@ -16,29 +16,29 @@ module.exports = (function () { * * In delete mode, only data that is not linked elsewhere will be returned for data records within collections. * - * @param {Object} a_client - The client object containing the client ID and admin status. + * @param {object} a_client - The client object containing the client ID and admin status. * @param {string} a_client._id - The unique identifier of the client. * @param {boolean} a_client.is_admin - A flag indicating if the client is an administrator. * @param {string} a_new_owner_id - The ID of the new owner to assign. * @param {Array} a_ids - An array of data and collection IDs to process. * @param {string} a_mode - The mode in which the operation is being performed. It can be one of the following: - * - `g_lib.TT_DATA_GET`: Read data permissions. - * - `g_lib.TT_DATA_PUT`: Write data permissions. - * - `g_lib.TT_REC_ALLOC_CHG`: Allocate/change record permissions. - * - `g_lib.TT_REC_OWNER_CHG`: Change record owner permissions. - * - `g_lib.TT_REC_DEL`: Delete record permissions. - * - `g_lib.TT_DATA_EXPORT`: Export data permissions. + * - `g_lib.TT_DATA_GET`: Read data permissions. + * - `g_lib.TT_DATA_PUT`: Write data permissions. + * - `g_lib.TT_REC_ALLOC_CHG`: Allocate/change record permissions. + * - `g_lib.TT_REC_OWNER_CHG`: Change record owner permissions. + * - `g_lib.TT_REC_DEL`: Delete record permissions. + * - `g_lib.TT_DATA_EXPORT`: Export data permissions. * - * @returns {Object} ctxt - An object containing the following properties: - * - `client`: The client information. - * - `new_owner`: The ID of the new owner. - * - `mode`: The mode for the operation. - * - `coll_perm`: The collection permission level. - * - `data_perm`: The data permission level. - * - `coll`: A list of collections. - * - `glob_data`: A list of Globus data records. - * - `ext_data`: A list of external data records. - * - `visited`: A record of visited items during recursion. + * @returns {object} ctxt - An object containing the following properties: + * - `client`: The client information. + * - `new_owner`: The ID of the new owner. + * - `mode`: The mode for the operation. + * - `coll_perm`: The collection permission level. + * - `data_perm`: The data permission level. + * - `coll`: A list of collections. + * - `glob_data`: A list of Globus data records. + * - `ext_data`: A list of external data records. + * - `visited`: A record of visited items during recursion. * * @throws {Error} g_lib.ERR_INVALID_MODE - If an invalid mode is passed. * @@ -151,7 +151,7 @@ module.exports = (function () { * data into two categories: those with Globus data (regardless of data size) and those * with external data. The final result is a flat list of collections and data. * - * @param {Object} a_ctxt - The recursion context object, containing relevant state such as permissions and mode. + * @param {object} a_ctxt - The recursion context object, containing relevant state such as permissions and mode. * @param {Array} a_ids - The current list of data/collection IDs to process. * @param {number} [a_data_perm] - The inherited data permission (undefined initially). * @param {number} [a_coll_perm] - The inherited collection permission (undefined initially). diff --git a/core/database/foxx/api/repo_router.js b/core/database/foxx/api/repo_router.js index 0aed93881..0ab414d14 100644 --- a/core/database/foxx/api/repo_router.js +++ b/core/database/foxx/api/repo_router.js @@ -368,8 +368,8 @@ router * Recursively analyzes collections but only counts each data record once regardless of how many places it is linked. * This function is used for pre-processing data move operations (e.g., changing allocation or owner). * - * @param {Object} req - The request object, containing the query parameters. - * @param {Object} res - The response object used to send the results. + * @param {object} req - The request object, containing the query parameters. + * @param {object} res - The response object used to send the results. * @returns {void} Sends an array of repository size statistics to the response. * * @example diff --git a/core/database/foxx/api/task_router.js b/core/database/foxx/api/task_router.js index b817f9fef..802f1b41c 100644 --- a/core/database/foxx/api/task_router.js +++ b/core/database/foxx/api/task_router.js @@ -213,8 +213,8 @@ router * It removes dependency locks and patches the task dependency graph both upstream and downstream. * It returns a list of new runnable tasks if available. * - * @param {Object} req - The request object containing the task ID in the query parameters and other relevant data in the body. - * @param {Object} res - The response object used to send the result or an error message. + * @param {object} req - The request object containing the task ID in the query parameters and other relevant data in the body. + * @param {object} res - The response object used to send the result or an error message. * @returns {void} Sends a list of new runnable tasks to the response. * * @throws {Error} Throws an error if the task does not exist or if there's an issue processing the transaction. diff --git a/core/database/foxx/api/tasks.js b/core/database/foxx/api/tasks.js index 78ed6a18e..7579e1129 100644 --- a/core/database/foxx/api/tasks.js +++ b/core/database/foxx/api/tasks.js @@ -1504,9 +1504,9 @@ var tasks_func = (function () { * to delete the allocations. Deletion is exclusive—if any other tasks are using the project or * associated data, the operation will be denied. * - * @param {Object} a_client - The client object that contains user details and permissions. + * @param {object} a_client - The client object that contains user details and permissions. * @param {Array} a_proj_ids - An array of project IDs to be deleted. - * @returns {Object} An object containing the task to delete the projects and allocations. + * @returns {object} An object containing the task to delete the projects and allocations. * @throws {Array} Throws an error array containing a code and message if the project does * not exist or the client lacks permissions. * @@ -2192,9 +2192,9 @@ var tasks_func = (function () { * @param {string} a_id - The ID of the collection to delete. * @throws {Error} Throws an error if the collection or associated graph objects cannot be deleted. * - * @note This function will delete aliases, notes, topics, and tags associated with the collection, - * but it will not recursively delete contained items. - * @note Use this function only within tasks or process code. + * This function will delete aliases, notes, topics, and tags associated with the collection, + * but it will not recursively delete contained items. + * Use this function only within tasks or process code. */ obj._deleteCollection = function (a_id) { // Delete alias @@ -2392,9 +2392,9 @@ var tasks_func = (function () { * @param {string} a_proj_id - The ID of the project to delete. * @throws {Error} Throws an error if the project or associated items cannot be deleted. * - * @note Use this function with caution, as it will permanently delete allocations, data, - * collections, groups, and the project. It should not be used for projects that - * contain raw data. + * Use this function with caution, as it will permanently delete allocations, data, + * collections, groups, and the project. It should not be used for projects that + * contain raw data. */ obj._projectDelete = function (a_proj_id) { console.log("_projectDelete", a_proj_id); diff --git a/eslint.config.js b/eslint.config.js index 40aa8b9b9..8fafa3b1d 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -3,7 +3,7 @@ const jsdocPlugin = require("eslint-plugin-jsdoc"); module.exports = [ { - ignores: ['docs/_static'], + ignores: ['docs/_static/*'], languageOptions: { globals: { ...globals.jquery, From bbfc3a9d999b58c4393e628c1281906269f11256 Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 08:37:32 -0500 Subject: [PATCH 08/16] Fix additional jsdoc items --- web/static/main_browse_tab.js | 9 +++++---- web/static/util.js | 4 ++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/web/static/main_browse_tab.js b/web/static/main_browse_tab.js index 2af3cbafd..2ea8fc136 100644 --- a/web/static/main_browse_tab.js +++ b/web/static/main_browse_tab.js @@ -2079,18 +2079,19 @@ function treeSelectRange(a_tree, a_node) { } /** - * @brief Check if pasting is allowed to the specified node. + * @function + * Check if pasting is allowed to the specified node. * * This function checks whether a paste operation is allowed based on various conditions, * such as whether the destination node is valid, whether the source and destination nodes * belong to the same scope, and other restrictions like node types and parent-child relationships. * - * @param {Object} dest_node - The candidate destination node where the paste operation is being attempted. - * @param {Object} src_node - The node being dragged or copied to the destination. + * @param {object} dest_node - The candidate destination node where the paste operation is being attempted. + * @param {object} src_node - The node being dragged or copied to the destination. * * @returns {string|boolean} Returns "over" if the paste is allowed, otherwise returns `false`. * - * @note There is additional source information in the pasteSourceParent and pasteCollections variables. + * There is additional source information in the pasteSourceParent and pasteCollections variables. */ function pasteAllowed(dest_node, src_node) { //console.log("pasteAllowed:",dest_node, src_node); diff --git a/web/static/util.js b/web/static/util.js index c55c92b19..b1dfa4cf1 100644 --- a/web/static/util.js +++ b/web/static/util.js @@ -778,8 +778,8 @@ export function dataGet(a_ids, a_cb) { * @param {UUID} client_id - The UUID of the Globus authentication client. * @param {string} redirect_uri - The URI-safe application-wide Globus Auth redirect URI. * @param {Array} [requested_scopes=[]] - The scopes on the token(s) being requested. - * In the case of accessing a mapped collection, this should include the mapped - * collection's UUID, such as: `https://auth.globus.org/scopes/YOUR-UUID-HERE/data_access`. + * In the case of accessing a mapped collection, this should include the mapped + * collection's UUID, such as: `https://auth.globus.org/scopes/YOUR-UUID-HERE/data_access`. * @param {string} [state="_default"] - Allows the application to pass information back to itself. * @param {boolean} [refresh_tokens=false] - Request refresh tokens in addition to access tokens. * @param {object} [query_params={}] - Additional parameters to be included in the authorization URL. From a61901991b128ed60dea4746148f42e22e20364e Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 08:42:30 -0500 Subject: [PATCH 09/16] Try to satisfy linter --- core/database/foxx/api/process.js | 81 ++++++++++++++++--------------- 1 file changed, 41 insertions(+), 40 deletions(-) diff --git a/core/database/foxx/api/process.js b/core/database/foxx/api/process.js index c15cd2114..a7450702d 100644 --- a/core/database/foxx/api/process.js +++ b/core/database/foxx/api/process.js @@ -6,46 +6,47 @@ const g_lib = require("./support"); module.exports = (function () { var obj = {}; - /** - * @function - * Pre-processes data and collection IDs for permissions and required data. - * This function examines the specified data and collections for the appropriate permissions - * based on the given mode and recursively processes items (data/collections) in included collections. - * It does not resolve IDs. On success, it returns lists of data records for Globus and external data, - * as well as records without data. Additionally, it returns a flat list of all collections. - * - * In delete mode, only data that is not linked elsewhere will be returned for data records within collections. - * - * @param {object} a_client - The client object containing the client ID and admin status. - * @param {string} a_client._id - The unique identifier of the client. - * @param {boolean} a_client.is_admin - A flag indicating if the client is an administrator. - * @param {string} a_new_owner_id - The ID of the new owner to assign. - * @param {Array} a_ids - An array of data and collection IDs to process. - * @param {string} a_mode - The mode in which the operation is being performed. It can be one of the following: - * - `g_lib.TT_DATA_GET`: Read data permissions. - * - `g_lib.TT_DATA_PUT`: Write data permissions. - * - `g_lib.TT_REC_ALLOC_CHG`: Allocate/change record permissions. - * - `g_lib.TT_REC_OWNER_CHG`: Change record owner permissions. - * - `g_lib.TT_REC_DEL`: Delete record permissions. - * - `g_lib.TT_DATA_EXPORT`: Export data permissions. - * - * @returns {object} ctxt - An object containing the following properties: - * - `client`: The client information. - * - `new_owner`: The ID of the new owner. - * - `mode`: The mode for the operation. - * - `coll_perm`: The collection permission level. - * - `data_perm`: The data permission level. - * - `coll`: A list of collections. - * - `glob_data`: A list of Globus data records. - * - `ext_data`: A list of external data records. - * - `visited`: A record of visited items during recursion. - * - * @throws {Error} g_lib.ERR_INVALID_MODE - If an invalid mode is passed. - * - * @example - * const result = obj.preprocessItems(client, newOwnerId, dataIds, g_lib.TT_DATA_GET); - * console.log(result.glob_data); - */ + /** + * @function + * Pre-processes data and collection IDs for permissions and required data. + * + * This function examines the specified data and collections for the appropriate permissions + * based on the given mode and recursively processes items (data/collections) in included collections. + * It does not resolve IDs. On success, it returns lists of data records for Globus and external data, + * as well as records without data. Additionally, it returns a flat list of all collections. + * + * In delete mode, only data that is not linked elsewhere will be returned for data records within collections. + * + * @param {object} a_client - The client object containing the client ID and admin status. + * @param {string} a_client._id - The unique identifier of the client. + * @param {boolean} a_client.is_admin - A flag indicating if the client is an administrator. + * @param {string} a_new_owner_id - The ID of the new owner to assign. + * @param {Array} a_ids - An array of data and collection IDs to process. + * @param {string} a_mode - The mode in which the operation is being performed. It can be one of the following: + * - `g_lib.TT_DATA_GET`: Read data permissions. + * - `g_lib.TT_DATA_PUT`: Write data permissions. + * - `g_lib.TT_REC_ALLOC_CHG`: Allocate/change record permissions. + * - `g_lib.TT_REC_OWNER_CHG`: Change record owner permissions. + * - `g_lib.TT_REC_DEL`: Delete record permissions. + * - `g_lib.TT_DATA_EXPORT`: Export data permissions. + * + * @returns {object} ctxt - An object containing the following properties: + * - `client`: The client information. + * - `new_owner`: The ID of the new owner. + * - `mode`: The mode for the operation. + * - `coll_perm`: The collection permission level. + * - `data_perm`: The data permission level. + * - `coll`: A list of collections. + * - `glob_data`: A list of Globus data records. + * - `ext_data`: A list of external data records. + * - `visited`: A record of visited items during recursion. + * + * @throws {Error} g_lib.ERR_INVALID_MODE - If an invalid mode is passed. + * + * @example + * const result = obj.preprocessItems(client, newOwnerId, dataIds, g_lib.TT_DATA_GET); + * console.log(result.glob_data); + */ obj.preprocessItems = function (a_client, a_new_owner_id, a_ids, a_mode) { //console.log( "preprocessItems start" ); var ctxt = { From dfc1d9146d27da6ee7c02c72feccd2d556514a88 Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 08:46:08 -0500 Subject: [PATCH 10/16] Be more selective about eslint rules --- eslint.config.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/eslint.config.js b/eslint.config.js index 8fafa3b1d..f579ace00 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -3,14 +3,14 @@ const jsdocPlugin = require("eslint-plugin-jsdoc"); module.exports = [ { - ignores: ['docs/_static/*'], + ignores: ['docs/_static/**/*'], languageOptions: { globals: { ...globals.jquery, ...globals.node, }, }, - files: ['**/*.js', '**/*.ts'], // Adjust file patterns as needed + files: ['web/**/*.js', 'web/**/*.ts', 'core/**/*.js'], // Adjust file patterns as needed plugins: { jsdoc: jsdocPlugin, }, From 5987c17ebe98d1b8418e466c50fea646c3c9acfc Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 08:47:11 -0500 Subject: [PATCH 11/16] Address items in tasks.js --- core/database/foxx/api/tasks.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/core/database/foxx/api/tasks.js b/core/database/foxx/api/tasks.js index 7579e1129..ab48007dc 100644 --- a/core/database/foxx/api/tasks.js +++ b/core/database/foxx/api/tasks.js @@ -1508,7 +1508,7 @@ var tasks_func = (function () { * @param {Array} a_proj_ids - An array of project IDs to be deleted. * @returns {object} An object containing the task to delete the projects and allocations. * @throws {Array} Throws an error array containing a code and message if the project does - * not exist or the client lacks permissions. + * not exist or the client lacks permissions. * * @example * const result = obj.taskInitProjDelete(client, ['proj_id_1', 'proj_id_2']); @@ -2234,8 +2234,8 @@ var tasks_func = (function () { * @param {string} a_id - The ID of the data record to delete. * @throws {Error} Throws an error if the data record or associated graph objects cannot be deleted. * - * @note This function will delete aliases, notes, tags, and update schema counts and allocations. - * @note It will not delete raw data, but it will adjust the allocation associated with the data record. + * This function will delete aliases, notes, tags, and update schema counts and allocations. + * It will not delete raw data, but it will adjust the allocation associated with the data record. */ obj._deleteDataRecord = function (a_id) { //console.log( "delete rec", a_id ); From af94af079efab583e771f393843e76f96e5dc35a Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 08:59:55 -0500 Subject: [PATCH 12/16] Address additional eslint items with JSDOc --- core/database/foxx/api/process.js | 2 +- web/static/jquery/jquery.js | 58 +++++++++++++++++++++++-------- web/static/main_browse_tab.js | 2 +- 3 files changed, 45 insertions(+), 17 deletions(-) diff --git a/core/database/foxx/api/process.js b/core/database/foxx/api/process.js index a7450702d..551a8e7bb 100644 --- a/core/database/foxx/api/process.js +++ b/core/database/foxx/api/process.js @@ -10,7 +10,7 @@ module.exports = (function () { * @function * Pre-processes data and collection IDs for permissions and required data. * - * This function examines the specified data and collections for the appropriate permissions + * @description This function examines the specified data and collections for the appropriate permissions * based on the given mode and recursively processes items (data/collections) in included collections. * It does not resolve IDs. On success, it returns lists of data records for Globus and external data, * as well as records without data. Additionally, it returns a flat list of all collections. diff --git a/web/static/jquery/jquery.js b/web/static/jquery/jquery.js index a3fd87833..fbbb99c4b 100644 --- a/web/static/jquery/jquery.js +++ b/web/static/jquery/jquery.js @@ -933,8 +933,12 @@ } /** - * Mark a function for special use by Sizzle - * @param {Function} fn The function to mark + * Marks a function for special use by Sizzle. + * This function adds a special `expando` property to the provided function, + * indicating that it should be treated as a special function by Sizzle. + * + * @param {Function} fn The function to mark. + * @returns {Function} The marked function with the `expando` property set to `true`. */ function markFunction(fn) { fn[expando] = true; @@ -942,8 +946,14 @@ } /** - * Support testing using an element - * @param {Function} fn Passed the created element and returns a boolean result + * Supports testing using a provided element. + * This function creates a `fieldset` element, passes it to the provided test function, + * and returns a boolean result based on the outcome of that test. + * The element is removed from the DOM after the test is executed. + * + * @param {Function} fn The test function to apply to the created element. + * The function receives the created element as an argument and should return a boolean result. + * @returns {boolean} Returns `true` if the test function returns a truthy value, `false` otherwise. */ function assert(fn) { var el = document.createElement("fieldset"); @@ -964,9 +974,13 @@ } /** - * Adds the same handler for all of the specified attrs - * @param {String} attrs Pipe-separated list of attributes - * @param {Function} handler The method that will be applied + * Adds the same handler for all of the specified attributes. + * This function splits a pipe-separated list of attributes and applies the given handler function + * to each attribute in the list. + * + * @param {string} attrs A pipe-separated list of attributes to which the handler should be applied. + * @param {Function} handler The handler function to apply to each attribute. + * This function will be assigned to `Expr.attrHandle` for each attribute. */ function addHandle(attrs, handler) { var arr = attrs.split("|"), @@ -1009,8 +1023,12 @@ } /** - * Returns a function to use in pseudos for input types - * @param {String} type + * Returns a function that can be used in pseudos for input types. + * The returned function will check if an element is an `input` element of the specified type. + * + * @param {string} type The input type to match (e.g., "text", "password", etc.). + * @returns {Function} A function that takes an element as an argument and returns `true` if the + * element is an `input` of the specified type, `false` otherwise. */ function createInputPseudo(type) { return function (elem) { @@ -1020,8 +1038,12 @@ } /** - * Returns a function to use in pseudos for buttons - * @param {String} type + * Returns a function that can be used in pseudos for buttons. + * The returned function will check if an element is a `button` or an `input` of the specified type. + * + * @param {string} type The button or input type to match (e.g., "button", "submit", etc.). + * @returns {Function} A function that takes an element as an argument and returns `true` if the + * element is a `button` or an `input` of the specified type, `false` otherwise. */ function createButtonPseudo(type) { return function (elem) { @@ -1031,8 +1053,11 @@ } /** - * Returns a function to use in pseudos for :enabled/:disabled - * @param {Boolean} disabled true for :disabled; false for :enabled + * Returns a function that can be used in pseudos for `:enabled` or `:disabled`. + * The returned function will check if an element is in the `:enabled` or `:disabled` state based on the value of `disabled`. + * + * @param {boolean} disabled `true` for `:disabled`; `false` for `:enabled`. + * @returns {Function} A function that takes an element as an argument and returns `true` if the element matches the `:disabled` or `:enabled` state, `false` otherwise. */ function createDisabledPseudo(disabled) { // Known :disabled false positives: fieldset[disabled] > legend:nth-of-type(n+2) :can-disable @@ -1084,8 +1109,11 @@ } /** - * Returns a function to use in pseudos for positionals - * @param {Function} fn + * Returns a function to use in pseudos for positionals. + * The returned function marks elements found at the specified indexes as matches. + * + * @param {Function} fn A function that returns an array of match indexes. + * @returns {Function} A function that processes the elements at the specified positions. */ function createPositionalPseudo(fn) { return markFunction(function (argument) { diff --git a/web/static/main_browse_tab.js b/web/static/main_browse_tab.js index 2ea8fc136..4e9ebdbc1 100644 --- a/web/static/main_browse_tab.js +++ b/web/static/main_browse_tab.js @@ -2082,7 +2082,7 @@ function treeSelectRange(a_tree, a_node) { * @function * Check if pasting is allowed to the specified node. * - * This function checks whether a paste operation is allowed based on various conditions, + * @description This function checks whether a paste operation is allowed based on various conditions, * such as whether the destination node is valid, whether the source and destination nodes * belong to the same scope, and other restrictions like node types and parent-child relationships. * From d8b2978bfc83dacbdb9023cdf78ec614dad7ca85 Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 09:06:15 -0500 Subject: [PATCH 13/16] Ignore jquery with eslint --- eslint.config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eslint.config.js b/eslint.config.js index f579ace00..4c6e18731 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -3,7 +3,7 @@ const jsdocPlugin = require("eslint-plugin-jsdoc"); module.exports = [ { - ignores: ['docs/_static/**/*'], + ignores: ['docs/_static/**/*', 'web/static/jquery/jquery.js'], languageOptions: { globals: { ...globals.jquery, From 1bfd9ffa22395572e23c5733512b1e21f20944c6 Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 09:09:48 -0500 Subject: [PATCH 14/16] Remove requrie description because seems to be faulty --- eslint.config.js | 1 - 1 file changed, 1 deletion(-) diff --git a/eslint.config.js b/eslint.config.js index 4c6e18731..ab81756b4 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -21,7 +21,6 @@ module.exports = [ 'jsdoc/check-param-names': 'error', 'jsdoc/check-tag-names': 'error', 'jsdoc/check-types': 'error', - 'jsdoc/require-description': 'error', 'jsdoc/require-param': 'error', 'jsdoc/require-param-name': 'error', 'jsdoc/require-param-type': 'error', From d1b31811ccf00531b4c6d33ef57eddefead906d9 Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 09:15:29 -0500 Subject: [PATCH 15/16] Address finicky jsdoc linter --- core/database/foxx/api/process.js | 2 +- web/static/jquery/jquery.js | 27 +++++++++++++++------------ web/static/main_browse_tab.js | 2 +- 3 files changed, 17 insertions(+), 14 deletions(-) diff --git a/core/database/foxx/api/process.js b/core/database/foxx/api/process.js index 551a8e7bb..a7450702d 100644 --- a/core/database/foxx/api/process.js +++ b/core/database/foxx/api/process.js @@ -10,7 +10,7 @@ module.exports = (function () { * @function * Pre-processes data and collection IDs for permissions and required data. * - * @description This function examines the specified data and collections for the appropriate permissions + * This function examines the specified data and collections for the appropriate permissions * based on the given mode and recursively processes items (data/collections) in included collections. * It does not resolve IDs. On success, it returns lists of data records for Globus and external data, * as well as records without data. Additionally, it returns a flat list of all collections. diff --git a/web/static/jquery/jquery.js b/web/static/jquery/jquery.js index fbbb99c4b..727d89dd6 100644 --- a/web/static/jquery/jquery.js +++ b/web/static/jquery/jquery.js @@ -952,7 +952,7 @@ * The element is removed from the DOM after the test is executed. * * @param {Function} fn The test function to apply to the created element. - * The function receives the created element as an argument and should return a boolean result. + * The function receives the created element as an argument and should return a boolean result. * @returns {boolean} Returns `true` if the test function returns a truthy value, `false` otherwise. */ function assert(fn) { @@ -980,7 +980,7 @@ * * @param {string} attrs A pipe-separated list of attributes to which the handler should be applied. * @param {Function} handler The handler function to apply to each attribute. - * This function will be assigned to `Expr.attrHandle` for each attribute. + * This function will be assigned to `Expr.attrHandle` for each attribute. */ function addHandle(attrs, handler) { var arr = attrs.split("|"), @@ -992,10 +992,13 @@ } /** - * Checks document order of two siblings - * @param {Element} a - * @param {Element} b - * @returns {Number} Returns less than 0 if a precedes b, greater than 0 if a follows b + * Compares the document order of two sibling elements. + * Returns a value indicating their relative position in the DOM. + * + * @param {Element} a The first element to compare. + * @param {Element} b The second element to compare. + * @returns {number} A negative number if `a` precedes `b`, a positive number if `a` follows `b`. + * Returns 0 if the elements are identical. */ function siblingCheck(a, b) { var cur = b && a, @@ -1135,8 +1138,8 @@ /** * Checks a node for validity as a Sizzle context - * @param {Element|Object=} context - * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value + * @param {Element|object=} context + * @returns {Element|object|boolean} The input node if acceptable, otherwise a falsy value */ function testContext(context) { return context && typeof context.getElementsByTagName !== "undefined" && context; @@ -1147,8 +1150,8 @@ /** * Detects XML nodes - * @param {Element|Object} elem An element or a document - * @returns {Boolean} True iff elem is a non-HTML XML node + * @param {Element|object} elem An element or a document + * @returns {boolean} True iff elem is a non-HTML XML node */ isXML = Sizzle.isXML = function (elem) { var namespace = elem && elem.namespaceURI, @@ -1162,8 +1165,8 @@ /** * Sets document-related variables once based on the current document - * @param {Element|Object} [doc] An element or document object to use to set the document - * @returns {Object} Returns the current document + * @param {Element|object} [doc] An element or document object to use to set the document + * @returns {object} Returns the current document */ setDocument = Sizzle.setDocument = function (node) { var hasCompare, diff --git a/web/static/main_browse_tab.js b/web/static/main_browse_tab.js index 4e9ebdbc1..2ea8fc136 100644 --- a/web/static/main_browse_tab.js +++ b/web/static/main_browse_tab.js @@ -2082,7 +2082,7 @@ function treeSelectRange(a_tree, a_node) { * @function * Check if pasting is allowed to the specified node. * - * @description This function checks whether a paste operation is allowed based on various conditions, + * This function checks whether a paste operation is allowed based on various conditions, * such as whether the destination node is valid, whether the source and destination nodes * belong to the same scope, and other restrictions like node types and parent-child relationships. * From f19dd7def5b35d0516122bc0e795e04dc2786c52 Mon Sep 17 00:00:00 2001 From: JoshuaSBrown Date: Tue, 7 Jan 2025 10:21:35 -0500 Subject: [PATCH 16/16] Fix js formatting --- core/database/foxx/api/data_router.js | 10 ++++----- core/database/foxx/api/process.js | 18 ++++++++-------- core/database/foxx/api/repo_router.js | 2 +- core/database/foxx/api/task_router.js | 6 +++--- core/database/foxx/api/tasks.js | 12 +++++------ eslint.config.js | 30 +++++++++++++-------------- web/static/jquery/jquery.js | 8 +++---- web/static/main_browse_tab.js | 4 ++-- web/static/util.js | 14 ++++++------- 9 files changed, 52 insertions(+), 52 deletions(-) diff --git a/core/database/foxx/api/data_router.js b/core/database/foxx/api/data_router.js index 23e310301..adaba633d 100644 --- a/core/database/foxx/api/data_router.js +++ b/core/database/foxx/api/data_router.js @@ -1466,10 +1466,10 @@ router /** * @function - * @description Gets the raw data path for local direct access from the specified domain, + * @description Gets the raw data path for local direct access from the specified domain, * if available, for a given data ID and client. - * - * The method checks the client's permissions for the data ID and returns the path to the data + * + * The method checks the client's permissions for the data ID and returns the path to the data * if the client has the required permissions and the data exists in the specified domain. * * @param {object} req - The request object, containing the query parameters. @@ -1478,11 +1478,11 @@ router * @param {string} req.queryParams.id - The data ID (not alias) associated with the data. * @param {string} req.queryParams.domain - The domain from which the data is being requested. * @param {object} res - The response object, used to send the raw data path or error. - * + * * @throws {Error} g_lib.ERR_PERM_DENIED - If the client does not have permission to read the data. * @throws {Error} g_lib.ERR_NO_RAW_DATA - If the raw data is not found. * @throws {Error} g_lib.ERR_INVALID_PARAM - If the data belongs to a different domain than specified. - * + * * @returns {void} - Returns the raw data path in the response if the request is successful. */ router diff --git a/core/database/foxx/api/process.js b/core/database/foxx/api/process.js index a7450702d..c989f0a57 100644 --- a/core/database/foxx/api/process.js +++ b/core/database/foxx/api/process.js @@ -12,9 +12,9 @@ module.exports = (function () { * * This function examines the specified data and collections for the appropriate permissions * based on the given mode and recursively processes items (data/collections) in included collections. - * It does not resolve IDs. On success, it returns lists of data records for Globus and external data, + * It does not resolve IDs. On success, it returns lists of data records for Globus and external data, * as well as records without data. Additionally, it returns a flat list of all collections. - * + * * In delete mode, only data that is not linked elsewhere will be returned for data records within collections. * * @param {object} a_client - The client object containing the client ID and admin status. @@ -42,7 +42,7 @@ module.exports = (function () { * - `visited`: A record of visited items during recursion. * * @throws {Error} g_lib.ERR_INVALID_MODE - If an invalid mode is passed. - * + * * @example * const result = obj.preprocessItems(client, newOwnerId, dataIds, g_lib.TT_DATA_GET); * console.log(result.glob_data); @@ -145,18 +145,18 @@ module.exports = (function () { /** * Recursively preprocesses data and collections for data operations. - * + * * This function performs a depth-first analysis of collections, verifying permissions. - * It ensures that if the required permission is satisfied via inherited ACLs, no further - * permission checks are needed below that point. The function segregates collections and - * data into two categories: those with Globus data (regardless of data size) and those + * It ensures that if the required permission is satisfied via inherited ACLs, no further + * permission checks are needed below that point. The function segregates collections and + * data into two categories: those with Globus data (regardless of data size) and those * with external data. The final result is a flat list of collections and data. - * + * * @param {object} a_ctxt - The recursion context object, containing relevant state such as permissions and mode. * @param {Array} a_ids - The current list of data/collection IDs to process. * @param {number} [a_data_perm] - The inherited data permission (undefined initially). * @param {number} [a_coll_perm] - The inherited collection permission (undefined initially). - * + * * @throws {Array} Throws error with permission or parameter issues. */ obj._preprocessItemsRecursive = function (a_ctxt, a_ids, a_data_perm, a_coll_perm) { diff --git a/core/database/foxx/api/repo_router.js b/core/database/foxx/api/repo_router.js index 0ab414d14..9b869ca00 100644 --- a/core/database/foxx/api/repo_router.js +++ b/core/database/foxx/api/repo_router.js @@ -365,7 +365,7 @@ router /** * @function * @description Calculates the total, per-repo size of selected items. - * Recursively analyzes collections but only counts each data record once regardless of how many places it is linked. + * Recursively analyzes collections but only counts each data record once regardless of how many places it is linked. * This function is used for pre-processing data move operations (e.g., changing allocation or owner). * * @param {object} req - The request object, containing the query parameters. diff --git a/core/database/foxx/api/task_router.js b/core/database/foxx/api/task_router.js index 802f1b41c..7950df72d 100644 --- a/core/database/foxx/api/task_router.js +++ b/core/database/foxx/api/task_router.js @@ -210,15 +210,15 @@ router /** * @function * @description Cleans up a task by removing it from the task dependency graph. - * It removes dependency locks and patches the task dependency graph both upstream and downstream. + * It removes dependency locks and patches the task dependency graph both upstream and downstream. * It returns a list of new runnable tasks if available. * * @param {object} req - The request object containing the task ID in the query parameters and other relevant data in the body. * @param {object} res - The response object used to send the result or an error message. * @returns {void} Sends a list of new runnable tasks to the response. - * + * * @throws {Error} Throws an error if the task does not exist or if there's an issue processing the transaction. - * + * * @example * // Sample usage: * router.post("/abort", function(req, res) { ... }); diff --git a/core/database/foxx/api/tasks.js b/core/database/foxx/api/tasks.js index ab48007dc..0a61d3975 100644 --- a/core/database/foxx/api/tasks.js +++ b/core/database/foxx/api/tasks.js @@ -1500,14 +1500,14 @@ var tasks_func = (function () { /** * Deletes one or more projects and associated data. If a project has no allocations, it can - * be deleted immediately. If a project has allocations and raw data, a task must be initialized - * to delete the allocations. Deletion is exclusive—if any other tasks are using the project or + * be deleted immediately. If a project has allocations and raw data, a task must be initialized + * to delete the allocations. Deletion is exclusive—if any other tasks are using the project or * associated data, the operation will be denied. * * @param {object} a_client - The client object that contains user details and permissions. * @param {Array} a_proj_ids - An array of project IDs to be deleted. * @returns {object} An object containing the task to delete the projects and allocations. - * @throws {Array} Throws an error array containing a code and message if the project does + * @throws {Array} Throws an error array containing a code and message if the project does * not exist or the client lacks permissions. * * @example @@ -2384,14 +2384,14 @@ var tasks_func = (function () { /** * Deletes a project and all associated graph objects immediately. - * - * This function deletes allocations, owned records (e.g., data, collections, groups), + * + * This function deletes allocations, owned records (e.g., data, collections, groups), * and the project itself. It performs a direct deletion of the project and its related * items, and should **NOT** be used on projects containing raw data. * * @param {string} a_proj_id - The ID of the project to delete. * @throws {Error} Throws an error if the project or associated items cannot be deleted. - * + * * Use this function with caution, as it will permanently delete allocations, data, * collections, groups, and the project. It should not be used for projects that * contain raw data. diff --git a/eslint.config.js b/eslint.config.js index ab81756b4..65f726475 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -3,31 +3,31 @@ const jsdocPlugin = require("eslint-plugin-jsdoc"); module.exports = [ { - ignores: ['docs/_static/**/*', 'web/static/jquery/jquery.js'], + ignores: ["docs/_static/**/*", "web/static/jquery/jquery.js"], languageOptions: { globals: { ...globals.jquery, ...globals.node, }, }, - files: ['web/**/*.js', 'web/**/*.ts', 'core/**/*.js'], // Adjust file patterns as needed + files: ["web/**/*.js", "web/**/*.ts", "core/**/*.js"], // Adjust file patterns as needed plugins: { jsdoc: jsdocPlugin, }, rules: { // Enforce proper alignment and formatting of JSDoc - 'jsdoc/check-alignment': 'error', - 'jsdoc/check-indentation': 'error', - 'jsdoc/check-param-names': 'error', - 'jsdoc/check-tag-names': 'error', - 'jsdoc/check-types': 'error', - 'jsdoc/require-param': 'error', - 'jsdoc/require-param-name': 'error', - 'jsdoc/require-param-type': 'error', - 'jsdoc/require-param-description': 'error', - 'jsdoc/require-returns': 'error', - 'jsdoc/require-returns-description': 'error', - 'jsdoc/require-returns-type': 'error', + "jsdoc/check-alignment": "error", + "jsdoc/check-indentation": "error", + "jsdoc/check-param-names": "error", + "jsdoc/check-tag-names": "error", + "jsdoc/check-types": "error", + "jsdoc/require-param": "error", + "jsdoc/require-param-name": "error", + "jsdoc/require-param-type": "error", + "jsdoc/require-param-description": "error", + "jsdoc/require-returns": "error", + "jsdoc/require-returns-description": "error", + "jsdoc/require-returns-type": "error", }, - } + }, ]; diff --git a/web/static/jquery/jquery.js b/web/static/jquery/jquery.js index 727d89dd6..fa337541d 100644 --- a/web/static/jquery/jquery.js +++ b/web/static/jquery/jquery.js @@ -948,7 +948,7 @@ /** * Supports testing using a provided element. * This function creates a `fieldset` element, passes it to the provided test function, - * and returns a boolean result based on the outcome of that test. + * and returns a boolean result based on the outcome of that test. * The element is removed from the DOM after the test is executed. * * @param {Function} fn The test function to apply to the created element. @@ -975,7 +975,7 @@ /** * Adds the same handler for all of the specified attributes. - * This function splits a pipe-separated list of attributes and applies the given handler function + * This function splits a pipe-separated list of attributes and applies the given handler function * to each attribute in the list. * * @param {string} attrs A pipe-separated list of attributes to which the handler should be applied. @@ -1030,7 +1030,7 @@ * The returned function will check if an element is an `input` element of the specified type. * * @param {string} type The input type to match (e.g., "text", "password", etc.). - * @returns {Function} A function that takes an element as an argument and returns `true` if the + * @returns {Function} A function that takes an element as an argument and returns `true` if the * element is an `input` of the specified type, `false` otherwise. */ function createInputPseudo(type) { @@ -1045,7 +1045,7 @@ * The returned function will check if an element is a `button` or an `input` of the specified type. * * @param {string} type The button or input type to match (e.g., "button", "submit", etc.). - * @returns {Function} A function that takes an element as an argument and returns `true` if the + * @returns {Function} A function that takes an element as an argument and returns `true` if the * element is a `button` or an `input` of the specified type, `false` otherwise. */ function createButtonPseudo(type) { diff --git a/web/static/main_browse_tab.js b/web/static/main_browse_tab.js index 2ea8fc136..c7943e3c8 100644 --- a/web/static/main_browse_tab.js +++ b/web/static/main_browse_tab.js @@ -2088,9 +2088,9 @@ function treeSelectRange(a_tree, a_node) { * * @param {object} dest_node - The candidate destination node where the paste operation is being attempted. * @param {object} src_node - The node being dragged or copied to the destination. - * + * * @returns {string|boolean} Returns "over" if the paste is allowed, otherwise returns `false`. - * + * * There is additional source information in the pasteSourceParent and pasteCollections variables. */ function pasteAllowed(dest_node, src_node) { diff --git a/web/static/util.js b/web/static/util.js index b1dfa4cf1..4b85ea364 100644 --- a/web/static/util.js +++ b/web/static/util.js @@ -771,23 +771,23 @@ export function dataGet(a_ids, a_cb) { /** * Basic implementation of `get_authorize_url` from the Globus SDK. - * - * This function generates the authorization URL that a user can follow to provide + * + * This function generates the authorization URL that a user can follow to provide * authorization and consent via Globus Auth. * * @param {UUID} client_id - The UUID of the Globus authentication client. * @param {string} redirect_uri - The URI-safe application-wide Globus Auth redirect URI. - * @param {Array} [requested_scopes=[]] - The scopes on the token(s) being requested. - * In the case of accessing a mapped collection, this should include the mapped + * @param {Array} [requested_scopes=[]] - The scopes on the token(s) being requested. + * In the case of accessing a mapped collection, this should include the mapped * collection's UUID, such as: `https://auth.globus.org/scopes/YOUR-UUID-HERE/data_access`. * @param {string} [state="_default"] - Allows the application to pass information back to itself. * @param {boolean} [refresh_tokens=false] - Request refresh tokens in addition to access tokens. * @param {object} [query_params={}] - Additional parameters to be included in the authorization URL. - * + * * @returns {string} The URL a user can follow to provide authorization and consent via Globus. - * + * * @throws {Error} If either `client_id` or `redirect_uri` are not provided. - * + * * @example * const url = globusGetAuthorizeURL( * 'your-client-id',