/**
 * An engine for generating TypeScript .d.ts files that provide type signatures
 * for non-TypeScript modules such as generated JavaScript or CSS. It can operate
 * in either a single-run mode or a watch mode.
 *
 * @packageDocumentation
 */

import { ITerminal } from '@rushstack/terminal';

/**
 * Associates a position in a generated `.d.ts` file with the position in the source file that
 * produced it.
 *
 * @public
 */
export declare interface IDeclarationMapping {
    /**
     * The zero-based line in the generated typings, before the generated file header is prepended.
     */
    generatedLine: number;
    /**
     * The zero-based column in the generated typings.
     */
    generatedColumn: number;
    /**
     * The zero-based position in the source file that produced this declaration.
     */
    sourcePosition: ISourcePosition;
}

/**
 * @public
 */
export declare interface IExportAsDefaultOptions {
    /**
     * This setting overrides the the interface name for the default wrapped export.
     *
     * @defaultValue "IExport"
     */
    interfaceName?: string;
    /**
     * @deprecated - Use {@link IExportAsDefaultOptions.interfaceDocumentationComment} instead.
     */
    documentationComment?: string;
    /**
     * This value is placed in a documentation comment for the
     * exported default interface.
     */
    interfaceDocumentationComment?: string;
    /**
     * This value is placed in a documentation comment for the
     * exported const value.
     */
    valueDocumentationComment?: string;
}

/**
 * Typings content produced by a parser, along with the information needed to emit a declaration
 * source map for it.
 *
 * @public
 */
export declare interface IGeneratedTypings {
    /**
     * The generated typings content, excluding the generated file header.
     */
    typingsData: string;
    /**
     * Positions associating declarations in {@link IGeneratedTypings.typingsData} with the source
     * file that produced them. When omitted or empty, no declaration map is emitted.
     */
    declarationMappings?: readonly IDeclarationMapping[];
}

/**
 * A zero-based position within a source file.
 *
 * @public
 */
export declare interface ISourcePosition {
    line: number;
    column: number;
}

/**
 * @public
 */
export declare interface IStringValuesTypingsGeneratorBaseOptions {
    /**
     * Setting this option wraps the typings export in a default property.
     */
    exportAsDefault?: boolean | IExportAsDefaultOptions;
    /**
     * @deprecated Use {@link IStringValuesTypingsGeneratorBaseOptions.exportAsDefault}'s
     * {@link IExportAsDefaultOptions.interfaceName} instead.
     */
    exportAsDefaultInterfaceName?: string;
}

/**
 * @public
 */
export declare interface IStringValuesTypingsGeneratorOptions<TFileContents extends string = string> extends ITypingsGeneratorOptions<IStringValueTypings | undefined, TFileContents>, IStringValuesTypingsGeneratorBaseOptions {
}

/**
 * @public
 */
export declare interface IStringValuesTypingsGeneratorOptionsWithCustomReadFile<TFileContents = string> extends ITypingsGeneratorOptionsWithCustomReadFile<IStringValueTypings | undefined, TFileContents>, IStringValuesTypingsGeneratorBaseOptions {
}

/**
 * @public
 */
export declare interface IStringValueTyping {
    exportName: string;
    comment?: string;
    /**
     * The zero-based position of this string's declaration in the source file. When provided and
     * declaration maps are enabled, "go to definition" resolves to this position.
     */
    sourcePosition?: ISourcePosition;
}

/**
 * @public
 */
export declare interface IStringValueTypings {
    typings: IStringValueTyping[];
    /**
     * Options for default exports. Note that options provided here will override
     * options provided in {@link IStringValuesTypingsGeneratorBaseOptions.exportAsDefault}.
     */
    exportAsDefault?: boolean | IExportAsDefaultOptions;
}

/**
 * @public
 */
export declare interface ITypingsGeneratorBaseOptions {
    srcFolder: string;
    generatedTsFolder: string;
    secondaryGeneratedTsFolders?: string[];
    globsToIgnore?: string[];
    terminal?: ITerminal;
    /**
     * If true, a `.d.ts.map` file is emitted next to each generated `.d.ts` file whose parser
     * provided declaration positions. This allows editors to resolve "go to definition" to the
     * original source file instead of the generated typings.
     *
     * @defaultValue false
     */
    generateDeclarationMaps?: boolean;
}

/**
 * @public
 */
