@eagleoutice/flowr 2.2.11 → 2.2.12

package/dataflow/internal/process/functions/call/built-in/built-in-replacement.js

@@ -6,16 +6,15 @@ const known_call_handling_1 = require("../known-call-handling");
 const log_1 = require("../../../../../../util/log");
 const built_in_assignment_1 = require("./built-in-assignment");
 const common_1 = require("../common");
-const assert_1 = require("../../../../../../util/assert");
 const r_function_call_1 = require("../../../../../../r-bridge/lang-4.x/ast/model/nodes/r-function-call");
 const logger_1 = require("../../../../../logger");
-const vertex_1 = require("../../../../../graph/vertex");
 const graph_1 = require("../../../../../graph/graph");
 const edge_1 = require("../../../../../graph/edge");
-const dfg_1 = require("../../../../../../util/mermaid/dfg");
 const type_1 = require("../../../../../../r-bridge/lang-4.x/ast/model/type");
-const list_access_1 = require("../../../../../../util/list-access");
+const containers_1 = require("../../../../../../util/containers");
 const config_1 = require("../../../../../../config");
+const unpack_argument_1 = require("../argument/unpack-argument");
+const built_in_access_1 = require("./built-in-access");
 function processReplacementFunction(name, 
 /** The last one has to be the value */
 args, rootId, data, config) {
@@ -25,45 +24,38 @@ args, rootId, data, config) {
     }
     /* we only get here if <-, <<-, ... or whatever is part of the replacement is not overwritten */
     (0, log_1.expensiveTrace)(logger_1.dataflowLogger, () => `Replacement ${name.content} with ${JSON.stringify(args)}, processing`);
-    let indices = undefined;
-    if (name.content === '$<-' && (0, config_1.getConfig)().solver.pointerTracking) {
-        const nonEmptyArgs = args.filter(arg => arg !== r_function_call_1.EmptyArgument);
-        const accessedArg = nonEmptyArgs.find(arg => arg.info.role === "accessed" /* RoleInParent.Accessed */);
-        const accessArg = nonEmptyArgs.find(arg => arg.info.role === "index-access" /* RoleInParent.IndexAccess */);
-        if (accessArg !== undefined && accessedArg != undefined) {
-            const leafIndex = { lexeme: accessArg.lexeme, nodeId: accessedArg.info.parent ?? '' };
-            const accessIndices = {
-                indices: [leafIndex],
-                isContainer: false
-            };
-            // Check for nested access
-            if (accessedArg.value?.type === type_1.RType.Access) {
-                indices = (0, list_access_1.constructNestedAccess)(accessedArg.value, accessIndices);
-            }
-            else {
-                // use access node as reference to get complete line in slice
-                indices = [accessIndices];
-            }
-        }
+    let indices = config.activeIndices;
+    if ((0, config_1.getConfig)().solver.pointerTracking) {
+        indices ??= constructAccessedIndices(name.content, args);
     }
     /* we assign the first argument by the last for now and maybe mark as maybe!, we can keep the symbol as we now know we have an assignment */
     const res = (0, built_in_assignment_1.processAssignment)(name, [args[0], args[args.length - 1]], rootId, data, {
         superAssignment: config.assignmentOperator === '<<-',
         makeMaybe: indices !== undefined ? false : config.makeMaybe,
-        indicesCollection: indices
+        indicesCollection: indices,
+        canBeReplacement: true
     });
+    const convertedArgs = config.readIndices ? args.slice(1, -1) : (0, built_in_access_1.symbolArgumentsToStrings)(args.slice(1, -1), 0);
     /* now, we soft-inject other arguments, so that calls like `x[y] <- 3` are linked correctly */
     const { callArgs } = (0, common_1.processAllArguments)({
         functionName: (0, info_1.initializeCleanDataflowInformation)(rootId, data),
-        args: args.slice(1, -1),
+        args: convertedArgs,
         data,
         functionRootId: rootId,
         finalGraph: res.graph,
         forceArgs: config.forceArgs,
     });
-    const fn = res.graph.getVertex(rootId, true);
-    (0, assert_1.guard)(fn?.tag === vertex_1.VertexType.FunctionCall && fn.args.length === 2, () => `Function ${rootId} not found in graph or not 2-arg fn-call (${JSON.stringify(fn)}) ${(0, dfg_1.graphToMermaidUrl)(res.graph)}`);
-    fn.args = [fn.args[0], ...callArgs, fn.args[1]];
+    (0, common_1.patchFunctionCall)({
+        nextGraph: res.graph,
+        data,
+        rootId,
+        name,
+        argumentProcessResult: args.map(a => a === r_function_call_1.EmptyArgument ? undefined : { entryPoint: (0, unpack_argument_1.unpackArgument)(a)?.info.id })
+    });
+    const firstArg = (0, unpack_argument_1.unpackArgument)(args[0])?.info.id;
+    if (firstArg) {
+        res.graph.addEdge(firstArg, rootId, edge_1.EdgeType.DefinedBy | edge_1.EdgeType.Reads);
+    }
     /* a replacement reads all of its call args as well, at least as far as I am aware of */
     for (const arg of callArgs) {
         const ref = (0, graph_1.getReferenceOfArgument)(arg);
@@ -73,4 +65,66 @@ args, rootId, data, config) {
     }
     return res;
 }
