@eagleoutice/flowr 2.2.12 → 2.2.13

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

@@ -26,13 +26,17 @@ const node_id_1 = require("../r-bridge/lang-4.x/ast/model/processing/node-id");
 const identifier_1 = require("../dataflow/environments/identifier");
 const r_function_call_1 = require("../r-bridge/lang-4.x/ast/model/nodes/r-function-call");
 const resolve_by_name_1 = require("../dataflow/environments/resolve-by-name");
-const environment_builder_1 = require("../../test/functionality/_helper/dataflow/environment-builder");
 const default_pipelines_1 = require("../core/steps/pipeline/default-pipelines");
 const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
-const text_1 = require("../util/text");
+const text_1 = require("../util/text/text");
 const log_1 = require("../../test/functionality/_helper/log");
 const linker_1 = require("../dataflow/internal/linker");
 const doc_normalized_ast_1 = require("./doc-util/doc-normalized-ast");
+const dfg_get_origin_1 = require("../dataflow/origin/dfg-get-origin");
+const identify_link_to_last_call_relation_1 = require("../queries/catalog/call-context-query/identify-link-to-last-call-relation");
+const doc_issue_1 = require("./doc-util/doc-issue");
+const unnamed_call_handling_1 = require("../dataflow/internal/process/functions/call/unnamed-call-handling");
+const environment_builder_1 = require("../../test/functionality/_helper/dataflow/environment-builder");
 async function subExplanation(shell, { description, code, expectedSubgraph }) {
     expectedSubgraph = await (0, doc_dfg_1.verifyExpectedSubgraph)(shell, code, expectedSubgraph);
     const marks = [];
@@ -68,7 +72,7 @@ async function explanation({ shell, name, type, description, code, expectedSubgr
 <a id='${name.toLowerCase().replaceAll(' ', '-')}'> </a>
 ### ${index}) ${name}
 
-Type: \`${type}\`
+Type: \`${type}\` (this is the numeric value of the bit-flag encountered when looking at the serialized vertex type)
 
 ${await subExplanation(shell, { name, description, code, expectedSubgraph })}
 
@@ -78,8 +82,8 @@ ${subExplanations.length > 0 ? await printAllSubExplanations(shell, subExplanati
 function edgeTypeToId(edgeType) {
     return (0, edge_1.edgeTypeToName)(edgeType).toLowerCase().replaceAll(' ', '-');
 }
-function linkEdgeName(edgeType) {
-    return `[\`${(0, edge_1.edgeTypeToName)(edgeType)}\`](#${edgeTypeToId(edgeType)})`;
+function linkEdgeName(edgeType, page = '') {
+    return `[\`${(0, edge_1.edgeTypeToName)(edgeType)}\`](${page}#${edgeTypeToId(edgeType)})`;
 }
 async function getVertexExplanations(shell, vertexType) {
     /* we use the map to ensure order easily :D */
@@ -155,6 +159,16 @@ In general, there may be many such edges, identifying every possible definition
 ${(0, doc_structure_1.details)('Example: Reads Edge Identifying Multiple Definitions (conditional)', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'x <- 1\nif(u) x <- 2\nprint(x)', { mark: new Set([10, '10->0', '10->4']), codeOpen: true }))}
 ${(0, doc_structure_1.details)('Example: Reads Edge Identifying Multiple Definitions (loop)', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'x <- 1\nfor(i in v) x <- 2\nprint(x)', { mark: new Set([11, '11->0', '11->5']), codeOpen: true }))}
 ${(0, doc_structure_1.details)('Example: Reads Edge Identifying Multiple Definitions (side-effect)', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'f <- function() x <<- 2\nx <- 2\nif(u) f()\nprint(x)', { mark: new Set([16, '16->1', '16->7']), codeOpen: true }))}
+
+${(0, doc_structure_1.block)({
+                type: 'IMPORTANT',
+                content: `
+	If you want to obtain the locations where a variable is defined, or read, or re-defined, refrain from tracking these details manually in the dataflow graph
+	as there are some edge-cases that require special attention.
+	In general, the ${(0, doc_types_1.shortLink)(dfg_get_origin_1.getOriginInDfg.name, vertexType.info)} function explained below in [working with the dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Working%20with%20the%20Dataflow%20Graph) will help you to get the information you need.
+	`
+            })}
+
 `,
             code: 'x',
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().use('1@x', 'x')
@@ -175,6 +189,12 @@ ${(0, doc_types_1.printHierarchy)({ program: vertexType.program, info: vertexTyp
 The related function argument references are defined like this:
 ${(0, doc_types_1.printHierarchy)({ program: vertexType.program, info: vertexType.info, root: 'FunctionArgument' })}
 
+There is another element of potential interest to you, the \`origin\` property which records how flowR created the respective function call.
+These origins may hold the name of any processor that is part of the ${(0, doc_types_1.shortLink)('BuiltInProcessorMapper', vertexType.info)} to signal that the respective processor was responsible for creating the vertex.
+The entry \`function\` signals that flowR used a processor for a user-defined function defined within the source code, \`unnamed\` signals that the function as an anonymous function definition.
+However, in general, flowR may use any fitting handler as an origin. For example, within a access definition, flowR will correspondingly redefine the meaning of \`:=\` to that of the \`table:assign\`. 
+
+
 
 ${(0, doc_structure_1.details)('Example: Simple Function Call (unresolved)', await (async () => {
                 const code = 'foo(x,3,y=3,)';
@@ -236,7 +256,7 @@ In this case, the call does not have a single ${linkEdgeName(edge_1.EdgeType.Cal
 global beyond the scope of the given script. _flowR_ generally (theoretically at least) does not know if the call really refers to a built-in variable or function,
 as any code that is not part of the analysis could cause the semantics to change. 
 However, it is (in most cases) safe to assume we call a builtin if there is a builtin function with the given name and if there is no ${linkEdgeName(edge_1.EdgeType.Calls)} edge attached to a call.
-If you want to check the resolve targets, refer to \`${resolve_by_name_1.resolveByName.name}\` which is defined in ${(0, doc_files_1.getFilePathMd)('../dataflow/environments/resolve-by-name')}.
+If you want to check the resolve targets, refer to ${(0, doc_types_1.shortLink)(resolve_by_name_1.resolveByName.name, vertexType.info)}.
 `)}
 
 ${(0, doc_structure_1.details)('2) the function only resolves to definitions that are present in the program', `
@@ -326,11 +346,13 @@ Similarly, trying to resolve the name with \`${resolve_by_name_1.resolveByName.n
 
 `)}
 
