@eagleoutice/flowr 2.0.25 → 2.1.0

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

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.documentServerMessage = documentServerMessage;
+exports.printServerMessages = printServerMessages;
+exports.inServerContext = inServerContext;
+exports.documentServerMessageResponse = documentServerMessageResponse;
+const doc_files_1 = require("./doc-files");
+const schema_1 = require("../../util/schema");
+const ansi_1 = require("../../util/ansi");
+const net_1 = require("../../../test/functionality/_helper/net");
+const doc_code_1 = require("./doc-code");
+const doc_ms_1 = require("./doc-ms");
+const assert_1 = require("../../util/assert");
+const messages = [];
+function documentServerMessage(description) {
+    messages.push(description);
+}
+async function printServerMessages(shell) {
+    let text = '<ul>';
+    for (const message of messages) {
+        text += '<li>' + await printServerMessage(message, shell) + '</li>\n\n';
+    }
+    return text + '</ul>';
+}
+async function inServerContext(shell, fn) {
+    return (0, net_1.withSocket)(shell, async (socket, server) => {
+        return fn(socket, server);
+    })();
+}
+function explainMsg(msg, type, desc = '', open = false) {
+    const bold = open ? s => `<b>${s}</b>` : s => s;
+    const msgPrettyPrint = JSON.stringify(msg, null, 2);
+    return `
+<li> ${bold('<code>' + msg.type + `</code> (${type})`)}
+<details${open ? ' open' : ''}> 
+
+<summary> Show Details </summary>
+
+${desc}
+
+${msgPrettyPrint.length > 5_000 ? '_As the message is pretty long, we inhibit pretty printing and syntax highlighting:_' : ''}
+${(0, doc_code_1.codeBlock)(msgPrettyPrint.length > 5_000 ? 'text' : 'json', msgPrettyPrint.length > 5_000 ? JSON.stringify(msg) : msgPrettyPrint)}
+
+</details>
+</li>
+`;
+}
+function getDescriptionForMessage(msg, description) {
+    if (description === undefined) {
+        return '';
+    }
+    else if (typeof description === 'function') {
+        return description(msg);
+    }
+    else {
+        return description ?? '';
+    }
+}
+function explainPingPong(description, received) {
+    let result = `<ol>${explainMsg(received[0], 'response', 'The first message is always a hello message.')}`;
+    let readReceived = 1;
+    /* we received one more than we sent (`hello` :D) */
+    for (const msg of description) {
+        if (msg.type === 'request') {
+            result += explainMsg(msg.message, 'request', getDescriptionForMessage(msg.message, msg.description), msg.mark);
+        }
+        else {
+            const response = received[readReceived++];
+            result += explainMsg(response, 'response', getDescriptionForMessage(response, msg.description), msg.mark);
+        }
+    }
+    return result + '</ol>';
+}
+async function documentServerMessageResponse({ shell, title, messageType, messages }) {
+    const start = performance.now();
+    const response = await inServerContext(shell, async (socket) => {
+        for (const metaMessage of messages) {
+            if (metaMessage.type === 'request') {
+                socket.send(JSON.stringify(metaMessage.message) + '\n');
+            }
+            else {
+                try {
+                    await socket.waitForMessage(metaMessage.expectedType, 20);
+                }
+                catch (e) {
+                    console.error('Failed to receive message', metaMessage.expectedType, 'has', socket.getMessages());
+                }
+            }
+        }
+        return socket.getMessages();
+    });
+    const end = performance.now();
+    (0, assert_1.guard)(title !== undefined || messageType !== undefined, 'Either a title or a message type must be given');
+    title ??= `Example of the <code>${messageType}</code> Message`;
+    return `
+<details>
+<summary>${title}</summary>
+
+_Note:_ even though we pretty-print these messages, they are sent as a single line, ending with a newline.
+
+The following lists all messages that were sent and received in case you want to reproduce the scenario:
+
+${explainPingPong(messages, response)}
+
+The complete round-trip took ${(0, doc_ms_1.printAsMs)(end - start)} (including time required to validate the messages, start, and stop the internal mock server).
+
+</details>
+`;
+}
+function getSchema(definitionPath, def) {
+    return def ? `<details>
+<summary style="color:gray">Message schema (<code>${def.type}</code>)</summary>
+
+For the definition of the hello message, please see it's implementation at ${(0, doc_files_1.getFilePathMd)(definitionPath)}.
+
+${(0, schema_1.describeSchema)(def.schema, ansi_1.markdownFormatter)}
+
+</details>
+` : '';
+}
+async function printServerMessage({ mermaidSequenceDiagram, text, title, shortDescription, definitionPath, defRequest, defResponse, additionalDefs }, shell) {
+    const base = defRequest ?? defResponse;
+    (0, assert_1.guard)(base !== undefined, 'At least one of the definitions must be given');
+    return `
+<a id="message-${base.type}"></a>
+<b>${title}</b> Message (<code>${base.type}</code>) 
+<details>
+
+<summary style="color:gray"> View Details. <i>${shortDescription}</i> </summary>
+
+\`\`\`mermaid
+sequenceDiagram
+    autonumber
+    participant Client
+    participant Server
+
+    ${mermaidSequenceDiagram}
+\`\`\`
+
+${await text(shell)}
+
+<hr>
+
+${getSchema(definitionPath, defRequest)}
+${getSchema(definitionPath, defResponse)}
+${additionalDefs?.map(def => getSchema(definitionPath, def)).join('\n') ?? ''}
+
+<hr>
+
+</details>	
+	`;
+}
+//# sourceMappingURL=doc-server-message.js.map

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

