@contentstack/cli-audit 1.0.0

package/lib/commands/cm/stacks/audit/index.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const csv = tslib_1.__importStar(require("fast-csv"));
+const isEmpty_1 = tslib_1.__importDefault(require("lodash/isEmpty"));
+const path_1 = require("path");
+const cli_utilities_1 = require("@contentstack/cli-utilities");
+const fs_1 = require("fs");
+const config_1 = tslib_1.__importDefault(require("../../../../config"));
+const log_1 = require("../../../../util/log");
+const messages_1 = require("../../../../messages");
+const base_command_1 = require("../../../../base-command");
+const modules_1 = require("../../../../modules");
+const types_1 = require("../../../../types");
+class Audit extends base_command_1.BaseCommand {
+    /**
+     * The `run` function is an asynchronous function that performs an audit on different modules
+     * (content-types, global-fields, entries) and generates a report.
+     */
+    async run() {
+        try {
+            await this.promptQueue();
+            const reportPath = this.flags['report-path'] || process.cwd();
+            this.sharedConfig.reportPath = (0, path_1.resolve)(reportPath, 'audit-report');
+            let { ctSchema, gfSchema } = this.getCtAndGfSchema();
+            let missingCtRefs, missingGfRefs, missingEntryRefs;
+            for (const module of this.sharedConfig.flags.modules || this.sharedConfig.modules) {
+                cli_utilities_1.ux.action.start(this.$t(this.messages.AUDIT_START_SPINNER, { module }));
+                switch (module) {
+                    case 'content-types':
+                        missingCtRefs = await new modules_1.ContentType({
+                            ctSchema,
+                            gfSchema,
+                            log: this.log,
+                            moduleName: module,
+                            config: this.sharedConfig,
+                        }).run();
+                        await this.prepareReport(module, missingCtRefs);
+                        break;
+                    case 'global-fields':
+                        missingGfRefs = await new modules_1.GlobalField({
+                            ctSchema,
+                            gfSchema,
+                            log: this.log,
+                            moduleName: module,
+                            config: this.sharedConfig,
+                        }).run();
+                        await this.prepareReport(module, missingGfRefs);
+                        break;
+                    case 'entries':
+                        missingEntryRefs = await new modules_1.Entries({
+                            ctSchema,
+                            gfSchema,
+                            log: this.log,
+                            moduleName: module,
+                            config: this.sharedConfig,
+                        }).run();
+                        await this.prepareReport(module, missingEntryRefs);
+                        break;
+                }
+                cli_utilities_1.ux.action.stop();
+            }
+            this.showOutputOnScreen([
+                { module: 'Content types', missingRefs: missingCtRefs },
+                { module: 'Global Fields', missingRefs: missingGfRefs },
+                { module: 'Entries', missingRefs: missingEntryRefs },
+            ]);
+            if (!(0, isEmpty_1.default)(missingCtRefs) || !(0, isEmpty_1.default)(missingGfRefs) || !(0, isEmpty_1.default)(missingEntryRefs)) {
+                this.log(this.$t(messages_1.auditMsg.FINAL_REPORT_PATH, { path: this.sharedConfig.reportPath }), 'warn');
+            }
+            else {
+                this.log(this.messages.NO_MISSING_REF_FOUND, 'info');
+                this.log('');
+            }
+        }
+        catch (error) {
+            this.log(error instanceof Error ? error.message : error, 'error');
+            console.trace(error);
+            cli_utilities_1.ux.action.stop('Process failed.!');
+            this.exit(1);
+        }
+    }
+    /**
+     * The `promptQueue` function prompts the user to enter a data directory path if the `data-dir` flag
+     * is missing, and sets the `basePath` property of the `sharedConfig` object to the entered path.
+     */
+    async promptQueue() {
+        // NOTE get content path if data-dir flag is missing
+        this.sharedConfig.basePath =
+            this.flags['data-dir'] ||
+                (await cli_utilities_1.cliux.inquire({
+                    type: 'input',
+                    name: 'data-dir',
+                    message: this.messages.DATA_DIR,
+                }));
+    }
+    /**
+     * The function `getCtAndGfSchema` reads and parses JSON files containing content type and global
+     * field schemas, and returns them as an object.
+     * @returns The function `getCtAndGfSchema()` returns an object with two properties: `ctSchema` and
+     * `gfSchema`. The values of these properties are the parsed JSON data from two different files.
+     */
+    getCtAndGfSchema() {
+        const ctPath = (0, path_1.join)(this.sharedConfig.basePath, this.sharedConfig.moduleConfig['content-types'].dirName, this.sharedConfig.moduleConfig['content-types'].fileName);
+        const gfPath = (0, path_1.join)(this.sharedConfig.basePath, this.sharedConfig.moduleConfig['global-fields'].dirName, this.sharedConfig.moduleConfig['global-fields'].fileName);
+        let ctSchema = (0, fs_1.existsSync)(ctPath) ? JSON.parse((0, fs_1.readFileSync)(ctPath, 'utf-8')) : [];
+        let gfSchema = (0, fs_1.existsSync)(gfPath) ? JSON.parse((0, fs_1.readFileSync)(gfPath, 'utf-8')) : [];
+        return { ctSchema, gfSchema };
+    }
+    /**
+     * The function `showOutputOnScreen` displays missing references on the terminal screen if the
+     * `showTerminalOutput` flag is set to true.
+     * @param {{ module: string; missingRefs?: Record<string, any> }[]} allMissingRefs - An array of
+     * objects, where each object has two properties:
+     */
+    showOutputOnScreen(allMissingRefs) {
+        if (this.sharedConfig.showTerminalOutput) {
+            this.log(''); // NOTE adding new line
+            for (const { module, missingRefs } of allMissingRefs) {
+                if (!(0, isEmpty_1.default)(missingRefs)) {
+                    (0, log_1.print)([
+                        {
+                            bold: true,
+                            color: 'cyan',
+                            message: ` ${module}`,
+                        },
+                    ]);
+                    cli_utilities_1.ux.table(Object.values(missingRefs).flat(), {
+                        name: {
+                            minWidth: 7,
+                            header: 'Title',
+                        },
+                        display_name: {
+                            minWidth: 7,
+                            header: 'Field name',
+                        },
+                        data_type: {
+                            minWidth: 7,
+                            header: 'Field type',
+                        },
+                        missingRefs: {
+                            minWidth: 7,
+                            header: 'Missing references',
+                            get: (row) => {
+                                return chalk_1.default.red(typeof row.missingRefs === 'object' ? JSON.stringify(row.missingRefs) : row.missingRefs);
+                            },
+                        },
+                        treeStr: {
+                            minWidth: 7,
+                            header: 'Path',
+                        },
+                    }, Object.assign({}, this.flags));
+                    this.log(''); // NOTE adding new line
+                }
+            }
+        }
+    }
+    /**
+     * The function prepares a report by writing a JSON file and a CSV file with a list of missing
+     * references for a given module.
+     * @param moduleName - The `moduleName` parameter is a string that represents the name of a module.
+     * It is used to generate the filename for the report.
+     * @param listOfMissingRefs - The `listOfMissingRefs` parameter is a record object that contains
+     * information about missing references. It is a key-value pair where the key represents the
+     * reference name and the value represents additional information about the missing reference.
+     * @returns The function `prepareReport` returns a Promise that resolves to `void`.
+     */
+    prepareReport(moduleName, listOfMissingRefs) {
+        if ((0, isEmpty_1.default)(listOfMissingRefs))
+            return Promise.resolve(void 0);
+        if (!(0, fs_1.existsSync)(this.sharedConfig.reportPath)) {
+            (0, fs_1.mkdirSync)(this.sharedConfig.reportPath, { recursive: true });
+        }
+        // NOTE write int json
+        (0, fs_1.writeFileSync)((0, path_1.join)(this.sharedConfig.reportPath, `${moduleName}.json`), JSON.stringify(listOfMissingRefs));
+        // NOTE write into CSV
+        return this.prepareCSV(moduleName, listOfMissingRefs);
+    }
+    /**
+     * The function `prepareCSV` takes a module name and a list of missing references, and generates a
+     * CSV file with the specified columns and filtered rows.
+     * @param moduleName - The `moduleName` parameter is a string that represents the name of a module.
+     * It is used to generate the name of the CSV file that will be created.
+     * @param listOfMissingRefs - The `listOfMissingRefs` parameter is a record object that contains
+     * information about missing references. Each key in the record represents a reference, and the
+     * corresponding value is an array of objects that contain details about the missing reference.
+     * @returns The function `prepareCSV` returns a Promise that resolves to `void`.
+     */
+    prepareCSV(moduleName, listOfMissingRefs) {
+        const csvStream = csv.format({ headers: true });
+        const csvPath = (0, path_1.join)(this.sharedConfig.reportPath, `${moduleName}.csv`);
+        const assetFileStream = (0, fs_1.createWriteStream)(csvPath);
+        assetFileStream.on('error', (error) => {
+            throw error;
+        });
+        return new Promise((resolve, reject) => {
+            csvStream.pipe(assetFileStream).on('close', resolve).on('error', reject);
+            const defaultColumns = Object.keys(types_1.OutputColumn);
+            const userDefinedColumns = this.sharedConfig.flags.columns ? this.sharedConfig.flags.columns.split(',') : null;
+            let missingRefs = Object.values(listOfMissingRefs).flat();
+            const columns = userDefinedColumns
+                ? [...userDefinedColumns, ...defaultColumns.filter((val) => !userDefinedColumns.includes(val))]
+                : defaultColumns;
+            if (this.sharedConfig.flags.filter) {
+                const [column, value] = this.sharedConfig.flags.filter.split('=');
+                missingRefs = missingRefs.filter((row) => row[types_1.OutputColumn[column]] === value);
+            }
+            for (const issue of missingRefs) {
+                let row = {};
+                for (const column of columns) {
+                    row[column] = issue[types_1.OutputColumn[column]];
+                    row[column] = typeof row[column] === 'object' ? JSON.stringify(row[column]) : row[column];
+                }
+                csvStream.write(row);
+            }
+            csvStream.end();
+        });
+    }
+}
+exports.default = Audit;
+Audit.aliases = ['cm:stacks:audit'];
+Audit.description = 'Perform audits and find possible errors in the exported Contentstack data';
+Audit.examples = [
+    '$ <%= config.bin %> <%= command.id %>',
+    '$ <%= config.bin %> <%= command.id %> --report-path=<path>',
+    '$ <%= config.bin %> <%= command.id %> --report-path=<path> --csv',
+    '$ <%= config.bin %> <%= command.id %> --report-path=<path> --filter="name=<filter-value>"',
+    '$ <%= config.bin %> <%= command.id %> --report-path=<path> --modules=content-types --filter="name="<filter-value>"',
+];
+Audit.flags = Object.assign({ 'report-path': cli_utilities_1.Flags.string({
+        description: messages_1.auditMsg.REPORT_PATH,
+    }), 'reference-only': cli_utilities_1.Flags.boolean({
+        hidden: true,
+        description: messages_1.auditMsg.REFERENCE_ONLY,
+    }), modules: cli_utilities_1.Flags.string({
+        multiple: true,
+        options: config_1.default.modules,
+        description: messages_1.auditMsg.MODULES,
+    }) }, cli_utilities_1.ux.table.flags({
+    only: ['columns', 'sort', 'filter', 'csv', 'no-truncate'],
+}));

