🔀 Major Refactor of NetSuite CustomModules Template (PR #9)

🚀 Major Refactor of NetSuite CustomModules Template (PR #9)

- 📘 Updated `readme.hbs` with an enhanced introduction section focusing on SuiteScript module testing and CI/CD integration, aligning with NS 2023.2 standards.
- 🛠️ Added new scripts (`flattenObjectPath.sh`, `rmDependents.sh`, `web.config.private`) to improve project management and security.
- 📚 Enhanced documentation generation process, integrating JSDoc comments and Markdown for automated class documentation.
- 📈 Implemented CI/CD pipeline enhancements for various environments (production, multiple sandboxes) and refined Azure Pipeline configurations.
- 🔒 Introduced `web.config.private` and `web.config.search.private` for enhanced security and UI functionality in the Documentation WebApp.
- 🧪 Updated unit test configurations and mock setups to ensure comprehensive testing coverage and reliability.
- 🐛 Fixed various issues in GitHub pipeline, including handling of existing directories and CSS file management.
- 📄 Added detailed comments and structured organization to key configuration files (`manifest.tpl.xml`, `jsDocsConf.json`).
- 🌟 General improvements for project clarity, efficiency, and compliance with the latest NetSuite standards.

This PR represents a significant overhaul of the NetSuite CustomModules Template, ensuring a robust, efficient, and up-to-date development environment for SuiteScript projects.

Author: devnetkc

.ci/config/docsMD.config.min.js

@@ -0,0 +1,54 @@
+/**
+ * @format
+ * Custom Module Paths for Jest Testing in NetSuite SuiteCloud Projects
+ *
+ * Purpose:
+ * This file defines a mapping between SuiteScript modules and their corresponding file paths
+ * within the project structure. It is used in Jest testing to resolve SuiteScript module imports
+ * that would otherwise not be recognized in the Jest environment.
+ *
+ * How It Works:
+ * - Each object in the CustomModulePaths array represents a mapping between a SuiteScript module
+ *   (as used in NetSuite) and its equivalent local file path.
+ * - 'module' key specifies the SuiteScript module path as it is referred to in the SuiteScript files.
+ * - 'path' key provides the actual file path relative to the root directory of the project.
+ * - This mapping allows Jest to correctly locate and import SuiteScript modules during tests.
+ *
+ * Integration with Jest:
+ * - This mapping is imported into the Jest configuration (jest.config.js) under 'customStubs'.
+ * - It enables Jest to understand and resolve the custom module paths specific to SuiteCloud projects,
+ *   facilitating the testing of SuiteScript modules with Jest.
+ *
+ * Example Format:
+ * - Suppose a SuiteScript module is located at 'src/FileCabinet/SuiteScripts/Modules/aModule.js'
+ *   and is referred to in SuiteScripts as '/SuiteScripts/Modules/aModule'.
+ * - The mapping object would be:
+ *   {
+ *     module: '/SuiteScripts/Modules/aModule',
+ *     path: '<rootDir>src/FileCabinet/SuiteScripts/Modules/aModule.js',
+ *   }
+ * - This tells Jest that whenever '/SuiteScripts/Modules/aModule' is imported in a test,
+ *   it should actually load from the specified path in the project directory.
+ */
+
+const CustomModulePaths = [
+  {
+    module: '/SuiteScripts/Modules/aModule',
+    path: '<rootDir>src/FileCabinet/SuiteScripts/Modules/aModule',
+  },
+  {
+    module: '/SuiteScripts/Modules/aModule.min',
+    path: '<rootDir>src/FileCabinet/SuiteScripts/Modules/aModule.js',
+  },
+  {
+    module: '/SuiteScripts/CS/customModule_CS',
+    path: '<rootDir>src/FileCabinet/SuiteScripts/CS/customModule_CS',
+  },
+  {
+    module: '/SuiteScripts/CS/customModule_CS.min',
+    path: '<rootDir>src/FileCabinet/SuiteScripts/CS/customModule_CS.js',
+  },
+];
+module.exports = {
+  CustomModulePaths,
+};

.ci/config/jest/modulePaths.js

@@ -2,12 +2,41 @@
   "source": {
     "includePattern": ".+\\.js(doc|x)?$",
     "include": ["."],
-    "exclude": ["node_modules", "__tests__", "jest.config.js"],
+    "exclude": ["node_modules", "docs"],
     "excludePattern": ".+\\.min\\.js$"
   },
   "recurseDepth": 10,
   "opts": {
-    "destination": "./docs/",
-    "recurse": true
+    "readme": "./README.md",
+    "destination": "./docs/private/",
+    "recurse": true,
+    "template": "node_modules/clean-jsdoc-theme",
+    "theme_opts": {
+      "title": "<a href=\"index.html\"><div class=\"sidebar-title\"><div class=\"image\"><img src=\"../assets/img/docs-icon.png\" \\></div><div class=\"text\">NetSuite Docs</div></div></a>",
+      "homepageTitle": "NetSuite Project Documentation",
+      "displayModuleHeader": true,
+      "include_css": ["docs/assets/templates/jsDocStyle.css"],
+      "codepen": {
+        "enable_for": ["examples"],
+        "options": {
+          "js_external": "https://code.jquery.com/jquery-3.6.0.min.js",
+          "js_pre_processor": "babel"
+        }
+      },
+      "base_url": "http://localhost/private/",
+      "favicon": "../assets/img/docs-icon.png",
+      "search": true,
+      "add_script_path": [
+        {
+          "src": "../assets/scripts/cs_sidebar.js",
+          "defer": "defer"
+        }
+      ]
+    }
+  },
+  "plugins": ["plugins/markdown"],
+  "markdown": {
+    "hardwrap": false,
+    "idInHeadings": true
   }
 }

.ci/config/jest/modulePaths.min.js

@@ -1,94 +1,126 @@
 #!/bin/bash
-## Reset Manifest
-cp ./.ci/templates/manifest.tpl.xml src/manifest.xml
+# Script Usage: Test with `npm run generate-manifests --headbranch=production --sourcebranch=sandbox`
+
+## Initial Checks and Setup
+### Checks if deploy.xml exists and exits if on a release run
+# deployFile: Flag to check existence of deploy.xml (0 = not exist, 1 = exist)
+# FLAT_OBJECTS: Flag to determine if flat object paths are used ("NO" by default)
+# GIT_BRANCHES: Specifies the range of branches to consider for deployment
+deployFile=0
+FLAT_OBJECTS="NO"
+GIT_BRANCHES="origin/$1..$2"
+
+### Exit Logic for Existing deploy.xml on Release Run
+# Exits if deploy.xml exists and script is run for a release
+if test -f "src/deploy.xml"; then
+    deployFile=1
+fi
+echo "Deploy: $3"
+if [[ $deployFile && $3 == "YES" ]]; then
+    echo "File already created"
+    cat "src/deploy.xml"
+    exit 0
+fi
+
+### Configuration for Object Directory and Repository Validation
+# Checks and sets flags based on script arguments for object directory usage and repo validation
+echo "Use Build Directory: $4"
+if [[ $4 == "YES" ]]; then
+    FLAT_OBJECTS="YES"
+    echo "Use flat Object paths on"
+fi
+echo "Running Validation: $5"
+if [[ $5 == "YES" ]]; then
+    GIT_BRANCHES="origin/$1..origin/$2"
+    echo "Validating Repo"
+fi
 
-## Store branch name for release
+## Manifest and Branch Setup
+### Resetting and Storing Manifest and Branch Information
+# Copies template manifest and stores the branch name for release
+cp ./.ci/templates/manifest.tpl.xml src/manifest.xml
 echo "$2" >./.ci/.branch
 
-## Declare variables
-### Create xml schema variables
+## Variable Declaration
+### Defining Schema and Regex Patterns for Processing
+# Variables for XML schema and various regex patterns for file and object identification
 endOfLine="</path>\n"
-
-### Create regex strings to test with
 srcRegex='src\/.*'
 attributesRegex='.*\.attributes.*'
 fileRegex='src\/FileCabinet\/SuiteScripts.*'
 objectRegex='src\/Objects\/.*'
 objectScriptPathRegex='.*scriptfile.*'
-
-### Output strings for File and Object lines
-#### Add more here if using other branches of deploy.xml schema
 FILELINE=
 OBJECTLINE=
-## Read git log for files impacted since origin headbranch -- reverts are also in the log
+filePathRegex="\(.*\)/\(.*\)"
+
+### Preparation for File and Object List Generation
+# Initializes the object file list for pipeline testing
+printf "" >objectFileList.pipeline-test.txt
+
+## Git Log Processing
+### Reading Git Log to Identify Modified Files
+# Processes git log to update src files in the deployment, excluding certain file types
 while read line; do
-    ### We only want to update src files in deployment
+    if [[ $line =~ \.(scss|sass|css)$ && $line != *.min.css ]]; then
+        continue
+    fi
     if [[ "$line" =~ $srcRegex ]]; then
-        ### Test if file exists, if not we can skip it and import as dependency later
-        if ! test -f "$line"; then
+        ADJUSTED_LINE="$line"
+        if [[ "$line" =~ $objectRegex && $FLAT_OBJECTS == "YES" ]]; then
+            fileName=$(echo "$line" | sed "s:$filePathRegex:\2:g")
+            ADJUSTED_LINE="src/Objects/$fileName"
+        fi
+        echo "Evaluating: $ADJUSTED_LINE"
+        if ! test -f "$ADJUSTED_LINE"; then
             continue
         fi
-
-        ### Setup what the new line will look like
-        newLine=$(echo "$line" | sed "s/src\//\t<path>~\//")"$endOfLine"
-
-        ### Skip duplicates -- lines which are already prepped to go in to deploy.xml
+        newLine=$(echo "$ADJUSTED_LINE" | sed "s/src\//\t<path>~\//")"$endOfLine"
         if [[ $OBJECTLINE == *"$newLine"* || $FILELINE == *"$newLine"* ]]; then
             continue
         fi
 
-        ### Separate Files & Objects to build deploy.xml
-        if [[ "$line" =~ $fileRegex ]]; then
-            if [[ "$line" =~ $attributesRegex ]]; then
+        ### File and Object Separation for deploy.xml
+        # Differentiates and processes files and objects for deployment
+        if [[ "$ADJUSTED_LINE" =~ $fileRegex ]]; then
+            if [[ "$ADJUSTED_LINE" =~ $attributesRegex ]]; then
                 continue
             fi
-            #### Is a file update
             FILELINE+="\t${newLine}"
-        elif [[ "$line" =~ $objectRegex ]]; then
-            ### Test line to see if the object needs a file path dependency added
+        elif [[ "$ADJUSTED_LINE" =~ $objectRegex ]]; then
             while read OBJLINE; do
                 if [[ "$OBJLINE" =~ $objectScriptPathRegex ]]; then
-                    #### Modify line to deploy.xml schema
                     SCRIPTPATH=$(echo "$OBJLINE" | sed "s/<scriptfile>\[/\/src/")
                     SCRIPTPATH=$(echo "${SCRIPTPATH}" | sed "s/\]<\/scriptfile>//")
                     depLine=$(echo "${SCRIPTPATH}" | sed "s/\/src\//\t<path>~\/FileCabinet\//")"$endOfLine"
                     CLEANPATH=$(echo "$SCRIPTPATH" | sed "s/src\///")
                     regexLineStr=".*$CLEANPATH"
-
-                    #### Check if dependency file is already in file paths list
                     if [[ "$FILELINE" =~ $regexLineStr ]]; then
                         continue
                     fi
-
-                    ##### Add to dependency to file list
                     FILELINE+="\t${depLine}"
                 fi
-            done < <(cat "./${line}")
-
-            #### Is an object file update
+            done < <(cat "./${ADJUSTED_LINE}")
+            echo "${ADJUSTED_LINE}" >>objectFileList.pipeline-test.txt
             OBJECTLINE+="\t${newLine}"
         fi
     fi
-    ### Clear line variable
     line=""
-done < <(git log --oneline --stat origin/$1..$2 --name-only)
+done < <(git log --oneline --stat "$GIT_BRANCHES" --name-only)
 
-## Generate deploy.xml file
-### Define output string variable
+## Deploy.xml Generation
+### Constructing deploy.xml Based on File and Object Modifications
+# Generates deploy.xml file with updated paths for files and objects based on git log
 OUTPUTLINES=""
-
-### If file path entries is > 0 add files to deploy.xml
 if [[ $FILELINE ]]; then
+    echo "##vso[task.setvariable variable=RELEASE_BUILD]true"
     OUTPUTLINES="<files>\n${FILELINE}\t</files>"
 fi
-
-### If object path entries is > 0 add objects to deploy.xml
 if [[ $OBJECTLINE ]]; then
+    echo "##vso[task.setvariable variable=RELEASE_BUILD]true"
     OUTPUTLINES="${OUTPUTLINES}\n\t<objects>\n${OBJECTLINE}\t</objects>"
 fi
-
-### Print output to custom updated deploy.xml
-# shellcheck disable=SC2059
+echo "Writing Output"
 printf "<deploy>
     <configuration>
         <path>~/AccountConfiguration/*</path>
@@ -99,5 +131,7 @@ printf "<deploy>
     </translationimports>
 </deploy>" >src/deploy.xml
 
-## Echo output for logging
+## Log Output
+### Displaying the Final deploy.xml for Verification
+# Outputs the final content of deploy.xml for logging and verification purposes
 cat src/deploy.xml

.ci/config/jsDocsConf.json

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Script Name: findMissingDependents.sh
+# Purpose:
+# This script is used to validate that NetSuite SuiteScript files in the repository
+# have corresponding SuiteCloud objects on the server. It's essential for ensuring
+# that all necessary script files are present and accounted for on the server.
+
+# Usage: ./findMissingDependents.sh
+
+# Functionality:
+# - The script reads a list of script IDs from a specified file (OBJFILE).
+# - For each script ID, it attempts to import the corresponding SuiteCloud object using the SuiteCloud CLI.
+# - If the import fails (indicating the SuiteCloud object is missing on the server),
+#   the script logs the script ID to an error file (ERRORFILE).
+# - This process helps identify discrepancies between the repository and the server,
+#   particularly missing SuiteCloud objects that may need attention.
+
+# Example usage in package.json:
+# "find-missing-dependents": "bash .ci/scripts/findMissingDependents.sh"
+
+SCRIPTIDREGEX="scriptid=\"(.*)\""
+SCRIPTIDSEDREGEX="\(.*\)scriptid=\"\(.*\)\"\(.*\)"
+OBJFILE="./deplist.rv-test.txt"
+DESTDIR="/Objects/_tmp/"
+FULLDESTDIR="./src/$DESTDIR"
+ERRORFILE="$FULLDESTDIR/errorList.txt"
+
+mkdir $FULLDESTDIR
+echo "" >$ERRORFILE
+
+while read line; do
+    SCRIPTID=$line
+    echo "Checking: $SCRIPTID"
+    {
+        npm run import-suitecloud-object --destinationfolder=$DESTDIR --scriptid=$SCRIPTID
+    } || {
+        echo "$line" >>$ERRORFILE
+    }
+done < <(cat $OBJFILE)

.ci/scripts/createDeployment.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+
+# This script is used by the "generate-manifests" script in the package.json file of 'netsuite-custommodules-template'.
+# It flattens the directory structure of NetSuite object files located in ./src/Objects/ and copies them to the build directory.
+# The script checks for changes in object files since a specified compare branch (usually 'origin/prod' or 'origin/main').
+
+# Usage: ./flattenObjectPaths.sh [BUILD_DIRECTORY] [COMPARE_BRANCH]
+
+# Parameters:
+# - BUILD_DIRECTORY: The destination directory where flattened object files will be copied.
+# - COMPARE_BRANCH: The branch to compare against to identify changed object files.
+
+# The script iterates through all object files and compares their change history with the compare branch.
+# Only object files with changes will be copied to the build directory for deployment.
+# If a duplicate object name is detected, the script exits with an error to alert the user to investigate.
+
+# Example usage in package.json:
+# "generate-manifests": "npm run compile-sass && bash .ci/scripts/createDeployment.sh $npm_config_headbranch $npm_config_sourcebranch $npm_config_releaserun $npm_config_flatobjects $npm_config_validaterun",
+# "flattenObjectPaths": "bash .ci/scripts/flattenObjectPaths.sh ./build/Objects origin/main origin/prod"
+
+# This script is part of the automated deployment process for NetSuite SuiteCloud projects.
+
+git fetch --all --prune
+
+find ./src/Objects/ -type f \( -iname \*.xml \) | while read relativePath; do
+    filePathRegex="\(.*\)/\(.*\)"
+    fileName=$(echo "$relativePath" | sed "s:$filePathRegex:\2:g")
+    squashedPathName="$1$fileName"
+
+    ## This is where we test if there's a change to this object file.
+    ## Only objects with changes will be copied to the build directory for deployment.
+
+    ## Read git log for files impacted since origin headbranch (reverts are also in the log).
+    while read line; do
+        changeLogFileName=$(echo "$line" | sed "s:$filePathRegex:\2:g")
+
+        ### We only want to copy object files in deployment which have been changed.
+        if [[ "$changeLogFileName" =~ $fileName ]]; then
+            ### Name matches change log, logic to copy file to build dir passes so far.
+            ## Test for duplicate objects and throw an exit error if a duplicate is located.
+            if test -f "$squashedPathName"; then
+                echo -e "\033[0;31mDUPLICATE_OBJECT_NAME_DETECTED: {squashedPathName: '$squashedPathName', relativePath:'$relativePath'}\033[0m"
+                exit 1
+            else
+                echo "Copying $fileName"
+                cp "$relativePath" "$1"
+            fi
+            break
+        fi
+
+        ### Clear line variable
+        line=""
+
+    done < <(git log --oneline --stat "origin/$2..$3" --name-only "./src/Objects")
+done

.ci/scripts/findMissingDepenents.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# Loop through all SCSS files in the specified directory
+for input in src/FileCabinet/SuiteScripts/*.scss; do
+    # Define the output file path by replacing the .scss extension with .min.css
+    output="src/FileCabinet/SuiteScripts/$(basename "$input" .scss).min.css"
+
+    # Compile the SCSS file to minified CSS using node-sass
+    node-sass --output-style compressed "$input" "$output"
+
+    # The resulting minified CSS is stored in the output file
+done