/**
   * @luddites-me/ts-tools
   *
   * @remarks
   * TypeScript project that provides build tooling for other TypeScript projects
   *
   * @packageDocumentation
   */

import { ILogObject } from 'tslog';
import { ISettingsParam } from 'tslog';
import { Logger } from 'tslog';

/**
 * Standard function signature for an assertion
 * @public
 */
export declare type Assertion = (data?: any) => Promise<any>;

/**
 * An array of strings representing the content section (no header) of a markdown section.
 * @public
 */
export declare interface Block {
    header?: string;
    content?: string;
}

/**
 * Iterates over all the markdown files in the project to build a tree of links to each document
 * @param params - {@link DocLinksParams} a doc links section header, an introductory paragraph, and a path to the repository.
 * @public
 * @returns a {@link ReadmeBlock} of relative links to the documents in the standardized documentation path
 */
export declare function buildDocumentationLinksBlock({ header, introduction, }: DocLinksParams): ReadmeBlock;

/**
 * Constructs a tslog LoggerOptions object based on the provided options
 * @public
 * @param options - log options
 * @returns ISettingsParam
 */
export declare const buildLoggerConfig: (options?: LogOptions | undefined) => ISettingsParam;

/**
 * The default configuration if none is provided.
 * @defaultValue {@link LogLevel.ERROR} and {@link TransportType.FILE}
 * @public
 */
export declare const DefaultLogOptions: ISettingsParam;

/**
 * Render method for log messages
 * @public
 */
export declare enum DisplayType {
    json = "json",
    pretty = "pretty"
}

/**
 * @public
 */
export declare interface DocLinksParams {
    /**
     * A string representing the header line for the link block to standard documentation files.
     */
    header: string;
    /**
     * An string representing an introduction to the standard documentation links block.
     */
    introduction?: string;
    /**
     * path to the repo root for calculation of a relative path to the standard documentation directory.
     */
    repoRoot: string | null;
}

/**
 * Structure representing env configuration
 * @public
 */
export declare interface EnvConfig {
    encoding?: string;
    silent?: boolean;
    path?: string;
    defaults?: string;
    schema?: string;
    errorOnMissing?: boolean;
    errorOnExtra?: boolean;
    errorOnRegex?: boolean;
    includeProcessEnv?: boolean;
    assignToProcessEnv?: boolean;
    overrideProcessEnv?: boolean;
}

/**
 * Defaults for env config
 * @public
 */
export declare const EnvConfigDefaults: EnvConfig;

/**
 * Represents an environment variable doc block in package.json
 * @public
 */
export declare interface EnvDoc {
    /**
     * environment variable doc description property.
     */
    description: string;
    /**
     * variable's default value
     */
    defaultValue: string;
}

/**
 * Collection of named {@link EnvDoc} docs
 * @public
 */
export declare interface EnvDocs {
    /**
     * A string to {@link EnvDoc}-block mapping.
     */
    [index: string]: EnvDoc;
}

/**
 * Definition of Environment Variables available in this project
 * @public
 */
export declare enum EnvVariables {
    DOCS_CREATE_README_INDEX = "DOCS_CREATE_README_INDEX",
    DOCS_CREATE_TOC = "DOCS_CREATE_TOC",
    IGNORE_JSON_FILES = "IGNORE_JSON_FILES",
    IGNORE_MARKDOWN_FILES = "IGNORE_MARKDOWN_FILES",
    IGNORE_PEER_DEPENDENCIES = "IGNORE_PEER_DEPENDENCIES",
    NODE_ENV = "NODE_ENV",
    SYNC_PEER_DEPENDENCIES = "SYNC_PEER_DEPENDENCIES"
}

/**
 * Type signature for error method
 * @public
 */
export declare type errorMethod = (message: string, error: Error, ...args: any[]) => void;

/**
 * For each documented environment variable in package.json, create documentation in README
 * @param docs - a {@link EnvDocs} object containing documentation objects describing environment variables.
 * @public
 * @returns a {@link ReadmeBlock} whose content is a formatted {@link EnvDocs}.
 */