export declare interface ITypingsGeneratorOptions<TTypingsResult = string | undefined, TFileContents extends string = string> extends ITypingsGeneratorOptionsWithoutReadFile<TTypingsResult, TFileContents> {
    readFile?: ReadFile<TFileContents>;
}

/**
 * Options for a TypingsGenerator that needs to customize how files are read.
 *
 * @public
 */
export declare interface ITypingsGeneratorOptionsWithCustomReadFile<TTypingsResult = string | undefined, TFileContents = string> extends ITypingsGeneratorOptionsWithoutReadFile<TTypingsResult, TFileContents> {
    readFile: ReadFile<TFileContents>;
}

/**
 * @public
 */
export declare interface ITypingsGeneratorOptionsWithoutReadFile<TTypingsResult = string | undefined, TFileContents = string> extends ITypingsGeneratorBaseOptions {
    fileExtensions: string[];
    parseAndGenerateTypings: (fileContents: TFileContents, filePath: string, relativePath: string) => TTypingsResult | Promise<TTypingsResult>;
    getAdditionalOutputFiles?: (relativePath: string) => string[];
}

/**
 * @public
 */
export declare type ReadFile<TFileContents = string> = (filePath: string, relativePath: string) => Promise<TFileContents> | TFileContents;

/**
 * Serializes a declaration source map that points a generated `.d.ts` back at the file that
 * produced it. TypeScript's language service follows these maps when resolving "go to definition",
 * so an editor navigates to the original source rather than the generated typings.
 *
 * @param mappings - The positions to map. Generated lines are relative to the typings content
 *   produced by the parser, before `generatedLineOffset` is applied.
 * @param generatedFileName - The file name of the generated typings, used as the map's `file`.
 * @param sourcePath - The path of the source file, relative to the folder containing the map.
 * @param generatedLineOffset - The number of header lines prepended to the generated typings.
 *
 * @public
 */
export declare function serializeDeclarationMap(mappings: readonly IDeclarationMapping[], generatedFileName: string, sourcePath: string, generatedLineOffset: number): string;

/**
 * This is a simple tool that generates .d.ts files for non-TS files that can be represented as
 * a simple set of named string exports.
 *
 * @public
 */
export declare class StringValuesTypingsGenerator<TFileContents = string> extends TypingsGenerator<TFileContents> {
    constructor(options: TFileContents extends string ? IStringValuesTypingsGeneratorOptions<TFileContents> : never);
    constructor(options: IStringValuesTypingsGeneratorOptionsWithCustomReadFile<TFileContents>);
}

/**
 * This is a simple tool that generates .d.ts files for non-TS files.
 *
 * @public
 */
export declare class TypingsGenerator<TFileContents = string> {
    private readonly _dependenciesOfFile;
    private readonly _consumersOfFile;
    private readonly _relativePaths;
    protected readonly _options: ITypingsGeneratorOptionsWithCustomReadFile<string | IGeneratedTypings | undefined, TFileContents>;
    protected readonly terminal: ITerminal;
    /**
     * The folder path that contains all input source files.
     */
    readonly sourceFolderPath: string;
    /**
     * The glob pattern used to find input files to process.
     */
    readonly inputFileGlob: string;
    /**
     * The glob patterns that should be ignored when finding input files to process.
     */
    readonly ignoredFileGlobs: readonly string[];
    constructor(options: TFileContents extends string ? ITypingsGeneratorOptions<string | IGeneratedTypings | undefined, TFileContents> : never);
    constructor(options: ITypingsGeneratorOptionsWithCustomReadFile<string | IGeneratedTypings | undefined, TFileContents>);
    /**
     * Generate typings for the provided input files.
     *
     * @param relativeFilePaths - The input files to process, relative to the source folder. If not provided,
     * all input files will be processed.
     */
    generateTypingsAsync(relativeFilePaths?: string[]): Promise<void>;
    runWatcherAsync(): Promise<void>;
    /**
     * Register file dependencies that may effect the typings of a consumer file.
     * Note: This feature is only useful in watch mode.
     * The registerDependency method must be called in the body of parseAndGenerateTypings every
     * time because the registry for a file is cleared at the beginning of processing.
     */
    registerDependency(consumer: string, rawDependency: string): void;
    getOutputFilePaths(relativePath: string): string[];
    private _getOutputFilePathsWithoutCheck;
    private _reprocessFilesAsync;
    private _parseFileAndGenerateTypingsAsync;
    /**
     * Removes the consumer from all extant dependencies
     */
    private _clearDependencies;
    private _getTypingsFilePaths;
    private _normalizeFileExtensions;
}

export { }