@eagleoutice/flowr 2.9.13 → 2.10.1

package/documentation/doc-util/doc-dfg.js

@@ -4,16 +4,14 @@ exports.printDfGraph = printDfGraph;
 exports.formatSideEffect = formatSideEffect;
 exports.printDfGraphForCode = printDfGraphForCode;
 exports.verifyExpectedSubgraph = verifyExpectedSubgraph;
-const dfg_1 = require("../../util/mermaid/dfg");
 const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
 const decorate_1 = require("../../r-bridge/lang-4.x/ast/model/processing/decorate");
-const resolve_graph_1 = require("../../dataflow/graph/resolve-graph");
-const diff_dataflow_graph_1 = require("../../dataflow/graph/diff-dataflow-graph");
 const assert_1 = require("../../util/assert");
 const time_1 = require("../../util/text/time");
 const doc_files_1 = require("./doc-files");
 const doc_code_1 = require("./doc-code");
 const flowr_analyzer_context_1 = require("../../project/context/flowr-analyzer-context");
+const df_helper_1 = require("../../dataflow/graph/df-helper");
 const call_graph_1 = require("../../dataflow/graph/call-graph");
 /**
  * Visualizes the dataflow graph as a mermaid graph inside a markdown code block.
@@ -21,7 +19,7 @@ const call_graph_1 = require("../../dataflow/graph/call-graph");
  */
 function printDfGraph(graph, mark, simplified = false) {
     return `
-${(0, doc_code_1.codeBlock)('mermaid', (0, dfg_1.graphToMermaid)({
+${(0, doc_code_1.codeBlock)('mermaid', df_helper_1.Dataflow.visualize.mermaid.convert({
         graph,
         prefix: 'flowchart LR',
         mark,
@@ -55,7 +53,7 @@ async function printDfGraphForCode(parser, code, { callGraph = false, simplified
         (0, assert_1.guard)(showCode, 'can not switch code and graph if code is not shown');
     }
     const metaInfo = `The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parse and normalize, using the [${parser.name}](${doc_files_1.FlowrWikiBaseRef}/Engines) engine) within the generation environment.`;
-    const graph = callGraph ? (0, call_graph_1.computeCallGraph)(result.dataflow.graph) : result.dataflow.graph;
+    const graph = callGraph ? call_graph_1.CallGraph.compute(result.dataflow.graph) : result.dataflow.graph;
     const dfGraph = printDfGraph(graph, mark, simplified);
     const simplyText = simplified ? '(simplified) ' : '';
     const graphName = callGraph ? 'Call Graph' : 'Dataflow Graph';
@@ -92,8 +90,8 @@ async function verifyExpectedSubgraph(parser, code, expectedSubgraph) {
         getId: (0, decorate_1.deterministicCountingIdGenerator)(0)
     }).allRemainingSteps();
     expectedSubgraph.setIdMap(info.normalize.idMap);
-    expectedSubgraph = (0, resolve_graph_1.resolveDataflowGraph)(expectedSubgraph, context);
-    const report = (0, diff_dataflow_graph_1.diffOfDataflowGraphs)({ name: 'expected', graph: expectedSubgraph }, { name: 'got', graph: info.dataflow.graph }, {
+    expectedSubgraph = df_helper_1.Dataflow.resolveGraphCriteria(expectedSubgraph, context);
+    const report = df_helper_1.Dataflow.diffGraphs({ name: 'expected', graph: expectedSubgraph }, { name: 'got', graph: info.dataflow.graph }, {
         leftIsSubgraph: true
     });
     (0, assert_1.guard)(report.isEqual(), () => `report:\n * ${report.comments()?.join('\n * ') ?? ''}`);

package/documentation/doc-util/doc-normalized-ast.d.ts

@@ -1,5 +1,3 @@
-import type { DataflowGraph } from '../../dataflow/graph/graph';
-import type { RShell } from '../../r-bridge/shell';
 import { type ParentInformation, type RNodeWithParent } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { KnownParser } from '../../r-bridge/parser';
 import type { RProject } from '../../r-bridge/lang-4.x/ast/model/nodes/r-project';
@@ -17,7 +15,3 @@ export interface PrintNormalizedAstOptions {
  * This is intended for documentation purposes.
  */
 export declare function printNormalizedAstForCode(parser: KnownParser, code: string, { showCode, prefix }?: PrintNormalizedAstOptions): Promise<string>;
-/**
- * returns resolved expected df graph
- */
-export declare function verifyExpectedSubgraph(shell: RShell, code: string, expectedSubgraph: DataflowGraph): Promise<DataflowGraph>;

package/documentation/doc-util/doc-normalized-ast.js

@@ -2,12 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printNormalizedAst = printNormalizedAst;
 exports.printNormalizedAstForCode = printNormalizedAstForCode;
-exports.verifyExpectedSubgraph = verifyExpectedSubgraph;
 const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
-const decorate_1 = require("../../r-bridge/lang-4.x/ast/model/processing/decorate");
-const resolve_graph_1 = require("../../dataflow/graph/resolve-graph");
-const diff_dataflow_graph_1 = require("../../dataflow/graph/diff-dataflow-graph");
-const assert_1 = require("../../util/assert");
 const ast_1 = require("../../util/mermaid/ast");
 const time_1 = require("../../util/text/time");
 const doc_files_1 = require("./doc-files");
@@ -59,22 +54,4 @@ ${(0, ast_1.normalizedAstToMermaid)(result.normalize.ast, { prefix })}
 
 ` : '\n(' + metaInfo + ')\n\n');
 }
