@eagleoutice/flowr 2.1.8 → 2.1.9

package/dataflow/graph/graph.d.ts

@@ -1,5 +1,4 @@
-import type { DataflowGraphEdge } from './edge';
-import { EdgeType } from './edge';
+import type { DataflowGraphEdge, EdgeType } from './edge';
 import type { DataflowInformation } from '../info';
 import type { DataflowGraphVertexArgument, DataflowGraphVertexFunctionCall, DataflowGraphVertexInfo } from './vertex';
 import { EmptyArgument } from '../../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
@@ -7,30 +6,56 @@ import type { IdentifierDefinition, IdentifierReference } from '../environments/
 import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { AstIdMap } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { LinkTo } from '../../queries/catalog/call-context-query/call-context-query-format';
+/**
+ * Describes the information we store per function body.
+ * The {@link DataflowFunctionFlowInformation#exitPoints} are stored within the enclosing {@link DataflowGraphVertexFunctionDefinition} vertex.
+ */
 export type DataflowFunctionFlowInformation = Omit<DataflowInformation, 'graph' | 'exitPoints'> & {
     graph: Set<NodeId>;
 };
 /**
+ * A reference with a name, e.g. `a` and `b` in the following function call:
+ *
  * ```r
  * foo(a = 3, b = 2)
  * ```
+ *
+ * @see #isNamedArgument
+ * @see PositionalFunctionArgument
  */
 export interface NamedFunctionArgument extends IdentifierReference {
     readonly name: string;
 }
 /**
+ * A reference which does not have a name, like the references to the arguments `3` and `2` in the following:
+ *
  * ```r
  * foo(3, 2)
  * ```
+ *
+ * @see #isPositionalArgument
+ * @see NamedFunctionArgument
  */
 export interface PositionalFunctionArgument extends Omit<IdentifierReference, 'name'> {
     readonly name?: undefined;
 }
 /** Summarizes either named (`foo(a = 3, b = 2)`), unnamed (`foo(3, 2)`), or empty (`foo(,)`) arguments within a function. */
 export type FunctionArgument = NamedFunctionArgument | PositionalFunctionArgument | typeof EmptyArgument;
+/**
+ * Check if the given argument is a {@link PositionalFunctionArgument}.
+ */
 export declare function isPositionalArgument(arg: FunctionArgument): arg is PositionalFunctionArgument;
+/**
+ * Check if the given argument is a {@link NamedFunctionArgument}.
+ */
 export declare function isNamedArgument(arg: FunctionArgument): arg is NamedFunctionArgument;
+/**
+ * Returns the reference of a non-empty argument.
+ */
 export declare function getReferenceOfArgument(arg: FunctionArgument): NodeId | undefined;
+/**
+ * A reference that is enough to indicate start and end points of an edge within the dataflow graph.
+ */
 type ReferenceForEdge = Pick<IdentifierReference, 'nodeId' | 'controlDependencies'> | IdentifierDefinition;
 /**
  * Maps the edges target to the edge information
@@ -41,11 +66,20 @@ export type OutgoingEdges<Edge extends DataflowGraphEdge = DataflowGraphEdge> =
  * In other words, it maps the source to the edge information.
  */
 export type IngoingEdges<Edge extends DataflowGraphEdge = DataflowGraphEdge> = Map<NodeId, Edge>;
+/**
+ * The structure of the serialized {@link DataflowGraph}.
+ */
 export interface DataflowGraphJson {
     readonly rootVertices: NodeId[];
     readonly vertexInformation: [NodeId, DataflowGraphVertexInfo][];
     readonly edgeInformation: [NodeId, [NodeId, DataflowGraphEdge][]][];
 }
