@mitre/inspec-objects 1.0.1 → 2.0.0

package/lib/utilities/diff.js

@@ -1,11 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.diffProfile = exports.ignoreFormattingDiff = exports.removeNewlines = void 0;
+exports.removeNewlines = removeNewlines;
+exports.ignoreFormattingDiff = ignoreFormattingDiff;
+exports.diffProfile = diffProfile;
 const tslib_1 = require("tslib");
 const json_diff_1 = require("json-diff");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const update_1 = require("./update");
 const global_1 = require("./global");
+/**
+ * Removes newlines from all string values within a nested object.
+ *
+ * This function recursively traverses the provided object and replaces
+ * newline characters (`\n`) in string values with the placeholder `{{{{newlineHERE}}}}`.
+ * It also trims any leading or trailing whitespace from the string values.
+ *
+ * @param control - The object from which to remove newlines. If not provided,
+ *                  an empty object is returned.
+ * @returns A new object with newlines removed from all string values.
+ */
 function removeNewlines(control) {
     if (!control) {
         return {};
@@ -20,16 +33,34 @@ function removeNewlines(control) {
         return value;
     });
 }
-exports.removeNewlines = removeNewlines;
-// Goal is to use a linter for the formatting and compare characters without whitespaces here
+/**
+ * Processes a diff object to ignore formatting differences such as whitespace.
+ * Goal is to use a linter for the formatting and compare characters without
+ * whitespaces here.
+ *
+ * The function performs the following:
+ * - If the diff value has a `__new` property, it compares the `__new` and
+ *   `__old` values after removing whitespace. If they are different, it sets
+ *   the result to the `__new` value.
+ * - If the diff value is an array, it maps and filters the array to include
+ *   only the new values.
+ * - If the diff value is an object, it recursively processes the object.
+ * - If the key ends with `__deleted`, it ignores the value.
+ * - Otherwise, it sets the result to the diff value.
+ *
+ * @param diffData - The diff object containing differences to process.
+ * @returns A new object with formatting differences ignored.
+ *
+
+ */
 function ignoreFormattingDiff(diffData) {
     return lodash_1.default.transform(diffData, (result, diffValue, key) => {
         if (lodash_1.default.has(diffValue, '__new')) {
             // Remove any trailing space
             if (typeof lodash_1.default.get(diffValue, '__new') === 'string' &&
                 typeof lodash_1.default.get(diffValue, '__old') === 'string') {
-                if ((0, global_1.removeWhitespace)(lodash_1.default.get(diffValue, '__new')) !==
-                    (0, global_1.removeWhitespace)(lodash_1.default.get(diffValue, '__old'))) {
+                if ((0, global_1.removeWhitespace)(lodash_1.default.get(diffValue, '__new', 'undefined')) !==
+                    (0, global_1.removeWhitespace)(lodash_1.default.get(diffValue, '__old', 'undefined'))) {
                     lodash_1.default.set(result, key, lodash_1.default.get(diffValue, '__new'));
                 }
             }
@@ -53,9 +84,20 @@ function ignoreFormattingDiff(diffData) {
         }
     });
 }
-exports.ignoreFormattingDiff = ignoreFormattingDiff;
+/**
+ * Computes the differences between two profiles and logs the process.
+ *
+ * @param fromProfile - The original profile to compare from.
+ * @param toProfile   - The target profile to compare to.
+ * @param logger      - The logger instance to use for logging information.
+ *
+ * @returns An object containing two properties:
+ *  - `ignoreFormattingDiff`: The profile differences ignoring formatting changes.
+ *  - `rawDiff`: The raw profile differences.
+ */
 function diffProfile(fromProfile, toProfile, logger) {
     var _a;
+    logger.info(`Processing diff between: ${fromProfile.name}(v:${fromProfile.version}) and: ${toProfile.name}(v:${toProfile.version})`);
     const profileDiff = {
         addedControlIDs: [],
         removedControlIDs: [],
@@ -72,9 +114,7 @@ function diffProfile(fromProfile, toProfile, logger) {
         addedControls: {},
         changedControls: {},
     };
-    const fromControlIDs = fromProfile.controls
-        .map((control) => control.id)
-        .sort();
+    const fromControlIDs = fromProfile.controls.map((control) => control.id).sort();
     const toControlIDs = toProfile.controls.map((control) => control.id).sort();
     // Find new controls
     const controlIDDiff = (_a = (0, json_diff_1.diff)(fromControlIDs, toControlIDs)) === null || _a === void 0 ? void 0 : _a.filter((item) => !(item.length === 1 && item[0] === ' '));
@@ -95,12 +135,12 @@ function diffProfile(fromProfile, toProfile, logger) {
                     const controlDiff = lodash_1.default.omit((0, json_diff_1.diff)(existingControl, newControl), 'code__deleted');
                     // logger.info("CONTROL DIFF:" + JSON.stringify(controlDiff, null, 2))
                     const renamedControlIgnoredFormatting = ignoreFormattingDiff(controlDiff);
-                    logger.info(JSON.stringify(renamedControlIgnoredFormatting));
                     profileDiff.changedControls[newControl.id] = renamedControlIgnoredFormatting;
                     profileDiff.changedControlIDs.push(newControl.id);
                     originalDiff.changedControls[newControl.id] = controlDiff;
                     originalDiff.changedControlIDs.push(newControl.id);
                     logger.verbose(`Control ${existingControl.id} has been updated to ${newControl.id}`);
+                    logger.debug(`Updated control content: ${JSON.stringify(renamedControlIgnoredFormatting)}`);
                 }
                 else {
                     profileDiff.removedControlIDs.push(diffValue[1]);
@@ -111,7 +151,7 @@ function diffProfile(fromProfile, toProfile, logger) {
                 logger.error(`Unable to find existing control ${diffValue[1]}`);
             }
         }
-        else if (diffValue[0] === '+' && !changedControlIds.includes(diffValue[1].toLowerCase()) && diffValue[1]) {
+        else if (diffValue[0] === '+' && !changedControlIds.includes(diffValue[1].toString().toLowerCase()) && diffValue[1]) {
             logger.info(JSON.stringify(diffValue));
             logger.info(JSON.stringify(changedControlIds));
             profileDiff.addedControlIDs.push(diffValue[1]);
@@ -147,4 +187,3 @@ function diffProfile(fromProfile, toProfile, logger) {
     }
     return { ignoreFormattingDiff: profileDiff, rawDiff: originalDiff };
 }
-exports.diffProfile = diffProfile;

package/lib/utilities/diffMarkdown.d.ts

@@ -1,4 +1,17 @@
 import { ProfileDiff } from '../types/diff';
+/**
+ * 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.
+ */
 export declare function createDiffMarkdown(diff: {
     ignoreFormattingDiff: ProfileDiff;
     rawDiff: any;

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;