-/**
- * returns resolved expected df graph
- */
-async function verifyExpectedSubgraph(shell, code, expectedSubgraph) {
-    /* we verify that we get what we want first! */
-    const context = (0, flowr_analyzer_context_1.contextFromInput)(code);
-    const info = await (0, default_pipelines_1.createDataflowPipeline)(shell, {
-        context: context,
-        getId: (0, decorate_1.deterministicCountingIdGenerator)(0)
-    }).allRemainingSteps();
-    expectedSubgraph.setIdMap(info.normalize.idMap);
-    expectedSubgraph = (0, resolve_graph_1.resolveDataflowGraph)(expectedSubgraph, context);
-    const report = (0, diff_dataflow_graph_1.diffOfDataflowGraphs)({ name: 'expected', graph: expectedSubgraph }, { name: 'got', graph: info.dataflow.graph }, {
-        leftIsSubgraph: true
-    });
-    (0, assert_1.guard)(report.isEqual(), () => `report:\n * ${report.comments()?.join('\n * ') ?? ''}`);
-    return expectedSubgraph;
-}
 //# sourceMappingURL=doc-normalized-ast.js.map

package/documentation/doc-util/doc-structure.js

@@ -5,8 +5,8 @@ exports.block = block;
 exports.section = section;
 exports.collapsibleToc = collapsibleToc;
 const doc_general_1 = require("./doc-general");
-const mermaid_1 = require("../../util/mermaid/mermaid");
 const strings_1 = require("../../util/text/strings");
+const mermaid_1 = require("../../util/mermaid/mermaid");
 /**
  *
  */
@@ -31,7 +31,7 @@ ${(0, doc_general_1.prefixLines)(content, '> ')}
 /**
  *
  */