package/lib/config/index.d.ts

@@ -0,0 +1,28 @@
+declare const config: {
+    showTerminalOutput: boolean;
+    skipRefs: string[];
+    modules: string[];
+    moduleConfig: {
+        'content-types': {
+            name: string;
+            fileName: string;
+            dirName: string;
+        };
+        'global-fields': {
+            name: string;
+            dirName: string;
+            fileName: string;
+        };
+        entries: {
+            name: string;
+            dirName: string;
+            fileName: string;
+        };
+        locales: {
+            name: string;
+            dirName: string;
+            fileName: string;
+        };
+    };
+};
+export default config;

package/lib/config/index.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config = {
+    showTerminalOutput: true,
+    skipRefs: ['sys_assets'],
+    modules: ['content-types', 'global-fields', 'entries'],
+    moduleConfig: {
+        'content-types': {
+            name: 'content type',
+            fileName: 'schema.json',
+            dirName: 'content_types',
+        },
+        'global-fields': {
+            name: 'global field',
+            dirName: 'global_fields',
+            fileName: 'globalfields.json',
+        },
+        entries: {
+            name: 'entries',
+            dirName: 'entries',
+            fileName: 'entries.json',
+        },
+        locales: {
+            name: 'locales',
+            dirName: 'locales',
+            fileName: 'locales.json',
+        },
+    },
+};
+exports.default = config;

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: {};
+export default _default;

