@mitre/inspec-objects 1.0.1 → 2.0.1

package/lib/utilities/diffMarkdown.js

@@ -1,10 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDiffMarkdown = void 0;
+exports.createDiffMarkdown = createDiffMarkdown;
 const tslib_1 = require("tslib");
 const mustache_1 = tslib_1.__importDefault(require("mustache"));
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const automatticUpdateTemplate_json_1 = tslib_1.__importDefault(require("../resources/automatticUpdateTemplate.json"));
+/**
+ * Generates a markdown representation of the differences between two profiles.
+ *
+ * The function processes the differences to create a renderable data structure
+ * that includes added controls, renamed controls, and updated properties such as
+ * checks, fixes, impacts, titles, and descriptions. It then uses a mustache template
+ * to render the markdown output.
+ *
+ * @param diff - An object containing the differences between two profiles.
+ * @param diff.ignoreFormattingDiff - The profile differences ignoring formatting changes.
+ * @param diff.rawDiff - The raw differences between the profiles.
+ * @returns A string containing the markdown representation of the differences.
+ */
 function createDiffMarkdown(diff) {
     const renderableDiffData = {
         addedControls: Object.values(diff.ignoreFormattingDiff.addedControls),
@@ -26,8 +39,8 @@ function createDiffMarkdown(diff) {
     Object.entries(diff.rawDiff.changedControls).forEach(([id, controlDiff]) => {
         var _a, _b;
         if ((_a = controlDiff.descs) === null || _a === void 0 ? void 0 : _a.check) {
-            const oldCheck = lodash_1.default.get(controlDiff.descs.check, '__old');
-            const newCheck = lodash_1.default.get(controlDiff.descs.check, '__new');
+            const oldCheck = lodash_1.default.get(controlDiff.descs.check, '__old', 'undefined');
+            const newCheck = lodash_1.default.get(controlDiff.descs.check, '__new', 'undefined');
             if (oldCheck.replace(/\n/g, '').replace(/\W/g, '') !==
                 newCheck.replace(/\n/g, '').replace(/\W/g, '')) {
                 renderableDiffData.updatedChecks.push({
@@ -38,8 +51,8 @@ function createDiffMarkdown(diff) {
             }
         }
         if ((_b = controlDiff.descs) === null || _b === void 0 ? void 0 : _b.fix) {
-            const oldFix = lodash_1.default.get(controlDiff.descs.fix, '__old');
-            const newFix = lodash_1.default.get(controlDiff.descs.fix, '__new');
+            const oldFix = lodash_1.default.get(controlDiff.descs.fix, '__old', 'undefined');
+            const newFix = lodash_1.default.get(controlDiff.descs.fix, '__new', 'undefined');
             if (oldFix.replace(/\n/g, '').replace(/\W/g, '') !==
                 newFix.replace(/\n/g, '').replace(/\W/g, '')) {
                 renderableDiffData.updatedFixes.push({
@@ -50,8 +63,8 @@ function createDiffMarkdown(diff) {
             }
         }
         if (controlDiff.impact) {
-            const oldImpact = lodash_1.default.get(controlDiff.impact, '__old');
-            const newImpact = lodash_1.default.get(controlDiff.impact, '__new');
+            const oldImpact = lodash_1.default.get(controlDiff.impact, '__old', 'undefined');
+            const newImpact = lodash_1.default.get(controlDiff.impact, '__new', 'undefined');
             if (oldImpact !== newImpact) {
                 renderableDiffData.updatedImpacts.push({
                     id: id,
@@ -61,8 +74,8 @@ function createDiffMarkdown(diff) {
             }
         }
         if (controlDiff.title) {
-            const oldTitle = lodash_1.default.get(controlDiff.title, '__old');
-            const newTitle = lodash_1.default.get(controlDiff.title, '__new');
+            const oldTitle = lodash_1.default.get(controlDiff.title, '__old', 'undefined');
+            const newTitle = lodash_1.default.get(controlDiff.title, '__new', 'undefined');
             if (oldTitle !== newTitle) {
                 renderableDiffData.updatedTitles.push({
                     id: id,
@@ -72,8 +85,8 @@ function createDiffMarkdown(diff) {
             }
         }
         if (controlDiff.desc) {
-            const oldDesc = lodash_1.default.get(controlDiff.desc, '__old');
-            const newDesc = lodash_1.default.get(controlDiff.desc, '__new');
+            const oldDesc = lodash_1.default.get(controlDiff.desc, '__old', 'undefined');
+            const newDesc = lodash_1.default.get(controlDiff.desc, '__new', 'undefined');
             if (oldDesc !== newDesc) {
                 renderableDiffData.updatedDescriptions.push({
                     id: id,
@@ -86,4 +99,3 @@ function createDiffMarkdown(diff) {
     // Render output
     return mustache_1.default.render(automatticUpdateTemplate_json_1.default.data, renderableDiffData);
 }
-exports.createDiffMarkdown = createDiffMarkdown;

package/lib/utilities/global.d.ts

@@ -1,7 +1,60 @@
+/**
+ * Wraps a given string to a specified line length by inserting newline characters.
+ *
+ * @param s - The string to be wrapped.
+ * @param lineLength - The maximum length of each line before wrapping. Defaults to 80.
+ * @returns The wrapped string with newline characters inserted at appropriate positions.
+ */
 export declare function wrap(s: string, lineLength?: number): string;
+/**
+ * Removes newline characters and excessive whitespace from a given string.
+ *
+ * This function replaces all newline characters (`\n` and `\\n`) with a single space,
+ * and collapses multiple spaces or tabs into a single space.
+ *
+ * @param s - The input string to be unformatted.
+ * @returns The unformatted string with newline characters and excessive whitespace removed.
+ */
 export declare function unformatText(s: string): string;
+/**
+ * Removes all whitespace characters from the given input string.
+ *
+ * @param input - The string from which to remove whitespace.
+ * @returns A new string with all whitespace characters removed.
+ */
 export declare function removeWhitespace(input: string): string;
+/**
+ * Escapes quotes in a given string based on the presence of single and double quotes.
+ *
+ * - If the string contains both single and double quotes, it wraps the string in `%q()` and escapes special case backslashes.
+ * - If the string contains only single quotes, it wraps the string in double quotes and escapes double quotes.
+ * - If the string contains only double quotes or no quotes, it wraps the string in single quotes and escapes single quotes.
+ *
+ * @param s - The input string to escape quotes in.
+ * @returns The string with appropriately escaped quotes.
+ */
 export declare function escapeQuotes(s: string): string;
+/**
+ * Replaces all instances of the placeholder `{{{{newlineHERE}}}}` in the given string with newline characters.
+ *
+ * @param s - The string containing the placeholders to be replaced.
+ * @returns The modified string with placeholders replaced by newline characters.
+ */
 export declare function removeNewlinePlaceholders(s: string): string;
+/**
+ * Retrieves the value from the first path in the provided paths array that exists in the given object.
+ *
+ * @param object - The object to search for the paths.
+ * @param paths - An array of string paths to check in the object.
+ * @returns The value from the first existing path in the object as a string.
+ * @throws Will throw an error if none of the paths exist in the object.
+ */
 export declare function getFirstPath(object: Record<string, unknown>, paths: string[]): string;
+/**
+ * Checks if the given file object has any of the specified paths.
+ *
+ * @param file - The object to check for the presence of the path(s).
+ * @param path - A string or an array of strings representing the path(s) to check.
+ * @returns `true` if any of the specified paths exist in the object, otherwise `false`.
+ */
 export declare function hasPath(file: Record<string, unknown>, path: string | string[]): boolean;

package/lib/utilities/global.js

@@ -1,9 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasPath = exports.getFirstPath = exports.removeNewlinePlaceholders = exports.escapeQuotes = exports.removeWhitespace = exports.unformatText = exports.wrap = void 0;
+exports.wrap = wrap;
+exports.unformatText = unformatText;
+exports.removeWhitespace = removeWhitespace;
+exports.escapeQuotes = escapeQuotes;
+exports.removeNewlinePlaceholders = removeNewlinePlaceholders;
+exports.getFirstPath = getFirstPath;
+exports.hasPath = hasPath;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
-// Breaks lines down to lineLength number of characters
+/**
+ * Wraps a given string to a specified line length by inserting newline characters.
+ *
+ * @param s - The string to be wrapped.
+ * @param lineLength - The maximum length of each line before wrapping. Defaults to 80.
+ * @returns The wrapped string with newline characters inserted at appropriate positions.
+ */
 function wrap(s, lineLength = 80) {
     let newString = '';
     let currentLength = 0;
@@ -34,25 +46,75 @@ function wrap(s, lineLength = 80) {
     }
     return newString;
 }
-exports.wrap = wrap;
-// Remove new lines and tabs
+/**
+ * Removes newline characters and excessive whitespace from a given string.
+ *
+ * This function replaces all newline characters (`\n` and `\\n`) with a single space,
+ * and collapses multiple spaces or tabs into a single space.
+ *
+ * @param s - The input string to be unformatted.
+ * @returns The unformatted string with newline characters and excessive whitespace removed.
+ */
 function unformatText(s) {
     return s.replace(/\n/g, ' ').replace(/\\n/g, ' ').replace(/( +|\t)/g, ' ');
 }
-exports.unformatText = unformatText;
+/**
+ * Removes all whitespace characters from the given input string.
+ *
+ * @param input - The string from which to remove whitespace.
+ * @returns A new string with all whitespace characters removed.
+ */
 function removeWhitespace(input) {
     return input.replace(/\s/gi, '');
 }
-exports.removeWhitespace = removeWhitespace;
+/**
+ * Escapes backslashes that precede closing parentheses in a given string.
+ *
+ * This function searches for occurrences of backslashes followed by a closing
+ * parenthesis in the input string and replaces each occurrence with two
+ * backslashes followed by a closing parenthesis. This effectively escapes
+ * the backslashes in such cases.
+ *
+ * @param s - The input string in which to escape backslashes.
+ * @returns A new string with the specified backslashes escaped.
+ */
 const escapeSpecialCaseBackslashes = (s) => {
-    return s.replace(/\\\)/g, '\\\\)'); // Escape backslashes if preceding close parentheses
+    return s.replace(/\\\)/g, '\\\\)');
 };
+/**
+ * Escapes single quotes and backslashes in a given string.
+ *
+ * This function replaces all backslashes (`\`) with double backslashes (`\\`)
+ * and all single quotes (`'`) with escaped single quotes (`\'`).
+ *
+ * @param s - The input string to be escaped.
+ * @returns The escaped string with single quotes and backslashes properly escaped.
+ */
 const escapeSingleQuotes = (s) => {
-    return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'"); // Escape backslashes and quotes
+    return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
 };
+/**
+ * Escapes backslashes and double quotes in a given string.
+ *
+ * This function replaces all backslashes (`\`) with double backslashes (`\\`)
+ * and all double quotes (`"`) with escaped double quotes (`\"`).
+ *
+ * @param s - The input string to be escaped.
+ * @returns The escaped string with backslashes and double quotes properly escaped.
+ */
 const escapeDoubleQuotes = (s) => {
-    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"'); // Escape backslashes and double quotes
+    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 };
+/**
+ * Escapes quotes in a given string based on the presence of single and double quotes.
+ *
+ * - If the string contains both single and double quotes, it wraps the string in `%q()` and escapes special case backslashes.
+ * - If the string contains only single quotes, it wraps the string in double quotes and escapes double quotes.
+ * - If the string contains only double quotes or no quotes, it wraps the string in single quotes and escapes single quotes.
+ *
+ * @param s - The input string to escape quotes in.
+ * @returns The string with appropriately escaped quotes.
+ */
 function escapeQuotes(s) {
     if (s.includes("'") && s.includes('"')) {
         return `%q(${escapeSpecialCaseBackslashes(removeNewlinePlaceholders(s))})`;
@@ -64,11 +126,23 @@ function escapeQuotes(s) {
         return `'${escapeSingleQuotes(removeNewlinePlaceholders(s))}'`;
     }
 }
-exports.escapeQuotes = escapeQuotes;
+/**
+ * Replaces all instances of the placeholder `{{{{newlineHERE}}}}` in the given string with newline characters.
+ *
+ * @param s - The string containing the placeholders to be replaced.
+ * @returns The modified string with placeholders replaced by newline characters.
+ */
 function removeNewlinePlaceholders(s) {
     return s.replace(/\{\{\{\{newlineHERE\}\}\}\}/g, '\n');
 }
-exports.removeNewlinePlaceholders = removeNewlinePlaceholders;
+/**
+ * Retrieves the value from the first path in the provided paths array that exists in the given object.
+ *
+ * @param object - The object to search for the paths.
+ * @param paths - An array of string paths to check in the object.
+ * @returns The value from the first existing path in the object as a string.
+ * @throws Will throw an error if none of the paths exist in the object.
+ */
 function getFirstPath(object, paths) {
     const index = lodash_1.default.findIndex(paths, (p) => hasPath(object, p));
     if (index === -1) {
@@ -78,7 +152,13 @@ function getFirstPath(object, paths) {
         return lodash_1.default.get(object, paths[index]);
     }
 }
-exports.getFirstPath = getFirstPath;
+/**
+ * Checks if the given file object has any of the specified paths.
+ *
+ * @param file - The object to check for the presence of the path(s).
+ * @param path - A string or an array of strings representing the path(s) to check.
+ * @returns `true` if any of the specified paths exist in the object, otherwise `false`.
+ */
 function hasPath(file, path) {
     let pathArray;
     if (typeof path === 'string') {
@@ -89,4 +169,3 @@ function hasPath(file, path) {
     }
     return lodash_1.default.some(pathArray, (p) => lodash_1.default.has(file, p));
 }
-exports.hasPath = hasPath;

package/lib/utilities/logging.d.ts

@@ -1,2 +1,2 @@
 import winston from 'winston';
-export declare function createWinstonLogger(level?: string): winston.Logger;
+export declare function createWinstonLogger(mapperName: string, level?: string): winston.Logger;

package/lib/utilities/logging.js

@@ -1,15 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createWinstonLogger = void 0;
+exports.createWinstonLogger = createWinstonLogger;
 const tslib_1 = require("tslib");
 const winston_1 = tslib_1.__importDefault(require("winston"));
-function createWinstonLogger(level = 'debug') {
+function createWinstonLogger(mapperName, level = 'debug') {
     return winston_1.default.createLogger({
         transports: [new winston_1.default.transports.Console()],
         level: level,
-        format: winston_1.default.format.combine(winston_1.default.format.timestamp({
+        format: winston_1.default.format.combine(winston_1.default.format.simple(), winston_1.default.format.timestamp({
             format: 'MMM-DD-YYYY HH:mm:ss Z',
-        }), winston_1.default.format.printf(info => `[${[info.timestamp]}] ${info.message}`)),
+        }), winston_1.default.format.printf(
+        // Using the ANSI escape code sequence initiator (\xb[) to change output colors
+        // Colors used are: 33m (yellow) and 34m (blue)
+        // \x1b[0m : Resets the color settings to the default
+        info => `\x1b[33m[${[info.timestamp]} -> ${mapperName}]:\x1b[0m \x1b[34m${info.message}\x1b[0m`)),
     });
 }
-exports.createWinstonLogger = createWinstonLogger;

package/lib/utilities/update.d.ts

@@ -3,7 +3,18 @@ import Control from '../objects/control';
 import Profile from '../objects/profile';
 import { ProfileDiff } from '../types/diff';
 import { OvalDefinitionValue } from '../types/oval';
-export declare type UpdatedProfileReturn = {
+/**
+ * Represents the return type of an updated profile operation.
+ *
+ * @typedef UpdatedProfileReturn
+ *
+ * @property {Profile} profile - The updated profile object.
+ * @property {Object} diff - The differences between the original and updated profiles.
+ * @property {ProfileDiff} diff.ignoreFormattingDiff - The differences ignoring formatting changes.
+ * @property {Record<string, unknown>} diff.rawDiff - The raw differences as a record.
+ * @property {string} markdown - The markdown representation of the differences.
+ */
+export type UpdatedProfileReturn = {
     profile: Profile;
     diff: {
         ignoreFormattingDiff: ProfileDiff;
@@ -11,8 +22,56 @@ export declare type UpdatedProfileReturn = {
     };
     markdown: string;
 };
+/**
+ * This is the most likely thing to break if you are getting code formatting issues.
+ *
+ * Extracts the `describe` block (what is actually run by inspec for validation)
+ * from an InSpec control object, collapsing multi-line strings.
+ *
+ * @param control - The InSpec control object containing the code to extract the `describe` block from.
+ * @returns The extracted `describe` block as a string, or an empty string if the control has no code.
+ */
 export declare function getExistingDescribeFromControl(control: Control): string;
+/**
+ * Finds an updated control from a list of updated controls by matching all possible identifiers.
+ *
+ * This function attempts to find a matching control in the `updatedControls` array by comparing
+ * the `id` of the `existingControl` with the `id` of each control in the `updatedControls` array.
+ * If no match is found based on `id`, it then tries to match based on legacy identifiers found
+ * in the `tags.legacy` property of each control in the `updatedControls` array.
+ *
+ * @param existingControl - The control to find a match for in the updated controls.
+ * @param updatedControls - An array of updated controls to search through.
+ * @returns The matching updated control if found, otherwise `undefined`.
+ */
 export declare function findUpdatedControlByAllIdentifiers(existingControl: Control, updatedControls: Control[]): Control | undefined;
+/**
+ * Updates a given control object with the provided partial update and logs the process.
+ *
+ * @param {Control} from - The original control object to be updated.
+ * @param {Partial<Control>} update - An object containing the properties to update in the original control.
+ * @param {winston.Logger} logger - A logger instance to log debug information.
+ * @returns {Control} - The updated control object.
+ */
 export declare function updateControl(from: Control, update: Partial<Control>, logger: winston.Logger): Control;
+/**
+ * Updates the describe block of a control with the describe block from another control.
+ *
+ * @param from - The control from which to get the existing describe block.
+ * @param update - The partial control data to update.
+ * @param logger - The logger instance to use for logging debug information.
+ * @returns The updated control with the describe block from the `from` control.
+ */
+export declare function updateControlDescribeBlock(from: Control, update: Partial<Control>, logger: winston.Logger): Control;
+/**
+ * Updates a given profile with new metadata and controls from another profile.
+ *
+ * @param from - The original profile to be updated.
+ * @param using - The profile containing the new metadata and controls.
+ * @param logger - A winston logger instance for logging debug information.
+ * @returns An object containing the updated profile and the diff between the original and updated profiles, excluding markdown.
+ *
+ * @throws Will throw an error if a new control is added but the control data is not available.
+ */
 export declare function updateProfile(from: Profile, using: Profile, logger: winston.Logger): Omit<UpdatedProfileReturn, 'markdown'>;
 export declare function updateProfileUsingXCCDF(from: Profile, using: string, id: 'group' | 'rule' | 'version' | 'cis', logger: winston.Logger, ovalDefinitions?: Record<string, OvalDefinitionValue>): UpdatedProfileReturn;

package/lib/utilities/update.js

@@ -2,13 +2,39 @@
 // Utilities to update a profile or control with new metadata
 // The ultimate goal is to preserve all the metadata that is already there and only add what is new
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.updateProfileUsingXCCDF = exports.updateProfile = exports.updateControl = exports.findUpdatedControlByAllIdentifiers = exports.getExistingDescribeFromControl = void 0;
+exports.getExistingDescribeFromControl = getExistingDescribeFromControl;
+exports.findUpdatedControlByAllIdentifiers = findUpdatedControlByAllIdentifiers;
+exports.updateControl = updateControl;
+exports.updateControlDescribeBlock = updateControlDescribeBlock;
+exports.updateProfile = updateProfile;
+exports.updateProfileUsingXCCDF = updateProfileUsingXCCDF;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const diff_1 = require("./diff");
+const control_1 = tslib_1.__importDefault(require("../objects/control"));
 const profile_1 = tslib_1.__importDefault(require("../objects/profile"));
 const xccdf_1 = require("../parsers/xccdf");
 const diffMarkdown_1 = require("./diffMarkdown");
+/**
+ * Projects values from the source object onto the destination object,
+ * updating the destination object in place.
+ *
+ * @param dst - The destination object to be updated.
+ * @param src - The source object containing new values.
+ * @param currentPath - The current path being processed (used for nested objects).
+ * @returns The updated destination object.
+ *
+ * @remarks
+ * - If a value in the source object is an object and the corresponding value
+ *   in the destination object is also an object, the function will recursively
+ *   update the nested object.
+ * - If a value in the source object is a string, it will be trimmed before
+ *   being set in the destination object.
+ * - If a value in the source object is a number, it will be directly set in
+ *   the destination object.
+ * - If a value in the source object is an array, the function will merge it with
+ *   the corresponding array in the destination object, ensuring unique values.
+ */
 function projectValuesOntoExistingObj(dst, src, currentPath = '') {
     for (const updatedValue in src) {
         const existingValue = lodash_1.default.get(dst, updatedValue);
@@ -31,28 +57,32 @@ function projectValuesOntoExistingObj(dst, src, currentPath = '') {
     }
     return dst;
 }
+/**
+ * Returns an array containing two numerical indices (i.e., start and stop
+ * line numbers) for each string or multi-line comment, given raw text as
+ * an input parameter. The raw text is a string containing the entirety of an
+ * InSpec control.
+ *
+ * The function utilizes a pair of stacks (i.e., `stack`, `rangeStack`) to keep
+ * track of string delimiters and their associated line numbers, respectively.
+ *
+ * Combinations Handled:
+ * - Single quotes (')
+ * - Double quotes (")
+ * - Back ticks (`)
+ * - Mixed quotes ("`'")
+ * - Percent strings (%; keys: q, Q, r, i, I, w, W, x; delimiters: (), {},
+ *   [], <>, most non-alphanumeric characters); (e.g., "%q()")
+ * - Percent literals (%; delimiters: (), {}, [], <>, most non-
+ *   alphanumeric characters); (e.g., "%()")
+ * - Multi-line comments (e.g., =begin\nSome comment\n=end)
+ * - Variable delimiters (i.e., parenthesis: (); array: []; hash: {})
+ *
+ * @param text - The raw text containing the entirety of an InSpec control.
+ * @returns An array of arrays, each containing two numerical indices representing
+ * the start and stop line numbers for each string or multi-line comment.
+ */
 function getRangesForLines(text) {
-    /*
-      Returns an array containing two numerical indices (i.e., start and stop
-      line numbers) for each string or multi-line comment, given raw text as
-      an input parameter. The raw text is a string containing the entirety of an
-      InSpec control.
-  
-      Algorithm utilizes a pair of stacks (i.e., `stack`, `rangeStack`) to keep
-      track of string delimiters and their associated line numbers, respectively.
-  
-      Combinations Handled:
-      - Single quotes (')
-      - Double quotes (")
-      - Back ticks (`)
-      - Mixed quotes ("`'")
-      - Percent strings (%; keys: q, Q, r, i, I, w, W, x; delimiters: (), {},
-        [], <>, most non-alphanumeric characters); (e.g., "%q()")
-      - Percent literals (%; delimiters: (), {}, [], <>, most non-
-        alphanumeric characters); (e.g., "%()")
-      - Multi-line comments (e.g., =begin\nSome comment\n=end)
-      - Variable delimiters (i.e., parenthesis: (); array: []; hash: {})
-    */
     const stringDelimiters = { '(': ')', '{': '}', '[': ']', '<': '>' };
     const variableDelimiters = { '(': ')', '{': '}', '[': ']' };
     const quotes = '\'"`';
@@ -145,11 +175,17 @@ function getRangesForLines(text) {
     }
     return ranges;
 }
+/**
+ * Joins lines of text from specified ranges and returns an array of strings.
+ * Each range is specified by a start and stop index, and the lines within
+ * those ranges are joined together.
+ *
+ * @param text - The raw text input to be processed.
+ * @param ranges - An array of ranges, where each range is a tuple containing
+ *                 the start and stop indices (inclusive) of the lines to be joined.
+ * @returns An array of strings, where lines within the specified ranges are joined.
+ */
 function joinMultiLineStringsFromRanges(text, ranges) {
-    /*
-      Returns an array of strings and joined strings at specified ranges, given
-      raw text as an input parameter.
-    */
     const originalLines = text.split('\n');
     const joinedLines = [];
     let i = 0;
@@ -170,11 +206,16 @@ function joinMultiLineStringsFromRanges(text, ranges) {
     }
     return joinedLines;
 }
+/**
+ * Filters out ranges that span only a single line. There is,
+ * drops ranges with the same start and stop line numbers (i.e., strings
+ * that populate a single line)
+ *
+ * @param ranges - An array of ranges, where each range is represented by a
+ *                 tuple of start and stop line numbers.
+ * @returns An array of ranges that span multiple lines.
+ */
 function getMultiLineRanges(ranges) {
-    /*
-      Drops ranges with the same start and stop line numbers (i.e., strings
-      that populate a single line)
-    */
     const multiLineRanges = [];
     for (const [start, stop] of ranges) {
         if (start !== stop) {
@@ -183,10 +224,15 @@ function getMultiLineRanges(ranges) {
     }
     return multiLineRanges;
 }
-/*
-  This is the most likely thing to break if you are getting code formatting issues.
-  Extract the existing describe blocks (what is actually run by inspec for validation)
-*/
+/**
+ * This is the most likely thing to break if you are getting code formatting issues.
+ *
+ * Extracts the `describe` block (what is actually run by inspec for validation)
+ * from an InSpec control object, collapsing multi-line strings.
+ *
+ * @param control - The InSpec control object containing the code to extract the `describe` block from.
+ * @returns The extracted `describe` block as a string, or an empty string if the control has no code.
+ */
 function getExistingDescribeFromControl(control) {
     if (control.code) {
         // Join multi-line strings in InSpec control.
@@ -214,13 +260,28 @@ function getExistingDescribeFromControl(control) {
             }
         }
         // Return synthesized logic as describe block
-        return describeBlock.slice(0, describeBlock.lastIndexOf('end')).join('\n'); // Drop trailing ['end', '\n'] from Control block.
+        const lastIndex = (describeBlock.lastIndexOf('end') === -1)
+            ? describeBlock.lastIndexOf('end\r')
+            : describeBlock.lastIndexOf('end');
+        // Drop trailing ['end', '\n'] from Control block.
+        return describeBlock.slice(0, lastIndex).join('\n');
     }
     else {
         return '';
     }
 }
-exports.getExistingDescribeFromControl = getExistingDescribeFromControl;
+/**
+ * Finds an updated control from a list of updated controls by matching all possible identifiers.
+ *
+ * This function attempts to find a matching control in the `updatedControls` array by comparing
+ * the `id` of the `existingControl` with the `id` of each control in the `updatedControls` array.
+ * If no match is found based on `id`, it then tries to match based on legacy identifiers found
+ * in the `tags.legacy` property of each control in the `updatedControls` array.
+ *
+ * @param existingControl - The control to find a match for in the updated controls.
+ * @param updatedControls - An array of updated controls to search through.
+ * @returns The matching updated control if found, otherwise `undefined`.
+ */
 function findUpdatedControlByAllIdentifiers(existingControl, updatedControls) {
     // Try to match based on IDs
     let updatedControl = updatedControls.find((updatedControl) => {
@@ -242,7 +303,14 @@ function findUpdatedControlByAllIdentifiers(existingControl, updatedControls) {
     }
     return undefined;
 }
-exports.findUpdatedControlByAllIdentifiers = findUpdatedControlByAllIdentifiers;
+/**
+ * Updates a given control object with the provided partial update and logs the process.
+ *
+ * @param {Control} from - The original control object to be updated.
+ * @param {Partial<Control>} update - An object containing the properties to update in the original control.
+ * @param {winston.Logger} logger - A logger instance to log debug information.
+ * @returns {Control} - The updated control object.
+ */
 function updateControl(from, update, logger) {
     const existingDescribeBlock = getExistingDescribeFromControl(from);
     logger.debug(`Existing describe block for control ${from.id}: ${JSON.stringify(existingDescribeBlock)}`);
@@ -250,7 +318,31 @@ function updateControl(from, update, logger) {
     projectedControl.describe = existingDescribeBlock;
     return projectedControl;
 }
-exports.updateControl = updateControl;
+/**
+ * Updates the describe block of a control with the describe block from another control.
+ *
+ * @param from - The control from which to get the existing describe block.
+ * @param update - The partial control data to update.
+ * @param logger - The logger instance to use for logging debug information.
+ * @returns The updated control with the describe block from the `from` control.
+ */
+function updateControlDescribeBlock(from, update, logger) {
+    const existingDescribeBlock = getExistingDescribeFromControl(from);
+    logger.debug(`Updating control ${update.id} with this describe block: ${JSON.stringify(existingDescribeBlock)}`);
+    const projectedControl = new control_1.default(update);
+    projectedControl.describe = existingDescribeBlock;
+    return projectedControl;
+}
+/**
+ * Updates a given profile with new metadata and controls from another profile.
+ *
+ * @param from - The original profile to be updated.
+ * @param using - The profile containing the new metadata and controls.
+ * @param logger - A winston logger instance for logging debug information.
+ * @returns An object containing the updated profile and the diff between the original and updated profiles, excluding markdown.
+ *
+ * @throws Will throw an error if a new control is added but the control data is not available.
+ */
 function updateProfile(from, using, logger) {
     // Update the profile with the new metadata
     const to = new profile_1.default(lodash_1.default.omit(from, 'controls'));
@@ -285,9 +377,8 @@ function updateProfile(from, using, logger) {
         diff,
     };
 }
-exports.updateProfile = updateProfile;
 function updateProfileUsingXCCDF(from, using, id, logger, ovalDefinitions) {
-    logger.debug(`Updating profile ${from.name} with control IDs: ${id}`);
+    logger.info(`Updating profile ${from.name} with control IDs type: ${id}`);
     // Parse the XCCDF benchmark and convert it into a Profile
     logger.debug('Loading XCCDF File');
     const xccdfProfile = (0, xccdf_1.processXCCDF)(using, false, id, ovalDefinitions);
@@ -305,4 +396,3 @@ function updateProfileUsingXCCDF(from, using, id, logger, ovalDefinitions) {
         markdown: markdown
     };
 }
-exports.updateProfileUsingXCCDF = updateProfileUsingXCCDF;