@eagleoutice/flowr 2.6.1 → 2.6.2

package/cli/script-core/summarizer-core.d.ts

@@ -1,2 +1,5 @@
 import type { SummarizerCliOptions } from '../summarizer-app';
+/**
+ * The core function for the 'flowr summarize' script.
+ */
 export declare function flowrScriptSummarizer(options: SummarizerCliOptions): Promise<void>;

package/cli/script-core/summarizer-core.js

@@ -39,6 +39,9 @@ async function retrieveSummarizer(options, outputBase) {
         process.exit(1);
     }
 }
+/**
+ * The core function for the 'flowr summarize' script.
+ */
 async function flowrScriptSummarizer(options) {
     const outputBase = (options.output ?? options.input).replace(/\.json$|\/$/, '-summary');
     console.log(`Writing outputs to base ${outputBase}`);

package/cli/summarizer-app.d.ts

@@ -1,8 +1,7 @@
 /**
  * The summarizer intends to post-process and summarize the results of
- * * the benchmark tool, and
- * * the statistics extraction.
- *
+ * the benchmark tool, and
+ * the statistics extraction.
  * @module
  */
 export interface SummarizerCliOptions {

package/cli/summarizer-app.js

@@ -1,9 +1,8 @@
 "use strict";
 /**
  * The summarizer intends to post-process and summarize the results of
- * * the benchmark tool, and
- * * the statistics extraction.
- *
+ * the benchmark tool, and
+ * the statistics extraction.
  * @module
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/config.d.ts

@@ -1,4 +1,4 @@
-import type { MergeableRecord } from './util/objects';
+import { type MergeableRecord } from './util/objects';
 import Joi from 'joi';
 import type { BuiltInDefinitions } from './dataflow/environments/built-in-config';
 import type { KnownParser } from './r-bridge/parser';
@@ -59,10 +59,9 @@ export interface FlowrLaxSourcingOptions extends MergeableRecord {
      */
     readonly repeatedSourceLimit?: number;
     /**
-     * sometimes files may have a different name in the source call	(e.g., due to later replacements),
+     * sometimes files may have a different name in the source call (e.g., due to later replacements),
      * with this setting you can provide a list of replacements to apply for each sourced file.
      * Every replacement consists of a record that maps a regex to a replacement string.
-     *
      * @example
      * ```ts
      * [
@@ -205,14 +204,29 @@ export type KnownEngines = {
 };
 export declare const defaultConfigOptions: FlowrConfigOptions;
 export declare const flowrConfigFileSchema: Joi.ObjectSchema<any>;
+/**
+ * Parses the given JSON string as a flowR config file.
+ */
 export declare function parseConfig(jsonString: string): FlowrConfigOptions | undefined;
 /**
  * Creates a new flowr config that has the updated values.
  */
 export declare function amendConfig(config: FlowrConfigOptions, amendmentFunc: (config: DeepWritable<FlowrConfigOptions>) => FlowrConfigOptions | void): FlowrConfigOptions;
+/**
+ * Clones the given flowr config object.
+ */
 export declare function cloneConfig(config: FlowrConfigOptions): FlowrConfigOptions;
+/**
+ * Loads the flowr config from the given file or the default locations.
+ */
 export declare function getConfig(configFile?: string, configWorkingDirectory?: string): FlowrConfigOptions;
+/**
+ * Gets the configuration for the given engine type from the config.
+ */
 export declare function getEngineConfig<T extends EngineConfig['type']>(config: FlowrConfigOptions, engine: T): EngineConfig & {
     type: T;
 } | undefined;
+/**
+ * Checks whether the given count is over the pointer analysis threshold configured in the config.
+ */
 export declare function isOverPointerAnalysisThreshold(config: FlowrConfigOptions, count: number): boolean;

package/config.js

@@ -142,6 +142,9 @@ exports.flowrConfigFileSchema = joi_1.default.object({
         }).description('The configuration of the shape inference for data frames.')
     }).description('The configuration options for abstract interpretation.')
 }).description('The configuration file format for flowR.');