export declare const formatEnvDocs: (docs: EnvDocs) => ReadmeBlock;

/**
 * For each documented script in package.json, create documentation in README
 * @param docs - a {@link ScriptDocs} object containing documentation objects describing
 * package.json scripts.
 * @public
 * @returns a {@link ReadmeBlock} whose content is a formatted {@link ScriptDocs}.
 */
export declare const formatScriptDocs: (docs: ScriptDocs) => ReadmeBlock;

/**
 * Uses \@microsoft/api-extractor to produce API documentation for this project
 * @remarks API Documentation generator
 *
 * @public
 */
export declare const generateApi: (configPath?: string | undefined) => void;

/**
 * Generates API docs for every documented class/method/interface/enum.
 * @param params - Optional list of command line params
 * @public
 * @returns async void
 */
export declare const generateApiDocs: (params?: string | undefined) => Promise<void>;

/**
 * Fetches an instance of a logger.
 * @remarks The returned logger will always be a new instance, with the same configuration.
 * @public
 * @param name - Script/project/method running this logger
 */
export declare const getCliLogger: (name?: string | undefined) => LogInterface;

/**
 * Fetches a list of files, filtered by an ignore list
 * @param envIgnoreFiles - environment variable to use for lists of ignored files
 * @param exclude - manual overrides to the ignore files list
 * @internal
 */
export declare const getIgnoredFiles: (envIgnoreFiles: EnvVariables, exclude?: string) => string[];

/**
 * Fetches a static instance of a logger.
 * @remarks The returned logger will always be the same instance, with the same configuration.
 * @public
 * @param logOptions - optional configuration options for the logger
 * @param reset - reset the static instance with a new configuration
 */
export declare const getLogger: (logOptions?: LogOptions | undefined, reset?: boolean) => LogInterface;

/**
 * Options for glob input
 * @public
 */
export declare const GLOB_OPTIONS: GlobOptions;

/**
 * Callback representation for glob callback
 * @public
 */
export declare type globCallback = (err: Error | null, matches: string[]) => void;

/**
 * Structure reprsenting glob options
 * @public
 */
export declare interface GlobOptions {
    dot?: boolean;
    ignore?: string[];
    realPath?: boolean;
}

/**
 * Defines known headers that we will parse
 * @remarks
 * `STRING` is for inserting new sections. `FIELD` is regex for matching sections.
 * @public
 */
export declare const HEADERS: {
    FIRST: {
        RE: RegExp;
    };
    TOC: {
        STRING: string;
        RE: RegExp;
    };
    LICENSE: {
        STRING: string;
        RE: RegExp;
    };
    GETTING_STARTED: {
        STRING: string;
        RE: RegExp;
    };
    SCRIPTS: {
        STRING: string;
        RE: RegExp;
    };
    ENV: {
        STRING: string;
        RE: RegExp;
    };
};
export { ILogObject }

/**
 * @public
 */
export declare type IndexedBlocks = Map<string, ReadmeBlock[]>;

/**
 * Type signature for info method
 * @public
 */
export declare type infoMethod = (message: string, ...args: any[]) => void;
export { ISettingsParam }

/**
 * Returns true if the fileName is in the ignore pattern
 * @param envIgnoreFiles - environment variable to use for ignoring files
 * @param fileName - name of path to ignore
 * @param exclude - optional string value of path(s) to exclude from the ignore equation
 * @public
 */
export declare const isIgnored: (envIgnoreFiles: EnvVariables, fileName: string, exclude?: string) => boolean;

/**
 * Determines if the util is being run as a script
 * @public
 * @param fileName - The file we are checking as the initial file callig the logic
 * @returns a boolean with true if the process is being ran as a script, otherwise false
 */
export declare const isRunAsScript: (fileName: string) => boolean;

/**
 * This will load the `.env` file onto the current process.
 *
 * @remarks
 * Missing properties will be loaded from `.env.defaults` if possible.
 * If no defaults exist and the properties are defined in `.env.schema`,
 * but are missing from `.env`, an error will be thrown with the missing
 * property name.
 * @public
 */
export declare const loadEnv: (config?: EnvConfig) => any;