+/**
+ * Constructs accessed indices of replacement function recursively.
+ *
+ * Example:
+ * ```r
+ * a$b <- 1
+ * # results in index with lexeme b as identifier
+ *
+ * a[[1]]$b
+ * # results in index with index 1 as identifier with a sub-index with lexeme b as identifier
+ * ```
+ *
+ * @param operation - Operation of replacement function e.g. '$\<-', '[\<-', '[[\<-'
+ * @param args      - Arguments of the replacement function
+ * @returns Accessed indices construct
+ */
+function constructAccessedIndices(operation, args) {
+    const { accessedArg, accessArg } = (0, containers_1.getAccessOperands)(args);
+    if (accessedArg === undefined || accessArg?.value === undefined || !isSupportedOperation(operation, accessArg.value)) {
+        return undefined;
+    }
+    const constructIdentifier = getIdentifierBuilder(operation);
+    const leafIndex = {
+        identifier: constructIdentifier(accessArg),
+        nodeId: accessedArg.info.parent ?? ''
+    };
+    const accessIndices = {
+        indices: [leafIndex],
+        isContainer: false
+    };
+    // Check for nested access
+    let indicesCollection = undefined;
+    if (accessedArg.value?.type === type_1.RType.Access) {
+        indicesCollection = (0, containers_1.constructNestedAccess)(accessedArg.value, accessIndices, constructIdentifier);
+    }
+    else {
+        // use access node as reference to get complete line in slice
+        indicesCollection = [accessIndices];
+    }
+    return indicesCollection;
+}
+function isSupportedOperation(operation, value) {
+    const isNameBasedAccess = (operation === '$<-' || operation === '@<-') && value.type === type_1.RType.Symbol;
+    const isNumericalIndexBasedAccess = (operation === '[[<-' || operation === '[<-') && value.type === type_1.RType.Number;
+    return isNameBasedAccess || isNumericalIndexBasedAccess;
+}
+function getIdentifierBuilder(operation) {
+    if (operation === '$<-' || operation == '@<-') {
+        return (arg) => {
+            return {
+                index: undefined,
+                lexeme: arg.lexeme,
+            };
+        };
+    }
+    // [[<- and [<-
+    return (arg) => {
+        return {
+            index: Number(arg.lexeme),
+        };
+    };
+}
 //# sourceMappingURL=built-in-replacement.js.map

package/dataflow/internal/process/functions/call/built-in/built-in-rm.d.ts

@@ -0,0 +1,7 @@
+import type { DataflowProcessorInformation } from '../../../../../processor';
+import type { DataflowInformation } from '../../../../../info';
+import type { ParentInformation } from '../../../../../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { RFunctionArgument } from '../../../../../../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
+import type { RSymbol } from '../../../../../../r-bridge/lang-4.x/ast/model/nodes/r-symbol';
+import type { NodeId } from '../../../../../../r-bridge/lang-4.x/ast/model/processing/node-id';
+export declare function processRm<OtherInfo>(name: RSymbol<OtherInfo & ParentInformation>, args: readonly RFunctionArgument<OtherInfo & ParentInformation>[], rootId: NodeId, data: DataflowProcessorInformation<OtherInfo & ParentInformation>): DataflowInformation;