+/**
+ * Parses the given JSON string as a flowR config file.
+ */
 function parseConfig(jsonString) {
     try {
         const parsed = JSON.parse(jsonString);
@@ -168,9 +171,15 @@ function amendConfig(config, amendmentFunc) {
     amendmentFunc(newConfig);
     return newConfig;
 }
+/**
+ * Clones the given flowr config object.
+ */
 function cloneConfig(config) {
     return JSON.parse(JSON.stringify(config));
 }
+/**
+ * Loads the flowr config from the given file or the default locations.
+ */
 function getConfig(configFile, configWorkingDirectory = process.cwd()) {
     try {
         return loadConfigFromFile(configFile, configWorkingDirectory);
@@ -180,6 +189,9 @@ function getConfig(configFile, configWorkingDirectory = process.cwd()) {
         return exports.defaultConfigOptions;
     }
 }
+/**
+ * Gets the configuration for the given engine type from the config.
+ */
 function getEngineConfig(config, engine) {
     const engines = config.engines;
     if (!engines.length) {
@@ -198,6 +210,9 @@ function getPointerAnalysisThreshold(config) {
         return pointerTracking ? 'unlimited' : 'disabled';
     }
 }
+/**
+ * Checks whether the given count is over the pointer analysis threshold configured in the config.
+ */
 function isOverPointerAnalysisThreshold(config, count) {
     const threshold = getPointerAnalysisThreshold(config);
     return threshold !== 'unlimited' && (threshold === 'disabled' || count > threshold);

package/control-flow/basic-cfg-guided-visitor.d.ts

@@ -1,4 +1,4 @@
-import type { CfgBasicBlockVertex, CfgEndMarkerVertex, CfgExpressionVertex, CfgSimpleVertex, CfgStatementVertex, ControlFlowInformation } from './control-flow-graph';
+import { type CfgBasicBlockVertex, type CfgEndMarkerVertex, type CfgExpressionVertex, type CfgSimpleVertex, type CfgStatementVertex, type ControlFlowInformation } from './control-flow-graph';
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
 export interface BasicCfgGuidedVisitorConfiguration<ControlFlow extends ControlFlowInformation = ControlFlowInformation> {
     readonly controlFlow: ControlFlow;
@@ -17,7 +17,6 @@ export declare class BasicCfgGuidedVisitor<ControlFlow extends ControlFlowInform
     constructor(config: Config);
     /**
      * call this function to indicate that a node is to be considered visited.
-     *
      * @returns `true` if the node was not visited before, `false` otherwise
      */
     protected visitNode(node: NodeId): boolean;

package/control-flow/basic-cfg-guided-visitor.js

@@ -19,7 +19,6 @@ class BasicCfgGuidedVisitor {
     }
     /**
      * call this function to indicate that a node is to be considered visited.
-     *
      * @returns `true` if the node was not visited before, `false` otherwise
      */
     visitNode(node) {

package/control-flow/cfg-to-basic-blocks.d.ts

@@ -1,4 +1,4 @@
-import type { ControlFlowInformation } from './control-flow-graph';
+import { type ControlFlowInformation } from './control-flow-graph';
 /**
  * Take a control flow information of a graph without any basic blocks and convert it to a graph with basic blocks.
  */

package/control-flow/control-flow-graph.d.ts

@@ -17,6 +17,9 @@ export declare const enum CfgEdgeType {
     /** a control dependency */
     Cd = 1
 }
+/**
+ * Provide a string representation of the given edge type.
+ */
 export declare function edgeTypeToString(type: CfgEdgeType): string;
 /**
  * A plain vertex in the {@link ControlFlowGraph}.
@@ -60,8 +63,18 @@ export interface CfgBasicBlockVertex extends CfgBaseVertex {
  * A vertex in the {@link ControlFlowGraph}.
  */
 export type CfgSimpleVertex = CfgStatementVertex | CfgExpressionVertex | CfgBasicBlockVertex | CfgEndMarkerVertex;
+/**
+ * Checks whether two vertices are equal.
+ */
 export declare function equalVertex(a: CfgSimpleVertex, b: CfgSimpleVertex): boolean;
+/**
+ * Checks whether a vertex is a marker vertex (i.e., does not correspond to an actual AST node
+ * but is a marker in the control flow graph).
+ */
 export declare function isMarkerVertex(vertex: CfgSimpleVertex): vertex is CfgEndMarkerVertex;
+/**
+ * Get the root id of a vertex, i.e., the id of the AST node it corresponds to.
+ */
 export declare function getVertexRootId(vertex: CfgSimpleVertex): NodeId;
 interface CfgFlowDependencyEdge extends MergeableRecord {
     label: CfgEdgeType.Fd;
@@ -83,7 +96,6 @@ export interface ReadOnlyControlFlowGraph {
      * any function definition or basic block and hence part of the "top-level" control flow.
      *
      * This is the pendant of {@link DataflowGraph#rootIds|rootIds()} on a {@link DataflowGraph}.
-     *
      * @see {@link ReadOnlyControlFlowGraph#vertices|vertices()} - for a way to get all vertices in the graph.
      * @see {@link ReadOnlyControlFlowGraph#getVertex|getVertex()} - for a way to get a specific vertex by its id.
      * @see {@link ReadOnlyControlFlowGraph#edges|edges()} - for a way to get all edges in the graph.
@@ -91,9 +103,7 @@ export interface ReadOnlyControlFlowGraph {
     readonly rootIds: () => ReadonlySet<NodeId>;
     /**
      * Provide a view of all vertices in the graph.
-     *
      * @param includeBasicBlockElements - if true, the elements of basic block elements are included in the result, otherwise this will only the basic blocks themselves
-     *
      * @see {@link ReadOnlyControlFlowGraph#rootVertexIds|rootVertexIds()} - for a way to get the root vertices of the graph.
      * @see {@link ReadOnlyControlFlowGraph#getVertex|getVertex()} - for a way to get a specific vertex by its id.
      * @see {@link ReadOnlyControlFlowGraph#edges|edges()} - for a way to get all edges in the graph.
@@ -110,7 +120,6 @@ export interface ReadOnlyControlFlowGraph {
      * Receive all outgoing edges of a given vertex.
      *
      * This is the pendant of {@link DataflowGraph#ingoingEdges|ingoingEdges()} on a {@link DataflowGraph}.
-     *
      * @see {@link ReadOnlyControlFlowGraph#ingoingEdges|ingoingEdges()} - for a way to get all ingoing edges of a vertex.
      */
     readonly outgoingEdges: (id: NodeId) => ReadonlyMap<NodeId, CfgEdge> | undefined;
@@ -118,13 +127,11 @@ export interface ReadOnlyControlFlowGraph {
      * Receive all ingoing edges of a given vertex.
      *
      * This is the pendant of {@link DataflowGraph#outgoingEdges|outgoingEdges()} on a {@link DataflowGraph}.
-     *
      * @see {@link ReadOnlyControlFlowGraph#outgoingEdges|outgoingEdges()} - for a way to get all outgoing edges of a vertex.
      */
     readonly ingoingEdges: (id: NodeId) => ReadonlyMap<NodeId, CfgEdge> | undefined;
     /**
      * Retrieve a vertex by its id.
-     *
      * @param id - the id of the vertex to retrieve
      * @param includeBlocks - if true, the elements of basic block elements are included in the result, otherwise this will only the basic blocks themselves
      *
@@ -133,7 +140,6 @@ export interface ReadOnlyControlFlowGraph {
     readonly getVertex: (id: NodeId, includeBlocks?: boolean) => CfgSimpleVertex | undefined;
     /**
      * Check if a vertex with the given id exists in the graph.
-     *
      * @param id - the id of the vertex to check
      * @param includeBlocks - if true, the elements of basic block elements are included in the check, otherwise this will only check the basic blocks themselves
      *
@@ -172,13 +178,11 @@ export declare class ControlFlowGraph<Vertex extends CfgSimpleVertex = CfgSimple
     private _mayHaveBasicBlocks;
     /**
      * Add a new vertex to the control flow graph.
-     *
      * @see {@link ControlFlowGraph#addEdge|addEdge()} - to add an edge
      */
     addVertex(vertex: Vertex, rootVertex?: boolean): this;
     /**
      * Add a new edge to the control flow graph.
-     *
      * @see {@link ControlFlowGraph#addVertex|addVertex()} - to add vertices
      * @see {@link ControlFlowGraph#addEdges|addEdges()} - to add multiple edges at once
      */
@@ -202,14 +206,12 @@ export declare class ControlFlowGraph<Vertex extends CfgSimpleVertex = CfgSimple
     /**
      * This removes the vertex and all edges to and from it.
      * @param id - the id of the vertex to remove
-     *
      * @see {@link ControlFlowGraph#addVertex|addVertex()} - to add a vertex
      * @see {@link ControlFlowGraph#removeEdge|removeEdge()} - to remove a specific edge
      */
     removeVertex(id: NodeId): this;
     /**
      * Removes a all direct edges between `from` and `to` from the control flow graph.
-     *
      * @see {@link ControlFlowGraph#addEdge|addEdge()} - to add an edge
      * @see {@link ControlFlowGraph#removeVertex|removeVertex()} - to remove a vertex and all its edges
      */
@@ -225,7 +227,10 @@ export declare class ControlFlowGraph<Vertex extends CfgSimpleVertex = CfgSimple
      */
     mergeWith(other: ControlFlowGraph<Vertex>, forceNested?: boolean): this;
 }
-/** Summarizes the control information of a program */
+/**
+ * Summarizes the control information of a program
+ * @see {@link emptyControlFlowInformation} - to create an empty control flow information object
+ */
 export interface ControlFlowInformation<Vertex extends CfgSimpleVertex = CfgSimpleVertex> extends MergeableRecord {
     /** all active 'return'(-like) unconditional jumps */
     returns: NodeId[];
@@ -240,5 +245,8 @@ export interface ControlFlowInformation<Vertex extends CfgSimpleVertex = CfgSimp
     /** the control flow graph summarizing the flow information */
     graph: ControlFlowGraph<Vertex>;
 }
+/**
+ * Create an empty control flow information object.
+ */
 export declare function emptyControlFlowInformation(): ControlFlowInformation;
 export {};

package/control-flow/control-flow-graph.js

@@ -18,6 +18,9 @@ var CfgVertexType;
     /** a (as far as R allows this) 'basic' block */
     CfgVertexType["Block"] = "blk";
 })(CfgVertexType || (exports.CfgVertexType = CfgVertexType = {}));
+/**
+ * Provide a string representation of the given edge type.
+ */
 function edgeTypeToString(type) {
     switch (type) {
         case 0 /* CfgEdgeType.Fd */:
@@ -28,6 +31,9 @@ function edgeTypeToString(type) {
             throw new Error(`Unknown edge type ${JSON.stringify(type)}`);
     }
 }
+/**
+ * Checks whether two vertices are equal.
+ */
 function equalVertex(a, b) {
     if (a.type !== b.type || a.id !== b.id) {
         return false;
@@ -40,9 +46,16 @@ function equalVertex(a, b) {
     }
     return true;
 }
+/**
+ * Checks whether a vertex is a marker vertex (i.e., does not correspond to an actual AST node
+ * but is a marker in the control flow graph).
+ */
 function isMarkerVertex(vertex) {
     return vertex.type === CfgVertexType.EndMarker;
 }
+/**
+ * Get the root id of a vertex, i.e., the id of the AST node it corresponds to.
+ */
 function getVertexRootId(vertex) {
     return isMarkerVertex(vertex) ? vertex.root : vertex.id;
 }
@@ -68,7 +81,6 @@ class ControlFlowGraph {
     _mayHaveBasicBlocks = false;
     /**
      * Add a new vertex to the control flow graph.
-     *
      * @see {@link ControlFlowGraph#addEdge|addEdge()} - to add an edge
      */
     addVertex(vertex, rootVertex = true) {
@@ -90,7 +102,6 @@ class ControlFlowGraph {
     }
     /**
      * Add a new edge to the control flow graph.
-     *
      * @see {@link ControlFlowGraph#addVertex|addVertex()} - to add vertices
      * @see {@link ControlFlowGraph#addEdges|addEdges()} - to add multiple edges at once
      */
@@ -190,7 +201,6 @@ class ControlFlowGraph {
     /**
      * This removes the vertex and all edges to and from it.
      * @param id - the id of the vertex to remove
-     *
      * @see {@link ControlFlowGraph#addVertex|addVertex()} - to add a vertex
      * @see {@link ControlFlowGraph#removeEdge|removeEdge()} - to remove a specific edge
      */
@@ -212,7 +222,6 @@ class ControlFlowGraph {
     }
     /**
      * Removes a all direct edges between `from` and `to` from the control flow graph.
-     *
      * @see {@link ControlFlowGraph#addEdge|addEdge()} - to add an edge
      * @see {@link ControlFlowGraph#removeVertex|removeVertex()} - to remove a vertex and all its edges
      */
@@ -281,6 +290,9 @@ class ControlFlowGraph {
     }
 }
 exports.ControlFlowGraph = ControlFlowGraph;
+/**
+ * Create an empty control flow information object.
+ */
 function emptyControlFlowInformation() {
     return {
         returns: [],

package/control-flow/dfg-cfg-guided-visitor.d.ts

@@ -1,8 +1,7 @@
 import { type CfgBasicBlockVertex, type CfgEndMarkerVertex, type CfgExpressionVertex, type CfgSimpleVertex, type CfgStatementVertex, type ControlFlowInformation } from './control-flow-graph';
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
-import type { DataflowGraphVertexArgument, DataflowGraphVertexFunctionCall, DataflowGraphVertexFunctionDefinition, DataflowGraphVertexUse, DataflowGraphVertexValue, DataflowGraphVertexVariableDefinition } from '../dataflow/graph/vertex';
-import type { BasicCfgGuidedVisitorConfiguration } from './basic-cfg-guided-visitor';
-import { BasicCfgGuidedVisitor } from './basic-cfg-guided-visitor';
+import { type DataflowGraphVertexArgument, type DataflowGraphVertexFunctionCall, type DataflowGraphVertexFunctionDefinition, type DataflowGraphVertexUse, type DataflowGraphVertexValue, type DataflowGraphVertexVariableDefinition } from '../dataflow/graph/vertex';
+import { type BasicCfgGuidedVisitorConfiguration, BasicCfgGuidedVisitor } from './basic-cfg-guided-visitor';
 import type { DataflowGraph } from '../dataflow/graph/graph';
 export interface DataflowCfgGuidedVisitorConfiguration<ControlFlow extends ControlFlowInformation = ControlFlowInformation, Dfg extends DataflowGraph = DataflowGraph> extends BasicCfgGuidedVisitorConfiguration<ControlFlow> {
     readonly dfg: Dfg;

package/control-flow/diff-cfg.d.ts

@@ -1,11 +1,9 @@
-import type { NamedGraph } from '../util/diff-graph';
-import { GraphDifferenceReport } from '../util/diff-graph';
-import type { GenericDiffConfiguration } from '../util/diff';
-import type { ControlFlowGraph } from './control-flow-graph';
+import { type NamedGraph, GraphDifferenceReport } from '../util/diff-graph';
+import { type GenericDiffConfiguration } from '../util/diff';
+import { type ControlFlowGraph } from './control-flow-graph';
 /**
  * Compare two control flow 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 diffOfDataflowGraphs} - for dataflow graphs
  */
 export declare function diffOfControlFlowGraphs(left: NamedGraph<ControlFlowGraph>, right: NamedGraph<ControlFlowGraph>, config?: Partial<GenericDiffConfiguration>): GraphDifferenceReport;

package/control-flow/diff-cfg.js

@@ -9,7 +9,6 @@ const arrays_1 = require("../util/collections/arrays");
 /**
  * Compare two control flow 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 diffOfDataflowGraphs} - for dataflow graphs
  */
 function diffOfControlFlowGraphs(left, right, config) {

package/control-flow/extract-cfg.d.ts

@@ -1,19 +1,17 @@
-import type { QuadSerializationConfiguration } from '../util/quads';
+import { type QuadSerializationConfiguration } from '../util/quads';
 import type { NormalizedAst, ParentInformation } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { DataflowGraph } from '../dataflow/graph/graph';
-import type { ControlFlowInformation } from './control-flow-graph';
-import type { CfgSimplificationPassName } from './cfg-simplification';
+import { type ControlFlowInformation } from './control-flow-graph';
+import { type CfgSimplificationPassName } from './cfg-simplification';
 import type { FlowrConfigOptions } from '../config';
 /**
  * Given a normalized AST, this approximates the control flow graph of the program.
  * This view is different from the computation of the dataflow graph and may differ,
  * especially because it focuses on intra-procedural analysis.
- *
  * @param ast             - the normalized AST
  * @param config          - the flowR config
  * @param graph           - additional dataflow facts to consider by the control flow extraction
  * @param simplifications - a list of simplification passes to apply to the control flow graph
- *
  * @see {@link extractCfgQuick} - for a simplified version of this function
  */
 export declare function extractCfg<Info = ParentInformation>(ast: NormalizedAst<Info & ParentInformation>, config: FlowrConfigOptions, graph?: DataflowGraph, simplifications?: readonly CfgSimplificationPassName[]): ControlFlowInformation;
@@ -24,7 +22,6 @@ export declare function extractCfgQuick<Info = ParentInformation>(ast: Normalize
 export declare const ResolvedCallSuffix = "-resolved-call-exit";
 /**
  * Convert a cfg to RDF quads.
- *
  * @see {@link df2quads}
  * @see {@link serialize2quads}
  * @see {@link graph2quads}

package/control-flow/extract-cfg.js

@@ -55,12 +55,10 @@ function dataflowCfgFolds(dataflowGraph) {
  * Given a normalized AST, this approximates the control flow graph of the program.
  * This view is different from the computation of the dataflow graph and may differ,
  * especially because it focuses on intra-procedural analysis.
- *
  * @param ast             - the normalized AST
  * @param config          - the flowR config
  * @param graph           - additional dataflow facts to consider by the control flow extraction
  * @param simplifications - a list of simplification passes to apply to the control flow graph
- *
  * @see {@link extractCfgQuick} - for a simplified version of this function
  */
 function extractCfg(ast, config, graph, simplifications) {
@@ -439,7 +437,6 @@ function cfgExprList(node, _grouping, expressions) {
 }
 /**
  * Convert a cfg to RDF quads.
- *
  * @see {@link df2quads}
  * @see {@link serialize2quads}
  * @see {@link graph2quads}

package/control-flow/happens-before.d.ts

@@ -1,6 +1,6 @@
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
 import { Ternary } from '../util/logic';
-import type { ControlFlowGraph } from './control-flow-graph';
+import { type ControlFlowGraph } from './control-flow-graph';
 /**
  * Determines if node `a` happens before node `b` in the control flow graph.
  */