-				`
+
+Similar to finding the definitions read by a variable use, please use the ${(0, doc_types_1.shortLink)(linker_1.getAllFunctionCallTargets.name, vertexType.info)} function to find all possible definitions of a function call,
+as explained in the [working with the dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Working%20with%20the%20Dataflow%20Graph) section.`
             })}
 
 Function calls are the most complicated mechanism in R as essentially everything is a function call.
-Even **control structures** like \`if(p) a else b\` are desugared into function calls (e.g., as \`if\`(p, a, b)).
+Even **control structures** like \`if(p) a else b\` are desugared into function calls (e.g., as \`\` \`if\`(p, a, b) \`\`).
 ${(0, doc_structure_1.details)('Example: <code>if</code> as a Function Call', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'if(p) a else b'))}
 
 Similarly, you should be aware of calls to **anonymous functions**, which may appear given directly (e.g. as \`(function() 1)()\`) or indirectly, with code
@@ -339,6 +361,21 @@ ${(0, doc_structure_1.details)('Example: Anonymous Function Call (given directly
 
 ${(0, doc_structure_1.details)('Example: Anonymous Function Call (given indirectly)', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'foo <- function() return(function() 3)\nfoo()()', { mark: new Set([12, '12->4']) }))}
 
+${(0, doc_structure_1.block)({
+                type: 'NOTE',
+                content: `Now you might be asking yourself how to differentiate anonymous and named functions and what you have to keep in mind when working with them?
+
+Unnamed functions have an array of signatures which you can use to identify them. 
+But in short - the \`origin\` attribute of the ${(0, doc_types_1.shortLink)('DataflowGraphVertexFunctionCall', vertexType.info)} is \`${unnamed_call_handling_1.UnnamedFunctionCallOrigin}\`.
+Please be aware that unnamed functions still have a \`name\` property to give it a unique identifier that can be used for debugging and reference.
+This name _always_ starts with \`${unnamed_call_handling_1.UnnamedFunctionCallPrefix}\`.
+
+To identify these calls please do not rely on the [Normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized%20AST). An expression like \`1 + 1\` will be correctly
+identified as a syntactical binary operation. Yet, from a dataflow/semantic perspective this is equivalent to \`\` \`+\`(1, 1) \`\` (which is a named function call and marked as such in the dataflow graph).
+To know which function is called, please rely on the ${linkEdgeName(edge_1.EdgeType.Calls)} edge.
+	`
+            })}
+
 Another interesting case is a function with **side effects**, most prominently with the super-assignment \`<<-\`.
 In this case, you may encounter the ${linkEdgeName(edge_1.EdgeType.SideEffectOnCall)} as exemplified below.
 ${(0, doc_structure_1.details)('Example: Function Call with a Side-Effect', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'f <- function() x <<- 3\n f()', { mark: new Set([8, '1->8']) }))}
@@ -495,8 +532,9 @@ ${(0, doc_structure_1.block)({
                 content: `
 A ${linkEdgeName(edge_1.EdgeType.Reads)} edge is not a transitive closure and only links the "directly read" definition(s).
 Our abstract domains resolving transitive ${linkEdgeName(edge_1.EdgeType.Reads)} edges (and for that matter, following ${linkEdgeName(edge_1.EdgeType.Returns)} as well)