package/dataflow/internal/process/functions/call/built-in/built-in-rm.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processRm = processRm;
+const known_call_handling_1 = require("../known-call-handling");
+const r_function_call_1 = require("../../../../../../r-bridge/lang-4.x/ast/model/nodes/r-function-call");
+const logger_1 = require("../../../../../logger");
+const remove_1 = require("../../../../../environments/remove");
+const type_1 = require("../../../../../../r-bridge/lang-4.x/ast/model/type");
+function processRm(name, args, rootId, data) {
+    if (args.length === 0) {
+        logger_1.dataflowLogger.warn('empty rm, skipping');
+        return (0, known_call_handling_1.processKnownFunctionCall)({ name, args, rootId, data }).information;
+    }
+    const res = (0, known_call_handling_1.processKnownFunctionCall)({ name, args, rootId, data }).information;
+    const names = [];
+    for (const arg of args) {
+        if (arg === r_function_call_1.EmptyArgument) {
+            logger_1.dataflowLogger.warn('empty argument in rm, skipping');
+            continue;
+        }
+        const unpacked = arg.value;
+        if (unpacked === undefined || (unpacked.type !== type_1.RType.Symbol && unpacked.type !== type_1.RType.String)) {
+            logger_1.dataflowLogger.warn(`argument is not a symbol or string, skipping ${JSON.stringify(unpacked)}`);
+        }
+        else if (unpacked.type === type_1.RType.Symbol) {
+            names.push(unpacked.content);
+        }
+        else if (unpacked.type === type_1.RType.String) {
+            names.push(unpacked.content.str);
+        }
+    }
+    let env = res.environment;
+    for (const name of names) {
+        env = (0, remove_1.remove)(name, env);
+    }
+    return {
+        ...res,
+        environment: env
+    };
+}
+//# sourceMappingURL=built-in-rm.js.map

package/dataflow/internal/process/functions/call/built-in/built-in-source.js

@@ -103,6 +103,10 @@ function findSource(seed, data) {
     return found;
 }
 function processSourceCall(name, args, rootId, data, config) {
+    if (args.length !== 1) {
+        logger_1.dataflowLogger.warn(`Expected exactly one argument for source currently, but got ${args.length} instead, skipping`);
+        return (0, known_call_handling_1.processKnownFunctionCall)({ name, args, rootId, data }).information;
+    }
     const information = config.includeFunctionCall ?
         (0, known_call_handling_1.processKnownFunctionCall)({ name, args, rootId, data }).information
         : (0, info_1.initializeCleanDataflowInformation)(rootId, data);
@@ -135,12 +139,14 @@ function processSourceCall(name, args, rootId, data, config) {
         if (filepath !== undefined) {
             const request = sourceProvider.createRequest(filepath);
             // check if the sourced file has already been dataflow analyzed, and if so, skip it
-            if (data.referenceChain.find(e => e.request === request.request && e.content === request.content)) {
-                logger_1.dataflowLogger.warn(`Found loop in dataflow analysis for ${JSON.stringify(request)}: ${JSON.stringify(data.referenceChain)}, skipping further dataflow analysis`);
+            const limit = (0, config_1.getConfig)().solver.resolveSource?.repeatedSourceLimit ?? 0;
+            const findCount = data.referenceChain.filter(e => e.request === request.request && e.content === request.content).length;
+            if (findCount > limit) {
+                logger_1.dataflowLogger.warn(`Found cycle (>=${limit + 1}) in dataflow analysis for ${JSON.stringify(request)}: ${JSON.stringify(data.referenceChain)}, skipping further dataflow analysis`);
                 information.graph.markIdForUnknownSideEffects(rootId);
                 return information;
             }
-            return sourceRequest(rootId, request, data, information, (0, decorate_1.sourcedDeterministicCountingIdGenerator)(path, name.location));
+            return sourceRequest(rootId, request, data, information, (0, decorate_1.sourcedDeterministicCountingIdGenerator)((findCount > 0 ? findCount + '::' : '') + path, name.location));
         }
     }
     (0, log_1.expensiveTrace)(logger_1.dataflowLogger, () => `Non-constant argument ${JSON.stringify(sourceFile)} for source is currently not supported, skipping`);
@@ -193,7 +199,13 @@ function sourceRequest(rootId, request, data, information, getId) {
     for (const [k, v] of normalized.idMap) {
         data.completeAst.idMap.set(k, v);
     }
-    return newInformation;
+    return {
+        ...newInformation,
+        in: newInformation.in.concat(dataflow.in),
+        out: newInformation.out.concat(dataflow.out),
+        unknownReferences: newInformation.unknownReferences.concat(dataflow.unknownReferences),
+        exitPoints: dataflow.exitPoints
+    };
 }
 function standaloneSourceFile(inputRequest, data, uniqueSourceId, information) {
     const path = inputRequest.request === 'file' ? inputRequest.content : '-inline-';
@@ -210,6 +222,6 @@ function standaloneSourceFile(inputRequest, data, uniqueSourceId, information) {
         currentRequest: request,
         environment: information.environment,
         referenceChain: [...data.referenceChain, inputRequest]
-    }, information, (0, decorate_1.deterministicPrefixIdGenerator)(path + '@' + uniqueSourceId));
+    }, information, (0, decorate_1.deterministicPrefixIdGenerator)(path + '::' + uniqueSourceId));
 }
 //# sourceMappingURL=built-in-source.js.map

