@eagleoutice/flowr 2.6.2 → 2.7.0

package/documentation/{print-cfg-wiki.js → wiki-cfg.js}

@@ -1,14 +1,6 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const shell_1 = require("../r-bridge/shell");
-const log_1 = require("../../test/functionality/_helper/log");
-const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
-const doc_code_1 = require("./doc-util/doc-code");
-const doc_types_1 = require("./doc-util/doc-types");
-const path_1 = __importDefault(require("path"));
+exports.WikiCfg = void 0;
 const doc_files_1 = require("./doc-util/doc-files");
 const doc_cli_option_1 = require("./doc-util/doc-cli-option");
 const doc_structure_1 = require("./doc-util/doc-structure");
@@ -32,7 +24,10 @@ const semantic_cfg_guided_visitor_1 = require("../control-flow/semantic-cfg-guid
 const doc_issue_1 = require("./doc-util/doc-issue");
 const edge_1 = require("../dataflow/graph/edge");
 const assert_1 = require("../util/assert");
-const config_1 = require("../config");
+const flowr_analyzer_context_1 = require("../project/context/flowr-analyzer-context");
+const doc_maker_1 = require("./wiki-mk/doc-maker");
+const doc_general_1 = require("./doc-util/doc-general");
+const doc_code_1 = require("./doc-util/doc-code");
 const CfgLongExample = `f <- function(a, b = 3) {
  if(a > b) {
  	return(a * b);
@@ -104,8 +99,8 @@ class CollectNumbersDataflowVisitor extends dfg_cfg_guided_visitor_1.DataflowAwa
 }
 class CollectSourcesSemanticVisitor extends semantic_cfg_guided_visitor_1.SemanticCfgGuidedVisitor {
     sources = [];
-    constructor(controlFlow, normalizedAst, dataflow, config) {
-        super({ controlFlow, normalizedAst, dfg: dataflow, flowrConfig: config, defaultVisitingOrder: 'forward' });
+    constructor(controlFlow, normalizedAst, dataflow, ctx) {
+        super({ controlFlow, normalizedAst, dfg: dataflow, ctx, defaultVisitingOrder: 'forward' });
     }
     onAssignmentCall({ source }) {
         if (source) {
@@ -116,33 +111,30 @@ class CollectSourcesSemanticVisitor extends semantic_cfg_guided_visitor_1.Semant
         return this.sources;
     }
 }
-async function getText(shell) {
-    const rversion = (await shell.usedRVersion())?.format() ?? 'unknown';
-    const types = (0, doc_types_1.getTypesFromFolder)({
-        rootFolder: path_1.default.resolve('./src'),
-        inlineTypes: doc_types_1.mermaidHide
-    });
-    const testTypes = (0, doc_types_1.getTypesFromFolder)({
-        rootFolder: path_1.default.resolve('./test'),
-        inlineTypes: doc_types_1.mermaidHide
-    });
-    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'control flow graph', rVersion: rversion })}
-
+/**
+ * https://github.com/flowr-analysis/flowr/wiki/Control-Flow-Graph
+ */
+class WikiCfg extends doc_maker_1.DocMaker {
+    constructor() {
+        super('wiki/Control Flow Graph.md', module.filename, 'control flow graph');
+    }
+    async text({ ctx, shell }) {
+        return `
 _flowR_ produces three main perspectives of the program: 1) a [normalized version of the AST](${doc_files_1.FlowrWikiBaseRef}/Normalized-AST)
 and 2) a [dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph), and 3) a control flow graph (CFG).
 flowR uses this CFG interweaved with its data flow analysis and for some of its queries (e.g., to link to the last call in a [Call-Context Query](${doc_files_1.FlowrWikiBaseRef}/Query-API)).
 
 Please note that, mostly due to historical reasons, the [control dependencies](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph#control-dependencies) that are stored directly within the
 DFG provide only a partial view of the CFG. While they provide you with information on the conditional execution of vertices, they do not encode the order of execution.
-In contrast, the CFG describes a complete view of the program's control flow.
+	In contrast, the CFG describes a complete view of the program's control flow.
 
 ${(0, doc_structure_1.block)({
-        type: 'TIP',
-        content: `If you want to investigate the Control Flow Graph,
+            type: 'TIP',
+            content: `If you want to investigate the Control Flow Graph,
 you can use the ${(0, doc_cli_option_1.getReplCommand)('controlflow*')} command in the REPL (see the [Interface wiki page](${doc_files_1.FlowrWikiBaseRef}/Interface) for more information).
 By default, this view does _not_ use basic blocks as, for example, R allows unconditional jumps to occur in spots where conventional languages would assume expressions (e.g., if-conditions).
 Yet, by using ${(0, doc_cli_option_1.getReplCommand)('controlflowbb*')} you can inspect the CFG with basic blocks (although you have to keep in mind that now, there can be a value flow between basic blocks)`
-    })}
+        })}
 
 For readability, we structure this wiki page into various segments:
 
@@ -157,7 +149,6 @@ For readability, we structure this wiki page into various segments:
 	- [Sophisticated CFG Traversal](#cfg-traversal)
 	- [Working With Exit Points](#cfg-exit-points)
 
-
 ${(0, doc_structure_1.section)('Initial Overview', 2, 'cfg-overview')}
 
 For now, let's look at a CFG for a program without any branching:
@@ -169,9 +160,9 @@ The corresponding CFG is a directed, labeled graph with two types of edges (cont
 ${await (0, doc_cfg_1.printCfgCode)(shell, 'x <- 2 * 3 + 1', { showCode: false, prefix: 'flowchart RL\n' })}
 
 ${(0, doc_structure_1.block)({
-        type: 'IMPORTANT',
-        content: 'As the edges describe dependencies they point in the inverse order of execution (which is very helpful for backward analyses)! The [visitors](#cfg-working) abstract away from this and there is no harm in considering an inverted CFG. Yet, you should keep this in mind!'
-    })}
+            type: 'IMPORTANT',
+            content: 'As the edges describe dependencies they point in the inverse order of execution (which is very helpful for backward analyses)! The [visitors](#cfg-working) abstract away from this and there is no harm in considering an inverted CFG. Yet, you should keep this in mind!'
+        })}
 
 Every normalized node of the [normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized-AST) that has any relevance to the
 execution is added and automatically linked using its id (similarly to vertices of the [dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph)).
@@ -202,54 +193,54 @@ ${await (0, doc_cfg_1.printCfgCode)(shell, 'f <- function() { 3 }\nf()', { showC
 
 ${(0, doc_structure_1.section)('Structure of the Control Flow Graph', 2, 'cfg-structure')}
 
-You can produce your very own control flow graph with ${(0, doc_types_1.shortLink)(extract_cfg_1.extractCfg.name, types.info)}.
-The ${(0, doc_types_1.shortLink)(control_flow_graph_1.ControlFlowGraph.name, types.info)} class describes everything required to model the control flow graph, with its edge types described by
- ${(0, doc_types_1.shortLink)('CfgEdge', types.info)} and its vertices by ${(0, doc_types_1.shortLink)('CfgSimpleVertex', types.info)}.
-However, you should be aware of the ${(0, doc_types_1.shortLink)('ControlFlowInformation', types.info)} interface which adds some additional information the CFG
+You can produce your very own control flow graph with ${ctx.link(extract_cfg_1.extractCfg)}.
+The ${ctx.link(control_flow_graph_1.ControlFlowGraph)} class describes everything required to model the control flow graph, with its edge types described by
+ ${ctx.link('CfgEdge')} and its vertices by ${ctx.link('CfgSimpleVertex')}.
+However, you should be aware of the ${ctx.link('ControlFlowInformation')} interface which adds some additional information the CFG
 (and is used during the construction of the CFG as well):
 
-${(0, doc_types_1.printHierarchy)({ info: types.info, root: 'ControlFlowInformation', program: types.program, openTop: true })}
+${ctx.hierarchy('ControlFlowInformation', { openTop: true })}
 
-To check whether the CFG has the expected shape, you can use the test function ${(0, doc_types_1.shortLink)('assertCfg', testTypes.info)} which supports testing for
- sub-graphs as well (it provides diffing capabilities similar to ${(0, doc_types_1.shortLink)('assertDataflow', testTypes.info)}).
-As the CFG may become unhandy for larger programs, there are simplifications available with ${(0, doc_types_1.shortLink)(cfg_simplification_1.simplifyControlFlowInformation.name, types.info)}
-(these can be passed on to the ${(0, doc_types_1.shortLink)(extract_cfg_1.extractCfg.name, types.info)} function as well).
+To check whether the CFG has the expected shape, you can use the test function ${ctx.link('assertCfg')} which supports testing for
+ sub-graphs as well (it provides diffing capabilities similar to ${ctx.link('assertDataflow')}).
+As the CFG may become unhandy for larger programs, there are simplifications available with ${ctx.link(cfg_simplification_1.simplifyControlFlowInformation)}
+(these can be passed on to the ${ctx.link(extract_cfg_1.extractCfg)} function as well).
 
 ${(0, doc_structure_1.section)('CFG Vertices', 3, 'cfg-structure-vertices')}
 
-All vertex types are summarized in the ${(0, doc_types_1.shortLink)('CfgVertexType', types.info)} enum which currently contains the following types:
+All vertex types are summarized in the ${ctx.link('CfgVertexType')} enum which currently contains the following types:
 
 ${Object.entries(control_flow_graph_1.CfgVertexType).map(([key, value]) => `- \`${key}\` (${value})`).join('\n')}
 
-We use the ${(0, doc_types_1.shortLink)('CfgBasicBlockVertex', types.info)} to represent [basic blocks](#cfg-basic-blocks) and separate
-expressions (${(0, doc_types_1.shortLink)('CfgExpressionVertex', types.info)}) and statements (${(0, doc_types_1.shortLink)('CfgStatementVertex', types.info)}) 
+We use the ${ctx.link('CfgBasicBlockVertex')} to represent [basic blocks](#cfg-basic-blocks) and separate
+expressions (${ctx.link('CfgExpressionVertex')}) and statements (${ctx.link('CfgStatementVertex')}) 
 as control flow units with and without side effects (if you want to, you can see view statements as effectful expressions).
-The markers (${(0, doc_types_1.shortLink)('CfgEndMarkerVertex', types.info)}) indicate the end of larger expressions/statements. 
+The markers (${ctx.link('CfgEndMarkerVertex')}) indicate the end of larger expressions/statements. 
 
 To signal these links, the expressions and statements contain information about the attached markers:
 
-${(0, doc_types_1.printHierarchy)({ info: types.info, root: 'CfgWithMarker', program: types.program, openTop: true })}
+${ctx.hierarchy('CfgWithMarker', { openTop: true })}
 
 Similarly, the markers contain a link to their root: 
 
-${(0, doc_types_1.printHierarchy)({ info: types.info, root: 'CfgWithRoot', program: types.program, openTop: true })}
+${ctx.hierarchy('CfgWithRoot', { openTop: true })}
 
 In mermaid visualizations, we use rectangles for statements, rounded rectangles for expressions and circles for exit markers.
 Blocks are visualized as boxes around the contained vertices.
 
 ${(0, doc_structure_1.block)({
-        type: 'NOTE',
-        content: `
-	Every CFG vertex has a ${(0, doc_types_1.shortLink)('NodeId', types.info)} that links it to the [normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized-AST) (although basic blocks will find no counterpart as they are a structuring element of the CFG).
+            type: 'NOTE',
+            content: `
+	Every CFG vertex has a ${ctx.link('NodeId')} that links it to the [normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized-AST) (although basic blocks will find no counterpart as they are a structuring element of the CFG).
 	Additionally, it may provide information on the called functions (in case that the current element is a function call).
-	Have a look at the ${(0, doc_types_1.shortLink)('CfgBaseVertex', types.info)} interface for more information.
+	Have a look at the ${ctx.link('CfgBaseVertex')} interface for more information.
 		`.trim()
-    })}
+        })}
 
 ${(0, doc_structure_1.section)('CFG Edges', 3, 'cfg-structure-edges')}
 
-The ${(0, doc_types_1.shortLink)(control_flow_graph_1.ControlFlowGraph.name, types.info)} uses two types of edges to represent the control flow, separated by the ${(0, doc_types_1.shortLink)('CfgEdgeType', types.info)} enum
-and the two interfaces: ${(0, doc_types_1.shortLink)('CfgFlowDependencyEdge', types.info)} and ${(0, doc_types_1.shortLink)('CfgControlDependencyEdge', types.info)}.
+The ${ctx.link(control_flow_graph_1.ControlFlowGraph)} uses two types of edges to represent the control flow, separated by the ${ctx.link('CfgEdgeType')} enum
+and the two interfaces: ${ctx.link('CfgFlowDependencyEdge')} and ${ctx.link('CfgControlDependencyEdge')}.
 
 ${(0, doc_structure_1.section)('Flow Dependencies', 4, 'cfg-flow-dependency')}
 
@@ -263,20 +254,20 @@ ${(0, doc_structure_1.section)('Control Dependencies', 4, 'cfg-control-dependenc
 Control dependencies&nbsp;(CD) are used to signal that the execution of the source vertex depends on the taget vertex (which, e.g., is the condition of an \`if\` statement or \`while\` loop).
 They contain additional information to signal _when_ the source vertex is executed:
 
-${(0, doc_types_1.printHierarchy)({ info: types.info, root: 'CfgControlDependencyEdge', program: types.program, openTop: true })}
+${ctx.hierarchy('CfgControlDependencyEdge', { openTop: true })}
 
 The extra \`caused\` link signals the vertex that caused the control flow influence.
 
 
 ${await (async () => {
-        const exa = await (0, doc_cfg_1.printCfgCode)(shell, 'if(u) 3 else 2', { showCode: true, prefix: 'flowchart RL\n' });
-        return (0, doc_structure_1.details)('Example: if-else', exa);
-    })()}
+            const exa = await (0, doc_cfg_1.printCfgCode)(shell, 'if(u) 3 else 2', { showCode: true, prefix: 'flowchart RL\n' });
+            return (0, doc_structure_1.details)('Example: if-else', exa);
+        })()}
 
 ${await (async () => {
-        const exa = await (0, doc_cfg_1.printCfgCode)(shell, 'while(u) b', { showCode: true, prefix: 'flowchart RL\n' });
-        return (0, doc_structure_1.details)('Example: while-loop', exa);
-    })()}
+            const exa = await (0, doc_cfg_1.printCfgCode)(shell, 'while(u) b', { showCode: true, prefix: 'flowchart RL\n' });
+            return (0, doc_structure_1.details)('Example: while-loop', exa);
+        })()}
 <br/>
 
 Please note that repeat loops do _not_ have control dependencies, as they repeat their body unconditionally.
@@ -284,26 +275,26 @@ Additionally, the control flow graph does not have to be connected. If you use a
 the corresponding exit markers are not reachable from the entry:
 
 ${await (async () => {
-        const exa = await (0, doc_cfg_1.printCfgCode)(shell, 'repeat { b }; after', { showCode: true, prefix: 'flowchart RL\n' });
-        return (0, doc_structure_1.details)('Example: repeat-loop (infinite)', exa);
-    })()}
+            const exa = await (0, doc_cfg_1.printCfgCode)(shell, 'repeat { b }; after', { showCode: true, prefix: 'flowchart RL\n' });
+            return (0, doc_structure_1.details)('Example: repeat-loop (infinite)', exa);
+        })()}
 
 ${await (async () => {
-        const exa = await (0, doc_cfg_1.printCfgCode)(shell, 'repeat { b; if(u) break; }; after', { showCode: true, prefix: 'flowchart RL\n' });
-        return (0, doc_structure_1.details)('Example: repeat-loop (with break)', exa);
-    })()}
+            const exa = await (0, doc_cfg_1.printCfgCode)(shell, 'repeat { b; if(u) break; }; after', { showCode: true, prefix: 'flowchart RL\n' });
+            return (0, doc_structure_1.details)('Example: repeat-loop (with break)', exa);
+        })()}
 <br/>
 
 In the context of a for-loop, the control dependency refer to whether the respective vector still has values to iterate over.
 
 ${await (async () => {
-        const exa = await (0, doc_cfg_1.printCfgCode)(shell, 'for(i in 1:10) b', { showCode: true, prefix: 'flowchart RL\n' });
-        return (0, doc_structure_1.details)('Example: for-loop', exa);
-    })()}
+            const exa = await (0, doc_cfg_1.printCfgCode)(shell, 'for(i in 1:10) b', { showCode: true, prefix: 'flowchart RL\n' });
+            return (0, doc_structure_1.details)('Example: for-loop', exa);
+        })()}
 
 ${(0, doc_structure_1.section)('Extra: Call Links', 4, 'cfg-call-links')}
 
-If you generate the CFG with the ${(0, doc_types_1.shortLink)(extract_cfg_1.extractCfg.name, types.info)} function you can (and, if you want to gain inter-procedural information, should)
+If you generate the CFG with the ${ctx.link(extract_cfg_1.extractCfg)} function you can (and, if you want to gain inter-procedural information, should)
 pass a matching [dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph) to it to incorporate the dataflow perspective into the CFG.
 
 The difference becomes obvious when we look at the code \`f <- function() b; f()\` first without the dataflow graph:
@@ -318,7 +309,7 @@ There are two important additions:
 
 1. A new exit marker, canonically suffixed with \`${extract_cfg_1.ResolvedCallSuffix}\` signals that we are aware of the function call target.
    This marker always follows the exit marker of the function call and links not just the call but also the exit points of the function definition.
-2. A new _calls_ attribute attached to the function call vertex. This holds the ${(0, doc_types_1.shortLink)('NodeId', types.info)} of the function definitions that are called from this vertex.
+2. A new _calls_ attribute attached to the function call vertex. This holds the ${ctx.link('NodeId')} of the function definitions that are called from this vertex.
 
 For built-in functions that are provided by flowR's built-in configuration (see the [interface wiki page](${doc_files_1.FlowrWikiBaseRef}/Interface)) the CFG does not contain
 the additional information directly:
@@ -334,7 +325,7 @@ ${(0, doc_structure_1.section)('Adding Basic Blocks', 3, 'cfg-basic-blocks')}
 As mentioned in the introduction, our control flow graph does not use basic blocks by default and hence simply links all vertices independent of whether they have (un-)conditional jumps or not.
 On the upside, this tells us the execution order (and, in case of promises, forcing order) of involved expressions and seamlessly handles cases like
 \`x <- return(3)\`.  On the downside, this makes it hard to apply classical control flow graph algorithms and, in general, makes the graph much harder to read.
-Yet, we can request basic blocks or transform an existing CFG into basic blocks using the ${(0, doc_types_1.shortLink)(cfg_to_basic_blocks_1.convertCfgToBasicBlocks.name, types.info)} function.
+Yet, we can request basic blocks or transform an existing CFG into basic blocks using the ${ctx.link(cfg_to_basic_blocks_1.convertCfgToBasicBlocks)} function.
 
 Any program without any (un-)conditional jumps now contains a single basic block:
 
@@ -345,7 +336,7 @@ While the CFG without basic blocks is much bigger:
 ${await (0, doc_cfg_1.printCfgCode)(shell, 'x <- 2 * 3 + 1', { showCode: false, prefix: 'flowchart RL\n' })}
 
 In a way, using the basic blocks perspective does not remove any of these vertices (we just usually visualize them compacted as their execution order should be "obvious").
-The vertices are still there, as elems of the ${(0, doc_types_1.shortLink)('CfgBasicBlockVertex', types.info)}:
+The vertices are still there, as elems of the ${ctx.link('CfgBasicBlockVertex')}:
 
 ${await (0, doc_cfg_1.printCfgCode)(shell, 'x <- 2 * 3 + 1', { showCode: false, prefix: 'flowchart RL\n', simplifications: ['to-basic-blocks'], simplify: false })}
 
@@ -360,9 +351,9 @@ ${await (0, doc_cfg_1.printCfgCode)(shell, CfgLongExample, { showCode: false, pr
 Now, without basic blocks, this is a different story...
 
 ${await (async () => {
-        const exa = await (0, doc_cfg_1.printCfgCode)(shell, CfgLongExample, { showCode: false, prefix: 'flowchart RL\n' });
-        return (0, doc_structure_1.details)('The full CFG', exa);
-    })()}
+            const exa = await (0, doc_cfg_1.printCfgCode)(shell, CfgLongExample, { showCode: false, prefix: 'flowchart RL\n' });
+            return (0, doc_structure_1.details)('The full CFG', exa);
+        })()}
 
 And again it should be noted that even though the example code is more complicated, this is still far from the average real-world script.
 
@@ -374,35 +365,35 @@ Similarly, flowR provides you with a set of utility functions and classes that y
 ${(0, doc_structure_1.section)('Simple Traversal', 3, 'cfg-simple-traversal')}
 
 If you are just interested in traversing the vertices within the cfg, two simple functions
-${(0, doc_types_1.shortLink)(simple_visitor_1.visitCfgInOrder.name, types.info)} and ${(0, doc_types_1.shortLink)(simple_visitor_1.visitCfgInReverseOrder.name, types.info)} are available. For [basic blocks](#cfg-basic-blocks)
+${ctx.link(simple_visitor_1.visitCfgInOrder)} and ${ctx.link(simple_visitor_1.visitCfgInReverseOrder)} are available. For [basic blocks](#cfg-basic-blocks)
 these will automatically traverse the elements contained within the blocks (in the respective order).
 For example, the following function will return all numbers contained within the CFG:
 
-${(0, doc_types_1.printCodeOfElement)(types, sampleCollectNumbers.name)}
+${ctx.code(sampleCollectNumbers)}
 
 Calling it with the CFG and AST of the expression \`x - 1 + 2L * 3\` yields the following elements (in this order):
 
 ${await (async () => {
-        const res = await (0, doc_cfg_1.getCfg)(shell, 'x - 1 + 2L * 3');
-        const collected = sampleCollectNumbers(res.info, res.ast);
-        return collected.map(n => '\n- `' + JSON.stringify(n) + '`').join('');
-    })()}
+            const res = await (0, doc_cfg_1.getCfg)(shell, 'x - 1 + 2L * 3');
+            const collected = sampleCollectNumbers(res.info, res.ast);
+            return collected.map(n => '\n- `' + JSON.stringify(n) + '`').join('');
+        })()}
 
-A more useful appearance of these visitors occurs with ${(0, doc_types_1.shortLink)(happens_before_1.happensBefore.name, types.info)} which uses the CFG to determine whether the execution
+A more useful appearance of these visitors occurs with ${ctx.link(happens_before_1.happensBefore)} which uses the CFG to determine whether the execution
 of one vertex always, maybe, or never happens before another vertex (see the corresponding [query documentation](${doc_files_1.FlowrWikiBaseRef}/Query-API#happens-before-query) for more information).
 
 
 ${(0, doc_structure_1.section)('Diffing and Testing', 3, 'cfg-diff-and-test')}
 
-As mentioned above, you can use the test function ${(0, doc_types_1.shortLink)('assertCfg', testTypes.info)} to check whether the control flow graph has the desired shape.
-The function supports testing for sub-graphs as well (it provides diffing capabilities similar to ${(0, doc_types_1.shortLink)('assertDataflow', testTypes.info)}).
-If you want to diff two control flow graphs, you can use the ${(0, doc_types_1.shortLink)(diff_cfg_1.diffOfControlFlowGraphs.name, types.info)} function.
+As mentioned above, you can use the test function ${ctx.link('assertCfg')} to check whether the control flow graph has the desired shape.
+The function supports testing for sub-graphs as well (it provides diffing capabilities similar to ${ctx.link('assertDataflow')}).
+If you want to diff two control flow graphs, you can use the ${ctx.link(diff_cfg_1.diffOfControlFlowGraphs)} function.
 
 ${(0, doc_structure_1.section)('Checking Properties', 4, 'cfg-check-properties')}
 
 To be a valid representation of the program, the CFG should satisfy a collection of properties that, in turn, you can automatically assume to hold
-when working with it. In general, we verify these in every unit test using ${(0, doc_types_1.shortLink)(cfg_properties_1.assertCfgSatisfiesProperties.name, types.info)},
-and you can have a look at the active properties by checking the ${(0, doc_types_1.shortLink)('CfgProperties', types.info)} object.
+when working with it. In general, we verify these in every unit test using ${ctx.link(cfg_properties_1.assertCfgSatisfiesProperties)},
+and you can have a look at the active properties by checking the ${ctx.link('CfgProperties')} object.
 In general, we check for a hammock graph (given that the program contains no definite infinite loop) and the absence of direct cycles.
 
 ${(0, doc_structure_1.section)('Sophisticated CFG Traversal', 3, 'cfg-traversal')}
@@ -422,97 +413,97 @@ visitors that incorporate various alternative perspectives:
 
 ${(0, doc_structure_1.section)('Basic CFG Visitor', 4, 'cfg-traversal-basic')}
 
-The ${(0, doc_types_1.shortLink)(basic_cfg_guided_visitor_1.BasicCfgGuidedVisitor.name, types.info)} class essential provides the same functionality as the [simple traversal](#cfg-simple-traversal) functions but in a class-based version.
+The ${ctx.link(basic_cfg_guided_visitor_1.BasicCfgGuidedVisitor)} class essential provides the same functionality as the [simple traversal](#cfg-simple-traversal) functions but in a class-based version.
 Using it, you can select whether you want to traverse the CFG in order or in reverse order.
 
 To replicate the number collector from above, you can use the following code:
 
-${(0, doc_types_1.printCodeOfElement)(types, CollectNumbersVisitor.name)}
+${ctx.code(CollectNumbersVisitor)}
 
-Instead of directly calling ${(0, doc_types_1.shortLink)(simple_visitor_1.visitCfgInOrder.name, types.info)} we pass the \`forward\` visiting order to the constructor of the visitor.
+Instead of directly calling ${ctx.link(simple_visitor_1.visitCfgInOrder)} we pass the \`forward\` visiting order to the constructor of the visitor.
 Executing it with the CFG and AST of the expression \`x - 1 + 2L * 3\`, causes the following numbers to be collected:
 
 ${await (async () => {
-        const res = await (0, doc_cfg_1.getCfg)(shell, 'x - 1 + 2L * 3');
-        const visitor = new CollectNumbersVisitor(res.info, res.ast);
-        visitor.start();
-        const collected = visitor.getNumbers();
-        return collected.map(n => '\n- `' + JSON.stringify(n) + '`').join('');
-    })()}
+            const res = await (0, doc_cfg_1.getCfg)(shell, 'x - 1 + 2L * 3');
+            const visitor = new CollectNumbersVisitor(res.info, res.ast);
+            visitor.start();
+            const collected = visitor.getNumbers();
+            return collected.map(n => '\n- `' + JSON.stringify(n) + '`').join('');
+        })()}
 
 
 ${(0, doc_structure_1.section)('Syntax-Aware CFG Visitor', 4, 'cfg-traversal-syntax')}
 
-The ${(0, doc_types_1.shortLink)(syntax_cfg_guided_visitor_1.SyntaxAwareCfgGuidedVisitor.name, types.info)} class incorporates knowledge of the [normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized-AST) into the CFG traversal and
+The ${ctx.link(syntax_cfg_guided_visitor_1.SyntaxAwareCfgGuidedVisitor)} class incorporates knowledge of the [normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized-AST) into the CFG traversal and
 directly provides specialized visitors for the various node types.
 Now, our running example of collecting all numbers simplifies to this:
 
-${(0, doc_types_1.printCodeOfElement)(types, CollectNumbersSyntaxVisitor.name)}
+${ctx.code(CollectNumbersSyntaxVisitor)}
 
 And again, executing it with the CFG and AST of the expression \`x - 1 + 2L * 3\`, causes the following numbers to be collected:
 
 ${await (async () => {
-        const res = await (0, doc_cfg_1.getCfg)(shell, 'x - 1 + 2L * 3');
-        const visitor = new CollectNumbersSyntaxVisitor(res.info, res.ast);
-        visitor.start();
-        const collected = visitor.getNumbers();
-        return collected.map(n => '\n- `' + JSON.stringify(n) + '`').join('');
-    })()}
+            const res = await (0, doc_cfg_1.getCfg)(shell, 'x - 1 + 2L * 3');
+            const visitor = new CollectNumbersSyntaxVisitor(res.info, res.ast);
+            visitor.start();
+            const collected = visitor.getNumbers();
+            return collected.map(n => '\n- `' + JSON.stringify(n) + '`').join('');
+        })()}
 
 ${(0, doc_structure_1.section)('Dataflow-Aware CFG Visitor', 4, 'cfg-traversal-dfg')}
 
 There is a lot of benefit in incorporating the [dataflow information](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph) into the CFG traversal, as it contains
 information about overwritten function calls, definition targets, and so on.
-Our best friend is the ${(0, doc_types_1.shortLink)(dfg_get_origin_1.getOriginInDfg.name, types.info)} function which provides the important information about the origin of a vertex in the dataflow graph.
-The ${(0, doc_types_1.shortLink)(dfg_cfg_guided_visitor_1.DataflowAwareCfgGuidedVisitor.name, types.info)} class does some of the basic lifting for us.
+Our best friend is the ${ctx.link(dfg_get_origin_1.getOriginInDfg)} function which provides the important information about the origin of a vertex in the dataflow graph.
+The ${ctx.link(dfg_cfg_guided_visitor_1.DataflowAwareCfgGuidedVisitor)} class does some of the basic lifting for us.
 While it is not ideal for our goal of collecting all numbers, it shines in other areas such as collecting all used variables,&nbsp;...
 
-${(0, doc_types_1.printCodeOfElement)(types, CollectNumbersDataflowVisitor.name)}
+${ctx.code(CollectNumbersDataflowVisitor)}
 
 Again, executing it with the CFG and Dataflow of the expression \`x - 1 + 2L * 3\`, causes the following numbers to be collected:
 
 ${await (async () => {
-        const res = await (0, doc_cfg_1.getCfg)(shell, 'x - 1 + 2L * 3');
-        const visitor = new CollectNumbersDataflowVisitor(res.info, res.dataflow.graph);
-        visitor.start();
-        const collected = visitor.getNumbers();
-        return collected.map(n => '\n- `' + JSON.stringify(n) + '`').join('');
-    })()}
+            const res = await (0, doc_cfg_1.getCfg)(shell, 'x - 1 + 2L * 3');
+            const visitor = new CollectNumbersDataflowVisitor(res.info, res.dataflow.graph);
+            visitor.start();
+            const collected = visitor.getNumbers();
+            return collected.map(n => '\n- `' + JSON.stringify(n) + '`').join('');
+        })()}
 
 ${(0, doc_structure_1.section)('Semantic CFG Visitor', 4, 'cfg-traversal-semantic')}
 
-The ${(0, doc_types_1.shortLink)(semantic_cfg_guided_visitor_1.SemanticCfgGuidedVisitor.name, types.info)} class is flowR's most advanced visitor that combines the syntactic and dataflow information.
+The ${ctx.link(semantic_cfg_guided_visitor_1.SemanticCfgGuidedVisitor)} class is flowR's most advanced visitor that combines the syntactic and dataflow information.
 The main idea is simple, it provides special handlers for assignments, conditionals, and other R semantics but still follows
 the structure of the CFG.
 
 ${(0, doc_structure_1.block)({
-        type: 'NOTE',
-        content: `This visitor is still in the design phase so please open up a [new issue](${doc_issue_1.NewIssueUrl}) if you have any suggestions or find any bugs.`
-    })}
+            type: 'NOTE',
+            content: `This visitor is still in the design phase so please open up a [new issue](${doc_issue_1.NewIssueUrl}) if you have any suggestions or find any bugs.`
+        })}
 
 To explore what it is capable of, let's create a visitor that prints all values that are used in assignments:
 
-${(0, doc_types_1.printCodeOfElement)(types, CollectSourcesSemanticVisitor.name)}
+${ctx.code(CollectSourcesSemanticVisitor)}
 
 Executing it with the CFG and Dataflow of the expression \`x <- 2; 3 -> x; assign("x", 42 + 21)\`, causes the following values&nbsp;(/lexemes) to be collected:
 
 ${await (async () => {
-        const res = await (0, doc_cfg_1.getCfg)(shell, 'x <- 2; 3 -> x; assign("x", 42 + 21)');
-        const visitor = new CollectSourcesSemanticVisitor(res.info, res.ast, res.dataflow.graph, config_1.defaultConfigOptions);
-        visitor.start();
-        const collected = visitor.getSources();
-        return collected.map(n => '\n- `' + n + '`').join('');
-    })()}
+            const res = await (0, doc_cfg_1.getCfg)(shell, 'x <- 2; 3 -> x; assign("x", 42 + 21)');
+            const visitor = new CollectSourcesSemanticVisitor(res.info, res.ast, res.dataflow.graph, (0, flowr_analyzer_context_1.contextFromInput)(''));
+            visitor.start();
+            const collected = visitor.getSources();
+            return collected.map(n => '\n- `' + n + '`').join('');
+        })()}
 
 All in all, this visitor offers the following semantic events:
 
 ${
-    /* let's iterate over all methods */
-    Object.getOwnPropertyNames(Object.getPrototypeOf(new semantic_cfg_guided_visitor_1.SemanticCfgGuidedVisitor(undefined)))
-        .filter(n => n !== 'constructor').sort().map(key => {
-        const doc = (0, doc_types_1.getDocumentationForType)(`SemanticCfgGuidedVisitor::${key}`, types.info, '  ');
-        return `- ${(0, doc_types_1.shortLink)(`SemanticCfgGuidedVisitor::${key}`, types.info)}\\\n${doc ?? '_no documentation available_'}\n`;
-    }).join('\n')}
+        /* let's iterate over all methods */
+        Object.getOwnPropertyNames(Object.getPrototypeOf(new semantic_cfg_guided_visitor_1.SemanticCfgGuidedVisitor(undefined)))
+            .filter(n => n !== 'constructor').sort().map(key => {
+            const doc = (0, doc_general_1.prefixLines)(ctx.doc(`SemanticCfgGuidedVisitor::${key}`), '  ');
+            return `- ${ctx.link(`SemanticCfgGuidedVisitor::${key}`)}\\\n${doc ?? '_no documentation available_'}\n`;
+        }).join('\n')}
 
 
 ${(0, doc_structure_1.section)('Working With Exit Points', 3, 'cfg-exit-points')}
@@ -522,49 +513,42 @@ With the [Dataflow Graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph) you
 But the control flow perspective gives you more! Given a simple addition like \`x + 1\`, the CFG looks like this:
 
 ${await (async function () {
-        const cfg = await (0, doc_cfg_1.getCfg)(shell, 'x + 1');
-        const [plusVertexId, plusVertex] = [...cfg.info.graph.vertices()].filter(([n]) => (0, node_id_1.recoverName)(n, cfg.ast.idMap) === '+')[0];
-        (0, assert_1.guard)(plusVertex.type === control_flow_graph_1.CfgVertexType.Expression);
-        const numOfExits = plusVertex.end?.length ?? 0;
-        (0, assert_1.guard)(plusVertex.end && numOfExits === 1);
-        return `${await (0, doc_cfg_1.printCfgCode)(shell, 'x + 1', { showCode: true, prefix: 'flowchart RL\n' })}
+            const cfg = await (0, doc_cfg_1.getCfg)(shell, 'x + 1');
+            const [plusVertexId, plusVertex] = [...cfg.info.graph.vertices()].filter(([n]) => (0, node_id_1.recoverName)(n, cfg.ast.idMap) === '+')[0];
+            (0, assert_1.guard)(plusVertex.type === control_flow_graph_1.CfgVertexType.Expression);
+            const numOfExits = plusVertex.end?.length ?? 0;
+            (0, assert_1.guard)(plusVertex.end && numOfExits === 1);
+            return `${await (0, doc_cfg_1.printCfgCode)(shell, 'x + 1', { showCode: true, prefix: 'flowchart RL\n' })}
 	
 Looking at the binary operation vertex for \`+\` (with id \`${plusVertexId}\`) we see that it is linked to a single exit ("end marker") point: \`${plusVertex.end[0]}\`.
 Checking this vertex essentially reveals all exit points of the expression &dash; in this case, this simply refers to the operands of the addition.
 However, the idea transfers to more complex expressions as well...
 	`;
-    })()}
+        })()}
 
 ${(0, doc_structure_1.details)('Example: Exit Points for an if', await (async function () {
-        const expr = 'if(u) 3 else 2';
-        const cfg = await (0, doc_cfg_1.getCfg)(shell, expr);
-        const [ifVertexId, ifVertex] = [...cfg.info.graph.vertices()].filter(([n]) => (0, node_id_1.recoverName)(n, cfg.ast.idMap) === 'if')[0];
-        (0, assert_1.guard)(ifVertex.type === control_flow_graph_1.CfgVertexType.Statement);
-        const numOfExits = ifVertex.end?.length ?? 0;
-        (0, assert_1.guard)(ifVertex.end && numOfExits === 1);
-        return `${await (0, doc_cfg_1.printCfgCode)(shell, expr, { showCode: true, prefix: 'flowchart RL\n' })}
+            const expr = 'if(u) 3 else 2';
+            const cfg = await (0, doc_cfg_1.getCfg)(shell, expr);
+            const [ifVertexId, ifVertex] = [...cfg.info.graph.vertices()].filter(([n]) => (0, node_id_1.recoverName)(n, cfg.ast.idMap) === 'if')[0];
+            (0, assert_1.guard)(ifVertex.type === control_flow_graph_1.CfgVertexType.Statement);
+            const numOfExits = ifVertex.end?.length ?? 0;
+            (0, assert_1.guard)(ifVertex.end && numOfExits === 1);
+            return `${await (0, doc_cfg_1.printCfgCode)(shell, expr, { showCode: true, prefix: 'flowchart RL\n' })}
 	
 Looking at the if vertex for (with id \`${ifVertexId}\`) we see that it is again linked to a single exit point: \`${ifVertex.end[0]}\`.
 Yet, now this exit vertex is linked to the two branches of the if statement (the \`then\` and \`else\` branch).
 	`;
-    })())}
+        })())}
 
 Hence, you may rely on the corresponding exit point(s) to identify all exits of a given expression (in a way, these exit-points are merely super-sinks trying to ensure the hammock graph property).
 
 ${(0, doc_structure_1.block)({
-        type: 'WARNING',
-        content: 'Using basic blocks, this works just the same. However, please keep in mind that the corresponding exit markers do not (and for control statements usually will not) be part of the same basic block.'
-    })}
+            type: 'WARNING',
+            content: 'Using basic blocks, this works just the same. However, please keep in mind that the corresponding exit markers do not (and for control statements usually will not) be part of the same basic block.'
+        })}
 
 `;
+    }
 }
-if (require.main === module) {
-    (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
-    const shell = new shell_1.RShell();
-    void getText(shell).then(str => {
-        console.log(str);
-    }).finally(() => {
-        shell.close();
-    });
-}
-//# sourceMappingURL=print-cfg-wiki.js.map
+exports.WikiCfg = WikiCfg;
+//# sourceMappingURL=wiki-cfg.js.map

package/documentation/wiki-core.d.ts

@@ -0,0 +1,14 @@
+import { FlowrAnalyzer } from '../project/flowr-analyzer';
+import type { DocMakerArgs } from './wiki-mk/doc-maker';
+import { DocMaker } from './wiki-mk/doc-maker';
+/**
+ * Shows how to inspect the context of an analyzer instance.
+ */
+export declare function inspectContextExample(analyzer: FlowrAnalyzer): void;
+/**
+ * https://github.com/flowr-analysis/flowr/wiki/Core
+ */
+export declare class WikiCore extends DocMaker {
+    constructor();
+    text({ shell, treeSitter, ctx }: DocMakerArgs): Promise<string>;
+}