@eagleoutice/flowr 2.1.8 → 2.1.10

package/README.md

@@ -47,6 +47,9 @@ We welcome every contribution! Please check out the [contributing guidelines](ht
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Core5563"><img src="https://avatars.githubusercontent.com/u/140061253?v=4?s=100" width="100px;" alt="Core5563"/><br /><sub><b>Core5563</b></sub></a><br /><a href="https://github.com/flowr-analysis/flowr/commits?author=Core5563" title="Code">💻</a> <a href="https://github.com/flowr-analysis/flowr/commits?author=Core5563" title="Tests">⚠️</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Ehcsan"><img src="https://avatars.githubusercontent.com/u/68707578?v=4?s=100" width="100px;" alt="Ehcsan"/><br /><sub><b>Ehcsan</b></sub></a><br /><a href="https://github.com/flowr-analysis/flowr/commits?author=Ehcsan" title="Code">💻</a> <a href="https://github.com/flowr-analysis/flowr/commits?author=Ehcsan" title="Tests">⚠️</a></td>
     </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Slartibartfass2"><img src="https://avatars.githubusercontent.com/u/40503329?v=4?s=100" width="100px;" alt="Felix Schlegel"/><br /><sub><b>Felix Schlegel</b></sub></a><br /><a href="https://github.com/flowr-analysis/flowr/commits?author=Slartibartfass2" title="Code">💻</a> <a href="https://github.com/flowr-analysis/flowr/commits?author=Slartibartfass2" title="Tests">⚠️</a></td>
+    </tr>
   </tbody>
   <tfoot>
     <tr>

package/benchmark/summarizer/first-phase/process.js

@@ -42,6 +42,7 @@ const shell_1 = require("../../../r-bridge/shell");
 const retriever_1 = require("../../../r-bridge/retriever");
 const visitor_1 = require("../../../r-bridge/lang-4.x/ast/model/processing/visitor");
 const type_1 = require("../../../r-bridge/lang-4.x/ast/model/type");
+const arrays_1 = require("../../../util/arrays");
 const tempfile = (() => {
     let _tempfile = undefined;
     return () => {
@@ -244,15 +245,15 @@ async function summarizeSlicerStats(stats, report = () => {
 }
 function summarizeSummarizedMeasurement(data) {
     data = data.filter(assert_1.isNotUndefined);
-    const min = data.map(d => d.min).filter(assert_1.isNotUndefined).reduce((a, b) => Math.min(a, b), Infinity);
-    const max = data.map(d => d.max).filter(assert_1.isNotUndefined).reduce((a, b) => Math.max(a, b), -Infinity);
+    const min = Math.min(...data.map(d => d.min).filter(assert_1.isNotUndefined));
+    const max = Math.max(...data.map(d => d.max).filter(assert_1.isNotUndefined));
     // calculate median of medians (don't just average the median!)
     const medians = data.map(d => d.median).filter(assert_1.isNotUndefined).sort((a, b) => a - b);
     const median = medians[Math.floor(medians.length / 2)];
-    const mean = data.map(d => d.mean).filter(assert_1.isNotUndefined).reduce((a, b) => a + b, 0) / data.length;
+    const mean = (0, arrays_1.arraySum)(data.map(d => d.mean).filter(assert_1.isNotUndefined)) / data.length;
     // Method 1 of https://www.statology.org/averaging-standard-deviations/
-    const std = Math.sqrt(data.map(d => d.std ** 2).filter(assert_1.isNotUndefined).reduce((a, b) => a + b, 0) / data.length);
-    const total = data.map(d => d.total).filter(assert_1.isNotUndefined).reduce((a, b) => a + b, 0);
+    const std = Math.sqrt((0, arrays_1.arraySum)(data.map(d => d.std ** 2).filter(assert_1.isNotUndefined)) / data.length);
+    const total = (0, arrays_1.arraySum)(data.map(d => d.total).filter(assert_1.isNotUndefined));
     return { min, max, median, mean, std, total };
 }
 function summarizeSummarizedReductions(reductions) {

package/cli/repl/commands/repl-dataflow.js

@@ -11,13 +11,16 @@ async function dataflow(shell, remainingLine) {
         request: (0, retriever_1.requestFromInput)(remainingLine.trim())
     }).allRemainingSteps();
 }
+function handleString(code) {
+    return code.startsWith('"') ? JSON.parse(code) : code;
+}
 exports.dataflowCommand = {
     description: `Get mermaid code for the dataflow graph of R code, start with '${retriever_1.fileProtocol}' to indicate a file`,
     usageExample: ':dataflow',
     aliases: ['d', 'df'],
     script: false,
     fn: async (output, shell, remainingLine) => {
-        const result = await dataflow(shell, remainingLine);
+        const result = await dataflow(shell, handleString(remainingLine));
         output.stdout((0, dfg_1.graphToMermaid)({ graph: result.dataflow.graph, includeEnvironments: false }).string);
     }
 };
@@ -27,7 +30,7 @@ exports.dataflowStarCommand = {
     aliases: ['d*', 'df*'],
     script: false,
     fn: async (output, shell, remainingLine) => {
-        const result = await dataflow(shell, remainingLine);
+        const result = await dataflow(shell, handleString(remainingLine));
         output.stdout((0, dfg_1.graphToMermaidUrl)(result.dataflow.graph, false));
     }
 };

package/cli/repl/commands/repl-normalize.js

@@ -11,13 +11,16 @@ async function normalize(shell, remainingLine) {
         request: (0, retriever_1.requestFromInput)(remainingLine.trim())
     }).allRemainingSteps();
 }
+function handleString(code) {
+    return code.startsWith('"') ? JSON.parse(code) : code;
+}
 exports.normalizeCommand = {
     description: `Get mermaid code for the normalized AST of R code, start with '${retriever_1.fileProtocol}' to indicate a file`,
     usageExample: ':normalize',
     aliases: ['n'],
     script: false,
     fn: async (output, shell, remainingLine) => {
-        const result = await normalize(shell, remainingLine);
+        const result = await normalize(shell, handleString(remainingLine));
         output.stdout((0, ast_1.normalizedAstToMermaid)(result.normalize.ast));
     }
 };
@@ -27,7 +30,7 @@ exports.normalizeStarCommand = {
     aliases: ['n*'],
     script: false,
     fn: async (output, shell, remainingLine) => {
-        const result = await normalize(shell, remainingLine);
+        const result = await normalize(shell, handleString(remainingLine));
         output.stdout((0, ast_1.normalizedAstToMermaidUrl)(result.normalize.ast));
     }
 };

package/cli/repl/commands/repl-query.js

@@ -19,7 +19,7 @@ async function getDataflow(shell, remainingLine) {
 function printHelp(output) {
     output.stderr(`Format: ${(0, ansi_1.italic)(':query "<query>" <code>', output.formatter)}`);
     output.stdout('The query is an array of query objects to represent multiple queries. Each query object may have the following properties:');
-    output.stdout((0, schema_1.describeSchema)(query_1.AnyQuerySchema, output.formatter));
+    output.stdout((0, schema_1.describeSchema)((0, query_1.AnyQuerySchema)(), output.formatter));
     output.stdout(`\n\nThe example ${(0, ansi_1.italic)(':query "[{\\"type\\": \\"call-context\\", \\"callName\\": \\"mean\\" }]" mean(1:10)', output.formatter)} would return the call context of the mean function.`);
     output.stdout('As a convenience, we interpret any (non-help) string not starting with \'[\' as a regex for the simple call-context query.');
     output.stdout(`Hence, ${(0, ansi_1.italic)(':query "mean" mean(1:10)', output.formatter)} is equivalent to the above example.`);
@@ -38,7 +38,7 @@ async function processQueryArgs(line, shell, output) {
     let parsedQuery = [];
     if (query.startsWith('[')) {
         parsedQuery = JSON.parse(query);
-        const validationResult = query_1.QueriesSchema.validate(parsedQuery);
+        const validationResult = (0, query_1.QueriesSchema)().validate(parsedQuery);
         if (validationResult.error) {
             output.stderr(`Invalid query: ${validationResult.error.message}`);
             printHelp(output);

package/cli/repl/server/messages/message-query.js

@@ -12,7 +12,7 @@ exports.requestQueryMessage = {
         type: joi_1.default.string().valid('request-query').required().description('The type of the message.'),
         id: joi_1.default.string().optional().description('If you give the id, the response will be sent to the client with the same id.'),
         filetoken: joi_1.default.string().required().description('The filetoken of the file/data retrieved from the analysis request.'),
-        query: query_1.QueriesSchema.required().description('The query to run on the file analysis information.')
+        query: (0, query_1.QueriesSchema)().required().description('The query to run on the file analysis information.')
     }).description('Request a query to be run on the file analysis information.')
 };
 exports.responseQueryMessage = {

package/config.d.ts

@@ -1,6 +1,14 @@
 import type { MergeableRecord } from './util/objects';
 import Joi from 'joi';
 import type { BuiltInDefinitions } from './dataflow/environments/built-in-config';
+export declare enum VariableResolve {
+    /** Don't resolve constants at all */
+    Disabled = "disabled",
+    /** Use alias tracking to resolve */
+    Alias = "alias",
+    /** Only resolve directly assigned builtin constants */
+    Builtin = "builtin"
+}
 export interface FlowrConfigOptions extends MergeableRecord {
     /**
      * Whether source calls should be ignored, causing {@link processSourceCall}'s behavior to be skipped
@@ -23,6 +31,19 @@ export interface FlowrConfigOptions extends MergeableRecord {
             };
         };
     };
+    /** How to resolve constants, constraints, cells, ... */
+    readonly solver: {
+        /**
+         * How to resolve variables and their values
+         */
+        readonly variables: VariableResolve;
+        /**
+         * Whether to track pointers in the dataflow graph,
+         * if not, the graph will be over-approximated wrt.
+         * containers and accesses
+         */
+        readonly pointerTracking: boolean;
+    };
 }
 export declare const defaultConfigOptions: FlowrConfigOptions;
 export declare const flowrConfigFileSchema: Joi.ObjectSchema<any>;

package/config.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.flowrConfigFileSchema = exports.defaultConfigOptions = void 0;
+exports.flowrConfigFileSchema = exports.defaultConfigOptions = exports.VariableResolve = void 0;
 exports.setConfigFile = setConfigFile;
 exports.parseConfig = parseConfig;
 exports.setConfig = setConfig;
@@ -14,6 +14,15 @@ const fs_1 = __importDefault(require("fs"));
 const log_1 = require("./util/log");
 const files_1 = require("./util/files");
 const joi_1 = __importDefault(require("joi"));
+var VariableResolve;
+(function (VariableResolve) {
+    /** Don't resolve constants at all */
+    VariableResolve["Disabled"] = "disabled";
+    /** Use alias tracking to resolve */
+    VariableResolve["Alias"] = "alias";
+    /** Only resolve directly assigned builtin constants */
+    VariableResolve["Builtin"] = "builtin";
+})(VariableResolve || (exports.VariableResolve = VariableResolve = {}));
 exports.defaultConfigOptions = {
     ignoreSourceCalls: false,
     rPath: undefined,
@@ -24,6 +33,10 @@ exports.defaultConfigOptions = {
                 definitions: []
             }
         }
+    },
+    solver: {
+        variables: VariableResolve.Alias,
+        pointerTracking: true
     }
 };
 exports.flowrConfigFileSchema = joi_1.default.object({
@@ -36,7 +49,11 @@ exports.flowrConfigFileSchema = joi_1.default.object({
                 definitions: joi_1.default.array().items(joi_1.default.object()).optional().description('The definitions to load/overwrite.')
             }).optional().description('Do you want to overwrite (parts) of the builtin definition?')
         }).optional().description('Semantics regarding the handlings of the environment.')
-    }).description('Configure language semantics and how flowR handles them.')
+    }).description('Configure language semantics and how flowR handles them.'),
+    solver: joi_1.default.object({
+        variables: joi_1.default.string().valid(...Object.values(VariableResolve)).description('How to resolve variables and their values.'),
+        pointerTracking: joi_1.default.boolean().description('Whether to track pointers in the dataflow graph, if not, the graph will be over-approximated wrt. containers and accesses.')
+    }).description('How to resolve constants, constraints, cells, ...')
 }).description('The configuration file format for flowR.');
 // we don't load from a config file at all by default unless setConfigFile is called
 let configFile = undefined;