package/lib/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = {};

package/lib/messages/index.d.ts

@@ -0,0 +1,33 @@
+declare const errors: {
+    NOT_EMPTY: string;
+};
+declare const commonMsg: {
+    CONFIG: string;
+    CURRENT_WORKING_DIR: string;
+    DATA_DIR: string;
+};
+declare const auditMsg: {
+    REPORT_PATH: string;
+    MODULES: string;
+    AUDIT_START_SPINNER: string;
+    PREPARING_ENTRY_METADATA: string;
+    REFERENCE_ONLY: string;
+    NOT_VALID_PATH: string;
+    NO_MISSING_REF_FOUND: string;
+    FINAL_REPORT_PATH: string;
+    SCAN_CT_SUCCESS_MSG: string;
+    SCAN_ENTRY_SUCCESS_MSG: string;
+};
+declare const messages: typeof errors & typeof commonMsg & typeof auditMsg;
+/**
+ * The function `$t` is a TypeScript function that replaces placeholders in a string with corresponding
+ * values from an object.
+ * @param {string} msg - The `msg` parameter is a string that represents a message or a template with
+ * placeholders. These placeholders are enclosed in curly braces, such as `{key}`.
+ * @param args - The `args` parameter is an object that contains key-value pairs. The keys represent
+ * placeholders in the `msg` string, and the values are the replacements for those placeholders.
+ * @returns a string.
+ */
+declare function $t(msg: string, args: Record<string, string>): string;
+export default messages;
+export { $t, errors, commonMsg, auditMsg };

