@microsoft/api-extractor/dist/index-internal.d.ts

Validate, document, and review the exported API for a TypeScript library

/**
 * API Extractor helps you build better TypeScript library packages.
 * It helps with validation, documentation, and reviewing of the exported API
 * for a TypeScript library.
 * 
 * @packagedocumentation
 */

import { JsonSchema } from '@microsoft/node-core-library';
import * as ts from 'typescript';

/**
 * Whether the function is public, private, or protected.
 * @alpha
 */
export declare type ApiAccessModifier = 'public' | 'private' | 'protected' | '';

/**
 * @alpha
 */
export declare type ApiItem = IApiProperty | ApiMember | IApiFunction | IApiConstructor | IApiClass | IApiEnum | IApiEnumMember | IApiInterface | IApiNamespace | IApiPackage;

/**
 * Support for loading the *.api.json file.
 *
 * @public
 */
export declare class ApiJsonFile {
    /**
     * The JSON Schema for API Extractor's *.api.json files (api-json.schema.json).
     */
    static jsonSchema: JsonSchema;
    /**
     * Loads an *.api.json data file, and validates that it conforms to the api-json.schema.json
     * schema.
     */
    static loadFromFile(apiJsonFilePath: string): IApiPackage;
}

/**
 * A member of a class.
 * @alpha
 */
export declare type ApiMember = IApiProperty | IApiMethod | IApiConstructor;

/**
 * ExternalApiHelper has the specific use case of generating an API json file from third-party definition files.
 * This class is invoked by the gulp-core-build-typescript gulpfile, where the external package names are
 * hard wired.
 * The job of this method is almost the same as the API Extractor task that is executed on first party packages,
 * with the exception that all packages analyzed here are external packages with definition files.
 *
 * @beta
 */
export declare class ExternalApiHelper {
    /**
     * @param rootDir - the absolute path containing a 'package.json' file and is also a parent of the
     * external package file. Ex: build.absolute_build_path.
     * @param libFolder - the path to the lib folder relative to the rootDir, this is where
     * 'external-api-json/external_package.api.json' file will be written. Ex: 'lib'.
     * @param externalPackageFilePath - the path to the '*.d.ts' file of the external package relative to the rootDir.
     * Ex: 'resources/external-api-json/es6-collection/index.t.ds'
     */
    static generateApiJson(rootDir: string, libFolder: string, externalPackageFilePath: string): void;
}

/**
 * Used to invoke the API Extractor tool.
 * @public
 */
export declare class Extractor {
    /**
     * The JSON Schema for API Extractor config file (api-extractor-config.schema.json).
     */
    static jsonSchema: JsonSchema;
    private static _defaultConfig;
    private static _declarationFileExtensionRegExp;
    private static _defaultLogger;
    private readonly _actualConfig;
    private readonly _program;
    private readonly _localBuild;
    private readonly _monitoredLogger;
    private readonly _absoluteRootFolder;
    /**
     * Given a list of absolute file paths, return a list containing only the declaration
     * files.  Duplicates are also eliminated.
     *
     * @remarks
     * The tsconfig.json settings specify the compiler's input (a set of *.ts source files,
     * plus some *.d.ts declaration files used for legacy typings).  However API Extractor
     * analyzes the compiler's output (a set of *.d.ts entry point files, plus any legacy
     * typings).  This requires API Extractor to generate a special file list when it invokes
     * the compiler.
     *
     * For configType=tsconfig this happens automatically, but for configType=runtime it is
     * the responsibility of the custom tooling.  The generateFilePathsForAnalysis() function
     * is provided to facilitate that.  Duplicates are removed so that entry points can be
     * appended without worrying whether they may already appear in the tsconfig.json file list.
     */
    static generateFilePathsForAnalysis(inputFilePaths: string[]): string[];
    private static _applyConfigDefaults(config);
    constructor(config: IExtractorConfig, options?: IExtractorOptions);
    /**
     * Returns the normalized configuration object after defaults have been applied.
     *
     * @remarks
     * This is a read-only object.  The caller should NOT modify any member of this object.
     * It is provided for diagnostic purposes.  For example, a build script could write
     * this object to a JSON file to report the final configuration options used by API Extractor.
     */
    readonly actualConfig: IExtractorConfig;
    /**
     * Invokes the API Extractor engine, using the configuration that was passed to the constructor.
     * @deprecated Use {@link Extractor.processProject} instead.
     */
    analyzeProject(options?: IAnalyzeProjectOptions): void;
    /**
     * Invokes the API Extractor engine, using the configuration that was passed to the constructor.
     * @param options - provides additional runtime state that is NOT part of the API Extractor
     *     config file.
     * @returns true for a successful build, or false if the tool chain should fail the build
     *
     * @remarks
     *
     * This function returns false to indicate that the build failed, i.e. the command-line tool
     * would return a nonzero exit code.  Normally the build fails if there are any errors or
     * warnings; however, if options.localBuild=true then warnings are ignored.
     */
    processProject(options?: IAnalyzeProjectOptions): boolean;
    private _generateRollupDtsFiles(context);
    private _generateRollupDtsFile(dtsRollupGenerator, mainDtsRollupFullPath, dtsKind);
    private _getShortFilePath(absolutePath);
    /**
     * Update the parsed command line to use paths from the specified TS compiler folder, if
     * a TS compiler folder is specified.
     */
    private _updateCommandLineForTypescriptPackage(commandLine, options);
}

