@eagleoutice/flowr 2.6.1 → 2.6.3

package/documentation/doc-util/doc-search.d.ts

@@ -1,25 +1,10 @@
 import type { RShell } from '../../r-bridge/shell';
-import type { SupportedQueryTypes } from '../../queries/query';
-import type { SupportedVirtualQueryTypes } from '../../queries/virtual-query/virtual-queries';
 import type { FlowrSearchLike } from '../../search/flowr-search-builder';
 export interface ShowSearchOptions {
     readonly showCode?: boolean;
     readonly collapseResult?: boolean;
 }
+/**
+ * Visualizes a search and its results in markdown format.
+ */
 export declare function showSearch(shell: RShell, code: string, search: FlowrSearchLike, { collapseResult }?: ShowSearchOptions): Promise<string>;
-export interface QueryDocumentation {
-    readonly name: string;
-    readonly type: 'virtual' | 'active';
-    readonly shortDescription: string;
-    readonly functionName: string;
-    readonly functionFile: string;
-    readonly buildExplanation: (shell: RShell) => Promise<string>;
-}
-export declare const RegisteredQueries: {
-    active: Map<string, QueryDocumentation>;
-    virtual: Map<string, QueryDocumentation>;
-};
-export declare function registerQueryDocumentation(query: SupportedQueryTypes | SupportedVirtualQueryTypes, doc: QueryDocumentation): void;
-export declare function linkToQueryOfName(id: SupportedQueryTypes | SupportedVirtualQueryTypes): string;
-export declare function tocForQueryType(type: 'active' | 'virtual'): string;
-export declare function explainQueries(shell: RShell, type: 'active' | 'virtual'): Promise<string>;

package/documentation/doc-util/doc-search.js

@@ -1,13 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RegisteredQueries = void 0;
 exports.showSearch = showSearch;
-exports.registerQueryDocumentation = registerQueryDocumentation;
-exports.linkToQueryOfName = linkToQueryOfName;
-exports.tocForQueryType = tocForQueryType;
-exports.explainQueries = explainQueries;
-const retriever_1 = require("../../r-bridge/retriever");
-const doc_files_1 = require("./doc-files");
 const doc_dfg_1 = require("./doc-dfg");
 const doc_code_1 = require("./doc-code");
 const time_1 = require("../../util/text/time");
@@ -15,11 +8,15 @@ const flowr_search_printer_1 = require("../../search/flowr-search-printer");
 const node_id_1 = require("../../r-bridge/lang-4.x/ast/model/processing/node-id");
 const dfg_1 = require("../../util/mermaid/dfg");
 const flowr_analyzer_builder_1 = require("../../project/flowr-analyzer-builder");
+/**
+ * Visualizes a search and its results in markdown format.
+ */
 async function showSearch(shell, code, search, { collapseResult = true } = {}) {
     const now = performance.now();
-    const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder((0, retriever_1.requestFromInput)(code))
+    const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder()
         .setParser(shell)
         .build();
+    analyzer.addRequest(code);
     const result = await analyzer.runSearch(search);
     const duration = performance.now() - now;
     const metaInfo = `
@@ -52,7 +49,7 @@ ${collapseResult ? ' <details> <summary style="color:gray">Show Results</summary
 The query returns the following vetices (all references to \`x\` in the code):
 ${result.getElements().map(({ node }) => `<b>${node.info.id} ('${(0, node_id_1.recoverContent)(node.info.id, dataflow.graph)}')</b> at L${(0, dfg_1.formatRange)(node.location)}`).join(', ')}
 
-${metaInfo}	
+${metaInfo}
 
 The returned results are highlighted thick and blue within the dataflow graph:
 
@@ -63,57 +60,4 @@ ${collapseResult ? '</details>' : ''}
 
 	`;
 }
