@eagleoutice/flowr/documentation/doc-util/doc-types.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import ts from 'typescript';
/**
 * Kinds of TypeScript type elements we can encounter.
 * Please note, that a `function` is also a `variable` here.
 */
export type TypeElementKind = 'interface' | 'type' | 'enum' | 'class' | 'variable';
/**
 * The full underlying information about a TypeScript type element found in source code.
 */
export interface TypeElementInSource {
    name: string;
    node: ts.Node;
    kind: TypeElementKind;
    extends: string[];
    generics: string[];
    filePath: string;
    lineNumber: number;
    comments?: string[];
    readonly properties?: string[];
}
/**
 * Retrieve TypeScript source files from the given file names.
 */
export declare function getTypeScriptSourceFiles(fileNames: readonly string[]): {
    files: ts.SourceFile[];
    program: ts.Program;
};
/**
 * Drop generics from a TypeScript type name.
 * @example
 * ```ts
 * const typeName = 'MyType<T, U>';
 * const cleanName = dropGenericsFromTypeName(typeName);
 * console.log(cleanName); // 'MyType'
 * ```
 */
export declare function dropGenericsFromTypeName(type: string): string;
/**
 * Remove comment symbols from a TypeScript comment string.
 * This also takes care of special JSDoc tags like `{@link ...}` and `{@see ...}`.
 * @example
 * ```ts
 * const comment = '/**\n* This is a comment.\n* It has multiple lines.\n *\/'; // closing comment sadly escaped for ts doc
 * const cleaned = removeCommentSymbolsFromTypeScriptComment(comment);
 * console.log(cleaned);
 * ```
 * This will output:
 * ```md
 * This is a comment.
 * It has multiple lines.
 * ```
 */
export declare function removeCommentSymbolsFromTypeScriptComment(comment: string): string;
/**
 *
 */
export declare function getStartLineOfTypeScriptNode(node: ts.Node, sourceFile: ts.SourceFile): number;
/**
 * Return the link to the type in the source code.
 * If you create a wiki, please refer to the functions provided by the {@link GeneralWikiContext}.
 */
export declare function getTypePathLink(elem: Pick<TypeElementInSource, 'filePath' | 'lineNumber'>, prefix?: string): string;
export interface MermaidClassDiagramArguments {
    readonly inlineTypes?: readonly string[];
    readonly simplify?: boolean;
    readonly reverse?: boolean;
}
/**
 * Visualize the type hierarchy as a mermaid class diagram.
 */
export declare function visualizeMermaidClassDiagram(hierarchyList: readonly TypeElementInSource[], options: {
    typeNameForMermaid?: string;
} & MermaidClassDiagramArguments): string | undefined;
export interface GetTypesAsMermaidOption {
    readonly rootFolder?: string | string[];
    readonly files?: readonly string[];
    /** if you request a type name, we will generate a mermaid diagram for that type */
    readonly typeNameForMermaid?: string;
    readonly inlineTypes?: readonly string[];
}
export interface TypeReport {
    /** if you request a type name this will include the mermaid diagram for the type */
    mermaid: string | undefined;
    info: TypeElementInSource[];
    program: ts.Program;
}
export declare function getTypesFromFolder(options: GetTypesAsMermaidOption & {
    typeNameForMermaid: string;
}): (TypeReport & {
    mermaid: string;
});
export declare function getTypesFromFolder(options: GetTypesAsMermaidOption & {
    typeNameForMermaid?: undefined;
}): (TypeReport & {
    mermaid: undefined;
});
export declare function getTypesFromFolder(options: GetTypesAsMermaidOption): TypeReport;
export interface PrintHierarchyArguments {
    readonly program: ts.Program;
    readonly info: TypeElementInSource[];
    readonly root: string;
    readonly ignoredTypes?: readonly string[];
    readonly collapseFromNesting?: number;
    readonly initialNesting?: number;
    readonly maxDepth?: number;
    readonly skipNesting?: number;
    readonly openTop?: boolean;
    readonly showImplSnippet?: boolean;
    readonly reverse?: boolean;
}
export declare const mermaidHide: string[];
/**
 * Print the hierarchy of types starting from the given root.
 * If you create a wiki, please refer to the functions provided by the {@link GeneralWikiContext}.
 */
export declare function printHierarchy({ program, info, root, ignoredTypes, collapseFromNesting, initialNesting, maxDepth, skipNesting, openTop, showImplSnippet, reverse }: PrintHierarchyArguments): string;
/**
 * Options to print code of an element
 */
export interface FnElementInfo {
    /** The type information collected from the source code */
    info: TypeElementInSource[];
    /** The TypeScript program used to extract the info */
    program: ts.Program;
    /** Number of lines to drop from the start of the code block */
    dropLinesStart?: number;
    /** Number of lines to drop from the end of the code block */
    dropLinesEnd?: number;
    /** Whether to not automatically gobble leading spaces */
    doNotAutoGobble?: boolean;
    /** Whether to hide the "Defined at ..." line */
    hideDefinedAt?: boolean;
}
/**
 * Print an element from the info as code block.
 * If you create a wiki, please refer to the functions provided by the {@link GeneralWikiContext}.
 *
 * This is great to show examples that are directly taken from the source code.
 */
export declare function printCodeOfElement({ program, info, dropLinesEnd, dropLinesStart, doNotAutoGobble, hideDefinedAt }: FnElementInfo, name: string): string;
/**
 * Create a short link to a type in the documentation.
 * If you create a wiki, please refer to the functions provided by the {@link GeneralDocContext}.
 * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g.,`MyContainer::MyType` (this works with function nestings too)
 *                    Use `:::` if you want to access a scoped function, but the name should be displayed without the scope
 * @param hierarchy - The hierarchy of types to search in
 * @param codeStyle - Whether to use code style for the link
 * @param realNameWrapper - How to highlight the function in name in the `x::y` format?
 * @param fuzzy     - Whether to use fuzzy matching when searching for the type
 * @param type      - Optionally restrict to a certain type of element
 */
export declare function shortLink(name: string, hierarchy: readonly TypeElementInSource[], codeStyle?: boolean, realNameWrapper?: string, fuzzy?: boolean, type?: TypeElementKind): string;
/**
 * Create a short link to a type in the documentation.
 * If you create a wiki, please refer to the functions provided by the {@link GeneralWikiContext}.
 * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g.,`MyContainer::MyType` (this works with function nestings too)
 *                    Use `:::` if you want to access a scoped function, but the name should be displayed without the scope
 * @param hierarchy - The hierarchy of types to search in
 */
export declare function shortLinkFile(name: string, hierarchy: readonly TypeElementInSource[]): string;
export interface GetDocumentationForTypeFilters {
    fuzzy?: boolean;
    type?: TypeElementKind;
}
/**
 * Retrieve documentation comments for a type.
 * If you create a wiki, please refer to the functions provided by the {@link GeneralWikiContext}.
 * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g.,`MyContainer::MyType` (this works with function nestings too)
 *                    Use `:::` if you want to access a scoped function, but the name should be displayed without the scope
 * @param hierarchy - The hierarchy of types to search in
 * @param prefix    - A prefix to add to each line of the documentation
 * @param filter    - Optional filters for retrieving the documentation
 */
export declare function getDocumentationForType(name: string, hierarchy: TypeElementInSource[], prefix?: string, filter?: GetDocumentationForTypeFilters): string;