@terafina/tffa-sfdx-plugin 0.1.0 → 1.0.1

package/lib/apexdoc/common/validator-engine.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/**
+ * Copyright (c) NCR Terafina
+ **/
+const apex_docs_error_1 = tslib_1.__importDefault(require("./apex-docs-error"));
+const engine_config_1 = tslib_1.__importDefault(require("./models/engine-config"));
+const utils_1 = tslib_1.__importDefault(require("./utils"));
+const validator_1 = tslib_1.__importDefault(require("./validator"));
+const fs_1 = require("fs");
+const settings_1 = tslib_1.__importDefault(require("./settings"));
+class ValidatorEngine extends validator_1.default {
+    constructor(config) {
+        super(config);
+        this.validFields = Object.keys(new engine_config_1.default());
+    }
+    // #region Engine Field Validators / Instance Methods
+    includes() {
+        ValidatorEngine.stringArray(this.config.includes, 'includes');
+    }
+    excludes() {
+        ValidatorEngine.stringArray(this.config.excludes, 'excludes');
+    }
+    cleanDir() {
+        this.config.cleanDir = utils_1.default.boolGuard(this.config.cleanDir, false);
+    }
+    showTOCSnippets() {
+        this.config.showTOCSnippets = utils_1.default.boolGuard(this.config.showTOCSnippets, true);
+    }
+    subtitle() {
+        ValidatorEngine.typeGuard('string', this.config.subtitle, 'subtitle');
+    }
+    pages() {
+        this.config.pages = ValidatorEngine.stringArray(this.config.pages, 'pages').map(path => ValidatorEngine.directory(path, 'pages', '.html'));
+    }
+    assets() {
+        // do not validate directory on assets, user will be warned at runtime
+        this.config.assets = ValidatorEngine.stringArray(this.config.assets, 'assets').map(path => utils_1.default.resolveWorkspaceFolder(path));
+    }
+    targetDirectory() {
+        const path = this.config.targetDirectory;
+        ValidatorEngine.typeGuard('string', path, 'targetDirectory');
+        if (path && path.length > 0) {
+            this.config.targetDirectory = utils_1.default.resolveWorkspaceFolder(path);
+        }
+        else {
+            throw new apex_docs_error_1.default(apex_docs_error_1.default.INVALID_TARGET_DIRECTORY(path));
+        }
+    }
+    homePagePath() {
+        ValidatorEngine.typeGuard('string', this.config.homePagePath, 'homePagePath');
+        this.config.homePagePath = ValidatorEngine.directory(this.config.homePagePath, 'homePagePath', '.html');
+    }
+    sortOrder() {
+        let sortOrder = this.config.sortOrder;
+        ValidatorEngine.typeGuard('string', sortOrder, 'sortOrder');
+        sortOrder = sortOrder.toLowerCase();
+        if (sortOrder === settings_1.default.ORDER_LOGICAL || sortOrder === settings_1.default.ORDER_ALPHA) {
+            this.config.sortOrder = sortOrder;
+        }
+        else {
+            throw new apex_docs_error_1.default(apex_docs_error_1.default.INVALID_SORT_ORDER(sortOrder));
+        }
+    }
+    title() {
+        ValidatorEngine.typeGuard('string', this.config.title, 'title');
+        this.config.title = this.config.title || 'Apex Documentation';
+    }
+    scope() {
+        const scopes = this.config.scope;
+        ValidatorEngine.typeGuard('array', scopes, 'scope');
+        if (scopes.length > 6) {
+            throw new apex_docs_error_1.default(apex_docs_error_1.default.SCOPE_ENTRIES_MAX);
+        }
+        if (scopes.length === 0) {
+            throw new apex_docs_error_1.default(apex_docs_error_1.default.SCOPE_ENTRIES_MIN);
+        }
+        const registeredScopes = new Array();
+        scopes.forEach(scope => {
+            if (typeof scope !== 'string') {
+                throw new apex_docs_error_1.default(apex_docs_error_1.default.ONLY_STRINGS('scope'));
+            }
+            let foundScope = false;
+            scope = scope.toLowerCase().trim();
+            settings_1.default.SCOPES.forEach(s => {
+                if (s.toLowerCase() === scope) {
+                    registeredScopes.push(s.toLowerCase());
+                    foundScope = true;
+                }
+            });
+            if (!foundScope) {
+                throw new apex_docs_error_1.default(apex_docs_error_1.default.SCOPE_ENTRY_INVALID(scope));
+            }
+        });
+        this.config.scope = registeredScopes;
+    }
+    source() {
+        this.config.source = this.config.source.map(src => ({
+            path: ValidatorEngine.directory(src.path, 'source.path'),
+            sourceUrl: ValidatorEngine.sourceUrl(src.sourceUrl)
+        }));
+    }
+    // #endregion
+    // #region Static ValidatorEngines
+    static port(port) {
+        this.typeGuard('number', port, 'port');
+        // only allows integers between 0-65535 as port numbers
+        if (!/^([0-9]{1,4}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])$/.test(String(port))) {
+            throw new apex_docs_error_1.default(apex_docs_error_1.default.INVALID_PORT(port));
+        }
+        return port;
+    }
+    // #endregion
+    // #region Static Helpers
+    static directory(path, arg, extension) {
+        this.typeGuard('string', path, arg);
+        // blank directory's can be ignored as default for non-required
+        // arguments. Source directory will always be populated by this point.
+        path = utils_1.default.resolveWorkspaceFolder(path);
+        if (path === '' || fs_1.existsSync(path)) {
+            if (path && extension && !path.endsWith(extension)) {
+                throw new apex_docs_error_1.default(apex_docs_error_1.default.INVALID_EXTENSION(arg, path, extension));
+            }
+            return path;
+        }
+        else {
+            throw new apex_docs_error_1.default(apex_docs_error_1.default.INVALID_DIRECTORY(arg, path));
+        }
+    }
+    static sourceUrl(str) {
+        if (!str) {
+            return undefined;
+        }
+        this.typeGuard('string', str, 'sourceUrl');
+        if (utils_1.default.isURL(str)) {
+            return str.trim();
+        }
+        else {
+            throw new apex_docs_error_1.default(apex_docs_error_1.default.INVALID_SOURCE_URL(str));
+        }
+    }
+    static stringArray(arr, argName) {
+        this.typeGuard('array', arr, argName);
+        arr.forEach(item => {
+            if (typeof item !== 'string') {
+                throw new apex_docs_error_1.default(apex_docs_error_1.default.ONLY_STRINGS(argName));
+            }
+        });
+        return arr;
+    }
+    static typeGuard(type, value, arg) {
+        if ((type === 'array' && Array.isArray(value)) || typeof value === type) {
+            return true;
+        }
+        else {
+            throw new apex_docs_error_1.default(apex_docs_error_1.default.INVALID_TYPE(arg, type));
+        }
+    }
+}
+exports.default = ValidatorEngine;
+//# sourceMappingURL=validator-engine.js.map

