@eagleoutice/flowr 2.1.8 → 2.1.9

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/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
  */
@@ -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 },
@@ -83,7 +122,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/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>';

package/dataflow/environments/identifier.d.ts

@@ -5,9 +5,17 @@ export type Identifier = string & {
     __brand?: 'identifier';
 };
 /**
- * Each reference only has exactly one reference type, stored as the respective number.
- * However, when checking we may want to allow for one of several types,
+ * Each reference has exactly one reference type, stored as the respective number.
+ * However, when checking, we may want to allow for one of several types,
  * allowing the combination of the respective bitmasks.
+ *
+ * Having reference types is important as R separates a variable definition from
+ * a function when resolving an {@link Identifier|identifier}.
+ * In `c <- 3; print(c(1, 2))` the call to `c` works normally (as the vector constructor),
+ * while writing `c <- function(...) ..1` overshadows the built-in and causes `print` to only output the first element.
+ *
+ * @see {@link isReferenceType} - for checking if a (potentially joint) reference type contains a certain type
+ * @see {@link ReferenceTypeReverseMapping} - for debugging
  */
 export declare enum ReferenceType {
     /** The identifier type is unknown */
@@ -27,19 +35,38 @@ export declare enum ReferenceType {
     /** The identifier is defined by a built-in function */
     BuiltInFunction = 128
 }
+/** Reverse mapping of the reference types so you can get the name from the bitmask (useful for debugging) */
 export declare const ReferenceTypeReverseMapping: Map<ReferenceType, string>;
 /**
  * Check if the reference types have an overlapping type!
  */
 export declare function isReferenceType(t: ReferenceType, target: ReferenceType): boolean;
+/**
+ * Describes all types of reference (definitions) that can appear within a graph (i.e., that are not built-in like the
+ * default definition for the assignment operator `<-`).
+ *
+ * @see {@link InGraphIdentifierDefinition} - for the definition of an identifier within the graph
+ */
 export type InGraphReferenceType = Exclude<ReferenceType, ReferenceType.BuiltInConstant | ReferenceType.BuiltInFunction>;
 /**
- * Something like `a` in `b <- a`.
- * Without any surrounding information, `a` will produce the identifier reference `a`.
- * Similarly, `b` will create a reference.
+ * An identifier reference points to a variable like `a` in `b <- a`.
+ * Without any surrounding code, `a` will produce the identifier reference `a`.
+ * Similarly, `b` will create a reference (although it will be an {@link IdentifierDefinition|identifier definition}
+ * which adds even more information).
+ *
+ * In general,
+ * references are merely pointers (with meta-information) to a vertex in the {@link DataflowGraph|dataflow graph}.
+ * In the context of the extractor, for example,
+ * they indicate the references that are currently (during the analysis at this given node)
+ * {@link DataflowInformation#in|read (`in`)}, {@link DataflowInformation#out|written (`out`)},
+ * or {@link DataflowInformation#unknownReferences|unknown (`unknownReferences`)}.
+ *
+ * @see {@link InGraphIdentifierDefinition}
  */
 export interface IdentifierReference {
-    /** Node which represents the reference in the AST */
+    /**
+     * The id of the node which represents the reference in the {@link NormalizedAst|normalized AST} and the {@link DataflowGraph|dataflow graph}.
+     */
     readonly nodeId: NodeId;
     /** Name the reference is identified by (e.g., the name of the variable), undefined if the reference is "artificial" (e.g., anonymous) */
     readonly name: Identifier | undefined;
@@ -51,13 +78,28 @@ export interface IdentifierReference {
      */
     controlDependencies: ControlDependency[] | undefined;
 }
+/**
+ * The definition of an {@link Identifier|identifier} within the {@link DataflowGraph|graph}.
+ * This extends on the {@link IdentifierReference}
+ * by adding the {@link NodeId} of the definition
+ * (and using `type` to mark the object type).
+ *
+ * Within a code snippet like `a <- 3`, the symbol processor will first create an
+ * {@link IdentifierReference|identifier reference} for `a` to reference the use
+ * and then promote it to an {@link InGraphIdentifierDefinition|identifier definition}.
+ *
+ * @see {@link IdentifierReference}
+ */
 interface InGraphIdentifierDefinition extends IdentifierReference {
     readonly type: InGraphReferenceType;
     /** The assignment (or whatever, like `assign` function call) node which ultimately defined this identifier */
     readonly definedAt: NodeId;
 }
 /**
- * Stores the definition of an identifier within an {@link IEnvironment}
+ * Stores the definition of an identifier within an {@link IEnvironment}.
+ *
+ * {@link BuiltInIdentifierDefinition} and {@link BuiltInIdentifierConstant} are used for built-in functions and constants only,
+ * so the most important one for your day-to-day R script is the {@link InGraphIdentifierDefinition}.
  */
 export type IdentifierDefinition = InGraphIdentifierDefinition | BuiltInIdentifierDefinition | BuiltInIdentifierConstant;
 export {};

package/dataflow/environments/identifier.js

@@ -3,9 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReferenceTypeReverseMapping = exports.ReferenceType = void 0;
 exports.isReferenceType = isReferenceType;
 /**
- * Each reference only has exactly one reference type, stored as the respective number.
- * However, when checking we may want to allow for one of several types,
+ * Each reference has exactly one reference type, stored as the respective number.
+ * However, when checking, we may want to allow for one of several types,
  * allowing the combination of the respective bitmasks.
+ *
+ * Having reference types is important as R separates a variable definition from
+ * a function when resolving an {@link Identifier|identifier}.
+ * In `c <- 3; print(c(1, 2))` the call to `c` works normally (as the vector constructor),
+ * while writing `c <- function(...) ..1` overshadows the built-in and causes `print` to only output the first element.
+ *
+ * @see {@link isReferenceType} - for checking if a (potentially joint) reference type contains a certain type
+ * @see {@link ReferenceTypeReverseMapping} - for debugging
  */
 var ReferenceType;
 (function (ReferenceType) {
@@ -26,6 +34,7 @@ var ReferenceType;
     /** The identifier is defined by a built-in function */
     ReferenceType[ReferenceType["BuiltInFunction"] = 128] = "BuiltInFunction";
 })(ReferenceType || (exports.ReferenceType = ReferenceType = {}));
+/** Reverse mapping of the reference types so you can get the name from the bitmask (useful for debugging) */
 exports.ReferenceTypeReverseMapping = new Map(Object.entries(ReferenceType).map(([k, v]) => [v, k]));
 /**
  * Check if the reference types have an overlapping type!

package/dataflow/extractor.js

@@ -20,6 +20,7 @@ const built_in_source_1 = require("./internal/process/functions/call/built-in/bu
 const cfg_1 = require("../util/cfg/cfg");
 const edge_1 = require("./graph/edge");
 const identify_link_to_last_call_relation_1 = require("../queries/catalog/call-context-query/identify-link-to-last-call-relation");
+const built_in_function_definition_1 = require("./internal/process/functions/call/built-in/built-in-function-definition");
 exports.processors = {
     [type_1.RType.Number]: process_value_1.processValue,
     [type_1.RType.String]: process_value_1.processValue,
@@ -56,11 +57,9 @@ function resolveLinkToSideEffects(ast, graph) {
         if (typeof s !== 'object') {
             continue;
         }
-        if (!cfg) {
-            cfg = (0, cfg_1.extractCFG)(ast).graph;
-        }
+        cfg ??= (0, cfg_1.extractCFG)(ast).graph;
         /* this has to change whenever we add a new link to relations because we currently offer no abstraction for the type */
-        const potentials = (0, identify_link_to_last_call_relation_1.identifyLinkToLastCallRelation)(s.id, cfg, graph, s.linkTo.callName);
+        const potentials = (0, identify_link_to_last_call_relation_1.identifyLinkToLastCallRelation)(s.id, cfg, graph, s.linkTo);
         for (const pot of potentials) {
             graph.addEdge(s.id, pot, edge_1.EdgeType.Reads);
         }
@@ -92,6 +91,8 @@ function produceDataFlowGraph(request, ast) {
             df = (0, built_in_source_1.standaloneSourceFile)(request[i], dfData, `root-${i}`, df);
         }
     }
+    // finally, resolve linkages
+    (0, built_in_function_definition_1.updateNestedFunctionCalls)(df.graph, df.environment);
     resolveLinkToSideEffects(ast, df.graph);
     return df;
 }

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

