@microsoft/api-extractor 7.56.3 → 7.57.1

package/lib-esm/api/ExtractorConfig.js

@@ -0,0 +1,801 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import * as path from 'node:path';
+import * as resolve from 'resolve';
+import { EnumMemberOrder, ReleaseTag } from '@microsoft/api-extractor-model';
+import { TSDocConfiguration, TSDocTagDefinition } from '@microsoft/tsdoc';
+import { TSDocConfigFile } from '@microsoft/tsdoc-config';
+import { RigConfig } from '@rushstack/rig-package';
+import { JsonFile, JsonSchema, FileSystem, PackageJsonLookup, PackageName, Text, InternalError, Path, NewlineKind } from '@rushstack/node-core-library';
+import { PackageMetadataManager } from '../analyzer/PackageMetadataManager';
+import { MessageRouter } from '../collector/MessageRouter';
+import apiExtractorSchema from '../schemas/api-extractor.schema.json';
+/** Default {@link IConfigApiReport.reportVariants} */
+const defaultApiReportVariants = ['complete'];
+/**
+ * Default {@link IConfigApiReport.tagsToReport}.
+ *
+ * @remarks
+ * Note that this list is externally documented, and directly affects report output.
+ * Also note that the order of tags in this list is significant, as it determines the order of tags in the report.
+ * Any changes to this list should be considered breaking.
+ */
+const defaultTagsToReport = {
+    '@sealed': true,
+    '@virtual': true,
+    '@override': true,
+    '@eventProperty': true,
+    '@deprecated': true
+};
+/**
+ * The `ExtractorConfig` class loads, validates, interprets, and represents the api-extractor.json config file.
+ * @sealed
+ * @public
+ */
+export class ExtractorConfig {
+    /**
+     * Gets the file path for the "complete" (default) report configuration, if one was specified.
+     * Otherwise, returns an empty string.
+     * @deprecated Use {@link ExtractorConfig.reportConfigs} to access all report configurations.
+     */
+    get reportFilePath() {
+        const completeConfig = this._getCompleteReportConfig();
+        return completeConfig === undefined ? '' : path.join(this.reportFolder, completeConfig.fileName);
+    }
+    /**
+     * Gets the temp file path for the "complete" (default) report configuration, if one was specified.
+     * Otherwise, returns an empty string.
+     * @deprecated Use {@link ExtractorConfig.reportConfigs} to access all report configurations.
+     */
+    get reportTempFilePath() {
+        const completeConfig = this._getCompleteReportConfig();
+        return completeConfig === undefined ? '' : path.join(this.reportTempFolder, completeConfig.fileName);
+    }
+    constructor({ projectFolder, packageJson, packageFolder, mainEntryPointFilePath, bundledPackages, tsconfigFilePath, overrideTsconfig, skipLibCheck, apiReportEnabled, apiReportIncludeForgottenExports, reportConfigs, reportFolder, reportTempFolder, tagsToReport, docModelGenerationOptions, apiJsonFilePath, docModelIncludeForgottenExports, projectFolderUrl, rollupEnabled, untrimmedFilePath, alphaTrimmedFilePath, betaTrimmedFilePath, publicTrimmedFilePath, omitTrimmingComments, tsdocMetadataEnabled, tsdocMetadataFilePath, tsdocConfigFile, tsdocConfiguration, newlineKind, messages, testMode, enumMemberOrder }) {
+        this.projectFolder = projectFolder;
+        this.packageJson = packageJson;
+        this.packageFolder = packageFolder;
+        this.mainEntryPointFilePath = mainEntryPointFilePath;
+        this.bundledPackages = bundledPackages;
+        this.tsconfigFilePath = tsconfigFilePath;
+        this.overrideTsconfig = overrideTsconfig;
+        this.skipLibCheck = skipLibCheck;
+        this.apiReportEnabled = apiReportEnabled;
+        this.apiReportIncludeForgottenExports = apiReportIncludeForgottenExports;
+        this.reportConfigs = reportConfigs;
+        this.reportFolder = reportFolder;
+        this.reportTempFolder = reportTempFolder;
+        this.tagsToReport = tagsToReport;
+        this.docModelGenerationOptions = docModelGenerationOptions;
+        this.apiJsonFilePath = apiJsonFilePath;
+        this.docModelIncludeForgottenExports = docModelIncludeForgottenExports;
+        this.projectFolderUrl = projectFolderUrl;
+        this.rollupEnabled = rollupEnabled;
+        this.untrimmedFilePath = untrimmedFilePath;
+        this.alphaTrimmedFilePath = alphaTrimmedFilePath;
+        this.betaTrimmedFilePath = betaTrimmedFilePath;
+        this.publicTrimmedFilePath = publicTrimmedFilePath;
+        this.omitTrimmingComments = omitTrimmingComments;
+        this.tsdocMetadataEnabled = tsdocMetadataEnabled;
+        this.tsdocMetadataFilePath = tsdocMetadataFilePath;
+        this.tsdocConfigFile = tsdocConfigFile;
+        this.tsdocConfiguration = tsdocConfiguration;
+        this.newlineKind = newlineKind;
+        this.messages = messages;
+        this.testMode = testMode;
+        this.enumMemberOrder = enumMemberOrder;
+    }
+    /**
+     * Returns a JSON-like string representing the `ExtractorConfig` state, which can be printed to a console
+     * for diagnostic purposes.
+     *
+     * @remarks
+     * This is used by the "--diagnostics" command-line option.  The string is not intended to be deserialized;
+     * its format may be changed at any time.
+     */
+    getDiagnosticDump() {
+        // Handle the simple JSON-serializable properties using buildJsonDumpObject()
+        const result = MessageRouter.buildJsonDumpObject(this, {
+            keyNamesToOmit: ['tsdocConfigFile', 'tsdocConfiguration']
+        });
+        // Implement custom formatting for tsdocConfigFile and tsdocConfiguration
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        result.tsdocConfigFile = {
+            filePath: this.tsdocConfigFile.filePath,
+            log: this.tsdocConfigFile.log.messages.map((x) => x.toString())
+        };
+        return JSON.stringify(result, undefined, 2);
+    }
+    /**
+     * Returns a simplified file path for use in error messages.
+     * @internal
+     */
+    _getShortFilePath(absolutePath) {
+        if (!path.isAbsolute(absolutePath)) {
+            throw new InternalError('Expected absolute path: ' + absolutePath);
+        }
+        if (Path.isUnderOrEqual(absolutePath, this.projectFolder)) {
+            return Path.convertToSlashes(path.relative(this.projectFolder, absolutePath));
+        }
+        return absolutePath;
+    }
+    /**
+     * Searches for the api-extractor.json config file associated with the specified starting folder,
+     * and loads the file if found.  This lookup supports
+     * {@link https://www.npmjs.com/package/@rushstack/rig-package | rig packages}.
+     *
+     * @remarks
+     * The search will first look for a package.json file in a parent folder of the starting folder;
+     * if found, that will be used as the base folder instead of the starting folder.  If the config
+     * file is not found in `<baseFolder>/api-extractor.json` or `<baseFolder>/config/api-extractor.json`,
+     * then `<baseFolder/config/rig.json` will be checked to see whether a
+     * {@link https://www.npmjs.com/package/@rushstack/rig-package | rig package} is referenced; if so then
+     * the rig's api-extractor.json file will be used instead.  If a config file is found, it will be loaded
+     * and returned with the `IExtractorConfigPrepareOptions` object. Otherwise, `undefined` is returned
+     * to indicate that API Extractor does not appear to be configured for the specified folder.
+     *
+     * @returns An options object that can be passed to {@link ExtractorConfig.prepare}, or `undefined`
+     * if not api-extractor.json file was found.
+     */
+    static tryLoadForFolder(options) {
+        const packageJsonLookup = options.packageJsonLookup || new PackageJsonLookup();
+        const startingFolder = options.startingFolder;
+        // Figure out which project we're in and look for the config file at the project root
+        const packageJsonFullPath = packageJsonLookup.tryGetPackageJsonFilePathFor(startingFolder);
+        const packageFolder = packageJsonFullPath
+            ? path.dirname(packageJsonFullPath)
+            : undefined;
+        // If there is no package, then just use the starting folder
+        const baseFolder = packageFolder || startingFolder;
+        let projectFolderLookupToken = undefined;
+        // First try the standard "config" subfolder:
+        let configFilename = path.join(baseFolder, 'config', ExtractorConfig.FILENAME);
+        if (FileSystem.exists(configFilename)) {
+            if (FileSystem.exists(path.join(baseFolder, ExtractorConfig.FILENAME))) {
+                throw new Error(`Found conflicting ${ExtractorConfig.FILENAME} files in "." and "./config" folders`);
+            }
+        }
+        else {
+            // Otherwise try the top-level folder
+            configFilename = path.join(baseFolder, ExtractorConfig.FILENAME);
+            if (!FileSystem.exists(configFilename)) {
+                // If We didn't find it in <packageFolder>/api-extractor.json or <packageFolder>/config/api-extractor.json
+                // then check for a rig package
+                if (packageFolder) {
+                    let rigConfig;
+                    if (options.rigConfig) {
+                        // The caller provided an already solved RigConfig.  Double-check that it is for the right project.
+                        if (!Path.isEqual(options.rigConfig.projectFolderPath, packageFolder)) {
+                            throw new Error('The provided ILoadForFolderOptions.rigConfig is for the wrong project folder:\n' +
+                                '\nExpected path: ' +
+                                packageFolder +
+                                '\nProvided path: ' +
+                                options.rigConfig.projectFolderOriginalPath);
+                        }
+                        rigConfig = options.rigConfig;
+                    }
+                    else {
+                        rigConfig = RigConfig.loadForProjectFolder({
+                            projectFolderPath: packageFolder
+                        });
+                    }
+                    if (rigConfig.rigFound) {
+                        configFilename = path.join(rigConfig.getResolvedProfileFolder(), ExtractorConfig.FILENAME);
+                        // If the "projectFolder" setting isn't specified in api-extractor.json, it defaults to the
+                        // "<lookup>" token which will probe for the tsconfig.json nearest to the api-extractor.json path.
+                        // But this won't work if api-extractor.json belongs to the rig.  So instead "<lookup>" should be
+                        // the "<packageFolder>" that referenced the rig.
+                        projectFolderLookupToken = packageFolder;
+                    }
+                }
+                if (!FileSystem.exists(configFilename)) {
+                    // API Extractor does not seem to be configured for this folder
+                    return undefined;
+                }
+            }
+        }
+        const configObjectFullPath = path.resolve(configFilename);
+        const configObject = ExtractorConfig.loadFile(configObjectFullPath);
+        return {
+            configObject,
+            configObjectFullPath,
+            packageJsonFullPath,
+            projectFolderLookupToken
+        };
+    }
+    /**
+     * Loads the api-extractor.json config file from the specified file path, and prepares an `ExtractorConfig` object.
+     *
+     * @remarks
+     * Loads the api-extractor.json config file from the specified file path.   If the "extends" field is present,
+     * the referenced file(s) will be merged.  For any omitted fields, the API Extractor default values are merged.
+     *
+     * The result is prepared using `ExtractorConfig.prepare()`.
+     */
+    static loadFileAndPrepare(configJsonFilePath) {
+        const configObjectFullPath = path.resolve(configJsonFilePath);
+        const configObject = ExtractorConfig.loadFile(configObjectFullPath);
+        const packageJsonLookup = new PackageJsonLookup();
+        const packageJsonFullPath = packageJsonLookup.tryGetPackageJsonFilePathFor(configObjectFullPath);
+        const extractorConfig = ExtractorConfig.prepare({
+            configObject,
+            configObjectFullPath,
+            packageJsonFullPath
+        });
+        return extractorConfig;
+    }
+    /**
+     * Performs only the first half of {@link ExtractorConfig.loadFileAndPrepare}, providing an opportunity to
+     * modify the object before it is passed to {@link ExtractorConfig.prepare}.
+     *
+     * @remarks
+     * Loads the api-extractor.json config file from the specified file path.   If the "extends" field is present,
+     * the referenced file(s) will be merged.  For any omitted fields, the API Extractor default values are merged.
+     */
+    static loadFile(jsonFilePath) {
+        // Set to keep track of config files which have been processed.
+        const visitedPaths = new Set();
+        let currentConfigFilePath = path.resolve(jsonFilePath);
+        let configObject = {};
+        // Lodash merges array values by default, which is unintuitive for config files (and makes it impossible for derived configurations to overwrite arrays).
+        // For example, given a base config containing an array property with value ["foo", "bar"] and a derived config that specifies ["baz"] for that property, lodash will produce ["baz", "bar"], which is unintuitive.
+        // This customizer function ensures that arrays are always overwritten.
+        const mergeCustomizer = (objValue, srcValue) => {
+            if (Array.isArray(srcValue)) {
+                return srcValue;
+            }
+            // Fall back to default merge behavior.
+            return undefined;
+        };
+        try {
+            do {
+                // Check if this file was already processed.
+                if (visitedPaths.has(currentConfigFilePath)) {
+                    throw new Error(`The API Extractor "extends" setting contains a cycle.` +
+                        `  This file is included twice: "${currentConfigFilePath}"`);
+                }
+                visitedPaths.add(currentConfigFilePath);
+                const currentConfigFolderPath = path.dirname(currentConfigFilePath);
+                // Load the extractor config defined in extends property.
+                const baseConfig = JsonFile.load(currentConfigFilePath);
+                let extendsField = baseConfig.extends || '';
+                // Delete the "extends" field so it doesn't get merged
+                delete baseConfig.extends;
+                if (extendsField) {
+                    if (extendsField.match(/^\.\.?[\\/]/)) {
+                        // EXAMPLE:  "./subfolder/api-extractor-base.json"
+                        extendsField = path.resolve(currentConfigFolderPath, extendsField);
+                    }
+                    else {
+                        // EXAMPLE:  "my-package/api-extractor-base.json"
+                        //
+                        // Resolve "my-package" from the perspective of the current folder.
+                        try {
+                            extendsField = resolve.sync(extendsField, {
+                                basedir: currentConfigFolderPath
+                            });
+                        }
+                        catch (e) {
+                            throw new Error(`Error resolving NodeJS path "${extendsField}": ${e.message}`);
+                        }
+                    }
+                }
+                // This step has to be performed in advance, since the currentConfigFolderPath information will be lost
+                // after lodash.merge() is performed.
+                ExtractorConfig._resolveConfigFileRelativePaths(baseConfig, currentConfigFolderPath);
+                // Merge extractorConfig into baseConfig, mutating baseConfig
+                lodash.mergeWith(baseConfig, configObject, mergeCustomizer);
+                configObject = baseConfig;
+                currentConfigFilePath = extendsField;
+            } while (currentConfigFilePath);
+        }
+        catch (e) {
+            throw new Error(`Error loading ${currentConfigFilePath}:\n` + e.message);
+        }
+        // Lastly, apply the defaults
+        configObject = lodash.mergeWith(lodash.cloneDeep(ExtractorConfig._defaultConfig), configObject, mergeCustomizer);
+        ExtractorConfig.jsonSchema.validateObject(configObject, jsonFilePath);
+        // The schema validation should ensure that this object conforms to IConfigFile
+        return configObject;
+    }
+    static _resolveConfigFileRelativePaths(configFile, currentConfigFolderPath) {
+        if (configFile.projectFolder) {
+            configFile.projectFolder = ExtractorConfig._resolveConfigFileRelativePath('projectFolder', configFile.projectFolder, currentConfigFolderPath);
+        }
+        if (configFile.mainEntryPointFilePath) {
+            configFile.mainEntryPointFilePath = ExtractorConfig._resolveConfigFileRelativePath('mainEntryPointFilePath', configFile.mainEntryPointFilePath, currentConfigFolderPath);
+        }
+        if (configFile.compiler) {
+            if (configFile.compiler.tsconfigFilePath) {
+                configFile.compiler.tsconfigFilePath = ExtractorConfig._resolveConfigFileRelativePath('tsconfigFilePath', configFile.compiler.tsconfigFilePath, currentConfigFolderPath);
+            }
+        }
+        if (configFile.apiReport) {
+            if (configFile.apiReport.reportFolder) {
+                configFile.apiReport.reportFolder = ExtractorConfig._resolveConfigFileRelativePath('reportFolder', configFile.apiReport.reportFolder, currentConfigFolderPath);
+            }
+            if (configFile.apiReport.reportTempFolder) {
+                configFile.apiReport.reportTempFolder = ExtractorConfig._resolveConfigFileRelativePath('reportTempFolder', configFile.apiReport.reportTempFolder, currentConfigFolderPath);
+            }
+        }
+        if (configFile.docModel) {
+            if (configFile.docModel.apiJsonFilePath) {
+                configFile.docModel.apiJsonFilePath = ExtractorConfig._resolveConfigFileRelativePath('apiJsonFilePath', configFile.docModel.apiJsonFilePath, currentConfigFolderPath);
+            }
+        }
+        if (configFile.dtsRollup) {
+            if (configFile.dtsRollup.untrimmedFilePath) {
+                configFile.dtsRollup.untrimmedFilePath = ExtractorConfig._resolveConfigFileRelativePath('untrimmedFilePath', configFile.dtsRollup.untrimmedFilePath, currentConfigFolderPath);
+            }
+            if (configFile.dtsRollup.alphaTrimmedFilePath) {
+                configFile.dtsRollup.alphaTrimmedFilePath = ExtractorConfig._resolveConfigFileRelativePath('alphaTrimmedFilePath', configFile.dtsRollup.alphaTrimmedFilePath, currentConfigFolderPath);
+            }
+            if (configFile.dtsRollup.betaTrimmedFilePath) {
+                configFile.dtsRollup.betaTrimmedFilePath = ExtractorConfig._resolveConfigFileRelativePath('betaTrimmedFilePath', configFile.dtsRollup.betaTrimmedFilePath, currentConfigFolderPath);
+            }
+            if (configFile.dtsRollup.publicTrimmedFilePath) {
+                configFile.dtsRollup.publicTrimmedFilePath = ExtractorConfig._resolveConfigFileRelativePath('publicTrimmedFilePath', configFile.dtsRollup.publicTrimmedFilePath, currentConfigFolderPath);
+            }
+        }
+        if (configFile.tsdocMetadata) {
+            if (configFile.tsdocMetadata.tsdocMetadataFilePath) {
+                configFile.tsdocMetadata.tsdocMetadataFilePath = ExtractorConfig._resolveConfigFileRelativePath('tsdocMetadataFilePath', configFile.tsdocMetadata.tsdocMetadataFilePath, currentConfigFolderPath);
+            }
+        }
+    }
+    static _resolveConfigFileRelativePath(fieldName, fieldValue, currentConfigFolderPath) {
+        if (!path.isAbsolute(fieldValue)) {
+            if (fieldValue.indexOf('<projectFolder>') !== 0) {
+                // If the path is not absolute and does not start with "<projectFolder>", then resolve it relative
+                // to the folder of the config file that it appears in
+                return path.join(currentConfigFolderPath, fieldValue);
+            }
+        }
+        return fieldValue;
+    }
+    /**
+     * Prepares an `ExtractorConfig` object using a configuration that is provided as a runtime object,
+     * rather than reading it from disk.  This allows configurations to be constructed programmatically,
+     * loaded from an alternate source, and/or customized after loading.
+     */
+    static prepare(options) {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        const filenameForErrors = options.configObjectFullPath || 'the configuration object';
+        const configObject = options.configObject;
+        if (configObject.extends) {
+            throw new Error('The IConfigFile.extends field must be expanded before calling ExtractorConfig.prepare()');
+        }
+        if (options.configObjectFullPath) {
+            if (!path.isAbsolute(options.configObjectFullPath)) {
+                throw new Error('The "configObjectFullPath" setting must be an absolute path');
+            }
+        }
+        ExtractorConfig.jsonSchema.validateObject(configObject, filenameForErrors);
+        const packageJsonFullPath = options.packageJsonFullPath;
+        let packageFolder = undefined;
+        let packageJson = undefined;
+        if (packageJsonFullPath) {
+            if (!/.json$/i.test(packageJsonFullPath)) {
+                // Catch common mistakes e.g. where someone passes a folder path instead of a file path
+                throw new Error('The "packageJsonFullPath" setting does not have a .json file extension');
+            }
+            if (!path.isAbsolute(packageJsonFullPath)) {
+                throw new Error('The "packageJsonFullPath" setting must be an absolute path');
+            }
+            if (options.packageJson) {
+                packageJson = options.packageJson;
+            }
+            else {
+                const packageJsonLookup = new PackageJsonLookup();
+                packageJson = packageJsonLookup.loadNodePackageJson(packageJsonFullPath);
+            }
+            packageFolder = path.dirname(packageJsonFullPath);
+        }
+        // "tsdocConfigFile" and "tsdocConfiguration" are prepared outside the try-catch block,
+        // so that if exceptions are thrown, it will not get the "Error parsing api-extractor.json:" header
+        let extractorConfigParameters;
+        try {
+            if (!configObject.compiler) {
+                // A merged configuration should have this
+                throw new Error('The "compiler" section is missing');
+            }
+            if (!configObject.projectFolder) {
+                // A merged configuration should have this
+                throw new Error('The "projectFolder" setting is missing');
+            }
+            let projectFolder;
+            if (configObject.projectFolder.trim() === '<lookup>') {
+                if (options.projectFolderLookupToken) {
+                    // Use the manually specified "<lookup>" value
+                    projectFolder = options.projectFolderLookupToken;
+                    if (!FileSystem.exists(options.projectFolderLookupToken)) {
+                        throw new Error('The specified "projectFolderLookupToken" path does not exist: ' +
+                            options.projectFolderLookupToken);
+                    }
+                }
+                else {
+                    if (!options.configObjectFullPath) {
+                        throw new Error('The "projectFolder" setting uses the "<lookup>" token, but it cannot be expanded because' +
+                            ' the "configObjectFullPath" setting was not specified');
+                    }
+                    // "The default value for `projectFolder` is the token `<lookup>`, which means the folder is determined
+                    // by traversing parent folders, starting from the folder containing api-extractor.json, and stopping
+                    // at the first folder that contains a tsconfig.json file.  If a tsconfig.json file cannot be found in
+                    // this way, then an error will be reported."
+                    let currentFolder = path.dirname(options.configObjectFullPath);
+                    for (;;) {
+                        const tsconfigPath = path.join(currentFolder, 'tsconfig.json');
+                        if (FileSystem.exists(tsconfigPath)) {
+                            projectFolder = currentFolder;
+                            break;
+                        }
+                        const parentFolder = path.dirname(currentFolder);
+                        if (parentFolder === '' || parentFolder === currentFolder) {
+                            throw new Error('The "projectFolder" setting uses the "<lookup>" token, but a tsconfig.json file cannot be' +
+                                ' found in this folder or any parent folder.');
+                        }
+                        currentFolder = parentFolder;
+                    }
+                }
+            }
+            else {
+                ExtractorConfig._rejectAnyTokensInPath(configObject.projectFolder, 'projectFolder');
+                if (!FileSystem.exists(configObject.projectFolder)) {
+                    throw new Error('The specified "projectFolder" path does not exist: ' + configObject.projectFolder);
+                }
+                projectFolder = configObject.projectFolder;
+            }
+            const tokenContext = {
+                unscopedPackageName: 'unknown-package',
+                packageName: 'unknown-package',
+                projectFolder: projectFolder
+            };
+            if (packageJson) {
+                tokenContext.packageName = packageJson.name;
+                tokenContext.unscopedPackageName = PackageName.getUnscopedName(packageJson.name);
+            }
+            if (!configObject.mainEntryPointFilePath) {
+                // A merged configuration should have this
+                throw new Error('The "mainEntryPointFilePath" setting is missing');
+            }
+            const mainEntryPointFilePath = ExtractorConfig._resolvePathWithTokens('mainEntryPointFilePath', configObject.mainEntryPointFilePath, tokenContext);
+            if (!ExtractorConfig.hasDtsFileExtension(mainEntryPointFilePath)) {
+                throw new Error('The "mainEntryPointFilePath" value is not a declaration file: ' + mainEntryPointFilePath);
+            }
+            if (!options.ignoreMissingEntryPoint && !FileSystem.exists(mainEntryPointFilePath)) {
+                throw new Error('The "mainEntryPointFilePath" path does not exist: ' + mainEntryPointFilePath);
+            }
+            const bundledPackages = configObject.bundledPackages || [];
+            // Note: we cannot fully validate package name patterns, as the strings may contain wildcards.
+            // We won't know if the entries are valid until we can compare them against the package.json "dependencies" contents.
+            const tsconfigFilePath = ExtractorConfig._resolvePathWithTokens('tsconfigFilePath', configObject.compiler.tsconfigFilePath, tokenContext);
+            if (configObject.compiler.overrideTsconfig === undefined) {
+                if (!tsconfigFilePath) {
+                    throw new Error('Either the "tsconfigFilePath" or "overrideTsconfig" setting must be specified');
+                }
+                if (!FileSystem.exists(tsconfigFilePath)) {
+                    throw new Error('The file referenced by "tsconfigFilePath" does not exist: ' + tsconfigFilePath);
+                }
+            }
+            if ((_a = configObject.apiReport) === null || _a === void 0 ? void 0 : _a.tagsToReport) {
+                _validateTagsToReport(configObject.apiReport.tagsToReport);
+            }
+            const apiReportEnabled = (_c = (_b = configObject.apiReport) === null || _b === void 0 ? void 0 : _b.enabled) !== null && _c !== void 0 ? _c : false;
+            const apiReportIncludeForgottenExports = (_e = (_d = configObject.apiReport) === null || _d === void 0 ? void 0 : _d.includeForgottenExports) !== null && _e !== void 0 ? _e : false;
+            let reportFolder = tokenContext.projectFolder;
+            let reportTempFolder = tokenContext.projectFolder;
+            const reportConfigs = [];
+            let tagsToReport = {};
+            if (apiReportEnabled) {
+                // Undefined case checked above where we assign `apiReportEnabled`
+                const apiReportConfig = configObject.apiReport;
+                const reportFileNameSuffix = '.api.md';
+                let reportFileNameBase;
+                if (apiReportConfig.reportFileName) {
+                    if (apiReportConfig.reportFileName.indexOf('/') >= 0 ||
+                        apiReportConfig.reportFileName.indexOf('\\') >= 0) {
+                        throw new Error(`The "reportFileName" setting contains invalid characters: "${apiReportConfig.reportFileName}"`);
+                    }
+                    if (!apiReportConfig.reportFileName.endsWith(reportFileNameSuffix)) {
+                        // `.api.md` extension was not specified. Use provided file name base as is.
+                        reportFileNameBase = apiReportConfig.reportFileName;
+                    }
+                    else {
+                        // The system previously asked users to specify their filenames in a form containing the `.api.md` extension.
+                        // This guidance has changed, but to maintain backwards compatibility, we will temporarily support input
+                        // that ends with the `.api.md` extension specially, by stripping it out.
+                        // This should be removed in version 8, possibly replaced with an explicit error to help users
+                        // migrate their configs.
+                        reportFileNameBase = apiReportConfig.reportFileName.slice(0, -reportFileNameSuffix.length);
+                    }
+                }
+                else {
+                    // Default value
+                    reportFileNameBase = '<unscopedPackageName>';
+                }
+                const reportVariantKinds = (_f = apiReportConfig.reportVariants) !== null && _f !== void 0 ? _f : defaultApiReportVariants;
+                for (const reportVariantKind of reportVariantKinds) {
+                    // Omit the variant kind from the "complete" report file name for simplicity and for backwards compatibility.
+                    const fileNameWithTokens = `${reportFileNameBase}${reportVariantKind === 'complete' ? '' : `.${reportVariantKind}`}${reportFileNameSuffix}`;
+                    const normalizedFileName = ExtractorConfig._expandStringWithTokens('reportFileName', fileNameWithTokens, tokenContext);
+                    reportConfigs.push({
+                        fileName: normalizedFileName,
+                        variant: reportVariantKind
+                    });
+                }
+                if (apiReportConfig.reportFolder) {
+                    reportFolder = ExtractorConfig._resolvePathWithTokens('reportFolder', apiReportConfig.reportFolder, tokenContext);
+                }
+                if (apiReportConfig.reportTempFolder) {
+                    reportTempFolder = ExtractorConfig._resolvePathWithTokens('reportTempFolder', apiReportConfig.reportTempFolder, tokenContext);
+                }
+                tagsToReport = {
+                    ...defaultTagsToReport,
+                    ...apiReportConfig.tagsToReport
+                };
+            }
+            let docModelGenerationOptions = undefined;
+            let apiJsonFilePath = '';
+            let docModelIncludeForgottenExports = false;
+            let projectFolderUrl;
+            if ((_g = configObject.docModel) === null || _g === void 0 ? void 0 : _g.enabled) {
+                apiJsonFilePath = ExtractorConfig._resolvePathWithTokens('apiJsonFilePath', configObject.docModel.apiJsonFilePath, tokenContext);
+                docModelIncludeForgottenExports = !!configObject.docModel.includeForgottenExports;
+                projectFolderUrl = configObject.docModel.projectFolderUrl;
+                const releaseTagsToTrim = new Set();
+                const releaseTagsToTrimOption = configObject.docModel.releaseTagsToTrim || ['@internal'];
+                for (const releaseTagToTrim of releaseTagsToTrimOption) {
+                    let releaseTag;
+                    switch (releaseTagToTrim) {
+                        case '@internal': {
+                            releaseTag = ReleaseTag.Internal;
+                            break;
+                        }
+                        case '@alpha': {
+                            releaseTag = ReleaseTag.Alpha;
+                            break;
+                        }
+                        case '@beta': {
+                            releaseTag = ReleaseTag.Beta;
+                            break;
+                        }
+                        case '@public': {
+                            releaseTag = ReleaseTag.Public;
+                            break;
+                        }
+                        default: {
+                            throw new Error(`The release tag "${releaseTagToTrim}" is not supported`);
+                        }
+                    }
+                    releaseTagsToTrim.add(releaseTag);
+                }
+                docModelGenerationOptions = {
+                    releaseTagsToTrim
+                };
+            }
+            let tsdocMetadataEnabled = false;
+            let tsdocMetadataFilePath = '';
+            if (configObject.tsdocMetadata) {
+                tsdocMetadataEnabled = !!configObject.tsdocMetadata.enabled;
+                if (tsdocMetadataEnabled) {
+                    tsdocMetadataFilePath = configObject.tsdocMetadata.tsdocMetadataFilePath || '';
+                    if (tsdocMetadataFilePath.trim() === '<lookup>') {
+                        if (!packageJson) {
+                            throw new Error('The "<lookup>" token cannot be used with the "tsdocMetadataFilePath" setting because' +
+                                ' the "packageJson" option was not provided');
+                        }
+                        if (!packageJsonFullPath) {
+                            throw new Error('The "<lookup>" token cannot be used with "tsdocMetadataFilePath" because' +
+                                'the "packageJsonFullPath" option was not provided');
+                        }
+                        tsdocMetadataFilePath = PackageMetadataManager.resolveTsdocMetadataPath(path.dirname(packageJsonFullPath), packageJson);
+                    }
+                    else {
+                        tsdocMetadataFilePath = ExtractorConfig._resolvePathWithTokens('tsdocMetadataFilePath', configObject.tsdocMetadata.tsdocMetadataFilePath, tokenContext);
+                    }
+                    if (!tsdocMetadataFilePath) {
+                        throw new Error('The "tsdocMetadata.enabled" setting is enabled,' +
+                            ' but "tsdocMetadataFilePath" is not specified');
+                    }
+                }
+            }
+            let rollupEnabled = false;
+            let untrimmedFilePath = '';
+            let betaTrimmedFilePath = '';
+            let alphaTrimmedFilePath = '';
+            let publicTrimmedFilePath = '';
+            let omitTrimmingComments = false;
+            if (configObject.dtsRollup) {
+                rollupEnabled = !!configObject.dtsRollup.enabled;
+                untrimmedFilePath = ExtractorConfig._resolvePathWithTokens('untrimmedFilePath', configObject.dtsRollup.untrimmedFilePath, tokenContext);
+                alphaTrimmedFilePath = ExtractorConfig._resolvePathWithTokens('alphaTrimmedFilePath', configObject.dtsRollup.alphaTrimmedFilePath, tokenContext);
+                betaTrimmedFilePath = ExtractorConfig._resolvePathWithTokens('betaTrimmedFilePath', configObject.dtsRollup.betaTrimmedFilePath, tokenContext);
+                publicTrimmedFilePath = ExtractorConfig._resolvePathWithTokens('publicTrimmedFilePath', configObject.dtsRollup.publicTrimmedFilePath, tokenContext);
+                omitTrimmingComments = !!configObject.dtsRollup.omitTrimmingComments;
+            }
+            let newlineKind;
+            switch (configObject.newlineKind) {
+                case 'lf':
+                    newlineKind = NewlineKind.Lf;
+                    break;
+                case 'os':
+                    newlineKind = NewlineKind.OsDefault;
+                    break;
+                default:
+                    newlineKind = NewlineKind.CrLf;
+                    break;
+            }
+            const enumMemberOrder = (_h = configObject.enumMemberOrder) !== null && _h !== void 0 ? _h : EnumMemberOrder.ByName;
+            extractorConfigParameters = {
+                projectFolder: projectFolder,
+                packageJson,
+                packageFolder,
+                mainEntryPointFilePath,
+                bundledPackages,
+                tsconfigFilePath,
+                overrideTsconfig: configObject.compiler.overrideTsconfig,
+                skipLibCheck: !!configObject.compiler.skipLibCheck,
+                apiReportEnabled,
+                reportConfigs,
+                reportFolder,
+                reportTempFolder,
+                apiReportIncludeForgottenExports,
+                tagsToReport,
+                docModelGenerationOptions,
+                apiJsonFilePath,
+                docModelIncludeForgottenExports,
+                projectFolderUrl,
+                rollupEnabled,
+                untrimmedFilePath,
+                alphaTrimmedFilePath,
+                betaTrimmedFilePath,
+                publicTrimmedFilePath,
+                omitTrimmingComments,
+                tsdocMetadataEnabled,
+                tsdocMetadataFilePath,
+                newlineKind,
+                messages: configObject.messages || {},
+                testMode: !!configObject.testMode,
+                enumMemberOrder
+            };
+        }
+        catch (e) {
+            throw new Error(`Error parsing ${filenameForErrors}:\n` + e.message);
+        }
+        let tsdocConfigFile = options.tsdocConfigFile;
+        if (!tsdocConfigFile) {
+            // Example: "my-project/tsdoc.json"
+            let packageTSDocConfigPath = TSDocConfigFile.findConfigPathForFolder(extractorConfigParameters.projectFolder);
+            if (!packageTSDocConfigPath || !FileSystem.exists(packageTSDocConfigPath)) {
+                // If the project does not have a tsdoc.json config file, then use API Extractor's base file.
+                packageTSDocConfigPath = ExtractorConfig._tsdocBaseFilePath;
+                if (!FileSystem.exists(packageTSDocConfigPath)) {
+                    throw new InternalError('Unable to load the built-in TSDoc config file: ' + packageTSDocConfigPath);
+                }
+            }
+            tsdocConfigFile = TSDocConfigFile.loadFile(packageTSDocConfigPath);
+        }
+        // IMPORTANT: After calling TSDocConfigFile.loadFile(), we need to check for errors.
+        if (tsdocConfigFile.hasErrors) {
+            throw new Error(tsdocConfigFile.getErrorSummary());
+        }
+        const tsdocConfiguration = new TSDocConfiguration();
+        tsdocConfigFile.configureParser(tsdocConfiguration);
+        // IMPORTANT: After calling TSDocConfigFile.configureParser(), we need to check for errors a second time.
+        if (tsdocConfigFile.hasErrors) {
+            throw new Error(tsdocConfigFile.getErrorSummary());
+        }
+        return new ExtractorConfig({ ...extractorConfigParameters, tsdocConfigFile, tsdocConfiguration });
+    }
+    /**
+     * Gets the report configuration for the "complete" (default) report configuration, if one was specified.
+     */
+    _getCompleteReportConfig() {
+        return this.reportConfigs.find((x) => x.variant === 'complete');
+    }
+    static _resolvePathWithTokens(fieldName, value, tokenContext) {
+        value = ExtractorConfig._expandStringWithTokens(fieldName, value, tokenContext);
+        if (value !== '') {
+            value = path.resolve(tokenContext.projectFolder, value);
+        }
+        return value;
+    }
+    static _expandStringWithTokens(fieldName, value, tokenContext) {
+        value = value ? value.trim() : '';
+        if (value !== '') {
+            value = Text.replaceAll(value, '<unscopedPackageName>', tokenContext.unscopedPackageName);
+            value = Text.replaceAll(value, '<packageName>', tokenContext.packageName);
+            const projectFolderToken = '<projectFolder>';
+            if (value.indexOf(projectFolderToken) === 0) {
+                // Replace "<projectFolder>" at the start of a string
+                value = path.join(tokenContext.projectFolder, value.substr(projectFolderToken.length));
+            }
+            if (value.indexOf(projectFolderToken) >= 0) {
+                // If after all replacements, "<projectFolder>" appears somewhere in the string, report an error
+                throw new Error(`The "${fieldName}" value incorrectly uses the "<projectFolder>" token.` +
+                    ` It must appear at the start of the string.`);
+            }
+            if (value.indexOf('<lookup>') >= 0) {
+                throw new Error(`The "${fieldName}" value incorrectly uses the "<lookup>" token`);
+            }
+            ExtractorConfig._rejectAnyTokensInPath(value, fieldName);
+        }
+        return value;
+    }
+    /**
+     * Returns true if the specified file path has the ".d.ts" file extension.
+     */
+    static hasDtsFileExtension(filePath) {
+        return ExtractorConfig._declarationFileExtensionRegExp.test(filePath);
+    }
+    /**
+     * Given a path string that may have originally contained expandable tokens such as `<projectFolder>"`
+     * this reports an error if any token-looking substrings remain after expansion (e.g. `c:\blah\<invalid>\blah`).
+     */
+    static _rejectAnyTokensInPath(value, fieldName) {
+        if (value.indexOf('<') < 0 && value.indexOf('>') < 0) {
+            return;
+        }
+        // Can we determine the name of a token?
+        const tokenRegExp = /(\<[^<]*?\>)/;
+        const match = tokenRegExp.exec(value);
+        if (match) {
+            throw new Error(`The "${fieldName}" value contains an unrecognized token "${match[1]}"`);
+        }
+        throw new Error(`The "${fieldName}" value contains extra token characters ("<" or ">"): ${value}`);
+    }
+}
+/**
+ * The JSON Schema for API Extractor config file (api-extractor.schema.json).
+ */
+ExtractorConfig.jsonSchema = JsonSchema.fromLoadedObject(apiExtractorSchema);
+/**
+ * The config file name "api-extractor.json".
+ */
+ExtractorConfig.FILENAME = 'api-extractor.json';
+/**
+ * The full path to `extends/tsdoc-base.json` which contains the standard TSDoc configuration
+ * for API Extractor.
+ * @internal
+ */
+ExtractorConfig._tsdocBaseFilePath = path.resolve(__dirname, '../../extends/tsdoc-base.json');
+ExtractorConfig._defaultConfig = JsonFile.load(path.join(__dirname, '../schemas/api-extractor-defaults.json'));
+/** Match all three flavors for type declaration files (.d.ts, .d.mts, .d.cts) */
+ExtractorConfig._declarationFileExtensionRegExp = /\.d\.(c|m)?ts$/i;
+const releaseTags = new Set(['@public', '@alpha', '@beta', '@internal']);
+/**
+ * Validate {@link ExtractorConfig.tagsToReport}.
+ */
+function _validateTagsToReport(tagsToReport) {
+    const includedReleaseTags = [];
+    const invalidTags = []; // tag name, error
+    for (const tag of Object.keys(tagsToReport)) {
+        if (releaseTags.has(tag)) {
+            // If a release tags is specified, regardless of whether it is enabled, we will throw an error.
+            // Release tags must not be specified.
+            includedReleaseTags.push(tag);
+        }
+        // If the tag is invalid, generate an error string from the inner error message.
+        try {
+            TSDocTagDefinition.validateTSDocTagName(tag);
+        }
+        catch (error) {
+            invalidTags.push([tag, error.message]);
+        }
+    }
+    const errorMessages = [];
+    for (const includedReleaseTag of includedReleaseTags) {
+        errorMessages.push(`${includedReleaseTag}: Release tags are always included in API reports and must not be specified`);
+    }
+    for (const [invalidTag, innerError] of invalidTags) {
+        errorMessages.push(`${invalidTag}: ${innerError}`);
+    }
+    if (errorMessages.length > 0) {
+        const errorMessage = [
+            `"tagsToReport" contained one or more invalid tags:`,
+            ...errorMessages
+        ].join('\n\t- ');
+        throw new Error(errorMessage);
+    }
+}
+//# sourceMappingURL=ExtractorConfig.js.map