/**
 * Configuration values used for the {@link IExtractorValidationRulesConfig} block.
 * @public
 */
export declare const enum ExtractorValidationRulePolicy {
    /**
     * Violations of the rule will be reported as build errors.
     */
    error = "error",
    /**
     * Violations of the rule are silently ignored.
     */
    allow = "allow",
}

/**
 * Options for {@link Extractor.processProject}.
 * @public
 */
export declare interface IAnalyzeProjectOptions {
    /**
     * If omitted, then the {@link IExtractorConfig.project} config will be used by default.
     */
    projectConfig?: IExtractorProjectConfig;
}

/**
 * DocItems are the typescript adaption of the json schemas
 * defined in API-json-schema.json. IDocElement is a component
 * for IDocItems because they represent formated rich text.
 *
 * This is the base class for other DocItem types.
 * @alpha
 */
export declare interface IApiBaseDefinition {
    /**
     * kind of item: 'class', 'enum', 'function', etc.
     */
    kind: string;
    isBeta: boolean;
    summary: MarkupBasicElement[];
    remarks: MarkupStructuredElement[];
    deprecatedMessage?: MarkupBasicElement[];
}

/**
 * IApiClass represetns an exported class.
 * @alpha
 */
export declare interface IApiClass extends IApiBaseDefinition {
    /**
     * {@inheritdoc IApiBaseDefinition.kind}
     */
    kind: 'class';
    /**
     * Can be a combination of methods and/or properties
     */
    members: IApiNameMap<ApiMember>;
    /**
     * Interfaces implemented by this class
     */
    implements?: string;
    /**
     * The base class for this class
     */
    extends?: string;
    /**
     * Generic type parameters for this class
     */
    typeParameters?: string[];
    /**
     * Indicates that the item was marked as "\@sealed" and must not be extended.
     */
    isSealed: boolean;
}

/**
 * A Typescript function.
 * @alpha
 */
export declare interface IApiConstructor extends IApiBaseDefinition {
    /**
     * {@inheritdoc IApiBaseDefinition.kind}
     */
    kind: 'constructor';
    /**
     * a text summary of the method definition
     */
    signature: string;
    /**
     * Indicates that the item was marked as "\@sealed" and must not be extended.
     */
    isSealed: boolean;
    /**
     * Indicates that the item was marked as "\@virtual" and may be extended.
     */
    isVirtual: boolean;
    /**
     * Indicates that the item was marked as "\@override" and is overriding a base definition.
     */
    isOverride: boolean;
    /**
     * parameters of the function
     */
    parameters: IApiNameMap<IApiParameter>;
}

/**
 * IApiEnum represents an exported enum.
 * @alpha
 */
export declare interface IApiEnum extends IApiBaseDefinition {
    /**
     * {@inheritdoc IApiBaseDefinition.kind}
     */
    kind: 'enum';
    values: IApiEnumMember[];
}

/**
 * A member of an IApiEnum.
 *
 * @alpha
 */
export declare interface IApiEnumMember extends IApiBaseDefinition {
    /**
     * {@inheritdoc IApiBaseDefinition.kind}
     */
    kind: 'enum value';
    value: string;
}

/**
 * A Typescript function.
 * @alpha
 */
export declare interface IApiFunction extends IApiBaseDefinition {
    /**
     * {@inheritdoc IApiBaseDefinition.kind}
     */
    kind: 'function';
    /**
     * a text summary of the method definition
     */
    signature: string;
    /**
     * parameters of the function
     */
    parameters: IApiNameMap<IApiParameter>;
    /**
     * a description of the return value
     */
    returnValue: IApiReturnValue;
}

/**
 * IApiInterface represents an exported interface.
 * @alpha
 */
export declare interface IApiInterface extends IApiBaseDefinition {
    /**
     * {@inheritdoc IApiBaseDefinition.kind}
     */
    kind: 'interface';
    /**
     * A mapping from the name of a member API to its ApiMember
     */
    members: IApiNameMap<ApiMember>;
    /**
     * Interfaces implemented by this interface
     */
    implements?: string;
    /**
     * The base interface for this interface
     */
    extends?: string;
    /**
     * Generic type parameters for this interface
     */
    typeParameters?: string[];
    /**
     * Indicates that the item was marked as "\@sealed" and must not be extended.
     */
    isSealed: boolean;
}