-are currently tailored to what we need in _flowR_. Hence, we offer a function like ${(0, doc_types_1.shortLink)(linker_1.getAllFunctionCallTargets.name, vertexType.info)} (defined in ${(0, doc_files_1.getFilePathMd)('../dataflow/internal/linker.ts')}),
-as well as ${(0, doc_types_1.shortLink)(resolve_by_name_1.resolvesToBuiltInConstant.name, vertexType.info)} (defined in ${(0, doc_files_1.getFilePathMd)('../dataflow/environments/resolve-by-name.ts')}) which do this for specific cases.
+are currently tailored to what we need in _flowR_. Hence, we offer a function like ${(0, doc_types_1.shortLink)(linker_1.getAllFunctionCallTargets.name, vertexType.info)},
+as well as ${(0, doc_types_1.shortLink)(resolve_by_name_1.resolvesToBuiltInConstant.name, vertexType.info)} which do this for specific cases.
+Refer to ${(0, doc_types_1.shortLink)(dfg_get_origin_1.getOriginInDfg.name, vertexType.info)} for a more general solution, as explained in [working with the dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Working%20with%20the%20Dataflow%20Graph).
 
 ${(0, doc_structure_1.details)('Example: Multi-Level Reads', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'x <- 3\ny <- x\nprint(y)', { mark: new Set(['9->7', '7->3', '4->0']) }))}
 
@@ -505,6 +543,10 @@ Similarly, ${linkEdgeName(edge_1.EdgeType.Reads)} can be cyclic, for example in
 ${(0, doc_structure_1.details)('Example: Cyclic Reads', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'for(i in v) x <- x + 1', { mark: new Set(['3->2']) }))}
 				`
             })}
+
+Reads edges may point to built-in definitions as well, to signal that something relates to a built-in element of flowR.
+Their targets are not part of the ${(0, doc_types_1.shortLink)(graph_1.DataflowGraph.name, vertexType.info)} but only markers to signal that the respective definition is a built-in.
+
  
 Please refer to the explanation of the respective vertices for more information.
 `,
