@eagleoutice/flowr 2.9.13 → 2.10.1

package/dataflow/graph/call-graph.d.ts

@@ -1,30 +1,57 @@
 import { DataflowGraph } from './graph';
 import type { DataflowGraphVertexFunctionCall, DataflowGraphVertexFunctionDefinition } from './vertex';
+import type { REnvironmentInformation } from '../environments/environment';
 import { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import { DefaultMap } from '../../util/collections/defaultmap';
 /**
  * A call graph is a dataflow graph where all vertices are function calls.
- * You can create a call graph from a dataflow graph using {@link computeCallGraph}.
- * If you want to extract a sub call graph, use {@link getSubCallGraph}.
+ * You can create a call graph from a dataflow graph using {@link CallGraph.compute}.
+ * If you want to extract a sub call graph, use {@link CallGraph.computeSubCallGraph}.
  * @see {@link dropTransitiveEdges} - to reduce the call graph by dropping transitive edges
  */
 export type CallGraph = DataflowGraph<Required<DataflowGraphVertexFunctionCall | DataflowGraphVertexFunctionDefinition>>;
+export interface State {
+    visited: Set<NodeId>;
+    potentials: [NodeId, Set<NodeId>][];
+}
 /**
- * Extracts the sub call graph from the given call graph, starting from the given entry points.
+ * Helper object for call-graphs, you can compute new call graphs based on {@link CallGraph.compute}.
+ * @see {@link Dataflow}
+ * @see {@link CallGraph}
  */
-export declare function getSubCallGraph(graph: CallGraph, entryPoints: Set<NodeId>): CallGraph;
-/**
- * Determines whether there is a path from `from` to `to` in the given graph (via any edge type, only respecting direction)
- */
-export declare function reaches(from: NodeId, to: NodeId, graph: DataflowGraph, knownReachability?: DefaultMap<NodeId, Set<NodeId>>): boolean;
-/**
- * Reduces the call graph by dropping all transitive edges.
- */
-export declare function dropTransitiveEdges(graph: CallGraph): CallGraph;
-/**
- * Computes the call graph from the given dataflow graph.
- * @see {@link CallGraph} - for details
- * @see {@link getSubCallGraph} - to extract sub call graphs
- * @see {@link dropTransitiveEdges} - to reduce the call graph by dropping transitive edges
- */
-export declare function computeCallGraph(graph: DataflowGraph): CallGraph;
+export declare const CallGraph: {
+    /**
+     * Extracts the sub call graph from the given call graph, starting from the given entry points.
+     */
+    readonly computeSubCallGraph: (this: void, graph: CallGraph, entryPoints: Set<NodeId>) => CallGraph;
+    /**
+     * Reduces the call graph by dropping all transitive edges.
+     */
+    readonly dropTransitiveEdges: (this: void, graph: CallGraph) => CallGraph;
+    /**
+     * Computes the call graph from the given dataflow graph.
+     * @see {@link CallGraph} - for details
+     * @see {@link CallGraph.computeSubCallGraph} - to extract sub call graphs
+     * @see {@link CallGraph.dropTransitiveEdges} - to reduce the call graph by dropping transitive edges
+     */
+    readonly compute: (this: void, graph: DataflowGraph) => CallGraph;
+    readonly visualize: {
+        readonly mermaid: {
+            readonly name: "DataflowMermaid";
+            readonly convert: (this: void, config: import("../../util/mermaid/dfg").MermaidGraphConfiguration) => {
+                string: string;
+                mermaid: import("../../util/mermaid/dfg").MermaidGraph;
+            };
+            readonly raw: (this: void, graph: DataflowGraph | import("../info").DataflowInformation, includeEnvironments?: boolean, mark?: ReadonlySet<NodeId>, simplified?: boolean) => string;
+            readonly url: (this: void, graph: DataflowGraph | import("../info").DataflowInformation, includeEnvironments?: boolean, mark?: ReadonlySet<NodeId>, simplified?: boolean) => string;
+        };
+        readonly quads: {
+            readonly convert: typeof import("./quads").df2quads;
+        };
+    };
+    readonly diffGraphs: <G extends DataflowGraph>(this: void, left: import("../../util/diff-graph").NamedGraph<G>, right: import("../../util/diff-graph").NamedGraph<G>, config?: Partial<import("../../util/diff").GenericDiffConfiguration>) => import("../../util/diff-graph").GraphDifferenceReport;
+    readonly invertGraph: <G extends DataflowGraph>(this: void, graph: G, cleanEnv: REnvironmentInformation) => G;
+    readonly resolveGraphCriteria: <G extends DataflowGraph>(graph: G, ctx: import("../../project/context/flowr-analyzer-context").ReadOnlyFlowrAnalyzerContext, idMap?: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").AstIdMap) => G;
+    readonly reaches: <G extends DataflowGraph>(this: void, from: NodeId, to: NodeId, graph: G, knownReachability?: DefaultMap<NodeId, Set<NodeId>>) => boolean;
+    readonly name: "CallGraph";
+};

package/dataflow/graph/call-graph.js

@@ -1,124 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSubCallGraph = getSubCallGraph;
-exports.reaches = reaches;
-exports.dropTransitiveEdges = dropTransitiveEdges;
-exports.computeCallGraph = computeCallGraph;
+exports.CallGraph = void 0;
 const graph_1 = require("./graph");
 const vertex_1 = require("./vertex");
 const node_id_1 = require("../../r-bridge/lang-4.x/ast/model/processing/node-id");
 const linker_1 = require("../internal/linker");
 const edge_1 = require("./edge");
-const built_in_1 = require("../environments/built-in");
+const built_in_proc_name_1 = require("../environments/built-in-proc-name");
 const defaultmap_1 = require("../../util/collections/defaultmap");
-/**
- * Extracts the sub call graph from the given call graph, starting from the given entry points.
- */
-function getSubCallGraph(graph, entryPoints) {
-    const result = new graph_1.DataflowGraph(graph.idMap);
-    const toVisit = Array.from(entryPoints);
-    const visited = new Set();
-    while (toVisit.length > 0) {
-        const currentId = toVisit.pop();
-        if (visited.has(currentId)) {
-            continue;
-        }
-        visited.add(currentId);
-        const currentVtx = graph.getVertex(currentId);
-        if (!currentVtx) {
-            continue;
-        }
-        result.addVertex(currentVtx, undefined, true);
-        for (const [tar, e] of graph.outgoingEdges(currentId) ?? []) {
-            if (edge_1.DfEdge.includesType(e, edge_1.EdgeType.Calls)) {
-                result.addEdge(currentId, tar, edge_1.EdgeType.Calls);
-                toVisit.push(tar);
-            }
-        }
-    }
-    return result;
-}
-/**
- * Determines whether there is a path from `from` to `to` in the given graph (via any edge type, only respecting direction)
- */
-function reaches(from, to, graph, knownReachability = new defaultmap_1.DefaultMap(() => new Set())) {
-    const visited = new Set();
-    const toVisit = [from];
-    while (toVisit.length > 0) {
-        const currentId = toVisit.pop();
-        if (visited.has(currentId)) {
-            continue;
-        }
-        if (currentId === to) {
-            knownReachability.get(from).add(to);
-            return true;
-        }
-        else if (knownReachability.get(currentId).has(to)) {
-            knownReachability.get(from).add(to);
-            return true;
-        }
-        visited.add(currentId);
-        for (const [tar] of graph.outgoingEdges(currentId) ?? []) {
-            toVisit.push(tar);
-        }
-    }
-    return false;
-}
-/**
- * Reduces the call graph by dropping all transitive edges.
- */
-function dropTransitiveEdges(graph) {
-    const newCg = new graph_1.DataflowGraph(graph.idMap);
-    newCg.mergeVertices(graph);
-    const knownReachability = new defaultmap_1.DefaultMap(() => new Set());
-    // heuristically sort by dif in ids
-    const es = Array.from(graph.edges(), ([e, ts]) => ts.entries().map(([t, { types }]) => [e, t, types]).toArray()).flat()
-        .sort((a, b) => String(a[0]).localeCompare(String(a[1])) - String(b[0]).localeCompare(String(b[1])));
-    for (const [from, to, types] of es) {
-        if (!reaches(from, to, newCg, knownReachability)) {
-            newCg.addEdge(from, to, types);
-        }
-    }
-    return newCg;
-}
-/**
- * Computes the call graph from the given dataflow graph.
- * @see {@link CallGraph} - for details
- * @see {@link getSubCallGraph} - to extract sub call graphs
- * @see {@link dropTransitiveEdges} - to reduce the call graph by dropping transitive edges
- */
-function computeCallGraph(graph) {
-    const result = new graph_1.DataflowGraph(graph.idMap);
-    const state = {
-        visited: new Set(),
-        potentials: []
-    };
-    for (const [, vert] of graph.vertices(false)) {
-        if (vert.tag === vertex_1.VertexType.FunctionCall) {
-            processCall(vert, undefined, graph, result, state);
-        }
-        else if (vert.tag === vertex_1.VertexType.FunctionDefinition) {
-            processFunctionDefinition(vert, undefined, graph, result, state);
-        }
-    }
-    for (const [from, tos] of state.potentials) {
-        for (const to of tos) {
-            if (!result.hasVertex(to)) {
-                const v = graph.getVertex(to);
-                if (v) {
-                    processUnknown(v, from, graph, result, state);
-                    if (v.tag === vertex_1.VertexType.FunctionDefinition) {
-                        processFunctionDefinition(v, from, graph, result, state);
-                    }
-                }
-            }
-            else {
-                result.addEdge(from, to, edge_1.EdgeType.Calls);
-            }
-        }
-    }
-    return result;
-}
+const graph_helper_1 = require("./graph-helper");
 function processCds(vtx, graph, result, state) {
     for (const tar of vtx.cds ?? []) {
         const targetVtx = graph.getVertex(tar.id);
@@ -213,7 +103,7 @@ function processCall(vtx, from, graph, result, state) {
                     tag: vertex_1.VertexType.FunctionCall,
                     name: name.lexeme,
                     onlyBuiltin: false,
-                    origin: [built_in_1.BuiltInProcName.Function],
+                    origin: [built_in_proc_name_1.BuiltInProcName.Function],
                     args: []
                 }, oriVtx.environment);
             }
@@ -264,4 +154,95 @@ function processFunctionDefinition(vtx, from, graph, result, state) {
         }
     }
 }