/**
 * Represents a reference to an ApiItem.
 * @alpha
 */
export declare interface IApiItemReference {
    /**
     * The name of the NPM scope, or an empty string if there is no scope.
     * @remarks
     * Example: `@microsoft`
     */
    scopeName: string;
    /**
     * The name of the NPM package that the API item belongs to, without the NPM scope.
     * @remarks
     * Example: `sample-package`
     */
    packageName: string;
    /**
     * The name of an exported API item, or an empty string.
     * @remarks
     * The name does not include any generic parameters or other punctuation.
     * Example: `SampleClass`
     */
    exportName: string;
    /**
     * The name of a member of the exported item, or an empty string.
     * @remarks
     * The name does not include any parameters or punctuation.
     * Example: `toString`
     */
    memberName: string;
}

/**
 * A member function of a typescript class or interface.
 * @alpha
 */
export declare interface IApiMethod extends IApiBaseDefinition {
    /**
     * {@inheritdoc IApiBaseDefinition.kind}
     */
    kind: 'method';
    /**
     * a text summary of the method definition
     */
    signature: string;
    /**
     * the access modifier of the method
     */
    accessModifier: ApiAccessModifier;
    /**
     * for an interface member, whether it is optional
     */
    isOptional: boolean;
    /**
     * for a class member, whether it is static
     */
    isStatic: boolean;
    /**
     * Indicates that the item was marked as "\@sealed" and must not be extended.
     */
    isSealed: boolean;
    /**
     * Indicates that the item was marked as "\@virtual" and may be extended.
     */
    isVirtual: boolean;
    /**
     * Indicates that the item was marked as "\@override" and is overriding a base definition.
     */
    isOverride: boolean;
    /**
     * a mapping of parameter name to IApiParameter
     */
    parameters: IApiNameMap<IApiParameter>;
    /**
     * describes the return value of the method
     */
    returnValue: IApiReturnValue;
}

/**
 * An ordered map of items, indexed by the symbol name.
 * @alpha
 */
export declare interface IApiNameMap<T> {
    /**
     * For a given name, returns the object with that name.
     */
    [name: string]: T;
}

/**
 * IApiInterface represents an exported interface.
 * @alpha
 */
export declare interface IApiNamespace extends IApiBaseDefinition {
    /**
     * {@inheritdoc IApiBaseDefinition.kind}
     */
    kind: 'namespace';
    /**
     * A mapping from the name of a member API to its ApiMember
     */
    exports: IApiNameMap<ApiItem>;
}

/**
 * IApiPackage is an object contaning the exported
 * definions of this API package. The exports can include:
 * classes, interfaces, enums, functions.
 * @alpha
 */
export declare interface IApiPackage {
    /**
    * {@inheritdoc IApiBaseDefinition.kind}
    */
    kind: 'package';
    /**
     * The name of the NPM package, including the optional scope.
     * @remarks
     * Example: `@microsoft/example-package`
     */
    name: string;
    /**
     * IDocItems of exported API items
     */
    exports: IApiNameMap<ApiItem>;
    /**
     * The following are needed so that this interface and can share
     * common properties with others that extend IApiBaseDefinition. The IApiPackage
     * does not extend the IApiBaseDefinition because a summary is not required for
     * a package.
     */
    isBeta: boolean;
    summary: MarkupBasicElement[];
    remarks: MarkupStructuredElement[];
    deprecatedMessage?: MarkupBasicElement[];
}

/**
 * Parameter Doc item.
 * @alpha
 */
export declare interface IApiParameter {
    /**
     * the parameter name
     */
    name: string;
    /**
     * describes the parameter
     */
    description: MarkupBasicElement[];
    /**
     * Whether the parameter is optional
     */
    isOptional: boolean;
    /**
     * Whether the parameter has the '...' spread suffix
     */
    isSpread: boolean;
    /**
     * The data type of the parameter
     */
    type: string;
}

/**
 * A property of a TypeScript class or interface
 * @alpha
 */
export declare interface IApiProperty extends IApiBaseDefinition {
    /**
     * {@inheritdoc IApiBaseDefinition.kind}
     */
    kind: 'property';
    /**
     * a text summary of the method definition
     */
    signature: string;
    /**
     * For an interface member, whether it is optional
     */
    isOptional: boolean;
    /**
     * Whether the property is read-only
     */
    isReadOnly: boolean;
    /**
     * For a class member, whether it is static
     */
    isStatic: boolean;
    /**
     * Whether the item was marked as "\@eventproperty", which indicates an event object that event
     * handlers can be attached to.
     */
    isEventProperty: boolean;
    /**
     * Indicates that the item was marked as "\@sealed" and must not be extended.
     */
    isSealed: boolean;
    /**
     * Indicates that the item was marked as "\@virtual" and may be extended.
     */
    isVirtual: boolean;
    /**
     * Indicates that the item was marked as "\@override" and is overriding a base definition.
     */
    isOverride: boolean;
    /**
     * The data type of this property
     */
    type: string;
}