package/lib/apexdoc/common/validator-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator-engine.js","sourceRoot":"","sources":["../../../src/apexdoc/common/validator-engine.ts"],"names":[],"mappings":"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"}

package/lib/apexdoc/common/validator.d.ts

@@ -0,0 +1,16 @@
+declare abstract class Validator<T> {
+    protected config: T;
+    [key: string]: any;
+    protected currentFields: string[];
+    protected validFields: string[];
+    constructor(config: T);
+    /**
+     * Since we're allowing rc and yaml config files (e.g. losing helpful intellisense)
+     * we need to carefully validate configs coming in. This method will match each config
+     * key to an instance method which validates that key. For engine configs, the 'port'
+     * setting is the exception which will be validated only at serveDocs runtime. This
+     * will also throw an error if any unexpected, rogue configuration settings are found.
+     */
+    validate(): T;
+}
+export default Validator;

package/lib/apexdoc/common/validator.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/**
+ * Copyright (c) NCR Terafina
+ **/
+const apex_docs_error_1 = tslib_1.__importDefault(require("./apex-docs-error"));
+class Validator {
+    constructor(config) {
+        this.config = config;
+        this.validFields = [];
+        this.config = config;
+        this.currentFields = Object.keys(config);
+    }
+    /**
+     * Since we're allowing rc and yaml config files (e.g. losing helpful intellisense)
+     * we need to carefully validate configs coming in. This method will match each config
+     * key to an instance method which validates that key. For engine configs, the 'port'
+     * setting is the exception which will be validated only at serveDocs runtime. This
+     * will also throw an error if any unexpected, rogue configuration settings are found.
+     */
+    validate() {
+        for (const field of this.currentFields) {
+            if (this.validFields.includes(field)) {
+                this[field] && this[field]();
+            }
+            else {
+                throw new apex_docs_error_1.default(apex_docs_error_1.default.UNKNOWN_CONFIG_SETTING(field));
+            }
+        }
+        return this.config;
+    }
+}
+exports.default = Validator;
+//# sourceMappingURL=validator.js.map