+/**
+ * An unknown side effect describes something that we cannot handle correctly (in all cases).
+ * For example, `eval` will be marked as an unknown side effect as we have no idea of how it will affect the program.
+ * Linked side effects are used whenever we know that a call may be affected by another one in a way that we cannot
+ * grasp from the dataflow perspective (e.g., an indirect dependency based on the currently active graphic device).
+ */
 export type UnknownSidEffect = NodeId | {
     id: NodeId;
     linkTo: LinkTo<RegExp>;
@@ -60,6 +94,11 @@ export type UnknownSidEffect = NodeId | {
  * However, this does not have to hold during the construction as edges may point from or to vertices which are yet to be constructed.
  *
  * All methods return the modified graph to allow for chaining.
+ *
+ * @see {@link DataflowGraph#addEdge|`addEdge`} - to add an edge to the graph
+ * @see {@link DataflowGraph#addVertex|`addVertex`} - to add a vertex to the graph
+ * @see {@link DataflowGraph#fromJson|`fromJson`} - to construct a dataflow graph object from a deserialized JSON object.
+ * @see {@link emptyGraph} - to create an empty graph (useful in tests)
  */
 export declare class DataflowGraph<Vertex extends DataflowGraphVertexInfo = DataflowGraphVertexInfo, Edge extends DataflowGraphEdge = DataflowGraphEdge> {
     private static DEFAULT_ENVIRONMENT;
@@ -144,7 +183,6 @@ export declare class DataflowGraph<Vertex extends DataflowGraphVertexInfo = Data
     addEdge(from: ReferenceForEdge, to: ReferenceForEdge, type: EdgeType): this;
     /** {@inheritDoc} */
     addEdge(from: NodeId | ReferenceForEdge, to: NodeId | ReferenceForEdge, type: EdgeType): this;
-    private installEdge;
     /**
      * Merges the other graph into *this* one (in-place). The return value is only for convenience.
      *

package/dataflow/graph/graph.js

@@ -5,7 +5,6 @@ exports.isPositionalArgument = isPositionalArgument;
 exports.isNamedArgument = isNamedArgument;
 exports.getReferenceOfArgument = getReferenceOfArgument;
 const assert_1 = require("../../util/assert");
-const edge_1 = require("./edge");
 const diff_1 = require("./diff");
 const vertex_1 = require("./vertex");
 const arrays_1 = require("../../util/arrays");
@@ -16,23 +15,27 @@ const clone_1 = require("../environments/clone");
 const json_1 = require("../../util/json");
 const built_in_1 = require("../environments/built-in");
 const logger_1 = require("../logger");
+/**
+ * Check if the given argument is a {@link PositionalFunctionArgument}.
+ */
 function isPositionalArgument(arg) {
     return arg !== r_function_call_1.EmptyArgument && arg.name === undefined;
 }
+/**
+ * Check if the given argument is a {@link NamedFunctionArgument}.
+ */
 function isNamedArgument(arg) {
     return arg !== r_function_call_1.EmptyArgument && arg.name !== undefined;
 }
+/**
+ * Returns the reference of a non-empty argument.
+ */
 function getReferenceOfArgument(arg) {
     if (arg !== r_function_call_1.EmptyArgument) {
-        return arg.nodeId;
+        return arg?.nodeId;
     }
     return undefined;
 }
-function extractEdgeIds(from, to) {
-    const fromId = typeof from === 'object' ? from.nodeId : from;
-    const toId = typeof to === 'object' ? to.nodeId : to;
-    return { fromId, toId };
-}
 /**
  * The dataflow graph holds the dataflow information found within the given AST.
  * We differentiate the directed edges in {@link EdgeType} and the vertices indicated by {@link DataflowGraphVertexArgument}
@@ -43,6 +46,11 @@ function extractEdgeIds(from, to) {
  * However, this does not have to hold during the construction as edges may point from or to vertices which are yet to be constructed.
  *
  * All methods return the modified graph to allow for chaining.
+ *
+ * @see {@link DataflowGraph#addEdge|`addEdge`} - to add an edge to the graph
+ * @see {@link DataflowGraph#addVertex|`addVertex`} - to add a vertex to the graph
+ * @see {@link DataflowGraph#fromJson|`fromJson`} - to construct a dataflow graph object from a deserialized JSON object.
+ * @see {@link emptyGraph} - to create an empty graph (useful in tests)
  */
 class DataflowGraph {
     static DEFAULT_ENVIRONMENT = undefined;
@@ -185,13 +193,10 @@ class DataflowGraph {
         return this;
     }
     /**
-     * Will insert a new edge into the graph,
-     * if the direction of the edge is of no importance (`same-read-read` or `same-def-def`), source
-     * and target will be sorted so that `from` has the lower, and `to` the higher id (default ordering).
      * Please note that this will never make edges to {@link BuiltIn} as they are not part of the graph.
      */
     addEdge(from, to, type) {
-        const { fromId, toId } = extractEdgeIds(from, to);
+        const [fromId, toId] = extractEdgeIds(from, to);
         if (fromId === toId || toId === built_in_1.BuiltIn) {
             return this;
         }
@@ -206,7 +211,6 @@ class DataflowGraph {
             else {
                 existingFrom.set(toId, edge);
             }
-            this.installEdge(type, toId, fromId, edge);
         }
         else {
             // adding the type
@@ -214,21 +218,6 @@ class DataflowGraph {
         }
         return this;
     }
-    installEdge(type, toId, fromId, edge) {
-        if (type === edge_1.EdgeType.DefinesOnCall) {
-            const otherEdge = {
-                ...edge,
-                types: edge_1.EdgeType.DefinedByOnCall
-            };
-            const existingTo = this.edgeInformation.get(toId);
-            if (existingTo === undefined) {
-                this.edgeInformation.set(toId, new Map([[fromId, otherEdge]]));
-            }
-            else {
-                existingTo.set(fromId, otherEdge);
-            }
-        }
-    }
     /**
      * Merges the other graph into *this* one (in-place). The return value is only for convenience.
      *
@@ -269,7 +258,7 @@ class DataflowGraph {
                         existing.set(target, edge);
                     }
                     else {
-                        get.types = get.types | edge.types;
+                        get.types |= edge.types;
                     }
                 }
             }
@@ -304,8 +293,17 @@ class DataflowGraph {
         const vertex = this.getVertex(from, true);
         (0, assert_1.guard)(vertex !== undefined, () => `node must be defined for ${from} to add control dependency`);
         vertex.controlDependencies ??= [];
-        if (to && vertex.controlDependencies.every(({ id, when: cond }) => id !== to && when !== cond)) {
-            vertex.controlDependencies.push({ id: to, when });
+        if (to) {
+            let hasControlDependency = false;
+            for (const { id, when: cond } of vertex.controlDependencies) {
+                if (id === to && when !== cond) {
+                    hasControlDependency = true;
+                    break;
+                }
+            }
+            if (!hasControlDependency) {
+                vertex.controlDependencies.push({ id: to, when });
+            }
         }
         return this;
     }
@@ -334,8 +332,8 @@ class DataflowGraph {
 exports.DataflowGraph = DataflowGraph;
 function mergeNodeInfos(current, next) {
     if (current.tag !== next.tag) {
-        logger_1.dataflowLogger.warn(`nodes to be joined for the same id should have the same tag, but ${JSON.stringify(current, json_1.jsonReplacer)} vs. ${JSON.stringify(next, json_1.jsonReplacer)} -- we are currently not handling cases in which vertices may be either! Keeping current.`);
-        return { ...current };
+        logger_1.dataflowLogger.warn(() => `nodes to be joined for the same id should have the same tag, but ${JSON.stringify(current, json_1.jsonReplacer)} vs. ${JSON.stringify(next, json_1.jsonReplacer)} -- we are currently not handling cases in which vertices may be either! Keeping current.`);
+        return current;
     }
     if (current.tag === vertex_1.VertexType.VariableDefinition) {
         (0, assert_1.guard)(current.scope === next.scope, 'nodes to be joined for the same id must have the same scope');
@@ -347,7 +345,14 @@ function mergeNodeInfos(current, next) {
         (0, assert_1.guard)(current.scope === next.scope, 'nodes to be joined for the same id must have the same scope');
         (0, assert_1.guard)((0, arrays_1.arrayEqual)(current.exitPoints, next.exitPoints), 'nodes to be joined must have same exist points');
     }
-    // make a copy
-    return { ...current };
+    return current;
+}
+/**
+ * Returns the ids of the dataflow vertices referenced by a {@link ReferenceForEdge}.
+ */
+function extractEdgeIds(from, to) {
+    const fromId = typeof from === 'object' ? from.nodeId : from;
+    const toId = typeof to === 'object' ? to.nodeId : to;
+    return [fromId, toId];
 }
 //# sourceMappingURL=graph.js.map

package/dataflow/graph/vertex.d.ts

@@ -3,7 +3,6 @@ import type { DataflowFunctionFlowInformation, FunctionArgument } from './graph'
 import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { REnvironmentInformation } from '../environments/environment';
 import type { ControlDependency } from '../info';
-export type DataflowGraphVertices<Vertex extends DataflowGraphVertexInfo = DataflowGraphVertexInfo> = Map<NodeId, Vertex>;
 export declare enum VertexType {
     Value = "value",
     Use = "use",
@@ -12,7 +11,7 @@ export declare enum VertexType {
     FunctionDefinition = "function-definition"
 }
 /**
- * Arguments required to construct a vertex in the dataflow graph.
+ * Arguments required to construct a vertex in the {@link DataflowGraph|dataflow graph}.
  *
  * @see DataflowGraphVertexUse
  * @see DataflowGraphVertexVariableDefinition
@@ -24,7 +23,9 @@ interface DataflowGraphVertexBase extends MergeableRecord {
      */
     readonly tag: VertexType;
     /**
-     * The id of the node (the id assigned by the {@link ParentInformation} decoration)
+     * The id of the node (the id assigned by the {@link ParentInformation} decoration).
+     * This unanimously identifies the vertex in the {@link DataflowGraph|dataflow graph}
+     * as well as the corresponding {@link NormalizedAst|normalized AST}.
      */
     id: NodeId;
     /**
@@ -32,19 +33,40 @@ interface DataflowGraphVertexBase extends MergeableRecord {
      */
     environment?: REnvironmentInformation | undefined;
     /**
-     * See {@link IdentifierReference}
+     * @see {@link ControlDependency} - the collection of control dependencies which have an influence on whether the vertex is executed.
      */
     controlDependencies: ControlDependency[] | undefined;
 }
 /**
  * Marker vertex for a value in the dataflow of the program.
+ * This does not contain the _value_ of the referenced constant
+ * as this is available with the {@link DataflowGraphVertexBase#id|id} in the {@link NormalizedAst|normalized AST}
+ * (or more specifically the {@link AstIdMap}).
+ *
+ * If you have a {@link DataflowGraph|dataflow graph} named `graph`
+ * with an {@link AstIdMap} and a value vertex object with name `value` the following Code should work:
+ *
+ * @example
+ * ```ts
+ * const node = graph.idMap.get(value.id)
+ * ```
+ *
+ * This then returns the corresponding node in the {@link NormalizedAst|normalized AST}, for example,
+ * an {@link RNumber} or {@link RString}.
+ *
+ * This works similarly for {@link IdentifierReference|identifier references}
+ * for which you can use the {@link IdentifierReference#nodeId|`nodeId`}.
+ *
+ * @see {@link isValueVertex} - to check if a vertex is a value vertex
  */
 export interface DataflowGraphVertexValue extends DataflowGraphVertexBase {
     readonly tag: VertexType.Value;
     readonly environment?: undefined;
 }
 /**
- * Arguments required to construct a vertex which represents the usage of a variable in the dataflow graph.
+ * Arguments required to construct a vertex which represents the usage of a variable in the {@link DataflowGraph|dataflow graph}.
+ *
+ * @see {@link isUseVertex} - to check if a vertex is a use vertex
  */
 export interface DataflowGraphVertexUse extends DataflowGraphVertexBase {
     readonly tag: VertexType.Use;
@@ -52,7 +74,9 @@ export interface DataflowGraphVertexUse extends DataflowGraphVertexBase {
     readonly environment?: undefined;
 }
 /**
- * Arguments required to construct a vertex which represents the usage of a variable in the dataflow graph.
+ * Arguments required to construct a vertex which represents the usage of a variable in the {@link DataflowGraph|dataflow graph}.
+ *
+ * @see {@link isFunctionCallVertex} - to check if a vertex is a function call vertex
  */
 export interface DataflowGraphVertexFunctionCall extends DataflowGraphVertexBase {
     readonly tag: VertexType.FunctionCall;
@@ -71,13 +95,20 @@ export interface DataflowGraphVertexFunctionCall extends DataflowGraphVertexBase
     environment: REnvironmentInformation | undefined;
 }
 /**
- * Arguments required to construct a vertex which represents the definition of a variable in the dataflow graph.
+ * Arguments required to construct a vertex which represents the definition of a variable in the {@link DataflowGraph|dataflow graph}.
+ *
+ * @see {@link isVariableDefinitionVertex} - to check if a vertex is a variable definition vertex
  */
 export interface DataflowGraphVertexVariableDefinition extends DataflowGraphVertexBase {
     readonly tag: VertexType.VariableDefinition;
     /** Does not require an environment, those are attached to the call */
     readonly environment?: undefined;
 }
+/**
+ * Arguments required to construct a vertex which represents the definition of a function in the {@link DataflowGraph|dataflow graph}.
+ *
+ * @see {@link isFunctionDefinitionVertex} - to check if a vertex is a function definition vertex
+ */
 export interface DataflowGraphVertexFunctionDefinition extends DataflowGraphVertexBase {
     readonly tag: VertexType.FunctionDefinition;
     /**
@@ -93,11 +124,39 @@ export interface DataflowGraphVertexFunctionDefinition extends DataflowGraphVert
     exitPoints: readonly NodeId[];
     environment?: REnvironmentInformation;
 }
+/**
+ * What is to be passed to construct a vertex in the {@link DataflowGraph|dataflow graph}
+ */
 export type DataflowGraphVertexArgument = DataflowGraphVertexUse | DataflowGraphVertexVariableDefinition | DataflowGraphVertexFunctionDefinition | DataflowGraphVertexFunctionCall | DataflowGraphVertexValue;
+/**
+ * This is the union type of all possible vertices that appear within a {@link DataflowGraph|dataflow graph},
+ * they can be constructed passing a {@link DataflowGraphVertexArgument} to the graph.
+ *
+ * See {@link DataflowGraphVertices} for an id-based mapping.
+ */
 export type DataflowGraphVertexInfo = Required<DataflowGraphVertexArgument>;
+/**
+ * A mapping of {@link NodeId}s to {@link DataflowGraphVertexInfo|vertices}.
+ */
+export type DataflowGraphVertices<Vertex extends DataflowGraphVertexInfo = DataflowGraphVertexInfo> = Map<NodeId, Vertex>;
+/**
+ * Check if the given vertex is a {@link DataflowGraphVertexValue|value vertex}.
+ */
 export declare function isValueVertex(vertex: DataflowGraphVertexBase): vertex is DataflowGraphVertexValue;
+/**
+ * Check if the given vertex is a {@link DataflowGraphVertexUse|use vertex}.
+ */
 export declare function isUseVertex(vertex: DataflowGraphVertexBase): vertex is DataflowGraphVertexUse;
+/**
+ * Check if the given vertex is a {@link DataflowGraphVertexFunctionCall|function call vertex}.
+ */
 export declare function isFunctionCallVertex(vertex: DataflowGraphVertexBase): vertex is DataflowGraphVertexFunctionCall;
+/**
+ * Check if the given vertex is a {@link DataflowGraphVertexVariableDefinition|variable definition vertex}.
+ */
 export declare function isVariableDefinitionVertex(vertex: DataflowGraphVertexBase): vertex is DataflowGraphVertexVariableDefinition;
+/**
+ * Check if the given vertex is a {@link DataflowGraphVertexFunctionDefinition|function definition vertex}.
+ */
 export declare function isFunctionDefinitionVertex(vertex: DataflowGraphVertexBase): vertex is DataflowGraphVertexFunctionDefinition;
 export {};

package/dataflow/graph/vertex.js

@@ -14,18 +14,33 @@ var VertexType;
     VertexType["VariableDefinition"] = "variable-definition";
     VertexType["FunctionDefinition"] = "function-definition";
 })(VertexType || (exports.VertexType = VertexType = {}));
+/**
+ * Check if the given vertex is a {@link DataflowGraphVertexValue|value vertex}.
+ */
 function isValueVertex(vertex) {
     return vertex.tag === VertexType.Value;
 }
+/**
+ * Check if the given vertex is a {@link DataflowGraphVertexUse|use vertex}.
+ */
 function isUseVertex(vertex) {
     return vertex.tag === VertexType.Use;
 }
+/**
+ * Check if the given vertex is a {@link DataflowGraphVertexFunctionCall|function call vertex}.
+ */
 function isFunctionCallVertex(vertex) {
     return vertex.tag === VertexType.FunctionCall;
 }
+/**
+ * Check if the given vertex is a {@link DataflowGraphVertexVariableDefinition|variable definition vertex}.
+ */
 function isVariableDefinitionVertex(vertex) {
     return vertex.tag === VertexType.VariableDefinition;
 }
+/**
+ * Check if the given vertex is a {@link DataflowGraphVertexFunctionDefinition|function definition vertex}.
+ */
 function isFunctionDefinitionVertex(vertex) {
     return vertex.tag === VertexType.FunctionDefinition;
 }

package/dataflow/info.d.ts

@@ -4,6 +4,24 @@ import type { IdentifierReference } from './environments/identifier';
 import type { REnvironmentInformation } from './environments/environment';
 import { DataflowGraph } from './graph/graph';
 import type { GenericDifferenceInformation, WriteableDifferenceReport } from '../util/diff';
+/**
+ * A control dependency links a vertex to the control flow element which
+ * may have an influence on its execution.
+ * Within `if(p) a else b`, `a` and `b` have a control dependency on the `if` (which in turn decides based on `p`).
+ *
+ * @see {@link happensInEveryBranch} - to check whether a list of control dependencies is exhaustive
+ */
+export interface ControlDependency {
+    /** The id of the node that causes the control dependency to be active (e.g., the condition of an if) */
+    readonly id: NodeId;
+    /** when does this control dependency trigger (if the condition is true or false)? */
+    readonly when?: boolean;
+}
+/**
+ * Classifies the type of exit point encountered.
+ *
+ * @see {@link ExitPoint}
+ */
 export declare const enum ExitPointType {
     /** The exit point is the implicit (last executed expression of a function/block) */
     Default = 0,
@@ -14,20 +32,31 @@ export declare const enum ExitPointType {
     /** The exit point is an explicit `next` call (or an alias of it) */
     Next = 3
 }
-export interface ControlDependency {
-    /** The id of the node that causes the control dependency to be active (e.g., the condition of an if) */
-    readonly id: NodeId;
-    /** when does this control dependency trigger (if the condition is true or false)? */
-    readonly when?: boolean;
-}
+/**
+ * An exit point describes the position which ends the current control flow structure.
+ * This may be as innocent as the last expression or explicit with a `return`/`break`/`next`.
+ *
+ * @see {@link ExitPointType} - for the different types of exit points
+ * @see {@link addNonDefaultExitPoints} - to easily modify lists of exit points
+ * @see {@link alwaysExits} - to check whether a list of control dependencies always triggers an exit
+ * @see {@link filterOutLoopExitPoints} - to remove loop exit points from a list
+ */
 export interface ExitPoint {
     /** What kind of exit point is this one? May be used to filter for exit points of specific causes. */
     readonly type: ExitPointType;
     /** The id of the node which causes the exit point! */
     readonly nodeId: NodeId;
-    /** Control dependencies which influence if the exit point triggers (e.g., if the `return` is contained within an `if` statement) */
+    /**
+     * Control dependencies which influence if the exit point triggers
+     * (e.g., if the `return` is contained within an `if` statement).
+     *
+     * @see {@link happensInEveryBranch} - to check whether control dependencies are exhaustive
+     */
     readonly controlDependencies: ControlDependency[] | undefined;
 }
+/**
+ * Adds all non-default exit points to the existing list.
+ */
 export declare function addNonDefaultExitPoints(existing: ExitPoint[], add: readonly ExitPoint[]): void;
 /** The control flow information for the current DataflowInformation. */
 export interface DataflowCfgInformation {
@@ -37,24 +66,63 @@ export interface DataflowCfgInformation {
     exitPoints: readonly ExitPoint[];
 }
 /**
- * The dataflow information is continuously updated during the dataflow analysis
+ * The dataflow information is one of the fundamental structures we have in the dataflow analysis.
+ * It is continuously updated during the dataflow analysis
  * and holds its current state for the respective subtree processed.
+ * Each processor during the dataflow analysis may use the information from its children
+ * to produce a new state of the dataflow information.
+ *
+ * You may initialize a new dataflow information with {@link initializeCleanDataflowInformation}.
+ *
+ * @see {@link DataflowCfgInformation} - the control flow aspects
  */
 export interface DataflowInformation extends DataflowCfgInformation {
-    /** References that have not been identified as read or write and will be so on higher */
+    /**
+     * References that have not been identified as read or write and will be so on higher processors.
+     *
+     * For example, when we analyze the `x` vertex in `x <- 3`, we will first create an unknown reference for `x`
+     * as we have not yet seen the assignment!
+     *
+     * @see {@link IdentifierReference} - a reference on a variable, parameter, function call, ...
+     */
     unknownReferences: readonly IdentifierReference[];
-    /** References which are read */
+    /**
+     * References which are read within the current subtree.
+     *
+     * @see {@link IdentifierReference} - a reference on a variable, parameter, function call, ...
+     * */
     in: readonly IdentifierReference[];
-    /** References which are written to */
+    /**
+     * References which are written to within the current subtree
+     *
+     * @see {@link IdentifierReference} - a reference on a variable, parameter, function call, ...
+     */
     out: readonly IdentifierReference[];
     /** Current environments used for name resolution, probably updated on the next expression-list processing */
     environment: REnvironmentInformation;
     /** The current constructed dataflow graph */
     graph: DataflowGraph;
 }
+/**
+ * Initializes an empty {@link DataflowInformation} object with the given entry point and data.
+ * This is to be used as a "starting point" when processing leaf nodes during the dataflow extraction.
+ *
+ * @see {@link DataflowInformation}
+ */
 export declare function initializeCleanDataflowInformation<T>(entryPoint: NodeId, data: Pick<DataflowProcessorInformation<T>, 'environment' | 'completeAst'>): DataflowInformation;
+/**
+ * Checks whether the given control dependencies are exhaustive (i.e. if for every control dependency on a boolean,
+ * the list contains a dependency on the `true` and on the `false` case).
+ */
 export declare function happensInEveryBranch(controlDependencies: readonly ControlDependency[] | undefined): boolean;
+/**
+ * Checks whether the given dataflow information always exits (i.e., if there is a non-default exit point in every branch).
+ * @see {@link ExitPoint} - for the different types of exit points
+ */
 export declare function alwaysExits(data: DataflowInformation): boolean;
+/**
+ * Filters out exit points which end their cascade within a loop.
+ */
 export declare function filterOutLoopExitPoints(exitPoints: readonly ExitPoint[]): readonly ExitPoint[];
 export declare function diffControlDependency<Report extends WriteableDifferenceReport>(a: ControlDependency | undefined, b: ControlDependency | undefined, info: GenericDifferenceInformation<Report>): void;
 export declare function diffControlDependencies<Report extends WriteableDifferenceReport>(a: ControlDependency[] | undefined, b: ControlDependency[] | undefined, info: GenericDifferenceInformation<Report>): void;

package/dataflow/info.js

@@ -8,9 +8,18 @@ exports.filterOutLoopExitPoints = filterOutLoopExitPoints;
 exports.diffControlDependency = diffControlDependency;
 exports.diffControlDependencies = diffControlDependencies;
 const graph_1 = require("./graph/graph");
+/**
+ * Adds all non-default exit points to the existing list.
+ */
 function addNonDefaultExitPoints(existing, add) {
     existing.push(...add.filter(({ type }) => type !== 0 /* ExitPointType.Default */));
 }
+/**
+ * Initializes an empty {@link DataflowInformation} object with the given entry point and data.
+ * This is to be used as a "starting point" when processing leaf nodes during the dataflow extraction.
+ *
+ * @see {@link DataflowInformation}
+ */
 function initializeCleanDataflowInformation(entryPoint, data) {
     return {
         unknownReferences: [],
@@ -22,6 +31,10 @@ function initializeCleanDataflowInformation(entryPoint, data) {
         exitPoints: [{ nodeId: entryPoint, type: 0 /* ExitPointType.Default */, controlDependencies: undefined }]
     };
 }
+/**
+ * Checks whether the given control dependencies are exhaustive (i.e. if for every control dependency on a boolean,
+ * the list contains a dependency on the `true` and on the `false` case).
+ */
 function happensInEveryBranch(controlDependencies) {
     if (controlDependencies === undefined) {
         /* the cds are unconstrained */
@@ -43,9 +56,16 @@ function happensInEveryBranch(controlDependencies) {
     }
     return trues.every(id => falseSet.has(id));
 }
+/**
+ * Checks whether the given dataflow information always exits (i.e., if there is a non-default exit point in every branch).
+ * @see {@link ExitPoint} - for the different types of exit points
+ */
 function alwaysExits(data) {
     return data.exitPoints?.some(e => e.type !== 0 /* ExitPointType.Default */ && happensInEveryBranch(e.controlDependencies)) ?? false;
 }
+/**
+ * Filters out exit points which end their cascade within a loop.
+ */
 function filterOutLoopExitPoints(exitPoints) {
     return exitPoints.filter(({ type }) => type === 1 /* ExitPointType.Return */ || type === 0 /* ExitPointType.Default */);
 }

package/dataflow/internal/linker.d.ts

@@ -23,8 +23,10 @@ export declare function linkFunctionCalls(graph: DataflowGraph, idMap: AstIdMap,
     functionCall: NodeId;
     called: readonly DataflowGraphVertexInfo[];
 }[];
-/** convenience function returning all known call targets */
-export declare function getAllFunctionCallTargets(call: NodeId, graph: DataflowGraph): NodeId[];
+/**
+ * convenience function returning all known call targets, as well as the name source which defines them
+ */
+export declare function getAllFunctionCallTargets(call: NodeId, graph: DataflowGraph, environment?: REnvironmentInformation): NodeId[];
 export declare function getAllLinkedFunctionDefinitions(functionDefinitionReadIds: ReadonlySet<NodeId>, dataflowGraph: DataflowGraph): Set<DataflowGraphVertexInfo>;
 /**
  * This method links a set of read variables to definitions in an environment.