@@ -526,7 +568,7 @@ Please refer to the explanation of the respective vertices for more information.
             name: 'DefinedBy Edge', /* concat for link generation */
             type: edge_1.EdgeType.DefinedBy,
             description: `
-The source vertex is usually a [\`define variable vertex\`](#variable-definition-vertex) linking the defined symbol to the entry point of the resulting side.
+The source vertex is usually a [\`variable definition\`](#variable-definition-vertex) linking the defined symbol to the entry point of the resulting side.
 ${(0, doc_structure_1.details)('In general, this does not have to be the right hand side of the operator.', await (0, doc_dfg_1.printDfGraphForCode)(shell, '3 -> x', { mark: new Set([0]) }))}
 
 However, nested definitions can carry it (in the nested case, \`x\` is defined by the return value of <code>\\\`<-\\\`(y, z)</code>). Additionally, we link the assignment function.
@@ -549,7 +591,8 @@ However, nested definitions can carry it (in the nested case, \`x\` is defined b
             shell,
             name: 'Calls Edge',
             type: edge_1.EdgeType.Calls,
-            description: 'Link the [function call](#function-call-vertex) to the [function definition](#function-definition-vertex) that is called.',
+            description: `Link the [function call](#function-call-vertex) to the [function definition](#function-definition-vertex) that is called. To find all called definitions, 
+		please use the ${(0, doc_types_1.shortLink)(dfg_get_origin_1.getOriginInDfg.name, vertexType.info)} function, as explained in [working with the dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Working%20with%20the%20Dataflow%20Graph).`,
             code: 'foo <- function() {}\nfoo()',
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().calls('2@foo', '1@function')
         }, []]);
@@ -557,9 +600,40 @@ However, nested definitions can carry it (in the nested case, \`x\` is defined b
             shell,
             name: 'Returns Edge',
             type: edge_1.EdgeType.Returns,
-            description: 'Link the [function call](#function-call-vertex) to the exit points of the target definition (this may incorporate the call-context).',
+            description: `Link the [function call](#function-call-vertex) to the exit points of the target definition (this may incorporate the call-context).
+As you can see in the example, this happens for user-defined functions (like \`foo\`) as well as for built-in functions (like \`<-\`).
+However, these edges are specific to scenarios in which flowR knows that a specific element is returned. 
+For contrast, compare this to a use of, for example, \`+\`:
+		
+${(0, doc_structure_1.details)('Example: No returns edge for +', await (0, doc_dfg_1.printDfGraphForCode)(shell, '1 + 1'))}
+
+Here, we do not get a ${linkEdgeName(edge_1.EdgeType.Returns)} edge as this function call creates a new value based on its arguments.
+In these scenarios you should rely on the \`args\` property of the ${(0, doc_types_1.shortLink)('DataflowGraphVertexFunctionCall', vertexType.info)} 
+and use the arguments to calculate what you need to know. Alternatively, you can track the ${linkEdgeName(edge_1.EdgeType.Argument)} edges.
+
+In general, the ${linkEdgeName(edge_1.EdgeType.Returns)} edge already does most of the heavy lifting for you, by respecting control flow influences and
+(as long as flowR is able to detect it) dead code.
+
+${(0, doc_structure_1.details)('Example: Tricky Returns', `We show the _simplified_ DFG for simplicity and highlight all ${linkEdgeName(edge_1.EdgeType.Returns)} edges involved in tracking the return of a call to \`f\` (as ${linkEdgeName(edge_1.EdgeType.Returns)} are never transitive and must hence be followed):\n` +
+                await (0, doc_dfg_1.printDfGraphForCode)(shell, 'f <- function() { if(u) { return(3); 2 } else 42 }\nf()', {
+                    simplified: true,
+                    mark: new Set(['19->15', '15->14', '14->12', '14->11', '11->9', '9->7'])
+                })
+                + '\n\n Note, that the `2` should be completely absent of the dataflow graph (recognized as dead code).')}
+<br/>
+
+${(0, doc_structure_1.block)({
+                type: 'NOTE',
+                content: `You might find it an inconvenience that there is no ${linkEdgeName(edge_1.EdgeType.Returns)} edge for _every_ function call. 
+If there is particular function for which you think flowR should be able to detect the return, please open a [new issue](${doc_issue_1.NewIssueUrl}).
+Yet the problem of flowR not tracking returns for functions that create new/transform existing values is a fundamental design decision &mdash; if this irritates you ~~you may be eligible for compensation~~, you may be interested in an
+alternative with the [Control Flow Graph](${doc_files_1.FlowrWikiBaseRef}/Control%20Flow%20Graph#cfg-exit-points) which not just tracks all possible execution orders of the program,
+but also the exit points of _all_ function calls. 
+`
+            })}
+		`,
             code: 'foo <- function() x\nfoo()',
-            expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().returns('2@foo', '1@x')
+            expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().returns('2@foo', '1@x').returns('1@<-', '1@foo').argument('1@<-', '1@foo')
         }, []]);
     const lateBindingExample = `
 f <- function() x
@@ -573,7 +647,7 @@ f()
             type: edge_1.EdgeType.DefinesOnCall,
             description: `*This edge is usually joined with ${linkEdgeName(edge_1.EdgeType.DefinedByOnCall)}!*
 
- Links an Argument to whichever parameter they cause to be defined if the related function call is invoked.
+ Links an argument to whichever parameter they cause to be defined if the related function call is invoked.
  
  In the context of functions which access their closure environment these edges play another tricky role as there are many cases 
  made more difficult by R's way of allowing closure environments to later receive variables.
@@ -689,18 +763,30 @@ async function getText(shell) {
     });
     return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'dataflow graph', rVersion: rversion })}
 
-This page briefly summarizes flowR's dataflow graph, represented by the ${(0, doc_types_1.shortLink)(graph_1.DataflowGraph.name, vertexType.info)}.
+This page briefly summarizes flowR's dataflow graph, represented by the ${(0, doc_types_1.shortLink)(graph_1.DataflowGraph.name, vertexType.info)} class within the code.
 In case you want to manually build such a graph (e.g., for testing), you can use the ${(0, doc_types_1.shortLink)(dataflowgraph_builder_1.DataflowGraphBuilder.name, vertexType.info)}.
-This wiki page focuses on explaining what such a dataflow graph looks like!
+In summary, we discuss the following topics:
+
+- [Vertices](#vertices)
+- [Edges](#edges)
+- [Control Dependencies](#control-dependencies)
+- [Dataflow Information](#dataflow-information)
+	- [Unknown Side Effects](#unknown-side-effects)
+- [Working with the Dataflow Graph](#dfg-working)
 
-Please be aware that the accompanied [dataflow information](#dataflow-information) returned by _flowR_ contains things besides the graph,
+Please be aware that the accompanied [dataflow information](#dataflow-information) (${(0, doc_types_1.shortLink)('DataflowInformation', vertexType.info)}) 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.
+
 > [!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). When using _flowR_ as a library, you may use the functions in ${(0, doc_files_1.getFilePathMd)('../util/mermaid/dfg.ts')}.
+> command in the REPL (see the [Interface wiki page](${doc_files_1.FlowrWikiBaseRef}/Interface) for more information). 
+> There is also a simplified perspective available with ${(0, doc_cli_option_1.getReplCommand)('dataflowsimple*')} that does not show everything but is easier to read.
+> 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 ${(0, doc_types_1.shortLink)(`${graph_1.DataflowGraph.name}::${graph_1.DataflowGraph.fromJson.name}`, vertexType.info, true, 'i')} to retrieve the graph from the JSON representation.
 
@@ -709,7 +795,8 @@ ${await (0, doc_dfg_1.printDfGraphForCode)(shell, 'x <- 3\ny <- x + 1\ny')}
 
 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.
-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).
+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 [Control Flow Graph](${doc_files_1.FlowrWikiBaseRef}/Control%20Flow%20Graph)).
 
 <details open>
 
@@ -748,18 +835,22 @@ ${(0, doc_general_1.prefixLines)((0, doc_code_1.codeBlock)('ts', 'const node = g
 > In case you just need the name (\`lexeme\`) of the respective vertex, ${(0, doc_types_1.shortLink)(node_id_1.recoverName.name, vertexType.info)} can help you out:
 ${(0, doc_general_1.prefixLines)((0, doc_code_1.codeBlock)('ts', `const name = ${node_id_1.recoverName.name}(id, graph.idMap);`), '> ')}
 
-## Vertices
+${(0, doc_structure_1.section)('Vertices', 2, 'vertices')}
+
+1. ${(0, doc_data_dfg_util_1.getAllVertices)().map(([k, v], index) => `[\`${k}\`](#${index + 1}-${v.toLowerCase().replace(/\s/g, '-')}-vertex)`).join('\n1. ')}
 
 ${await getVertexExplanations(shell, vertexType)}
 
