import type { FnElementInfo, MermaidClassDiagramArguments, PrintHierarchyArguments, TypeElementKind } from '../doc-util/doc-types';
import type { RShell } from '../../r-bridge/shell';
import type { ValidWikiDocumentTargetsNoSuffix } from '../../cli/wiki';
import type { PathLike } from 'fs';
import type { scripts } from '../../cli/common/scripts-info';
import type { ScriptOptions } from '../doc-util/doc-cli-option';
import type { ReplCommandNames } from '../../cli/repl/commands/repl-commands';
/**
 * Context available when generating documentation for a wiki in markdown format
 */
export interface ElementFilter {
    /** In case names collide, you can use this to further distinguish between them */
    readonly file?: RegExp;
    /** In case names collide, you can use this to further distinguish between them, by specifying the kind you search for */
    readonly type?: TypeElementKind;
    /** Whether to use fuzzy matching for the element name */
    readonly fuzzy?: boolean;
}
/**
 * Formatting options for links to code elements
 */
export interface LinkFormat {
    /**
     * Whether to use md code font for the link text
     */
    codeFont?: boolean;
    /**
     * Wrapper for the real name (if specified), e.g., to italicize or bold it
     */
    realNameWrapper?: 'i' | 'b';
}
export type ElementId = string;
export type ElementIdOrRef = ElementId | {
    name: string;
} | (new () => unknown);
type NamedPrototype = {
    prototype: {
        constructor: {
            name: string;
        };
    };
};
type ProtoKeys<T> = T extends {
    prototype: infer P;
} ? keyof P : never;
type StaticKeys<T> = T extends {
    prototype: infer P;
} ? Exclude<keyof T, keyof P> : never;
export declare const ConstantWikiLinkInfo: {
    readonly 'flowr:npm': {
        readonly url: "https://www.npmjs.com/package/@eagleoutice/flowr";
        readonly name: "flowR on npm";
    };
    readonly 'flowr:github': {
        readonly url: string;
        readonly name: "flowR's GitHub";
    };
    readonly 'flowr:wiki': {
        readonly url: "https://github.com/flowr-analysis/flowr/wiki";
        readonly name: "flowR's wiki";
    };
    readonly 'flowr:docker': {
        readonly url: "https://hub.docker.com/r/eagleoutice/flowr";
        readonly name: "flowR's Docker Image";
    };
    readonly 'flowr:vscode': {
        readonly url: "https://marketplace.visualstudio.com/items?itemName=code-inspect.vscode-flowr";
        readonly name: "flowR extension for VS Code";
    };
    readonly 'flowr:positron': {
        readonly url: "https://open-vsx.org/extension/code-inspect/vscode-flowr";
        readonly name: "flowR extension for Positron";
    };
    readonly 'flowr:rstudio-addin': {
        readonly url: "https://github.com/flowr-analysis/rstudio-addin-flowr";
        readonly name: "flowR RStudio Addin";
    };
    readonly 'flowr:radapter': {
        readonly url: "https://github.com/flowr-analysis/flowr-r-adapter";
        readonly name: "flowR R Adapter";
    };
    readonly 'flowr:benchmarks': {
        readonly url: "https://flowr-analysis.github.io/flowr/wiki/stats/benchmark";
        readonly name: "flowR benchmark page";
    };
    readonly 'flowr:docs': {
        readonly url: "https://flowr-analysis.github.io/flowr/docs";
        readonly name: "flowR code docs";
    };
    readonly 'flowr:zenodo': {
        readonly url: "https://zenodo.org/doi/10.5281/zenodo.13319290";
        readonly name: "flowR on Zenodo";
    };
};
/**
 * Provides methods to generate links, code snippets, and documentation for code elements.
 * These wrap around a collection of useful helpers originating from the doc utils.
 * To create an instance, use {@link makeDocContextForTypes} (although if you are writing a wiki, you get such an instance).
 */
