@eagleoutice/flowr 2.1.1 → 2.1.3

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RegisteredQueries = void 0;
+exports.asciiSummaryOfQueryResult = asciiSummaryOfQueryResult;
 exports.showQuery = showQuery;
 exports.registerQueryDocumentation = registerQueryDocumentation;
 exports.tocForQueryType = tocForQueryType;
@@ -9,12 +10,159 @@ const query_1 = require("../../queries/query");
 const pipeline_executor_1 = require("../../core/pipeline-executor");
 const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
 const retriever_1 = require("../../r-bridge/retriever");
-const doc_ms_1 = require("./doc-ms");
 const json_1 = require("../../util/json");
 const ansi_1 = require("../../util/ansi");
-const repl_query_1 = require("../../cli/repl/commands/repl-query");
 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/time");
+const built_in_1 = require("../../dataflow/environments/built-in");
+const dfg_1 = require("../../util/mermaid/dfg");
+const ast_1 = require("../../util/mermaid/ast");
+const doc_hover_over_1 = require("./doc-hover-over");
+function nodeString(id, formatter, processed) {
+    if (id === built_in_1.BuiltIn) {
+        return (0, ansi_1.italic)('built-in', formatter);
+    }
+    const node = processed.normalize.idMap.get(id);
+    if (node === undefined) {
+        return `UNKNOWN: ${id}`;
+    }
+    return `${(0, ansi_1.italic)('`' + (node.lexeme ?? node.info.fullLexeme ?? 'UNKNOWN') + '`', formatter)} (L.${node.location?.[0]})`;
+}
+function asciiCallContextSubHit(formatter, results, processed) {
+    const result = [];
+    for (const { id, calls = [], linkedIds = [], aliasRoots = [] } of results) {
+        const node = processed.normalize.idMap.get(id);
+        if (node === undefined) {
+            result.push(` ${(0, ansi_1.bold)('UNKNOWN: ' + JSON.stringify({ calls, linkedIds }))}`);
+            continue;
+        }
+        let line = nodeString(id, formatter, processed);
+        if (calls.length > 0) {
+            line += ` with ${calls.length} call${calls.length > 1 ? 's' : ''} (${calls.map(c => nodeString(c, formatter, processed)).join(', ')})`;
+        }
+        if (linkedIds.length > 0) {
+            line += ` with ${linkedIds.length} link${linkedIds.length > 1 ? 's' : ''} (${linkedIds.map(c => nodeString(c, formatter, processed)).join(', ')})`;
+        }
+        if (aliasRoots.length > 0) {
+            line += ` with ${aliasRoots.length} alias root${aliasRoots.length > 1 ? 's' : ''} (${aliasRoots.map(c => nodeString(c, formatter, processed)).join(', ')})`;
+        }
+        result.push(line);
+    }
+    return result.join(', ');
+}
+function asciiCallContext(formatter, results, processed) {
+    /* traverse over 'kinds' and within them 'subkinds' */
+    const result = [];
+    for (const [kind, { subkinds }] of Object.entries(results['kinds'])) {
+        result.push(`   ╰ ${(0, ansi_1.bold)(kind, formatter)}`);
+        for (const [subkind, values] of Object.entries(subkinds)) {
+            result.push(`     ╰ ${(0, ansi_1.bold)(subkind, formatter)}: ${asciiCallContextSubHit(formatter, values, processed)}`);
+        }
+    }
+    return result.join('\n');
+}
+function summarizeIdsIfTooLong(ids) {
+    const naive = ids.join(', ');
+    if (naive.length <= 20) {
+        return naive;
+    }
+    let acc = '';
+    let i = 0;
+    while (acc.length <= 20) {
+        acc += ids[i++] + ', ';
+    }
+    if (i < ids.length) {
+        acc += '... (see JSON below)';
+    }
+    return (0, doc_hover_over_1.textWithTooltip)(acc, JSON.stringify(ids));
+}
+function asciiSummaryOfQueryResult(formatter, totalInMs, results, processed) {
+    const result = [];
+    for (const [query, queryResults] of Object.entries(results)) {
+        if (query === '.meta') {
+            continue;
+        }
+        if (query === 'call-context') {
+            const out = queryResults;
+            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
+            result.push(asciiCallContext(formatter, out, processed));
+            continue;
+        }
+        else if (query === 'dataflow') {
+            const out = queryResults;
+            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
+            result.push(`   ╰ [Dataflow Graph](${(0, dfg_1.graphToMermaidUrl)(out.graph)})`);
+            continue;
+        }
+        else if (query === 'id-map') {
+            const out = queryResults;
+            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
+            result.push(`   ╰ Id List: {${summarizeIdsIfTooLong([...out.idMap.keys()])}}`);
+            continue;
+        }
+        else if (query === 'normalized-ast') {
+            const out = queryResults;
+            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
+            result.push(`   ╰ [Normalized AST](${(0, ast_1.normalizedAstToMermaidUrl)(out.normalized.ast)})`);
+            continue;
+        }
+        else if (query === 'static-slice') {
+            const out = queryResults;
+            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
+            for (const [fingerprint, obj] of Object.entries(out.results)) {
+                const { criteria, noMagicComments, noReconstruction } = JSON.parse(fingerprint);
+                const addons = [];
+                if (noReconstruction) {
+                    addons.push('no reconstruction');
+                }
+                if (noMagicComments) {
+                    addons.push('no magic comments');
+                }
+                result.push(`   ╰ Slice for {${criteria.join(', ')}} ${addons.join(', ')}`);
+                if ('reconstruct' in obj) {
+                    result.push('     ╰ Code (newline as <code>&#92;n</code>): <code>' + obj.reconstruct.code.split('\n').join('\\n') + '</code>');
+                }
+                else {
+                    result.push(`     ╰ Id List: {${summarizeIdsIfTooLong([...obj.slice.result])}}`);
+                }
+            }
+            continue;
+        }
+        else if (query === 'dataflow-cluster') {
+            const out = queryResults;
+            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${out['.meta'].timing.toFixed(0)}ms)`);
+            result.push(`   ╰ Found ${out.clusters.length} cluster${out.clusters.length === 1 ? '' : 's'}`);
+            for (const cluster of out.clusters) {
+                const unknownSideEffects = cluster.hasUnknownSideEffects ? '(has unknown side effect)' : '';
+                result.push(`      ╰ ${unknownSideEffects} {${summarizeIdsIfTooLong(cluster.members)}} ([marked](${(0, dfg_1.graphToMermaidUrl)(processed.dataflow.graph, false, new Set(cluster.members))}))`);
+            }
+            continue;
+        }
+        else if (query === 'lineage') {
+            const out = queryResults;
+            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
+            for (const [criteria, lineage] of Object.entries(out.lineages)) {
+                result.push(`   ╰ ${criteria}: {${summarizeIdsIfTooLong([...lineage])}}`);
+            }
+            continue;
+        }
+        result.push(`Query: ${(0, ansi_1.bold)(query, formatter)}`);
+        let timing = -1;
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        for (const [key, value] of Object.entries(queryResults)) {
+            if (key === '.meta') {
+                timing = value.timing;
+                continue;
+            }
+            result.push(` ╰ ${key}: ${JSON.stringify(value)}`);
+        }
+        result.push(`  - Took ${(0, time_1.printAsMs)(timing, 0)}`);
+    }
+    result.push((0, ansi_1.italic)(`All queries together required ≈${(0, time_1.printAsMs)(results['.meta'].timing, 0)} (1ms accuracy, total ${(0, time_1.printAsMs)(totalInMs, 0)})`, formatter));
+    return formatter.format(result.join('\n'));
+}
 async function showQuery(shell, code, queries, { showCode, collapseResult } = {}) {
     const now = performance.now();
     const analysis = await new pipeline_executor_1.PipelineExecutor(default_pipelines_1.DEFAULT_DATAFLOW_PIPELINE, {
@@ -24,9 +172,8 @@ async function showQuery(shell, code, queries, { showCode, collapseResult } = {}
     const results = (0, query_1.executeQueries)({ graph: analysis.dataflow.graph, ast: analysis.normalize }, queries);
     const duration = performance.now() - now;
     const metaInfo = `
-The analysis required _${(0, doc_ms_1.printAsMs)(duration)}_ (including parsing and normalization and the query) within the generation environment.
+The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parsing and normalization and the query) within the generation environment.
 	`.trim();
-    const resultAsString = JSON.stringify(results, json_1.jsonReplacer, 2);
     return `
 
 \`\`\`json
@@ -37,7 +184,7 @@ ${collapseResult ? ' <details> <summary style="color:gray">Show Results</summary
 
 _Results (prettified and summarized):_
 
-${(0, repl_query_1.asciiSummaryOfQueryResult)(ansi_1.markdownFormatter, duration, results, analysis)}
+${asciiSummaryOfQueryResult(ansi_1.markdownFormatter, duration, results, analysis)}
 
 <details> <summary style="color:gray">Show Detailed Results as Json</summary>
 
@@ -46,9 +193,7 @@ ${metaInfo}
 In general, the JSON contains the Ids of the nodes in question as they are present in the normalized AST or the dataflow graph of flowR.
 Please consult the [Interface](${doc_files_1.FlowrWikiBaseRef}/Interface) wiki page for more information on how to get those.
 
-\`\`\`json
-${resultAsString}
-\`\`\`
+${(0, doc_code_1.jsonWithLimit)(results)}
 
 </details>
 
@@ -79,7 +224,7 @@ function linkify(name) {
     return name.toLowerCase().replace(/ /g, '-');
 }
 function tocForQueryType(type) {
-    const queries = exports.RegisteredQueries[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}`);

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