/**
 * {@inheritDoc LogInterface}
 * @public
 */
export declare class Log implements LogInterface {
    logger: Logger;
    /**
     * @param logOptions - optional configuration options for the logger
     */
    constructor(logOptions?: LogOptions);
    /**
     * {@inheritDoc LogInterface.log}
     */
    log: (level: LogLevel, message: string, ...args: any[]) => void;
    /**
     * {@inheritDoc LogInterface.info}
     */
    debug: (message: string, ...args: any[]) => void;
    /**
     * {@inheritDoc LogInterface.info}
     */
    info: (message: string, ...args: any[]) => void;
    /**
     * {@inheritDoc LogInterface.info}
     */
    warn: (message: string, ...args: any[]) => void;
    /**
     * {@inheritDoc LogInterface.error}
     */
    error: (message: string, error: Error, ...args: any[]) => void;
    /**
     * {@inheritDoc LogInterface.error}
     */
    fatal: (message: string, error: Error, ...args: any[]) => void;
}
export { Logger }

/**
 * Definition of logging implementation requirements
 * @public
 */
export declare interface LogInterface {
    /**
     * Allows logging at any desired log level
     * @param level - the log level to use (DEBUG, INFO, WARN, ERROR)
     * @param message - a brief description of the issue
     * @param args - any number of additional string messages, which will be joined together or a JSON object
     * @returns void
     */
    log: logMethod;
    /**
     * Generates an INFO log
     * @param message - a brief description of the issue
     * @param args - any number of additional string messages, which will be joined together or a JSON object
     * @returns void
     */
    debug: infoMethod;
    /**
     * Generates an INFO log
     * @param message - a brief description of the issue
     * @param args - any number of additional string messages, which will be joined together or a JSON object
     * @returns void
     */
    info: infoMethod;
    /**
     * Generates an WARN log
     * @param message - a brief description of the issue
     * @param args - any number of additional string messages, which will be joined together or a JSON object
     * @returns void
     */
    warn: infoMethod;
    /**
     * Generates an ERROR log
     * @param message - a brief description of the issue
     * @param args - any number of additional string messages, which will be joined together or a JSON object
     * @returns void
     */
    error: errorMethod;
    /**
     * Generates an FATAL log
     * @param message - a brief description of the issue
     * @param args - any number of additional string messages, which will be joined together or a JSON object
     * @returns void
     */
    fatal: errorMethod;
}

/**
 * The valid log levels
 * @remarks These log levels conform to standard log level definitions
 * @public
 */
export declare enum LogLevel {
    SILLY = "silly",
    TRACE = "trace",
    DEBUG = "debug",
    INFO = "info",
    WARN = "warn",
    ERROR = "error",
    FATAL = "fatal"
}

/**
 * Type signature for log method
 * @public
 */
export declare type logMethod = (level: LogLevel, message: string, ...args: any[]) => void;

/**
 * Configuration options for instantiating the Log
 * @public
 */
export declare interface LogOptions {
    /**
     * The service name to use for log metadata and file names
     */
    serviceName: string;
    /**
     * The minimum log level to capture
     */
    logLevel: LogLevel;
    /**
     * An optional collection of all required output targets
     */
    transports?: Transports[];
    /**
     * An optional type for rendering. Choices are `pretty` and `json`. Default is `json`.
     */
    type?: DisplayType;
}

/**
 * Reads the package.json and README.md files, and generates a standardized {@link Readme}, exports it and writes to disk.
 * @public
 */
export declare function main(): Promise<void>;

/**
 * Runs format against a directory
 * @public
 */
export declare const prettify: (path?: string, options?: GlobOptions, callback?: globCallback) => void;

/**
 * Formats markdown content according to the prettier config
 * @public
 */
export declare const prettyMarkdown: (input: string) => string;

/**
 * Used to match against a content header.
 * @public
 */
export declare type Query = string | RegExp;

/**
 * The Readme class represents a markdown README and provides an API for programmatic transformations of it.
 * @public
 */
