@eagleoutice/flowr 2.6.0 → 2.6.2

package/dataflow/graph/diff-dataflow-graph.js

@@ -19,7 +19,6 @@ const diff_graph_1 = require("../../util/diff-graph");
 /**
  * Compare two dataflow graphs and return a report on the differences.
  * If you simply want to check whether they equal, use {@link GraphDifferenceReport#isEqual|`<result>.isEqual()`}.
- *
  * @see {@link diffOfControlFlowGraphs} - for control flow graphs
  */
 function diffOfDataflowGraphs(left, right, config) {
@@ -80,6 +79,9 @@ function diffFunctionArgumentsReferences(fn, a, b, ctx) {
     }
     (0, diff_2.diffIdentifierReferences)(a, b, ctx);
 }
+/**
+ * Checks whether two function argument lists are equal.
+ */
 function equalFunctionArguments(fn, a, b) {
     const ctx = {
         report: new diff_graph_1.GraphDifferenceReport(),
@@ -91,6 +93,9 @@ function equalFunctionArguments(fn, a, b) {
     diffFunctionArguments(fn, a, b, ctx);
     return ctx.report.isEqual();
 }
+/**
+ * Compares two function argument lists and reports differences.
+ */
 function diffFunctionArguments(fn, a, b, ctx) {
     if (a === false || b === false) {
         if (a !== b) {
@@ -129,6 +134,9 @@ function diffFunctionArguments(fn, a, b, ctx) {
         }
     }
 }
+/**
+ * Compares the vertices of two dataflow graphs and reports differences.
+ */
 function diffVertices(ctx) {
     // collect vertices from both sides
     const lVert = ctx.left.vertices(true).map(([id, info]) => [id, info]).toArray();
@@ -232,6 +240,9 @@ function diffEdge(edge, otherEdge, ctx, id, target) {
         ctx.report.addComment(`Target of ${id}->${target} in ${ctx.leftname} differs in edge types: ${JSON.stringify([...(0, edge_1.edgeTypesToNames)(edge.types)])} vs ${JSON.stringify([...(0, edge_1.edgeTypesToNames)(otherEdge.types)])}`, { tag: 'edge', from: id, to: target });
     }
 }
+/**
+ * Compares two sets of outgoing edges and reports differences.
+ */
 function diffEdges(ctx, id, lEdges, rEdges) {
     if (lEdges === undefined || rEdges === undefined) {
         if ((lEdges === undefined && !ctx.config.leftIsSubgraph)

package/dataflow/graph/edge.d.ts

@@ -56,7 +56,13 @@ export type EdgeTypeBits = number;
  * Otherwise, use {@link edgeTypesToNames} which handles these cases.
  */
 export declare function edgeTypeToName(type: EdgeType): string;
+/**
+ * Takes joint edge types and splits them into their individual components.
+ */
 export declare function splitEdgeTypes(types: EdgeTypeBits): EdgeType[];
+/**
+ * Takes joint edge types and returns their human-readable names.
+ */
 export declare function edgeTypesToNames(bits: EdgeTypeBits): Set<EdgeTypeName>;
 export declare const enum TraverseEdge {
     /** Do not traverse this edge */
@@ -84,4 +90,7 @@ export declare function edgeIncludesType(type: EdgeTypeBits, typesToInclude: Edg
  * Counterpart of {@link edgeIncludesType}.
  */
 export declare function edgeDoesNotIncludeType(type: EdgeTypeBits, types: EdgeTypeBits): boolean;
+/**
+ * Determines whether an edge should be traversed during dataflow analysis.
+ */
 export declare function shouldTraverseEdge(types: EdgeTypeBits): TraverseEdge;

package/dataflow/graph/edge.js

@@ -57,6 +57,9 @@ const edgeTypeToHumanReadableName = new Map([
 function edgeTypeToName(type) {
     return edgeTypeToHumanReadableName.get(type);
 }
+/**
+ * Takes joint edge types and splits them into their individual components.
+ */
 function splitEdgeTypes(types) {
     const split = [];
     for (const bit of edgeTypeToHumanReadableName.keys()) {
@@ -66,6 +69,9 @@ function splitEdgeTypes(types) {
     }
     return split;
 }
+/**
+ * Takes joint edge types and returns their human-readable names.
+ */
 function edgeTypesToNames(bits) {
     const types = new Set();
     for (const [bit, name] of edgeTypeToHumanReadableName.entries()) {
@@ -97,6 +103,9 @@ function edgeDoesNotIncludeType(type, types) {
 }
 const alwaysTraverseEdgeTypes = EdgeType.Reads | EdgeType.DefinedBy | EdgeType.Argument | EdgeType.Calls;
 const definedByOnCallTypes = EdgeType.DefinesOnCall | EdgeType.DefinedByOnCall;
+/**
+ * Determines whether an edge should be traversed during dataflow analysis.
+ */
 function shouldTraverseEdge(types) {
     if (edgeIncludesType(types, EdgeType.NonStandardEvaluation)) {
         return 0 /* TraverseEdge.Never */;

package/dataflow/graph/graph.d.ts

@@ -1,9 +1,9 @@
 import type { DataflowGraphEdge, EdgeType } from './edge';
 import type { DataflowInformation } from '../info';
-import type { DataflowGraphVertexArgument, DataflowGraphVertexFunctionCall, DataflowGraphVertexInfo } from './vertex';
+import { type DataflowGraphVertexArgument, type DataflowGraphVertexFunctionCall, type DataflowGraphVertexInfo } from './vertex';
 import { EmptyArgument } from '../../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
 import type { Identifier, IdentifierDefinition, IdentifierReference } from '../environments/identifier';
-import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
+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';
 /**
@@ -19,7 +19,6 @@ export type DataflowFunctionFlowInformation = Omit<DataflowInformation, 'graph'
  * ```r
  * foo(a = 3, b = 2)
  * ```
- *
  * @see #isNamedArgument
  * @see PositionalFunctionArgument
  */
@@ -32,7 +31,6 @@ export interface NamedFunctionArgument extends IdentifierReference {
  * ```r
  * foo(3, 2)
  * ```
- *
  * @see #isPositionalArgument
  * @see NamedFunctionArgument
  */
@@ -95,7 +93,6 @@ 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.
@@ -116,21 +113,17 @@ export declare class DataflowGraph<Vertex extends DataflowGraphVertexInfo = Data
     private edgeInformation;
     /**
      * Get the {@link DataflowGraphVertexInfo} attached to a node as well as all outgoing edges.
-     *
      * @param id                      - The id of the node to get
      * @param includeDefinedFunctions - If true this will search function definitions as well and not just the toplevel
      * @returns the node info for the given id (if it exists)
-     *
      * @see #getVertex
      */
     get(id: NodeId, includeDefinedFunctions?: boolean): [Vertex, OutgoingEdges] | undefined;
     /**
      * Get the {@link DataflowGraphVertexInfo} attached to a vertex.
-     *
      * @param id                      - The id of the node to get
      * @param includeDefinedFunctions - If true this will search function definitions as well and not just the toplevel
      * @returns the node info for the given id (if it exists)
-     *
      * @see #get
      */
     getVertex(id: NodeId, includeDefinedFunctions?: boolean): Vertex | undefined;
@@ -138,9 +131,9 @@ export declare class DataflowGraph<Vertex extends DataflowGraphVertexInfo = Data
     ingoingEdges(id: NodeId): IngoingEdges | undefined;
     /**
      * Given a node in the normalized AST this either:
-     * * returns the id if the node directly exists in the DFG
-     * * returns the ids of all vertices in the DFG that are linked to this
-     * * returns undefined if the node is not part of the DFG and not linked to any node
+     * returns the id if the node directly exists in the DFG
+     * returns the ids of all vertices in the DFG that are linked to this
+     * returns undefined if the node is not part of the DFG and not linked to any node
      */
     getLinked(nodeId: NodeId): NodeId[] | undefined;
     /** Retrieves the id-map to the normalized AST attached to the dataflow graph */
@@ -157,19 +150,16 @@ export declare class DataflowGraph<Vertex extends DataflowGraphVertexInfo = Data
     /**
      * @param includeDefinedFunctions - If true this will iterate over function definitions as well and not just the toplevel
      * @returns the ids of all toplevel vertices in the graph together with their vertex information
-     *
      * @see #edges
      */
     vertices(includeDefinedFunctions: boolean): MapIterator<[NodeId, Vertex]>;
     /**
      * @returns the ids of all edges in the graph together with their edge information
-     *
      * @see #vertices
      */
     edges(): MapIterator<[NodeId, OutgoingEdges]>;
     /**
      * Returns true if the graph contains a node with the given id.
-     *
      * @param id                      - The id to check for
      * @param includeDefinedFunctions - If true this will check function definitions as well and not just the toplevel
      */
@@ -181,12 +171,10 @@ export declare class DataflowGraph<Vertex extends DataflowGraphVertexInfo = Data
     rootIds(): ReadonlySet<NodeId>;
     /**
      * Adds a new vertex to the graph, for ease of use, some arguments are optional and filled automatically.
-     *
      * @param vertex - The vertex to add
      * @param asRoot - If false, this will only add the vertex but do not add it to the {@link rootIds|root vertices} of the graph.
      *                 This is probably only of use, when you construct dataflow graphs for tests.
      * @param overwrite - If true, this will overwrite the vertex if it already exists in the graph (based on the id).
-     *
      * @see DataflowGraphVertexInfo
      * @see DataflowGraphVertexArgument
      */
@@ -199,10 +187,9 @@ export declare class DataflowGraph<Vertex extends DataflowGraphVertexInfo = Data
     addEdge(from: NodeId | ReferenceForEdge, to: NodeId | ReferenceForEdge, type: EdgeType | number): this;
     /**
      * Merges the other graph into *this* one (in-place). The return value is only for convenience.
-     *
      * @param otherGraph        - The graph to merge into this one
      * @param mergeRootVertices - If false, this will only merge the vertices and edges but exclude the root vertices this is probably only of use
-     * 													  in the context of function definitions
+     *                            in the context of function definitions
      */
     mergeWith(otherGraph: DataflowGraph<Vertex, Edge> | undefined, mergeRootVertices?: boolean): this;
     private mergeEdges;

package/dataflow/graph/graph.js

@@ -45,7 +45,6 @@ function getReferenceOfArgument(arg) {
  * 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.
@@ -74,11 +73,9 @@ class DataflowGraph {
     edgeInformation = new Map();
     /**
      * Get the {@link DataflowGraphVertexInfo} attached to a node as well as all outgoing edges.
-     *
      * @param id                      - The id of the node to get
      * @param includeDefinedFunctions - If true this will search function definitions as well and not just the toplevel
      * @returns the node info for the given id (if it exists)
-     *
      * @see #getVertex
      */
     get(id, includeDefinedFunctions = true) {
@@ -88,11 +85,9 @@ class DataflowGraph {
     }
     /**
      * Get the {@link DataflowGraphVertexInfo} attached to a vertex.
-     *
      * @param id                      - The id of the node to get
      * @param includeDefinedFunctions - If true this will search function definitions as well and not just the toplevel
      * @returns the node info for the given id (if it exists)
-     *
      * @see #get
      */
     getVertex(id, includeDefinedFunctions = true) {
@@ -112,9 +107,9 @@ class DataflowGraph {
     }
     /**
      * Given a node in the normalized AST this either:
-     * * returns the id if the node directly exists in the DFG
-     * * returns the ids of all vertices in the DFG that are linked to this
-     * * returns undefined if the node is not part of the DFG and not linked to any node
+     * returns the id if the node directly exists in the DFG
+     * returns the ids of all vertices in the DFG that are linked to this
+     * returns undefined if the node is not part of the DFG and not linked to any node
      */
     getLinked(nodeId) {
         if (this.vertexInformation.has(nodeId)) {
@@ -152,7 +147,6 @@ class DataflowGraph {
     /**
      * @param includeDefinedFunctions - If true this will iterate over function definitions as well and not just the toplevel
      * @returns the ids of all toplevel vertices in the graph together with their vertex information
-     *
      * @see #edges
      */
     *vertices(includeDefinedFunctions) {
@@ -167,7 +161,6 @@ class DataflowGraph {
     }
     /**
      * @returns the ids of all edges in the graph together with their edge information
-     *
      * @see #vertices
      */
     *edges() {
@@ -175,7 +168,6 @@ class DataflowGraph {
     }
     /**
      * Returns true if the graph contains a node with the given id.
-     *
      * @param id                      - The id to check for
      * @param includeDefinedFunctions - If true this will check function definitions as well and not just the toplevel
      */
@@ -193,12 +185,10 @@ class DataflowGraph {
     }
     /**
      * Adds a new vertex to the graph, for ease of use, some arguments are optional and filled automatically.
-     *
      * @param vertex - The vertex to add
      * @param asRoot - If false, this will only add the vertex but do not add it to the {@link rootIds|root vertices} of the graph.
      *                 This is probably only of use, when you construct dataflow graphs for tests.
      * @param overwrite - If true, this will overwrite the vertex if it already exists in the graph (based on the id).
-     *
      * @see DataflowGraphVertexInfo
      * @see DataflowGraphVertexArgument
      */
@@ -244,10 +234,9 @@ class DataflowGraph {
     }
     /**
      * Merges the other graph into *this* one (in-place). The return value is only for convenience.
-     *
      * @param otherGraph        - The graph to merge into this one
      * @param mergeRootVertices - If false, this will only merge the vertices and edges but exclude the root vertices this is probably only of use
-     * 													  in the context of function definitions
+     *                            in the context of function definitions
      */
     mergeWith(otherGraph, mergeRootVertices = true) {
         if (otherGraph === undefined) {

package/dataflow/graph/invert-dfg.d.ts

@@ -1,2 +1,5 @@
 import { DataflowGraph } from './graph';
+/**
+ *
+ */
 export declare function invertDfg(graph: DataflowGraph): DataflowGraph;

package/dataflow/graph/invert-dfg.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.invertDfg = invertDfg;
 const graph_1 = require("./graph");
+/**
+ *
+ */
 function invertDfg(graph) {
     const invertedGraph = new graph_1.DataflowGraph(graph.idMap);
     for (const [, v] of graph.vertices(true)) {

package/dataflow/graph/quads.d.ts

@@ -1,4 +1,4 @@
-import type { QuadSerializationConfiguration } from '../../util/quads';
+import { type QuadSerializationConfiguration } from '../../util/quads';
 import type { DataflowGraph } from './graph';
 /**
  * @see cfg2quads

package/dataflow/graph/unknown-replacement.d.ts

@@ -7,5 +7,11 @@ export type ReplacementOperatorHandlerArgs = {
     id: NodeId;
 };
 export type ReplacementOperatorHandler = (args: ReplacementOperatorHandlerArgs) => void;
+/**
+ *
+ */
 export declare function onReplacementOperator(handler: ReplacementOperatorHandler): void;
+/**
+ *
+ */
 export declare function handleReplacementOperator(args: ReplacementOperatorHandlerArgs): void;

package/dataflow/graph/unknown-replacement.js

@@ -3,9 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.onReplacementOperator = onReplacementOperator;
 exports.handleReplacementOperator = handleReplacementOperator;
 const handlers = [];
+/**
+ *
+ */
 function onReplacementOperator(handler) {
     handlers.push(handler);
 }
+/**
+ *
+ */
 function handleReplacementOperator(args) {
     handlers.forEach(handler => handler(args));
 }

package/dataflow/graph/unknown-side-effect.d.ts

@@ -3,5 +3,13 @@ import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-i
 import type { REnvironmentInformation } from '../environments/environment';
 import type { DataflowGraph } from './graph';
 export type UnknownSideEffectHandler = (graph: DataflowGraph, env: REnvironmentInformation, id: NodeId, target?: LinkTo<RegExp | string>) => void;
+/**
+ * Globally registers a handler for unknown side effects.
+ * @see {@link handleUnknownSideEffect} for triggering the handlers.
+ */
 export declare function onUnknownSideEffect(handler: UnknownSideEffectHandler): void;
+/**
+ * Handles an unknown side effect occurring at the given node in the dataflow graph.
+ * @see {@link onUnknownSideEffect} for registering handlers.
+ */
 export declare function handleUnknownSideEffect(graph: DataflowGraph, env: REnvironmentInformation, id: NodeId, target?: LinkTo<RegExp | string>): void;

package/dataflow/graph/unknown-side-effect.js

@@ -3,9 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.onUnknownSideEffect = onUnknownSideEffect;
 exports.handleUnknownSideEffect = handleUnknownSideEffect;
 const handlers = [];
+/**
+ * Globally registers a handler for unknown side effects.
+ * @see {@link handleUnknownSideEffect} for triggering the handlers.
+ */
 function onUnknownSideEffect(handler) {
     handlers.push(handler);
 }
+/**
+ * Handles an unknown side effect occurring at the given node in the dataflow graph.
+ * @see {@link onUnknownSideEffect} for registering handlers.
+ */
 function handleUnknownSideEffect(graph, env, id, target) {
     graph.markIdForUnknownSideEffects(id, target);
     handlers.forEach(handler => handler(graph, env, id, target));

package/dataflow/graph/vertex.d.ts

@@ -43,6 +43,9 @@ export interface NamedArgumentId {
     readonly index: number | undefined;
     readonly lexeme: string;
 }
+/**
+ * Type guard to check whether {@link identifier} is a {@link NamedArgumentId}.
+ */
 export declare function isNamedArgumentId(identifier: IndexIdentifier): identifier is NamedArgumentId;
 export type IndexIdentifier = UnnamedArgumentId | NamedArgumentId;
 /**
@@ -64,7 +67,6 @@ export interface ContainerLeafIndex {
  * A single index of a container, which is a container itself.
  *
  * This can be, e.g., a list, vector, or data frame.
- *
  * @see {@link ContainerLeafIndex} - for a single index of a container which is not a container itself
  * @see {@link isParentContainerIndex} - to check if an index is a parent container index
  */
@@ -74,6 +76,9 @@ export interface ContainerParentIndex extends ContainerLeafIndex {
      */
     readonly subIndices: ContainerIndices[];
 }
+/**
+ * Type guard to check whether {@link index} is a {@link ContainerParentIndex}.
+ */
 export declare function isParentContainerIndex(index: ContainerIndex): index is ContainerParentIndex;
 /**
  * A single index of a container.
@@ -81,13 +86,15 @@ export declare function isParentContainerIndex(index: ContainerIndex): index is
 export type ContainerIndex = ContainerLeafIndex | ContainerParentIndex;
 /**
  * Checks whether {@link index} is accessed by {@link accessLexeme}.
- *
  * @param index - The {@link ContainerIndex}, which is accessed
  * @param accessLexeme - The access lexeme
  * @param isIndexBasedAccess - Whether the index of the {@link ContainerIndex} is accessed i.e. the position in the container and not e.g. the name of the index
  * @returns true, when {@link accessLexeme} accesses the {@link index}, false otherwise
  */
 export declare function isAccessed(index: ContainerIndex, accessLexeme: string, isIndexBasedAccess: boolean): boolean;
+/**
+ * Checks whether two {@link ContainerIndex|container indices} are the same.
+ */
 export declare function isSameIndex(a: ContainerIndex, b: ContainerIndex): boolean;
 /**
  * List of indices of a single statement like `list(a=3, b=2)`
@@ -108,7 +115,6 @@ export interface ContainerIndices {
 export type ContainerIndicesCollection = ContainerIndices[] | undefined;
 /**
  * Arguments required to construct a vertex in the {@link DataflowGraph|dataflow graph}.
- *
  * @see DataflowGraphVertexUse
  * @see DataflowGraphVertexVariableDefinition
  * @see DataflowGraphVertexFunctionDefinition
@@ -153,7 +159,6 @@ export interface DataflowGraphVertexAstLink {
  *
  * 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)
@@ -164,7 +169,6 @@ export interface DataflowGraphVertexAstLink {
  *
  * 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 {
@@ -173,7 +177,6 @@ export interface DataflowGraphVertexValue extends DataflowGraphVertexBase {
 }
 /**
  * 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 {
@@ -185,7 +188,6 @@ export interface DataflowGraphVertexUse extends DataflowGraphVertexBase {
  * Arguments required to construct a vertex which represents the call to a function in the {@link DataflowGraph|dataflow graph}.
  * This describes all kinds of function calls, including calls to built-ins and control-flow structures such as `if` or `for` (they are
  * treated as function calls in R).
- *
  * @see {@link isFunctionCallVertex} - to check if a vertex is a function call vertex
  */
 export interface DataflowGraphVertexFunctionCall extends DataflowGraphVertexBase {
@@ -210,7 +212,6 @@ export interface DataflowGraphVertexFunctionCall extends DataflowGraphVertexBase
 export type FunctionOriginInformation = BuiltInMappingName | string;
 /**
  * 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 {
@@ -220,7 +221,6 @@ export interface DataflowGraphVertexVariableDefinition extends DataflowGraphVert
 }
 /**
  * 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 {

package/dataflow/graph/vertex.js

@@ -20,15 +20,20 @@ var VertexType;
 })(VertexType || (exports.VertexType = VertexType = {}));
 exports.ValidVertexTypes = new Set(Object.values(VertexType));
 exports.ValidVertexTypeReverse = Object.fromEntries(Object.entries(VertexType).map(([k, v]) => [v, k]));
+/**
+ * Type guard to check whether {@link identifier} is a {@link NamedArgumentId}.
+ */
 function isNamedArgumentId(identifier) {
     return 'lexeme' in identifier;
 }
+/**
+ * Type guard to check whether {@link index} is a {@link ContainerParentIndex}.
+ */
 function isParentContainerIndex(index) {
     return 'subIndices' in index;
 }
 /**
  * Checks whether {@link index} is accessed by {@link accessLexeme}.
- *
  * @param index - The {@link ContainerIndex}, which is accessed
  * @param accessLexeme - The access lexeme
  * @param isIndexBasedAccess - Whether the index of the {@link ContainerIndex} is accessed i.e. the position in the container and not e.g. the name of the index
@@ -43,6 +48,9 @@ function isAccessed(index, accessLexeme, isIndexBasedAccess) {
     }
     return false;
 }
+/**
+ * Checks whether two {@link ContainerIndex|container indices} are the same.
+ */
 function isSameIndex(a, b) {
     if (isNamedArgumentId(a.identifier) && isNamedArgumentId(b.identifier)) {
         return a.identifier.lexeme === b.identifier.lexeme;

package/dataflow/info.d.ts

@@ -8,7 +8,6 @@ import type { GenericDifferenceInformation, WriteableDifferenceReport } from '..
  * 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 {
@@ -16,10 +15,11 @@ export interface ControlDependency {
     readonly id: NodeId;
     /** when does this control dependency trigger (if the condition is true or false)? */
     readonly when?: boolean;
+    /** whether this control dependency was created due to iteration (e.g., a loop) */
+    readonly byIteration?: boolean;
 }
 /**
  * Classifies the type of exit point encountered.
- *
  * @see {@link ExitPoint}
  */
 export declare const enum ExitPointType {
@@ -35,7 +35,6 @@ export declare const enum ExitPointType {
 /**
  * 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
@@ -49,7 +48,6 @@ export interface ExitPoint {
     /**
      * 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;
@@ -73,7 +71,6 @@ export interface DataflowCfgInformation {
  * 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 {
@@ -82,19 +79,16 @@ export interface DataflowInformation extends DataflowCfgInformation {
      *
      * 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 within the current subtree.
-     *
      * @see {@link IdentifierReference} - a reference on a variable, parameter, function call, ...
-     * */
+     */
     in: readonly IdentifierReference[];
     /**
      * References which are written to within the current subtree
-     *
      * @see {@link IdentifierReference} - a reference on a variable, parameter, function call, ...
      */
     out: readonly IdentifierReference[];
@@ -106,7 +100,6 @@ export interface DataflowInformation extends DataflowCfgInformation {
 /**
  * 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' | 'builtInEnvironment' | 'completeAst'>): DataflowInformation;
@@ -124,5 +117,11 @@ 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[];
+/**
+ * Calculates the difference between two control dependencies.
+ */
 export declare function diffControlDependency<Report extends WriteableDifferenceReport>(a: ControlDependency | undefined, b: ControlDependency | undefined, info: GenericDifferenceInformation<Report>): void;
+/**
+ * Calculates the difference between two lists of control dependencies.
+ */
 export declare function diffControlDependencies<Report extends WriteableDifferenceReport>(a: ControlDependency[] | undefined, b: ControlDependency[] | undefined, info: GenericDifferenceInformation<Report>): void;

package/dataflow/info.js

@@ -17,7 +17,6 @@ function addNonDefaultExitPoints(existing, add) {
 /**
  * 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) {
@@ -69,6 +68,9 @@ function alwaysExits(data) {
 function filterOutLoopExitPoints(exitPoints) {
     return exitPoints.filter(({ type }) => type === 1 /* ExitPointType.Return */ || type === 0 /* ExitPointType.Default */);
 }
+/**
+ * Calculates the difference between two control dependencies.
+ */
 function diffControlDependency(a, b, info) {
     if (a === undefined || b === undefined) {
         if (a !== b) {
@@ -83,6 +85,9 @@ function diffControlDependency(a, b, info) {
         info.report.addComment(`${info.position}Different control dependency when. ${info.leftname}: ${a.when} vs. ${info.rightname}: ${b.when}`);
     }
 }
+/**
+ * Calculates the difference between two lists of control dependencies.
+ */
 function diffControlDependencies(a, b, info) {
     if (a === undefined || b === undefined) {
         if (a !== b) {