@eagleoutice/flowr 2.9.11 → 2.9.12

package/README.md

@@ -24,7 +24,7 @@ It offers a wide variety of features, for example:
     
     ```shell
     $ docker run -it --rm eagleoutice/flowr # or npm run flowr 
-    flowR repl using flowR v2.9.10, R grammar v14 (tree-sitter engine)
+    flowR repl using flowR v2.9.11, R grammar v14 (tree-sitter engine)
     R> :query @linter "read.csv(\"/root/x.txt\")"
     ```
     
@@ -35,11 +35,11 @@ It offers a wide variety of features, for example:
     ```text
     Query: linter (2 ms)
        ╰ Deprecated Functions (deprecated-functions):
-           ╰ Metadata: totalCalls: 0, totalFunctionDefinitions: 0, searchTimeMs: 0, processTimeMs: 0
+           ╰ Metadata: totalCalls: 0, totalFunctionDefinitions: 0, searchTimeMs: 1, processTimeMs: 0
        ╰ File Path Validity (file-path-validity):
            ╰ certain:
                ╰ Path `/root/x.txt` at 1.1-23
-           ╰ Metadata: totalReads: 1, totalUnknown: 0, totalWritesBeforeAlways: 0, totalValid: 0, searchTimeMs: 1, processTimeMs: 0
+           ╰ Metadata: totalReads: 1, totalUnknown: 0, totalWritesBeforeAlways: 0, totalValid: 0, searchTimeMs: 0, processTimeMs: 0
        ╰ Seeded Randomness (seeded-randomness):
            ╰ Metadata: consumerCalls: 0, callsWithFunctionProducers: 0, callsWithAssignmentProducers: 0, callsWithNonConstantProducers: 0, callsWithOtherBranchProducers: 0, searchTimeMs: 0, processTimeMs: 0
        ╰ Absolute Paths (absolute-file-paths):
@@ -58,7 +58,7 @@ It offers a wide variety of features, for example:
            ╰ Metadata: consideredNodes: 5, searchTimeMs: 0, processTimeMs: 0
        ╰ Useless Loops (useless-loop):
            ╰ Metadata: numOfUselessLoops: 0, searchTimeMs: 0, processTimeMs: 0
-    All queries together required ≈2 ms (1ms accuracy, total 3 ms)
+    All queries together required ≈2 ms (1ms accuracy, total 2 ms)
     ```
     
     
@@ -80,7 +80,7 @@ It offers a wide variety of features, for example:
     
     _Results (prettified and summarized):_
     
-    Query: **linter** (3 ms)\
+    Query: **linter** (2 ms)\
        ╰ **Deprecated Functions** (deprecated-functions):\
     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ _Metadata_: <code>totalCalls: 0, totalFunctionDefinitions: 0, searchTimeMs: 1, processTimeMs: 0</code>\
     &nbsp;&nbsp;&nbsp;╰ **File Path Validity** (file-path-validity):\
@@ -88,11 +88,11 @@ It offers a wide variety of features, for example:
     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ Path `/root/x.txt` at 1.1-23\
     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ _Metadata_: <code>totalReads: 1, totalUnknown: 0, totalWritesBeforeAlways: 0, totalValid: 0, searchTimeMs: 0, processTimeMs: 0</code>\
     &nbsp;&nbsp;&nbsp;╰ **Seeded Randomness** (seeded-randomness):\
-    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ _Metadata_: <code>consumerCalls: 0, callsWithFunctionProducers: 0, callsWithAssignmentProducers: 0, callsWithNonConstantProducers: 0, callsWithOtherBranchProducers: 0, searchTimeMs: 1, processTimeMs: 0</code>\
+    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ _Metadata_: <code>consumerCalls: 0, callsWithFunctionProducers: 0, callsWithAssignmentProducers: 0, callsWithNonConstantProducers: 0, callsWithOtherBranchProducers: 0, searchTimeMs: 0, processTimeMs: 0</code>\
     &nbsp;&nbsp;&nbsp;╰ **Absolute Paths** (absolute-file-paths):\
     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ certain:\
     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ Path `/root/x.txt` at 1.1-23\
-    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ _Metadata_: <code>totalConsidered: 1, totalUnknown: 0, searchTimeMs: 0, processTimeMs: 0</code>\
+    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ _Metadata_: <code>totalConsidered: 1, totalUnknown: 0, searchTimeMs: 1, processTimeMs: 0</code>\
     &nbsp;&nbsp;&nbsp;╰ **Unused Definitions** (unused-definitions):\
     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ _Metadata_: <code>totalConsidered: 0, searchTimeMs: 0, processTimeMs: 0</code>\
     &nbsp;&nbsp;&nbsp;╰ **Naming Convention** (naming-convention):\
@@ -102,14 +102,14 @@ It offers a wide variety of features, for example:
     &nbsp;&nbsp;&nbsp;╰ **Dataframe Access Validation** (dataframe-access-validation):\
     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ _Metadata_: <code>numOperations: 0, numAccesses: 0, totalAccessed: 0, searchTimeMs: 0, processTimeMs: 0</code>\
     &nbsp;&nbsp;&nbsp;╰ **Dead Code** (dead-code):\
-    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ _Metadata_: <code>consideredNodes: 5, searchTimeMs: 0, processTimeMs: 1</code>\
+    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ _Metadata_: <code>consideredNodes: 5, searchTimeMs: 0, processTimeMs: 0</code>\
     &nbsp;&nbsp;&nbsp;╰ **Useless Loops** (useless-loop):\
     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;╰ _Metadata_: <code>numOfUselessLoops: 0, searchTimeMs: 0, processTimeMs: 0</code>\
