fix: add jsdoc

Author: yelizhenden-mdb

tools/spectral/ipa/metrics/collector.js

@@ -36,16 +36,16 @@ class Collector {
     });
   }
 
-  add(type, componentId, ruleName, exceptionReason = null ) {
+  add(type, componentId, ruleName, exceptionReason = null) {
     if (componentId && ruleName && type) {
       if (!Object.values(EntryType).includes(type)) {
         throw new Error(`Invalid entry type: ${type}`);
       }
 
       componentId = componentId.join('.');
-      const entry = {componentId, ruleName};
+      const entry = { componentId, ruleName };
 
-      if(type === EntryType.EXCEPTION && exceptionReason) {
+      if (type === EntryType.EXCEPTION && exceptionReason) {
         entry.exceptionReason = exceptionReason;
       }
 

tools/spectral/ipa/rulesets/functions/eachCustomMethodMustBeGetOrPost.js

@@ -1,9 +1,6 @@
 import { isCustomMethod } from './utils/resourceEvaluation.js';
 import { collectException, hasException } from './utils/exceptions.js';
-import {
-  collectAdoption,
-  collectAndReturnViolation,
-} from './utils/collectionUtils.js';
+import { collectAdoption, collectAndReturnViolation } from './utils/collectionUtils.js';
 
 const RULE_NAME = 'xgen-IPA-109-custom-method-must-be-GET-or-POST';
 const ERROR_MESSAGE = 'The HTTP method for custom methods must be GET or POST.';

tools/spectral/ipa/rulesets/functions/eachCustomMethodMustUseCamelCase.js

@@ -1,10 +1,7 @@
 import { getCustomMethodName, isCustomMethod } from './utils/resourceEvaluation.js';
 import { collectException, hasException } from './utils/exceptions.js';
 import { casing } from '@stoplight/spectral-functions';
-import {
-  collectAdoption,
-  collectAndReturnViolation,
-} from './utils/collectionUtils.js';
+import { collectAdoption, collectAndReturnViolation } from './utils/collectionUtils.js';
 
 const RULE_NAME = 'xgen-IPA-109-custom-method-must-use-camel-case';
 

tools/spectral/ipa/rulesets/functions/eachEnumValueMustBeUpperSnakeCase.js

@@ -1,10 +1,7 @@
 import { collectException, hasException } from './utils/exceptions.js';
 import { resolveObject } from './utils/componentUtils.js';
 import { casing } from '@stoplight/spectral-functions';
-import {
-  collectAdoption,
-  collectAndReturnViolation,
-} from './utils/collectionUtils.js';
+import { collectAdoption, collectAndReturnViolation } from './utils/collectionUtils.js';
 
 const RULE_NAME = 'xgen-IPA-123-enum-values-must-be-upper-snake-case';
 const ERROR_MESSAGE = 'enum value must be UPPER_SNAKE_CASE.';
@@ -43,5 +40,4 @@ export default (input, _, { path, documentInventory }) => {
   } else {
     return collectAndReturnViolation(path, RULE_NAME, errors);
   }
-
 };

tools/spectral/ipa/rulesets/functions/eachPathAlternatesBetweenResourceNameAndPathParam.js

@@ -1,9 +1,6 @@
 import { isPathParam } from './utils/componentUtils.js';
 import { collectException, hasException } from './utils/exceptions.js';
-import {
-  collectAdoption,
-  collectAndReturnViolation,
-} from './utils/collectionUtils.js';
+import { collectAdoption, collectAndReturnViolation } from './utils/collectionUtils.js';
 
 const RULE_NAME = 'xgen-IPA-102-path-alternate-resource-name-path-param';
 const ERROR_MESSAGE = 'API paths must alternate between resource name and path params.';

tools/spectral/ipa/rulesets/functions/eachResourceHasGetMethod.js

@@ -7,10 +7,7 @@ import {
   getResourcePaths,
 } from './utils/resourceEvaluation.js';
 import { collectException, hasException } from './utils/exceptions.js';
-import {
-  collectAdoption,
-  collectAndReturnViolation,
-} from './utils/collectionUtils.js';
+import { collectAdoption, collectAndReturnViolation } from './utils/collectionUtils.js';
 
 const RULE_NAME = 'xgen-IPA-104-resource-has-GET';
 const ERROR_MESSAGE = 'APIs must provide a get method for resources.';

tools/spectral/ipa/rulesets/functions/exceptionExtensionFormat.js

@@ -1,7 +1,4 @@
-import {
-  collectAdoption,
-  collectAndReturnViolation,
-} from './utils/collectionUtils.js';
+import { collectAdoption, collectAndReturnViolation } from './utils/collectionUtils.js';
 
 const RULE_NAME = 'xgen-IPA-005-exception-extension-format';
 const ERROR_MESSAGE = 'IPA exceptions must have a valid rule name and a reason.';

tools/spectral/ipa/rulesets/functions/singletonHasNoId.js

@@ -7,10 +7,7 @@ import {
 } from './utils/resourceEvaluation.js';
 import { collectException, hasException } from './utils/exceptions.js';
 import { getAllSuccessfulGetResponseSchemas } from './utils/methodUtils.js';
-import {
-  collectAdoption,
-  collectAndReturnViolation,
-} from './utils/collectionUtils.js';
+import { collectAdoption, collectAndReturnViolation } from './utils/collectionUtils.js';
 
 const RULE_NAME = 'xgen-IPA-113-singleton-must-not-have-id';
 const ERROR_MESSAGE = 'Singleton resources must not have a user-provided or system-generated ID.';
@@ -23,7 +20,7 @@ export default (input, opts, { path, documentInventory }) => {
   }
 
   if (hasException(input, RULE_NAME)) {
-    collectException(input, RULE_NAME, path)
+    collectException(input, RULE_NAME, path);
     return;
   }
 

tools/spectral/ipa/rulesets/functions/utils/collectionUtils.js

@@ -1,5 +1,15 @@
 import collector, { EntryType } from '../../../metrics/collector.js';
 
+/**
+ * Collects a violation entry and returns formatted error data.
+ *
+ * @param {string} path - The JSON path for the object where the rule violation occurred.
+ * @param {string} ruleName - The name of the rule that was violated.
+ * @param {string|Array<Object>} errorData - The error information. Can be either a string message or an array of error objects.
+ * @returns {Array<Object>} An array of error objects. Each object has a 'message' property.
+ * @throws {Error} Throws an error if errorData is neither a string nor an array.
+ *
+ */
 export function collectAndReturnViolation(path, ruleName, errorData) {
   collector.add(EntryType.VIOLATION, path, ruleName);
 
@@ -12,6 +22,12 @@ export function collectAndReturnViolation(path, ruleName, errorData) {
   }
 }
 
+/**
+ * Collects an adoption entry.
+ *
+ * @param {string} path - The JSON path for the object where the rule adoption occurred.
+ * @param {string} ruleName - The name of the rule that was adopted.
+ */
 export function collectAdoption(path, ruleName) {
   collector.add(EntryType.ADOPTION, path, ruleName);
-}
+}

tools/spectral/ipa/rulesets/functions/utils/exceptions.js

@@ -17,15 +17,15 @@ export function hasException(object, ruleName) {
 }
 
 /**
- * Collects the information about the object if the object has an exception defined for the given rule
+ * Collects an exception entry.
  *
  * @param object the object to evaluate
- * @param ruleName the name of the exempted rule
- * @param path the JSON path to the object
+ * @param {string} path - The JSON path for the object where the rule exception occurred.
+ * @param {string} ruleName - The name of the rule that the exception is defined for.
  */
 export function collectException(object, ruleName, path) {
   let exceptionReason = object[EXCEPTION_EXTENSION][ruleName];
-  if(exceptionReason) {
+  if (exceptionReason) {
     collector.add(EntryType.EXCEPTION, path, ruleName, exceptionReason);
   }
 }