/**
 * Return value of a method or function.
 * @alpha
 */
export declare interface IApiReturnValue {
    /**
     * The data type returned by the function
     */
    type: string;
    /**
     * Describes the return value
     */
    description: MarkupBasicElement[];
}

/**
 * Configures how the API JSON files (*.api.json) will be generated.
 *
 * @public
 */
export declare interface IExtractorApiJsonFileConfig {
    /**
     * Whether to generate API JSON files at all.  The default is true.
     */
    enabled: boolean;
    /**
     * Specifies where the *.api.json file should be written.
     *
     * The default value is "./dist"
     */
    outputFolder?: string;
}

/**
 * Configures how the API review files (*.api.ts) will be generated.
 *
 * @public
 */
export declare interface IExtractorApiReviewFileConfig {
    /**
     * Whether to generate review files at all.  The default is true.
     */
    enabled: boolean;
    /**
     * The file path of the folder containing API review file, relative to
     * the project folder.  This is part of an API review workflow:  During a build,
     * the API Extractor will output an API file, e.g. "my-project/temp/my-project.api.ts".
     * It will then compare this file against the last reviewed file,
     * e.g. "../api-review/my-project.api.ts" (assuming that apiReviewFolder is "../api-review").
     * If the files are different, the build will fail with an error message that instructs
     * the developer to update the approved file, and then commit it to Git.  When they
     * create a Pull Request, a branch policy will look for changes under "api-review/*"
     * and require signoff from the appropriate reviewers.
     *
     * The default value is "./etc".
     *
     * Example: "config" (for a standalone project)
     * Example: "../../common/api-review"  (for a Git repository with Rush)
     */
    apiReviewFolder?: string;
    /**
     * The *.api.ts report is saved into this folder.  During a production build
     * (i.e. when IExtractorRuntimeOptions.productionBuild=true) the temporary file will
     * be compared with the file in apiReviewFolder; if there are differences, and error
     * will be reported.  During a non-production build, the temporary file will be
     * automatically copied to the apiReviewFolder.
     *
     * The default value is "./temp".
     */
    tempFolder?: string;
}

/**
 * Configuration options for the API Extractor tool.  These options can be loaded
 * from a JSON config file.
 *
 * @public
 */
export declare interface IExtractorConfig {
    /**
     * Determines how the TypeScript compiler will be invoked.
     * The compiler.configType selects the type of configuration;
     * Different options are available according to the configuration type.
     */
    compiler: IExtractorTsconfigCompilerConfig | IExtractorRuntimeCompilerConfig;
    /**
     * {@inheritdoc IExtractorPoliciesConfig}
     */
    policies?: IExtractorPoliciesConfig;
    /**
     * {@inheritdoc IExtractorValidationRulesConfig}
     */
    validationRules?: IExtractorValidationRulesConfig;
    /**
     * {@inheritdoc IExtractorProjectConfig}
     */
    project: IExtractorProjectConfig;
    /**
     * {@inheritdoc IExtractorApiReviewFileConfig}
     */
    apiReviewFile?: IExtractorApiReviewFileConfig;
    /**
     * {@inheritdoc IExtractorApiJsonFileConfig}
     */
    apiJsonFile?: IExtractorApiJsonFileConfig;
    /**
     * {@inheritdoc IExtractorDtsRollupConfig}
     * @beta
     */
    dtsRollup?: IExtractorDtsRollupConfig;
}

/**
 * Configures how the *.d.ts rollup files will be generated.
 *
 * @remarks
 * API Extractor can generate a consolidated *.d.ts file that contains all
 * the exported typings for the package entry point.  It can also trim
 * \@alpha, \@beta, and \@internal definitions according to the release type.
 *
 * @beta
 */