@@ -9,8 +9,8 @@ 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 time_1 = require("../../util/time");
 const messages = [];
 function documentServerMessage(description) {
     messages.push(description);
@@ -29,7 +29,6 @@ async function inServerContext(shell, fn) {
 }
 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' : ''}> 
@@ -38,8 +37,7 @@ function explainMsg(msg, type, desc = '', open = false) {
 
 ${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)}
+${(0, doc_code_1.jsonWithLimit)(msg)}
 
 </details>
 </li>
@@ -102,7 +100,7 @@ The following lists all messages that were sent and received in case you want to
 
 ${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).
+The complete round-trip took ${(0, time_1.printAsMs)(end - start)} (including time required to validate the messages, start, and stop the internal mock server).
 
 </details>
 `;

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

@@ -37,14 +37,19 @@ function dropGenericsFromType(type) {
     return type;
 }
 function removeCommentSymbols(comment) {
-    return comment.replace(/^\/\*\*?/, '').replace(/\*\/$/, '').replace(/^\s*\*/, '').trim();
+    return comment
+        // remove '/** \n * \n */...
+        .replace(/^\/\*\*?/gm, '').replace(/^\s*\*\s*/gm, '').replace(/\*\/$/gm, '').replace(/^\s*\*/gm, '')
+        /* replace {@key foo|bar} with `bar` and {@key foo} with `foo` */
+        .replace(/\{@[a-zA-Z]+ ([^}]+\|)?(?<name>[^}]+)}/gm, '<code>$<name></code>')
+        .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);
+            out.push(removeCommentSymbols(comment));
         }
         else if (comment !== undefined) {
             for (const c of comment) {
@@ -62,6 +67,7 @@ function getType(node, typeChecker) {
     const tryDirect = typeChecker.getTypeAtLocation(node);
     return tryDirect ? typeChecker.typeToString(tryDirect) : 'unknown';
 }
+const defaultSkip = ['Pick', 'Partial', 'Required', 'Readonly', 'Omit', 'DeepPartial', 'DeepReadonly', 'DeepWritable', 'StrictOmit'];
 function followTypeReference(type, sourceFile) {
     const node = type.typeName;
     if (typescript_1.default.isQualifiedName(node)) {
@@ -69,10 +75,11 @@ function followTypeReference(type, 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;
+    const baseLexeme = type.getText(sourceFile) ?? '';
+    if (defaultSkip.map(s => nodeLexeme.startsWith(s))) {
+        return [baseLexeme, ...args];
     }
-    return [nodeLexeme, ...args];
+    return [nodeLexeme, baseLexeme, ...args];
 }
 function collectHierarchyInformation(sourceFiles, options) {
     const hierarchyList = [];
@@ -112,7 +119,7 @@ function collectHierarchyInformation(sourceFiles, options) {
                     .map(dropGenericsFromType);
             }
             else if (typescript_1.default.isTypeReferenceNode(node.type)) {
-                baseTypes = [...followTypeReference(node.type, sourceFile)];
+                baseTypes = [...followTypeReference(node.type, sourceFile)].map(dropGenericsFromType);
             }
             const generics = node.typeParameters?.map(param => param.getText(sourceFile) ?? '') ?? [];
             hierarchyList.push({
@@ -129,7 +136,7 @@ function collectHierarchyInformation(sourceFiles, options) {
         else if (typescript_1.default.isEnumDeclaration(node)) {
             const enumName = node.name?.getText(sourceFile) ?? '';
             hierarchyList.push({
-                name: enumName,
+                name: dropGenericsFromType(enumName),
                 node,
                 kind: 'enum',
                 extends: [],
@@ -178,9 +185,10 @@ function generateMermaidClassDiagram(hierarchyList, rootName, options, visited =
         }
     }
     collect.nodeLines.push(`click ${node.name} href "${getTypePathLink(node)}" "${(0, mermaid_1.escapeMarkdown)(node.comments?.join('; ').replace(/\n/g, ' ') ?? '')}"`);
+    const inline = [...options.inlineTypes ?? [], ...defaultSkip];
     if (node.extends.length > 0) {
         for (const baseType of node.extends) {
-            if (options.inlineTypes?.includes(baseType)) {
+            if (inline.includes(baseType)) {
                 const info = hierarchyList.find(h => h.name === baseType);
                 for (const property of info?.properties ?? []) {
                     if (!writtenProperties.has(property)) {
@@ -191,10 +199,10 @@ function generateMermaidClassDiagram(hierarchyList, rootName, options, visited =
             }
             else {
                 if (node.kind === 'type' || hierarchyList.find(h => h.name === baseType)?.kind === 'type') {
-                    collect.edgeLines.push(`${baseType} .. ${node.name}`);
+                    collect.edgeLines.push(`${dropGenericsFromType(baseType)} .. ${node.name}`);
                 }
                 else {
-                    collect.edgeLines.push(`${baseType} <|-- ${node.name}`);
+                    collect.edgeLines.push(`${dropGenericsFromType(baseType)} <|-- ${node.name}`);
                 }
                 const { nodeLines, edgeLines } = generateMermaidClassDiagram(hierarchyList, baseType, options, visited);
                 collect.nodeLines.push(...nodeLines);
@@ -243,7 +251,7 @@ function implSnippet(node, program, nesting = 0) {
     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));
+    const code = node.node.getFullText(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}   `)}`;
 }

package/documentation/print-dataflow-graph-wiki.js

@@ -615,6 +615,13 @@ What to do if you encounter this vertex?
 
 This depends on your analysis. To handle many real-world sources correctly you are probably fine with just ignoring it.
 Yet, you may choose to follow these references for other queries. For now, _flowR's_ support for non-standard evaluation is limited.
+
+Besides the obvious quotation there are other cases in which _flowR_ may choose to create a ${linkEdgeName(edge_1.EdgeType.NonStandardEvaluation)} edge, there are
+some that may appear to be counter-intuitive. For example, a for-loop body, as in the following example.
+
+${(0, doc_structure_1.details)('Example: For-Loop Body', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'for(i in v) b', { mark: new Set([2, '4->2']) }))}	
+${(0, doc_structure_1.details)('Example: While-Loop Body', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'while(TRUE) b', { mark: new Set([1, '3->1']) }))}	
+
 				`
             })}
 `,
@@ -674,7 +681,9 @@ Additionally, you may be interested in the set of [Unknown Side Effects](#unknow
 > [!TIP]
 > If you want to investigate the dataflow graph,
 > you can either use the [Visual Studio Code extension](${doc_files_1.FlowrGithubBaseRef}/vscode-flowr) or the ${(0, doc_cli_option_1.getReplCommand)('dataflow*')}
-> command in the REPL (see the [Interface wiki page](${doc_files_1.FlowrWikiBaseRef}/Interface) for more information).
+> command in the REPL (see the [Interface wiki page](${doc_files_1.FlowrWikiBaseRef}/Interface) for more information). When using _flowR_ as a library, you may use the functions in ${(0, doc_files_1.getFilePathMd)('../util/mermaid/dfg.ts')}.
+> 
+> If you receive a dataflow graph in its serialized form (e.g., by talking to a [_flowR_ server](${doc_files_1.FlowrWikiBaseRef}/Interface)), you can use \`${graph_1.DataflowGraph.name}::${graph_1.DataflowGraph.fromJson.name}\` to retrieve the graph from the JSON representation.
 
 ${await (0, doc_dfg_1.printDfGraphForCode)(shell, 'x <- 3\ny <- x + 1\ny')}
 

package/documentation/print-interface-wiki.js

@@ -19,7 +19,7 @@ const flowr_main_options_1 = require("../cli/flowr-main-options");
 const doc_issue_1 = require("./doc-util/doc-issue");
 const pipeline_executor_1 = require("../core/pipeline-executor");
 async function explainServer(shell) {
-    (0, doc_data_server_messages_1.documentAllMessages)();
+    (0, doc_data_server_messages_1.documentAllServerMessages)();
     return `
 As explained in the [Overview](${doc_files_1.FlowrWikiBaseRef}/Overview), you can simply run the [TCP](https://de.wikipedia.org/wiki/Transmission_Control_Protocol)&nbsp;server by adding the ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'server', true)} flag (and, due to the interactive mode, exit with the conventional <kbd>CTRL</kbd>+<kbd>C</kbd>).
 Currently, every connection is handled by the same underlying \`${shell_1.RShell.name}\` - so the server is not designed to handle many clients at a time.

package/documentation/print-normalized-ast-wiki.js

@@ -11,8 +11,8 @@ const doc_normalized_ast_1 = require("./doc-util/doc-normalized-ast");
 const doc_types_1 = require("./doc-util/doc-types");
 const path_1 = __importDefault(require("path"));
 const doc_files_1 = require("./doc-util/doc-files");
-const doc_ms_1 = require("./doc-util/doc-ms");
 const doc_cli_option_1 = require("./doc-util/doc-cli-option");
+const time_1 = require("../util/time");
 async function getText(shell) {
     const rversion = (await shell.usedRVersion())?.format() ?? 'unknown';
     const now = performance.now();
@@ -67,7 +67,7 @@ Grayed-out parts are used for structuring the AST, grouping together related nod
 
 ${(0, doc_code_1.codeBlock)('mermaid', types.text)}
 
-_The generation of the class diagram required ${(0, doc_ms_1.printAsMs)(elapsed)}._
+_The generation of the class diagram required ${(0, time_1.printAsMs)(elapsed)}._
 </details>
 
 Node types are controlled by the \`${'RType'}\` enum (see ${(0, doc_files_1.getFilePathMd)('../r-bridge/lang-4.x/ast/model/type.ts')}),