discord.js/packages/api-extractor/src/api/IConfigFile.ts

// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.

import type { EnumMemberOrder } from '@discordjs/api-extractor-model';
import type { ExtractorLogLevel } from './ExtractorLogLevel.js';

/**
 * Represents an entry point in the package
 * Example:
 * ```
 * {
 *   modulePath: 'Shape/Square',
 *   filePath: './dist/Shape/Square/index.d.ts'
 * }
 * ```
 */
export interface IConfigEntryPoint {
	filePath: string;
	modulePath: string;
}

/**
 * Determines how the TypeScript compiler engine will be invoked by API Extractor.
 *
 * @remarks
 * This is part of the {@link IConfigFile} structure.
 * @public
 */
export interface IConfigCompiler {
	/**
	 * Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
	 *
	 * @remarks
	 * The value must conform to the TypeScript tsconfig schema:
	 *
	 * http://json.schemastore.org/tsconfig
	 *
	 * If omitted, then the tsconfig.json file will instead be read from the projectFolder.
	 */
	overrideTsconfig?: {};

	/**
	 * This option causes the compiler to be invoked with the `--skipLibCheck` option.
	 *
	 * @remarks
	 * This option is not recommended and may cause API Extractor to produce incomplete or incorrect declarations,
	 * but it may be required when dependencies contain declarations that are incompatible with the TypeScript engine
	 * that API Extractor uses for its analysis.  Where possible, the underlying issue should be fixed rather than
	 * relying on skipLibCheck.
	 */
	skipLibCheck?: boolean;

	/**
	 * Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
	 *
	 * @remarks
	 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
	 * prepend a folder token such as `<projectFolder>`.
	 *
	 * Note: This setting will be ignored if `overrideTsconfig` is used.
	 */
	tsconfigFilePath?: string;
}

/**
 * The allowed variations of API reports.
 *
 * @public
 */
export type ApiReportVariant = 'alpha' | 'beta' | 'complete' | 'public';

/**
 * Configures how the API report files (*.api.md) will be generated.
 *
 * @remarks
 * This is part of the {@link IConfigFile} structure.
 * @public
 */
export interface IConfigApiReport {
	/**
	 * Whether to generate an API report.
	 */
	enabled: boolean;

	/**
	 * Whether "forgotten exports" should be included in the API report file.
	 *
	 * @remarks
	 * Forgotten exports are declarations flagged with `ae-forgotten-export` warnings. See
	 * https://api-extractor.com/pages/messages/ae-forgotten-export/ to learn more.
	 * @defaultValue `false`
	 */
	includeForgottenExports?: boolean;

	/**
	 * The base filename for the API report files, to be combined with {@link IConfigApiReport.reportFolder} or
	 * {@link IConfigApiReport.reportTempFolder} to produce the full file path.
	 *
	 * @remarks
	 * The `reportFileName` should not include any path separators such as `\` or `/`.  The `reportFileName` should
	 * not include a file extension, since API Extractor will automatically append an appropriate file extension such
	 * as `.api.md`.  If the {@link IConfigApiReport.reportVariants} setting is used, then the file extension includes
	 * the variant name, for example `my-report.public.api.md` or `my-report.beta.api.md`. The `complete` variant always
	 * uses the simple extension `my-report.api.md`.
	 *
	 * Previous versions of API Extractor required `reportFileName` to include the `.api.md` extension explicitly;
	 * for backwards compatibility, that is still accepted but will be discarded before applying the above rules.
	 * @defaultValue `<unscopedPackageName>`
	 */
	reportFileName?: string;

	/**
	 * Specifies the folder where the API report file is written.  The file name portion is determined by
	 * the `reportFileName` setting.
	 *
	 * @remarks
	 * The API report file is normally tracked by Git.  Changes to it can be used to trigger a branch policy,
	 * e.g. for an API review.
	 *
	 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
	 * prepend a folder token such as `<projectFolder>`.
	 */
	reportFolder?: string;

	/**
	 * Specifies the folder where the temporary report file is written.  The file name portion is determined by
	 * the `reportFileName` setting.
	 *
	 * @remarks
	 * After the temporary file is written to disk, it is compared with the file in the `reportFolder`.
	 * If they are different, a production build will fail.
	 *
	 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
	 * prepend a folder token such as `<projectFolder>`.
	 */
	reportTempFolder?: string;