export declare interface IExtractorDtsRollupConfig {
    /**
     * Whether to generate rollup *.d.ts files.  The default is false.
     */
    enabled: boolean;
    /**
     * If "trimming" is false (the default), then a single *.d.ts rollup file will be generated in the
     * "publishFolder".  If "trimming" is true, then three separate *.d.ts rollups will be
     * generated in "publishFolderForInternal", "publishFolderForBeta", and "publishFolderForPublic".
     *
     * @remarks
     * In either case, "mainDtsRollupPath" indicates the relative file path.
     */
    trimming?: boolean;
    /**
     * This setting is only used if "trimming" is false.
     * It indicates the folder where "npm publish" will be run.  The default value is "./dist".
     */
    publishFolder?: string;
    /**
     * This setting is only used if "trimming" is true.
     * It indicates the folder where "npm publish" will be run for an internal release.
     * The default value is "./dist/internal".
     *
     * @remarks
     * An internal release will contain all definitions that are reachable from the entry point.
     */
    publishFolderForInternal?: string;
    /**
     * This setting is only used if "trimming" is true.
     * It indicates the folder where "npm publish" will be run for a beta release.
     * The default value is "./dist/beta".
     *
     * @remarks
     * A beta release will contain all definitions that are reachable from the entry point,
     * except definitions marked as \@alpha or \@internal.
     */
    publishFolderForBeta?: string;
    /**
     * This setting is only used if "trimming" is true.
     * It indicates the folder where "npm publish" will be run for a public release.
     * The default value is "./dist/public".
     *
     * @remarks
     * A public release will contain all definitions that are reachable from the entry point,
     * except definitions marked as \@beta, \@alpha, or \@internal.
     */
    publishFolderForPublic?: string;
    /**
     * Specifies the relative path for the *.d.ts rollup file to be generated for the
     * package's main entry point.  The default value is an empty string, which causes
     * the path to be automatically inferred from the "typings" field of the project's
     * package.json file.
     *
     * @remarks
     * If specified, the value must be a relative path that can be combined with one of
     * the publish folder settings.
     */
    mainDtsRollupPath?: string;
}

/**
 * Runtime options for Extractor.
 *
 * @public
 */
export declare interface IExtractorOptions {
    /**
     * If IExtractorConfig.project.configType = 'runtime', then the TypeScript compiler state
     * must be provided via this option.
     */
    compilerProgram?: ts.Program;
    /**
     * Allows the caller to handle API Extractor errors; otherwise, they will be logged
     * to the console.
     */
    customLogger?: Partial<ILogger>;
    /**
     * Indicates that API Extractor is running as part of a local build, e.g. on developer's
     * machine. This disables certain validation that would normally be performed
     * for a ship/production build. For example, the *.api.ts review file is
     * automatically local in a debug build.
     *
     * The default value is false.
     */
    localBuild?: boolean;
    /**
     * By default API Extractor uses its own TypeScript compiler version to analyze your project.
     * This can often cause compiler errors due to incompatibilities between different TS versions.
     * Use this option to specify the folder path for your compiler version.
     *
     * @remarks
     * This option only applies when compiler.config.configType is set to "tsconfig"
     *
     * @beta
     */
    typescriptCompilerFolder?: string;
    /**
     * This option causes the typechecker to be invoked with the --skipLibCheck option. 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. If this option is used, it is strongly recommended that broken
     * dependencies be fixed or upgraded.
     *
     * @remarks
     * This option only applies when compiler.config.configType is set to "tsconfig"
     */
    skipLibCheck?: boolean;
}

/**
 * These policies determine how API Extractor validates various best practices for API design.
 *
 * @public
 */
export declare interface IExtractorPoliciesConfig {
    /**
     * Controls how API Extractor treats the TypeScript namespace keyword:
     *
     * conservative - (the default) namespaces may only be used to represent tables of constants
     *
     * permissive - arbitrary nesting of namespaces is allowed
     */
    namespaceSupport?: 'conservative' | 'permissive';
}

/**
 * Describes a specific project that will be analyzed.  In principle, multiple individual
 * projects can be processed while reusing a common compiler state.
 *
 * @public
 */
export declare interface IExtractorProjectConfig {
    /**
     * Specifies the TypeScript *.d.ts file that will be treated as the entry point
     * for compilation.  Typically this corresponds to the "typings" or "types" field
     * from package.json, but secondary entry points are also possible.
     *
     * @remarks
     * The file extension must not be *.ts.  API Extractor does NOT process TypeScript
     * source code, but instead the output of the compiler.  This is needed for compatibility
     * with preprocessors and also custom tooling that produces TypeScript-compatible outputs
     * without using the real compiler.  It also speeds up the analysis by avoiding the
     * need to parse implementation code.
     */
    entryPointSourceFile: string;
    /**
     * Indicates folders containing additional APJ JSON files (*.api.json) that will be
     * consulted during the analysis.  This is useful for providing annotations for
     * external packages that were not built using API Extractor.
     */
    externalJsonFileFolders?: string[];
}

/**
 * With this configuration, API Extractor is configured using an already prepared compiler state
 * that is provided programmatically at runtime.  This can potentially enable faster builds,
 * by reusing the same compiler invocation for tsc, tslint, and API Extractor.
 *
 * If configType='runtime' is specified, then IExtractorRuntimeOptions.compilerProgram must be
 * provided.
 *
 * @public
 */
export declare interface IExtractorRuntimeCompilerConfig {
    configType: 'runtime';
}