@@ -114,6 +114,12 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      * @see reads for parameters.
      */
     definesOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this;
+    /**
+     * Adds a **defined-by-on-call edge** with from as definition, and to as variable.
+     *
+     * @see reads for parameters.
+     */
+    definedByOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this;
     /**
      * Adds an **argument edge** (E9) with from as function call, and to as argument.
      *

package/dataflow/graph/dataflowgraph-builder.js

@@ -212,6 +212,14 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
     definesOnCall(from, to) {
         return this.edgeHelper(from, to, edge_1.EdgeType.DefinesOnCall);
     }
+    /**
+     * Adds a **defined-by-on-call edge** with from as definition, and to as variable.
+     *
+     * @see reads for parameters.
+     */
+    definedByOnCall(from, to) {
+        return this.edgeHelper(from, to, edge_1.EdgeType.DefinedByOnCall);
+    }
     /**
      * Adds an **argument edge** (E9) with from as function call, and to as argument.
      *

package/dataflow/graph/edge.d.ts

@@ -19,9 +19,15 @@ export declare enum EdgeType {
     Calls = 4,
     /** The source returns target on call */
     Returns = 8,
-    /** The edge determines that source (probably argument) defines the target (probably parameter), currently automatically created by `addEdge` */
+    /**
+     * The edge determines that source (probably argument) defines the target (probably parameter).
+     * This may also link a function call to definitions it causes to be active (as part of the closure) of the called function definition.
+     */
     DefinesOnCall = 16,