-    _All queries together required ≈3 ms (1ms accuracy, total 3 ms)_
+    _All queries together required ≈2 ms (1ms accuracy, total 2 ms)_
     
     <details> <summary style="color:gray">Show Detailed Results as Json</summary>
     
-    The analysis required _2.5 ms_ (including parsing and normalization and the query) within the generation environment.
+    The analysis required _2.2 ms_ (including parsing and normalization and the query) within the generation environment.
     
     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](https://github.com/flowr-analysis/flowr/wiki/Interface) wiki page for more information on how to get those.
@@ -161,7 +161,7 @@ It offers a wide variety of features, for example:
               "callsWithAssignmentProducers": 0,
               "callsWithNonConstantProducers": 0,
               "callsWithOtherBranchProducers": 0,
-              "searchTimeMs": 1,
+              "searchTimeMs": 0,
               "processTimeMs": 0
             }
           },
@@ -181,7 +181,7 @@ It offers a wide variety of features, for example:
             ".meta": {
               "totalConsidered": 1,
               "totalUnknown": 0,
-              "searchTimeMs": 0,
+              "searchTimeMs": 1,
               "processTimeMs": 0
             }
           },
@@ -226,7 +226,7 @@ It offers a wide variety of features, for example:
             ".meta": {
               "consideredNodes": 5,
               "searchTimeMs": 0,
-              "processTimeMs": 1
+              "processTimeMs": 0
             }
           },
           "useless-loop": {
@@ -239,11 +239,11 @@ It offers a wide variety of features, for example:
           }
         },
         ".meta": {
-          "timing": 3
+          "timing": 2
         }
       },
       ".meta": {
-        "timing": 3
+        "timing": 2
       }
     }
     ```
@@ -308,7 +308,7 @@ It offers a wide variety of features, for example:
     
     ```shell
     $ docker run -it --rm eagleoutice/flowr # or npm run flowr 
-    flowR repl using flowR v2.9.10, R grammar v14 (tree-sitter engine)
+    flowR repl using flowR v2.9.11, R grammar v14 (tree-sitter engine)
     R> :query @static-slice (11@sum) file://test/testfiles/example.R
     ```
     
@@ -322,7 +322,7 @@ It offers a wide variety of features, for example:
     N <- 10
     for(i in 1:(N-1)) sum <- sum + i + w
     sum
-    All queries together required ≈2 ms (1ms accuracy, total 3 ms)
+    All queries together required ≈2 ms (1ms accuracy, total 2 ms)
     ```
     
     
@@ -356,7 +356,7 @@ It offers a wide variety of features, for example:
          
 
 * 🚀 **fast call-graph, data-, and control-flow graphs**\