package/lib/apexdoc/common/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../../src/apexdoc/common/validator.ts"],"names":[],"mappings":";;;AAAA;;IAEI;AACJ,gFAA6C;AAE7C,MAAe,SAAS;IAKtB,YAA6B,MAAS;QAAT,WAAM,GAAN,MAAM,CAAG;QAF5B,gBAAW,GAAG,EAAc,CAAC;QAGrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;OAMG;IACI,QAAQ;QACb,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,aAAa,EAAE;YACtC,IAAI,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE;gBACpC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;aAC9B;iBAAM;gBACL,MAAM,IAAI,yBAAY,CAAC,yBAAY,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;aACpE;SACF;QAED,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF;AAED,kBAAe,SAAS,CAAC"}

package/lib/apexdoc/engine/file-manager.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) NCR Terafina
+ **/
+import * as Models from '../common/models';
+import { ISourceEntry, Option, IApexDoxMenus } from '..';
+declare class FileManager {
+    private path;
+    private projectTitle;
+    private userAssets;
+    constructor(targetDirectory: string, projectTitle: string, assets: string[]);
+    /**
+     * Collects the Apex .cls files the user has indicated they'd like to document via config settings.
+     *
+     * @param sources A list of `ISourceEntry` objects from where to collect our .cls files
+     * @param includes See config settings: a list of patterns to include
+     * @param excludes See config settings: a list of patterns to exclude
+     */
+    getFiles(sources: ISourceEntry[], includes: string[], excludes: string[]): ISourceEntry[];
+    /**
+     * Main routine that creates HTML file for each of our classes and for any additional
+     * pages that a user has included, e.g. home page, class group, supplementary.
+     *
+     * @param groupNameMap Map of our class group names to their ClassGroup instances
+     * @param models Map of our model names to their TopLevelModel instances
+     * @param pages Any additional pages, including the project home page, the user has included
+     */
+    createDocs(groupNameMap: Map<string, Models.ClassGroup>, models: Map<string, Models.TopLevelModel>, pages: string[]): void;
+    /**
+     * Parses HTML files provided by the user, like class group pages,
+     * and the project home page. Returns any content between
+     * the <body> tags, or the entire markup if no <body> tags are present.
+     * The extracted markup will be placed within the project's standard
+     * page layout (header, menu, footer) for the final product.
+     *
+     * @param filePath The path of the HTML file to parse.
+     * @returns string representing the markup or void.
+     */
+    parseHTMLFile(filePath: string): Option<string, void>;
+    private makeDirs;
+    private createHTMLFiles;
+    private createSearchIndex;
+    private collectApexDoxAssets;
+    private copyAssetsToTarget;
+    private makePage;
+    makeMenuItems(models: Map<string, Models.TopLevelModel>): void;
+    makeRestDefinition(models: Map<string, Models.TopLevelModel>): void;
+    mapToObj(inputMap: Map<string, any>): any;
+    makeDocumentationPages(fileMap: Map<string, string>, menus: IApexDoxMenus, models: Map<string, Models.TopLevelModel>): void;
+    private makeSupplementaryPages;
+    private makeClassGroupPages;
+}
+export default FileManager;