@@ -0,0 +1,12 @@
+export interface DetailsOptions {
+    readonly color?: string;
+    readonly open?: boolean;
+    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' | 'INFO' | 'TIP';
+    readonly content: string;
+}
+export declare function block({ type, content }: BlockOptions): string;

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

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.details = details;
+exports.block = block;
+const doc_general_1 = require("./doc-general");
+function details(title, content, { color = 'black', open = false, hideIfEmpty = true, prefixInit = '' } = {}) {
+    return hideIfEmpty && content.trim().length === 0 ? '' : `
+${prefixInit}<details${open ? ' open' : ''}><summary style="color:${color}">${title}</summary>
+
+${content}
+
+</details>
+    `;
+}
+function block({ type, content }) {
+    return `
+> [!${type}]
+${(0, doc_general_1.prefixLines)(content, '> ')}
+`;
+}
+//# sourceMappingURL=doc-structure.js.map

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

@@ -0,0 +1,38 @@
+import ts from 'typescript';
+export interface TypeElementInSource {
+    name: string;
+    node: ts.Node;
+    kind: 'interface' | 'type' | 'enum';
+    extends: string[];
+    generics: string[];
+    filePath: string;
+    lineNumber: number;
+    comments?: string[];
+    readonly properties?: string[];
+}
+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 getTypePathLink({ filePath, lineNumber }: TypeElementInSource, prefix?: string): string;
+export interface GetTypesAsMermaidOption {
+    readonly rootFolder?: string;
+    readonly files?: readonly string[];
+    readonly typeName: string;
+    readonly inlineTypes?: readonly string[];
+}
+export interface MermaidTypeReport {
+    text: string;
+    info: TypeElementInSource[];
+    program: ts.Program;
+}
+export declare function getTypesFromFolderAsMermaid(options: GetTypesAsMermaidOption): MermaidTypeReport;
+export declare function implSnippet(node: TypeElementInSource | undefined, program: ts.Program, nesting?: number): string;
+export interface PrintHierarchyArguments {
+    readonly program: ts.Program;
+    readonly hierarchy: TypeElementInSource[];
+    readonly root: string;
+    readonly collapseFromNesting?: number;
+    readonly initialNesting?: number;
+    readonly maxDepth?: number;
+}
+export declare const mermaidHide: string[];
+export declare function printHierarchy({ program, hierarchy, root, collapseFromNesting, initialNesting, maxDepth }: PrintHierarchyArguments): string;

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