-  Within just [<i><span title="This measurement is automatically fetched from the latest benchmark!">104.5 ms</span></i> (as of Feb 13, 2026)](https://flowr-analysis.github.io/flowr/wiki/stats/benchmark), 
+  Within just [<i><span title="This measurement is automatically fetched from the latest benchmark!">98.9 ms</span></i> (as of Feb 18, 2026)](https://flowr-analysis.github.io/flowr/wiki/stats/benchmark), 
   _flowR_ can analyze the data- and control-flow of the average real-world R&nbsp;script. See the [benchmarks](https://flowr-analysis.github.io/flowr/wiki/stats/benchmark) for more information,
   and consult the [wiki pages](https://github.com/flowr-analysis/flowr/wiki/wiki/dataflow-graph) for more details on the [dataflow graphs](https://github.com/flowr-analysis/flowr/wiki/wiki/dataflow-graph) as well as [call graphs](https://github.com/flowr-analysis/flowr/wiki/wiki/dataflow-graph#perspectives-cg).
 
@@ -392,7 +392,7 @@ It offers a wide variety of features, for example:
     
     ```shell
     $ docker run -it --rm eagleoutice/flowr # or npm run flowr 
-    flowR repl using flowR v2.9.10, R grammar v14 (tree-sitter engine)
+    flowR repl using flowR v2.9.11, R grammar v14 (tree-sitter engine)
     R> :dataflow* test/testfiles/example.R
     ```
     
@@ -700,7 +700,7 @@ It offers a wide variety of features, for example:
     ```
     
     	
-    (The analysis required _2.2 ms_ (including parse and normalize, using the [tree-sitter](https://github.com/flowr-analysis/flowr/wiki/Engines) engine) within the generation environment.)
+    (The analysis required _1.6 ms_ (including parse and normalize, using the [tree-sitter](https://github.com/flowr-analysis/flowr/wiki/Engines) engine) within the generation environment.)
     
     
     

package/dataflow/cluster.js

@@ -30,18 +30,22 @@ function makeCluster(graph, from, notReached) {
     if (info.tag === vertex_1.VertexType.FunctionDefinition) {
         for (const { nodeId } of info.exitPoints) {
             if (notReached.delete(nodeId)) {
-                makeCluster(graph, nodeId, notReached).forEach(n => nodes.add(n));
+                for (const m of makeCluster(graph, nodeId, notReached)) {
+                    nodes.add(m);
+                }
             }
         }
     }
     // cluster adjacent edges
-    for (const [dest, e] of [...graph.outgoingEdges(from) ?? [], ...graph.ingoingEdges(from) ?? []]) {
-        // don't cluster for function content if it isn't returned
-        if (edge_1.DfEdge.doesNotIncludeType(e, edge_1.EdgeType.Returns) && info.onlyBuiltin && info.name === '{') {
-            continue;
-        }
-        if (notReached.delete(dest)) {
-            makeCluster(graph, dest, notReached).forEach(n => nodes.add(n));
+    for (const edges of [graph.outgoingEdges(from), graph.ingoingEdges(from)]) {
+        for (const [dest, e] of edges ?? []) {
+            // don't cluster for function content if it isn't returned
+            if (edge_1.DfEdge.doesNotIncludeType(e, edge_1.EdgeType.Returns) && info.onlyBuiltin && info.name === '{') {
+                continue;
+            }
+            if (notReached.delete(dest)) {
+                makeCluster(graph, dest, notReached).forEach(n => nodes.add(n));
+            }
         }
     }
     return nodes;

package/dataflow/graph/quads.js

@@ -10,13 +10,10 @@ const edge_1 = require("./edge");
  */
 function df2quads(graph, config) {
     return (0, quads_1.graph2quads)({
-        rootIds: [...graph.rootIds()],
-        vertices: graph.vertices(true)
-            .map(([id, v]) => ({
-            ...v,
-            id
-        })).toArray(),
-        edges: graph.edges().flatMap(([fromId, targets]) => [...targets].map(([toId, info]) => ({
+        rootIds: Array.from(graph.rootIds()),
+        vertices: Array.from(graph.vertices(true)
+            .map(([, v]) => v)),
+        edges: graph.edges().flatMap(([fromId, targets]) => Array.from(targets).map(([toId, info]) => ({
             from: fromId,
             to: toId,
             type: Array.from(edge_1.DfEdge.typesToNames(info)),

package/dataflow/internal/linker.js

@@ -395,18 +395,18 @@ function getAllLinkedFunctionDefinitions(functionDefinitionReadIds, dataflowGrap
             builtIns.add(cid);
             continue;
         }
-        const currentInfo = dataflowGraph.get(cid, true);
-        if (currentInfo === undefined) {
+        const vertex = dataflowGraph.getVertex(cid);
+        if (vertex === undefined) {
             continue;
         }
-        const [vertex, edges] = currentInfo;
         // Found a function definition
         if (vertex.subflow !== undefined) {
             result.add(vertex);
             continue;
         }
         let hasReturnEdge = false;
-        for (const [target, e] of edges) {
+        const outgoing = dataflowGraph.outgoingEdges(cid) ?? [];
+        for (const [target, e] of outgoing) {
             if (edge_1.DfEdge.includesType(e, edge_1.EdgeType.Returns)) {
                 hasReturnEdge = true;
                 if (!visited.has(target)) {
@@ -417,7 +417,7 @@ function getAllLinkedFunctionDefinitions(functionDefinitionReadIds, dataflowGrap
         if (vertex.tag === vertex_1.VertexType.FunctionCall || hasReturnEdge || (vertex.tag === vertex_1.VertexType.VariableDefinition && vertex.par)) {
             continue;
         }
-        for (const [target, e] of edges) {
+        for (const [target, e] of outgoing) {
             if (edge_1.DfEdge.includesType(e, LinkedFnFollowBits) && !visited.has(target)) {
                 potential.push(target);
             }

package/documentation/wiki-dataflow-graph.js

@@ -39,6 +39,10 @@ const flowr_analyzer_context_1 = require("../project/context/flowr-analyzer-cont
 const doc_maker_1 = require("./wiki-mk/doc-maker");
 const flowr_analyzer_1 = require("../project/flowr-analyzer");
 const built_in_1 = require("../dataflow/environments/built-in");
+const dfg_1 = require("../util/mermaid/dfg");
+const r_number_1 = require("../r-bridge/lang-4.x/ast/model/nodes/r-number");
+const model_1 = require("../r-bridge/lang-4.x/ast/model/model");
+const range_1 = require("../util/range");
 async function subExplanation(parser, { description, code, expectedSubgraph }) {
     expectedSubgraph = await (0, doc_dfg_1.verifyExpectedSubgraph)(parser, code, expectedSubgraph);
     const marks = [];
@@ -741,12 +745,14 @@ class WikiDataflowGraph extends doc_maker_1.DocMaker {
         super('wiki/Dataflow Graph.md', module.filename, 'dataflow graph');
     }
     async text({ ctx, treeSitter }) {
+        const introExampleCode = 'x <- 3\ny <- x + 1\ny';
         return `
-This page briefly summarizes flowR's dataflow graph, represented by the ${ctx.link(graph_1.DataflowGraph)} class within the code.
-In case you want to manually build such a graph (e.g., for testing), you can use the ${ctx.link(dataflowgraph_builder_1.DataflowGraphBuilder)}.
+This page briefly summarizes flowR's dataflow graph (${ctx.link(graph_1.DataflowGraph)}).
 If you are interested in which features we support and which features are still to be worked on, please refer to our ${ctx.linkPage('wiki/Capabilities')} page.
-In summary, we discuss the following topics:
+In case you want to manually build such a graph (e.g., for testing), you can use the ${ctx.link(dataflowgraph_builder_1.DataflowGraphBuilder)}.
+In summary, we discuss the following topics in this wiki page:
 
+- [Reading the Visualization](#reading-the-visualization)
 - [Vertices](#vertices)
 - [Edges](#edges)
 - [Control Dependencies](#control-dependencies)
@@ -756,37 +762,35 @@ In summary, we discuss the following topics:
     - [Call Graph Perspective](#perspectives-cg)
 - [Working with the Dataflow Graph](#dfg-working)
 
-Please be aware that the accompanied [dataflow information](#dataflow-information) (${ctx.link('DataflowInformation')}) returned by _flowR_ contains things besides the graph,
-like the entry and exit points of the subgraphs, and currently active references (see [below](#dataflow-information)).
-Additionally, you may be interested in the set of [Unknown Side Effects](#unknown-side-effects), marking calls which _flowR_ is unable to handle correctly.
-
-Potentially, you are interested in another perspective that flowR provides, the [control flow graph](${doc_files_1.FlowrWikiBaseRef}/Control%20Flow%20Graph), so please check the correpsonding
-wiki page if you are unsure.
+Please be aware that the accompanied [dataflow information](#dataflow-information) (${ctx.link('DataflowInformation')}) returned by _flowR_ 
+contains things besides the graph, like the entry and exit points of the subgraphs, and currently active references (see [below](#dataflow-information)).
+Additionally, you may be interested in the [Unknown Side Effects](#unknown-side-effects), marking calls which _flowR_ is unable to handle correctly.
 
 > [!TIP]
-> If you want to investigate the dataflow graph,
-> you can either use the [Visual Studio Code extension](${doc_files_1.FlowrVsCode}) or the ${ctx.replCmd('dataflow*')}
-> command in the REPL (see the ${ctx.linkPage('wiki/Interface', 'Interface wiki page')} for more information). 
-> There is also a simplified perspective available with ${ctx.replCmd('dataflowsimple*')} that does not show everything but is easier to read.
+> To investigate the dataflow graph,
+> you can either use the ${ctx.linkPage('flowr:vscode')} or the ${ctx.replCmd('dataflow*')}
+> command in the REPL (see the ${ctx.linkPage('wiki/Interface', 'Interface wiki page')}). 
+> There is also a simplified version available with ${ctx.replCmd('dataflowsimple*')} that does not show everything but is easier to read.
 > For small graphs, you can also use ${ctx.replCmd('dataflowascii')} to print the graph as ASCII art.
->
-> 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 ${ctx.linkM(graph_1.DataflowGraph, 'fromJson', { realNameWrapper: 'i', codeFont: true })} to retrieve the graph from the JSON representation.
+> 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 ${ctx.linkM(graph_1.DataflowGraph, 'fromJson', { realNameWrapper: 'i', codeFont: true })} to recover the graph object.
 >
 > Also, check out the [${doc_files_1.FlowrGithubGroupName}/sample-analyzer-df-diff](${doc_files_1.FlowrGithubBaseRef}/sample-analyzer-df-diff) repository for a complete example project creating and comparing dataflow graphs.
 
-${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'x <- 3\ny <- x + 1\ny')}
+To get started, let's look at the graph for the following code snippet:
+${(0, doc_code_1.codeBlock)('r', introExampleCode)}
 
+With this code, the corresponding dataflow graph looks like this:
 
-The above dataflow graph showcases the general gist. We define a dataflow graph as a directed graph G = (V, E), differentiating between ${(0, doc_data_dfg_util_1.getAllVertices)().length} types of vertices V and
-${(0, doc_data_dfg_util_1.getAllEdges)().length} types of edges E allowing each vertex to have a single, and each edge to have multiple distinct types.
+${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, introExampleCode, { showCode: false })}
+
+The above dataflow graph showcases the general gist. We define a dataflow graph as a directed graph G&nbsp;=&nbsp;(V,&nbsp;E), 
+differentiating between ${(0, doc_data_dfg_util_1.getAllVertices)().length} types of vertices&nbsp;V and
+${(0, doc_data_dfg_util_1.getAllEdges)().length} types of edges&nbsp;E allowing each vertex to have a single, and each edge to have multiple distinct types.
 Additionally, every node may have links to its [control dependencies](#control-dependencies) (which you may view as a ${(0, text_1.nth)((0, doc_data_dfg_util_1.getAllEdges)().length + 1)} edge type, 
 although they are explicitly no data dependency and relate to the ${ctx.linkPage('wiki/Control Flow Graph')}. 
 
-<details open>
-
-<summary>Vertex Types</summary>
+${(0, doc_structure_1.details)('Simplified Version of the graph', await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'x <- 3\ny <- x + 1\ny', { simplified: true, showCode: false }))}
 
 The following vertices types exist:
 
@@ -794,20 +798,13 @@ The following vertices types exist:
 
 ${(0, doc_structure_1.details)('Class Diagram', 'All boxes should link to their respective implementation:\n' + (0, doc_code_1.codeBlock)('mermaid', ctx.mermaid('DataflowGraphVertexInfo', { inlineTypes: ['MergeableRecord'] })))}
 
-</details>
-
-<details open>
-
-<summary>Edge Types</summary>
-
-The following edges types exist, internally we use bitmasks to represent multiple types in a compact form:
+The following edges types exist, internally we use bitmasks to represent multiple types in a compact form, so you 
+should use the ${ctx.link('DfEdge', { codeFont: false, realNameWrapper: 'i' }, { type: 'variable' })} object and its methods to work with them:
 
 1. ${(0, doc_data_dfg_util_1.getAllEdges)().map(([k, v], index) => `[\`${k}\` (${v})](#${index + 1}-${k.toLowerCase().replace(/\s/g, '-')}-edge)`).join('\n1. ')}
 
 ${(0, doc_structure_1.details)('Class Diagram', 'All boxes should link to their respective implementation:\n' + (0, doc_code_1.codeBlock)('mermaid', ctx.mermaid('EdgeType', { inlineTypes: ['MergeableRecord'] })))}
 
-</details>
-
 
 From an implementation perspective all of these types are represented by respective interfaces, see ${(0, doc_files_1.getFilePathMd)('../dataflow/graph/vertex.ts')} and ${(0, doc_files_1.getFilePathMd)('../dataflow/graph/edge.ts')}.
 
@@ -828,6 +825,64 @@ ${(0, doc_general_1.prefixLines)((0, doc_code_1.codeBlock)('ts', `const name = $
 > For argument wrappers you can access the dataflow information for their value. For dead code, however, flowR currently contains
 > some core heuristics that remove it which cannot be reversed easily. So please open [an issue](${doc_issue_1.NewIssueUrl}) if you encounter such a case and require the node to be present in the dataflow graph.
 
+${(0, doc_structure_1.section)('Reading the Visualizations', 2, 'reading-the-visualization')}
+
+Before we dive into the details of the different vertices and edges, let's briefly talk about how to read the visualizations.
+For this, let's have a look at a very simple graph, created for the number \`42\`:
+
+${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, '42', { showCode: false })}
+
+${(0, doc_structure_1.section)('Vertex Shape', 3, 'vtx-shape')}
+
+The _shape_ of the vertex tells you the type of the vertex in the dataflow graph using the following scheme (the types are 
+explained in more detail in the following sections):
+
+${(0, doc_code_1.codeBlock)('mermaid', 'flowchart TD\n' +
+            // use mermaidNodeBrackets to get open and closing bracket
+            Object.entries(vertex_1.VertexType)
+                .map(([k, v]) => {
+                const { open, close } = (0, dfg_1.mermaidNodeBrackets)(v);
+                return `   ${v}${open}${k}${close}`;
+            }).join('\n') +
+            // we add a subflow for the function definition
+            '\n    subgraph fbox ["function body"]\n   body((...))\n    end\n   fdef-->fbox')}
+
+${(0, doc_structure_1.section)('Syntactic Types', 3, 'vtx-synt-type')}
+
+Within the shape, in square brackets, you can find the syntactic type of the vertex
+which is linked to the node in the ${ctx.linkPage('wiki/Normalized AST')}.
+For more information on valid types and what to do with them, please refer to the ${ctx.linkPage('wiki/Normalized AST', 'normalized AST wiki page')}
+and the corresponding helper objects (e.g., ${ctx.link(r_number_1.RNumber, undefined, { type: 'variable' })}).
+
+${(0, doc_structure_1.section)('Lexeme', 3, 'vtx-lexeme')}
+
+Also in the first line, next to the [syntactic type](#vtx-synt-type), you can find the lexeme of the vertex (if it has one, e.g., for a variable definition or use).
+This usually represents the textual source string of the respective vertex, and is also linked to the ${ctx.linkPage('wiki/Normalized AST')}.
+You can access the lexeme too with ${ctx.linkO(model_1.RNode, 'lexeme')}.
+
+${(0, doc_structure_1.section)('Vertex Id', 3, 'vtx-id')}
+
+In the second line, you will usually find the id (in the form of a ${ctx.link(node_id_1.NodeId, undefined, { type: 'variable' })}) of the vertex,
+alongside its [control dependencies](#control-dependencies) if it has any. This id links the vertex to the respective node in the ${ctx.linkPage('wiki/Normalized AST')} (and all other perspectives created by flowR).
+To give you an example, have a look at the following graph:
+
+${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'if(u) a', { showCode: false, mark: new Set(['1']) })}
+With the _may_ prefix you can see that \`a\` has a [control dependency](#control-dependencies)
+on the \`if\`, which only triggers when the condition is \`true\` (as indicated by the \`+\` suffix).
+
+${(0, doc_structure_1.section)('Location', 3, 'vtx-location')}
+
+The third line indicates the compressed ${ctx.link(range_1.SourceRange)} of the vertex in the format \`startLine.startCharacter - endLine.endCharacter\`. If the range reads \`1.7\`, 
+this is short for \`1.7-1.7\`, likewise, \`1.7-9\` is short for \`1.7-1.9\`. So, \`1.7-9\` describes something starting
+in the first line at the seventh character and ending in the first line at the ninth character.
+
+${(0, doc_structure_1.section)('Arguments and Additional Information', 3, 'vtx-additional-info')}
+
+Some vertices (e.g., [function calls](#function-call-vertex)) have additional information, like the arguments of the call. 
+As you can see with the \`if\` example above alongside the [vertex id](#vtx-id),
+these vertices also have an additional line which lists the ids of the arguments in order to clear any ambiguity in case, for example,
+the mermaid graph layouting fumbles the order.
+
 ${(0, doc_structure_1.section)('Vertices', 2, 'vertices')}
 
 1. ${(0, doc_data_dfg_util_1.getAllVertices)().map(([k, v]) => `[\`${k}\`](#${v.toLowerCase().replaceAll(/\s/g, '-')}-vertex)`).join('\n1. ')}

package/documentation/wiki-engine.js

@@ -37,6 +37,19 @@ are exposed with some command line options (e.g., when using the docker image of
 - ${ctx.cliOption('flowr', 'engine.tree-sitter.tree-sitter-wasm-path', false)} pass the path to the wasm of tree-sitter (see [below](#tree-sitter))
 - ${ctx.cliOption('flowr', 'default-engine', false)} to set the default engine to use
 
+<a id="r-shell"></a>
+## Dealing with the R Shell Engine
+
+The ${ctx.link(shell_1.RShell)} engine is the original engine of flowR and is still available today.
+It provides a powerful interface to the R interpreter, allowing for complex interactions and the execution of R code.
+There are two interfaces available: 
+
+* The ${ctx.link(shell_1.RShell)} which is asynchronous and allows for non-blocking interactions with the R interpreter. This is the default engine.
+* The ${ctx.link(shell_executor_1.RShellExecutor)} which is synchronous and blocks the execution until the R code is executed. This can be useful for certain use cases where you want to ensure that the R code is executed before proceeding with the analysis.
+
+Please note, that these classes are available to you even if you do not use/enable the R shell engine.
+The selection and preparation of the engine just reflects what the flowR analysis will use. 
+
 <a id="tree-sitter"></a>
 ## Dealing with the Tree-Sitter Engine
 
@@ -59,6 +72,11 @@ you first must build the new wasm file. For this you have to:
 3. Pass the \`tree-sitter-r.wasm\` to flowR. 
 
 For tree-sitter, please rely on the [releases](https://github.com/tree-sitter/tree-sitter/releases).
+
+${(0, doc_structure_1.block)({
+            type: 'NOTE',
+            content: 'The tree-sitter grammar may not be able to parse all valid R code due to some bugs in the parser grammar. In that case, please report these to the [tree-sitter-r repository](https://github.com/r-lib/tree-sitter-r).'
+        })}
 `;
     }
 }

package/documentation/wiki-mk/doc-context.d.ts

@@ -47,17 +47,50 @@ type StaticKeys<T> = T extends {
     prototype: infer P;
 } ? Exclude<keyof T, keyof P> : never;
 export declare const ConstantWikiLinkInfo: {
-    readonly 'flowr:npm': "https://www.npmjs.com/package/@eagleoutice/flowr";
-    readonly 'flowr:github': string;
-    readonly 'flowr:wiki': "https://github.com/flowr-analysis/flowr/wiki";
-    readonly 'flowr:docker': "https://hub.docker.com/r/eagleoutice/flowr";
-    readonly 'flowr:vscode': "https://marketplace.visualstudio.com/items?itemName=code-inspect.vscode-flowr";
-    readonly 'flowr:positron': "https://open-vsx.org/extension/code-inspect/vscode-flowr";
-    readonly 'flowr:rstudio-addin': "https://github.com/flowr-analysis/rstudio-addin-flowr";
-    readonly 'flowr:radapter': "https://github.com/flowr-analysis/flowr-r-adapter";
-    readonly 'flowr:benchmarks': "https://flowr-analysis.github.io/flowr/wiki/stats/benchmark";
-    readonly 'flowr:docs': "https://flowr-analysis.github.io/flowr/docs";
-    readonly 'flowr:zenodo': "https://zenodo.org/doi/10.5281/zenodo.13319290";
+    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.

package/documentation/wiki-mk/doc-context.js

@@ -23,17 +23,17 @@ function getNameFromElementIdOrRef(element) {
     }
 }
 exports.ConstantWikiLinkInfo = {
-    'flowr:npm': doc_files_1.FlowrNpmRef,
-    'flowr:github': doc_files_1.FlowrGithubRef,
-    'flowr:wiki': doc_files_1.FlowrWikiBaseRef,
-    'flowr:docker': doc_files_1.FlowrDockerRef,
-    'flowr:vscode': doc_files_1.FlowrVsCode,
-    'flowr:positron': doc_files_1.FlowrPositron,
-    'flowr:rstudio-addin': doc_files_1.FlowrRStudioAddin,
-    'flowr:radapter': doc_files_1.FlowrRAdapter,
-    'flowr:benchmarks': 'https://flowr-analysis.github.io/flowr/wiki/stats/benchmark',
-    'flowr:docs': 'https://flowr-analysis.github.io/flowr/docs',
-    'flowr:zenodo': 'https://zenodo.org/doi/10.5281/zenodo.13319290'
+    'flowr:npm': { url: doc_files_1.FlowrNpmRef, name: 'flowR on npm' },
+    'flowr:github': { url: doc_files_1.FlowrGithubRef, name: 'flowR\'s GitHub' },
+    'flowr:wiki': { url: doc_files_1.FlowrWikiBaseRef, name: 'flowR\'s wiki' },
+    'flowr:docker': { url: doc_files_1.FlowrDockerRef, name: 'flowR\'s Docker Image' },
+    'flowr:vscode': { url: doc_files_1.FlowrVsCode, name: 'flowR extension for VS Code' },
+    'flowr:positron': { url: doc_files_1.FlowrPositron, name: 'flowR extension for Positron' },
+    'flowr:rstudio-addin': { url: doc_files_1.FlowrRStudioAddin, name: 'flowR RStudio Addin' },
+    'flowr:radapter': { url: doc_files_1.FlowrRAdapter, name: 'flowR R Adapter' },
+    'flowr:benchmarks': { url: 'https://flowr-analysis.github.io/flowr/wiki/stats/benchmark', name: 'flowR benchmark page' },
+    'flowr:docs': { url: 'https://flowr-analysis.github.io/flowr/docs', name: 'flowR code docs' },
+    'flowr:zenodo': { url: 'https://zenodo.org/doi/10.5281/zenodo.13319290', name: 'flowR on Zenodo' },
 };
 /**
  * Creates a wiki context for generating documentation for code elements.
@@ -100,14 +100,17 @@ function makeDocContextForTypes(shell, ...rootFolders) {
             });
         },
         linkPage(pageName, linkText, segment) {
-            const text = linkText ?? pageName.split('/').pop() ?? pageName;
             let link;
+            let text = linkText;
             if (pageName in exports.ConstantWikiLinkInfo) {
-                link = exports.ConstantWikiLinkInfo[pageName];
+                const i = exports.ConstantWikiLinkInfo[pageName];
+                link = i.url;
+                text ??= i.name;
             }
             else {
                 link = `${doc_files_1.FlowrWikiBaseRef}/${pageName.toLowerCase().replace(/ /g, '-')}`;
             }
+            text ??= pageName.split('/').pop() ?? pageName;
             return `[${text}](${link}${segment ? `#${segment}` : ''})`;
         },
         linkCode(path, lineNumber) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/flowr",
-  "version": "2.9.11",
+  "version": "2.9.12",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {

package/queries/catalog/dependencies-query/function-info/library-functions.js

@@ -13,6 +13,7 @@ exports.LibraryFunctions = [
     { package: 'easypackages', name: 'from_import', argIdx: 0, argName: 'package', resolveValue: true },
     { package: 'easypackages', name: 'libraries', argIdx: 'unnamed', resolveValue: true },
     { package: 'librarian', name: 'shelf', argIdx: 'unnamed', resolveValue: true },
-    { package: 'devtools', name: 'load_all', argIdx: 0, argName: 'path', resolveValue: true }
+    { package: 'devtools', name: 'load_all', argIdx: 0, argName: 'path', resolveValue: true, defaultValue: '.' },
+    { package: 'devtools', name: 'load_code', argIdx: 0, argName: 'path', resolveValue: true, defaultValue: '.' },
 ];
 //# sourceMappingURL=library-functions.js.map

package/queries/catalog/dependencies-query/function-info/read-functions.js

@@ -93,7 +93,7 @@ exports.ReadFunctions = [
     { package: 'XLConnect', name: 'loadWorkbook', argIdx: 0, argName: 'filename', resolveValue: true },
     { package: 'DiagrammeR', name: 'import_graph', argIdx: 0, argName: 'graph_file', resolveValue: true },
     { package: 'DiagrammeR', name: 'open_graph', argIdx: 0, argName: 'file', resolveValue: true },
-    { package: 'highcharter', name: 'download_map_data', argIdx: 0, argName: 'url', resolveValue: true },
+    { package: 'highcharter', name: 'download_map_data', argIdx: 0, argName: 'url', resolveValue: true, defaultValue: 'custom/world.js' },
     { package: 'rvest', name: 'read_html', argIdx: 0, argName: 'x', resolveValue: true },
     { package: 'rvest', name: 'read_html_live', argIdx: 0, argName: 'url', resolveValue: true },
     { package: 'stats', name: 'read.ftable', argIdx: 0, argName: 'file', resolveValue: true },

package/queries/catalog/dependencies-query/function-info/visualize-functions.js

@@ -9,5 +9,13 @@ exports.VisualizeFunctions =
 // plot creation
 default_builtin_config_1.GgPlotCreate.map(f => ({ package: 'ggplot2', name: f })).concat(default_builtin_config_1.TinyPlotCrate.map(f => ({ package: 'tinyplot', name: f })), default_builtin_config_1.GraphicsPlotCreate.map(f => ({ name: f })), 
 // plot modification
-default_builtin_config_1.GgPlotImplicitAddons.concat(default_builtin_config_1.GgPlotAddons).map(f => ({ package: 'ggplot2', name: f, linkTo: LinkToPlotCreation })), default_builtin_config_1.TinyPlotAddons.map(f => ({ package: 'tinyplot', name: f, linkTo: LinkToPlotCreation })), default_builtin_config_1.GraphicsPlotAddons.map(f => ({ name: f, linkTo: LinkToPlotCreation })));
+default_builtin_config_1.GgPlotImplicitAddons.concat(default_builtin_config_1.GgPlotAddons).map(f => ({ package: 'ggplot2', name: f, linkTo: LinkToPlotCreation })), default_builtin_config_1.TinyPlotAddons.map(f => ({ package: 'tinyplot', name: f, linkTo: LinkToPlotCreation })), default_builtin_config_1.GraphicsPlotAddons.map(f => ({ name: f, linkTo: LinkToPlotCreation }))).map(f => {
+    if (f.name !== 'hist') {
+        return f;
+    }
+    else {
+        // ignore if plot is false.
+        return { ...f, ignoreIf: 'arg-false', additionalArgs: { val: { argIdx: 17, argName: 'plot', resolveValue: true } } };
+    }
+});
 //# sourceMappingURL=visualize-functions.js.map

package/queries/catalog/dependencies-query/function-info/write-functions.js

@@ -115,5 +115,6 @@ exports.WriteFunctions = [
     { package: 'rpolars', name: 'write_csv', argIdx: 0, argName: 'file', resolveValue: true, ignoreIf: 'arg-missing' },
     { package: 'rpolars', name: 'write_ndjson', argIdx: 0, argName: 'file', resolveValue: true, ignoreIf: 'arg-missing' },
     { package: 'rpolars', name: 'write_parquet', argIdx: 0, argName: 'file', resolveValue: true, ignoreIf: 'arg-missing' },
+    { package: 'magick', name: 'image_write', argIdx: 1, argName: 'path', resolveValue: true, ignoreIf: 'arg-missing' },
 ];
 //# sourceMappingURL=write-functions.js.map

package/util/mermaid/dfg.d.ts

@@ -1,6 +1,7 @@
 import { type DataflowGraph } from '../../dataflow/graph/graph';
 import { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import { type IdentifierDefinition } from '../../dataflow/environments/identifier';
+import { type DataflowGraphVertexInfo } from '../../dataflow/graph/vertex';
 import { type MermaidMarkdownMark, type MermaidMarkStyle } from './info';
 interface MermaidGraph {
     nodeLines: string[];
@@ -15,6 +16,13 @@ interface MermaidGraph {
     /** if given, the dataflow graph will only focus on the "important" parts */
     simplified?: boolean;
 }
+/**
+ * Translates a vertex tag to the corresponding mermaid node brackets.
+ */
+export declare function mermaidNodeBrackets(tag: DataflowGraphVertexInfo['tag']): {
+    open: string;
+    close: string;
+};
 /**
  * Prints an identifier definition in a human-readable format.
  */

package/util/mermaid/dfg.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.mermaidNodeBrackets = mermaidNodeBrackets;
 exports.printIdentifier = printIdentifier;
 exports.graphToMermaid = graphToMermaid;
 exports.graphToMermaidUrl = graphToMermaidUrl;
@@ -89,6 +90,9 @@ function displayFunctionArgMapping(argMapping) {
 function encodeEdge(from, to, types) {
     return `${from}->${to}["${Array.from(types).join(':')}"]`;
 }
+/**
+ * Translates a vertex tag to the corresponding mermaid node brackets.
+ */
 function mermaidNodeBrackets(tag) {
     let open;
     let close;

package/util/quads.js

@@ -130,16 +130,24 @@ function processLiteralEntry(value, key, obj, quads, config, index) {
     }
 }
 function processObjectEntry(key, value, obj, quads, config) {
-    if (config.ignore(key, value)) {
-        return;
-    }
-    if (guardCycle(value)) {
+    if (config.ignore(key, value) || guardCycle(value)) {
         return;
     }
     if ((0, objects_1.isObjectOrArray)(value)) {
         if (Array.isArray(value)) {
             processArrayEntries(key, value, obj, quads, config);
         }
+        else if (value instanceof Map) {
+            for (const [mapKey, mapValue] of value.entries()) {
+                processObjectEntry('key-' + String(mapKey), mapValue, obj, quads, config);
+            }
+        }
+        else if (value instanceof Set) {
+            let i = 0;
+            for (const setValue of value.values()) {
+                processObjectEntry('idx-' + String(i++), setValue, obj, quads, config);
+            }
+        }
         else {
             processObjectEntries(key, value, obj, quads, config);
         }
@@ -152,10 +160,10 @@ let store = new Set();
 function guardCycle(obj) {
     // @ts-expect-error we do not care about the type here
     if ((0, objects_1.isObjectOrArray)(obj) && 'id' in obj) {
-        if (store.has(obj.id)) {
+        if (store.has(obj)) {
             return true;
         }
-        store.add(obj.id);
+        store.add(obj);
     }
     return false;
 }

package/util/range.d.ts

@@ -16,6 +16,7 @@ export type SourcePosition = [
  * Utility functions for {@link SourcePosition|source positions}.
  */
 export declare const SourcePosition: {
+    readonly name: "SourcePosition";
     /**
      * Formats a {@link SourcePosition|source position} as a human-readable string.
      */
@@ -48,6 +49,7 @@ export type SourceRange = [
  * Utility functions for {@link SourceRange|source ranges}.
  */
 export declare const SourceRange: {
+    readonly name: "SourceRange";
     /**
      * Prints a {@link SourceRange|range} as a human-readable string.
      */
@@ -123,6 +125,7 @@ export type SourceLocation = [...r: SourceRange, f?: string];
  * Utility functions for {@link SourceLocation|source locations}.
  */
 export declare const SourceLocation: {
+    readonly name: "SourceLocation";
     /**
      * Formats a {@link SourceLocation|source location} as a human-readable string.
      */

package/util/range.js

@@ -6,6 +6,7 @@ const assert_1 = require("./assert");
  * Utility functions for {@link SourcePosition|source positions}.
  */
 exports.SourcePosition = {
+    name: 'SourcePosition',
     /**
      * Formats a {@link SourcePosition|source position} as a human-readable string.
      */
@@ -36,6 +37,7 @@ exports.SourcePosition = {
  * Utility functions for {@link SourceRange|source ranges}.
  */
 exports.SourceRange = {
+    name: 'SourceRange',
     /**
      * Prints a {@link SourceRange|range} as a human-readable string.
      */
@@ -157,6 +159,7 @@ exports.SourceRange = {
  * Utility functions for {@link SourceLocation|source locations}.
  */
 exports.SourceLocation = {
+    name: 'SourceLocation',
     /**
      * Formats a {@link SourceLocation|source location} as a human-readable string.
      */

package/util/version.js

@@ -6,7 +6,7 @@ exports.printVersionInformation = printVersionInformation;
 const semver_1 = require("semver");
 const assert_1 = require("./assert");
 // this is automatically replaced with the current version by release-it
-const version = '2.9.11';
+const version = '2.9.12';
 /**
  * Retrieves the current flowR version as a new {@link SemVer} object.
  */