package/lib/messages/index.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditMsg = exports.commonMsg = exports.errors = exports.$t = void 0;
+const errors = {
+    NOT_EMPTY: '{value} cannot be empty.',
+};
+exports.errors = errors;
+const commonMsg = {
+    CONFIG: 'Path of the external config.',
+    CURRENT_WORKING_DIR: 'Current working directory.',
+    DATA_DIR: 'Path where the data is stored.',
+};
+exports.commonMsg = commonMsg;
+const auditMsg = {
+    REPORT_PATH: 'Path to store the audit reports.',
+    MODULES: 'Provide the list of modules to be audited.',
+    AUDIT_START_SPINNER: '{module} scanning...',
+    PREPARING_ENTRY_METADATA: 'Creating entry metadata...',
+    REFERENCE_ONLY: 'Checks only for missing references.',
+    NOT_VALID_PATH: "Provided path '{path}' is not valid.",
+    NO_MISSING_REF_FOUND: 'No missing references found.',
+    FINAL_REPORT_PATH: "Reports ready. Please find the reports at '{path}'.",
+    SCAN_CT_SUCCESS_MSG: "Successfully completed the scanning of {module} '{title}'.",
+    SCAN_ENTRY_SUCCESS_MSG: "Successfully completed the scanning of {module} ({local}) '{title}'.",
+};
+exports.auditMsg = auditMsg;
+const messages = Object.assign(Object.assign(Object.assign({}, errors), commonMsg), auditMsg);
+/**
+ * The function `$t` is a TypeScript function that replaces placeholders in a string with corresponding
+ * values from an object.
+ * @param {string} msg - The `msg` parameter is a string that represents a message or a template with
+ * placeholders. These placeholders are enclosed in curly braces, such as `{key}`.
+ * @param args - The `args` parameter is an object that contains key-value pairs. The keys represent
+ * placeholders in the `msg` string, and the values are the replacements for those placeholders.
+ * @returns a string.
+ */
+function $t(msg, args) {
+    if (!msg)
+        return '';
+    for (const key of Object.keys(args)) {
+        msg = msg.replace(new RegExp(`{${key}}`, 'g'), args[key]);
+    }
+    return msg;
+}
+exports.$t = $t;
+exports.default = messages;

package/lib/modules/content-types.d.ts

