@eagleoutice/flowr 2.2.16 → 2.3.0

package/abstract-interpretation/data-frame/mappers/arguments.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeRegExp = escapeRegExp;
+exports.filterValidNames = filterValidNames;
+exports.getArgumentValue = getArgumentValue;
+exports.getEffectiveArgs = getEffectiveArgs;
+exports.getFunctionArgument = getFunctionArgument;
+exports.getFunctionArguments = getFunctionArguments;
+exports.getUnresolvedSymbolsInExpression = getUnresolvedSymbolsInExpression;
+exports.hasCriticalArgument = hasCriticalArgument;
+exports.isDataFrameArgument = isDataFrameArgument;
+exports.isNamedArgument = isNamedArgument;
+exports.isRNull = isRNull;
+exports.isValidColName = isValidColName;
+const vertex_1 = require("../../../dataflow/graph/vertex");
+const make_argument_1 = require("../../../dataflow/internal/process/functions/call/argument/make-argument");
+const r_function_call_1 = require("../../../r-bridge/lang-4.x/ast/model/nodes/r-function-call");
+const type_1 = require("../../../r-bridge/lang-4.x/ast/model/type");
+const convert_values_1 = require("../../../r-bridge/lang-4.x/convert-values");
+const shape_inference_1 = require("../shape-inference");
+const resolve_args_1 = require("../resolve-args");
+const visitor_1 = require("../../../r-bridge/lang-4.x/ast/model/processing/visitor");
+/** Regular expression representing valid columns names, e.g. for `data.frame` */
+const ColNamesRegex = /^[A-Za-z.][A-Za-z0-9_.]*$/;
+/**
+ * Escapes a regular expression given as string by escaping all special regular expression characters.
+ *
+ * @param text        - The text to escape
+ * @param allowTokens - Whether to allow and keep unescaped tokens like `\s`, `\t`, or `\n`
+ * @returns The escaped text
+ */
+function escapeRegExp(text, allowTokens = false) {
+    if (allowTokens) { // only allow and keep the tokens `\s`, `\t`, and `\n` in the text
+        return text.replace(/[.*+?^${}()|[\]]|\\[^stn]/g, '\\$&');
+    }
+    else {
+        return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+}
+/**
+ * Maps all invalid, duplicate, or empty column names to top depending on the provided arguments.
+ *
+ * @param colnames     - The columns names to filter
+ * @param checkNames   - Whether to map all invalid column names to top (`undefined`)
+ * @param noDupNames   - Whether to map all duplicate column names to top (`undefined`)
+ * @param noEmptyNames - Whether to map all empty column names to top (`undefined`)
+ * @returns The filtered column names
+ */
+function filterValidNames(colnames, checkNames, noDupNames, noEmptyNames) {
+    if (checkNames) { // map all invalid column names to top
+        colnames = colnames?.map(entry => isValidColName(entry) ? entry : undefined);
+    }
+    if (noDupNames) { // map all duplicate column names to top
+        colnames = colnames?.map((entry, _, list) => entry !== undefined && list.filter(other => other === entry).length === 1 ? entry : undefined);
+    }
+    if (noEmptyNames) { // map all empty column names to top
+        colnames = colnames?.map(entry => entry?.length === 0 ? undefined : entry);
+    }
+    return colnames;
+}
+/**
+ * Gets the value of an argument that specified as {@link FunctionParameterLocation}.
+ *
+ * @param args     - The arguments to get the requested argument from
+ * @param argument - The specification of the argument to get the value for
+ * @param info     - Argument resolve information
+ * @returns The resolved value of the argument or `undefined`
+ */
+function getArgumentValue(args, argument, info) {
+    const arg = getFunctionArgument(args, argument, info);
+    const defaultValue = typeof argument !== 'string' ? argument.default : undefined;
+    return arg !== undefined ? (0, resolve_args_1.resolveIdToArgValue)(arg, info) : defaultValue;
+}
+/**
+ * Gets all effective argument from a list of arguments by removing all arguments whose names should be excluded.
+ *
+ * @param args     - The list of arguments to filter
+ * @param excluded - The names of the arguments to exclude
+ * @returns The filtered list of arguments
+ */
+function getEffectiveArgs(args, excluded) {
+    return args.filter(arg => arg === r_function_call_1.EmptyArgument || arg.name === undefined || !excluded.includes((0, resolve_args_1.unquoteArgument)(arg.name.content)));
+}
+/**
+ * Gets an argument specified as {@link FunctionParameterLocation} from a list of arguments.
+ *
+ * @param args     - The arguments to get the requested argument from
+ * @param argument - The specification of the argument to get
+ * @param info     - Argument resolve information
+ * @returns An argument matching the specified `argument` or `undefined`
+ */
+function getFunctionArgument(args, argument, info) {
+    const pos = typeof argument !== 'string' ? argument.pos : -1;
+    const name = typeof argument !== 'string' ? argument.name : argument;
+    let arg = undefined;
+    if (name !== undefined) {
+        arg = args.find(arg => (0, resolve_args_1.resolveIdToArgName)(arg, info) === name);
+    }
+    const hasArgPos = arg === undefined && pos >= 0 && pos < args.length && args[pos] !== r_function_call_1.EmptyArgument && args[pos].name === undefined;
+    if (hasArgPos) {
+        arg = args[pos];
+    }
+    return arg;
+}
+/**
+ * Get all function arguments of a function call node in the data flow graph.
+ *
+ * @param node - The function call node to get the arguments for
+ * @param dfg  - The data flow graph for retrieving the arguments
+ * @returns The arguments of the function call in the data flow graph
+ */
+function getFunctionArguments(node, dfg) {
+    const vertex = dfg.getVertex(node.info.id);
+    if (vertex?.tag === vertex_1.VertexType.FunctionCall && dfg.idMap !== undefined) {
+        const idMap = dfg.idMap;
+        return vertex.args
+            .map(arg => arg === r_function_call_1.EmptyArgument ? arg : idMap.get(arg.nodeId))
+            .map(arg => arg === r_function_call_1.EmptyArgument || arg?.type === type_1.RType.Argument ? arg : (0, make_argument_1.toUnnamedArgument)(arg, idMap));
+    }
+    return node.arguments;
+}
+/**
+ * Gets all nested symbols in an expression that have no outgoing edges in the data flow graph.
+ * @param expression - The expression to get the symbols from
+ * @param dfg        - The data flow graph for checking the outgoing edges
+ * @returns The name of all unresolved symbols in the expression
+ */
+function getUnresolvedSymbolsInExpression(expression, dfg) {
+    if (expression === undefined || expression === r_function_call_1.EmptyArgument || dfg === undefined) {
+        return [];
+    }
+    const unresolvedSymbols = [];
+    (0, visitor_1.visitAst)(expression, node => {
+        if (node.type === type_1.RType.Symbol) {
+            const vertex = dfg.get(node.info.id);
+            if ((0, vertex_1.isUseVertex)(vertex?.[0]) && vertex[1].size === 0) {
+                unresolvedSymbols.push((0, resolve_args_1.unquoteArgument)(node.content));
+            }
+        }
+    });
+    return unresolvedSymbols;
+}
+/**
+ * Checks whether a list of arguments contains any critical argument.
+ *
+ * @param args     - The list of arguments to check
+ * @param critical - The critical arguments to search for (as string or {@link FunctionParameterLocation}s)
+ * @param info     - Argument resolve information
+ * @returns Whether the arguments contain any critical argument
+ */
+function hasCriticalArgument(args, critical, info) {
+    for (const param of critical ?? []) {
+        const arg = getFunctionArgument(args, param, info);
+        if (arg === undefined) {
+            continue;
+        }
+        else if (typeof param !== 'string' && param.default !== undefined) {
+            const value = (0, resolve_args_1.resolveIdToArgValue)(arg, info);
+            if (value !== undefined && value === param.default) {
+                continue;
+            }
+        }
+        return true;
+    }
+    return false;
+}
+function isDataFrameArgument(arg, info) {
+    return arg !== r_function_call_1.EmptyArgument && (0, shape_inference_1.resolveIdToDataFrameShape)(arg, info.graph) !== undefined;
+}
+/**
+ * Checks whether a function argument is a names argument.
+ */
+function isNamedArgument(arg) {
+    return arg !== r_function_call_1.EmptyArgument && arg?.name !== undefined;
+}
+function isRNull(node) {
+    if (node === r_function_call_1.EmptyArgument || node?.type === type_1.RType.Argument) {
+        return node !== r_function_call_1.EmptyArgument && isRNull(node.value);
+    }
+    return node?.type === type_1.RType.Symbol && node.content === convert_values_1.RNull;
+}
+/**
+ * Checks whether a string is a valid columns name according to the flag `check.names` in R.
+ */
+function isValidColName(colname) {
+    return colname !== undefined && ColNamesRegex.test(colname);
+}
+//# sourceMappingURL=arguments.js.map

package/abstract-interpretation/data-frame/mappers/assignment-mapper.d.ts

@@ -0,0 +1,20 @@
+import type { DataflowGraph } from '../../../dataflow/graph/graph';
+import type { RNode } from '../../../r-bridge/lang-4.x/ast/model/model';
+import type { RString } from '../../../r-bridge/lang-4.x/ast/model/nodes/r-string';
+import type { RSymbol } from '../../../r-bridge/lang-4.x/ast/model/nodes/r-symbol';
+import type { ParentInformation } from '../../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { DataFrameAssignmentInfo } from '../absint-info';
+/**
+ * Maps a concrete data frame assignment to data frame assignment info containing the ids of the identifier and assigned expression.
+ * We currently do not support function assignments dealing with data frames.
+ *
+ * @param identifier - The R node of the variable identifier
+ * @param expression - The R node of the assigned expression
+ * @param dfg  - The data flow graph for resolving the arguments
+ * @returns Data frame assignment info containing the IDs of the identifier and expression, or `undefined` if the node does not represent a data frame assignment
+ */
+export declare function mapDataFrameVariableAssignment(identifier: RSymbol<ParentInformation> | RString<ParentInformation>, expression: RNode<ParentInformation>, dfg: DataflowGraph): DataFrameAssignmentInfo | undefined;
+/**
+ * Checks whether a R node represents an assignment target, i.e. is a `RSymbol` or `RString`.
+ */
+export declare function isAssignmentTarget(node: RNode<ParentInformation> | undefined): node is RSymbol<ParentInformation> | RString<ParentInformation>;

package/abstract-interpretation/data-frame/mappers/assignment-mapper.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapDataFrameVariableAssignment = mapDataFrameVariableAssignment;
+exports.isAssignmentTarget = isAssignmentTarget;
+const config_1 = require("../../../config");
+const type_1 = require("../../../r-bridge/lang-4.x/ast/model/type");
+const arguments_1 = require("./arguments");
+/**
+ * Maps a concrete data frame assignment to data frame assignment info containing the ids of the identifier and assigned expression.
+ * We currently do not support function assignments dealing with data frames.
+ *
+ * @param identifier - The R node of the variable identifier
+ * @param expression - The R node of the assigned expression
+ * @param dfg  - The data flow graph for resolving the arguments
+ * @returns Data frame assignment info containing the IDs of the identifier and expression, or `undefined` if the node does not represent a data frame assignment
+ */
+function mapDataFrameVariableAssignment(identifier, expression, dfg) {
+    const resolveInfo = { graph: dfg, idMap: dfg.idMap, full: true, resolve: config_1.VariableResolve.Alias };
+    if (!(0, arguments_1.isDataFrameArgument)(expression, resolveInfo)) {
+        return;
+    }
+    return {
+        type: 'assignment',
+        identifier: identifier.info.id,
+        expression: expression.info.id
+    };
+}
+/**
+ * Checks whether a R node represents an assignment target, i.e. is a `RSymbol` or `RString`.
+ */
+function isAssignmentTarget(node) {
+    return node?.type === type_1.RType.Symbol || node?.type === type_1.RType.String;
+}
+//# sourceMappingURL=assignment-mapper.js.map

package/abstract-interpretation/data-frame/mappers/function-mapper.d.ts

@@ -0,0 +1,261 @@
+import type { FlowrConfigOptions } from '../../../config';
+import { type ResolveInfo } from '../../../dataflow/eval/resolve/alias-tracking';
+import type { DataflowGraph } from '../../../dataflow/graph/graph';
+import type { RNode } from '../../../r-bridge/lang-4.x/ast/model/model';
+import type { RFunctionArgument } from '../../../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
+import type { ParentInformation } from '../../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { DataFrameExpressionInfo, DataFrameOperation } from '../absint-info';
+import type { FunctionParameterLocation } from './arguments';
+/**
+ * Represents the different types of data frames in R
+ */
+declare enum DataFrameType {
+    DataFrame = "data.frame",
+    Tibble = "tibble",
+    DataTable = "data.table"
+}
+/**
+ * Mapper for mapping the supported concrete data frame functions to mapper functions,
+ * including information about the origin library of the functions and the type of the returned data frame.
+ */
+declare const DataFrameFunctionMapper: {
+    readonly 'data.frame': {
+        readonly mapper: typeof mapDataFrameCreate;
+        readonly library: "base";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly 'as.data.frame': {
+        readonly mapper: typeof mapDataFrameConvert;
+        readonly library: "base";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly 'read.table': {
+        readonly mapper: typeof mapDataFrameRead;
+        readonly library: "utils";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly 'read.csv': {
+        readonly mapper: typeof mapDataFrameRead;
+        readonly library: "utils";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly 'read.csv2': {
+        readonly mapper: typeof mapDataFrameRead;
+        readonly library: "utils";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly 'read.delim': {
+        readonly mapper: typeof mapDataFrameRead;
+        readonly library: "utils";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly 'read.delim2': {
+        readonly mapper: typeof mapDataFrameRead;
+        readonly library: "utils";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly read_table: {
+        readonly mapper: typeof mapDataFrameRead;
+        readonly library: "readr";
+        readonly returnType: DataFrameType.Tibble;
+    };
+    readonly read_csv: {
+        readonly mapper: typeof mapDataFrameRead;
+        readonly library: "readr";
+        readonly returnType: DataFrameType.Tibble;
+    };
+    readonly read_csv2: {
+        readonly mapper: typeof mapDataFrameRead;
+        readonly library: "readr";
+        readonly returnType: DataFrameType.Tibble;
+    };
+    readonly read_tsv: {
+        readonly mapper: typeof mapDataFrameRead;
+        readonly library: "readr";
+        readonly returnType: DataFrameType.Tibble;
+    };
+    readonly read_delim: {
+        readonly mapper: typeof mapDataFrameRead;
+        readonly library: "readr";
+        readonly returnType: DataFrameType.Tibble;
+    };
+    readonly cbind: {
+        readonly mapper: typeof mapDataFrameColBind;
+        readonly library: "base";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly rbind: {
+        readonly mapper: typeof mapDataFrameRowBind;
+        readonly library: "base";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly head: {
+        readonly mapper: typeof mapDataFrameHeadTail;
+        readonly library: "utils";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly tail: {
+        readonly mapper: typeof mapDataFrameHeadTail;
+        readonly library: "utils";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly subset: {
+        readonly mapper: typeof mapDataFrameSubset;
+        readonly library: "base";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly filter: {
+        readonly mapper: typeof mapDataFrameFilter;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly select: {
+        readonly mapper: typeof mapDataFrameSelect;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly mutate: {
+        readonly mapper: typeof mapDataFrameMutate;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly transform: {
+        readonly mapper: typeof mapDataFrameMutate;
+        readonly library: "base";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly group_by: {
+        readonly mapper: typeof mapDataFrameGroupBy;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.Tibble;
+    };
+    readonly summarise: {
+        readonly mapper: typeof mapDataFrameSummarize;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly summarize: {
+        readonly mapper: typeof mapDataFrameSummarize;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly inner_join: {
+        readonly mapper: typeof mapDataFrameJoin;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly left_join: {
+        readonly mapper: typeof mapDataFrameJoin;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly right_join: {
+        readonly mapper: typeof mapDataFrameJoin;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly full_join: {
+        readonly mapper: typeof mapDataFrameJoin;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly merge: {
+        readonly mapper: typeof mapDataFrameJoin;
+        readonly library: "base";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly relocate: {
+        readonly mapper: typeof mapDataFrameIdentity;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+    readonly arrange: {
+        readonly mapper: typeof mapDataFrameIdentity;
+        readonly library: "dplyr";
+        readonly returnType: DataFrameType.DataFrame;
+    };
+};
+/** All currently supported data frame functions */
+type DataFrameFunction = keyof typeof DataFrameFunctionMapper;
+/**
+ * Maps a concrete data frame function call to abstract data frame operations.
+ *
+ * @param node   - The R node of the function call
+ * @param dfg    - The data flow graph for resolving the arguments
+ * @param config - The flowR configuration to use
+ * @returns Data frame expression info containing the mapped abstract data frame operations, or `undefined` if the node does not represent a data frame function call
+ */
+export declare function mapDataFrameFunctionCall<Name extends DataFrameFunction>(node: RNode<ParentInformation>, dfg: DataflowGraph, config: FlowrConfigOptions): DataFrameExpressionInfo | undefined;
+declare function mapDataFrameCreate(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    checkNames: FunctionParameterLocation<boolean>;
+    noDupNames: FunctionParameterLocation<boolean>;
+    special: string[];
+}, info: ResolveInfo): DataFrameOperation[];
+declare function mapDataFrameConvert(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    dataFrame: FunctionParameterLocation;
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+declare function mapDataFrameRead(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    fileName: FunctionParameterLocation;
+    text?: FunctionParameterLocation;
+    header: FunctionParameterLocation<boolean>;
+    separator: FunctionParameterLocation<string>;
+    quote: FunctionParameterLocation<string>;
+    comment: FunctionParameterLocation<string>;
+    skipLines: FunctionParameterLocation<number>;
+    checkNames: FunctionParameterLocation<boolean>;
+    noDupNames: FunctionParameterLocation<boolean>;
+    noEmptyNames?: boolean;
+}, info: ResolveInfo, config: FlowrConfigOptions): DataFrameOperation[];
+declare function mapDataFrameColBind(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    special: string[];
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+declare function mapDataFrameRowBind(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    special: string[];
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+declare function mapDataFrameHeadTail(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    dataFrame: FunctionParameterLocation;
+    amount: FunctionParameterLocation<number>;
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+declare function mapDataFrameSubset(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    dataFrame: FunctionParameterLocation;
+    subset: FunctionParameterLocation;
+    select: FunctionParameterLocation;
+    drop: FunctionParameterLocation<boolean>;
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+declare function mapDataFrameFilter(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    dataFrame: FunctionParameterLocation;
+    special: string[];
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+declare function mapDataFrameSelect(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    dataFrame: FunctionParameterLocation;
+    special: string[];
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+declare function mapDataFrameMutate(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    dataFrame: FunctionParameterLocation;
+    special: string[];
+    checkNames?: boolean;
+    noDupNames?: boolean;
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+declare function mapDataFrameGroupBy(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    dataFrame: FunctionParameterLocation;
+    by: FunctionParameterLocation;
+    special: string[];
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+declare function mapDataFrameSummarize(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    dataFrame: FunctionParameterLocation;
+    special: string[];
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+declare function mapDataFrameJoin(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    dataFrame: FunctionParameterLocation;
+    otherDataFrame: FunctionParameterLocation;
+    by: FunctionParameterLocation;
+    joinAll: FunctionParameterLocation<boolean>;
+    joinLeft: FunctionParameterLocation<boolean>;
+    joinRight: FunctionParameterLocation<boolean>;
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+declare function mapDataFrameIdentity(args: readonly RFunctionArgument<ParentInformation>[], params: {
+    dataFrame: FunctionParameterLocation;
+    special: string[];
+    disallowNamedArgs?: boolean;
+}, info: ResolveInfo): DataFrameOperation[] | undefined;
+export {};