-## Edges
+${(0, doc_structure_1.section)('Edges', 2, 'edges')}
+
+1. ${(0, doc_data_dfg_util_1.getAllEdges)().map(([k, v], index) => `[\`${k}\` (${v})](#${index + 1}-${k.toLowerCase().replace(/\s/g, '-')}-edge)`).join('\n1. ')}
 
 ${await getEdgesExplanations(shell, vertexType)}
 
-## Control Dependencies
+${(0, doc_structure_1.section)('Control Dependencies', 2, 'control-dependencies')}
 
 Each vertex may have a list of active control dependencies.
-They hold the \`id\` of all nodes that effect if the current vertex is part of the execution or not,
+They hold the ${(0, doc_types_1.shortLink)('NodeId', vertexType.info)} of all nodes that effect if the current vertex is part of the execution or not,
 and a boolean flag \`when\` to indicate if the control dependency is active when the condition is \`true\` or \`false\`.
 
 As an example, consider the following dataflow graph:
@@ -775,7 +866,8 @@ ${(0, doc_structure_1.details)('Example: Multiple Vertices (Assignment)', await
 ${(0, doc_structure_1.details)('Example: Multiple Vertices (Arithmetic Expression)', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'if(p) 3 + 2'))}
 ${(0, doc_structure_1.details)('Example: Nested Conditionals', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'if(x) { if(y) a else b } else c'))}
 
-## Dataflow Information
+
+${(0, doc_structure_1.section)('Dataflow Information', 2, 'dataflow-information')}
 
 Using _flowR's_ code interface (see the [Interface](${doc_files_1.FlowrWikiBaseRef}/Interface) wiki page for more), you can generate the dataflow information
 for a given piece of R code (in this case \`x <- 1; x + 1\`) as follows (using the ${(0, doc_types_1.shortLink)(shell_1.RShell.name, vertexType.info)} and the ${(0, doc_types_1.shortLink)(pipeline_executor_1.PipelineExecutor.name, vertexType.info)} classes):
@@ -877,6 +969,69 @@ Additionally, we express this by a ${linkEdgeName(edge_1.EdgeType.Reads)} edge.
 	`;
         })()}
  