@@ -0,0 +1,276 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mermaidHide = void 0;
+exports.getType = getType;
+exports.followTypeReference = followTypeReference;
+exports.getTypePathLink = getTypePathLink;
+exports.getTypesFromFolderAsMermaid = getTypesFromFolderAsMermaid;
+exports.implSnippet = implSnippet;
+exports.printHierarchy = printHierarchy;
+const typescript_1 = __importDefault(require("typescript"));
+const assert_1 = require("../../util/assert");
+const doc_files_1 = require("./doc-files");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const mermaid_1 = require("../../util/mermaid/mermaid");
+const doc_code_1 = require("./doc-code");
+const doc_structure_1 = require("./doc-structure");
+function getSourceFiles(fileNames) {
+    try {
+        const program = typescript_1.default.createProgram(fileNames, { target: typescript_1.default.ScriptTarget.ESNext });
+        return { program, files: fileNames.map(fileName => program.getSourceFile(fileName)).filter(file => !!file) };
+    }
+    catch (err) {
+        console.error('Failed to get source files', err);
+        return { files: [], program: undefined };
+    }
+}
+function dropGenericsFromType(type) {
+    let previous;
+    do {
+        previous = type;
+        type = type.replace(/<.*>/g, '');
+    } while (type !== previous);
+    return type;
+}
+function removeCommentSymbols(comment) {
+    return comment.replace(/^\/\*\*?/, '').replace(/\*\/$/, '').replace(/^\s*\*/, '').trim();
+}
+function getTextualComments(node) {
+    const comments = typescript_1.default.getJSDocCommentsAndTags(node);
+    const out = [];
+    for (const { comment } of comments) {
+        if (typeof comment === 'string') {
+            out.push(comment);
+        }
+        else if (comment !== undefined) {
+            for (const c of comment) {
+                out.push(removeCommentSymbols(c.getText(c.getSourceFile())));
+            }
+        }
+    }
+    return out;
+}
+function getStartLine(node, sourceFile) {
+    const lineStart = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line;
+    return lineStart + 1;
+}
+function getType(node, typeChecker) {
+    const tryDirect = typeChecker.getTypeAtLocation(node);
+    return tryDirect ? typeChecker.typeToString(tryDirect) : 'unknown';
+}
+function followTypeReference(type, sourceFile) {
+    const node = type.typeName;
+    if (typescript_1.default.isQualifiedName(node)) {
+        return [node.right.getText(sourceFile) ?? ''];
+    }
+    const args = type.typeArguments?.map(arg => arg.getText(sourceFile)) ?? [];
+    const nodeLexeme = node.getText(sourceFile) ?? '';
+    if (['Pick', 'Partial', 'Required', 'Readonly', 'Omit'].map(s => nodeLexeme.startsWith(s))) {
+        return args;
+    }
+    return [nodeLexeme, ...args];
+}
+function collectHierarchyInformation(sourceFiles, options) {
+    const hierarchyList = [];
+    const typeChecker = options.program.getTypeChecker();
+    const visit = (node, sourceFile) => {
+        if (!node) {
+            return;
+        }
+        if (typescript_1.default.isInterfaceDeclaration(node)) {
+            const interfaceName = node.name?.getText(sourceFile) ?? '';
+            const baseTypes = node.heritageClauses?.flatMap(clause => clause.types
+                .map(type => type.getText(sourceFile) ?? '')
+                .map(dropGenericsFromType)) ?? [];
+            const generics = node.typeParameters?.map(param => param.getText(sourceFile) ?? '') || [];
+            hierarchyList.push({
+                name: dropGenericsFromType(interfaceName),
+                node,
+                kind: 'interface',
+                extends: baseTypes,
+                generics,
+                comments: getTextualComments(node),
+                filePath: sourceFile.fileName,
+                lineNumber: getStartLine(node, sourceFile),
+                properties: node.members.map(member => {
+                    const name = member.name?.getText(sourceFile) ?? '';
+                    return `${name}${(0, mermaid_1.escapeMarkdown)(': ' + getType(member, typeChecker))}`;
+                }),
+            });
+        }
+        else if (typescript_1.default.isTypeAliasDeclaration(node)) {
+            const typeName = node.name?.getText(sourceFile) ?? '';
+            let baseTypes = [];
+            if (typescript_1.default.isIntersectionTypeNode(node.type) || typescript_1.default.isUnionTypeNode(node.type)) {
+                baseTypes = node.type.types
+                    .filter(typeNode => typescript_1.default.isTypeReferenceNode(typeNode))
+                    .flatMap(typeName => followTypeReference(typeName, sourceFile))
+                    .map(dropGenericsFromType);
+            }
+            else if (typescript_1.default.isTypeReferenceNode(node.type)) {
+                baseTypes = [...followTypeReference(node.type, sourceFile)];
+            }
+            const generics = node.typeParameters?.map(param => param.getText(sourceFile) ?? '') ?? [];
+            hierarchyList.push({
+                name: dropGenericsFromType(typeName),
+                node,
+                kind: 'type',
+                extends: baseTypes,
+                comments: getTextualComments(node),
+                generics,
+                filePath: sourceFile.fileName,
+                lineNumber: getStartLine(node, sourceFile),
+            });
+        }
+        else if (typescript_1.default.isEnumDeclaration(node)) {
+            const enumName = node.name?.getText(sourceFile) ?? '';
+            hierarchyList.push({
+                name: enumName,
+                node,
+                kind: 'enum',
+                extends: [],
+                comments: getTextualComments(node),
+                generics: [],
+                filePath: sourceFile.fileName,
+                lineNumber: getStartLine(node, sourceFile),
+                properties: node.members.map(member => {
+                    const name = member.name?.getText(sourceFile) ?? '';
+                    return `${name}${(0, mermaid_1.escapeMarkdown)(': ' + getType(member, typeChecker))}`;
+                })
+            });
+        }
+        typescript_1.default.forEachChild(node, child => visit(child, sourceFile));
+    };
+    sourceFiles.forEach(sourceFile => {
+        visit(sourceFile, sourceFile);
+    });
+    return hierarchyList;
+}
+function getTypePathLink({ filePath, lineNumber }, prefix = doc_files_1.RemoteFlowrFilePathBaseRef) {
+    const fromSource = filePath.replace(/^.*\/src\//, 'src/');
+    return `${prefix}/${fromSource}#L${lineNumber}`;
+}
+function generateMermaidClassDiagram(hierarchyList, rootName, options, visited = new Set()) {
+    const collect = { nodeLines: [], edgeLines: [] };
+    if (visited.has(rootName)) {
+        return collect;
+    } // Prevent circular references
+    visited.add(rootName);
+    const node = hierarchyList.find(h => h.name === rootName);
+    if (!node) {
+        return collect;
+    }
+    const genericPart = node.generics.length > 0 ? `~${node.generics.join(', ')}~` : '';
+    collect.nodeLines.push(`class ${node.name}${genericPart}`);
+    collect.nodeLines.push(`    <<${node.kind}>> ${node.name}`);
+    if (node.kind === 'type') {
+        collect.nodeLines.push(`style ${node.name} opacity:.35,fill:#FAFAFA`);
+    }
+    const writtenProperties = new Set();
+    if (node.properties) {
+        for (const property of node.properties) {
+            collect.nodeLines.push(`    ${node.name} : ${property}`);
+            writtenProperties.add(property);
+        }
+    }
+    collect.nodeLines.push(`click ${node.name} href "${getTypePathLink(node)}" "${(0, mermaid_1.escapeMarkdown)(node.comments?.join('; ').replace(/\n/g, ' ') ?? '')}"`);
+    if (node.extends.length > 0) {
+        for (const baseType of node.extends) {
+            if (options.inlineTypes?.includes(baseType)) {
+                const info = hierarchyList.find(h => h.name === baseType);
+                for (const property of info?.properties ?? []) {
+                    if (!writtenProperties.has(property)) {
+                        collect.nodeLines.push(`    ${node.name} : ${property} [from ${baseType}]`);
+                        writtenProperties.add(property);
+                    }
+                }
+            }
+            else {
+                if (node.kind === 'type' || hierarchyList.find(h => h.name === baseType)?.kind === 'type') {
+                    collect.edgeLines.push(`${baseType} .. ${node.name}`);
+                }
+                else {
+                    collect.edgeLines.push(`${baseType} <|-- ${node.name}`);
+                }
+                const { nodeLines, edgeLines } = generateMermaidClassDiagram(hierarchyList, baseType, options, visited);
+                collect.nodeLines.push(...nodeLines);
+                collect.edgeLines.push(...edgeLines);
+            }
+        }
+    }
+    return collect;
+}
+function visualizeMermaidClassDiagram(hierarchyList, options) {
+    const { nodeLines, edgeLines } = generateMermaidClassDiagram(hierarchyList, options.typeName, options);
+    return nodeLines.length === 0 && edgeLines.length === 0 ? '' : `
+classDiagram
+direction RL
+${nodeLines.join('\n')}
+${edgeLines.join('\n')}
+`;
+}
+function getTypesFromFileAsMermaid(fileNames, options) {
+    const { files, program } = getSourceFiles(fileNames);
+    (0, assert_1.guard)(files.length > 0, () => `No source files found for ${JSON.stringify(fileNames)}`);
+    const withProgram = { ...options, program };
+    const hierarchyList = collectHierarchyInformation(files, withProgram);
+    return {
+        text: visualizeMermaidClassDiagram(hierarchyList, withProgram),
+        info: hierarchyList,
+        program
+    };
+}
+function getTypesFromFolderAsMermaid(options) {
+    (0, assert_1.guard)(options.rootFolder !== undefined || options.files !== undefined, 'Either rootFolder or files must be provided');
+    const files = [...options.files ?? []];
+    if (options.rootFolder) {
+        for (const fileBuff of fs_1.default.readdirSync(options.rootFolder, { recursive: true })) {
+            const file = fileBuff.toString();
+            if (file.endsWith('.ts')) {
+                files.push(path_1.default.join(options.rootFolder, file));
+            }
+        }
+    }
+    return getTypesFromFileAsMermaid(files, options);
+}
+function implSnippet(node, program, nesting = 0) {
+    (0, assert_1.guard)(node !== undefined, 'Node must be defined => invalid change of type name?');
+    const indent = ' '.repeat(nesting * 2);
+    const bold = node.kind === 'interface' || node.kind === 'enum' ? '**' : '';
+    const sep = node.comments ? '  \n' : '\n';
+    let text = node.comments?.join('\n') ?? '';
+    const code = node.node.getText(program.getSourceFile(node.node.getSourceFile().fileName));
+    text += `\n<details><summary style="color:gray">Defined at <a href="${getTypePathLink(node)}">${getTypePathLink(node, '.')}</a></summary>\n\n${(0, doc_code_1.codeBlock)('ts', code)}\n\n</details>\n`;
+    return `${indent} * ${bold}[${node.name}](${getTypePathLink(node)})${bold} ${sep}${indent}   ${text.replaceAll('\t', '    ').split(/\n/g).join(`\n${indent}   `)}`;
+}
+exports.mermaidHide = ['Leaf', 'Location', 'Namespace', 'Base', 'WithChildren', 'Partial', 'RAccessBase'];
+function printHierarchy({ program, hierarchy, root, collapseFromNesting = 1, initialNesting = 0, maxDepth = 20 }) {
+    if (initialNesting > maxDepth) {
+        return '';
+    }
+    const node = hierarchy.find(e => e.name === root);
+    if (!node) {
+        return '';
+    }
+    const thisLine = implSnippet(node, program, initialNesting);
+    const result = [];
+    for (const baseType of node.extends) {
+        if (exports.mermaidHide.includes(baseType)) {
+            continue;
+        }
+        const res = printHierarchy({ program, hierarchy, root: baseType, collapseFromNesting, initialNesting: initialNesting + 1, maxDepth });
+        result.push(res);
+    }
+    const out = result.join('\n');
+    if (initialNesting === collapseFromNesting - 1) {
+        return thisLine + (out ? (0, doc_structure_1.details)(`View more (${node.extends.join(', ')})`, out, { prefixInit: ' '.repeat(2 * (collapseFromNesting + 1)) }) : '');
+    }
+    else {
+        return thisLine + (out ? '\n' + out : '');
+    }
+}
+//# sourceMappingURL=doc-types.js.map

package/{r-bridge/data/print.js → documentation/print-capabilities-markdown.js}

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const data_1 = require("./data");
+const data_1 = require("../r-bridge/data/data");
+const version_1 = require("../util/version");
+const log_1 = require("../../test/functionality/_helper/log");
 const supportedSymbolMap = new Map([
     ['not', ':red_circle:'],
     ['partially', ':large_orange_diamond:'],
@@ -36,7 +38,8 @@ function printAsMarkdown(capabilities, depth = 0, lines = []) {
 }
 function getPreamble() {
     const currentDateAndTime = new Date().toISOString().replace('T', ', ').replace(/\.\d+Z$/, ' UTC');
-    return `_This document was generated automatically from '${module.filename}' on ${currentDateAndTime} summarizig flowR's current capabilities_
+    const shortenFilename = module.filename.replace(/^.*src\//, 'src/');
+    return `_This document was generated from '${shortenFilename}' on ${currentDateAndTime} summarizig flowR's current capabilities (v${(0, version_1.flowrVersion)().format()})._
 
 The code-font behind each capability name is a link to the capability's id. This id can be used to reference the capability in a labeled test within flowR.
 Besides, we use colored bullets like this:
@@ -51,8 +54,9 @@ Besides, we use colored bullets like this:
 
 `;
 }
-/** if we run this script, we want a markdown representation of the capabilities */
+/** if we run this script, we want a Markdown representation of the capabilities */
 if (require.main === module) {
+    (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
     console.log(getPreamble() + printAsMarkdown(data_1.flowrCapabilities.capabilities));
 }
-//# sourceMappingURL=print.js.map
+//# sourceMappingURL=print-capabilities-markdown.js.map

package/documentation/print-dataflow-graph-wiki.d.ts

@@ -0,0 +1 @@
+export {};