	/**
	 * The set of report variants to generate.
	 *
	 * @remarks
	 * To support different approval requirements for different API levels, multiple "variants" of the API report can
	 * be generated.  The `reportVariants` setting specifies a list of variants to be generated.  If omitted,
	 * by default only the `complete` variant will be generated, which includes all `@internal`, `@alpha`, `@beta`,
	 * and `@public` items.  Other possible variants are `alpha` (`@alpha` + `@beta` + `@public`),
	 * `beta` (`@beta` + `@public`), and `public` (`@public only`).
	 *
	 * The resulting API report file names will be derived from the {@link IConfigApiReport.reportFileName}.
	 * @defaultValue `[ "complete" ]`
	 */
	reportVariants?: ApiReportVariant[];

	/**
	 * Specifies a list of {@link https://tsdoc.org/ | TSDoc} tags that should be reported in the API report file for
	 * items whose documentation contains them.
	 *
	 * @remarks
	 * Tag names must begin with `@`.
	 *
	 * This list may include standard TSDoc tags as well as custom ones.
	 * For more information on defining custom TSDoc tags, see
	 * {@link https://api-extractor.com/pages/configs/tsdoc_json/#defining-your-own-tsdoc-tags | here}.
	 *
	 * Note that an item's release tag will always reported; this behavior cannot be overridden.
	 * @defaultValue `@sealed`, `@virtual`, `@override`, `@eventProperty`, and `@deprecated`
	 * @example Omitting default tags
	 * To omit the `@sealed` and `@virtual` tags from API reports, you would specify `tagsToReport` as follows:
	 * ```json
	 * "tagsToReport": {
	 *  "@sealed": false,
	 *  "@virtual": false
	 * }
	 * ```
	 * @example Including additional tags
	 * To include additional tags to the set included in API reports, you could specify `tagsToReport` like this:
	 * ```json
	 * "tagsToReport": {
	 *  "@customTag": true
	 * }
	 * ```
	 * This will result in `@customTag` being included in addition to the default tags.
	 */
	tagsToReport?: Readonly<Record<`@${string}`, boolean>>;
}

/**
 * The allowed release tags that can be used to mark API items.
 *
 * @public
 */
export type ReleaseTagForTrim = '@alpha' | '@beta' | '@internal' | '@public';

/**
 * Configures how the doc model file (*.api.json) will be generated.
 *
 * @remarks
 * This is part of the {@link IConfigFile} structure.
 * @public
 */
export interface IConfigDocModel {
	/**
	 * The output path for the doc model file.  The file extension should be ".api.json".
	 *
	 * @remarks
	 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
	 * prepend a folder token such as `<projectFolder>`.
	 */
	apiJsonFilePath?: string;

	/**
	 * Whether to generate a doc model file.
	 */
	enabled: boolean;

	/**
	 * Whether "forgotten exports" should be included in the doc model file.
	 *
	 * @remarks
	 * Forgotten exports are declarations flagged with `ae-forgotten-export` warnings. See
	 * https://api-extractor.com/pages/messages/ae-forgotten-export/ to learn more.
	 * @defaultValue `false`
	 */
	includeForgottenExports?: boolean;

	/**
	 * The base URL where the project's source code can be viewed on a website such as GitHub or
	 * Azure DevOps. This URL path corresponds to the `<projectFolder>` path on disk.
	 *
	 * @remarks
	 * This URL is concatenated with the file paths serialized to the doc model to produce URL file paths to individual API items.
	 * For example, if the `projectFolderUrl` is "https://github.com/microsoft/rushstack/tree/main/apps/api-extractor" and an API
	 * item's file path is "api/ExtractorConfig.ts", the full URL file path would be
	 * "https://github.com/microsoft/rushstack/tree/main/apps/api-extractor/api/ExtractorConfig.js".
	 *
	 * Can be omitted if you don't need source code links in your API documentation reference.
	 */
	projectFolderUrl?: string;

	/**
	 * Specifies a list of release tags that will be trimmed from the doc model.
	 *
	 * @defaultValue `["@internal"]`
	 */
	releaseTagsToTrim?: ReleaseTagForTrim[];
}

/**
 * Configures how the .d.ts rollup file will be generated.
 *
 * @remarks
 * This is part of the {@link IConfigFile} structure.
 * @public
 */