/**
 * With this configuration, API Extractor configures the compiler based on settings that
 * it finds in the project's tsconfig.json file.
 *
 * @public
 */
export declare interface IExtractorTsconfigCompilerConfig {
    configType: 'tsconfig';
    /**
     * The root folder for the project.
     * @remarks
     * This folder typically contains the tsconfig.json and package.json config files.
     */
    rootFolder: string;
    /**
     * Override the tsconfig.json file contents.
     *
     * @remarks
     * Provides already parsed tsconfig.json contents conforming to the TypeScript tsconfig schema:
     * http://json.schemastore.org/tsconfig
     *
     * If omitted, then by default the tsconfig.json file will be loaded from the root folder.
     */
    overrideTsconfig?: {};
}

/**
 * Configuration for various validation checks that ensure good API design
 *
 * @public
 */
export declare interface IExtractorValidationRulesConfig {
    /**
     * This rule checks for top-level API items that are missing a release tag such as \@beta or \@internal.
     * If "allow" is chosen, then missing release tags will be assumed to be \@public.
     * The default policy is "error".
     */
    missingReleaseTags?: ExtractorValidationRulePolicy;
}

/**
 * Provides a custom logging service to API Extractor.
 * @public
 */
export declare interface ILogger {
    /**
     * Log a message that will only be shown in a "verbose" logging mode.
     */
    logVerbose(message: string): void;
    /**
     * Log a normal message.
     */
    logInfo(message: string): void;
    /**
     * Log a warning message.  Typically it is shown in yellow and will break a production build.
     */
    logWarning(message: string): void;
    /**
     * Log an error message.  Typically it is shown in red and will break a production build.
     */
    logError(message: string): void;
}

/**
 * A hyperlink to an API item
 * @public
 */
export declare interface IMarkupApiLink {
    /** The kind of markup element */
    kind: 'api-link';
    /** The link text */
    elements: MarkupLinkTextElement[];
    /** The API item that will serve as the hyperlink target */
    target: IApiItemReference;
}

/**
 * A box containing source code with syntax highlighting
 * @remarks
 * NOTE: IMarkupHighlightedText is just a span of text, whereas IMarkupCodeBox is a box showing a larger code sample.
 * @public
 */
export declare interface IMarkupCodeBox {
    /** The kind of markup element */
    kind: 'code-box';
    /** {@inheritdoc IMarkupHighlightedText.text} */
    text: string;
    highlighter: MarkupHighlighter;
}

/**
 * Options for {@link Markup.createTextElements}
 *
 * @public
 */
export declare interface IMarkupCreateTextOptions {
    /**
     * Whether the text should be boldfaced.
     */
    bold?: boolean;
    /**
     * Whether the text should be italicized.
     */
    italics?: boolean;
}

/**
 * A top-level heading
 * @public
 */
export declare interface IMarkupHeading1 {
    /** The kind of markup element */
    kind: 'heading1';
    /**
     * The heading title
     * @remarks
     * Formatting such as bold/italics are not supported in headings.
     * If this text contains symbols such as HTML codes, they will be rendered literally.
     */
    text: string;
}

/**
 * A sub heading
 * @public
 */
export declare interface IMarkupHeading2 {
    /** The kind of markup element */
    kind: 'heading2';
    /** {@inheritdoc IMarkupHeading1.text} */
    text: string;
}

/**
 * Source code shown in a fixed-width font, with syntax highlighting.
 * @remarks
 * NOTE: IMarkupHighlightedText is just a span of text, whereas IMarkupCodeBox is a box showing a larger code sample.
 * @public
 */
export declare interface IMarkupHighlightedText {
    /** The kind of markup element */
    kind: 'code';
    /**
     * The text content to display.
     * @remarks
     * This content will be highlighted using the specified syntax highlighter.
     * If this text contains symbols such as HTML codes, they will be rendered literally.
     */
    text: string;
    /** Indicates the syntax highlighting that will be applied to this text */
    highlighter: MarkupHighlighter;
}

/**
 * Represents an HTML tag such as `<td>` or `</td>` or `<img src="example.gif" />`.
 *
 * @public
 */
export declare interface IMarkupHtmlTag {
    /** The kind of markup element */
    kind: 'html-tag';
    /**
     * A string containing the HTML tag.
     *
     * @remarks
     * To avoid parsing ambiguities with other AEDoc constructs, API Extractor will ensure that
     * this string is a complete and properly formatted opening or closing HTML tag such
     * as `<td>` or `</td>` or `<img src="example.gif" />`.  Beyond this, API Extractor does NOT
     * attempt to parse the tag attributes, or verify that opening/closing pairs are balanced,
     * or determine whether the nested tree is valid HTML.  That responsibility is left to the consuming
     * documentation engine.
     */
    token: string;
}