+/**
+ * Helper object for call-graphs, you can compute new call graphs based on {@link CallGraph.compute}.
+ * @see {@link Dataflow}
+ * @see {@link CallGraph}
+ */
+exports.CallGraph = {
+    name: 'CallGraph',
+    ...graph_helper_1.GraphHelper,
+    /**
+     * Extracts the sub call graph from the given call graph, starting from the given entry points.
+     */
+    computeSubCallGraph(graph, entryPoints) {
+        const result = new graph_1.DataflowGraph(graph.idMap);
+        const toVisit = Array.from(entryPoints);
+        const visited = new Set();
+        while (toVisit.length > 0) {
+            const currentId = toVisit.pop();
+            if (visited.has(currentId)) {
+                continue;
+            }
+            visited.add(currentId);
+            const currentVtx = graph.getVertex(currentId);
+            if (!currentVtx) {
+                continue;
+            }
+            result.addVertex(currentVtx, undefined, true);
+            for (const [tar, e] of graph.outgoingEdges(currentId) ?? []) {
+                if (edge_1.DfEdge.includesType(e, edge_1.EdgeType.Calls)) {
+                    result.addEdge(currentId, tar, edge_1.EdgeType.Calls);
+                    toVisit.push(tar);
+                }
+            }
+        }
+        return result;
+    },
+    /**
+     * Reduces the call graph by dropping all transitive edges.
+     */
+    dropTransitiveEdges(graph) {
+        const newCg = new graph_1.DataflowGraph(graph.idMap);
+        newCg.mergeVertices(graph);
+        const knownReachability = new defaultmap_1.DefaultMap(() => new Set());
+        // heuristically sort by dif in ids
+        const es = Array.from(graph.edges(), ([e, ts]) => ts.entries().map(([t, { types }]) => [e, t, types]).toArray()).flat()
+            .sort((a, b) => String(a[0]).localeCompare(String(a[1])) - String(b[0]).localeCompare(String(b[1])));
+        for (const [from, to, types] of es) {
+            if (!exports.CallGraph.reaches(from, to, newCg, knownReachability)) {
+                newCg.addEdge(from, to, types);
+            }
+        }
+        return newCg;
+    },
+    /**
+     * Computes the call graph from the given dataflow graph.
+     * @see {@link CallGraph} - for details
+     * @see {@link CallGraph.computeSubCallGraph} - to extract sub call graphs
+     * @see {@link CallGraph.dropTransitiveEdges} - to reduce the call graph by dropping transitive edges
+     */
+    compute(graph) {
+        const result = new graph_1.DataflowGraph(graph.idMap);
+        const state = {
+            visited: new Set(),
+            potentials: []
+        };
+        for (const [, vert] of graph.vertices(false)) {
+            if (vert.tag === vertex_1.VertexType.FunctionCall) {
+                processCall(vert, undefined, graph, result, state);
+            }
+            else if (vert.tag === vertex_1.VertexType.FunctionDefinition) {
+                processFunctionDefinition(vert, undefined, graph, result, state);
+            }
+        }
+        for (const [from, tos] of state.potentials) {
+            for (const to of tos) {
+                if (!result.hasVertex(to)) {
+                    const v = graph.getVertex(to);
+                    if (v) {
+                        processUnknown(v, from, graph, result, state);
+                        if (v.tag === vertex_1.VertexType.FunctionDefinition) {
+                            processFunctionDefinition(v, from, graph, result, state);
+                        }
+                    }
+                }
+                else {
+                    result.addEdge(from, to, edge_1.EdgeType.Calls);
+                }
+            }
+        }
+        return result;
+    }
+};
 //# sourceMappingURL=call-graph.js.map

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

