docs: Update type definitions and JSDoc for parser functions (#15)

Co-authored-by: csmig <[email protected]>

ReviewParser.js

@@ -4,7 +4,20 @@ import decode from './decode.js'
 const decodeHTML = function () {
   return decode(arguments[1])
 }
-
+/**
+ * Parses data from a CKL format into a format suitable for further processing.
+ * 
+ * @param {ParserParams} ReviewsFromCklParams - The parameters object containing:
+ * @param {string} ReviewsFromCklParams.data - The CKL data to be processed.
+ * @param {FieldSettings} ReviewsFromCklParams.fieldSettings - Settings related to detail and comment fields.
+ * @param {boolean} ReviewsFromCklParams.allowAccept - Flag indicating whether accepting a review is allowed.
+ * @param {ImportOptions} ReviewsFromCklParams.importOptions - Options for handling import behavior.
+ * @param {*} ReviewsFromCklParams.sourceRef - A reference to the source of the CKL data.
+ * 
+ * @returns {ParseResult} An object containing parsed ckl data
+ * 
+ * @throws {Error} 
+ */
 export function reviewsFromCkl(
   {
     data,
@@ -73,7 +86,7 @@ export function reviewsFromCkl(
   if (returnObj.checklists.length === 0) {
     throw (new Error("STIG_INFO element has no SI_DATA for SID_NAME == stigId"))
   }
-  returnObj.error = errorMessages
+  returnObj.errors = errorMessages
 
   return (returnObj)
 
@@ -402,6 +415,22 @@ export function reviewsFromCkl(
   }
 }
 
+
+/**
+ * Parses data from a XCCDF format into a format suitable for further processing.
+ * 
+ * @param {ParserXccdfParams} ReviewsFromXccdfParams - The parameters object containing:
+ * @param {string} ReviewsFromXccdfParams.data - The xccdf data to be processed.
+ * @param {FieldSettings} ReviewsFromXccdfParams.fieldSettings - Settings related to detail and comment fields.
+ * @param {boolean} ReviewsFromXccdfParams.allowAccept - Flag indicating whether accepting a review is allowed.
+ * @param {ImportOptions} ReviewsFromXccdfParams.importOptions - Options for handling import behavior.
+ * @param {ScapBenchmarkMap} ReviewsFromXccdfParams.scapBenchmarkMap - A map of SCAP benchmark IDs to their corresponding STIG IDs.
+ * @param {*} ReviewsFromXccdfParams.sourceRef - A reference to the source of the xccdf data.
+ * 
+ * @returns {ParseResult} An object containing parsed xccdf data
+ * 
+ * @throws {Error} 
+ */
 export function reviewsFromXccdf(
   {
     data,
@@ -412,6 +441,7 @@ export function reviewsFromXccdf(
     sourceRef
   }) {
 
+
   // Parse the XML
   const parseOptions = {
     allowBooleanAttributes: false,
@@ -723,6 +753,21 @@ export function reviewsFromXccdf(
   }
 }
 
+
+/**
+ * Parses data from a cklb format into a format suitable for further processing.
+ * 
+ * @param {ParserParams} ReviewsFromCklbParams - The parameters object containing:
+ * @param {string} ReviewsFromCklbParams.data - The cklb data to be processed.
+ * @param {FieldSettings} ReviewsFromCklbParams.fieldSettings - Settings related to detail and comment fields.
+ * @param {boolean} ReviewsFromCklbParams.allowAccept - Flag indicating whether accepting a review is allowed.
+ * @param {ImportOptions} ReviewsFromCklbParams.importOptions - Options for handling import behavior.
+ * @param {*} ReviewsFromCklbParams.sourceRef - A reference to the source of the cklb data.
+ * 
+ * @returns {ParseResult} An object containing parsed cklb data
+ * 
+ * @throws {Error} 
+ */
 export function reviewsFromCklb(
   {
     data,

TaskObject.js

@@ -119,11 +119,15 @@ export default class TaskObject {
       const apiAsset = this.#findAssetFromParsedTarget(parsedResult.target)
       if (!apiAsset && !options.createObjects) {
         // Bail if the asset doesn't exist and we shouldn't create it
-        this.errors.push({
-          message: `asset does not exist for target and createObjects is false`,
-          target: parsedResult.target,
-          sourceRef: parsedResult.sourceRef
-        })
+
+        /** @type {TaskObjectError} */
+        const error = {
+            message: `asset does not exist for target and createObjects is false`,
+            target: parsedResult.target,
+            sourceRef: parsedResult.sourceRef
+        }
+
+        this.errors.push(error)
         continue
       }
       // Try to find the target in our Map()

index.d.ts

@@ -73,7 +73,7 @@ interface ParsedReview {
     comment: string;
     detail: string;
     result: ReviewResult;
-    resultEngine: ResultEngine | null
+    resultEngine: ResultEngine | null;
     ruleId: string;
     status: ReviewStatus;
 }
@@ -94,13 +94,13 @@ interface ParsedChecklist {
     benchmarkId: string;
     reviews: ParsedReview[];
     revisionStr: string;
-    errors: string[];
     stats: ParsedChecklistStats;
     sourceRef: any;
 }
 
 interface ParseResult {
     target: ParsedTarget;
+    errors?: string[]; // only used in the ckl parser
     checklists: ParsedChecklist[];
     sourceRef: any;
 }
@@ -138,15 +138,72 @@ interface TaskAssetValue {
     sourceRefs: any[];
 }
 
+interface TaskObjectError { 
+  message: string;
+  target: ParsedTarget;
+  sourceRef: any;
+}
+
 declare class TaskObject {
     constructor (options: TaskObjectParams);
     apiAssets: ApiAsset[];
     apiStigs: ApiStig[];
     #assetNameMap: Map<string, ApiAsset>;
     #benchmarkIdMap: Map<string, string[]>;
     #cklHostnameMap: Map<string, ApiAsset[]>;
-    errors: array;
+    errors: TaskObjectError[];
     parsedResults: TaskObjectParseResult[];
     sourceRefs: any[];
     taskAssets: Map<string, TaskAssetValue>;
 }
+
+type AutoStatus = 'null' | 'saved' | 'submitted' | 'accepted';
+type Unreviewed = 'commented' | 'never' | 'always';
+type UnreviewedCommented = 'informational' | 'notchecked';
+type EmptyCommentDetailType = 'replace' | 'ignore' | 'import';
+type RequiredType = 'always' | 'findings' | 'optional';
+type EnabledType = 'always' | 'findings';
+
+interface FieldOptions {
+  enabled: EnabledType;
+  required: RequiredType;
+};
+
+interface FieldSettings {
+  detail: FieldOptions;
+  comment: FieldOptions;
+}
+
+interface ImportOptions {
+  autoStatus: AutoStatus;
+  unreviewed: Unreviewed;
+  unreviewedCommented: UnreviewedCommented;
+  emptyDetail: EmptyCommentDetailType;
+  emptyComment: EmptyCommentDetailType;
+  allowCustom: boolean;
+}
+
+interface ParserParams {
+  data: string;
+  fieldSettings: FieldSettings;
+  allowAccept: boolean;
+  importOptions: ImportOptions;
+  sourceRef: any;
+}
+
+interface ImportOptions {
+  autoStatus: AutoStatus;
+  unreviewed: Unreviewed;
+  unreviewedCommented: UnreviewedCommented;
+  emptyDetail: EmptyCommentDetailType;
+  emptyComment: EmptyCommentDetailType;
+  allowCustom: boolean;
+}
+
+interface ScapBenchmarkMap {
+  [key: string]: string;
+}
+
+interface ParserXccdfParams extends ParserParams{
+  scapBenchmarkMap: ScapBenchmarkMap;
+}