chore: adds jsdocs

Author: snehaljha-sf

src/migration/related/FlexipageMigration.ts

@@ -1,3 +1,10 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
 import * as fs from 'fs';
 import * as path from 'path';
 import * as shell from 'shelljs';
@@ -13,28 +20,83 @@ import { transformFlexipageBundle } from '../../utils/flexipage/flexiPageTransfo
 import { Flexipage } from '../interfaces';
 import { BaseRelatedObjectMigration } from './BaseRealtedObjectMigration';
 
+/**
+ * FlexipageMigration handles the migration and assessment of FlexiPage components
+ * in Salesforce OmniStudio migration operations.
+ *
+ * This class provides functionality to:
+ * - Assess FlexiPage components for migration readiness
+ * - Migrate FlexiPage components to the target format
+ * - Process FlexiPage XML files and transform their content
+ * - Generate assessment reports with detailed status information
+ * - Handle errors and provide detailed error reporting
+ *
+ * The migration process involves:
+ * - Retrieving FlexiPage metadata from the Salesforce org
+ * - Parsing and analyzing FlexiPage XML files
+ * - Transforming component structures and properties
+ * - Generating diff information for visual comparison
+ * - Writing transformed files back to the project structure
+ */
 export class FlexipageMigration extends BaseRelatedObjectMigration {
+  /** Messages instance for internationalization */
   private messages: Messages;
 
+  /**
+   * Creates a new FlexipageMigration instance.
+   *
+   * @param projectPath - The path to the Salesforce project
+   * @param namespace - The namespace for the migration operation
+   * @param org - The Salesforce org connection
+   * @param messages - Messages instance for internationalization
+   */
   public constructor(projectPath: string, namespace: string, org: Org, messages: Messages) {
     super(projectPath, namespace, org);
     this.messages = messages;
   }
 
+  /**
+   * Returns the object type constant for FlexiPage components.
+   *
+   * @returns The FlexiPage constant string
+   */
   public processObjectType(): string {
     return Constants.FlexiPage;
   }
 
+  /**
+   * Performs assessment of FlexiPage components to determine migration readiness.
+   *
+   * @returns Array of FlexiPage assessment information
+   */
   public assess(): FlexiPageAssessmentInfo[] {
     Logger.info(this.messages.getMessage('assessingFlexiPages'));
     return this.process('assess');
   }
 
+  /**
+   * Performs migration of FlexiPage components to the target format.
+   *
+   * @returns Array of FlexiPage assessment information after migration
+   */
   public migrate(): FlexiPageAssessmentInfo[] {
     Logger.info(this.messages.getMessage('migratingFlexiPages'));
     return this.process('migrate');
   }
 
+  /**
+   * Processes FlexiPage files in either assessment or migration mode.
+   *
+   * This method:
+   * - Retrieves FlexiPage metadata from the Salesforce org
+   * - Reads and processes each FlexiPage XML file
+   * - Transforms the content based on the specified mode
+   * - Handles errors and provides detailed logging
+   * - Generates progress indicators for long-running operations
+   *
+   * @param mode - The processing mode: 'assess' for analysis only, 'migrate' for actual transformation
+   * @returns Array of FlexiPage assessment information
+   */
   private process(mode: 'assess' | 'migrate'): FlexiPageAssessmentInfo[] {
     Logger.info(this.messages.getMessage('retrievingFlexiPages'));
     shell.cd(this.projectPath);
@@ -76,6 +138,22 @@ export class FlexipageMigration extends BaseRelatedObjectMigration {
     return flexPageAssessmentInfos;
   }
 
+  /**
+   * Processes a single FlexiPage file for assessment or migration.
+   *
+   * This method:
+   * - Reads the FlexiPage XML file content
+   * - Parses the XML structure into a JavaScript object
+   * - Transforms the FlexiPage bundle using the flexipage transformer
+   * - Generates diff information for visual comparison
+   * - Writes transformed content back to file in migration mode
+   * - Handles errors and provides detailed error information
+   *
+   * @param fileName - The name of the FlexiPage file
+   * @param filePath - The full path to the FlexiPage file
+   * @param mode - The processing mode: 'assess' or 'migrate'
+   * @returns FlexiPage assessment information with status and error details
+   */
   private processFlexiPage(fileName: string, filePath: string, mode: 'assess' | 'migrate'): FlexiPageAssessmentInfo {
     Logger.logVerbose(this.messages.getMessage('startingFlexiPageProcessing', [fileName]));
     const fileContent = fs.readFileSync(filePath, 'utf8');

src/utils/XMLUtil.ts

@@ -1,9 +1,39 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
 import { XMLParser, XMLBuilder } from 'fast-xml-parser';
 
+/**
+ * XMLUtil provides XML parsing and building functionality using the fast-xml-parser library.
+ *
+ * This class handles:
+ * - Parsing XML strings into JavaScript objects
+ * - Building XML strings from JavaScript objects
+ * - Configuring parser options for Salesforce metadata XML structures
+ * - Handling arrays for specific FlexiPage elements
+ */
 class XMLUtil {
+  /** XML parser instance configured for Salesforce metadata */
   private parser: XMLParser;
+  /** XML builder instance configured for formatted output */
   private builder: XMLBuilder;
 
+  /**
+   * Initializes the XMLUtil with configured parser and builder instances.
+   *
+   * The parser is configured to:
+   * - Preserve attributes with '@' prefix
+   * - Handle arrays for FlexiPage regions and item instances
+   * - Parse Salesforce metadata XML structures
+   *
+   * The builder is configured to:
+   * - Format output with proper indentation
+   * - Preserve attributes with '@' prefix
+   */
   public constructor() {
     this.parser = new XMLParser({
       ignoreAttributes: false,
@@ -20,11 +50,23 @@ class XMLUtil {
     });
   }
 
+  /**
+   * Parses an XML string into a JavaScript object.
+   *
+   * @param xml - The XML string to parse
+   * @returns JavaScript object representation of the XML structure
+   */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   public parse(xml: string): any {
     return this.parser.parse(xml);
   }
 
+  /**
+   * Builds an XML string from a JavaScript object.
+   *
+   * @param json - The JavaScript object to convert to XML
+   * @returns Formatted XML string
+   */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   public build(json: any): string {
     return this.builder.build(json);

src/utils/flexipage/flexiPageTransformer.ts

@@ -1,15 +1,47 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
 import { Flexipage, FlexiComponentInstanceProperty } from '../../migration/interfaces';
 
+/** Attributes to remove during transformation */
 const attrsToRemove = ['target'];
 
+/** Component name to look for during transformation */
 const lookupComponentName = 'vlocityLWCOmniWrapper';
+/** Target component name after transformation */
 const targetComponentName = 'runtime_omnistudio:omniscript';
+/** Target identifier after transformation */
 const targetIdentifier = 'runtime_omnistudio_omniscript';
 
+/**
+ * Transforms a Flexipage bundle by replacing vlocityLWCOmniWrapper components
+ * with runtime_omnistudio:omniscript components and updating their properties.
+ *
+ * This function performs the following transformations:
+ * - Identifies vlocityLWCOmniWrapper components within the specified namespace
+ * - Removes the 'target' property from component instance properties
+ * - Creates new properties for language, subType, theme, and type
+ * - Updates the component name and identifier to the target runtime component
+ *
+ * @param ogBundle - The original Flexipage bundle to transform
+ * @param namespace - The namespace to filter components by
+ * @returns The transformed Flexipage bundle if changes were made, or false if no changes were needed
+ * @throws Error if the 'target' property is not found for a component
+ */
 export function transformFlexipageBundle(ogBundle: Flexipage, namespace: string): Flexipage | boolean {
   const bundle: Flexipage = JSON.parse(JSON.stringify(ogBundle)) as Flexipage;
   let changes = false;
 
+  /**
+   * Filters out properties that should be removed during transformation
+   *
+   * @param item - The component instance property to check
+   * @returns true if the property should be kept, false if it should be removed
+   */
   const propRemover = (item: FlexiComponentInstanceProperty): boolean => {
     return !attrsToRemove.includes(item.name);
   };
@@ -48,7 +80,13 @@ export function transformFlexipageBundle(ogBundle: Flexipage, namespace: string)
   return changes ? bundle : false;
 }
 
-// will change after Aastha's utility
+/**
+ * Creates new properties for the transformed component.
+ * TODO: This function will be updated after Aastha's utility is available.
+ *
+ * @param _property - The original property value (currently unused)
+ * @returns Object containing the new properties for the transformed component
+ */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 function createNewProps(_property: string): Record<string, string> {
   return {

src/utils/resultsbuilder/FlexipageAssessmentReporter.ts

@@ -1,3 +1,9 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
 import { FlexiPageAssessmentInfo } from '../interfaces';
 import { FileDiffUtil } from '../lwcparser/fileutils/FileDiffUtil';
 import { OmnistudioOrgDetails } from '../orgUtils';
@@ -9,10 +15,31 @@ import {
 } from '../reportGenerator/reportInterfaces';
 import { createFilterGroupParam, createRowDataParam, getOrgDetailsForReport } from '../reportGenerator/reportUtil';
 
+/**
+ * FlexipageAssessmentReporter provides functionality to generate assessment reports
+ * for Flexipage migration operations. It processes FlexiPage assessment information
+ * and converts it into report-ready data structures.
+ *
+ * This class handles:
+ * - Converting FlexiPage assessment data into report parameters
+ * - Generating summary statistics for different migration statuses
+ * - Creating report rows with proper formatting and styling
+ * - Managing header groups and filter options for reports
+ * - Ensuring unique row IDs for report data
+ */
 export class FlexipageAssessmentReporter {
+  /** Static counter for generating unique row IDs */
   private static rowId = 0;
+  /** Prefix for row ID generation */
   private static rowIdPrefix = 'flexipage-row-data-';
 
+  /**
+   * Generates comprehensive assessment data for Flexipage migration reports.
+   *
+   * @param flexipageAssessmentInfos - Array of FlexiPage assessment information
+   * @param omnistudioOrgDetails - Organization details for the report
+   * @returns Complete report parameters including title, headers, filters, and rows
+   */
   public static getFlexipageAssessmentData(
     flexipageAssessmentInfos: FlexiPageAssessmentInfo[],
     omnistudioOrgDetails: OmnistudioOrgDetails
@@ -29,6 +56,12 @@ export class FlexipageAssessmentReporter {
     };
   }
 
+  /**
+   * Generates summary statistics for Flexipage assessment data.
+   *
+   * @param flexipageAssessmentInfos - Array of FlexiPage assessment information
+   * @returns Array of summary items with counts and CSS classes for different statuses
+   */
   public static getSummaryData(
     flexipageAssessmentInfos: FlexiPageAssessmentInfo[]
   ): Array<import('../reportGenerator/reportInterfaces').SummaryItemDetailParam> {
@@ -51,6 +84,12 @@ export class FlexipageAssessmentReporter {
     ];
   }
 
+  /**
+   * Converts FlexiPage assessment information into report row data.
+   *
+   * @param flexipageAssessmentInfos - Array of FlexiPage assessment information
+   * @returns Array of report row parameters with formatted data and unique row IDs
+   */
   private static getRowsForReport(flexipageAssessmentInfos: FlexiPageAssessmentInfo[]): ReportRowParam[] {
     if (!flexipageAssessmentInfos || flexipageAssessmentInfos.length === 0) {
       return [];
@@ -98,6 +137,11 @@ export class FlexipageAssessmentReporter {
     }));
   }
 
+  /**
+   * Generates header groups for Flexipage assessment reports.
+   *
+   * @returns Array of header group parameters defining the report column structure
+   */
   private static getHeaderGroupsForReport(): ReportHeaderGroupParam[] {
     return [
       {
@@ -126,6 +170,11 @@ export class FlexipageAssessmentReporter {
       },
     ];
   }
+  /**
+   * Generates filter groups for Flexipage assessment reports.
+   *
+   * @returns Array of filter group parameters for filtering by errors and status
+   */
   private static getFilterGroupsForReport(): FilterGroupParam[] {
     return [
       createFilterGroupParam('Filter by Errors', 'errors', ['Has Errors', 'Has No Errors']),