@@ -12,7 +12,7 @@ import type { HookInformation } from '../hooks';
  * Creates an empty dataflow graph.
  * Should only be used in tests and documentation.
  */
-export declare function emptyGraph(cleanEnv?: REnvironmentInformation, idMap?: AstIdMap): DataflowGraphBuilder<DataflowGraphVertexInfo>;
+export declare function emptyGraph(this: void, cleanEnv?: REnvironmentInformation, idMap?: AstIdMap): DataflowGraphBuilder<DataflowGraphVertexInfo>;
 export type DataflowGraphEdgeTarget = NodeId | (readonly NodeId[]);
 /**
  * This DataflowGraphBuilder extends {@link DataflowGraph} with builder methods to

package/dataflow/graph/dataflowgraph-builder.js

@@ -8,12 +8,12 @@ const node_id_1 = require("../../r-bridge/lang-4.x/ast/model/processing/node-id"
 const graph_1 = require("./graph");
 const vertex_1 = require("./vertex");
 const r_function_call_1 = require("../../r-bridge/lang-4.x/ast/model/nodes/r-function-call");
-const built_in_1 = require("../environments/built-in");
 const edge_1 = require("./edge");
 const default_builtin_config_1 = require("../environments/default-builtin-config");
 const flowr_search_executor_1 = require("../../search/flowr-search-executor");
 const assert_1 = require("../../util/assert");
 const flowr_analyzer_context_1 = require("../../project/context/flowr-analyzer-context");
+const built_in_proc_name_1 = require("../environments/built-in-proc-name");
 /**
  * Creates an empty dataflow graph.
  * Should only be used in tests and documentation.
@@ -85,7 +85,7 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
             environment: (info?.onlyBuiltIn || onlyBuiltInAuto) ? undefined : info?.environment ?? this.defaultEnvironment,
             cds: info?.cds?.map(c => ({ ...c, id: node_id_1.NodeId.normalize(c.id) })),
             onlyBuiltin: info?.onlyBuiltIn ?? onlyBuiltInAuto ?? false,
-            origin: info?.origin ?? [(0, default_builtin_config_1.getDefaultProcessor)(name) ?? built_in_1.BuiltInProcName.Function],
+            origin: info?.origin ?? [(0, default_builtin_config_1.getDefaultProcessor)(name) ?? built_in_proc_name_1.BuiltInProcName.Function],
             link: info?.link
         }, asRoot);
         if (!info?.omitArgs) {

package/dataflow/graph/df-helper.d.ts

@@ -0,0 +1,133 @@
+import { DataflowGraph } from './graph';
+import { EdgeType } from './edge';
+import { emptyGraph } from './dataflowgraph-builder';
+import { getOriginInDfg } from '../origin/dfg-get-origin';
+import { CallGraph } from './call-graph';
+import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
+import type { REnvironmentInformation } from '../environments/environment';
+/**
+ * This is the root helper object to work with the {@link DataflowGraph}.
+ *
+ * - {@link Dataflow.visualize} - for visualization helpers (e.g., rendering the DFG as a mermaid graph),
+ * - {@link Dataflow.views} - for working with specific views of the dataflow graph (e.g., the call graph),
+ * - {@link Dataflow.edge} - for working with the edges in the dataflow graph,
+ */
+export declare const Dataflow: {
+    /**
+     * Maps to flowR's dataflow edge helper to work with the edges in the dataflow graph
+     */
+    readonly edge: {
+        readonly name: "DfEdge";
+        readonly typesToNames: (this: void, { types }: {
+            types: number;
+        }) => Set<import("./edge").EdgeTypeName>;
+        readonly splitTypes: (this: void, { types }: {
+            types: number;
+        }) => EdgeType[];
+        readonly typeToName: (this: void, type: EdgeType) => string;
+        readonly includesType: (this: void, { types }: {
+            types: number;
+        }, typesToInclude: EdgeType) => boolean;
+        readonly doesNotIncludeType: (this: void, { types }: {
+            types: number;
+        }, any: EdgeType) => boolean;
+    };
+    /**
+     * Dispatches to helper objects that relate to (sub-) views of the dataflow graph, e.g. the call graph.
+     */
+    readonly views: {
+        /**
+         * Maps to flowR's helper object for the call-graph
+         */
+        readonly callGraph: {
+            readonly computeSubCallGraph: (this: void, graph: CallGraph, entryPoints: Set<NodeId>) => CallGraph;
+            readonly dropTransitiveEdges: (this: void, graph: CallGraph) => CallGraph;
+            readonly compute: (this: void, graph: DataflowGraph) => CallGraph;
+            readonly visualize: {
+                readonly mermaid: {
+                    readonly name: "DataflowMermaid";
+                    readonly convert: (this: void, config: import("../../util/mermaid/dfg").MermaidGraphConfiguration) => {
+                        string: string;
+                        mermaid: import("../../util/mermaid/dfg").MermaidGraph;
+                    };
+                    readonly raw: (this: void, graph: DataflowGraph | import("../info").DataflowInformation, includeEnvironments?: boolean, mark?: ReadonlySet<NodeId>, simplified?: boolean) => string;
+                    readonly url: (this: void, graph: DataflowGraph | import("../info").DataflowInformation, includeEnvironments?: boolean, mark?: ReadonlySet<NodeId>, simplified?: boolean) => string;
+                };
+                readonly quads: {
+                    readonly convert: typeof import("./quads").df2quads;
+                };
+            };
+            readonly diffGraphs: <G extends DataflowGraph>(this: void, left: import("../../util/diff-graph").NamedGraph<G>, right: import("../../util/diff-graph").NamedGraph<G>, config?: Partial<import("../../util/diff").GenericDiffConfiguration>) => import("../../util/diff-graph").GraphDifferenceReport;
+            readonly invertGraph: <G extends DataflowGraph>(this: void, graph: G, cleanEnv: REnvironmentInformation) => G;
+            readonly resolveGraphCriteria: <G extends DataflowGraph>(graph: G, ctx: import("../../project/context/flowr-analyzer-context").ReadOnlyFlowrAnalyzerContext, idMap?: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").AstIdMap) => G;
+            readonly reaches: <G extends DataflowGraph>(this: void, from: NodeId, to: NodeId, graph: G, knownReachability?: import("../../util/collections/defaultmap").DefaultMap<NodeId, Set<NodeId>>) => boolean;
+            readonly name: "CallGraph";
+        };
+    };
+    /**
+     * Dispatches to helper functions to create new dataflow graphs, e.g. from a pipeline or an empty graph.
+     */
+    readonly create: {
+        /**
+         * Creates an empty dataflow graph with the given id map (or a new one if not provided).
+         * @see {@link emptyGraph}
+         */
+        readonly empty: typeof emptyGraph;
+    };
+    /**
+     * Returns the origin of a vertex in the dataflow graph
+     * @see {@link getOriginInDfg} - for the underlying function
+     */
+    readonly origin: typeof getOriginInDfg;
+    /**
+     * Only returns the sub-part of the graph that is determined by the given selection.
+     * In other words, this will return a graph with only vertices that are part of the selected ids,
+     * and edges that are between such selected vertices.
+     * @param graph                 - the dataflow graph to slice for
+     * @param select                - the ids to select in the reduced graph
+     * @param includeMissingTargets - if set to true, this will include edges which target vertices that are not selected!
+     */
+    readonly reduceGraph: <G extends DataflowGraph>(this: void, graph: G, select: ReadonlySet<NodeId>, includeMissingTargets?: boolean) => G;
+    /**
+     * Given the id of a vertex (usually a variable use),
+     * this returns a reachable provenance set by calculating a non-interprocedural and non-context sensitive backward slice, but stopping at the given ids!
+     * You can obtain the corresponding graph using {@link Dataflow.reduceGraph}.
+     * @param id       - The id to use as a seed for provenance calculation
+     * @param graph    - The graph to perform the provenance calculation on
+     * @param consider - The ids to restrict the calculation too (e.g., the ids contained within a function definition to restrict the analysis to)
+     * @see {@link Dataflow.provenanceGraph} - for a convenience wrapper to directly obtain the graph of the provenance.
+     */
+    readonly provenance: (this: void, id: NodeId, graph: DataflowGraph, consider?: ReadonlySet<NodeId>) => Set<NodeId>;
+    /**
+     * A convenience wrapper for {@link Dataflow.reduceGraph|reducing} the {@link Dataflow.provenance|provenance} of a graph.
+     * @param id       - The id to use as a seed for provenance calculation
+     * @param graph    - The graph to perform the provenance calculation on
+     * @param consider - The ids to restrict the calculation too (e.g., the ids contained within a function definition to restrict the analysis to)
+     * @see {@link Dataflow.provenance}
+     */
+    readonly provenanceGraph: (this: void, id: NodeId, graph: DataflowGraph, consider?: ReadonlySet<NodeId>) => DataflowGraph;
+    readonly visualize: {
+        readonly mermaid: {
+            readonly name: "DataflowMermaid";
+            readonly convert: (this: void, config: import("../../util/mermaid/dfg").MermaidGraphConfiguration) => {
+                string: string;
+                mermaid: import("../../util/mermaid/dfg").MermaidGraph;
+            };
+            readonly raw: (this: void, graph: DataflowGraph | import("../info").DataflowInformation, includeEnvironments?: boolean, mark?: ReadonlySet<NodeId>, simplified?: boolean) => string;
+            readonly url: (this: void, graph: DataflowGraph | import("../info").DataflowInformation, includeEnvironments?: boolean, mark?: ReadonlySet<NodeId>, simplified?: boolean) => string;
+        };
+        readonly quads: {
+            readonly convert: typeof import("./quads").df2quads;
+        };
+    };
+    readonly diffGraphs: <G extends DataflowGraph>(this: void, left: import("../../util/diff-graph").NamedGraph<G>, right: import("../../util/diff-graph").NamedGraph<G>, config?: Partial<import("../../util/diff").GenericDiffConfiguration>) => import("../../util/diff-graph").GraphDifferenceReport;
+    readonly invertGraph: <G extends DataflowGraph>(this: void, graph: G, cleanEnv: REnvironmentInformation) => G;
+    readonly resolveGraphCriteria: <G extends DataflowGraph>(graph: G, ctx: import("../../project/context/flowr-analyzer-context").ReadOnlyFlowrAnalyzerContext, idMap?: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").AstIdMap) => G;
+    readonly reaches: <G extends DataflowGraph>(this: void, from: NodeId, to: NodeId, graph: G, knownReachability?: import("../../util/collections/defaultmap").DefaultMap<NodeId, Set<NodeId>>) => boolean;
+    readonly name: "Dataflow";
+    /**
+     * Maps to flowR's main graph object to store and manipulate the dataflow graph
+     * @see {@link DataflowGraph}
+     */
+    readonly graph: typeof DataflowGraph;
+};

package/dataflow/graph/df-helper.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Dataflow = void 0;
+const graph_1 = require("./graph");
+const edge_1 = require("./edge");
+const dataflowgraph_builder_1 = require("./dataflowgraph-builder");
+const dfg_get_origin_1 = require("../origin/dfg-get-origin");
+const graph_helper_1 = require("./graph-helper");
+const call_graph_1 = require("./call-graph");
+/**
+ * This is the root helper object to work with the {@link DataflowGraph}.
+ *
+ * - {@link Dataflow.visualize} - for visualization helpers (e.g., rendering the DFG as a mermaid graph),
+ * - {@link Dataflow.views} - for working with specific views of the dataflow graph (e.g., the call graph),
+ * - {@link Dataflow.edge} - for working with the edges in the dataflow graph,
+ */
+exports.Dataflow = {
+    name: 'Dataflow',
+    /**
+     * Maps to flowR's main graph object to store and manipulate the dataflow graph
+     * @see {@link DataflowGraph}
+     */
+    graph: graph_1.DataflowGraph,
+    ...graph_helper_1.GraphHelper,
+    /**
+     * Maps to flowR's dataflow edge helper to work with the edges in the dataflow graph
+     */
+    edge: edge_1.DfEdge,
+    /**
+     * Dispatches to helper objects that relate to (sub-) views of the dataflow graph, e.g. the call graph.
+     */
+    views: {
+        /**
+         * Maps to flowR's helper object for the call-graph
+         */
+        callGraph: call_graph_1.CallGraph,
+    },
+    /**
+     * Dispatches to helper functions to create new dataflow graphs, e.g. from a pipeline or an empty graph.
+     */
+    create: {
+        /**
+         * Creates an empty dataflow graph with the given id map (or a new one if not provided).
+         * @see {@link emptyGraph}
+         */
+        empty: dataflowgraph_builder_1.emptyGraph
+    },
+    /**
+     * Returns the origin of a vertex in the dataflow graph
+     * @see {@link getOriginInDfg} - for the underlying function
+     */
+    origin: dfg_get_origin_1.getOriginInDfg,
+    /**
+     * Only returns the sub-part of the graph that is determined by the given selection.
+     * In other words, this will return a graph with only vertices that are part of the selected ids,
+     * and edges that are between such selected vertices.
+     * @param graph                 - the dataflow graph to slice for
+     * @param select                - the ids to select in the reduced graph
+     * @param includeMissingTargets - if set to true, this will include edges which target vertices that are not selected!
+     */
+    reduceGraph(graph, select, includeMissingTargets = false) {
+        const df = new graph_1.DataflowGraph(graph.idMap);
+        const roots = graph.rootIds();
+        // if the graph has no root ids all selected vertices are non-root in this case we just break the fdef selection and promote all to root!
+        const selectedRoots = roots.intersection(select);
+        const forceRoot = selectedRoots.size === 0;
+        for (const [id, vtx] of graph.vertices(true)) {
+            if (select.has(id)) {
+                df.addVertex(vtx, vtx.environment, forceRoot || roots.has(id));
+            }
+        }
+        for (const [from, targets] of graph.edges()) {
+            if (!select.has(from)) {
+                continue;
+            }
+            for (const [tar, { types }] of targets.entries()) {
+                if (!includeMissingTargets && !select.has(tar)) {
+                    continue;
+                }
+                df.addEdge(from, tar, types);
+            }
+        }
+        for (const u of graph.unknownSideEffects) {
+            if (typeof u === 'object' && select.has(u.id)) {
+                df.markIdForUnknownSideEffects(u.id, u.linkTo);
+            }
+            else if (select.has(u)) {
+                df.markIdForUnknownSideEffects(u);
+            }
+        }
+        return df;
+    },
+    /**
+     * Given the id of a vertex (usually a variable use),
+     * this returns a reachable provenance set by calculating a non-interprocedural and non-context sensitive backward slice, but stopping at the given ids!
+     * You can obtain the corresponding graph using {@link Dataflow.reduceGraph}.
+     * @param id       - The id to use as a seed for provenance calculation
+     * @param graph    - The graph to perform the provenance calculation on
+     * @param consider - The ids to restrict the calculation too (e.g., the ids contained within a function definition to restrict the analysis to)
+     * @see {@link Dataflow.provenanceGraph} - for a convenience wrapper to directly obtain the graph of the provenance.
+     */
+    provenance(id, graph, consider) {
+        const queue = [id];
+        const visited = new Set();
+        const followEdges = edge_1.EdgeType.Calls | edge_1.EdgeType.Reads | edge_1.EdgeType.Returns | edge_1.EdgeType.Argument | edge_1.EdgeType.DefinedBy | edge_1.EdgeType.DefinedByOnCall;
+        while (queue.length > 0) {
+            const nodeId = queue.pop();
+            if (nodeId === undefined || visited.has(nodeId) || (consider && !consider.has(nodeId))) {
+                continue;
+            }
+            visited.add(nodeId);
+            const vtx = graph.get(nodeId);
+            if (vtx === undefined) {
+                continue;
+            }
+            for (const [to, types] of vtx[1]) {
+                if (edge_1.DfEdge.includesType(types, followEdges)) {
+                    queue.push(to);
+                }
+            }
+            for (const cd of vtx[0].cds ?? []) {
+                queue.push(cd.id);
+            }
+        }
+        return visited;
+    },
+    /**
+     * A convenience wrapper for {@link Dataflow.reduceGraph|reducing} the {@link Dataflow.provenance|provenance} of a graph.
+     * @param id       - The id to use as a seed for provenance calculation
+     * @param graph    - The graph to perform the provenance calculation on
+     * @param consider - The ids to restrict the calculation too (e.g., the ids contained within a function definition to restrict the analysis to)
+     * @see {@link Dataflow.provenance}
+     */
+    provenanceGraph(id, graph, consider) {
+        return exports.Dataflow.reduceGraph(graph, exports.Dataflow.provenance(id, graph, consider));
+    }
+};
+//# sourceMappingURL=df-helper.js.map

package/dataflow/graph/diff-dataflow-graph.d.ts

@@ -1,17 +1,12 @@
 import { FunctionArgument, type OutgoingEdges } from './graph';
-import { type GenericDiffConfiguration, type GenericDifferenceInformation } from '../../util/diff';
+import { type GenericDifferenceInformation } from '../../util/diff';
 import { type NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
-import { type GraphDiffContext, type NamedGraph, GraphDifferenceReport } from '../../util/diff-graph';
+import type { GraphDifferenceReport, GraphDiffContext } from '../../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
+ * This is the underlying function to calculate the difference based on a given context.
+ * Use {@link Dataflow.diff} to calculate the diff of two graphs.
  */
-export declare function diffOfDataflowGraphs(left: NamedGraph, right: NamedGraph, config?: Partial<GenericDiffConfiguration>): GraphDifferenceReport;
-/**
- * Checks whether two function argument lists are equal.
- */
-export declare function equalFunctionArguments(fn: NodeId, a: false | readonly FunctionArgument[], b: false | readonly FunctionArgument[]): boolean;
+export declare function diffDataflowGraph(ctx: GraphDiffContext): void;
 /**
  * Compares two function argument lists and reports differences.
  */