@eagleoutice/flowr 2.1.10 → 2.1.12

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

@@ -10,6 +10,8 @@ exports.getTypePathLink = getTypePathLink;
 exports.getTypesFromFolderAsMermaid = getTypesFromFolderAsMermaid;
 exports.implSnippet = implSnippet;
 exports.printHierarchy = printHierarchy;
+exports.shortLink = shortLink;
+exports.getDocumentationForType = getDocumentationForType;
 const typescript_1 = __importDefault(require("typescript"));
 const assert_1 = require("../../util/assert");
 const doc_files_1 = require("./doc-files");
@@ -18,6 +20,7 @@ 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");
 function getSourceFiles(fileNames) {
     try {
         const program = typescript_1.default.createProgram(fileNames, { target: typescript_1.default.ScriptTarget.ESNext });
@@ -171,6 +174,42 @@ function collectHierarchyInformation(sourceFiles, options) {
                 }),
             });
         }
+        else if (typescript_1.default.isVariableDeclaration(node) || typescript_1.default.isExportDeclaration(node) || typescript_1.default.isExportAssignment(node) || typescript_1.default.isDeclarationStatement(node)) {
+            const name = node.name?.getText(sourceFile) ?? '';
+            const comments = getTextualComments(node);
+            hierarchyList.push({
+                name: dropGenericsFromType(name),
+                node,
+                kind: 'variable',
+                extends: [],
+                comments,
+                generics: [],
+                filePath: sourceFile.fileName,
+                lineNumber: getStartLine(node, sourceFile),
+            });
+        }
+        else if (typescript_1.default.isPropertyAssignment(node) || typescript_1.default.isPropertyDeclaration(node) || typescript_1.default.isPropertySignature(node)
+            || typescript_1.default.isMethodDeclaration(node) || typescript_1.default.isMethodSignature(node) || typescript_1.default.isFunctionDeclaration(node)) {
+            const name = node.name?.getText(sourceFile) ?? '';
+            // get the name of the object/enclosing type
+            let parent = node.parent;
+            while (typeof parent === 'object' && parent !== undefined && !('name' in parent)) {
+                parent = parent.parent;
+            }
+            if (typeof parent === 'object' && 'name' in parent) {
+                const comments = getTextualComments(node);
+                hierarchyList.push({
+                    name: dropGenericsFromType(name),
+                    node,
+                    kind: 'variable',
+                    extends: [parent.name?.getText(sourceFile) ?? ''],
+                    comments,
+                    generics: [],
+                    filePath: sourceFile.fileName,
+                    lineNumber: getStartLine(node, sourceFile),
+                });
+            }
+        }
         typescript_1.default.forEachChild(node, child => visit(child, sourceFile));
     };
     sourceFiles.forEach(sourceFile => {
@@ -266,7 +305,7 @@ function getTypesFromFolderAsMermaid(options) {
     }
     return getTypesFromFileAsMermaid(files, options);
 }
-function implSnippet(node, program, nesting = 0) {
+function implSnippet(node, program, showName = true, nesting = 0) {
     (0, assert_1.guard)(node !== undefined, 'Node must be defined => invalid change of type name?');
     const indent = ' '.repeat(nesting * 2);
     const bold = node.kind === 'interface' || node.kind === 'enum' ? '**' : '';
@@ -274,7 +313,8 @@ function implSnippet(node, program, nesting = 0) {
     let text = node.comments?.join('\n') ?? '';
     const code = node.node.getFullText(program.getSourceFile(node.node.getSourceFile().fileName));
     text += `\n<details><summary style="color:gray">Defined at <a href="${getTypePathLink(node)}">${getTypePathLink(node, '.')}</a></summary>\n\n${(0, doc_code_1.codeBlock)('ts', code)}\n\n</details>\n`;
-    return `${indent} * ${bold}[${node.name}](${getTypePathLink(node)})${bold} ${sep}${indent}   ${text.replaceAll('\t', '    ').split(/\n/g).join(`\n${indent}   `)}`;
+    const init = showName ? ` * ${bold}[${node.name}](${getTypePathLink(node)})${bold} ${sep}${indent}` : '';
+    return ` ${indent} ${showName ? init : ''} ${text.replaceAll('\t', '    ').split(/\n/g).join(`\n${indent}   `)}`;
 }
 exports.mermaidHide = ['Leaf', 'Location', 'Namespace', 'Base', 'WithChildren', 'Partial', 'RAccessBase'];
 function printHierarchy({ program, hierarchy, root, collapseFromNesting = 1, initialNesting = 0, maxDepth = 20 }) {
@@ -285,7 +325,7 @@ function printHierarchy({ program, hierarchy, root, collapseFromNesting = 1, ini
     if (!node) {
         return '';
     }
-    const thisLine = implSnippet(node, program, initialNesting);
+    const thisLine = implSnippet(node, program, true, initialNesting);
     const result = [];
     for (const baseType of node.extends) {
         if (exports.mermaidHide.includes(baseType)) {
@@ -302,4 +342,42 @@ function printHierarchy({ program, hierarchy, root, collapseFromNesting = 1, ini
         return thisLine + (out ? '\n' + out : '');
     }
 }
+function retrieveNode(name, hierarchy) {
+    let container = undefined;
+    if (name.includes('::')) {
+        [container, name] = name.split('::');
+    }
+    const node = hierarchy.find(e => e.name === name);
+    if (!node) {
+        return undefined;
+    }
+    else if (container && !node.extends.includes(container)) {
+        return undefined;
+    }
+    return [container, name, node];
+}
+/**
+ * Create a short link to a type in the documentation
+ * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g. `MyContainer::MyType` (this works with function nestings too)
+ * @param hierarchy - The hierarchy of types to search in
+ * @param codeStyle - Whether to use code style for the link
+ */
+function shortLink(name, hierarchy, codeStyle = true) {
+    const res = retrieveNode(name, hierarchy);
+    if (!res) {
+        return '';
+    }
+    const [pkg, mainName, node] = res;
+    const comments = node.comments?.join('\n').replace(/\\?\n|```[a-zA-Z]*|\s\s*/g, ' ').replace(/<\/?code>|/g, '') ?? '';
+    return `[${codeStyle ? '<code>' : ''}${(node.comments?.length ?? 0) > 0 ?
+        (0, html_hover_over_1.textWithTooltip)(pkg ? `${pkg}::<b>${mainName}</b>` : mainName, (0, mermaid_1.escapeMarkdown)(comments.length > 400 ? comments.slice(0, 400) + '...' : comments)) : node.name}${codeStyle ? '</code>' : ''}](${getTypePathLink(node)})`;
+}
+function getDocumentationForType(name, hierarchy) {
+    const res = retrieveNode(name, hierarchy);
+    if (!res) {
+        return '';
+    }
+    const [, , node] = res;
+    return node.comments?.join('\n') ?? '';
+}
 //# sourceMappingURL=doc-types.js.map

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

@@ -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-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 `
@@ -162,6 +167,11 @@ function explainConfigFile() {
 When running _flowR_, you may want to specify some behaviors with a dedicated configuration file. 
 By default, flowR looks for a file named \`${flowr_main_options_1.defaultConfigFile}\` in the current working directory (or any higher directory). 
 You can also specify a different file with ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'config-file')} or pass the configuration inline using ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'config-json')}.
+To inspect the current configuration, you can run flowr with the ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'verbose')} flag, or use the \`config\` [Query](${doc_files_1.FlowrWikiBaseRef}/Query%20API).
+Within the REPL this works by running the following:
+
+${(0, doc_code_1.codeBlock)('shell', ':query @config')}
+
 
 The following summarizes the configuration options:
 
@@ -209,8 +219,8 @@ ${(0, doc_code_1.codeBlock)('json', JSON.stringify({
 - \`loadDefaults\` (boolean, initially \`true\`): If set to \`true\`, the default built-in definitions are loaded before applying the custom definitions. Setting this flag to \`false\` explicitly disables the loading of the default definitions.
 - \`definitions\` (array, initially empty): Allows to overwrite or define new built-in elements. Each object within must have a \`type\` which is one of the below. Furthermore, they may define a string array of \`names\` which specifies the identifiers to bind the definitions to. You may use \`assumePrimitive\` to specify whether _flowR_ should assume that this is a primitive non-library definition (so you probably just do not want to specify the key).
 
-  | Type          | Description                                                                                                                                                                                                                                                                                              | Example                                                                                                    |
-  | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+  | 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: 'builtin: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: ['[', '[['] }\` |
@@ -229,37 +239,43 @@ ${(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\`&nbsp;ecosystem installed on the host system.
+The ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} class allows interfacing with the \`R\`&nbsp;ecosystem installed on the host system.
 For now, there are no (real) alternatives, although we plan on providing more flexible drop-in replacements.
 
 > [!IMPORTANT]
-> Each \`${shell_1.RShell.name}\` controls a new instance of the R&nbsp;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, {
@@ -276,9 +292,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,8 +94,8 @@ 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> {

package/documentation/print-query-wiki.js

@@ -25,6 +25,10 @@ const doc_cli_option_1 = require("./doc-util/doc-cli-option");
 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',
@@ -190,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',
@@ -208,6 +231,18 @@ ${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
 		`;
     }
 });
+(0, doc_query_1.registerQueryDocumentation)('config', {
+    name: 'Config Query',
+    type: 'active',
+    shortDescription: 'Returns the current configuration of flowR.',
+    functionName: config_query_executor_1.executeConfigQuery.name,
+    functionFile: '../queries/catalog/config-query/config-query-format.ts',
+    // eslint-disable-next-line @typescript-eslint/require-await -- no need for async here
+    buildExplanation: async () => {
+        return `
+This query provides access to the current configuration of the flowR instance. See the [Interface](${doc_files_1.FlowrWikiBaseRef}/Interface) wiki page for more information on what the configuration represents.`;
+    }
+});
 (0, doc_query_1.registerQueryDocumentation)('compound', {
     name: 'Compound Query',
     type: 'virtual',

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.10",
+  "version": "2.1.12",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -28,6 +28,7 @@
     "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: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 .",

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);
     }

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

@@ -0,0 +1,3 @@
+import type { ConfigQuery, ConfigQueryResult } from './config-query-format';
+import type { BasicQueryData } from '../../base-query-format';
+export declare function executeConfigQuery(_: BasicQueryData, queries: readonly ConfigQuery[]): ConfigQueryResult;

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeConfigQuery = executeConfigQuery;
+const log_1 = require("../../../util/log");
+const config_1 = require("../../../config");
+function executeConfigQuery(_, queries) {
+    if (queries.length !== 1) {
+        log_1.log.warn('Config query expects only up to one query, but got', queries.length);
+    }
+    return {
+        '.meta': {
+            /* there is no sense in measuring a get */
+            timing: 0
+        },
+        config: (0, config_1.getConfig)()
+    };
+}
+//# sourceMappingURL=config-query-executor.js.map

package/queries/catalog/config-query/config-query-format.d.ts

@@ -0,0 +1,16 @@
+import type { BaseQueryFormat, BaseQueryResult } from '../../base-query-format';
+import { executeConfigQuery } from './config-query-executor';
+import { type OutputFormatter } from '../../../util/ansi';
+import Joi from 'joi';
+import type { FlowrConfigOptions } from '../../../config';
+export interface ConfigQuery extends BaseQueryFormat {
+    readonly type: 'config';
+}
+export interface ConfigQueryResult extends BaseQueryResult {
+    readonly config: FlowrConfigOptions;
+}
+export declare const ConfigQueryDefinition: {
+    readonly executor: typeof executeConfigQuery;
+    readonly asciiSummarizer: (formatter: OutputFormatter, _processed: unknown, queryResults: BaseQueryResult, result: string[]) => boolean;
+    readonly schema: Joi.ObjectSchema<any>;
+};

package/queries/catalog/config-query/config-query-format.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigQueryDefinition = void 0;
+const config_query_executor_1 = require("./config-query-executor");
+const ansi_1 = require("../../../util/ansi");
+const time_1 = require("../../../util/time");
+const joi_1 = __importDefault(require("joi"));
+const json_1 = require("../../../util/json");
+exports.ConfigQueryDefinition = {
+    executor: config_query_executor_1.executeConfigQuery,
+    asciiSummarizer: (formatter, _processed, queryResults, result) => {
+        const out = queryResults;
+        result.push(`Query: ${(0, ansi_1.bold)('config', formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
+        result.push(`   ╰ Config:\n${JSON.stringify(out.config, json_1.jsonReplacer, 4)}`);
+        return true;
+    },
+    schema: joi_1.default.object({
+        type: joi_1.default.string().valid('config').required().description('The type of the query.'),
+    }).description('The config query retrieves the current configuration of the flowR instance.')
+};
+//# sourceMappingURL=config-query-format.js.map

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

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

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

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

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

@@ -83,7 +83,7 @@ function makeCallContextQuery(functions, kind) {
 }
 function getResults(data, results, kind, functions, makeInfo, additionalAllowedTypes) {
     return Object.entries(results?.kinds[kind]?.subkinds ?? {}).flatMap(([name, results]) => results.flatMap(({ id, linkedIds }) => {
-        const vertex = data.graph.getVertex(id);
+        const vertex = data.dataflow.graph.getVertex(id);
         const info = functions.find(f => f.name === name);
         let index = info.argIdx;
         if (info.argName) {
@@ -99,7 +99,7 @@ function getResults(data, results, kind, functions, makeInfo, additionalAllowedT
         return args.flatMap(a => (0, objects_1.compactRecord)(makeInfo(id, vertex, a, linkedIds)));
     })).filter(assert_1.isNotUndefined) ?? [];
 }
-function getArgumentValue({ graph }, vertex, argumentIndex, additionalAllowedTypes) {
+function getArgumentValue({ dataflow: { graph } }, vertex, argumentIndex, additionalAllowedTypes) {
     if (vertex) {
         if (argumentIndex === 'unnamed') {
             // return all unnamed arguments

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

@@ -1,3 +1,3 @@
 import type { LineageQuery, LineageQueryResult } from './lineage-query-format';
 import type { BasicQueryData } from '../../base-query-format';
-export declare function executeLineageQuery({ graph, ast }: BasicQueryData, queries: readonly LineageQuery[]): LineageQueryResult;
+export declare function executeLineageQuery({ dataflow: { graph }, ast }: BasicQueryData, queries: readonly LineageQuery[]): LineageQueryResult;

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

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeLineageQuery = executeLineageQuery;
 const log_1 = require("../../../util/log");
 const repl_lineage_1 = require("../../../cli/repl/commands/repl-lineage");
-function executeLineageQuery({ graph, ast }, queries) {
+function executeLineageQuery({ dataflow: { graph }, ast }, queries) {
     const start = Date.now();
     const result = {};
     for (const { criterion } of queries) {

package/queries/catalog/location-map-query/location-map-query-format.js

@@ -19,6 +19,6 @@ exports.LocationMapQueryDefinition = {
     },
     schema: joi_1.default.object({
         type: joi_1.default.string().valid('location-map').required().description('The type of the query.'),
-    }).description('The id map query retrieves the location of every id in the ast.')
+    }).description('The location map query retrieves the location of every id in the ast.')
 };
 //# sourceMappingURL=location-map-query-format.js.map

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

@@ -0,0 +1,3 @@
+import type { BasicQueryData } from '../../base-query-format';
+import type { SearchQuery, SearchQueryResult } from './search-query-format';
+export declare function executeSearch({ ast, dataflow }: BasicQueryData, queries: readonly SearchQuery[]): SearchQueryResult;