export declare class Readme {
    STANDARD_DOCS_PATH: string;
    /**
     * @param line - string representing a single line from a readme content.
     *
     * @returns a boolean indicating whether the readme line is a header
     */
    static isHeader: (line: string) => boolean;
    /**
     * @param line - string representing a single line from a readme content.
     *
     * @returns a boolean indicating whether the readme line is a code start tag.
     */
    static isCodeStartTag: (line: string) => boolean;
    /**
     * @param line - string representing a single line from a readme content.
     *
     * @returns a boolean indicating whether the readme line is a code end tag.
     */
    static isCodeEndTag: (line: string) => boolean;
    /**
     * @param block - a {@link Block} object representing a content block in a parsed readme file.
     *
     * @returns a boolean indicating whether the readme line is a code end tag.
     */
    static isRootNode: (block: Block) => boolean;
    /**
     * @param line - string representing a single line from a readme content.
     *
     * @returns a github-sanitized string to be used as an anchor tag linking to another section of the same readme document.
     */
    static sanitize: (line: string) => string;
    /**
     * @param s - a string to be repeated
     * @param count - the number of times a string should be repeated.
     *
     * @returns a string comprised of `s`, repeated `count` times.
     */
    static repeat: (s: string, count: number) => string;
    /**
     * @param header - a string representing a readme content section header.
     * @param query - a {@link Query} object
     * @param strict - a boolean flag to enable strict string matching.
     *
     * @returns - a boolean indicating whether a specific header was found in the readme content.
     */
    static headerFound(header: string, query: Query, strict?: boolean): boolean;
    /**
     * @param textParts - a list of strings that are used to build a table of contents entry that links to a content section
     *
     * @returns a string representing a markdown anchor tag to a link in the same document.
     */
    static makeLink: (...textParts: string[]) => string;
    /**
     * Generates a content block with an unlicense license.
     * @param heading - type of heading to use for the license block.
     * @returns a {@link ReadmeBlock}
     */
    static getLicenseBlock(header?: string): ReadmeBlock;
    /**
     * @param content - a string representing an unparsed section
     * @returns a parsed readme section as a {@link ReadmeBlock}
     */
    static parseBlockFromContent(content: string): ReadmeBlock;
    /**
     * readme content
     */
    content: string;
    /**
     * A list of {@link ReadmeBlock}.
     */
    blocks: ReadmeBlock[];
    /**
     * A map of {@link IndexedBlocks} blocks.
     */
    indexedBlocks: IndexedBlocks;
    /**
     * @param content - readme content as a string.
     */
    constructor(content?: string);
    /**
     * @param content - readme content as string, to be parsed into {@link ReadmeBlock}s.
     * Parses the readme content and returns a Readme instance for chaining.
     * @public
     * @returns a {@link Readme} instance.
     */
    static parse(content?: string): ReadmeBlock[];
    /**
     * Indexes {@link Block}s by header to support efficient querying.
     * @public
     */
    index(): void;
    /**
     * Generates a table of contents for a specified subset of sections, to avoid
     * including the readme top level sections, and to provide greater user control.
     * @public
     * @param startAt - the index of blocks to start parsing for the table of contents
     * @param indent - a string used to pad indentations for the list indentations.
     *
     * @returns a table of contents in string form.
     */
    getTocBlock(startAt?: number, indent?: string): ReadmeBlock | undefined;
    /**
     * Convert the internal readme representation back to a string.
     *
     * @returns a string representing the entire readme after any transformations.
     */
    export(): string;
    /** Implements toString method so that the readme is coerced properly
     * when stringified.
     *
     * @returns a string representing the entire readme, post any transformations.
     */
    toString(): string;
    /**
     * Get a content parsed block by index.
     *
     * @param index - index of block in list of parsed content blocks.
     *
     * @returns a {@link Block} at the supplied index.  If the index is out of range, it throws an error.
     */
    getSectionAt(index: number): ReadmeBlock;
    /**
     * Find a single content (non-code) block by header.
     *
     * @param content - a {@link Block} object to insert before a matched content header.
     * @param strict - whether to perform a strict string match or not against a content header.
     *
     * @returns a single {@link Block } object if a section is matched, or null.
     */
    getSection(target: Query, strict?: boolean): ReadmeBlock | null;
    /**
     * Find content blocks by header.
     *
     * @param content - a {@link Block} object to insert before a matched content header.
     * @param strict - whether to perform a strict string match or not against a content header.
     *
     * @returns a list of matched content {@link Block}s.
     */
    getSections(target: Query, strict?: boolean): ReadmeBlock[];
    /**
     * Parses content and adds it as a block to the end of the readme.
     * @param content - a string representing an unparsed readme section
     */
    appendContent(content: string): void;
    /**
     * Parses content and adds it as a block to the beginning of the readme.
     * @param content - a string representing an unparsed readme section
     */
    prependContent(content: string): void;
    /**
     * Appends content at end of the readme content list.
     *
     * @param block - a {@link Block} object to insert before a matched content header.
     * @param target - optional target block to append the new block after.
     */
    appendBlock(block: ReadmeBlock, target?: ReadmeBlock | null): void;
    /**
     * Prepends content to the beginning of the readme content list.
     *
     * @param block - a {@link Block} object to insert before a matched content header.
     * @param target - optional target block to prepend the new block before.
     */
    prependBlock(block: ReadmeBlock, target?: ReadmeBlock | null): void;
    /**
     * Inserts the content after a matching content block.
     *
     * @param target - a {@link Query} object to match a content section.
     * @param content - a {@link Block} object to insert after a matched content header.
     * @param strict - boolean indicating whether to perform a strict match or not against a content header.
     */
    insertAfter(target: Query, newBlock: ReadmeBlock, strict?: boolean): void;
    /**
     * Inserts the content after a matching content block.
     *
     * @param target - a {@link Query} object to match a content section.
     * @param content - a {@link Block} object to insert before a matched content header.
     * @param strict - whether to perform a strict string match or not against a content header.
     */
    insertBefore(target: Query, newBlock: ReadmeBlock, strict?: boolean): void;
    /**
     * Set the first found section (targeted by string/regex) to the supplied content
     *
     * @param target - a {@link Query} object to match a content section for replacement.
     * @param content - a {@link Block} object to insert after a matched content header.
     */
    setSection(target: Query, content: string): void;
    /**
     * Set the section content at the supplied index. If the index is out of range, throw an error.
     *
     * @param index - index at which to set a section's content.
     * @param content - a {@link Block} object to insert after a matched content header.
     */
    setSectionAt(index: number, content: string): void;
}