/**
 * A line break, similar to the "<br>" tag in HTML.
 * @public
 */
export declare interface IMarkupLineBreak {
    /** The kind of markup element */
    kind: 'break';
}

/**
 * A call-out box containing an informational note
 * @public
 */
export declare interface IMarkupNoteBox {
    /** The kind of markup element */
    kind: 'note-box';
    elements: MarkupBasicElement[];
}

/**
 * Represents an entire page.
 *
 * @public
 */
export declare interface IMarkupPage {
    /** The kind of markup element */
    kind: 'page';
    breadcrumb: MarkupBasicElement[];
    title: string;
    elements: MarkupStructuredElement[];
}

/**
 * A paragraph separator, similar to the "<p>" tag in HTML
 * @public
 */
export declare interface IMarkupParagraph {
    /** The kind of markup element */
    kind: 'paragraph';
}

/**
 * A table, with an optional header row
 * @public
 */
export declare interface IMarkupTable {
    /** The kind of markup element */
    kind: 'table';
    header?: IMarkupTableRow;
    rows: IMarkupTableRow[];
}

/**
 * A cell inside an IMarkupTableRow element.
 *
 * @public
 */
export declare interface IMarkupTableCell {
    /** The kind of markup element */
    kind: 'table-cell';
    /** The text content for the table cell */
    elements: MarkupBasicElement[];
}

/**
 * A row inside an IMarkupTable element.
 *
 * @public
 */
export declare interface IMarkupTableRow {
    /** The kind of markup element */
    kind: 'table-row';
    cells: IMarkupTableCell[];
}

/**
 * A block of plain text, possibly with simple formatting such as bold or italics.
 *
 * @public
 */
export declare interface IMarkupText {
    /** The kind of markup element */
    kind: 'text';
    /**
     * The plain text content to display.
     * @remarks
     * If this text contains symbols such as HTML codes, they will be rendered literally,
     * without any special formatting.
     */
    text: string;
    /**
     * Whether the text should be formatted using boldface
     */
    bold?: boolean;
    /**
     * Whether the text should be formatted using italics
     */
    italics?: boolean;
}

/**
 * A hyperlink to an internet URL
 * @public
 */
export declare interface IMarkupWebLink {
    /** The kind of markup element */
    kind: 'web-link';
    /** The link text */
    elements: MarkupLinkTextElement[];
    /** The internet URL that will serve as the hyperlink target */
    targetUrl: string;
}

/**
 * Provides various operations for working with MarkupElement objects.
 *
 * @public
 */