-function section(title, depth = 2, anchor = (0, mermaid_1.escapeId)(title)) {
+function section(title, depth = 2, anchor = mermaid_1.Mermaid.escapeId(title)) {
     return `<h${depth} id="${anchor}">${title}</h${depth}>`;
 }
 function strToLink(str) {
@@ -40,7 +40,7 @@ function strToLink(str) {
         const [, name, link] = match;
         return `[${name}](${link})`;
     }
-    return `[${str}](#${(0, mermaid_1.escapeId)(str)})`;
+    return `[${str}](#${mermaid_1.Mermaid.escapeId(str)})`;
 }
 /**
  * Supported pattern: `Name@link`

package/documentation/doc-util/doc-types.js

@@ -54,11 +54,11 @@ const assert_1 = require("../../util/assert");
 const doc_files_1 = require("./doc-files");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const mermaid_1 = require("../../util/mermaid/mermaid");
 const doc_code_1 = require("./doc-code");
 const doc_structure_1 = require("./doc-structure");
 const html_hover_over_1 = require("../../util/html-hover-over");
 const doc_general_1 = require("./doc-general");
+const mermaid_1 = require("../../util/mermaid/mermaid");
 const options = {
     target: typescript_1.default.ScriptTarget.ESNext,
     skipLibCheck: true,
@@ -186,7 +186,7 @@ function formatNode(node, sourceFile, typeChecker) {
     }
     const type = getType(node, typeChecker);
     const typeAnnotation = type.includes('=>') ? type.replaceAll(/\s+=>\s+/g, ' ') : ': ' + type;
-    return `${prefix}${(0, mermaid_1.escapeMarkdown)(name + typeAnnotation)}${suffix}`;
+    return `${prefix}${mermaid_1.Mermaid.escape(name + typeAnnotation)}${suffix}`;
 }
 function getType(node, typeChecker) {
     const tryDirect = typeChecker.getTypeAtLocation(node);
@@ -381,7 +381,7 @@ function generateMermaidClassDiagram(hierarchyList, rootName, options, visited =
     if (node.kind === 'type') {
         collect.nodeLines.push(`style ${node.name} opacity:.35,fill:#FAFAFA`);
     }
-    collect.nodeLines.push(`click ${node.name} href "${getTypePathLink(node)}" "${(0, mermaid_1.escapeMarkdown)(node.comments?.join('; ').replace(/\n/g, ' ') ?? '')}"`);
+    collect.nodeLines.push(`click ${node.name} href "${getTypePathLink(node)}" "${mermaid_1.Mermaid.escape(node.comments?.join('; ').replace(/\n/g, ' ') ?? '')}"`);
     const inline = [...options.inlineTypes ?? [], ...defaultSkip];
     let baseTypes = node.extends;
     if (options.reverse) {

package/documentation/wiki-core.js

@@ -45,6 +45,7 @@ const doc_structure_1 = require("./doc-util/doc-structure");
 const shell_1 = require("../r-bridge/shell");
 const log_1 = require("../../test/functionality/_helper/log");
 const log_2 = require("../util/log");
+const model_1 = require("../r-bridge/lang-4.x/ast/model/model");
 async function makeAnalyzerExample() {
     const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder()
         .configure('ignoreSourceCalls', true)
@@ -308,7 +309,7 @@ If you are interested in the raw token types that we may encounter, have a look
 The normalization function ${ctx.link(parser_2.normalize)} takes the output from the previous steps and uses the ${ctx.link(format_1.prepareParsedData)} and 
 ${ctx.link(format_1.convertPreparedParsedData)} functions to first transform the serialized parsing output to an object. 
 Next, ${ctx.link(normalize_root_1.normalizeRootObjToAst)} transforms this object to a normalized AST and ${ctx.link(decorate_1.decorateAst)} adds additional information to the AST (like roles, ids, depth, etc.).
-While looking at the mermaid visualization of such an AST is nice and usually sufficient, looking at the objects themselves shows you the full range of information the AST provides (all encompassed within the ${ctx.link('RNode')} type).
+While looking at the mermaid visualization of such an AST is nice and usually sufficient, looking at the objects themselves shows you the full range of information the AST provides (all encompassed within the ${ctx.link(model_1.RNode)} type).
 
 Let's have a look at the normalized AST for the sample code \`${sampleCode}\` (please refer to the [normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized-AST) wiki page for more information):
 
@@ -358,7 +359,7 @@ We use the ${ctx.link(extractor_1.produceDataFlowGraph)} function as an entry po
 The function is mainly backed by its ${ctx.link('processors')} object which maps each type in the normalized AST to an appropriate handler ("fold-function").
 
 To understand these handlers, let's start with the simplest one, ${ctx.link(process_uninteresting_leaf_1.processUninterestingLeaf)} signals that 
-we do not care about this node and just produce an empty dataflow information (using ${ctx.link(info_1.initializeCleanDataflowInformation)}). 
+we do not care about this node and just produce an empty dataflow information (using ${ctx.linkO(info_1.DataflowInformation, 'initialize')}). 
 Looking at the function showcases the general structure of a processor:
 
 ${ctx.hierarchy(process_uninteresting_leaf_1.processUninterestingLeaf, { maxDepth: 2, openTop: true })}
@@ -384,7 +385,7 @@ ${ctx.hierarchy(process_value_1.processValue, { maxDepth: 2, openTop: true })}
 
 Please note, that we add the [value vertex](${doc_files_1.FlowrWikiBaseRef}/Dataflow-Graph#value-vertex) to the newly created dataflow graph,
 which holds a reference to the constant. If you are confused with the use of the ${ctx.link('ParentInformation')} type, 
-this stems from the [AST decoration](#normalization) and signals that we have a decorated ${ctx.link('RNode')} (which may have additional information in \`OtherInfo\`).
+this stems from the [AST decoration](#normalization) and signals that we have a decorated ${ctx.link(model_1.RNode)} (which may have additional information in \`OtherInfo\`).
 
 Yet again, this is not very interesting. When looking at the ${ctx.link('processors')} object you may be confused by
 many lines just mapping the node to the ${ctx.link(process_named_call_1.processAsNamedCall)} function.
@@ -424,7 +425,7 @@ to produce a new dataflow information.
 
 Given the [dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow-Graph), you can do a lot more!
 You can issue [queries](${doc_files_1.FlowrWikiBaseRef}/Query-API) to explore the graph, [search](${doc_files_1.FlowrWikiBaseRef}/Search-API) for specific elements, or, for example, request a [static backward slice](#static-backward-slicing).
-Of course, all of these endeavors work not just with the ${ctx.link(shell_1.RShell.name)} but also with the [\`tree-sitter\` engine](${doc_files_1.FlowrWikiBaseRef}/Engines). 
+Of course, all of these endeavors work not just with the ${ctx.link(shell_1.RShell)} but also with the [\`tree-sitter\` engine](${doc_files_1.FlowrWikiBaseRef}/Engines). 
 
 ### Static Backward Slicing
 

package/documentation/wiki-dataflow-graph.js

@@ -38,11 +38,12 @@ const flowr_analyzer_builder_1 = require("../project/flowr-analyzer-builder");
 const flowr_analyzer_context_1 = require("../project/context/flowr-analyzer-context");
 const doc_maker_1 = require("./wiki-mk/doc-maker");
 const flowr_analyzer_1 = require("../project/flowr-analyzer");
-const built_in_1 = require("../dataflow/environments/built-in");
 const dfg_1 = require("../util/mermaid/dfg");
 const r_number_1 = require("../r-bridge/lang-4.x/ast/model/nodes/r-number");
 const model_1 = require("../r-bridge/lang-4.x/ast/model/model");
 const range_1 = require("../util/range");
+const df_helper_1 = require("../dataflow/graph/df-helper");
+const built_in_proc_name_1 = require("../dataflow/environments/built-in-proc-name");
 async function subExplanation(parser, { description, code, expectedSubgraph }) {
     expectedSubgraph = await (0, doc_dfg_1.verifyExpectedSubgraph)(parser, code, expectedSubgraph);
     const marks = [];
@@ -170,7 +171,7 @@ ${(0, doc_structure_1.block)({
                 content: `
 	If you want to obtain the locations where a variable is defined, or read, or re-defined, refrain from tracking these details manually in the dataflow graph
 	as there are some edge-cases that require special attention.
-	In general, the ${ctx.link(dfg_get_origin_1.getOriginInDfg)} function explained below in [working with the dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph#working-with-the-dataflow-graph) will help you to get the information you need.
+	In general, the ${ctx.link(dfg_get_origin_1.getOriginInDfg)} (which is also available as ${ctx.linkO(df_helper_1.Dataflow, 'origin')}) function explained below in [working with the dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph#working-with-the-dataflow-graph) will help you to get the information you need.
 	`
             })}
 
@@ -196,8 +197,8 @@ ${ctx.hierarchy('FunctionArgument')}
 
 There is another element of potential interest to you, the \`origin\` property which records how flowR created the respective function call.
 These origins may hold the name of any processor that is part of the ${ctx.link('BuiltInProcName')} enumeration to signal that the respective processor (cf. ${ctx.link('BuiltInProcessorMapper')}) was responsible for creating the vertex.
-The entry \`${built_in_1.BuiltInProcName.Function}\` signals that flowR used a processor for a user-defined function defined within the source code, \`${built_in_1.BuiltInProcName.Unnamed}\` signals that the function as an anonymous function definition.
-However, in general, flowR may use any fitting handler as an origin (see the ${ctx.link('BuiltInProcName')} enum for a *complete* list). For example, within a access definition, flowR will correspondingly redefine the meaning of \`:=\` to that of the \`${built_in_1.BuiltInProcName.TableAssignment}\`. 
+The entry \`${built_in_proc_name_1.BuiltInProcName.Function}\` signals that flowR used a processor for a user-defined function defined within the source code, \`${built_in_proc_name_1.BuiltInProcName.Unnamed}\` signals that the function as an anonymous function definition.
+However, in general, flowR may use any fitting handler as an origin (see the ${ctx.link('BuiltInProcName')} enum for a *complete* list). For example, within a access definition, flowR will correspondingly redefine the meaning of \`:=\` to that of the \`${built_in_proc_name_1.BuiltInProcName.TableAssignment}\`. 
 
 ${(0, doc_structure_1.details)('Example: Simple Function Call (unresolved)', await (async () => {
                 const code = 'foo(x,3,y=3,)';
@@ -367,7 +368,7 @@ ${(0, doc_structure_1.block)({
                 content: `Now you might be asking yourself how to differentiate anonymous and named functions and what you have to keep in mind when working with them?
 
 Unnamed functions have an array of signatures which you can use to identify them. 
-But in short: the \`origin\` attribute of the ${ctx.link('DataflowGraphVertexFunctionCall')} is \`${built_in_1.BuiltInProcName.Unnamed}\`.
+But in short: the \`origin\` attribute of the ${ctx.link('DataflowGraphVertexFunctionCall')} is \`${built_in_proc_name_1.BuiltInProcName.Unnamed}\`.
 Please be aware that unnamed functions still have a \`name\` property to give it a unique identifier that can be used for debugging and reference.
 This name _always_ starts with \`${unnamed_call_handling_1.UnnamedFunctionCallPrefix}\`.
 
@@ -1052,7 +1053,8 @@ ${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'alias <- unknown\nalias(
 ${(0, doc_structure_1.section)('Working with the Dataflow Graph', 2, 'dfg-working')}
 
 The ${ctx.link('DataflowInformation')} is the core result of _flowR_ and summarizes a lot of information.
-Depending on what you are interested in, there exists a plethora of functions and queries to help you out, answering the most important questions:
+Depending on what you are interested in, there exists a plethora of functions and queries to help you out, answering the most important questions.
+Generally, we recommend you check out the ${ctx.link(df_helper_1.Dataflow, undefined, { type: 'variable' })} helper object!
 
 * The **${ctx.linkPage('wiki/Query API')}** provides many functions to query the dataflow graph for specific information (dependencies, calls, slices, clusters, ...)
 * The **${ctx.linkPage('wiki/Search API')}** allows you to search for specific vertices or edges in the dataflow graph or the original program
@@ -1064,9 +1066,9 @@ Depending on what you are interested in, there exists a plethora of functions an
 
 FlowR also provides various helper objects (with the same name as the corresponding type) to help you work with the dataflow graph:
 
-* ${ctx.link('DfEdge', undefined, { type: 'variable' })} to get helpful functions wrt. edges (see [below](#dfg-resolving-values))
-* ${ctx.link('Identifier', undefined, { type: 'variable' })} to get helpful functions wrt. identifiers
-* ${ctx.link('FunctionArgument', undefined, { type: 'variable' })} to get helpful functions wrt. function arguments
+* ${ctx.link(edge_1.DfEdge, undefined, { type: 'variable' })} to get helpful functions wrt. edges (see [below](#dfg-resolving-values))
+* ${ctx.link(identifier_1.Identifier, undefined, { type: 'variable' })} to get helpful functions wrt. identifiers
+* ${ctx.link(graph_1.FunctionArgument, undefined, { type: 'variable' })} to get helpful functions wrt. function arguments
 
 Some of these functions have been explained in their respective wiki pages. However, some are part of the ${ctx.linkPage('wiki/Dataflow Graph', 'Dataflow Graph API')} and so we explain them here.
 If you are interested in which features we support and which features are still to be worked on, please refer to our ${ctx.linkPage('wiki/Capabilities', 'capabilities')} page.
@@ -1107,14 +1109,14 @@ ${await (async () => {
                 }
                 throw new Error('Could not find edge');
             })()}&mdash;which is usually not very helpful.
-You can use ${ctx.link('DfEdge::splitTypes')} to get the individual bitmasks of all included types, and 
-${ctx.link('DfEdge::includesType')} to check whether a specific type (or one of a collection of types) is included in the edge.
+You can use ${ctx.linkO(edge_1.DfEdge, 'splitTypes')} to get the individual bitmasks of all included types, and 
+${ctx.linkO(edge_1.DfEdge, 'includesType')} to check whether a specific type (or one of a collection of types) is included in the edge.
 
 ${(0, doc_structure_1.section)('Handling Origins', 3, 'dfg-handling-origins')}
 
 If you are writing another analysis on top of the dataflow graph, you probably want to know all definitions that serve as the source of a read, all functions
 that are called by an invocation, and more.
-For this, the ${ctx.link(dfg_get_origin_1.getOriginInDfg)} function provides you with a collection of ${ctx.link('Origin')} objects:
+For this, the ${ctx.link(dfg_get_origin_1.getOriginInDfg)} (this is also accessible with ${ctx.linkO(df_helper_1.Dataflow, 'origin')}) function provides you with a collection of ${ctx.link('Origin')} objects:
 
 ${ctx.hierarchy('Origin', { openTop: true })}
 

package/documentation/wiki-interface.js

@@ -18,8 +18,8 @@ const flowr_main_options_1 = require("../cli/flowr-main-options");
 const doc_issue_1 = require("./doc-util/doc-issue");
 const doc_structure_1 = require("./doc-util/doc-structure");
 const doc_maker_1 = require("./wiki-mk/doc-maker");
-const built_in_1 = require("../dataflow/environments/built-in");
 const doc_writing_code_1 = require("./data/interface/doc-writing-code");
+const built_in_proc_name_1 = require("../dataflow/environments/built-in-proc-name");
 async function explainServer(parser) {
     (0, doc_data_server_messages_1.documentAllServerMessages)();
     return `
@@ -236,7 +236,7 @@ ${(0, doc_code_1.codeBlock)('json', JSON.stringify({
             environment: {
                 overwriteBuiltIns: {
                     definitions: [
-                        { type: 'function', names: ['foo'], processor: built_in_1.BuiltInProcName.Assignment, config: {} }
+                        { type: 'function', names: ['foo'], processor: built_in_proc_name_1.BuiltInProcName.Assignment, config: {} }
                     ]
                 }
             }
@@ -290,7 +290,7 @@ ${(0, doc_code_1.codeBlock)('json', JSON.stringify({
   | Type            | Description                                                                                                                                                                                                                                                                                              | Example                                                                                                    |
   | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
   | \`constant\`    | Additionally allows for a \`value\` this should resolve to.                                                                                                                                                                                                                                                | \`{ type: 'constant', names: ['NULL', 'NA'],  value: null }\`                                                |
-  | \`function\`    | Is a rather flexible way to define and bind built-in functions. For the time, we do not have extensive documentation to cover all the cases, so please either consult the sources with the \`default-builtin-config.ts\` or open a [new issue](${doc_issue_1.NewIssueUrl}). | \`{ type: 'function', names: ['next'], processor: '${built_in_1.BuiltInProcName.Default}', config: { cfg: ExitPointType.Next } }\` |
+  | \`function\`    | Is a rather flexible way to define and bind built-in functions. For the time, we do not have extensive documentation to cover all the cases, so please either consult the sources with the \`default-builtin-config.ts\` or open a [new issue](${doc_issue_1.NewIssueUrl}). | \`{ type: 'function', names: ['next'], processor: '${built_in_proc_name_1.BuiltInProcName.Default}', config: { cfg: ExitPointType.Next } }\` |
   | \`replacement\` | A comfortable way to specify replacement functions like \`$<-\` or \`names<-\`. \`suffixes\` describes the... suffixes to attach automatically. | \`{ type: 'replacement', suffixes: ['<-', '<<-'], names: ['[', '[['] }\` |
 
 

package/documentation/wiki-linter.js

@@ -122,6 +122,12 @@ df[6, "value"]
 `, tagTypes);
     rule(knownParser, 'dead-code', 'DeadCodeConfig', 'DEAD_CODE', 'lint-dead-code', 'if(TRUE) 1 else 2', tagTypes);
     rule(knownParser, 'useless-loop', 'UselessLoopConfig', 'USELESS_LOOP', 'lint-useless-loop', 'for(i in c(1)) { print(i) }', tagTypes);
+    rule(knownParser, 'stop-call', 'StopWithCallConfig', 'STOP_WITH_CALL_ARG', 'lint-stop-call', 'stop(42)', tagTypes);
+    rule(knownParser, 'problematic-eval', 'ProblematicEvalConfig', 'PROBLEMATIC_EVAL', 'lint-problematic-eval', `
+function(x) {
+	eval(x)
+}
+`, tagTypes);
     function rule(parser, name, configType, ruleType, testfile, example, types) {
         const rule = linter_rules_1.LintingRules[name];
         const tags = rule.info.tags.toSorted((a, b) => {

package/documentation/wiki-normalized-ast.js

@@ -16,6 +16,7 @@ const roxygen_parse_1 = require("../r-bridge/roxygen2/roxygen-parse");
 const r_binary_op_1 = require("../r-bridge/lang-4.x/ast/model/nodes/r-binary-op");
 const model_1 = require("../r-bridge/lang-4.x/ast/model/model");
 const r_project_1 = require("../r-bridge/lang-4.x/ast/model/nodes/r-project");
+const r_expression_list_1 = require("../r-bridge/lang-4.x/ast/model/nodes/r-expression-list");
 async function quickNormalizedAstMultipleFiles() {
     const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder()
         .setEngine('tree-sitter')
@@ -95,8 +96,8 @@ ${await (0, doc_normalized_ast_1.printNormalizedAstForCode)(treeSitter, 'x <- 2
 > you can either use the [Visual Studio Code extension](${doc_files_1.FlowrGithubBaseRef}/vscode-flowr) or the ${(0, doc_cli_option_1.getReplCommand)('normalize*')} 
 > command in the REPL (see the [Interface wiki page](${doc_files_1.FlowrWikiBaseRef}/Interface) for more information).
 
-Indicative of the normalization is the root ${ctx.link('RProject')} node, which is present in every normalized AST
-and provides the ${ctx.link('RExpressionList')} nodes for each file in the project.
+Indicative of the normalization is the root ${ctx.link(r_project_1.RProject)} node, which is present in every normalized AST
+and provides the ${ctx.link(r_expression_list_1.RExpressionList)} nodes for each file in the project.
 In general, we provide node types for:
 
 1. literals (e.g., numbers and strings)
@@ -112,7 +113,7 @@ In general, we provide node types for:
 Every node is a link, which directly refers to the implementation in the source code.
 Grayed-out parts are used for structuring the AST, grouping together related nodes.
 
-${(0, doc_code_1.codeBlock)('mermaid', ctx.mermaid('RNode'))}
+${(0, doc_code_1.codeBlock)('mermaid', ctx.mermaid(model_1.RNode))}
 
 </details>
 
@@ -123,7 +124,7 @@ Most notably, the \`info\` field holds the \`id\` of the node, which is used to
 
 In summary, we have the following types:
 
-${(0, doc_structure_1.details)('Normalized AST Node Types', ctx.hierarchy('RNode', { collapseFromNesting: Number.MAX_VALUE, ignoredTypes: ['Info', 'LogLevel'] }))}
+${(0, doc_structure_1.details)('Normalized AST Node Types', ctx.hierarchy(model_1.RNode, { collapseFromNesting: Number.MAX_VALUE, ignoredTypes: ['Info', 'LogLevel'] }))}
 
 The following segments intend to give you an overview of how to work with the normalized AST:
 

package/documentation/wiki-query.js

@@ -29,7 +29,6 @@ const vertex_1 = require("../dataflow/graph/vertex");
 const control_flow_query_executor_1 = require("../queries/catalog/control-flow-query/control-flow-query-executor");
 const doc_cfg_1 = require("./doc-util/doc-cfg");
 const df_shape_query_executor_1 = require("../queries/catalog/df-shape-query/df-shape-query-executor");
-const _00_slice_1 = require("../core/steps/all/static-slicing/00-slice");
 const doc_repl_1 = require("./doc-util/doc-repl");
 const inspect_higher_order_query_executor_1 = require("../queries/catalog/inspect-higher-order-query/inspect-higher-order-query-executor");
 const doc_escape_1 = require("./doc-util/doc-escape");
@@ -39,6 +38,8 @@ const call_graph_query_executor_1 = require("../queries/catalog/call-graph-query
 const inspect_recursion_query_executor_1 = require("../queries/catalog/inspect-recursion-query/inspect-recursion-query-executor");
 const does_call_query_executor_1 = require("../queries/catalog/does-call-query/does-call-query-executor");
 const inspect_exception_query_executor_1 = require("../queries/catalog/inspect-exceptions-query/inspect-exception-query-executor");
+const slice_direction_1 = require("../util/slice-direction");
+const provenance_query_executor_1 = require("../queries/catalog/provenance-query/provenance-query-executor");
 (0, doc_query_1.registerQueryDocumentation)('call-context', {
     name: 'Call-Context Query',
     type: 'active',
@@ -554,7 +555,7 @@ To specify a variable of interest, you have to present flowR with a [slicing cri
 
 To exemplify the capabilities, consider the following code:
 ${(0, doc_code_1.codeBlock)('r', exampleCode)}
-If you are interested in the parts required for the use of \`x\` in the last line, you can use the following query:
+If you are interested in the parts required for the use of \`x\` in the last line and \`z\`, you can use the following query:
 
 ${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
                 type: 'static-slice',
@@ -575,7 +576,7 @@ Likewise, if you want the forward slice for the first use of \`x\`, you can do i
 ${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
                 type: 'static-slice',
                 criteria: ['1@x'],
-                direction: _00_slice_1.SliceDirection.Forward
+                direction: slice_direction_1.SliceDirection.Forward
             }], { showCode: false, shorthand: (0, doc_query_1.sliceQueryShorthand)(['1@x'], (0, doc_escape_1.escapeNewline)(exampleCode), true) })}
 
 You can disable [magic comments](${doc_files_1.FlowrWikiBaseRef}/Interface#slice-magic-comments) using the \`noMagicComments\` flag.
@@ -583,6 +584,30 @@ This query replaces the old [\`request-slice\`](${doc_files_1.FlowrWikiBaseRef}/
 		`;
     }
 });
+(0, doc_query_1.registerQueryDocumentation)('provenance', {
+    name: 'Provenance Query',
+    type: 'active',
+    shortDescription: 'Calculate the provenance of a given variable, optionally restricted to its enveloping fdef',
+    functionName: provenance_query_executor_1.executeProvenanceQuery.name,
+    functionFile: '../queries/catalog/provenance-query/provenance-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'x <- 1\ny <- 2\nz <- 3\nx';
+        const criterion = '4@x';
+        return `
+Given a [slicing criterion](${doc_files_1.FlowrWikiBaseRef}/Terminology#slicing-criterion), flowR will return the provenance
+of the given program element (i.e., all related vertices in a non-interprocedural and non-context sensitive backward slice).
+
+To exemplify the capabilities, consider the following code:
+${(0, doc_code_1.codeBlock)('r', exampleCode)}
+If you are interested in the provenance of the \`x\` in the last line you can use:
+
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'provenance',
+                criterion
+            }], { showCode: false, shorthand: (0, doc_query_1.sliceQueryShorthand)([criterion], (0, doc_escape_1.escapeNewline)(exampleCode)) })}
+`;
+    }
+});
 (0, doc_query_1.registerQueryDocumentation)('dependencies', {
     name: 'Dependencies Query',
     type: 'active',

package/linter/linter-rules.d.ts

@@ -277,10 +277,58 @@ export declare const LintingRules: {
             readonly certainty: import("./linter-format").LintingRuleCertainty.BestEffort;
             readonly tags: readonly [import("./linter-tags").LintingRuleTag.Smell, import("./linter-tags").LintingRuleTag.Readability];
             readonly defaultConfig: {
-                readonly loopyFunctions: Set<import("../dataflow/environments/built-in").BuiltInProcName>;
+                readonly loopyFunctions: Set<import("../dataflow/environments/built-in-proc-name").BuiltInProcName>;
             };
         };
     };
+    readonly 'problematic-eval': {
+        readonly createSearch: (config: import("./rules/problematic-eval").ProblematicEvalConfig) => import("../search/flowr-search-builder").FlowrSearchBuilder<"from-query", [], import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../search/flowr-search").FlowrSearchElements<import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../search/flowr-search").FlowrSearchElement<import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>;
+        readonly processSearchResult: (elements: import("../search/flowr-search").FlowrSearchElements<import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../search/flowr-search").FlowrSearchElement<import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>, _config: import("./rules/problematic-eval").ProblematicEvalConfig, data: {
+            normalize: import("../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+            dataflow: import("../dataflow/info").DataflowInformation;
+            cfg: import("../control-flow/control-flow-graph").ControlFlowInformation;
+            analyzer: import("../project/flowr-analyzer").ReadonlyFlowrAnalysisProvider;
+        }) => Promise<{
+            results: import("./rules/problematic-eval").ProblematicEvalResult[];
+            ".meta": import("./rules/problematic-eval").ProblematicEvalMetadata;
+        }>;
+        readonly prettyPrint: {
+            readonly query: (result: import("./rules/problematic-eval").ProblematicEvalResult) => string;
+            readonly full: (result: import("./rules/problematic-eval").ProblematicEvalResult) => string;
+        };
+        readonly info: {
+            readonly name: "Problematic eval";
+            readonly description: "Detects uses of eval-like functions whose inputs are not statically constant. Prints the computed input-sources for the eval and flags usages that depend on non-constant/trusted inputs.";
+            readonly tags: readonly [import("./linter-tags").LintingRuleTag.Security, import("./linter-tags").LintingRuleTag.Smell, import("./linter-tags").LintingRuleTag.Readability, import("./linter-tags").LintingRuleTag.Performance];
+            readonly certainty: import("./linter-format").LintingRuleCertainty.BestEffort;
+            readonly defaultConfig: {
+                readonly considerAsEval: "^eval$";
+            };
+        };
+    };
+    readonly 'stop-call': {
+        readonly createSearch: () => import("../search/flowr-search-builder").FlowrSearchBuilder<"get", ["filter"], import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, Promise<import("../search/flowr-search").FlowrSearchElements<import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, [] | import("../search/flowr-search").FlowrSearchElement<import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>>;
+        readonly processSearchResult: (elements: import("../search/flowr-search").FlowrSearchElements<import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../search/flowr-search").FlowrSearchElement<import("../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>, _config: import("../util/objects").MergeableRecord, { dataflow, analyzer }: {
+            normalize: import("../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+            dataflow: import("../dataflow/info").DataflowInformation;
+            cfg: import("../control-flow/control-flow-graph").ControlFlowInformation;
+            analyzer: import("../project/flowr-analyzer").ReadonlyFlowrAnalysisProvider;
+        }) => {
+            results: import("ts-essentials").Writable<import("./rules/stop-with-call-arg").StopWithCallResult>[];
+            '.meta': import("./rules/stop-with-call-arg").StopWithCallMetadata;
+        };
+        readonly prettyPrint: {
+            readonly query: (result: import("./rules/stop-with-call-arg").StopWithCallResult) => string;
+            readonly full: (result: import("./rules/stop-with-call-arg").StopWithCallResult) => string;
+        };
+        readonly info: {
+            readonly name: "Stop without call.=False argument";
+            readonly tags: readonly [import("./linter-tags").LintingRuleTag.Smell];
+            readonly certainty: import("./linter-format").LintingRuleCertainty.BestEffort;
+            readonly description: "Checks whether stop calls without call. argument set to FALSE are used.";
+            readonly defaultConfig: {};
+        };
+    };
 };
 export type LintingRuleNames = keyof typeof LintingRules;
 export type LintingRuleMetadata<Name extends LintingRuleNames> = typeof LintingRules[Name] extends LintingRule<infer _Result, infer Metadata, infer _Config, infer _Info, infer _Elements> ? Metadata : never;

package/linter/linter-rules.js

@@ -11,6 +11,8 @@ const naming_convention_1 = require("./rules/naming-convention");
 const dataframe_access_validation_1 = require("./rules/dataframe-access-validation");
 const useless_loop_1 = require("./rules/useless-loop");
 const network_functions_1 = require("./rules/network-functions");
+const stop_with_call_arg_1 = require("./rules/stop-with-call-arg");
+const problematic_eval_1 = require("./rules/problematic-eval");
 /**
  * The registry of currently supported linting rules.
  * A linting rule can be executed on a dataflow pipeline result using {@link executeLintingRule}.
@@ -25,6 +27,8 @@ exports.LintingRules = {
     'network-functions': network_functions_1.NETWORK_FUNCTIONS,
     'dataframe-access-validation': dataframe_access_validation_1.DATA_FRAME_ACCESS_VALIDATION,
     'dead-code': dead_code_1.DEAD_CODE,
-    'useless-loop': useless_loop_1.USELESS_LOOP
+    'useless-loop': useless_loop_1.USELESS_LOOP,
+    'problematic-eval': problematic_eval_1.PROBLEMATIC_EVAL,
+    'stop-call': stop_with_call_arg_1.STOP_WITH_CALL_ARG
 };
 //# sourceMappingURL=linter-rules.js.map

package/linter/rules/problematic-eval.d.ts

@@ -0,0 +1,44 @@
+import { type LintingResult, LintingRuleCertainty } from '../linter-format';
+import type { MergeableRecord } from '../../util/objects';
+import { SourceLocation } from '../../util/range';
+import { LintingRuleTag } from '../linter-tags';
+import type { InputSources } from '../../queries/catalog/input-sources-query/simple-input-classifier';
+/**
+ * Describes a linting result for a problematic eval usage, including the location of the eval call and the computed input sources that lead to it.
+ */
+export interface ProblematicEvalResult extends LintingResult {
+    loc: SourceLocation;
+    sources: InputSources;
+}
+export interface ProblematicEvalConfig extends MergeableRecord {
+    /**
+     * All calls that should be considered to be valid eval entry points, this will be interpreted as a Regex!
+     */
+    considerAsEval: string;
+}
+export type ProblematicEvalMetadata = MergeableRecord;
+export declare const PROBLEMATIC_EVAL: {
+    readonly createSearch: (config: ProblematicEvalConfig) => import("../../search/flowr-search-builder").FlowrSearchBuilder<"from-query", [], import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>>;
+    readonly processSearchResult: (elements: import("../../search/flowr-search").FlowrSearchElements<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation, import("../../search/flowr-search").FlowrSearchElement<import("../../r-bridge/lang-4.x/ast/model/processing/decorate").ParentInformation>[]>, _config: ProblematicEvalConfig, data: {
+        normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+        dataflow: import("../../dataflow/info").DataflowInformation;
+        cfg: import("../../control-flow/control-flow-graph").ControlFlowInformation;
+        analyzer: import("../../project/flowr-analyzer").ReadonlyFlowrAnalysisProvider;
+    }) => Promise<{
+        results: ProblematicEvalResult[];
+        ".meta": ProblematicEvalMetadata;
+    }>;
+    readonly prettyPrint: {
+        readonly query: (result: ProblematicEvalResult) => string;
+        readonly full: (result: ProblematicEvalResult) => string;
+    };
+    readonly info: {
+        readonly name: "Problematic eval";
+        readonly description: "Detects uses of eval-like functions whose inputs are not statically constant. Prints the computed input-sources for the eval and flags usages that depend on non-constant/trusted inputs.";
+        readonly tags: readonly [LintingRuleTag.Security, LintingRuleTag.Smell, LintingRuleTag.Readability, LintingRuleTag.Performance];
+        readonly certainty: LintingRuleCertainty.BestEffort;
+        readonly defaultConfig: {
+            readonly considerAsEval: "^eval$";
+        };
+    };
+};