/**
 * The ReadmeBlock represents the header and the content of a Readme section.
 * It exists to provide a way for the user to use methods returning {@link ReadmeBlock}
 * with the {@link Readme} instance.
 * @public
 */
export declare class ReadmeBlock {
    /**
     * A parsed Markdown header.
     */
    header: string;
    /**
     * A parsed Markdown section.
     */
    content: string;
    /**
     * @param block - an object conforming to the {@link Block} interface
     */
    constructor(block: Block);
    /**
     * @returns a string formatting the combination of the header and the content lines.
     */
    toString(): string;
}

/**
 * Represents a script or environment variable doc block in package.json
 * @public
 */
export declare interface ScriptDoc {
    /**
     * script doc description property.
     */
    description: string;
    /**
     * flag as to whether script is for devs or not.
     * not currently used, but potentially useful for future organization.
     */
    dev: boolean;
}

/**
 * Collection of named {@link ScriptDoc} docs
 * @public
 */
export declare interface ScriptDocs {
    /**
     * A string to {@link ScriptDoc}-block mapping.
     */
    [index: string]: ScriptDoc;
}

/**
 * Defines an individual assertion
 * @public
 */
export declare interface SdkAssertionTest {
    assertion?: SdkTestAssertionType;
    assertionFunction: Assertion;
    input?: any;
    name: string;
    property?: string;
}

/**
 * Defines a collection of primitive tests to be executed
 * @public
 */
export declare interface SdkAssertionTestSuite {
    assertions: SdkAssertionTest[];
    name: string;
}

/**
 * Properties required for an SDK enum test
 * @public
 */
export declare interface SdkEnumTest {
    assert: any;
    input?: string | number;
}