export interface GeneralDocContext {
    /**
     * Generate a hyperlink to a code element in the wiki.
     * If you want to reference the member of a class, use `ClassName::MemberName` as element name.
     * For ease of use, you can also call {@link GeneralDocContext#linkM|linkM} to create a link to a member.
     * @param element - The element to create a link for, the name can be qualified with `::` to specify the class.
     *                  This causes the link to be usually printed as `ClassName::ElementName`. If you want to avoid showing
     *                  the class name, use `:::` as separator. Please note that for elements with a sensible (`.name`),
     *                  you can also pass the function/constructor reference directly (e.g., `link(MyClass)`).
     * @param fmt     - Formatting options for the link (see {@link LinkFormat})
     * @param filter  - An optional filter to further specify the element to link to, in case multiple elements with the same name exist.
     * @example
     * ```ts
     * link(registerPluginMaker.name)
     * ```
     *
     * Creates a (markdown) link to the `registerPluginMaker` function in the code base
     * and, if available, attaches the TS documentation as tooltip.
     * By using the `.name`, the link text will be `registerPluginMaker` but respect, e.g., renaming refactorings done in the code base.
     * @see {@link linkFile}  - to create a link using the file path as name.
     * @see {@link shortLink} - for the underlying impl.
     * @see {@link dropGenericsFromTypeName} - to clean up type names for display.
     */
    link(element: ElementIdOrRef, fmt?: LinkFormat, filter?: ElementFilter): string;
    /**
     * Generate a hyperlink to a member of a class in the wiki.
     * This is a convenience method around {@link GeneralDocContext#link|link}.
     * @example
     * ```ts
     * linkM(MyClass, 'myMethod')
     * ```
     *
     * Creates a (markdown) link to the `myMethod` member of the `MyClass` class in the code base.
     * @see {@link GeneralWikiContext#link|link} - for the underlying impl.
     * @see {@link GeneralWikiContext#linkO|linkO} - to link using an object reference instead of a class and member name (e.g. for helper objects).
     */
    linkM<T extends NamedPrototype>(cls: T, element: ProtoKeys<T> | StaticKeys<T>, fmt?: LinkFormat & {
        hideClass?: boolean;
    }, filter?: ElementFilter): string;
    /**
     * Generate a hyperlink to a type/element definition in the code base which is displayed using the type/element name as link text.
     * This is similar to {@link GeneralDocContext#link}, but it uses the type/element name as link text, which is especially useful for types with long or complex names.
     */
    linkO<T extends object & {
        name: string;
    }>(obj: T, element: keyof T, fmt?: LinkFormat, filter?: ElementFilter): string;
    /**
     * Generate a hyperlink to a type/element definition in the code base which is displayed using the file path as name
     * @param element - The element to create a link for, the name can be qualified with `::` to specify the class.
     * @example
     * ```ts
     * linkFile(registerPluginMaker.name)
     * ```
     * Creates a (markdown) link to the `registerPluginMaker` function in the code base
     * using the file path as link name.
     * @see {@link GeneralWikiContext#link|link} - to create a link with a custom name/using the type name by default.
     * @see {@link linkFile}  - for the underlying impl.
     */
    linkFile(element: ElementIdOrRef): string;
    /**
     * Returns the documentation for a code element as markdown string.
     * If you want to, e.g., prefix all of these lines with indentation or `> ` for blockquotes,
     * use {@link prefixLines}.
     * @param element - The element to create documentation for, the name can be qualified with `::` to specify the class.
     * @param filter  - An optional filter to further specify the element to get the documentation for, in case multiple elements with the same name exist.
     * @example
     * ```ts
     * doc(exampleFn.name)
     * ```
     *
     * Creates the documentation for the `exampleFn` function in the code base as markdown string.
     * @see {@link getDocumentationForType} - for the underlying impl.
     * @see {@link removeCommentSymbolsFromTypeScriptComment} - to clean up TS doc comments.
     */
    doc(element: ElementIdOrRef, filter?: Omit<ElementFilter, 'file'>): string;
    /**
     * Returns the code snippet for a code element as markdown string.
     * @param element - The element to create a code snippet for, the name can be qualified with `::` to specify the class.
     * @param fmt     - Formatting options for the code snippet (see {@link FnElementInfo})
     * @param filter  - An optional filter to further specify the element to get the code for, in case multiple elements with the same name exist.
     * @example
     * ```ts
     * code(exampleFn.name, { dropLinesStart: 1, dropLinesEnd: 2 })
     * ```
     *
     * Creates a code snippet for the `exampleFn` function in the code base,
     * dropping the first and last two lines of the function definition.
     * If, for example, the function looks like this:
     *
     * ```ts
     * function exampleFn(a: number, b: number): number {
     *    // This is an example
     *     const result = a + b;
     *     return result;
     * }
     * ```
     *
     * The resulting code snippet will be (auto-gobbled by default):
     *
     * ```ts
     * // This is an example
     * const result = a + b;
     * ```
     * @see {@link printCodeOfElement} - for the underlying impl.
     */
    code(element: ElementIdOrRef, fmt?: Omit<FnElementInfo, 'info' | 'program'>, filter?: ElementFilter): string;
    /**
     * Returns the code snippet for a code file as markdown string.
     * @param path - The path to the file to create a code snippet for.
     * @param fmt  - Formatting options for the code snippet (see {@link FnElementInfo})
     * @example
     * ```ts
     * code('src/path/to/file.ts', { skipImports: true })
     * ```
     *
     * Creates a code snippet for the source file `src/path/to/file.ts`,
     * dropping the lines with import statements of the source code.
     */
    codeFile(path: string, fmt?: Omit<FnElementInfo, 'info' | 'program'>): string;
    /**
     * Returns the hierarchy (e.g., class inheritance) for a code element as markdown string,
     * including their documentation and snippets.
     * @param element - The element to create a hierarchy for, the name can be qualified with `::` to specify the class.
     * @param fmt     - Formatting options for the hierarchy (see {@link PrintHierarchyArguments})
     * @param filter  - An optional filter to further specify the element to get the hierarchy for, in case multiple elements with the same name exist.
     * @example
     * ```ts
     * hierarchy(MyClass.name, { maxDepth: 2 })
     * ```
     *
     * Creates the hierarchy for the `MyClass` class in the code base,
     * including up to two levels of inheritance.
     * @see {@link printHierarchy} - for the underlying impl.
     */
    hierarchy(element: ElementIdOrRef, fmt?: Omit<PrintHierarchyArguments, 'info' | 'program' | 'root'>, filter?: ElementFilter): string;
    /**
     * Generates an auto-generation header for the wiki page.
     * @param filename - The name of the file being generated. Probably use `module.filename`.
     * @param purpose - The purpose of the file, e.g., 'wiki context for types'.
     */
    header(filename: string, purpose: string): Promise<string>;
    /**
     * Generates a mermaid diagram for the given code element, returned as markdown string.
     * @param element - The element to create a mermaid diagram for, the name can be qualified with `::` to specify the class.
     * @param options - Formatting options for the mermaid class diagram (see {@link MermaidClassDiagramArguments})
     */
    mermaid(element: ElementIdOrRef, options?: MermaidClassDiagramArguments): string;
    /**
     * Generates a wiki link to another wiki or general docs page.
     * @example
     * ```ts
     * linkWikiPage('wiki/Setup')
     * ```
     * Creates a link to the `wiki/Setup` wiki page with the link text `Setup`.
     * This also supports a select subset of external pages in the context of flowR
     * @param pageName - The name of the wiki page to link to.
     * @param linkText - Optional text to display for the link. If not provided, the page name will be used.
     * @param segment  - An optional segment within the page to link to (e.g., a header anchor).
     */
    linkPage(pageName: ValidWikiDocumentTargetsNoSuffix | keyof typeof ConstantWikiLinkInfo, linkText?: string, segment?: string): string;
    /**
     * Generates a link to a code file in the code base.
     * @param path       - The path to the code file.
     * @param lineNumber - An optional line number to link to within the file.
     */
    linkCode(path: PathLike, lineNumber?: number): string;
    /**
     * Generates the CLI long option for a given script and option name.
     * @example
     * ```ts
     * cliOption('flowr', 'help')
     * ```
     * Returns `--help` with the accompanying docs.
     * @param scriptName - The name of the script (e.g., 'flowr', 'analyze', etc.)
     * @param optionName - The name of the option for which to generate the long option string.
     * @param withAlias  - Whether to include the alias in the output. Default is `false`.
     * @param quote      - Whether to wrap the option in backticks. Default is `true`.
     * @see {@link ScriptOptions} - for the valid option names per script.
     * @see {@link getCliLongOptionOf} - for the underlying impl.
     */
    cliOption<ScriptName extends keyof typeof scripts | 'flowr', OptionName extends ScriptOptions<ScriptName>>(scriptName: ScriptName, optionName: OptionName, withAlias?: boolean, quote?: boolean): string;
    /**
     * Generates the REPL command string for a given command name.
     * @example
     * ```ts
     * replCmd('help')
     * ```
     * Returns `:help` with the accompanying docs.
     * @param commandName - The name of the REPL command.
     * @param quote - Whether to wrap the command in backticks. Default is `true`.
     * @param showStar - Whether to show a `[*]` suffix for starred commands. Default is `false`.
     * @see {@link getReplCommand} - for the underlying impl.
     */
    replCmd(commandName: ReplCommandNames, quote?: boolean, showStar?: boolean): string;
}
/**
 * Creates a wiki context for generating documentation for code elements.
 * This context provides methods to create links, code snippets, and documentation for code elements.
 * @param shell       - An optional RShell instance to retrieve the R version for the auto-generation header.
 * @param rootFolders - The root folder(s) of the code base to analyze. Defaults to flower's `src/` **and** `test/` folder.
 * @example
 * ```ts
 * const ctx = makeContextForTypes();
 * const linkToFn = ctx.link('myFunction');
 * const fnDoc = ctx.doc('myFunction');
 * ```
 */
export declare function makeDocContextForTypes(shell?: RShell, ...rootFolders: string[]): GeneralDocContext;
export {};