package/dataflow/environments/built-in.d.ts

@@ -24,6 +24,7 @@ import { processSourceCall } from '../internal/process/functions/call/built-in/b
 import type { ForceArguments } from '../internal/process/functions/call/common';
 import { processApply } from '../internal/process/functions/call/built-in/built-in-apply';
 import type { LinkTo } from '../../queries/catalog/call-context-query/call-context-query-format';
+import { processList } from '../internal/process/functions/call/built-in/built-in-list';
 export declare const BuiltIn = "built-in";
 export type BuiltInIdentifierProcessor = <OtherInfo>(name: RSymbol<OtherInfo & ParentInformation>, args: readonly RFunctionArgument<OtherInfo & ParentInformation>[], rootId: NodeId, data: DataflowProcessorInformation<OtherInfo & ParentInformation>) => DataflowInformation;
 export type BuiltInIdentifierProcessorWithConfig<Config> = <OtherInfo>(name: RSymbol<OtherInfo & ParentInformation>, args: readonly RFunctionArgument<OtherInfo & ParentInformation>[], rootId: NodeId, data: DataflowProcessorInformation<OtherInfo & ParentInformation>, config: Config) => DataflowInformation;
@@ -63,6 +64,7 @@ export declare const BuiltInProcessorMapper: {
     readonly 'builtin:repeat-loop': typeof processRepeatLoop;
     readonly 'builtin:while-loop': typeof processWhileLoop;
     readonly 'builtin:replacement': typeof processReplacementFunction;
+    readonly 'builtin:list': typeof processList;
 };
 export type BuiltInMappingName = keyof typeof BuiltInProcessorMapper;
 export type ConfigOfBuiltInMappingName<N extends BuiltInMappingName> = Parameters<typeof BuiltInProcessorMapper[N]>[4];