/**
 * Complete set of properties required for an SDK enum test suite
 * @public
 */
export declare interface SdkEnumTestSuite {
    conversionFunction: (data?: any) => Promise<string>;
    targetEnum: string;
    tests: SdkEnumTest[];
}

/**
 * Properties required for an SDK model test mock
 * @public
 */
export declare interface SdkModelTestMock {
    assert: string;
    input: object;
}

/**
 * Complete set of properties required for an SDK model test suite
 * @public
 */
export declare interface SdkModelTestSuite {
    conversionFunction: (data?: any) => Promise<object | Error>;
    mocks: SdkModelTestMock[];
    targetModel: string;
}

/**
 * Properties required for an SDK string test
 * @public
 */
export declare interface SdkStringTest {
    assert: string;
    input?: string;
}

/**
 * Complete set of properties required for an SDK string test suite
 * @public
 */
export declare interface SdkStringTestSuite {
    conversionFunction: Assertion;
    strings: SdkStringTest[];
    targetString: string;
}

/**
 * Currently supported primitive assertions
 * @public
 */
export declare enum SdkTestAssertionType {
    IS_NULL = "is_null",
    IS_NOT_NULL = "is_not_null",
    IS_NOT_UNDEFINED = "is_not_undefined",
    IS_TRUE = "is_true",
    IS_FALSE = "is_false",
    TO_NOT_THROW = "not_to_throw",
    TO_THROW = "to_throw"
}

/**
 * Mechanism for synchronous wait.
 * Usage: `await this.sleep(5000)`
 * @param milliseconds - the number of milliseconds to wait
 * @internal
 */
export declare const sleep: (milliseconds?: number) => Promise<void>;

/**
 * Iterates over all JSON files and alpha sorts them
 * @remarks
 * This excludes files not in VCS
 * @public
 */
export declare const sortJson: (path?: string, options?: GlobOptions, callback?: globCallback) => void;

/**
 * Normalizes all documentation in the project.
 * @param content - readme text content.
 * @param title - name of the H1 header
 * @param scriptDocs - a {@link ScriptDocs} object containing documentation on package.json scripts.
 * @param envDocs - a {@link EnvDocs} object containing documentation for environment variables
 * @param repoRoot - the name of the repository, used as a fallback for the top-level readme header if it's missing.
 * @public
 * @returns an exported {@link Readme} instance.
 */
export declare function standardize(content: string, title: string, scriptDocs?: ScriptDocs, envDocs?: EnvDocs, repoRoot?: string): string;

/**
 * Executes an method and asserts the execution time is within bounds
 *
 * @param suite - The suite to be executed
 * @public
 */
export declare const testExecutionTime: (name: string, method: any, time: number) => void;

/**
 * Executes an SDK assertion suite using the provided functions
 *
 * @param suite - The suite to be executed
 * @public
 */
export declare const testSdkAssertion: (suite: SdkAssertionTestSuite) => Promise<void>;

/**
 * Executes an SDK enum conversion test suite using the provided conversion
 * function and array of tests.
 *
 * @param suite - The suite to be executed
 * @public
 */
export declare const testSdkEnumConversion: (suite: SdkEnumTestSuite) => Promise<void>;

/**
 * Executes an SDK model conversion test suite using the provided conversion
 * function and array of mocks.
 *
 * @param suite - The suite to be executed
 * @public
 */
export declare const testSdkModelConversion: (suite: SdkModelTestSuite) => Promise<void>;

/**
 * Executes an SDK string conversion test suite using the provided conversion
 * function and array of tests.
 *
 * @param suite - The suite to be executed
 * @public
 */
export declare const testSdkStringConversion: (suite: SdkStringTestSuite) => Promise<void>;

/**
 * Defines a specific output type, which is log level + location
 * @public
 */
export declare interface Transports {
    type: TransportType;
    logLevel: LogLevel;
}

/**
 * The valid output locations for logs
 * @remarks Additional output locations will be enabled in the future
 * @public
 */
export declare enum TransportType {
    CONSOLE = "console",
    FILE = "file",
    NONE = "none",
    API = "api"
}

export { }