@eagleoutice/flowr 2.1.11 → 2.2.0

package/documentation/print-dataflow-graph-wiki.js

@@ -85,7 +85,7 @@ async function getVertexExplanations(shell, vertexType) {
     /* we use the map to ensure order easily :D */
     const vertexExplanations = new Map();
     vertexExplanations.set(vertex_1.VertexType.Value, [{
-            shell: shell,
+            shell,
             name: 'Value Vertex',
             type: vertex_1.VertexType.Value,
             description: `
@@ -113,7 +113,7 @@ ${(0, doc_structure_1.details)('Example: Semantics Create a Value', `In the foll
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().constant('0')
         }, []]);
     vertexExplanations.set(vertex_1.VertexType.Use, [{
-            shell: shell,
+            shell,
             name: 'Use Vertex',
             type: vertex_1.VertexType.Use,
             description: `
@@ -160,7 +160,7 @@ ${(0, doc_structure_1.details)('Example: Reads Edge Identifying Multiple Definit
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().use('1@x', 'x')
         }, []]);
     vertexExplanations.set(vertex_1.VertexType.FunctionCall, [{
-            shell: shell,
+            shell,
             name: 'Function Call Vertex',
             type: vertex_1.VertexType.FunctionCall,
             description: `
@@ -348,7 +348,7 @@ ${(0, doc_structure_1.details)('Example: Function Call with a Side-Effect', awai
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().call('1@foo', 'foo', [])
         }, []]);
     vertexExplanations.set(vertex_1.VertexType.VariableDefinition, [{
-            shell: shell,
+            shell,
             name: 'Variable Definition Vertex',
             type: vertex_1.VertexType.VariableDefinition,
             description: `
@@ -392,7 +392,7 @@ As you can see, _flowR_ is able to recognize that the initial definition of \`x\
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().defineVariable('1@x', 'x')
         }, []]);
     vertexExplanations.set(vertex_1.VertexType.FunctionDefinition, [{
-            shell: shell,
+            shell,
             name: 'Function Definition Vertex',
             type: vertex_1.VertexType.FunctionDefinition,
             description: `
@@ -484,7 +484,7 @@ Besides this being a theoretically "shorter" way of defining a function, this be
 async function getEdgesExplanations(shell) {
     const edgeExplanations = new Map();
     edgeExplanations.set(edge_1.EdgeType.Reads, [{
-            shell: shell,
+            shell,
             name: 'Reads Edge',
             type: edge_1.EdgeType.Reads,
             description: `
@@ -522,7 +522,7 @@ Please refer to the explanation of the respective vertices for more information.
                 expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().reads('1:20', '1@x')
             }]]);
     edgeExplanations.set(edge_1.EdgeType.DefinedBy, [{
-            shell: shell,
+            shell,
             name: 'DefinedBy Edge', /* concat for link generation */
             type: edge_1.EdgeType.DefinedBy,
             description: `
@@ -546,7 +546,7 @@ However, nested definitions can carry it (in the nested case, \`x\` is defined b
                 expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().definedBy('1@x', '1:8')
             }]]);
     edgeExplanations.set(edge_1.EdgeType.Calls, [{
-            shell: shell,
+            shell,
             name: 'Calls Edge',
             type: edge_1.EdgeType.Calls,
             description: 'Link the [function call](#function-call-vertex) to the [function definition](#function-definition-vertex) that is called.',
@@ -554,7 +554,7 @@ However, nested definitions can carry it (in the nested case, \`x\` is defined b
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().calls('2@foo', '1@function')
         }, []]);
     edgeExplanations.set(edge_1.EdgeType.Returns, [{
-            shell: shell,
+            shell,
             name: 'Returns Edge',
             type: edge_1.EdgeType.Returns,
             description: 'Link the [function call](#function-call-vertex)  to the exit points of the target definition (this may incorporate the call-context).',
@@ -568,7 +568,7 @@ f()
 	`.trim();
     const dfInfo = await (0, doc_dfg_1.printDfGraphForCode)(shell, lateBindingExample, { switchCodeAndGraph: true, codeOpen: true, mark: new Set([1, '1->5', '9->5']) });
     edgeExplanations.set(edge_1.EdgeType.DefinesOnCall, [{
-            shell: shell,
+            shell,
             name: 'DefinesOnCall Edge',
             type: edge_1.EdgeType.DefinesOnCall,
             description: `*This edge is usually joined with ${linkEdgeName(edge_1.EdgeType.DefinedByOnCall)}!*
@@ -592,7 +592,7 @@ ${dfInfo}
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().definesOnCall('$11', '$1').definedByOnCall('$1', '$11')
         }, []]);
     edgeExplanations.set(edge_1.EdgeType.DefinedByOnCall, [{
-            shell: shell,
+            shell,
             name: 'DefinedByOnCall Edge',
             type: edge_1.EdgeType.DefinedByOnCall,
             description: `*This edge is usually joined with ${linkEdgeName(edge_1.EdgeType.DefinesOnCall)}!*
@@ -602,7 +602,7 @@ ${dfInfo}
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().definesOnCall('$11', '$1').definedByOnCall('$1', '$11')
         }, []]);
     edgeExplanations.set(edge_1.EdgeType.Argument, [{
-            shell: shell,
+            shell,
             name: 'Argument Edge',
             type: edge_1.EdgeType.Argument,
             description: `Links a [function call](#function-call-vertex) to the entry point of its arguments. If we do not know the target of such a call, we automatically assume that all arguments are read by the call as well!
@@ -613,7 +613,7 @@ The exception to this is the [function definition](#function-definition-vertex)
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().argument('1@f', '1@x').reads('1@f', '1@x').argument('1@f', '1@y').reads('1@f', '1@y')
         }, []]);
     edgeExplanations.set(edge_1.EdgeType.SideEffectOnCall, [{
-            shell: shell,
+            shell,
             name: 'SideEffectOnCall Edge',
             type: edge_1.EdgeType.SideEffectOnCall,
             description: 'Links a global side effect to an affected function call (e.g., a super definition within the function body)',
@@ -621,7 +621,7 @@ The exception to this is the [function definition](#function-definition-vertex)
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().sideEffectOnCall('1@x', '2@f')
         }, []]);
     edgeExplanations.set(edge_1.EdgeType.NonStandardEvaluation, [{
-            shell: shell,
+            shell,
             name: 'NonStandardEvaluation Edge',
             type: edge_1.EdgeType.NonStandardEvaluation,
             description: `
@@ -668,7 +668,7 @@ ${(0, doc_structure_1.details)('Example: While-Loop Body', await (0, doc_dfg_1.p
 async function dummyDataflow() {
     const shell = new shell_1.RShell();
     const result = await new pipeline_executor_1.PipelineExecutor(default_pipelines_1.DEFAULT_DATAFLOW_PIPELINE, {
-        shell,
+        parser: shell,
         request: (0, retriever_1.requestFromInput)('x <- 1\nx + 1')
     }).allRemainingSteps();
     shell.close();
@@ -689,7 +689,7 @@ async function getText(shell) {
     });
     return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'dataflow graph', rVersion: rversion })}
 
-This page briefly summarizes flowR's dataflow graph, represented by ${graph_1.DataflowGraph.name} in ${(0, doc_files_1.getFilePathMd)('../dataflow/graph/graph.ts')}.
+This page briefly summarizes flowR's dataflow graph, represented by ${(0, doc_types_1.shortLink)('DataflowGraph', vertexType.info)} in ${(0, doc_files_1.getFilePathMd)('../dataflow/graph/graph.ts')}.
 In case you want to manually build such a graph (e.g., for testing), you can use the builder in ${(0, doc_files_1.getFilePathMd)('../dataflow/graph/dataflowgraph-builder.ts')}.
 This wiki page focuses on explaining what such a dataflow graph looks like!
 

package/documentation/print-engines-wiki.d.ts

@@ -0,0 +1 @@
+export {};

package/documentation/print-engines-wiki.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const shell_1 = require("../r-bridge/shell");
+const log_1 = require("../../test/functionality/_helper/log");
+const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
+const doc_types_1 = require("./doc-util/doc-types");
+const path_1 = __importDefault(require("path"));
+const shell_executor_1 = require("../r-bridge/shell-executor");
+const tree_sitter_executor_1 = require("../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor");
+const doc_files_1 = require("./doc-util/doc-files");
+const doc_cli_option_1 = require("./doc-util/doc-cli-option");
+const doc_structure_1 = require("./doc-util/doc-structure");
+async function getText(shell) {
+    const rversion = (await shell.usedRVersion())?.format() ?? 'unknown';
+    const types = (0, doc_types_1.getTypesFromFolderAsMermaid)({
+        rootFolder: path_1.default.resolve('src/r-bridge/lang-4.x/tree-sitter/'),
+        files: [path_1.default.resolve('./src/config.ts'), path_1.default.resolve('./src/r-bridge/shell.ts'), path_1.default.resolve('./src/r-bridge/shell-executor.ts')],
+        typeName: 'FlowrConfigOptions',
+        inlineTypes: doc_types_1.mermaidHide
+    });
+    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'engines', rVersion: rversion })}
+
+To analyze R scripts, flowR needs to parse the R code and for that, we require a parser.
+Originally, flowR shipped with a ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)}, an asynchronous interface to the R interpreter, still available today.
+Later we extended this with the ${(0, doc_types_1.shortLink)(shell_executor_1.RShellExecutor.name, types.info)}, the synchronous counterpart to the ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)}.
+However, these interfaces are relatively slow as they require communication with an underlying R interpreter. 
+Using [tree-sitter](https://tree-sitter.github.io/tree-sitter/), with its [node bindings](https://github.com/tree-sitter/node-tree-sitter)
+and [R grammar](https://github.com/r-lib/tree-sitter-r), we can provide the ${(0, doc_types_1.shortLink)(tree_sitter_executor_1.TreeSitterExecutor.name, types.info)} which
+is synchronous, faster, and no longer needs an R installation, but requires the appropriate bindings.
+To allow users of R to freely choose their backend between the R interpreter and the tree-sitter parser,
+we provide the concept of engines. 
+
+Engines can be loaded with [flowR's configuration file](${doc_files_1.FlowrWikiBaseRef}/Interface#configuring-flowr). Additionally, they
+are exposed with some command line options (e.g., when using the docker image of flowR):
+
+- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.r-shell.disabled', false)} to disable the ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} engine
+- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.r-shell.r-path', false)} (which is the canonical version of ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'r-path')})
+- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.disabled', false)} to disable the ${(0, doc_types_1.shortLink)(tree_sitter_executor_1.TreeSitterExecutor.name, types.info)} engine
+- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.wasm-path', false)} pass the path to the wasm of the r grammar of tree-sitter (see [below](#tree-sitter))
+- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.tree-sitter-wasm-path', false)} pass the path to the wasm of tree-sitter (see [below](#tree-sitter))
+- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'default-engine', false)} to set the default engine to use
+
+<a id="tree-sitter"></a>
+## Dealing with the Tree-Sitter Engine
+
+${(0, doc_structure_1.block)({
+        type: 'WARNING',
+        content: 'As the tree-sitter engine is only for parsing, it cannot execute R code.'
+    })}
+
+In general, there is no need for you to pass custom paths using either 
+${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.wasm-path', false)} or
+${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.tree-sitter-wasm-path', false)}.
+However, you may want to experiment with the R grammar or provide a newer
+one in case that of _flowR_ is outdated. 
+
+To use a newer [R grammar](https://github.com/r-lib/tree-sitter-r),
+you first must build the new wasm file. For this you have to:
+
+1. Install the dependencies with \`npm ci\` in the tree-sitter-r repository.
+2. Build the wasm using \`tree-sitter build --wasm .\` the [tree sitter cli](https://github.com/tree-sitter/tree-sitter)
+   which should be a dev dependency.
+3. Pass the \`tree-sitter-r.wasm\` to flowR. 
+
+For tree-sitter, please rely on the [releases](https://github.com/tree-sitter/tree-sitter/releases).
+
+`;
+}
+/** if we run this script, we want a Markdown representation of the capabilities */
+if (require.main === module) {
+    (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
+    const shell = new shell_1.RShell();
+    void getText(shell).then(str => {
+        console.log(str);
+    }).finally(() => {
+        shell.close();
+    });
+}
+//# sourceMappingURL=print-engines-wiki.js.map

package/documentation/print-interface-wiki.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const shell_1 = require("../r-bridge/shell");
 const log_1 = require("../../test/functionality/_helper/log");
@@ -19,6 +22,8 @@ const flowr_main_options_1 = require("../cli/flowr-main-options");
 const doc_issue_1 = require("./doc-util/doc-issue");
 const pipeline_executor_1 = require("../core/pipeline-executor");
 const doc_structure_1 = require("./doc-util/doc-structure");
+const doc_types_1 = require("./doc-util/doc-types");
+const path_1 = __importDefault(require("path"));
 async function explainServer(shell) {
     (0, doc_data_server_messages_1.documentAllServerMessages)();
     return `
@@ -96,7 +101,7 @@ async function explainRepl(shell) {
     return `
 > [!NOTE]
 > To execute arbitrary R commands with a repl request, _flowR_ has to be started explicitly with ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'r-session-access')}.
-> Please be aware that this introduces a security risk.
+> Please be aware that this introduces a security risk and note that this relies on the [\`r-shell\` engine](${doc_files_1.FlowrWikiBaseRef}/Engines).
 
 
 Although primarily meant for users to explore, 
@@ -167,16 +172,16 @@ Within the REPL this works by running the following:
 
 ${(0, doc_code_1.codeBlock)('shell', ':query @config')}
 
-
 The following summarizes the configuration options:
 
-
 - \`ignoreSourceCalls\`: If set to \`true\`, _flowR_ will ignore source calls when analyzing the code, i.e., ignoring the inclusion of other files.
 - \`rPath\`: The path to the R executable. If not set, _flowR_ will try to find the R executable in the system's PATH.
 - \`semantics\`: allows to configure the way _flowR_ handles R, although we currently only support \`semantics/environment/overwriteBuiltIns\`. 
   You may use this to overwrite _flowR_'s handling of built-in function and even completely clear the preset definitions shipped with flowR. 
   See [Configure BuiltIn Semantics](#configure-builtin-semantics) for more information.
 - \`solver\`: allows to configure how _flowR_ resolves variables and their values (currently we support: ${Object.values(config_1.VariableResolve).map(v => `\`${v}\``).join(', ')}), as well as if pointer analysis should be active.
+- \`engines\`: allows to configure the engines used by _flowR_ to interact with R code. See the [Engines wiki page](${doc_files_1.FlowrWikiBaseRef}/Engines) for more information.
+- \`defaultEngine\`: allows to specify the default engine to use for interacting with R code. If not set, an arbitrary engine from the specified list will be used.
 
 So you can configure _flowR_ by adding a file like the following:
 
@@ -196,6 +201,7 @@ ${(0, doc_code_1.codeBlock)('json', JSON.stringify({
                 }
             }
         },
+        engines: [{ type: 'r-shell' }],
         solver: {
             variables: config_1.VariableResolve.Alias,
             pointerTracking: true
@@ -234,41 +240,45 @@ ${(0, schema_1.describeSchema)(config_1.flowrConfigFileSchema, ansi_1.markdownFo
 	`;
 }
 function explainWritingCode(shell) {
+    const types = (0, doc_types_1.getTypesFromFolderAsMermaid)({
+        rootFolder: path_1.default.resolve('./src/r-bridge/'),
+        files: [path_1.default.resolve('./src/core/pipeline-executor.ts'), path_1.default.resolve('./src/core/steps/pipeline/default-pipelines.ts')],
+        typeName: 'RShell',
+        inlineTypes: doc_types_1.mermaidHide
+    });
     return `
-
-
 _flowR_ can be used as a [module](${doc_files_1.FlowrNpmRef}) and offers several main classes and interfaces that are interesting for extension writers 
 (see the [Visual Studio Code extension](${doc_files_1.FlowrGithubBaseRef}/vscode-flowr) or the [core](${doc_files_1.FlowrWikiBaseRef}/Core) wiki page for more information).
 
-### Using the \`${shell_1.RShell.name}\` to Interact with R
+### Using the ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} to Interact with R
 
-The \`${shell_1.RShell.name}\` class allows to interface with the \`R\` ecosystem installed on the host system.
-For now, there are no (real) alternatives, although we plan on providing more flexible drop-in replacements.
+The ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} class allows interfacing with the \`R\` ecosystem installed on the host system.
+Please have a look at [flowR's engines](${doc_files_1.FlowrWikiBaseRef}/Engines) for more information on alterantives.
 
 > [!IMPORTANT]
-> Each \`${shell_1.RShell.name}\` controls a new instance of the R interpreter, make sure to call \`${shell_1.RShell.name}::${shell.close.name}()\` when you’re done.
+> Each ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} controls a new instance of the R&nbsp;interpreter, make sure to call <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.close.name}()</code> when you’re done.
 
-You can start a new "session" simply by constructing a new object with \`new ${shell_1.RShell.name}()\`.
+You can start a new "session" simply by constructing a new object with <code>new ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}()</code>.
 
-However, there are several options which may be of interest (e.g., to automatically revive the shell in case of errors or to control the name location of the R process on the system).
+However, there are several options that may be of interest (e.g., to automatically revive the shell in case of errors or to control the name location of the R process on the system).
 
-With a shell object (let's call it \`shell\`), you can execute R code by using \`${shell_1.RShell.name}::${shell.sendCommand.name}\`, 
+With a shell object (let's call it \`shell\`), you can execute R code by using <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.sendCommand.name}</code>, 
 for example \`shell.${shell.sendCommand.name}("1 + 1")\`. 
-However, this does not return anything, so if you want to collect the output of your command, use \`${shell_1.RShell.name}::${shell.sendCommandWithOutput.name}\` instead.
+However, this does not return anything, so if you want to collect the output of your command, use <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.sendCommandWithOutput.name}</code> instead.
 
-Besides that, the command \`${shell_1.RShell.name}::${shell.tryToInjectHomeLibPath.name}\` may be of interest, as it enables all libraries available on the host system.
+Besides that, the command <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.tryToInjectHomeLibPath.name}</code> may be of interest, as it enables all libraries available on the host system.
 
 ### The Pipeline Executor
 
 Once, in the beginning, _flowR_ was meant to produce a dataflow graph merely to provide *program slices*. 
-However, with continuous updates, the [dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow&20Graph) repeatedly proves to be the more interesting part.
+However, with continuous updates, the [dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph) repeatedly proves to be the more interesting part.
 With this, we restructured _flowR_'s originally *hardcoded* pipeline to be far more flexible. 
 Now, it can be theoretically extended or replaced with arbitrary steps, optional steps, and what we call 'decorations' of these steps. 
-In short, if you still "just want to slice" you can do it like this:
+In short, if you still "just want to slice" you can do it like this with the ${(0, doc_types_1.shortLink)(pipeline_executor_1.PipelineExecutor.name, types.info)}:
 
 ${(0, doc_code_1.codeBlock)('ts', `
 const slicer = new ${pipeline_executor_1.PipelineExecutor.name}(DEFAULT_SLICING_PIPELINE, {
-  shell:     new ${shell_1.RShell.name}(),
+  parser:    new ${shell_1.RShell.name}(),
   request:   ${retriever_1.requestFromInput.name}('x <- 1\\nx + 1'),
   criterion: ['2@x']
 })
@@ -281,9 +291,9 @@ const slice = await slicer.allRemainingSteps()
 <summary style='color:gray'>More Information</summary>
 
 If you compare this, with what you would have done with the old (and removed) \`SteppingSlicer\`, 
-this essentially just requires you to replace the \`SteppingSlicer\` with the \`${pipeline_executor_1.PipelineExecutor.name}\` 
-and to pass the \`DEFAULT_SLICING_PIPELINE\` as the first argument.
-The \`${pipeline_executor_1.PipelineExecutor.name}\`...
+this essentially just requires you to replace the \`SteppingSlicer\` with the ${(0, doc_types_1.shortLink)(pipeline_executor_1.PipelineExecutor.name, types.info)}
+and to pass the ${(0, doc_types_1.shortLink)('DEFAULT_SLICING_PIPELINE', types.info)} as the first argument.
+The ${(0, doc_types_1.shortLink)(pipeline_executor_1.PipelineExecutor.name, types.info)}...
 
 1. allows investigating the results of all intermediate steps
 2. Can be executed step-by-step

package/documentation/print-normalized-ast-wiki.js

@@ -24,7 +24,7 @@ async function getText(shell) {
     const now = performance.now();
     const types = (0, doc_types_1.getTypesFromFolderAsMermaid)({
         rootFolder: path_1.default.resolve('./src/r-bridge/lang-4.x/ast/model/'),
-        files: [path_1.default.resolve('./src/abstract-interpretation/normalized-ast-fold.ts')],
+        files: [path_1.default.resolve('./src/abstract-interpretation/normalized-ast-fold.ts'), path_1.default.resolve('./src/core/steps/pipeline/default-pipelines.ts')],
         typeName: 'RNode',
         inlineTypes: doc_types_1.mermaidHide
     });
@@ -77,7 +77,7 @@ ${(0, doc_code_1.codeBlock)('mermaid', types.text)}
 _The generation of the class diagram required ${(0, time_1.printAsMs)(elapsed)}._
 </details>
 
-Node types are controlled by the \`${'RType'}\` enum (see ${(0, doc_files_1.getFilePathMd)('../r-bridge/lang-4.x/ast/model/type.ts')}), 
+Node types are controlled by the ${(0, doc_types_1.shortLink)('RType', types.info)} enum (see ${(0, doc_files_1.getFilePathMd)('../r-bridge/lang-4.x/ast/model/type.ts')}), 
 which is used to distinguish between different types of nodes.
 Additionally, every AST node is generic with respect to the \`Info\` type which allows for arbitrary decorations (e.g., parent inforamtion or dataflow constraints).
 Most notably, the \`info\` field holds the \`id\` of the node, which is used to reference the node in the [dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph).
@@ -94,13 +94,13 @@ The following segments intend to give you an overview of how to work with the no
 ## How Get a Normalized AST
 
 As explained alongside the [Interface](${doc_files_1.FlowrWikiBaseRef}/Interface#the-pipeline-executor) wiki page, you can use the 
-\`${pipeline_executor_1.PipelineExecutor.name}\` to get the normalized AST. If you are only interested in the normalization,
-a pipeline like the \`DEFAULT_NORMALIZE_PIPELINE\` suffices:
+\`${pipeline_executor_1.PipelineExecutor.name}\` to get the ${(0, doc_types_1.shortLink)('NormalizedAst', types.info)}. If you are only interested in the normalization,
+a pipeline like the ${(0, doc_types_1.shortLink)('DEFAULT_NORMALIZE_PIPELINE', types.info)} suffices:
 
 ${(0, doc_code_1.codeBlock)('ts', `
 async function getAst(code: string): Promise<RNode> {
     const result = await new ${pipeline_executor_1.PipelineExecutor.name}(DEFAULT_NORMALIZE_PIPELINE, {
-        shell: new ${shell_1.RShell.name}(),
+        parser:  new ${shell_1.RShell.name}(),
         request: ${retriever_1.requestFromInput.name}(code.trim())
     }).allRemainingSteps();
     return result.normalize.ast;

package/documentation/print-query-wiki.js

@@ -26,6 +26,9 @@ const doc_issue_1 = require("./doc-util/doc-issue");
 const location_map_query_executor_1 = require("../queries/catalog/location-map-query/location-map-query-executor");
 const identify_link_to_last_call_relation_1 = require("../queries/catalog/call-context-query/identify-link-to-last-call-relation");
 const config_query_executor_1 = require("../queries/catalog/config-query/config-query-executor");
+const search_query_executor_1 = require("../queries/catalog/search-query/search-query-executor");
+const flowr_search_builder_1 = require("../search/flowr-search-builder");
+const vertex_1 = require("../dataflow/graph/vertex");
 (0, doc_query_1.registerQueryDocumentation)('call-context', {
     name: 'Call-Context Query',
     type: 'active',
@@ -191,6 +194,25 @@ ${await (0, doc_query_1.showQuery)(shell, example_query_code_1.exampleQueryCode,
 		`;
     }
 });
+(0, doc_query_1.registerQueryDocumentation)('search', {
+    name: 'Search Query',
+    type: 'active',
+    shortDescription: 'Provides access to flowR\'s search API',
+    functionName: search_query_executor_1.executeSearch.name,
+    functionFile: '../queries/catalog/search-query/search-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'x + 1';
+        return `
+With this query you can use the [Search API](${doc_files_1.FlowrWikiBaseRef}/Search%20API) to conduct searches on the flowR analysis result. 
+
+Using the example code \`${exampleCode}\`, the following query returns all uses of 'x' in the code:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'search',
+                search: flowr_search_builder_1.Q.var('x').filter(vertex_1.VertexType.Use).build()
+            }], { showCode: true, collapseQuery: false })}
+		`;
+    }
+});
 (0, doc_query_1.registerQueryDocumentation)('id-map', {
     name: 'Id-Map Query',
     type: 'active',

package/documentation/print-search-wiki.d.ts

@@ -0,0 +1 @@
+export {};

package/documentation/print-search-wiki.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const shell_1 = require("../r-bridge/shell");
+const log_1 = require("../../test/functionality/_helper/log");
+const doc_files_1 = require("./doc-util/doc-files");
+const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
+const doc_search_1 = require("./doc-util/doc-search");
+const flowr_search_builder_1 = require("../search/flowr-search-builder");
+const vertex_1 = require("../dataflow/graph/vertex");
+const doc_types_1 = require("./doc-util/doc-types");
+const path_1 = __importDefault(require("path"));
+async function getText(shell) {
+    const rversion = (await shell.usedRVersion())?.format() ?? 'unknown';
+    const types = (0, doc_types_1.getTypesFromFolderAsMermaid)({
+        rootFolder: path_1.default.resolve('./src/search/'),
+        typeName: 'FlowrSearchGenerator',
+        inlineTypes: doc_types_1.mermaidHide
+    });
+    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'search API', rVersion: rversion })}
+
+This page briefly summarizes flowR's search API which provides a set of functions to search for nodes in the [Dataflow Graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph) and the 
+[Normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized%20AST) of a given R code (the search will always consider both, with respect to your search query).
+Please see the [Interface](${doc_files_1.FlowrWikiBaseRef}/Interface) wiki page for more information on how to access this API.
+Within code, you can execute a search using the ${(0, doc_types_1.shortLink)('runSearch', types.info)} function.
+
+For an initial motivation, let's have a look at the following example:
+
+${await (0, doc_search_1.showSearch)(shell, 'x <- x * x', flowr_search_builder_1.Q.var('x'))}
+
+This returns all references to the variable \`x\` in the code.
+However, the search API is not limited to simple variable references and can do much more.
+
+For example, let's have every definition of \`x\` in the code but the first one:
+
+${await (0, doc_search_1.showSearch)(shell, 'x <- x * x\nprint(x)\nx <- y <- 3\nprint(x)\nx <- 2', flowr_search_builder_1.Q.var('x').filter(vertex_1.VertexType.VariableDefinition).skip(1))}
+
+In summary, every search has two parts. It is initialized with a _generator_ (such as \`Q.var('x')\`)
+and can be further refined with _transformers_ or _modifiers_.
+Such queries can be constructed starting from the ${(0, doc_types_1.shortLink)('Q', types.info)} object (backed by ${(0, doc_types_1.shortLink)('FlowrSearchGenerator', types.info)}) and
+are fully serializable so you can use them when communicating with the [Query API](${doc_files_1.FlowrWikiBaseRef}/Query%20API).
+
+We offer the following generators:
+
+${Object.keys(flowr_search_builder_1.Q).sort().map(key => `- ${(0, doc_types_1.shortLink)(`FlowrSearchGenerator::${key}`, types.info)}\\\n${(0, doc_types_1.getDocumentationForType)(`FlowrSearchGenerator::${key}`, types.info)}`).join('\n')}
+
+Likewise, we have a palette of _transformers_ and _modifiers_:
+
+${
+    /* let's iterate over all methods of FlowrSearchBuilder */
+    Object.getOwnPropertyNames(Object.getPrototypeOf(new flowr_search_builder_1.FlowrSearchBuilder(undefined)))
+        .filter(n => n !== 'constructor').sort().map(key => `- ${(0, doc_types_1.shortLink)(`FlowrSearchBuilder::${key}`, types.info)}\\\n${(0, doc_types_1.getDocumentationForType)(`FlowrSearchBuilder::${key}`, types.info)}`).join('\n')}
+
+Every search (and consequently the search pipeline) works with an array of ${(0, doc_types_1.shortLink)('FlowrSearchElement', types.info)} (neatly wrapped in ${(0, doc_types_1.shortLink)('FlowrSearchElements', types.info)}).
+Hence, even operations such as \`.first\` or \`.last\` return an array of elements (albeit with a single or no element).
+The search API does its best to stay typesafe wrt. to the return type and the transformers in use. 
+In addition, it offers optimizer passes to optimize the search pipeline before execution.
+They are executed with \`.build\` which may happen automatically, whenever you want to run a search using ${(0, doc_types_1.shortLink)('runSearch', types.info)}.
+
+`;
+}
+/** if we run this script, we want a Markdown representation of the capabilities */
+if (require.main === module) {
+    (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
+    const shell = new shell_1.RShell();
+    void getText(shell).then(str => {
+        console.log(str);
+    }).finally(() => {
+        shell.close();
+    });
+}
+//# sourceMappingURL=print-search-wiki.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/flowr",
-  "version": "2.1.11",
+  "version": "2.2.0",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -21,17 +21,21 @@
     "stats-helper": "ts-node src/cli/statistics-helper-app.ts",
     "slicer": "ts-node src/cli/slicer-app.ts",
     "benchmark-helper": "ts-node src/cli/benchmark-helper-app.ts",
-    "benchmark": "npm run build && node dist/src/cli/benchmark-app.js",
+    "benchmark": "npm run build && npm run build:copy-wasm && node dist/src/cli/benchmark-app.js",
     "summarizer": "ts-node src/cli/summarizer-app.ts",
     "export-quads": "ts-node src/cli/export-quads-app.ts",
     "capabilities-markdown": "ts-node src/documentation/print-capabilities-markdown.ts",
     "wiki:df-graph": "ts-node src/documentation/print-dataflow-graph-wiki.ts",
     "wiki:normalized-ast": "ts-node src/documentation/print-normalized-ast-wiki.ts",
     "wiki:query-api": "ts-node src/documentation/print-query-wiki.ts",
+    "wiki:engines": "ts-node src/documentation/print-engines-wiki.ts",
+    "wiki:search-api": "ts-node src/documentation/print-search-wiki.ts",
     "wiki:linting-and-testing": "ts-node src/documentation/print-linting-and-testing-wiki.ts",
     "wiki:interface": "ts-node src/documentation/print-interface-wiki.ts",
     "build": "tsc --project .",
-    "build:bundle-flowr": "npm run build && esbuild --bundle dist/src/cli/flowr.js --platform=node --bundle --minify --target=node22 --outfile=dist/src/cli/flowr.min.js",
+    "build:bundle-flowr": "npm run build && esbuild --bundle dist/src/cli/flowr.js --platform=node --bundle --minify --target=node22 --outfile=dist/src/cli/flowr.min.js && npm run build:copy-wasm-min",
+    "build:copy-wasm": "cp src/r-bridge/lang-4.x/tree-sitter/tree-sitter-r.wasm dist/src/r-bridge/lang-4.x/tree-sitter/ && cp src/r-bridge/lang-4.x/tree-sitter/tree-sitter.wasm dist/src/r-bridge/lang-4.x/tree-sitter/",
+    "build:copy-wasm-min": "cp src/r-bridge/lang-4.x/tree-sitter/tree-sitter-r.wasm dist/src/cli && cp src/r-bridge/lang-4.x/tree-sitter/tree-sitter.wasm dist/src/cli",
     "lint-local": "npx eslint --version && npx eslint src/ test/ --rule \"no-warning-comments: off\"",
     "lint": "npm run license-compat -- --summary && npx eslint --version && npx eslint src/ test/",
     "license-compat": "license-checker --onlyAllow 'MIT;MIT OR X11;GPLv2;LGPL;GNUGPL;ISC;Apache-2.0;FreeBSD;BSD-2-Clause;clearbsd;ModifiedBSD;BSD-3-Clause;Python-2.0;Unlicense;WTFPL;BlueOak-1.0.0;CC-BY-4.0;CC-BY-3.0;CC0-1.0;0BSD'",
@@ -39,7 +43,7 @@
     "test": "vitest --exclude \"test/system-tests/**\" --config test/vitest.config.mts",
     "test:system": "vitest --dir test/system-tests --config test/system-tests/vitest.config.mts",
     "test:coverage": "npm run test -- --coverage",
-    "performance-test": "func() { cd test/performance/ && bash run-all-suites.sh $1 $2 $3; cd ../../; }; func",
+    "performance-test": "func() { cd test/performance/ && bash run-all-suites.sh $1 $2 $3 $4; cd ../../; }; func",
     "test-full": "npm run test:coverage -- --no-watch -- --make-summary --test-installation",
     "detect-circular-deps": "npx madge  --extensions ts,tsx --circular src/",
     "checkup": "npm run flowr -- --execute \":version\" && npm run lint && npm run test-full -- --allowOnly=false && npm run test:system -- --no-watch && docker build -t test-flowr -f scripts/Dockerfile . && npm run doc && npm-run-all wiki:*"
@@ -162,7 +166,7 @@
         "npm run lint",
         "npm run test-full"
       ],
-      "after:bump": "npm run build",
+      "after:bump": "npm run build && npm run build:copy-wasm",
       "after:git:release": "echo After git push, before github release",
       "after:release": "echo Successfully released ${name} v${version} to ${repo.repository}."
     },
@@ -219,6 +223,7 @@
     "tmp": "^0.2.3",
     "ts-essentials": "^10.0.2",
     "tslog": "^4.9.3",
+    "web-tree-sitter": "^0.24.7",
     "ws": "^8.18.0",
     "xpath-ts2": "^1.4.2"
   }

package/queries/base-query-format.d.ts

@@ -1,5 +1,5 @@
 import type { NormalizedAst } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
-import type { DataflowGraph } from '../dataflow/graph/graph';
+import type { DataflowInformation } from '../dataflow/info';
 export interface BaseQueryFormat {
     /** used to select the query type :) */
     readonly type: string;
@@ -13,5 +13,5 @@ export interface BaseQueryResult {
 }
 export interface BasicQueryData {
     readonly ast: NormalizedAst;
-    readonly graph: DataflowGraph;
+    readonly dataflow: DataflowInformation;
 }

package/queries/catalog/call-context-query/call-context-query-executor.d.ts

@@ -9,4 +9,4 @@ import type { BasicQueryData } from '../../base-query-format';
  *    This happens during the main resolution!
  * 4. Attach `linkTo` calls to the respective calls.
  */
-export declare function executeCallContextQueries({ graph, ast }: BasicQueryData, queries: readonly CallContextQuery[]): CallContextQueryResult;
+export declare function executeCallContextQueries({ dataflow: { graph }, ast }: BasicQueryData, queries: readonly CallContextQuery[]): CallContextQueryResult;

package/queries/catalog/call-context-query/call-context-query-executor.js

@@ -158,7 +158,7 @@ function doesFilepathMatch(file, filter) {
  *    This happens during the main resolution!
  * 4. Attach `linkTo` calls to the respective calls.
  */
-function executeCallContextQueries({ graph, ast }, queries) {
+function executeCallContextQueries({ dataflow: { graph }, ast }, queries) {
     /* omit performance page load */
     const now = Date.now();
     /* the node id and call targets if present */

package/queries/catalog/cluster-query/cluster-query-executor.d.ts

@@ -1,3 +1,3 @@
 import type { DataflowClusterQuery, DataflowClusterQueryResult } from './cluster-query-format';
 import type { BasicQueryData } from '../../base-query-format';
-export declare function executeDataflowClusterQuery({ graph }: BasicQueryData, queries: readonly DataflowClusterQuery[]): DataflowClusterQueryResult;
+export declare function executeDataflowClusterQuery({ dataflow: { graph } }: BasicQueryData, queries: readonly DataflowClusterQuery[]): DataflowClusterQueryResult;

package/queries/catalog/cluster-query/cluster-query-executor.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeDataflowClusterQuery = executeDataflowClusterQuery;
 const log_1 = require("../../../util/log");
 const cluster_1 = require("../../../dataflow/cluster");
-function executeDataflowClusterQuery({ graph }, queries) {
+function executeDataflowClusterQuery({ dataflow: { graph } }, queries) {
     if (queries.length !== 1) {
         log_1.log.warn('The dataflow cluster query expects only up to one query, but got', queries.length);
     }