export declare class Markup {
    /**
     * A predefined constant for the IMarkupLineBreak element.
     */
    static BREAK: IMarkupLineBreak;
    /**
     * A predefined constant for the IMarkupParagraph element.
     */
    static PARAGRAPH: IMarkupParagraph;
    /**
     * Appends text content to the `output` array.  If the last item in the array is a
     * compatible IMarkupText element, the text will be merged into it.  Otherwise, a new
     * IMarkupText element will be created.
     */
    static appendTextElements(output: MarkupElement[], text: string, options?: IMarkupCreateTextOptions): void;
    /**
     * Constructs an IMarkupText element representing the specified text string, with
     * optional formatting.
     *
     * @remarks
     * NOTE: All whitespace (including newlines) will be collapsed to single spaces.
     * This behavior is similar to how HTML handles whitespace.  To preserve
     * newlines, use {@link Markup.createTextParagraphs} instead.
     */
    static createTextElements(text: string, options?: IMarkupCreateTextOptions): IMarkupText[];
    /**
     * This function is similar to {@link Markup.createTextElements}, except that multiple newlines
     * will be converted to a Markup.PARAGRAPH object.
     */
    static createTextParagraphs(text: string, options?: IMarkupCreateTextOptions): MarkupBasicElement[];
    /**
     * Constructs an IMarkupApiLink element that represents a hyperlink to the specified
     * API object.  The hyperlink is applied to an existing stream of markup elements.
     * @param textElements - the markup sequence that will serve as the link text
     * @param target - the API object that the hyperlink will point to
     */
    static createApiLink(textElements: MarkupLinkTextElement[], target: IApiItemReference): IMarkupApiLink;
    /**
     * Constructs an IMarkupApiLink element that represents a hyperlink to the specified
     * API object.  The hyperlink is applied to a plain text string.
     * @param text - the text string that will serve as the link text
     * @param target - the API object that the hyperlink will point to
     */
    static createApiLinkFromText(text: string, target: IApiItemReference): IMarkupApiLink;
    /**
     * Constructs an IMarkupWebLink element that represents a hyperlink an internet URL.
     * @param textElements - the markup sequence that will serve as the link text
     * @param targetUrl - the URL that the hyperlink will point to
     */
    static createWebLink(textElements: MarkupLinkTextElement[], targetUrl: string): IMarkupWebLink;
    /**
     * Constructs an IMarkupWebLink element that represents a hyperlink an internet URL.
     * @param text - the plain text string that will serve as the link text
     * @param targetUrl - the URL that the hyperlink will point to
     */
    static createWebLinkFromText(text: string, targetUrl: string): IMarkupWebLink;
    /**
     * Constructs an IMarkupHighlightedText element representing a program code text
     * with optional syntax highlighting
     */
    static createCode(code: string, highlighter?: MarkupHighlighter): IMarkupHighlightedText;
    /**
     * Constructs an IMarkupHtmlTag element representing an opening or closing HTML tag.
     */
    static createHtmlTag(token: string): IMarkupHtmlTag;
    /**
     * Constructs an IMarkupHeading1 element with the specified title text
     */
    static createHeading1(text: string): IMarkupHeading1;
    /**
     * Constructs an IMarkupHeading2 element with the specified title text
     */
    static createHeading2(text: string): IMarkupHeading2;
    /**
     * Constructs an IMarkupCodeBox element representing a program code text
     * with the specified syntax highlighting
     */
    static createCodeBox(code: string, highlighter: MarkupHighlighter): IMarkupCodeBox;
    /**
     * Constructs an IMarkupNoteBox element that will display the specified markup content
     */
    static createNoteBox(textElements: MarkupBasicElement[]): IMarkupNoteBox;
    /**
     * Constructs an IMarkupNoteBox element that will display the specified plain text string
     */
    static createNoteBoxFromText(text: string): IMarkupNoteBox;
    /**
     * Constructs an IMarkupTableRow element containing the specified cells, which each contain a
     * sequence of MarkupBasicElement content
     */
    static createTableRow(cellValues?: MarkupBasicElement[][] | undefined): IMarkupTableRow;
    /**
     * Constructs an IMarkupTable element containing the specified header cells, which each contain a
     * sequence of MarkupBasicElement content.
     * @remarks
     * The table initially has zero rows.
     */
    static createTable(headerCellValues?: MarkupBasicElement[][] | undefined): IMarkupTable;
    /**
     * Constructs an IMarkupTable element with the specified title.
     */
    static createPage(title: string): IMarkupPage;
    /**
     * Extracts plain text from the provided markup elements, discarding any formatting.
     *
     * @remarks
     * The returned string is suitable for counting words or extracting search keywords.
     * Its formatting is not guaranteed, and may change in future updates of this API.
     *
     * API Extractor determines whether an API is "undocumented" by using extractTextContent()
     * to extract the text from its summary, and then counting the number of words.
     */
    static extractTextContent(elements: MarkupElement[]): string;
    /**
     * Use this to clean up a MarkupElement sequence, assuming the sequence is now in
     * its final form.
     *
     * @remarks
     * The following operations are performed:
     *
     * 1. Remove leading/trailing white space around paragraphs
     *
     * 2. Remove redundant paragraph elements
     */
    static normalize<T extends MarkupElement>(elements: T[]): void;
    /**
     * This formats an IApiItemReference as its AEDoc notation.
     *
     * @remarks
     * Depending on the provided components, example return values might look like
     * "\@ms/my-library:SomeClass.someProperty", "my-library:SomeClass", "SomeClass",
     * or "SomeClass.someProperty".
     */
    static formatApiItemReference(apiItemReference: IApiItemReference): string;
    private static _extractTextContent(elements, buffer);
    private static _trimRawText(text);
}

/**
 * Represents basic text consisting of paragraphs and links (without structures such as headers or tables).
 *
 * @public
 */
export declare type MarkupBasicElement = MarkupLinkTextElement | IMarkupApiLink | IMarkupWebLink | IMarkupParagraph | IMarkupLineBreak;

/**
 * The super set of all markup interfaces, used e.g. for functions that recursively traverse
 * the tree.
 *
 * @public
 */
export declare type MarkupElement = MarkupStructuredElement | IMarkupTableCell | IMarkupTableRow | IMarkupPage;

/**
 * Indicates the the text should be colorized according to the specified language syntax.
 * If "plain" is specified, then no highlighting should be performed.
 *
 * @public
 */
export declare type MarkupHighlighter = 'javascript' | 'plain';

/**
 * Represents markup that can be used as the link text for a hyperlink
 *
 * @public
 */
export declare type MarkupLinkTextElement = IMarkupText | IMarkupHighlightedText | IMarkupHtmlTag;

/**
 * Represents structured text that contains headings, tables, and boxes.  These are the top-level
 * elements of a IMarkupPage.
 *
 * @public
 */
export declare type MarkupStructuredElement = MarkupBasicElement | IMarkupHeading1 | IMarkupHeading2 | IMarkupCodeBox | IMarkupNoteBox | IMarkupTable;