export interface IConfigDtsRollup {
	/**
	 * Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
	 *
	 * @remarks
	 * This file will include only declarations that are marked as `@public`, `@beta`, or `@alpha`.
	 *
	 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
	 * prepend a folder token such as `<projectFolder>`.
	 */
	alphaTrimmedFilePath?: string;

	/**
	 * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
	 *
	 * @remarks
	 * This file will include only declarations that are marked as `@public` or `@beta`.
	 *
	 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
	 * prepend a folder token such as `<projectFolder>`.
	 */
	betaTrimmedFilePath?: string;

	/**
	 * Whether to generate the .d.ts rollup file.
	 */
	enabled: boolean;

	/**
	 * When a declaration is trimmed, by default it will be replaced by a code comment such as
	 * "Excluded from this release type: exampleMember".  Set "omitTrimmingComments" to true to remove the
	 * declaration completely.
	 */
	omitTrimmingComments?: boolean;

	/**
	 * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
	 *
	 * @remarks
	 * This file will include only declarations that are marked as `@public`.
	 *
	 * If the path is an empty string, then this file will not be written.
	 *
	 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
	 * prepend a folder token such as `<projectFolder>`.
	 */
	publicTrimmedFilePath?: string;

	/**
	 * Specifies the output path for a .d.ts rollup file to be generated without any trimming.
	 *
	 * @remarks
	 * This file will include all declarations that are exported by the main entry point.
	 *
	 * If the path is an empty string, then this file will not be written.
	 *
	 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
	 * prepend a folder token such as `<projectFolder>`.
	 */
	untrimmedFilePath?: string;
}

/**
 * Configures how the tsdoc-metadata.json file will be generated.
 *
 * @remarks
 * This is part of the {@link IConfigFile} structure.
 * @public
 */
export interface IConfigTsdocMetadata {
	/**
	 * Whether to generate the tsdoc-metadata.json file.
	 */
	enabled: boolean;

	/**
	 * Specifies where the TSDoc metadata file should be written.
	 *
	 * @remarks
	 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
	 * prepend a folder token such as `<projectFolder>`.
	 *
	 * The default value is `<lookup>`, which causes the path to be automatically inferred from the `tsdocMetadata`,
	 * `typings` or `main` fields of the project's package.json.  If none of these fields are set, the lookup
	 * falls back to `tsdoc-metadata.json` in the package folder.
	 */
	tsdocMetadataFilePath?: string;
}

/**
 * Configures reporting for a given message identifier.
 *
 * @remarks
 * This is part of the {@link IConfigFile} structure.
 * @public
 */
export interface IConfigMessageReportingRule {
	/**
	 * When `addToApiReportFile` is true:  If API Extractor is configured to write an API report file (.api.md),
	 * then the message will be written inside that file; otherwise, the message is instead logged according to
	 * the `logLevel` option.
	 */
	addToApiReportFile?: boolean;

	/**
	 * Specifies whether the message should be written to the tool's output log.
	 *
	 * @remarks
	 * Note that the `addToApiReportFile` property may supersede this option.
	 */
	logLevel: ExtractorLogLevel;
}

/**
 * Specifies a table of reporting rules for different message identifiers, and also the default rule used for
 * identifiers that do not appear in the table.
 *
 * @remarks
 * This is part of the {@link IConfigFile} structure.
 * @public
 */
export interface IConfigMessageReportingTable {
	/**
	 * The key is a message identifier for the associated type of message, or "default" to specify the default policy.
	 * For example, the key might be `TS2551` (a compiler message), `tsdoc-link-tag-unescaped-text` (a TSDOc message),
	 * or `ae-extra-release-tag` (a message related to the API Extractor analysis).
	 */
	[messageId: string]: IConfigMessageReportingRule;
}

/**
 * Configures how API Extractor reports error and warning messages produced during analysis.
 *
 * @remarks
 * This is part of the {@link IConfigFile} structure.
 * @public
 */
export interface IExtractorMessagesConfig {
	/**
	 * Configures handling of diagnostic messages generating the TypeScript compiler while analyzing the
	 * input .d.ts files.
	 */
	compilerMessageReporting?: IConfigMessageReportingTable;

	/**
	 * Configures handling of messages reported by API Extractor during its analysis.
	 */
	extractorMessageReporting?: IConfigMessageReportingTable;

	/**
	 * Configures handling of messages reported by the TSDoc parser when analyzing code comments.
	 */
	tsdocMessageReporting?: IConfigMessageReportingTable;
}