@@ -0,0 +1,96 @@
+import { LogFn, ConfigType, ModularBlockType, ContentTypeStruct, GroupFieldDataType, RefErrorReturnType, CtConstructorParam, GlobalFieldDataType, JsonRTEFieldDataType, ModularBlocksDataType, ModuleConstructorParam, ReferenceFieldDataType } from '../types';
+import auditConfig from '../config';
+export default class ContentType {
+    log: LogFn;
+    fileName: string;
+    config: ConfigType;
+    folderPath: string;
+    currentUid: string;
+    currentTitle: string;
+    gfSchema: ContentTypeStruct[];
+    ctSchema: ContentTypeStruct[];
+    protected schema: ContentTypeStruct[];
+    protected missingRefs: Record<string, any>;
+    moduleName: keyof typeof auditConfig.moduleConfig;
+    constructor({ log, config, moduleName, ctSchema, gfSchema }: ModuleConstructorParam & CtConstructorParam);
+    /**
+     * The `run` function checks if a folder path exists, sets the schema based on the module name,
+     * iterates over the schema and looks for references, and returns a list of missing references.
+     * @returns the `missingRefs` object.
+     */
+    run(): Promise<Record<string, any>>;
+    /**
+     * The function `lookForReference` iterates through a given schema and performs validation checks
+     * based on the data type of each field.
+     * @param {Record<string, unknown>[]} tree - An array of objects representing the tree structure of
+     * the content type or field being validated. Each object in the array should have a "uid" property
+     * representing the unique identifier of the content type or field, and a "name" property
+     * representing the display name of the content type or field.
+     * @param {ContentTypeStruct | GlobalFieldDataType | ModularBlockType | GroupFieldDataType}  - -
+     * `tree`: An array of objects representing the tree structure of the content type or field. Each
+     * object in the array should have a `uid` and `name` property.
+     */
+    lookForReference(tree: Record<string, unknown>[], { schema }: ContentTypeStruct | GlobalFieldDataType | ModularBlockType | GroupFieldDataType): Promise<void>;
+    /**
+     * The function validates a reference field in a tree data structure.
+     * @param {Record<string, unknown>[]} tree - The "tree" parameter is an array of objects, where each
+     * object represents a node in a tree-like structure. Each object can have multiple properties, and
+     * the structure of the tree is defined by the relationships between these properties.
+     * @param {ReferenceFieldDataType} field - The `field` parameter is of type `ReferenceFieldDataType`.
+     * @returns an array of RefErrorReturnType.
+     */
+    validateReferenceField(tree: Record<string, unknown>[], field: ReferenceFieldDataType): RefErrorReturnType[];
+    /**
+     * The function "validateGlobalField" asynchronously validates a global field by looking for a
+     * reference in a tree data structure.
+     * @param {Record<string, unknown>[]} tree - The `tree` parameter is an array of objects. Each object
+     * represents a node in a tree structure. The tree structure can be represented as a hierarchical
+     * structure where each object can have child nodes.
+     * @param {GlobalFieldDataType} field - The `field` parameter is of type `GlobalFieldDataType`. It
+     * represents the field that needs to be validated.
+     */
+    validateGlobalField(tree: Record<string, unknown>[], field: GlobalFieldDataType): Promise<void>;
+    /**
+     * The function validates the reference to values in a JSON RTE field.
+     * @param {Record<string, unknown>[]} tree - The "tree" parameter is an array of objects where each
+     * object represents a node in a tree-like structure. Each object can have multiple key-value pairs,
+     * where the key is a string and the value can be of any type.
+     * @param {JsonRTEFieldDataType} field - The `field` parameter is of type `JsonRTEFieldDataType`.
+     * @returns The function `validateJsonRTEFields` is returning an array of `RefErrorReturnType`
+     * objects.
+     */
+    validateJsonRTEFields(tree: Record<string, unknown>[], field: JsonRTEFieldDataType): RefErrorReturnType[];
+    /**
+     * The function validates the modular blocks field by traversing each module and looking for
+     * references.
+     * @param {Record<string, unknown>[]} tree - An array of objects representing the tree structure of
+     * the modular blocks. Each object in the array represents a node in the tree and contains properties
+     * like "uid" and "name".
+     * @param {ModularBlocksDataType} field - The `field` parameter is of type `ModularBlocksDataType`.
+     * It represents a modular blocks field and contains an array of blocks. Each block has properties
+     * like `uid` and `title`.
+     */
+    validateModularBlocksField(tree: Record<string, unknown>[], field: ModularBlocksDataType): Promise<void>;
+    /**
+     * The function `validateGroupField` is an asynchronous function that validates a group field by
+     * looking for a reference in a tree data structure.
+     * @param {Record<string, unknown>[]} tree - The `tree` parameter is an array of objects that
+     * represents a tree structure. Each object in the array represents a node in the tree, and it
+     * contains key-value pairs where the keys are field names and the values are the corresponding field
+     * values.
+     * @param {GroupFieldDataType} field - The `field` parameter is of type `GroupFieldDataType`. It
+     * represents the group field that needs to be validated.
+     */
+    validateGroupField(tree: Record<string, unknown>[], field: GroupFieldDataType): Promise<void>;
+    /**
+     * The function `validateReferenceToValues` checks if all the references specified in a field exist
+     * in a given tree of records and returns any missing references.
+     * @param {Record<string, unknown>[]} tree - An array of objects representing a tree structure. Each
+     * object in the array should have a "name" property.
+     * @param {ReferenceFieldDataType | JsonRTEFieldDataType} field - The `field` parameter is an object
+     * that represents a reference field in a content type. It has the following properties:
+     * @returns The function `validateReferenceToValues` returns an array of `RefErrorReturnType`
+     * objects.
+     */
+    validateReferenceToValues(tree: Record<string, unknown>[], field: ReferenceFieldDataType | JsonRTEFieldDataType): RefErrorReturnType[];
+}