package/lib/apexdoc/engine/file-manager.js

@@ -0,0 +1,390 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/**
+ * Copyright (c) NCR Terafina
+ **/
+const Models = tslib_1.__importStar(require("../common/models"));
+const apex_docs_error_1 = tslib_1.__importDefault(require("../common/apex-docs-error"));
+const cheerio_1 = tslib_1.__importDefault(require("cheerio"));
+const class_markup_generator_1 = tslib_1.__importDefault(require("./generators/models/class-markup-generator"));
+const enum_markup_generator_1 = tslib_1.__importDefault(require("./generators/models/enum-markup-generator"));
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const generator_utils_1 = tslib_1.__importDefault(require("./generators/generator-utils"));
+const line_reader_1 = tslib_1.__importDefault(require("../common/line-reader"));
+const menu_generator_1 = tslib_1.__importDefault(require("./generators/menu-generator"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const pretty_1 = tslib_1.__importDefault(require("pretty"));
+const rimraf_1 = tslib_1.__importDefault(require("rimraf"));
+const utils_1 = tslib_1.__importDefault(require("../common/utils"));
+const core_1 = require("@salesforce/core");
+const settings_1 = tslib_1.__importDefault(require("../common/settings"));
+class FileManager {
+    constructor(targetDirectory, projectTitle, assets) {
+        this.path = targetDirectory;
+        this.userAssets = assets;
+        this.projectTitle = projectTitle;
+    }
+    // ===========================================================================
+    // #region Public API Methods
+    // ===========================================================================
+    /**
+     * Collects the Apex .cls files the user has indicated they'd like to document via config settings.
+     *
+     * @param sources A list of `ISourceEntry` objects from where to collect our .cls files
+     * @param includes See config settings: a list of patterns to include
+     * @param excludes See config settings: a list of patterns to exclude
+     */
+    getFiles(sources, includes, excludes) {
+        const filesToCopy = new Array(), noneFound = new Array();
+        const isEntryMatch = (entry, fileName) => fileName === entry ||
+            (entry.startsWith('*') && fileName.endsWith(entry.slice(1))) ||
+            (entry.endsWith('*') && fileName.startsWith(entry.slice(0, -1)));
+        for (const src of sources) {
+            const files = fs_1.default.readdirSync(src.path);
+            if (files && files.some(file => file.endsWith('cls'))) {
+                files.forEach(fileName => {
+                    // make sure entry is a file and is an apex class
+                    if (!fileName.endsWith('.cls')) {
+                        return;
+                    }
+                    // if file is explicitly excluded or matches wildcard, return early
+                    for (const entry of excludes) {
+                        if (isEntryMatch(entry, fileName)) {
+                            return;
+                        }
+                    }
+                    // no includes params, include file
+                    if (includes.length === 0) {
+                        filesToCopy.push({
+                            path: path_1.default.resolve(src.path, fileName),
+                            sourceUrl: src.sourceUrl
+                        });
+                        return;
+                    }
+                    // there are includes params, only include files that pass test
+                    for (const entry of includes) {
+                        // file matches explicitly matches or matches wildcard
+                        if (isEntryMatch(entry, fileName)) {
+                            filesToCopy.push({
+                                path: path_1.default.resolve(src.path, fileName),
+                                sourceUrl: src.sourceUrl
+                            });
+                            return;
+                        }
+                    }
+                });
+            }
+            else if (files && files.some(file => file.endsWith('page') || file.endsWith('component'))) {
+                files.forEach(fileName => {
+                    // make sure entry is a file and is an apex class
+                    if (!(fileName.endsWith('.page') || fileName.endsWith('.component'))) {
+                        return;
+                    }
+                    // if file is explicitly excluded or matches wildcard, return early
+                    for (const entry of excludes) {
+                        if (isEntryMatch(entry, fileName)) {
+                            return;
+                        }
+                    }
+                    // no includes params, include file
+                    if (includes.length === 0) {
+                        filesToCopy.push({
+                            path: path_1.default.resolve(src.path, fileName),
+                            sourceUrl: src.sourceUrl
+                        });
+                        return;
+                    }
+                    // there are includes params, only include files that pass test
+                    for (const entry of includes) {
+                        // file matches explicitly matches or matches wildcard
+                        if (isEntryMatch(entry, fileName)) {
+                            filesToCopy.push({
+                                path: path_1.default.resolve(src.path, fileName),
+                                sourceUrl: src.sourceUrl
+                            });
+                            return;
+                        }
+                    }
+                });
+            }
+            else {
+                noneFound.push(src.path);
+            }
+        }
+        if (!filesToCopy.length) {
+            // no .cls files found at all, or all .cls files have been excluded, throw error
+            const sourceDirs = sources.map(src => src.path).join(',');
+            throw new apex_docs_error_1.default(apex_docs_error_1.default.NO_FILES_FOUND(sourceDirs));
+        }
+        else if (noneFound.length) {
+            // no .cls files found in one or more (but not all) of given source dirs, show warning
+            throw new core_1.SfdxError(`No matching .cls files found in ${noneFound.join(',')}`);
+        }
+        return filesToCopy;
+    }
+    /**
+     * Main routine that creates HTML file for each of our classes and for any additional
+     * pages that a user has included, e.g. home page, class group, supplementary.
+     *
+     * @param groupNameMap Map of our class group names to their ClassGroup instances
+     * @param models Map of our model names to their TopLevelModel instances
+     * @param pages Any additional pages, including the project home page, the user has included
+     */
+    createDocs(groupNameMap, models, pages) {
+        // make the menu and the scoping panel
+        // and initialize our main file map
+        const fileMap = new Map();
+        const menus = {
+            class: menu_generator_1.default.makeMenu(groupNameMap, models),
+            scope: menu_generator_1.default.makeScopeMenu()
+        };
+        // create the markup for our different varieties of HTML pages
+        // and add to our file map. HTML files will be created from this map.
+        this.makeSupplementaryPages(fileMap, menus, pages);
+        this.makeClassGroupPages(fileMap, menus, groupNameMap);
+        this.makeDocumentationPages(fileMap, menus, models);
+        // Now finalize everything... Make our directories first
+        // if they don't exist yet, then create our HTML files.
+        // Lastly, copy our assets, ours first, then the users.
+        // If they're using a favicon this will override ours.
+        this.makeDirs();
+        this.makeMenuItems(models);
+        this.makeRestDefinition(models);
+        this.createHTMLFiles(fileMap);
+        this.createSearchIndex(fileMap);
+        this.copyAssetsToTarget(this.collectApexDoxAssets());
+        this.copyAssetsToTarget(this.userAssets);
+    }
+    /**
+     * Parses HTML files provided by the user, like class group pages,
+     * and the project home page. Returns any content between
+     * the <body> tags, or the entire markup if no <body> tags are present.
+     * The extracted markup will be placed within the project's standard
+     * page layout (header, menu, footer) for the final product.
+     *
+     * @param filePath The path of the HTML file to parse.
+     * @returns string representing the markup or void.
+     */
+    parseHTMLFile(filePath) {
+        if (!filePath.trim()) {
+            return;
+        }
+        const contents = new line_reader_1.default(filePath).toString();
+        if (contents) {
+            const startIndex = contents.indexOf('<body>');
+            const endIndex = contents.indexOf('</body>');
+            if (startIndex !== -1 && endIndex !== -1) {
+                return contents.substring(startIndex + 6, endIndex);
+            }
+            else if (startIndex === -1 && endIndex === -1) {
+                return contents;
+            }
+        }
+    }
+    // #endregion
+    // ===========================================================================
+    // ===========================================================================
+    // #region FS Utils
+    // ===========================================================================
+    makeDirs() {
+        const root = this.path;
+        const assets = path_1.default.resolve(root, 'assets');
+        // clean directory first if user specified this
+        settings_1.default.config.cleanDir && rimraf_1.default.sync(root);
+        if (!fs_1.default.existsSync(root)) {
+            [root, assets].forEach(path => fs_1.default.mkdirSync(path));
+        }
+        else if (fs_1.default.existsSync(root) && !fs_1.default.existsSync(assets)) {
+            fs_1.default.mkdirSync(assets);
+        }
+    }
+    createHTMLFiles(fileMap) {
+        for (const fileName of fileMap.keys()) {
+            const contents = utils_1.default.preCodeTrim(pretty_1.default(fileMap.get(fileName)));
+            const fullyQualifiedFileName = path_1.default.resolve(this.path, fileName + '.html');
+            fs_1.default.writeFileSync(fullyQualifiedFileName, contents);
+        }
+    }
+    createSearchIndex(fileMap) {
+        const searchIndex = [];
+        fileMap.forEach((contents, fileName) => {
+            const $ = cheerio_1.default.load(contents.replace(/(<\/\w+>)/g, '$1 '));
+            // do some hacky replacements to keep
+            // text as searchable as possible
+            const plainText = $('.doc-page')
+                .text()
+                .replace(/\s\(/g, '(')
+                .split('\n')
+                .map(line => line.trim())
+                .filter(line => !!line);
+            searchIndex.push({
+                title: fileName === 'index' ? 'Home' : fileName,
+                fileName: fileName + '.html',
+                text: plainText.join(' ')
+            });
+        });
+        fs_1.default.writeFileSync(path_1.default.resolve(this.path, 'assets', 'search-idx.js'), `export default ${JSON.stringify(searchIndex, null, 4)};\n`);
+    }
+    collectApexDoxAssets() {
+        const extensionRoot = '../../../';
+        const files = fs_1.default.readdirSync(path_1.default.resolve(__dirname, extensionRoot, 'assets'));
+        return files.map(fileName => path_1.default.resolve(__dirname, extensionRoot, 'assets', fileName));
+    }
+    copyAssetsToTarget(files) {
+        files.forEach(file => {
+            if (fs_1.default.existsSync(file)) {
+                fs_1.default.copyFileSync(file, path_1.default.resolve(this.path, 'assets', path_1.default.basename(file)));
+            }
+            else {
+                throw new core_1.SfdxError(apex_docs_error_1.default.ASSET_NOT_FOUND(file));
+            }
+        });
+    }
+    // #endregion
+    // ===========================================================================
+    // ===========================================================================
+    // #region Document Generators
+    // ===========================================================================
+    makePage(contents, menus, title = '') {
+        const pageTitle = title ? `<h2 class='section-title'>${title}</h2>` : '';
+        const rows = [
+            ['scoping-panel', menus.scope],
+            ['doc-page', pageTitle + contents],
+            ['footer', generator_utils_1.default.footer]
+        ];
+        const html = `<!DOCTYPE html>
+            <html lang="en">
+            ${generator_utils_1.default.makeHead(this.projectTitle)}
+            <body>
+                ${menus.class}
+                <table id="content">
+                ${generator_utils_1.default.mapHTML(rows, ([className, contents]) => `<tr>
+                        <td class="${className}">
+                            ${contents}
+                        </td>
+                    </tr>`)}
+                </table>
+            </body>
+            </html>`;
+        return html;
+    }
+    makeMenuItems(models) {
+        const menuMap = new Map();
+        for (const model of models.values()) {
+            const group = model.groupName;
+            let items = menuMap.get(group);
+            if (!items) {
+                items = [];
+            }
+            const item = { name: model.name, path: model.name + '.html' };
+            items.push(item);
+            menuMap.set(group, items);
+        }
+        const menus = [];
+        for (const k of menuMap.keys()) {
+            const items = menuMap.get(k);
+            if (items) {
+                const menu = { name: k, items: items };
+                menus.push(menu);
+            }
+        }
+        menus.sort((a, b) => a.name.localeCompare(b.name));
+        const fullyQualifiedFileName = path_1.default.resolve(this.path, 'assets', 'menujson' + '.js');
+        let text = 'var menu = ' + JSON.stringify(menus, null, 4);
+        text = text + '\nexport {menu};';
+        fs_1.default.writeFileSync(fullyQualifiedFileName, text);
+    }
+    makeRestDefinition(models) {
+        const definitions = [];
+        const schemas = {};
+        const fileName = 'api';
+        for (const model of models.values()) {
+            if (model.modelType === Models.ModelType.CLASS) {
+                const cModel = model;
+                if (cModel.restUrl) {
+                    definitions.push(...cModel.restDefinition);
+                }
+                if (cModel.isDTO) {
+                    schemas[cModel.name] = cModel.dtoDefinition;
+                    const childs = cModel.childClasses;
+                    if (childs && childs.length > 0)
+                        for (const cdto of childs) {
+                            const name = cdto.name.replace(cModel.name + '.', '');
+                            schemas[name] = cdto.dtoDefinition;
+                        }
+                }
+            }
+        }
+        if (definitions.length > 0) {
+            const fullyQualifiedFileName = path_1.default.resolve(this.path, 'assets', fileName + '.json');
+            fs_1.default.writeFileSync(fullyQualifiedFileName, JSON.stringify(definitions, null, 4));
+        }
+        const fullyQualifiedFileName = path_1.default.resolve(this.path, 'assets', fileName + 'schemas' + '.json');
+        fs_1.default.writeFileSync(fullyQualifiedFileName, JSON.stringify(schemas, null, 4));
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    mapToObj(inputMap) {
+        const obj = {};
+        inputMap.forEach((value, key) => {
+            obj[key] = value;
+        });
+        return obj;
+    }
+    makeDocumentationPages(fileMap, menus, models) {
+        for (const model of models.values()) {
+            let fileName = '';
+            let contents = '';
+            if (model.nameLine) {
+                fileName = model.name;
+                if (model.modelType === Models.ModelType.CLASS) {
+                    const cModel = model;
+                    contents += class_markup_generator_1.default.generate(cModel, models);
+                    // get child classes to work with in the order user specifies
+                    const childClasses = settings_1.default.config.sortOrder === settings_1.default.ORDER_ALPHA ? cModel.childClassesSorted : cModel.childClasses;
+                    // map over child classes, creating HTML, and concat result
+                    contents += childClasses.map(cmChild => class_markup_generator_1.default.generate(cmChild, models)).join('');
+                }
+                else if (model.modelType === Models.ModelType.ENUM) {
+                    const eModel = model;
+                    contents += enum_markup_generator_1.default.generate(eModel, models);
+                }
+            }
+            else {
+                continue;
+            }
+            fileMap.set(fileName, this.makePage(contents, menus));
+        }
+    }
+    makeSupplementaryPages(fileMap, menus, pages) {
+        pages.forEach((pagePath, i) => {
+            if (i === 0) {
+                // our home page is always the first index
+                const homePageContents = this.parseHTMLFile(pagePath);
+                const markup = this.makePage(homePageContents || generator_utils_1.default.defaultHomePage, menus, 'Home');
+                fileMap.set('index', markup);
+            }
+            else {
+                const contents = this.parseHTMLFile(pagePath);
+                if (contents) {
+                    const markup = this.makePage(contents, menus);
+                    fileMap.set(path_1.default.basename(pagePath.substring(0, pagePath.lastIndexOf('.'))), markup);
+                }
+            }
+        });
+    }
+    makeClassGroupPages(fileMap, menus, classGroupMap) {
+        for (const group of classGroupMap.keys()) {
+            const cg = classGroupMap.get(group);
+            if (cg && cg.contentSource) {
+                const cgContent = this.parseHTMLFile(cg.contentSource);
+                if (cgContent) {
+                    const markup = this.makePage(cgContent, menus, generator_utils_1.default.encodeText(cg.name, false));
+                    fileMap.set(cg.contentFileName, markup);
+                }
+            }
+        }
+    }
+}
+exports.default = FileManager;
+//# sourceMappingURL=file-manager.js.map