-exports.RegisteredQueries = {
-    'active': new Map(),
-    'virtual': new Map()
-};
-function registerQueryDocumentation(query, doc) {
-    const map = exports.RegisteredQueries[doc.type];
-    if (map.has(query)) {
-        throw new Error(`Query ${query} already registered`);
-    }
-    map.set(query, doc);
-}
-function linkify(name) {
-    return name.toLowerCase().replace(/ /g, '-');
-}
-function linkToQueryOfName(id) {
-    const query = exports.RegisteredQueries.active.get(id) ?? exports.RegisteredQueries.virtual.get(id);
-    if (!query) {
-        throw new Error(`Query ${id} not found`);
-    }
-    return `[${query.name}](#${linkify(query.name)})`;
-}
-function tocForQueryType(type) {
-    const queries = [...exports.RegisteredQueries[type].entries()].sort(([, { name: a }], [, { name: b }]) => a.localeCompare(b));
-    const result = [];
-    for (const [id, { name, shortDescription }] of queries) {
-        result.push(`1. [${name}](#${linkify(name)}) (\`${id}\`):\\\n    ${shortDescription}`);
-    }
-    return result.join('\n');
-}
-async function explainQuery(shell, { name, functionName, functionFile, buildExplanation }) {
-    return `
-### ${name}
-
-${await buildExplanation(shell)}
-
-<details> 
-
-<summary style="color:gray">Implementation Details</summary>
-
-Responsible for the execution of the ${name} query is \`${functionName}\` in ${(0, doc_files_1.getFilePathMd)(functionFile)}.
-
-</details>	
-
-`;
-}
-async function explainQueries(shell, type) {
-    const queries = [...exports.RegisteredQueries[type].entries()].sort(([, { name: a }], [, { name: b }]) => a.localeCompare(b));
-    const result = [];
-    for (const [, doc] of queries) {
-        result.push(await explainQuery(shell, doc));
-    }
-    return result.join(`\n${'-'.repeat(5)}\n\n`);
-}
 //# sourceMappingURL=doc-search.js.map

package/documentation/doc-util/doc-server-message.d.ts

@@ -1,6 +1,6 @@
-import type { RShell } from '../../r-bridge/shell';
 import type { FlowrMessage, IdMessageBase, MessageDefinition } from '../../cli/repl/server/messages/all-messages';
