@eagleoutice/flowr 2.1.8 → 2.1.10

package/dataflow/environments/identifier.d.ts

@@ -1,13 +1,22 @@
 import type { BuiltInIdentifierConstant, BuiltInIdentifierDefinition } from './built-in';
 import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { ControlDependency } from '../info';
+import type { ContainerIndicesCollection } from '../graph/vertex';
 export type Identifier = string & {
     __brand?: 'identifier';
 };
 /**
- * Each reference only has exactly one reference type, stored as the respective number.
- * However, when checking we may want to allow for one of several types,
+ * Each reference has exactly one reference type, stored as the respective number.
+ * However, when checking, we may want to allow for one of several types,
  * allowing the combination of the respective bitmasks.
+ *
+ * Having reference types is important as R separates a variable definition from
+ * a function when resolving an {@link Identifier|identifier}.
+ * In `c <- 3; print(c(1, 2))` the call to `c` works normally (as the vector constructor),
+ * while writing `c <- function(...) ..1` overshadows the built-in and causes `print` to only output the first element.
+ *
+ * @see {@link isReferenceType} - for checking if a (potentially joint) reference type contains a certain type
+ * @see {@link ReferenceTypeReverseMapping} - for debugging
  */
 export declare enum ReferenceType {
     /** The identifier type is unknown */
@@ -27,19 +36,38 @@ export declare enum ReferenceType {
     /** The identifier is defined by a built-in function */
     BuiltInFunction = 128
 }
+/** Reverse mapping of the reference types so you can get the name from the bitmask (useful for debugging) */
 export declare const ReferenceTypeReverseMapping: Map<ReferenceType, string>;
 /**
  * Check if the reference types have an overlapping type!
  */
 export declare function isReferenceType(t: ReferenceType, target: ReferenceType): boolean;
+/**
+ * Describes all types of reference (definitions) that can appear within a graph (i.e., that are not built-in like the
+ * default definition for the assignment operator `<-`).
+ *
+ * @see {@link InGraphIdentifierDefinition} - for the definition of an identifier within the graph
+ */
 export type InGraphReferenceType = Exclude<ReferenceType, ReferenceType.BuiltInConstant | ReferenceType.BuiltInFunction>;
 /**
- * Something like `a` in `b <- a`.
- * Without any surrounding information, `a` will produce the identifier reference `a`.
- * Similarly, `b` will create a reference.
+ * An identifier reference points to a variable like `a` in `b <- a`.
+ * Without any surrounding code, `a` will produce the identifier reference `a`.
+ * Similarly, `b` will create a reference (although it will be an {@link IdentifierDefinition|identifier definition}
+ * which adds even more information).
+ *
+ * In general,
+ * references are merely pointers (with meta-information) to a vertex in the {@link DataflowGraph|dataflow graph}.
+ * In the context of the extractor, for example,
+ * they indicate the references that are currently (during the analysis at this given node)
+ * {@link DataflowInformation#in|read (`in`)}, {@link DataflowInformation#out|written (`out`)},
+ * or {@link DataflowInformation#unknownReferences|unknown (`unknownReferences`)}.
+ *
+ * @see {@link InGraphIdentifierDefinition}
  */
 export interface IdentifierReference {
-    /** Node which represents the reference in the AST */
+    /**
+     * The id of the node which represents the reference in the {@link NormalizedAst|normalized AST} and the {@link DataflowGraph|dataflow graph}.
+     */
     readonly nodeId: NodeId;
     /** Name the reference is identified by (e.g., the name of the variable), undefined if the reference is "artificial" (e.g., anonymous) */
     readonly name: Identifier | undefined;
@@ -51,13 +79,35 @@ export interface IdentifierReference {
      */
     controlDependencies: ControlDependency[] | undefined;
 }
-interface InGraphIdentifierDefinition extends IdentifierReference {
+/**
+ * The definition of an {@link Identifier|identifier} within the {@link DataflowGraph|graph}.
+ * This extends on the {@link IdentifierReference}
+ * by adding the {@link NodeId} of the definition
+ * (and using `type` to mark the object type).
+ *
+ * Within a code snippet like `a <- 3`, the symbol processor will first create an
+ * {@link IdentifierReference|identifier reference} for `a` to reference the use
+ * and then promote it to an {@link InGraphIdentifierDefinition|identifier definition}.
+ *
+ * @see {@link IdentifierReference}
+ */
+export interface InGraphIdentifierDefinition extends IdentifierReference {
     readonly type: InGraphReferenceType;
-    /** The assignment (or whatever, like `assign` function call) node which ultimately defined this identifier */
+    /**
+     * The assignment node which ultimately defined this identifier
+     * (the arrow operator for e.g. `x <- 3`, or `assign` call in `assign("x", 3)`)
+     */
     readonly definedAt: NodeId;
+    readonly value?: NodeId[];
+    /**
+     * this attribute links a definition to indices (pointer links) it may be affected by or related to
+     */
+    indicesCollection?: ContainerIndicesCollection;
 }
 /**
- * Stores the definition of an identifier within an {@link IEnvironment}
+ * Stores the definition of an identifier within an {@link IEnvironment}.
+ *
+ * {@link BuiltInIdentifierDefinition} and {@link BuiltInIdentifierConstant} are used for built-in functions and constants only,
+ * so the most important one for your day-to-day R script is the {@link InGraphIdentifierDefinition}.
  */
 export type IdentifierDefinition = InGraphIdentifierDefinition | BuiltInIdentifierDefinition | BuiltInIdentifierConstant;
-export {};

package/dataflow/environments/identifier.js

@@ -3,9 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReferenceTypeReverseMapping = exports.ReferenceType = void 0;
 exports.isReferenceType = isReferenceType;
 /**
- * Each reference only has exactly one reference type, stored as the respective number.
- * However, when checking we may want to allow for one of several types,
+ * Each reference has exactly one reference type, stored as the respective number.
+ * However, when checking, we may want to allow for one of several types,
  * allowing the combination of the respective bitmasks.
+ *
+ * Having reference types is important as R separates a variable definition from
+ * a function when resolving an {@link Identifier|identifier}.
+ * In `c <- 3; print(c(1, 2))` the call to `c` works normally (as the vector constructor),
+ * while writing `c <- function(...) ..1` overshadows the built-in and causes `print` to only output the first element.
+ *
+ * @see {@link isReferenceType} - for checking if a (potentially joint) reference type contains a certain type
+ * @see {@link ReferenceTypeReverseMapping} - for debugging
  */
 var ReferenceType;
 (function (ReferenceType) {
@@ -26,6 +34,7 @@ var ReferenceType;
     /** The identifier is defined by a built-in function */
     ReferenceType[ReferenceType["BuiltInFunction"] = 128] = "BuiltInFunction";
 })(ReferenceType || (exports.ReferenceType = ReferenceType = {}));
+/** Reverse mapping of the reference types so you can get the name from the bitmask (useful for debugging) */
 exports.ReferenceTypeReverseMapping = new Map(Object.entries(ReferenceType).map(([k, v]) => [v, k]));
 /**
  * Check if the reference types have an overlapping type!

package/dataflow/environments/resolve-by-name.d.ts

@@ -2,6 +2,8 @@ import type { REnvironmentInformation } from './environment';
 import { Ternary } from '../../util/logic';
 import type { Identifier, IdentifierDefinition } from './identifier';
 import { ReferenceType } from './identifier';
+import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
+import type { DataflowGraph } from '../graph/graph';
 /**
  * Resolves a given identifier name to a list of its possible definition location using R scoping and resolving rules.
  *
@@ -13,8 +15,11 @@ import { ReferenceType } from './identifier';
  */
 export declare function resolveByName(name: Identifier, environment: REnvironmentInformation, target?: ReferenceType): IdentifierDefinition[] | undefined;
 export declare function resolvesToBuiltInConstant(name: Identifier | undefined, environment: REnvironmentInformation, wantedValue: unknown): Ternary;
-export interface ResolveResult<T = unknown> {
-    value: T;
-    from: ReferenceType;
-}
-export declare function resolveToConstants(name: Identifier | undefined, environment: REnvironmentInformation): ResolveResult[] | undefined;
+export declare function resolveToConstants(name: Identifier | undefined, environment: REnvironmentInformation): unknown[] | undefined;
+export declare function getAliases(sourceIds: readonly NodeId[], dataflow: DataflowGraph, environment: REnvironmentInformation): NodeId[] | undefined;
+export declare function resolveToValues(identifier: Identifier | undefined, environment: REnvironmentInformation, graph: DataflowGraph): unknown[] | undefined;
+/**
+ * Convenience function using the variable resolver as specified within the configuration file
+ * In the future we may want to have this set once at the start of the analysis
+ */
+export declare function resolveValueOfVariable(identifier: Identifier | undefined, environment: REnvironmentInformation, graph: DataflowGraph): unknown[] | undefined;

package/dataflow/environments/resolve-by-name.js

@@ -3,9 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveByName = resolveByName;
 exports.resolvesToBuiltInConstant = resolvesToBuiltInConstant;
 exports.resolveToConstants = resolveToConstants;
+exports.getAliases = getAliases;
+exports.resolveToValues = resolveToValues;
+exports.resolveValueOfVariable = resolveValueOfVariable;
 const environment_1 = require("./environment");
 const identifier_1 = require("./identifier");
 const info_1 = require("../info");
+const node_id_1 = require("../../r-bridge/lang-4.x/ast/model/processing/node-id");
+const vertex_1 = require("../graph/vertex");
+const config_1 = require("../../config");
+const assert_1 = require("../../util/assert");
 const FunctionTargetTypes = identifier_1.ReferenceType.Function | identifier_1.ReferenceType.BuiltInFunction | identifier_1.ReferenceType.Unknown | identifier_1.ReferenceType.Argument | identifier_1.ReferenceType.Parameter;
 const VariableTargetTypes = identifier_1.ReferenceType.Variable | identifier_1.ReferenceType.Parameter | identifier_1.ReferenceType.Argument | identifier_1.ReferenceType.Unknown;
 const ConstantTargetTypes = identifier_1.ReferenceType.Constant | identifier_1.ReferenceType.BuiltInConstant | identifier_1.ReferenceType.Unknown;
@@ -86,12 +93,103 @@ function resolveToConstants(name, environment) {
         return undefined;
     }
     const definitions = resolveByName(name, environment, identifier_1.ReferenceType.Constant);
-    if (definitions === undefined) {
+    return definitions?.map(def => def.value);
+}
+const AliasHandler = {
+    [vertex_1.VertexType.Value]: (sourceId) => [sourceId],
+    [vertex_1.VertexType.Use]: getUseAlias,
+    [vertex_1.VertexType.FunctionCall]: () => undefined,
+    [vertex_1.VertexType.FunctionDefinition]: () => undefined,
+    [vertex_1.VertexType.VariableDefinition]: () => undefined
+};
+function getUseAlias(sourceId, dataflow, environment) {
+    const definitions = [];
+    // Source is Symbol -> resolve definitions of symbol
+    const identifier = (0, node_id_1.recoverName)(sourceId, dataflow.idMap);
+    if (identifier === undefined) {
+        return undefined;
+    }
+    const defs = resolveByName(identifier, environment);
+    if (defs === undefined) {
         return undefined;
     }
-    return definitions.map(def => ({
-        value: def.value,
-        from: def.type
-    }));
+    for (const def of defs) {
+        // If one definition is not constant (or a variable aliasing a constant)
+        // we can't say for sure what value the source has
+        if (def.type === identifier_1.ReferenceType.Variable) {
+            if (def.value === undefined) {
+                return undefined;
+            }
+            definitions.push(...def.value);
+        }
+        else if (def.type === identifier_1.ReferenceType.Constant || def.type === identifier_1.ReferenceType.BuiltInConstant) {
+            definitions.push(def.nodeId);
+        }
+        else {
+            return undefined;
+        }
+    }
+    return definitions;
+}
+function getAliases(sourceIds, dataflow, environment) {
+    const definitions = new Set();
+    for (const sourceId of sourceIds) {
+        const info = dataflow.getVertex(sourceId);
+        if (info === undefined) {
+            return undefined;
+        }
+        const defs = AliasHandler[info.tag](sourceId, dataflow, environment);
+        for (const def of defs ?? []) {
+            definitions.add(def);
+        }
+    }
+    return [...definitions];
+}
+function resolveToValues(identifier, environment, graph) {
+    if (identifier === undefined) {
+        return undefined;
+    }
+    const defs = resolveByName(identifier, environment);
+    if (defs === undefined) {
+        return undefined;
+    }
+    const values = [];
+    for (const def of defs) {
+        if (def.type === identifier_1.ReferenceType.BuiltInConstant) {
+            values.push(def.value);
+        }
+        else if (def.type === identifier_1.ReferenceType.BuiltInFunction) {
+            // Tracked in #1207
+        }
+        else if (def.value !== undefined) {
+            /* if there is at least one location for which we have no idea, we have to give up for now! */
+            if (def.value.length === 0) {
+                return undefined;
+            }
+            for (const id of def.value) {
+                const value = graph.idMap?.get(id)?.content;
+                if (value !== undefined) {
+                    values.push(value);
+                }
+            }
+        }
+    }
+    if (values.length == 0) {
+        return undefined;
+    }
+    return values;
+}
+/**
+ * Convenience function using the variable resolver as specified within the configuration file
+ * In the future we may want to have this set once at the start of the analysis
+ */
+function resolveValueOfVariable(identifier, environment, graph) {
+    const resolve = (0, config_1.getConfig)().solver.variables;
+    switch (resolve) {
+        case config_1.VariableResolve.Alias: return resolveToValues(identifier, environment, graph);
+        case config_1.VariableResolve.Builtin: return resolveToConstants(identifier, environment);
+        case config_1.VariableResolve.Disabled: return [];
+        default: (0, assert_1.assertUnreachable)(resolve);
+    }
 }
 //# sourceMappingURL=resolve-by-name.js.map

package/dataflow/extractor.js

@@ -20,6 +20,7 @@ const built_in_source_1 = require("./internal/process/functions/call/built-in/bu
 const cfg_1 = require("../util/cfg/cfg");
 const edge_1 = require("./graph/edge");
 const identify_link_to_last_call_relation_1 = require("../queries/catalog/call-context-query/identify-link-to-last-call-relation");
+const built_in_function_definition_1 = require("./internal/process/functions/call/built-in/built-in-function-definition");
 exports.processors = {
     [type_1.RType.Number]: process_value_1.processValue,
     [type_1.RType.String]: process_value_1.processValue,
@@ -56,11 +57,9 @@ function resolveLinkToSideEffects(ast, graph) {
         if (typeof s !== 'object') {
             continue;
         }
-        if (!cfg) {
-            cfg = (0, cfg_1.extractCFG)(ast).graph;
-        }
+        cfg ??= (0, cfg_1.extractCFG)(ast).graph;
         /* this has to change whenever we add a new link to relations because we currently offer no abstraction for the type */
-        const potentials = (0, identify_link_to_last_call_relation_1.identifyLinkToLastCallRelation)(s.id, cfg, graph, s.linkTo.callName);
+        const potentials = (0, identify_link_to_last_call_relation_1.identifyLinkToLastCallRelation)(s.id, cfg, graph, s.linkTo);
         for (const pot of potentials) {
             graph.addEdge(s.id, pot, edge_1.EdgeType.Reads);
         }
@@ -92,6 +91,8 @@ function produceDataFlowGraph(request, ast) {
             df = (0, built_in_source_1.standaloneSourceFile)(request[i], dfData, `root-${i}`, df);
         }
     }
+    // finally, resolve linkages
+    (0, built_in_function_definition_1.updateNestedFunctionCalls)(df.graph, df.environment);
     resolveLinkToSideEffects(ast, df.graph);
     return df;
 }

package/dataflow/graph/dataflowgraph-builder.d.ts

@@ -114,6 +114,12 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      * @see reads for parameters.
      */
     definesOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this;
+    /**
+     * Adds a **defined-by-on-call edge** with from as definition, and to as variable.
+     *
+     * @see reads for parameters.
+     */
+    definedByOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**
      * Adds an **argument edge** (E9) with from as function call, and to as argument.
      *

package/dataflow/graph/dataflowgraph-builder.js

@@ -212,6 +212,14 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
     definesOnCall(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.DefinesOnCall);
     }
+    /**
+     * Adds a **defined-by-on-call edge** with from as definition, and to as variable.
+     *
+     * @see reads for parameters.
+     */
+    definedByOnCall(from, to) {
+        return this.edgeHelper(from, to, edge_1.EdgeType.DefinedByOnCall);
+    }
     /**
      * Adds an **argument edge** (E9) with from as function call, and to as argument.
      *

package/dataflow/graph/edge.d.ts

@@ -19,9 +19,15 @@ export declare enum EdgeType {
     Calls = 4,
     /** The source returns target on call */
     Returns = 8,
-    /** The edge determines that source (probably argument) defines the target (probably parameter), currently automatically created by `addEdge` */
+    /**
+     * The edge determines that source (probably argument) defines the target (probably parameter).
+     * This may also link a function call to definitions it causes to be active (as part of the closure) of the called function definition.
+     */
     DefinesOnCall = 16,
-    /** Inverse of `defines-on-call` currently only needed to get better results when slicing complex function calls */
+    /**
+     * Usually the inverse of `defines-on-call` (in the context of arguments and parameters).
+     * This may also link an open read (within a function) to the definition that is active at the call site.
+     */
     DefinedByOnCall = 32,
     /** Formal used as argument to a function call */
     Argument = 64,
@@ -57,8 +63,8 @@ export declare const enum TraverseEdge {
     Never = 0,
     /** Traverse the edge as a side effect */
     SideEffect = 1,
-    /** Traverse this edge if the definition is relevant */
-    DefinedByOnCall = 2,
+    /** Traverse this edge if the definition is relevant (i.e., if two matching edges trigger this state) */
+    OnlyIfBoth = 2,
     /** Always traverse this edge */
     Always = 3
 }

package/dataflow/graph/edge.js

@@ -22,9 +22,15 @@ var EdgeType;
     EdgeType[EdgeType["Calls"] = 4] = "Calls";
     /** The source returns target on call */
     EdgeType[EdgeType["Returns"] = 8] = "Returns";
-    /** The edge determines that source (probably argument) defines the target (probably parameter), currently automatically created by `addEdge` */
+    /**
+     * The edge determines that source (probably argument) defines the target (probably parameter).
+     * This may also link a function call to definitions it causes to be active (as part of the closure) of the called function definition.
+     */
     EdgeType[EdgeType["DefinesOnCall"] = 16] = "DefinesOnCall";
-    /** Inverse of `defines-on-call` currently only needed to get better results when slicing complex function calls */
+    /**
+     * Usually the inverse of `defines-on-call` (in the context of arguments and parameters).
+     * This may also link an open read (within a function) to the definition that is active at the call site.
+     */
     EdgeType[EdgeType["DefinedByOnCall"] = 32] = "DefinedByOnCall";
     /** Formal used as argument to a function call */
     EdgeType[EdgeType["Argument"] = 64] = "Argument";
@@ -89,13 +95,14 @@ function edgeIncludesType(type, types) {
 function edgeDoesNotIncludeType(type, types) {
     return (types & type) === 0;
 }
-const alwaysTraverseEdgeTypes = EdgeType.Reads | EdgeType.DefinedBy | EdgeType.Argument | EdgeType.Calls | EdgeType.DefinesOnCall;
+const alwaysTraverseEdgeTypes = EdgeType.Reads | EdgeType.DefinedBy | EdgeType.Argument | EdgeType.Calls;
+const definedByOnCallTypes = EdgeType.DefinesOnCall | EdgeType.DefinedByOnCall;
 function shouldTraverseEdge(types) {
     if (edgeIncludesType(types, alwaysTraverseEdgeTypes)) {
         return 3 /* TraverseEdge.Always */;
     }
-    else if (edgeIncludesType(types, EdgeType.DefinedByOnCall)) {
-        return 2 /* TraverseEdge.DefinedByOnCall */;
+    else if (edgeIncludesType(types, definedByOnCallTypes)) {
+        return 2 /* TraverseEdge.OnlyIfBoth */;
     }
     else if (edgeIncludesType(types, EdgeType.SideEffectOnCall)) {
         return 1 /* TraverseEdge.SideEffect */;

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.
      *