+${(0, doc_structure_1.section)('Working with the Dataflow Graph', 2, 'dfg-working')}
+
+The ${(0, doc_types_1.shortLink)('DataflowInformation', vertexType.info)} is the core result of _flowR_ and summarizes a lot of information.
+Depending on what you are interested in, there exists a plethora of functions and queries to help you out, answering the most important questions:
+
+* The **[Query API](${doc_files_1.FlowrWikiBaseRef}/Query%20API)** provides many functions to query the dataflow graph for specific information (dependencies, calls, slices, clusters, ...)
+* The **[Search API](${doc_files_1.FlowrWikiBaseRef}/Search%20API)** allows you to search for specific vertices or edges in the dataflow graph or the original program
+* ${(0, doc_types_1.shortLink)(node_id_1.recoverName.name, vertexType.info)} and ${(0, doc_types_1.shortLink)(node_id_1.recoverContent.name, vertexType.info)} to get the name or content of a vertex in the dataflow graph
+* ${(0, doc_types_1.shortLink)(resolve_by_name_1.resolveValueOfVariable.name, vertexType.info)} and ${(0, doc_types_1.shortLink)(resolve_by_name_1.resolveIdToValue.name, vertexType.info)} to resolve the value of a variable or id (if possible, see [below](#dfg-resolving-values))
+* ${(0, doc_types_1.shortLink)(edge_1.edgeIncludesType.name, vertexType.info)} to check if an edge includes a specific type and ${(0, doc_types_1.shortLink)(edge_1.splitEdgeTypes.name, vertexType.info)} to split the bitmask of edges into its types (see [below](#dfg-resolving-values))
+* ${(0, doc_types_1.shortLink)(identify_link_to_last_call_relation_1.getValueOfArgument.name, vertexType.info)} to get the (syntactical) value of an argument in a function call 
+* ${(0, doc_types_1.shortLink)(dfg_get_origin_1.getOriginInDfg.name, vertexType.info)} to get information about where a read, call, ... comes from (see [below](#dfg-resolving-values))
+
+Some of these functions have been explained in their respective wiki pages. However, some are part of the [Dataflow Graph API](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph%20API) and so we explain them here.
+
+${(0, doc_structure_1.section)('Resolving Values', 3, 'dfg-resolving-values')}
+
+FlowR supports a [configurable](${doc_files_1.FlowrWikiBaseRef}/Interface#configuring-flowr) level of value tracking&mdash;all with the goal of knowing the static value domain of a variable.
+These capabilities are exposed by the [resolve value Query](${doc_files_1.FlowrWikiBaseRef}/Query-API#resolve-value-query) and backed by two important functions:
+
+${(0, doc_types_1.shortLink)(resolve_by_name_1.resolveValueOfVariable.name, vertexType.info)} provides an environment-sensitive (see ${(0, doc_types_1.shortLink)('REnvironmentInformation', vertexType.info)})
+value resolution, while ${(0, doc_types_1.shortLink)(resolve_by_name_1.resolveIdToValue.name, vertexType.info)} provides a more general, but potentially less precise resolution independent of the current state.
+
+${(0, doc_structure_1.section)('Assessing Edges', 3, 'dfg-assess-edge')}
+
+The [edges](#edges) of the dataflow graph use bitmasks to represent an edge with multiple types. While this compacts the representation greatly, it makes it
+difficult to check whether a given edge is a read edge. 
+Consider the following example:
+
+${await (0, doc_dfg_1.printDfGraphForCode)(shell, 'print(x)', { mark: new Set(['3->1']) })}
+
+Retrieving the _types_ of the edge from the print call to its argument returns:
+${await (async () => {
+            const dfg = await (0, default_pipelines_1.createDataflowPipeline)(shell, {
+                request: (0, retriever_1.requestFromInput)('print(x)')
+            }).allRemainingSteps();
+            const edge = dfg.dataflow.graph.outgoingEdges(3);
+            if (edge) {
+                const wanted = edge.get(1);
+                if (wanted) {
+                    return '`' + wanted.types + '`';
+                }
+            }
+            new Error('Could not find edge');
+        })()}&mdash;which is usually not very helpful.
+You can use ${(0, doc_types_1.shortLink)(edge_1.splitEdgeTypes.name, vertexType.info)} to get the individual bitmasks of all included types, and 
+${(0, doc_types_1.shortLink)(edge_1.edgeIncludesType.name, vertexType.info)} to check whether a specific type (or one of a collection of types) is included in the edge.
+
+${(0, doc_structure_1.section)('Handling Origins', 3, 'dfg-handling-origins')}
+
+If you are writing another analysis on top of the dataflow graph, you probably want to know all definitions that serve as the source of a read, all functions
+that are called by an invocation, and more.
+For this, the ${(0, doc_types_1.shortLink)(dfg_get_origin_1.getOriginInDfg.name, vertexType.info)} function provides you with a collection of ${(0, doc_types_1.shortLink)('Origin', vertexType.info)} objects:
+
+${(0, doc_types_1.printHierarchy)({ program: vertexType.program, info: vertexType.info, root: 'Origin', openTop: true })}
+
+Their respective uses are documented alongside their implementation:
+
+${['SimpleOrigin', 'FunctionCallOrigin', 'BuiltInFunctionOrigin'].sort().map(key => `- ${(0, doc_types_1.shortLink)(`${key}`, vertexType.info)}\\\n${(0, doc_types_1.getDocumentationForType)(`${key}`, vertexType.info)}`).join('\n')}
+
+Please note, the current structure of this function is biased by what implementations already exist in flowR.
+Hence, we do not just track definitions and constants, but also the origins of function calls, albeit we do not yet track the origins of values (only resorting to
+a constant origin). If you are confused by this please start a discussion&mdash;in a way we are still deciding on a good API for this.
 
 	`;
     })()}

package/documentation/print-engines-wiki.js

@@ -24,7 +24,7 @@ async function getText(shell) {
     return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'engines', rVersion: rversion })}
 
 To analyze R scripts, flowR needs to parse the R code and for that, we require a parser.
-Originally, flowR shipped with a ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)}, an asynchronous interface to the R interpreter, still available today.
+Originally, flowR shipped with an ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)}, an asynchronous interface to the R interpreter, still available today.
 Later we extended this with the ${(0, doc_types_1.shortLink)(shell_executor_1.RShellExecutor.name, types.info)}, the synchronous counterpart to the ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)}.
 However, these interfaces are relatively slow as they require communication with an underlying R interpreter. 
 Using [tree-sitter](https://tree-sitter.github.io/tree-sitter/), with its [node bindings](https://github.com/tree-sitter/node-tree-sitter)

package/documentation/print-faq-wiki.d.ts

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

package/documentation/print-faq-wiki.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const log_1 = require("../../test/functionality/_helper/log");
+const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
+const doc_files_1 = require("./doc-util/doc-files");
+const doc_code_1 = require("./doc-util/doc-code");
+function print() {
+    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'frequently asked questions' })}
+	
+## 💮 *flowR* FAQ
+
+### 🧑‍💻 *flowR* Development
+
+${qAndA('What are test labels and how do they work?', `
+Tests are labeled based on the *flowR* capabilities that they test for. The list of supported capabilities can be found on the [Capabilities](${doc_files_1.FlowrWikiBaseRef}/Capabilities) wiki page. For more extensive information on test labels, see the [test labels wiki section](${doc_files_1.FlowrWikiBaseRef}/Linting-and-Testing#test-labels).
+`)}
+
+${qAndA('How do I generate mermaid diagrams?', `
+There are several ways to generate mermaid diagrams based on the input data that you want to use.
+- From the AST (abstract syntax tree): ${(0, doc_files_1.getFilePathMd)('../util/mermaid/ast.ts')}
+- From the CFG (control flow graph): ${(0, doc_files_1.getFilePathMd)('../util/mermaid/cfg.ts')}
+- From the DFG (dataflow graph): ${(0, doc_files_1.getFilePathMd)('../util/mermaid/dfg.ts')}
+`)}
+
+${qAndA('How do I create new wiki pages?', `
+To create an automatically generated wiki page, you can follow these steps:
+- Createa a new file in \`src/documentation\` with a name like \`print-my-page-wiki.ts\`.
+- Add a new wiki generation script to the ${(0, doc_files_1.getFilePathMd)('../../package.json')}. You can copy one of the existing ones of the form \`"wiki:my-page": "ts-node src/documentation/print-my-page-wiki.ts"\`.
+- Add the wiki generation script to the \`broken-links-and-wiki.yml\` GitHub workflow file to enable automatic generation through the CI. You can copy one of the existing ones of the form \`update_page wiki/"My page" wiki:my-page\`.
+
+You can test your page by piping the wiki generation script to a file. For example, you can run the following command:
+${(0, doc_code_1.codeBlock)('shell', 'npm run --silent wiki:my-page > __my-page.md')}
+`)}
+Remember not to commit this file, as it's only meant for testing.
+
+## 🇷 R FAQ
+
+### 📦 R Packages
+
+${qAndA('What is the R prelude and R base package?', `
+The base package contains lots of base functions like \`source\` for example. 
+The R prelude includes the base package along with several other packages.
+Packages that were loaded by the prelude can be called without prefixing the function call with the package name and the \`::\` operator. 
+
+The packages loaded by the R prelude can be seen in the \`attached base packages\` sections in the output of \`sessionInfo()\`.
+`)}
+
+${qAndA('How to get documentation for a function or package?', `
+There are a couple of ways to get documentation for a function or package. 
+
+🖥️ Firstly, if you have already installed the package the function originated from you can simply run \`?<package name>::<function name>\` in an R session to print the 
+relevant documentation. If you don't know the origin of the package, you can use 
+\`??<function name>\` in an R shell to fuzzy find all documentations containing 
+\`<function name>\` or something similar. 
+
+🌐 Secondly, if you don't have or don't want to install the package you can simply google the fully qualified name of the function. Good sources include \`rdrr.io\`
+or \`rdocumentation.org\`. Additionally, the package documentation PDF can also
+be downloaded directly from \`cran\`.  
+`)}
+
+    `.trim();
+}
+function qAndA(question, answer) {
+    return `<details>
+<summary><strong>${question}</strong></summary>
+
+${answer.trim()}
+
+</details>`;
+}
+if (require.main === module) {
+    (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
+    console.log(print());
+}
+//# sourceMappingURL=print-faq-wiki.js.map

package/documentation/print-interface-wiki.js

@@ -17,7 +17,7 @@ const doc_repl_1 = require("./doc-util/doc-repl");
 const doc_dfg_1 = require("./doc-util/doc-dfg");
 const config_1 = require("../config");
 const schema_1 = require("../util/schema");
-const ansi_1 = require("../util/ansi");
+const ansi_1 = require("../util/text/ansi");
 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");