-    /** Inverse of `defines-on-call` currently only needed to get better results when slicing complex function calls */
+    /**
+     * Usually the inverse of `defines-on-call` (in the context of arguments and parameters).
+     * This may also link an open read (within a function) to the definition that is active at the call site.
+     */
     DefinedByOnCall = 32,
     /** Formal used as argument to a function call */
     Argument = 64,
@@ -57,8 +63,8 @@ export declare const enum TraverseEdge {
     Never = 0,
     /** Traverse the edge as a side effect */
     SideEffect = 1,
-    /** Traverse this edge if the definition is relevant */
-    DefinedByOnCall = 2,
+    /** Traverse this edge if the definition is relevant (i.e., if two matching edges trigger this state) */
+    OnlyIfBoth = 2,
     /** Always traverse this edge */
     Always = 3
 }

package/dataflow/graph/edge.js

@@ -22,9 +22,15 @@ var EdgeType;
     EdgeType[EdgeType["Calls"] = 4] = "Calls";
     /** The source returns target on call */
     EdgeType[EdgeType["Returns"] = 8] = "Returns";
-    /** The edge determines that source (probably argument) defines the target (probably parameter), currently automatically created by `addEdge` */
+    /**
+     * The edge determines that source (probably argument) defines the target (probably parameter).
+     * This may also link a function call to definitions it causes to be active (as part of the closure) of the called function definition.
+     */
     EdgeType[EdgeType["DefinesOnCall"] = 16] = "DefinesOnCall";
-    /** Inverse of `defines-on-call` currently only needed to get better results when slicing complex function calls */
+    /**
+     * Usually the inverse of `defines-on-call` (in the context of arguments and parameters).
+     * This may also link an open read (within a function) to the definition that is active at the call site.
+     */
     EdgeType[EdgeType["DefinedByOnCall"] = 32] = "DefinedByOnCall";
     /** Formal used as argument to a function call */
     EdgeType[EdgeType["Argument"] = 64] = "Argument";
@@ -89,13 +95,14 @@ function edgeIncludesType(type, types) {
 function edgeDoesNotIncludeType(type, types) {
     return (types & type) === 0;
 }
-const alwaysTraverseEdgeTypes = EdgeType.Reads | EdgeType.DefinedBy | EdgeType.Argument | EdgeType.Calls | EdgeType.DefinesOnCall;
+const alwaysTraverseEdgeTypes = EdgeType.Reads | EdgeType.DefinedBy | EdgeType.Argument | EdgeType.Calls;
+const definedByOnCallTypes = EdgeType.DefinesOnCall | EdgeType.DefinedByOnCall;
 function shouldTraverseEdge(types) {
     if (edgeIncludesType(types, alwaysTraverseEdgeTypes)) {
         return 3 /* TraverseEdge.Always */;
     }
-    else if (edgeIncludesType(types, EdgeType.DefinedByOnCall)) {
-        return 2 /* TraverseEdge.DefinedByOnCall */;
+    else if (edgeIncludesType(types, definedByOnCallTypes)) {
+        return 2 /* TraverseEdge.OnlyIfBoth */;
     }
     else if (edgeIncludesType(types, EdgeType.SideEffectOnCall)) {
         return 1 /* TraverseEdge.SideEffect */;