/**
 * Configuration options for the API Extractor tool.  These options can be constructed programmatically
 * or loaded from the api-extractor.json config file using the {@link ExtractorConfig} class.
 *
 * @public
 */
export interface IConfigFile {
	/**
	 * support multiple entry points.
	 */
	additionalEntryPoints: IConfigEntryPoint[];

	/**
	 * {@inheritDoc IConfigApiReport}
	 */
	apiReport?: IConfigApiReport;

	/**
	 * A list of NPM package names whose exports should be treated as part of this package.
	 *
	 * @remarks
	 *
	 * For example, suppose that Webpack is used to generate a distributed bundle for the project `library1`,
	 * and another NPM package `library2` is embedded in this bundle.  Some types from `library2` may become part
	 * of the exported API for `library1`, but by default API Extractor would generate a .d.ts rollup that explicitly
	 * imports `library2`.  To avoid this, we can specify:
	 *
	 * ```js
	 *   "bundledPackages": [ "library2" ],
	 * ```
	 *
	 * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
	 * local files for `library1`.
	 */
	bundledPackages?: string[];

	/**
	 * {@inheritDoc IConfigCompiler}
	 */
	compiler?: IConfigCompiler;

	/**
	 * {@inheritDoc IConfigDocModel}
	 */
	docModel?: IConfigDocModel;

	/**
	 * {@inheritDoc IConfigDtsRollup}
	 *
	 * @beta
	 */
	dtsRollup?: IConfigDtsRollup;

	/**
	 * Specifies how API Extractor sorts members of an enum when generating the .api.json file.
	 *
	 * @remarks
	 * By default, the output files will be sorted alphabetically, which is "by-name".
	 * To keep the ordering in the source code, specify "preserve".
	 * @defaultValue `by-name`
	 */
	enumMemberOrder?: EnumMemberOrder;

	/**
	 * Optionally specifies another JSON config file that this file extends from.  This provides a way for
	 * standard settings to be shared across multiple projects.
	 *
	 * @remarks
	 * If the path starts with `./` or `../`, the path is resolved relative to the folder of the file that contains
	 * the `extends` field.  Otherwise, the first path segment is interpreted as an NPM package name, and will be
	 * resolved using NodeJS `require()`.
	 */
	extends?: string;

	/**
	 * Specifies the .d.ts file to be used as the starting point for analysis.  API Extractor
	 * analyzes the symbols exported by this module.
	 *
	 * @remarks
	 *
	 * The file extension must be ".d.ts" and not ".ts".
	 * The path is resolved relative to the "projectFolder" location.
	 */
	mainEntryPointFilePath: string;

	/**
	 * Specifies the import path of the entrypoint used as the starting point for analysis.
	 */
	mainEntryPointName: string;

	/**
	 * {@inheritDoc IExtractorMessagesConfig}
	 */
	messages?: IExtractorMessagesConfig;

	/**
	 * Specifies what type of newlines API Extractor should use when writing output files.
	 *
	 * @remarks
	 * By default, the output files will be written with Windows-style newlines.
	 * To use POSIX-style newlines, specify "lf" instead.
	 * To use the OS's default newline kind, specify "os".
	 */
	newlineKind?: 'crlf' | 'lf' | 'os';

	/**
	 * Determines the `<projectFolder>` token that can be used with other config file settings.  The project folder
	 * typically contains the tsconfig.json and package.json config files, but the path is user-defined.
	 *
	 * @remarks
	 *
	 * The path is resolved relative to the folder of the config file that contains the setting.
	 *
	 * The default value for `projectFolder` is the token `<lookup>`, which means the folder is determined using
	 * the following heuristics:
	 *
	 * If the config/rig.json system is used (as defined by {@link https://www.npmjs.com/package/@rushstack/rig-package
	 * | @rushstack/rig-package}), then the `<lookup>` value will be the package folder that referenced the rig.
	 *
	 * Otherwise, the `<lookup>` value 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.
	 */
	projectFolder?: string;

	/**
	 * Set to true when invoking API Extractor's test harness.
	 *
	 * @remarks
	 * When `testMode` is true, the `toolVersion` field in the .api.json file is assigned an empty string
	 * to prevent spurious diffs in output files tracked for tests.
	 */
	testMode?: boolean;

	/**
	 * {@inheritDoc IConfigTsdocMetadata}
	 *
	 * @beta
	 */
	tsdocMetadata?: IConfigTsdocMetadata;
}