package/dataflow/environments/built-in.js

@@ -24,6 +24,7 @@ const built_in_source_1 = require("../internal/process/functions/call/built-in/b
 const built_in_apply_1 = require("../internal/process/functions/call/built-in/built-in-apply");
 const built_in_config_1 = require("./built-in-config");
 const default_builtin_config_1 = require("./default-builtin-config");
+const built_in_list_1 = require("../internal/process/functions/call/built-in/built-in-list");
 exports.BuiltIn = 'built-in';
 function defaultBuiltInProcessor(name, args, rootId, data, config) {
     const { information: res, processedArguments } = (0, known_call_handling_1.processKnownFunctionCall)({ name, args, rootId, data, forceArgs: config.forceArgs });
@@ -88,6 +89,7 @@ exports.BuiltInProcessorMapper = {
     'builtin:repeat-loop': built_in_repeat_loop_1.processRepeatLoop,
     'builtin:while-loop': built_in_while_loop_1.processWhileLoop,
     'builtin:replacement': built_in_replacement_1.processReplacementFunction,
+    'builtin:list': built_in_list_1.processList,
 };
 exports.BuiltInMemory = new Map();
 exports.EmptyBuiltInMemory = new Map();

package/dataflow/environments/default-builtin-config.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultBuiltinConfig = void 0;
+const identify_link_to_last_call_relation_1 = require("../../queries/catalog/call-context-query/identify-link-to-last-call-relation");
+const type_1 = require("../../r-bridge/lang-4.x/ast/model/type");
+const cascade_action_1 = require("../../queries/catalog/call-context-query/cascade-action");
 /**
  * Contains the built-in definitions recognized by flowR
  */
@@ -11,7 +14,7 @@ exports.DefaultBuiltinConfig = [
     {
         type: 'function',
         names: [
-            '~', '+', '-', '*', '/', '^', '!', '?', '**', '==', '!=', '>', '<', '>=', '<=', '%%', '%/%', '%*%', '%in%', ':', 'list',
+            '~', '+', '-', '*', '/', '^', '!', '?', '**', '==', '!=', '>', '<', '>=', '<=', '%%', '%/%', '%*%', '%in%', ':',
             'rep', 'seq', 'seq_len', 'seq_along', 'seq.int', 'gsub', 'which', 'class', 'dimnames', 'min', 'max',
             'intersect', 'subset', 'match', 'sqrt', 'abs', 'round', 'floor', 'ceiling', 'signif', 'trunc', 'log', 'log10', 'log2', 'sum', 'mean',
             'unique', 'paste', 'paste0', 'read.csv', 'stop', 'is.null', 'numeric', 'as.character', 'as.integer', 'as.logical', 'as.numeric', 'as.matrix',
@@ -26,7 +29,7 @@ exports.DefaultBuiltinConfig = [
     {
         type: 'function',
         names: [
-            'c', 't'
+            'c', 't', 'aperm' /* vector construction, concatenation, transpose function, permutation generation */
         ],
         processor: 'builtin:default',
         config: { readAllArguments: true },
@@ -40,10 +43,45 @@ exports.DefaultBuiltinConfig = [
     { type: 'function', names: ['print', 'message', 'warning'], processor: 'builtin:default', config: { returnsNthArgument: 0, forceArgs: 'all', hasUnknownSideEffects: { type: 'link-to-last-call', callName: /^sink$/ } }, assumePrimitive: false },
     // graphics base
     { type: 'function', names: ['plot', 'plot.new', 'curve', 'map', 'image', 'boxplot', 'dotchart', 'sunflowerplot', 'barplot', 'matplot', 'hist', 'stem', 'density', 'smoothScatter', 'contour', 'persp'],
-        processor: 'builtin:default', config: { forceArgs: 'all', hasUnknownSideEffects: { type: 'link-to-last-call', callName: /^pdf|jpeg|png|windows|postscript|xfig|bitmap|pictex|cairo_pdf|svg|bmp|tiff|X11|quartz$/ } }, assumePrimitive: true },
+        processor: 'builtin:default',
+        config: {
+            forceArgs: 'all',
+            hasUnknownSideEffects: {
+                type: 'link-to-last-call',
+                ignoreIf: (source, graph) => {
+                    /* map with add = true appends to an existing plot */
+                    return (source.name === 'map' && (0, identify_link_to_last_call_relation_1.getValueOfArgument)(graph, source, {
+                        index: 11,
+                        name: 'add'
+                    }, [type_1.RType.Logical])?.content === true);
+                },
+                callName: /^(pdf|jpeg|png|windows|postscript|xfig|bitmap|pictex|cairo_pdf|svg|bmp|tiff|X11|quartz)$/
+            }
+        }, assumePrimitive: true },
     // graphics addons
-    { type: 'function', names: ['points', 'abline', 'mtext', 'lines', 'text', 'legend', 'title', 'axis', 'polygon', 'polypath', 'pie', 'rect', 'segments', 'arrows', 'symbols', 'tiplabels'],
-        processor: 'builtin:default', config: { forceArgs: 'all', hasUnknownSideEffects: { type: 'link-to-last-call', callName: /^dev\.new|dev\.copy|plot\.new|xspline|sunflowerplot|dotchart|plot|map|image|curve|boxplot|barplot|matplot|hist|stem|density|smoothScatter|contour|persp$/ } }, assumePrimitive: true },
+    { type: 'function', names: ['points', 'abline', 'map', 'mtext', 'lines', 'text', 'legend', 'title', 'axis', 'polygon', 'polypath', 'pie', 'rect', 'segments', 'arrows', 'symbols', 'tiplabels'],
+        processor: 'builtin:default', config: {
+            forceArgs: 'all',
+            hasUnknownSideEffects: {
+                type: 'link-to-last-call',
+                callName: /^(dev\.new|dev\.copy|plot\.new|xspline|sunflowerplot|dotchart|plot|map|image|curve|boxplot|barplot|matplot|hist|stem|density|smoothScatter|contour|persp)$/,
+                ignoreIf: (source, graph) => {
+                    const sourceVertex = graph.getVertex(source);
+                    /* map with add = true appends to an existing plot */
+                    return (sourceVertex?.name === 'map' && (0, identify_link_to_last_call_relation_1.getValueOfArgument)(graph, sourceVertex, {
+                        index: 11,
+                        name: 'add'
+                    }, [type_1.RType.Logical])?.content !== true);
+                },
+                cascadeIf: (target, _, graph) => {
+                    /* map with add = true appends to an existing plot */
+                    return target.name === 'map' ? ((0, identify_link_to_last_call_relation_1.getValueOfArgument)(graph, target, {
+                        index: 11,
+                        name: 'add'
+                    }, [type_1.RType.Logical])?.content === true ? cascade_action_1.CascadeAction.Continue : cascade_action_1.CascadeAction.Stop) : cascade_action_1.CascadeAction.Stop;
+                }
+            }
+        }, assumePrimitive: true },
     { type: 'function', names: ['('], processor: 'builtin:default', config: { returnsNthArgument: 0 }, assumePrimitive: true },
     { type: 'function', names: ['load', 'load_all', 'setwd', 'set.seed'], processor: 'builtin:default', config: { hasUnknownSideEffects: true, forceArgs: [true] }, assumePrimitive: false },
     { type: 'function', names: ['eval', 'body', 'formals', 'environment'], processor: 'builtin:default', config: { hasUnknownSideEffects: true, forceArgs: [true] }, assumePrimitive: false },
@@ -60,8 +98,9 @@ exports.DefaultBuiltinConfig = [
     { type: 'function', names: ['get'], processor: 'builtin:get', config: {}, assumePrimitive: false },
     { type: 'function', names: ['library', 'require'], processor: 'builtin:library', config: {}, assumePrimitive: false },
     { type: 'function', names: ['<-', '='], processor: 'builtin:assignment', config: { canBeReplacement: true }, assumePrimitive: true },
-    { type: 'function', names: [':=', 'assign'], processor: 'builtin:assignment', config: {}, assumePrimitive: true },
-    { type: 'function', names: ['delayedAssign'], processor: 'builtin:assignment', config: { quoteSource: true }, assumePrimitive: true },
+    { type: 'function', names: [':='], processor: 'builtin:assignment', config: {}, assumePrimitive: true },
+    { type: 'function', names: ['assign'], processor: 'builtin:assignment', config: { targetVariable: true }, assumePrimitive: true },
+    { type: 'function', names: ['delayedAssign'], processor: 'builtin:assignment', config: { quoteSource: true, targetVariable: true }, assumePrimitive: true },
     { type: 'function', names: ['<<-'], processor: 'builtin:assignment', config: { superAssignment: true, canBeReplacement: true }, assumePrimitive: true },
     { type: 'function', names: ['->'], processor: 'builtin:assignment', config: { swapSourceAndTarget: true, canBeReplacement: true }, assumePrimitive: true },
     { type: 'function', names: ['->>'], processor: 'builtin:assignment', config: { superAssignment: true, swapSourceAndTarget: true, canBeReplacement: true }, assumePrimitive: true },
@@ -74,6 +113,7 @@ exports.DefaultBuiltinConfig = [
     { type: 'function', names: ['repeat'], processor: 'builtin:repeat-loop', config: {}, assumePrimitive: true },
     { type: 'function', names: ['while'], processor: 'builtin:while-loop', config: {}, assumePrimitive: true },
     { type: 'function', names: ['do.call'], processor: 'builtin:apply', config: { indexOfFunction: 0, unquoteFunction: true }, assumePrimitive: true },
+    { type: 'function', names: ['list'], processor: 'builtin:list', config: {}, assumePrimitive: true },
     {
         type: 'function',
         names: [
@@ -83,7 +123,7 @@ exports.DefaultBuiltinConfig = [
             /* downloader and installer functions (R, devtools, BiocManager) */
             'library.dynam', 'install.packages', 'install', 'install_github', 'install_gitlab', 'install_bitbucket', 'install_url', 'install_git', 'install_svn', 'install_local', 'install_version', 'update_packages',
             /* weird env attachments */
-            'attach', 'unname'
+            'attach', 'unname', 'data'
         ],
         processor: 'builtin:default',
         config: { hasUnknownSideEffects: true },

package/dataflow/environments/define.js

@@ -4,8 +4,15 @@ exports.define = define;
 const assert_1 = require("../../util/assert");
 const environment_1 = require("./environment");
 const clone_1 = require("./clone");
+const vertex_1 = require("../graph/vertex");
 function defInEnv(newEnvironments, name, definition) {
     const existing = newEnvironments.memory.get(name);
+    // When there are defined indices, merge the definitions
+    const inGraphDefinition = definition;
+    if (existing !== undefined && inGraphDefinition.indicesCollection !== undefined && inGraphDefinition.controlDependencies === undefined) {
+        newEnvironments.memory.set(name, mergeDefinitions(existing, inGraphDefinition));
+        return;
+    }
     // check if it is maybe or not
     if (existing === undefined || definition.controlDependencies === undefined) {
         newEnvironments.memory.set(name, [definition]);
@@ -14,6 +21,77 @@ function defInEnv(newEnvironments, name, definition) {
         existing.push(definition);
     }
 }
+function mergeDefinitions(existing, definition) {
+    // When new definition is not a single index, e.g., a list redefinition, then reset existing definition
+    if (definition.indicesCollection?.some(indices => indices.isContainer)) {
+        return [definition];
+    }
+    const existingDefs = existing.map((def) => def).filter((def) => def !== undefined);
+    const overwriteIndices = definition.indicesCollection?.flatMap(indices => indices.indices) ?? [];
+    // Compare existing and new definitions,
+    // add new definitions and remove existing definitions that are overwritten by new definition
+    const newExistingDefs = [];
+    for (const overwriteIndex of overwriteIndices) {
+        for (const existingDef of existingDefs) {
+            if (existingDef.indicesCollection === undefined) {
+                continue;
+            }
+            const newIndicesCollection = overwriteContainerIndices(existingDef.indicesCollection, overwriteIndex);
+            // if indices are now empty list, don't keep empty definition
+            if (newIndicesCollection.length > 0) {
+                newExistingDefs.push({
+                    ...existingDef,
+                    indicesCollection: newIndicesCollection,
+                });
+            }
+        }
+    }
+    // store changed existing definitions and add new one
+    return [...newExistingDefs, definition];
+}
+function overwriteContainerIndices(existingIndices, overwriteIndex) {
+    const newIndicesCollection = [];
+    for (const indices of existingIndices) {
+        let newIndices;
+        // When overwrite index is container itself, then only overwrite sub-index
+        if ((0, vertex_1.isParentContainerIndex)(overwriteIndex)) {
+            newIndices = [];
+            for (const index of indices.indices) {
+                if (index.lexeme === overwriteIndex.lexeme && (0, vertex_1.isParentContainerIndex)(index)) {
+                    const overwriteSubIndices = overwriteIndex.subIndices.flatMap(a => a.indices);
+                    let newSubIndices = index.subIndices;
+                    for (const overwriteSubIndex of overwriteSubIndices) {
+                        newSubIndices = overwriteContainerIndices(newSubIndices, overwriteSubIndex);
+                    }
+                    if (newSubIndices.length > 0) {
+                        newIndices.push({
+                            ...index,
+                            subIndices: newSubIndices,
+                        });
+                    }
+                }
+                if (index.lexeme !== overwriteIndex.lexeme || !(0, vertex_1.isParentContainerIndex)(index)) {
+                    newIndices.push(index);
+                }
+            }
+        }
+        else if (indices.isContainer) {
+            // If indices are not a single, e.g., a list, take the whole definition
+            newIndices = indices.indices;
+        }
+        else {
+            // Filter existing indices with the same name
+            newIndices = indices.indices.filter(def => def.lexeme !== overwriteIndex.lexeme);
+        }
+        if (indices.isContainer || newIndices.length > 0) {
+            newIndicesCollection.push({
+                ...indices,
+                indices: newIndices,
+            });
+        }
+    }
+    return newIndicesCollection;
+}
 /**
  * Insert the given `definition` --- defined within the given scope --- into the passed along `environments` will take care of propagation.
  * Does not modify the passed along `environments` in-place! It returns the new reference.

package/dataflow/environments/environment.d.ts

@@ -7,19 +7,22 @@
 import type { Identifier, IdentifierDefinition, IdentifierReference } from './identifier';
 import type { DataflowGraph } from '../graph/graph';
 import type { ControlDependency } from '../info';
+/**
+ * Marks the reference as maybe (i.e., as controlled by a set of {@link IdentifierReference#controlDependencies|control dependencies}).
+ */
 export declare function makeReferenceMaybe(ref: IdentifierReference, graph: DataflowGraph, environments: REnvironmentInformation, includeDefs: boolean, defaultCd?: ControlDependency | undefined): IdentifierReference;
 export declare function makeAllMaybe(references: readonly IdentifierReference[] | undefined, graph: DataflowGraph, environments: REnvironmentInformation, includeDefs: boolean, defaultCd?: ControlDependency | undefined): IdentifierReference[];
 export type EnvironmentMemory = Map<Identifier, IdentifierDefinition[]>;
+/** A single entry/scope within an {@link REnvironmentInformation} */
 export interface IEnvironment {
-    /** unique and internally generated identifier -- will not be used for comparison but assists debugging for tracking identities */
+    /** Unique and internally generated identifier -- will not be used for comparison but helps with debugging for tracking identities */
     readonly id: number;
     /** Lexical parent of the environment, if any (can be manipulated by R code) */
     parent: IEnvironment;
-    /**
-   * Maps to exactly one definition of an identifier if the source is known, otherwise to a list of all possible definitions
-   */
+    /** Maps to exactly one definition of an identifier if the source is known, otherwise to a list of all possible definitions */
     memory: EnvironmentMemory;
 }
+/** @see REnvironmentInformation */
 export declare class Environment implements IEnvironment {
     readonly id: number;
     parent: IEnvironment;
@@ -27,11 +30,26 @@ export declare class Environment implements IEnvironment {
     constructor(parent: IEnvironment);
 }
 /**
- * First of all, yes, R stores its environments differently, potentially even with a different differentiation between
- * the `baseenv`, the `emptyenv`and other default environments. Yet, during dataflow we want sometimes to know more (static
- * reference information) and sometimes know less (to be honest we do not want that,
+ * An environment describes a ({@link IEnvironment#parent|scoped}) mapping of names to their definitions ({@link EnvironmentMemory}).
+ *
+ * First, yes, R stores its environments differently, potentially even with another differentiation between
+ * the `baseenv`, the `emptyenv`, and other default environments (see https://adv-r.hadley.nz/environments.html).
+ * Yet, during the dataflow analysis, we want sometimes to know more (static {@link IdentifierDefinition|reference information})
+ * and sometimes know less (to be honest, we do not want that,
  * but statically determining all attached environments is theoretically impossible --- consider attachments by user input).
- * One example would be maps holding a potential list of all definitions of a variable, if we do not know the execution path (like with `if(x) A else B`).
+ *
+ * One important environment is the {@link BuiltInEnvironment} which contains the default definitions for R's built-in functions and constants.
+ * Please use {@link initializeCleanEnvironments} to initialize the environments (which includes the built-ins).
+ * During serialization, you may want to rely on the {@link builtInEnvJsonReplacer} to avoid the huge built-in environment.
+ *
+ *
+ * @see {@link define} - to define a new {@link IdentifierDefinition|identifier definition} within an environment
+ * @see {@link resolveByName} - to resolve an {@link Identifier|identifier/name} to its {@link IdentifierDefinition|definitions} within an environment
+ * @see {@link makeReferenceMaybe} - to attach control dependencies to a reference
+ * @see {@link pushLocalEnvironment} - to create a new local scope
+ * @see {@link popLocalEnvironment} - to remove the current local scope
+ * @see {@link appendEnvironment} - to append an environment to the current one
+ * @see {@link overwriteEnvironment} - to overwrite the definitions in the current environment with those of another one
  */
 export interface REnvironmentInformation {
     /**  The currently active environment (the stack is represented by the currently active {@link IEnvironment#parent}). Environments are maintained within the dataflow graph. */
@@ -39,7 +57,27 @@ export interface REnvironmentInformation {
     /** nesting level of the environment, will be `0` for the global/root environment */
     readonly level: number;
 }
+/**
+ * The built-in {@link REnvironmentInformation|environment} is the root of all environments.
+ *
+ * For its default content (when not overwritten by a flowR config),
+ * see the {@link DefaultBuiltinConfig}.
+ */
 export declare const BuiltInEnvironment: Environment;
+/**
+ * The twin of the {@link BuiltInEnvironment} but with less built ins defined for
+ * cases in which we want some commonly overwritten variables to remain open.
+ * If you do not know if you need the empty environment, you do not need the empty environment (right now).
+ *
+ * @see {@link BuiltInEnvironment}
+ */
 export declare const EmptyBuiltInEnvironment: IEnvironment;
+/**
+ * Initialize a new {@link REnvironmentInformation|environment} with the built-ins.
+ * See {@link EmptyBuiltInEnvironment} for the case `fullBuiltIns = false`.
+ */
 export declare function initializeCleanEnvironments(fullBuiltIns?: boolean): REnvironmentInformation;
+/**
+ * Helps to serialize an environment, but replaces the built-in environment with a placeholder.
+ */
 export declare function builtInEnvJsonReplacer(k: unknown, v: unknown): unknown;

package/dataflow/environments/environment.js

@@ -9,6 +9,9 @@ const identifier_1 = require("./identifier");
 const built_in_1 = require("./built-in");
 const resolve_by_name_1 = require("./resolve-by-name");
 const json_1 = require("../../util/json");
+/**
+ * Marks the reference as maybe (i.e., as controlled by a set of {@link IdentifierReference#controlDependencies|control dependencies}).
+ */
 function makeReferenceMaybe(ref, graph, environments, includeDefs, defaultCd = undefined) {
     const node = graph.get(ref.nodeId, true);
     if (includeDefs) {
@@ -42,6 +45,7 @@ function makeAllMaybe(references, graph, environments, includeDefs, defaultCd =
     return references.map(ref => makeReferenceMaybe(ref, graph, environments, includeDefs, defaultCd));
 }
 let environmentIdCounter = 0;
+/** @see REnvironmentInformation */
 class Environment {
     id = environmentIdCounter++;
     parent;
@@ -52,14 +56,30 @@ class Environment {
     }
 }
 exports.Environment = Environment;
-/* the built-in environment is the root of all environments */
+/**
+ * The built-in {@link REnvironmentInformation|environment} is the root of all environments.
+ *
+ * For its default content (when not overwritten by a flowR config),
+ * see the {@link DefaultBuiltinConfig}.
+ */
 exports.BuiltInEnvironment = new Environment(undefined);
 exports.BuiltInEnvironment.memory = undefined;
+/**
+ * The twin of the {@link BuiltInEnvironment} but with less built ins defined for
+ * cases in which we want some commonly overwritten variables to remain open.
+ * If you do not know if you need the empty environment, you do not need the empty environment (right now).
+ *
+ * @see {@link BuiltInEnvironment}
+ */
 exports.EmptyBuiltInEnvironment = {
     id: exports.BuiltInEnvironment.id,
     memory: undefined,
     parent: undefined
 };
+/**
+ * Initialize a new {@link REnvironmentInformation|environment} with the built-ins.
+ * See {@link EmptyBuiltInEnvironment} for the case `fullBuiltIns = false`.
+ */
 function initializeCleanEnvironments(fullBuiltIns = true) {
     exports.BuiltInEnvironment.memory ??= built_in_1.BuiltInMemory;
     exports.EmptyBuiltInEnvironment.memory ??= built_in_1.EmptyBuiltInMemory;
@@ -68,6 +88,9 @@ function initializeCleanEnvironments(fullBuiltIns = true) {
         level: 0
     };
 }
+/**
+ * Helps to serialize an environment, but replaces the built-in environment with a placeholder.
+ */
 function builtInEnvJsonReplacer(k, v) {
     if (v === exports.BuiltInEnvironment) {
         return '<BuiltInEnvironment>';