package/dataflow/internal/process/functions/call/built-in/built-in-vector.d.ts

@@ -0,0 +1,15 @@
+import type { RFunctionArgument } from '../../../../../../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
+import type { RSymbol } from '../../../../../../r-bridge/lang-4.x/ast/model/nodes/r-symbol';
+import type { ParentInformation } from '../../../../../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { NodeId } from '../../../../../../r-bridge/lang-4.x/ast/model/processing/node-id';
+import type { DataflowInformation } from '../../../../../info';
+import type { DataflowProcessorInformation } from '../../../../../processor';
+/**
+ * Process a vector call.
+ *
+ * Example:
+ * ```r
+ * c(1, 2, 3, 4)
+ * ```
+ */
+export declare function processVector<OtherInfo>(name: RSymbol<OtherInfo & ParentInformation>, args: readonly RFunctionArgument<OtherInfo & ParentInformation>[], rootId: NodeId, data: DataflowProcessorInformation<OtherInfo & ParentInformation>): DataflowInformation;

package/dataflow/internal/process/functions/call/built-in/built-in-vector.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processVector = processVector;
+const r_function_call_1 = require("../../../../../../r-bridge/lang-4.x/ast/model/nodes/r-function-call");
+const type_1 = require("../../../../../../r-bridge/lang-4.x/ast/model/type");
+const known_call_handling_1 = require("../known-call-handling");
+const config_1 = require("../../../../../../config");
+const containers_1 = require("../../../../../../util/containers");
+/**
+ * Process a vector call.
+ *
+ * Example:
+ * ```r
+ * c(1, 2, 3, 4)
+ * ```
+ */
+function processVector(name, args, rootId, data) {
+    const fnCall = (0, known_call_handling_1.processKnownFunctionCall)({ name, args, rootId, data });
+    if (!(0, config_1.getConfig)().solver.pointerTracking) {
+        return fnCall.information;
+    }
+    const vectorArgs = [];
+    let argIndex = 1;
+    for (const arg of args) {
+        // Skip invalid argument types
+        if (arg === r_function_call_1.EmptyArgument || arg.type !== type_1.RType.Argument || arg.value === undefined) {
+            continue;
+        }
+        if (isPrimitive(arg.value.type)) {
+            vectorArgs.push({
+                identifier: { index: argIndex++ },
+                nodeId: arg.value.info.id,
+            });
+        }
+        else {
+            // Check whether argument value can be resolved
+            let indicesCollection;
+            if (arg.value.type === type_1.RType.Symbol) {
+                indicesCollection = (0, containers_1.resolveIndicesByName)(arg.value.lexeme, data.environment);
+            }
+            else {
+                // Check whether argument is nested container
+                indicesCollection = fnCall.information.graph.getVertex(arg.value.info.id)?.indicesCollection;
+            }
+            const flattenedIndices = indicesCollection?.flatMap(indices => indices.indices)
+                .map(index => {
+                return {
+                    identifier: { index: argIndex++ },
+                    nodeId: index.nodeId,
+                };
+            }) ?? [];
+            vectorArgs.push(...flattenedIndices);
+        }
+    }
+    if ((0, config_1.isOverPointerAnalysisThreshold)(vectorArgs.length)) {
+        return fnCall.information;
+    }
+    const indices = {
+        indices: vectorArgs,
+        isContainer: true,
+    };
+    // Add resolved indices to vertex
+    const vertex = fnCall.information.graph.getVertex(rootId);
+    if (vertex) {
+        vertex.indicesCollection = [indices];
+    }
+    return fnCall.information;
+}
+/**
+ * Checks whether the passed type is primitive i.e. number, logical or string.
+ */
+function isPrimitive(type) {
+    return type === type_1.RType.Number || type === type_1.RType.Logical || type === type_1.RType.String;
+}
+//# sourceMappingURL=built-in-vector.js.map