-import type { FakeServer, FakeSocket } from '../../../test/functionality/_helper/net';
+import { type FakeServer, type FakeSocket } from '../../../test/functionality/_helper/net';
+import type { KnownParser } from '../../r-bridge/parser';
 export interface ServerMessageDescription {
     readonly title: string;
     readonly type: 'request' | 'response';
@@ -10,11 +10,20 @@ export interface ServerMessageDescription {
     readonly defRequest?: MessageDefinition<IdMessageBase>;
     readonly defResponse?: MessageDefinition<IdMessageBase>;
     readonly additionalDefs?: MessageDefinition<IdMessageBase>[];
-    readonly text: (shell: RShell) => Promise<string>;
+    readonly text: (shell: KnownParser) => Promise<string>;
 }
+/**
+ * Documents a server message for later printing.
+ */
 export declare function documentServerMessage(description: ServerMessageDescription): void;
-export declare function printServerMessages(shell: RShell): Promise<string>;
-export declare function inServerContext<T>(shell: RShell, fn: (socket: FakeSocket, server: FakeServer) => Promise<T> | T): Promise<T>;
+/**
+ * Visualizes all documented server messages in markdown format.
+ */
+export declare function printServerMessages(treeSitter: KnownParser): Promise<string>;
+/**
+ * Executes the given function within a server context.
+ */
+export declare function inServerContext<T>(shell: KnownParser, fn: (socket: FakeSocket, server: FakeServer) => Promise<T> | T): Promise<T>;
 interface ResponseMessageInPingPong {
     readonly type: 'response';
     readonly expectedType: FlowrMessage['type'];
@@ -28,10 +37,13 @@ interface RequestMessageInPingPong {
     readonly mark?: boolean;
 }
 export interface MessagePingPongDocumentationArguments {
-    readonly shell: RShell;
+    readonly shell: KnownParser;
     readonly title?: string;
     readonly messageType?: FlowrMessage['type'];
     readonly messages: readonly (ResponseMessageInPingPong | RequestMessageInPingPong)[];
 }
+/**
+ * Documents a ping-pong message exchange with the server.
+ */
 export declare function documentServerMessageResponse({ shell, title, messageType, messages }: MessagePingPongDocumentationArguments): Promise<string>;
 export {};

package/documentation/doc-util/doc-server-message.js

@@ -12,16 +12,25 @@ const doc_code_1 = require("./doc-code");
 const assert_1 = require("../../util/assert");
 const time_1 = require("../../util/text/time");
 const messages = [];
+/**
+ * Documents a server message for later printing.
+ */
 function documentServerMessage(description) {
     messages.push(description);
 }
-async function printServerMessages(shell) {
+/**
+ * Visualizes all documented server messages in markdown format.
+ */
+async function printServerMessages(treeSitter) {
     let text = '<ul>';
     for (const message of messages) {
-        text += '<li>' + await printServerMessage(message, shell) + '</li>\n\n';
+        text += '<li>' + await printServerMessage(message, treeSitter) + '</li>\n\n';
     }
     return text + '</ul>';
 }
+/**
+ * Executes the given function within a server context.
+ */
 async function inServerContext(shell, fn) {
     return (0, net_1.withSocket)(shell, async (socket, server) => {
         return fn(socket, server);
@@ -69,6 +78,9 @@ function explainPingPong(description, received) {
     }
     return result + '</ol>';
 }
+/**
+ * Documents a ping-pong message exchange with the server.
+ */
 async function documentServerMessageResponse({ shell, title, messageType, messages }) {
     const start = performance.now();
     const response = await inServerContext(shell, async (socket) => {
@@ -116,7 +128,7 @@ ${(0, schema_1.describeSchema)(def.schema, ansi_1.markdownFormatter)}
 </details>
 ` : '';
 }
-async function printServerMessage({ mermaidSequenceDiagram, text, title, shortDescription, definitionPath, defRequest, defResponse, additionalDefs }, shell) {
+async function printServerMessage({ mermaidSequenceDiagram, text, title, shortDescription, definitionPath, defRequest, defResponse, additionalDefs }, treeSitter) {
     const base = defRequest ?? defResponse;
     (0, assert_1.guard)(base !== undefined, 'At least one of the definitions must be given');
     return `
@@ -135,7 +147,7 @@ sequenceDiagram
     ${mermaidSequenceDiagram}
 \`\`\`
 
-${await text(shell)}
+${await text(treeSitter)}
 
 <hr>
 
@@ -145,7 +157,7 @@ ${additionalDefs?.map(def => getSchema(definitionPath, def)).join('\n') ?? ''}
 
 <hr>
 
-</details>	
+</details>
 	`;
 }
 //# sourceMappingURL=doc-server-message.js.map

package/documentation/doc-util/doc-structure.d.ts

@@ -4,12 +4,21 @@ export interface DetailsOptions {
     readonly hideIfEmpty?: boolean;
     readonly prefixInit?: string;
 }
+/**
+ *
+ */
 export declare function details(title: string, content: string, { color, open, hideIfEmpty, prefixInit }?: DetailsOptions): string;
 export interface BlockOptions {
     readonly type: 'NOTE' | 'WARNING' | 'TIP' | 'IMPORTANT';
     readonly content: string;
 }
+/**
+ *
+ */
 export declare function block({ type, content }: BlockOptions): string;
+/**
+ *
+ */
 export declare function section(title: string, depth?: 1 | 2 | 3 | 4 | 5 | 6, anchor?: string): string;
 /**
  * Supported pattern: `Name@link`

package/documentation/doc-util/doc-structure.js

@@ -7,21 +7,30 @@ exports.collapsibleToc = collapsibleToc;
 const doc_general_1 = require("./doc-general");
 const mermaid_1 = require("../../util/mermaid/mermaid");
 const strings_1 = require("../../util/text/strings");
+/**
+ *
+ */
 function details(title, content, { color, open = false, hideIfEmpty = true, prefixInit = '' } = {}) {
     return hideIfEmpty && content.trim().length === 0 ? '' : `
-${prefixInit}<details${open ? ' open' : ''}><summary style="${color ? 'color:' + color : ''}">${title}</summary>
+${prefixInit}<details${open ? ' open' : ''}><summary${color ? ' style="color:' + color + '"' : ''}>${title}</summary>
 
 ${content}
 
 </details>
     `;
 }
+/**
+ *
+ */
 function block({ type, content }) {
     return `
 > [!${type}]
 ${(0, doc_general_1.prefixLines)(content, '> ')}
 `;
 }
+/**
+ *
+ */
 function section(title, depth = 2, anchor = (0, mermaid_1.escapeId)(title)) {
     return `<h${depth} id="${anchor}">${title}</h${depth}>`;
 }

package/documentation/doc-util/doc-types.d.ts

@@ -1,5 +1,12 @@
 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;
@@ -11,20 +18,57 @@ export interface TypeElementInSource {
     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 getTextualCommentsFromTypeScript(node: ts.Node): string[];
+/**
+ *
+ */
 export declare function getStartLineOfTypeScriptNode(node: ts.Node, sourceFile: ts.SourceFile): number;
-export declare function getType(node: ts.Node, typeChecker: ts.TypeChecker): string;
-export declare function followTypeReference(type: ts.TypeReferenceNode, sourceFile: ts.SourceFile): string[];
-export declare function getTypePathForTypeScript({ filePath }: Pick<TypeElementInSource, 'filePath'>): string;
+/**
+ * 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;
+/**
+ * Visualize the type hierarchy as a mermaid class diagram.
+ */
+export declare function visualizeMermaidClassDiagram(hierarchyList: readonly TypeElementInSource[], options: {
+    typeNameForMermaid?: string;
+    inlineTypes?: readonly string[];
+}): string | undefined;
 export interface GetTypesAsMermaidOption {
-    readonly rootFolder?: string;
+    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;
@@ -47,7 +91,6 @@ export declare function getTypesFromFolder(options: GetTypesAsMermaidOption & {
     mermaid: undefined;
 });
 export declare function getTypesFromFolder(options: GetTypesAsMermaidOption): TypeReport;
-export declare function implSnippet(node: TypeElementInSource | undefined, program: ts.Program, showName?: boolean, nesting?: number, open?: boolean): string;
 export interface PrintHierarchyArguments {
     readonly program: ts.Program;
     readonly info: TypeElementInSource[];
@@ -56,20 +99,41 @@ export interface PrintHierarchyArguments {
     readonly initialNesting?: number;
     readonly maxDepth?: number;
     readonly openTop?: boolean;
+    readonly showImplSnippet?: boolean;
 }
 export declare const mermaidHide: string[];
-export declare function printHierarchy({ program, info, root, collapseFromNesting, initialNesting, maxDepth, openTop }: PrintHierarchyArguments): string;
-interface FnInfo {
+/**
+ * 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, collapseFromNesting, initialNesting, maxDepth, openTop, showImplSnippet }: 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;
 }
-export declare function printCodeOfElement({ program, info, dropLinesEnd, dropLinesStart, doNotAutoGobble, hideDefinedAt }: FnInfo, name: string): string;
 /**
- * Create a short link to a type in the documentation
+ * 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 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
@@ -77,10 +141,25 @@ export declare function printCodeOfElement({ program, info, dropLinesEnd, dropLi
  * @param realNameWrapper - How to highlight the function in name in the `x::y` format?
  */
 export declare function shortLink(name: string, hierarchy: readonly TypeElementInSource[], codeStyle?: boolean, realNameWrapper?: 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 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;
-export {};