package/dataflow/internal/process/functions/call/common.d.ts

@@ -34,6 +34,6 @@ export interface PatchFunctionCallInput<OtherInfo> {
     readonly rootId: NodeId;
     readonly name: RSymbol<OtherInfo & ParentInformation>;
     readonly data: DataflowProcessorInformation<OtherInfo & ParentInformation>;
-    readonly argumentProcessResult: readonly (DataflowInformation | undefined)[];
+    readonly argumentProcessResult: readonly (Pick<DataflowInformation, 'entryPoint'> | undefined)[];
 }
 export declare function patchFunctionCall<OtherInfo>({ nextGraph, rootId, name, data, argumentProcessResult }: PatchFunctionCallInput<OtherInfo>): void;

package/dataflow/internal/process/functions/call/common.js

@@ -64,9 +64,12 @@ function processAllArguments({ functionName, args, data, finalGraph, functionRoo
         }
         processedArguments.push(processed);
         finalEnv = (0, overwrite_1.overwriteEnvironment)(finalEnv, processed.environment);
+        finalGraph.mergeWith(processed.graph);
         // resolve reads within argument, we resolve before adding the `processed.environment` to avoid cyclic dependencies
         for (const ingoing of [...processed.in, ...processed.unknownReferences]) {
-            const tryToResolve = ingoing.name ? (0, resolve_by_name_1.resolveByName)(ingoing.name, argEnv, identifier_1.ReferenceType.Unknown) : undefined;
+            // check if it is called directly
+            const vtx = finalGraph.getVertex(ingoing.nodeId);
+            const tryToResolve = ingoing.name ? (0, resolve_by_name_1.resolveByName)(ingoing.name, argEnv, vtx?.tag === vertex_1.VertexType.FunctionCall ? identifier_1.ReferenceType.Function : identifier_1.ReferenceType.Unknown) : undefined;
             if (tryToResolve === undefined) {
                 remainingReadInArgs.push(ingoing);
             }
@@ -90,7 +93,6 @@ function processAllArguments({ functionName, args, data, finalGraph, functionRoo
             }
         }
         argEnv = (0, overwrite_1.overwriteEnvironment)(argEnv, processed.environment);
-        finalGraph.mergeWith(processed.graph);
         if (arg.type !== type_1.RType.Argument || !arg.name) {
             callArgs.push({ nodeId: processed.entryPoint, controlDependencies: undefined, type: identifier_1.ReferenceType.Argument });
         }

package/dataflow/internal/process/functions/call/named-call-handling.d.ts

@@ -4,4 +4,6 @@ import type { ParentInformation } from '../../../../../r-bridge/lang-4.x/ast/mod
 import type { RFunctionArgument } from '../../../../../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
 import type { RSymbol } from '../../../../../r-bridge/lang-4.x/ast/model/nodes/r-symbol';
 import type { NodeId } from '../../../../../r-bridge/lang-4.x/ast/model/processing/node-id';
+import type { DataflowGraph } from '../../../../graph/graph';
+export declare function markAsOnlyBuiltIn(graph: DataflowGraph, rootId: NodeId): void;
 export declare function processNamedCall<OtherInfo>(name: RSymbol<OtherInfo & ParentInformation>, args: readonly RFunctionArgument<OtherInfo & ParentInformation>[], rootId: NodeId, data: DataflowProcessorInformation<OtherInfo & ParentInformation>): DataflowInformation;

package/dataflow/internal/process/functions/call/named-call-handling.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.markAsOnlyBuiltIn = markAsOnlyBuiltIn;
 exports.processNamedCall = processNamedCall;
 const info_1 = require("../../../../info");
 const known_call_handling_1 = require("./known-call-handling");
@@ -27,6 +28,13 @@ function processDefaultFunctionProcessor(information, name, args, rootId, data)
     const call = (0, known_call_handling_1.processKnownFunctionCall)({ name, args, rootId, data, forceArgs: (resolve?.length ?? 0) > 0 ? undefined : 'all' });
     return mergeInformation(information, call.information);
 }
+function markAsOnlyBuiltIn(graph, rootId) {
+    const v = graph.getVertex(rootId);
+    if (v?.tag === vertex_1.VertexType.FunctionCall) {
+        v.onlyBuiltin = true;
+        v.environment = undefined;
+    }
+}
 function processNamedCall(name, args, rootId, data) {
     const resolved = (0, resolve_by_name_1.resolveByName)(name.content, data.environment, identifier_1.ReferenceType.Function) ?? [];
     let defaultProcessor = resolved.length === 0;
@@ -46,11 +54,7 @@ function processNamedCall(name, args, rootId, data) {
     }
     else if (information && builtIn) {
         // mark the function call as built in only
-        const v = information.graph.getVertex(rootId);
-        if (v?.tag === vertex_1.VertexType.FunctionCall) {
-            v.onlyBuiltin = true;
-            v.environment = undefined;
-        }
+        markAsOnlyBuiltIn(information.graph, rootId);
     }
     return information ?? (0, info_1.initializeCleanDataflowInformation)(rootId, data);
 }

package/dataflow/internal/process/process-named-call.d.ts

@@ -3,4 +3,7 @@ import type { DataflowInformation } from '../../info';
 import type { Base, RNode, Location } from '../../../r-bridge/lang-4.x/ast/model/model';
 import type { ParentInformation } from '../../../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { EmptyArgument } from '../../../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
+/**
+ * Helper function for {@link processNamedCall} using the given `functionName` as the name of the function.
+ */
 export declare function processAsNamedCall<OtherInfo>(functionName: RNode<OtherInfo & ParentInformation> & Base<OtherInfo> & Location, data: DataflowProcessorInformation<OtherInfo & ParentInformation>, name: string, args: readonly (RNode<OtherInfo & ParentInformation> | typeof EmptyArgument | undefined)[]): DataflowInformation;

package/dataflow/internal/process/process-named-call.js

@@ -4,6 +4,9 @@ exports.processAsNamedCall = processAsNamedCall;
 const named_call_handling_1 = require("./functions/call/named-call-handling");
 const make_argument_1 = require("./functions/call/argument/make-argument");
 const type_1 = require("../../../r-bridge/lang-4.x/ast/model/type");
+/**
+ * Helper function for {@link processNamedCall} using the given `functionName` as the name of the function.
+ */
 function processAsNamedCall(functionName, data, name, args) {
     return (0, named_call_handling_1.processNamedCall)({
         type: type_1.RType.Symbol,

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

@@ -1,7 +1,16 @@
 import type { ControlFlowInformation } from '../../util/cfg/cfg';
-import type { RShell } from '../../r-bridge/shell';
 import type { NormalizedAst } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
-export declare function getCfg(shell: RShell, code: string): Promise<{
+import type { KnownParser } from '../../r-bridge/parser';
+import type { DataflowInformation } from '../../dataflow/info';
+export declare function getCfg(parser: KnownParser, code: string): Promise<{
     info: ControlFlowInformation;
     ast: NormalizedAst;
+    dataflow: DataflowInformation;
 }>;
+export declare function printCfg(cfg: ControlFlowInformation, ast: NormalizedAst, prefix?: string): string;
+export interface PrintCfgOptions {
+    readonly showCode?: boolean;
+    readonly openCode?: boolean;
+    readonly prefix?: string;
+}
+export declare function printCFGCode(parser: KnownParser, code: string, { showCode, openCode, prefix }?: PrintCfgOptions): Promise<string>;

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

@@ -1,18 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCfg = getCfg;
+exports.printCfg = printCfg;
+exports.printCFGCode = printCFGCode;
 const cfg_1 = require("../../util/cfg/cfg");
-const pipeline_executor_1 = require("../../core/pipeline-executor");
 const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
 const retriever_1 = require("../../r-bridge/retriever");
-async function getCfg(shell, code) {
-    const steps = await new pipeline_executor_1.PipelineExecutor(default_pipelines_1.DEFAULT_DATAFLOW_PIPELINE, {
-        parser: shell,
+const time_1 = require("../../util/time");
+const doc_files_1 = require("./doc-files");
+const cfg_2 = require("../../util/mermaid/cfg");
+const doc_code_1 = require("./doc-code");
+async function getCfg(parser, code) {
+    const result = await (0, default_pipelines_1.createDataflowPipeline)(parser, {
         request: (0, retriever_1.requestFromInput)(code)
     }).allRemainingSteps();
+    const cfg = (0, cfg_1.extractCFG)(result.normalize, result.dataflow.graph);
     return {
-        info: (0, cfg_1.extractCFG)(steps.normalize, steps.dataflow?.graph),
-        ast: steps.normalize
+        info: cfg,
+        ast: result.normalize,
+        dataflow: result.dataflow
     };
 }
+function printCfg(cfg, ast, prefix = 'flowchart TD\n') {
+    return `
+${(0, doc_code_1.codeBlock)('mermaid', (0, cfg_2.cfgToMermaid)(cfg, ast, prefix))}
+	`;
+}
+async function printCFGCode(parser, code, { showCode = true, openCode = false, prefix = 'flowchart BT\n' } = {}) {
+    const now = performance.now();
+    const res = await getCfg(parser, code);
+    const duration = performance.now() - now;
+    const metaInfo = `The analysis required _${(0, time_1.printAsMs)(duration)}_ (including the dataflow analysis, normalization, and parsing with the [${parser.name}](${doc_files_1.FlowrWikiBaseRef}/Engines) engine) within the generation environment.`;
+    return '\n\n' + printCfg(res.info, res.ast, prefix) + (showCode ? `
+<details${openCode ? ' open' : ''}>
+
+<summary style="color:gray">R Code of the CFG</summary>
+
+${metaInfo}
+
+${(0, doc_code_1.codeBlock)('r', code)}
+
+</details>
+
+` : '\n(' + metaInfo + ')\n\n');
+}
 //# sourceMappingURL=doc-cfg.js.map

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

@@ -4,17 +4,25 @@ exports.codeBlock = codeBlock;
 exports.codeInline = codeInline;
 exports.jsonWithLimit = jsonWithLimit;
 const json_1 = require("../../util/json");
+const environment_1 = require("../../dataflow/environments/environment");
 function codeBlock(language, code) {
     return `\n\`\`\`${language}\n${code?.trim() ?? ''}\n\`\`\`\n`;
 }
 function codeInline(code) {
     return `<code>${code}</code>`;
 }
-function jsonWithLimit(object, maxLength = 5_000, tooLongText = '_As the code is pretty long, we inhibit pretty printing and syntax highlighting (JSON):_') {
+function jsonWithLimit(object, maxLength = 5_000, tooLongText = '_As the code is pretty long, we inhibit pretty printing and syntax highlighting (JSON, hiding built-in):_') {
     const prettyPrinted = JSON.stringify(object, json_1.jsonReplacer, 2);
     return `
 ${prettyPrinted.length > maxLength ? tooLongText : ''}
-${codeBlock(prettyPrinted.length > maxLength ? 'text' : 'json', prettyPrinted.length > 5_000 ? JSON.stringify(object, json_1.jsonReplacer) : prettyPrinted)}
+${codeBlock(prettyPrinted.length > maxLength ? 'text' : 'json', prettyPrinted.length > 5_000 ? JSON.stringify(object, (k, v) => {
+        if (typeof v === 'object' && v !== null && 'id' in v && v['id'] === 0 && 'memory' in v && v['memory']) {
+            return '<BuiltInEnvironment>';
+        }
+        else {
+            return (0, environment_1.builtInEnvJsonReplacer)(k, v);
+        }
+    }) : prettyPrinted)}
 `;
 }
 //# sourceMappingURL=doc-code.js.map

package/documentation/print-capabilities-markdown.js

@@ -86,7 +86,7 @@ async function printSingleCapability(info, depth, index, capability) {
     if (capability.url) {
         nextLine += '\\\nSee ' + (0, strings_1.joinWithLast)(capability.url.map(({ name, href }) => `[${name}](${href})`)) + ' for more info.';
     }
-    nextLine += ' Internal ID: `' + capability.id + '`';
+    nextLine += ' (internal ID: `' + capability.id + '`)';
     if (capability.example) {
         nextLine += `\n${(0, doc_general_1.prefixLines)(typeof capability.example === 'string' ? capability.example : await capability.example(info.parser), nextLineIndent + '> ')}`;
     }

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

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

package/documentation/print-cfg-wiki.js

@@ -0,0 +1,84 @@
+"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"));
+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");
+const doc_issue_1 = require("./doc-util/doc-issue");
+const doc_cfg_1 = require("./doc-util/doc-cfg");
+const visitor_1 = require("../util/cfg/visitor");
+async function getText(shell) {
+    const rversion = (await shell.usedRVersion())?.format() ?? 'unknown';
+    const types = (0, doc_types_1.getTypesFromFolderAsMermaid)({
+        rootFolder: path_1.default.resolve('./src'),
+        typeName: 'RNode',
+        inlineTypes: doc_types_1.mermaidHide
+    });
+    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'control flow graph', rVersion: rversion })}
+
+_flowR_ produces two 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). However, for further analyses, we also provide an explicit control flow graph 
+that is calculated from the normalized AST **and** the dataflow graph to incorporate change in language semantics.
+flowR also uses this CFG for some of its queries (e.g., to link to the last call in a [Call-Context Query](${doc_files_1.FlowrWikiBaseRef}/Query-API))
+but does not incorporate it into its core analysis.
+
+
+${(0, doc_structure_1.block)({
+        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).`
+    })}
+
+The CFG may be a little bit uncommon compared to the classical CFG with basic blocks. This is mostly due to historical reasons. 
+Please [open a new issue](${doc_issue_1.NewIssueUrl}) if you are interested in such a perspective.
+
+But for now, let's look at a simple CFG for a program without any branching:
+
+${(0, doc_code_1.codeBlock)('r', 'x <- 2 * 3 + 1')}
+
+The corresponding CFG is a directed, labeled graph with two types of edges (control and flow dependencies):
+
+${await (0, doc_cfg_1.printCFGCode)(shell, 'x <- 2 * 3 + 1', { showCode: false, prefix: 'flowchart RL\n' })}
+
+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)).
+Higher expressions, such as \`2 * 3\` get an additional node with an artificial id that ends in \`-exit\` to mark whenever their calculation is over.
+
+To gain a better understanding, let's have a look at a simple program with a single branching structure:
+
+${await (0, doc_cfg_1.printCFGCode)(shell, 'if(u) 3 else 2', { showCode: true, openCode: true, prefix: 'flowchart RL\n' })}
+
+Here, you can see the \`if\` node followed by the condition (in this case merely \`u\`) that then splits into two branches for the two possible outcomes.
+The \`if\` structure is terminated by the corresponding \`-exit\` node.
+
+For you to compare, the following shows the CFG of an \`if\` without an \`else\` branch:
+
+${await (0, doc_cfg_1.printCFGCode)(shell, 'if(u || v) 3', { showCode: true, openCode: false, prefix: 'flowchart RL\n' })}
+
+The control flow graph also harmonizes with function definitions, and calls:
+
+${await (0, doc_cfg_1.printCFGCode)(shell, 'f <- function() { 3 }\nf()', { showCode: true, openCode: true, prefix: 'flowchart RL\n' })}
+
+In general, it is probably best to use the ${(0, doc_cli_option_1.getReplCommand)('controlflow*')} command in the REPL to investigate the CFG interactively.
+Have a look at the ${(0, doc_types_1.shortLink)(visitor_1.visitCfgInReverseOrder.name, types.info)} function for a generic CFG visitor.
+
+`;
+}
+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