@eagleoutice/flowr 2.1.1 → 2.1.2

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

@@ -37,14 +37,19 @@ function dropGenericsFromType(type) {
     return type;
 }
 function removeCommentSymbols(comment) {
-    return comment.replace(/^\/\*\*?/, '').replace(/\*\/$/, '').replace(/^\s*\*/, '').trim();
+    return comment
+        // remove '/** \n * \n */...
+        .replace(/^\/\*\*?/gm, '').replace(/^\s*\*\s*/gm, '').replace(/\*\/$/gm, '').replace(/^\s*\*/gm, '')
+        /* replace {@key foo|bar} with `bar` and {@key foo} with `foo` */
+        .replace(/\{@[a-zA-Z]+ ([^}]+\|)?(?<name>[^}]+)}/gm, '<code>$<name></code>')
+        .trim();
 }
 function getTextualComments(node) {
     const comments = typescript_1.default.getJSDocCommentsAndTags(node);
     const out = [];
     for (const { comment } of comments) {
         if (typeof comment === 'string') {
-            out.push(comment);
+            out.push(removeCommentSymbols(comment));
         }
         else if (comment !== undefined) {
             for (const c of comment) {
@@ -62,6 +67,7 @@ function getType(node, typeChecker) {
     const tryDirect = typeChecker.getTypeAtLocation(node);
     return tryDirect ? typeChecker.typeToString(tryDirect) : 'unknown';
 }
+const defaultSkip = ['Pick', 'Partial', 'Required', 'Readonly', 'Omit', 'DeepPartial', 'DeepReadonly', 'DeepWritable', 'StrictOmit'];
 function followTypeReference(type, sourceFile) {
     const node = type.typeName;
     if (typescript_1.default.isQualifiedName(node)) {
@@ -69,10 +75,11 @@ function followTypeReference(type, sourceFile) {
     }
     const args = type.typeArguments?.map(arg => arg.getText(sourceFile)) ?? [];
     const nodeLexeme = node.getText(sourceFile) ?? '';
-    if (['Pick', 'Partial', 'Required', 'Readonly', 'Omit'].map(s => nodeLexeme.startsWith(s))) {
-        return args;
+    const baseLexeme = type.getText(sourceFile) ?? '';
+    if (defaultSkip.map(s => nodeLexeme.startsWith(s))) {
+        return [baseLexeme, ...args];
     }
-    return [nodeLexeme, ...args];
+    return [nodeLexeme, baseLexeme, ...args];
 }
 function collectHierarchyInformation(sourceFiles, options) {
     const hierarchyList = [];
@@ -112,7 +119,7 @@ function collectHierarchyInformation(sourceFiles, options) {
                     .map(dropGenericsFromType);
             }
             else if (typescript_1.default.isTypeReferenceNode(node.type)) {
-                baseTypes = [...followTypeReference(node.type, sourceFile)];
+                baseTypes = [...followTypeReference(node.type, sourceFile)].map(dropGenericsFromType);
             }
             const generics = node.typeParameters?.map(param => param.getText(sourceFile) ?? '') ?? [];
             hierarchyList.push({
@@ -129,7 +136,7 @@ function collectHierarchyInformation(sourceFiles, options) {
         else if (typescript_1.default.isEnumDeclaration(node)) {
             const enumName = node.name?.getText(sourceFile) ?? '';
             hierarchyList.push({
-                name: enumName,
+                name: dropGenericsFromType(enumName),
                 node,
                 kind: 'enum',
                 extends: [],
@@ -178,9 +185,10 @@ function generateMermaidClassDiagram(hierarchyList, rootName, options, visited =
         }
     }
     collect.nodeLines.push(`click ${node.name} href "${getTypePathLink(node)}" "${(0, mermaid_1.escapeMarkdown)(node.comments?.join('; ').replace(/\n/g, ' ') ?? '')}"`);
+    const inline = [...options.inlineTypes ?? [], ...defaultSkip];
     if (node.extends.length > 0) {
         for (const baseType of node.extends) {
-            if (options.inlineTypes?.includes(baseType)) {
+            if (inline.includes(baseType)) {
                 const info = hierarchyList.find(h => h.name === baseType);
                 for (const property of info?.properties ?? []) {
                     if (!writtenProperties.has(property)) {
@@ -191,10 +199,10 @@ function generateMermaidClassDiagram(hierarchyList, rootName, options, visited =
             }
             else {
                 if (node.kind === 'type' || hierarchyList.find(h => h.name === baseType)?.kind === 'type') {
-                    collect.edgeLines.push(`${baseType} .. ${node.name}`);
+                    collect.edgeLines.push(`${dropGenericsFromType(baseType)} .. ${node.name}`);
                 }
                 else {
-                    collect.edgeLines.push(`${baseType} <|-- ${node.name}`);
+                    collect.edgeLines.push(`${dropGenericsFromType(baseType)} <|-- ${node.name}`);
                 }
                 const { nodeLines, edgeLines } = generateMermaidClassDiagram(hierarchyList, baseType, options, visited);
                 collect.nodeLines.push(...nodeLines);
@@ -243,7 +251,7 @@ function implSnippet(node, program, nesting = 0) {
     const bold = node.kind === 'interface' || node.kind === 'enum' ? '**' : '';
     const sep = node.comments ? '  \n' : '\n';
     let text = node.comments?.join('\n') ?? '';
-    const code = node.node.getText(program.getSourceFile(node.node.getSourceFile().fileName));
+    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}   `)}`;
 }

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

@@ -615,6 +615,13 @@ What to do if you encounter this vertex?
 
 This depends on your analysis. To handle many real-world sources correctly you are probably fine with just ignoring it.
 Yet, you may choose to follow these references for other queries. For now, _flowR's_ support for non-standard evaluation is limited.
+
+Besides the obvious quotation there are other cases in which _flowR_ may choose to create a ${linkEdgeName(edge_1.EdgeType.NonStandardEvaluation)} edge, there are
+some that may appear to be counter-intuitive. For example, a for-loop body, as in the following example.
+
+${(0, doc_structure_1.details)('Example: For-Loop Body', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'for(i in v) b', { mark: new Set([2, '4->2']) }))}	
+${(0, doc_structure_1.details)('Example: While-Loop Body', await (0, doc_dfg_1.printDfGraphForCode)(shell, 'while(TRUE) b', { mark: new Set([1, '3->1']) }))}	
+
 				`
             })}
 `,
@@ -674,7 +681,9 @@ Additionally, you may be interested in the set of [Unknown Side Effects](#unknow
 > [!TIP]
 > If you want to investigate the dataflow graph,
 > you can either use the [Visual Studio Code extension](${doc_files_1.FlowrGithubBaseRef}/vscode-flowr) or the ${(0, doc_cli_option_1.getReplCommand)('dataflow*')}
-> command in the REPL (see the [Interface wiki page](${doc_files_1.FlowrWikiBaseRef}/Interface) for more information).
+> command in the REPL (see the [Interface wiki page](${doc_files_1.FlowrWikiBaseRef}/Interface) for more information). When using _flowR_ as a library, you may use the functions in ${(0, doc_files_1.getFilePathMd)('../util/mermaid/dfg.ts')}.
+> 
+> If you receive a dataflow graph in its serialized form (e.g., by talking to a [_flowR_ server](${doc_files_1.FlowrWikiBaseRef}/Interface)), you can use \`${graph_1.DataflowGraph.name}::${graph_1.DataflowGraph.fromJson.name}\` to retrieve the graph from the JSON representation.
 
 ${await (0, doc_dfg_1.printDfGraphForCode)(shell, 'x <- 3\ny <- x + 1\ny')}
 

package/documentation/print-interface-wiki.js

@@ -19,7 +19,7 @@ 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");
 async function explainServer(shell) {
-    (0, doc_data_server_messages_1.documentAllMessages)();
+    (0, doc_data_server_messages_1.documentAllServerMessages)();
     return `
 As explained in the [Overview](${doc_files_1.FlowrWikiBaseRef}/Overview), you can simply run the [TCP](https://de.wikipedia.org/wiki/Transmission_Control_Protocol)&nbsp;server by adding the ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'server', true)} flag (and, due to the interactive mode, exit with the conventional <kbd>CTRL</kbd>+<kbd>C</kbd>).
 Currently, every connection is handled by the same underlying \`${shell_1.RShell.name}\` - so the server is not designed to handle many clients at a time.

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

@@ -11,8 +11,8 @@ const doc_normalized_ast_1 = require("./doc-util/doc-normalized-ast");
 const doc_types_1 = require("./doc-util/doc-types");
 const path_1 = __importDefault(require("path"));
 const doc_files_1 = require("./doc-util/doc-files");
-const doc_ms_1 = require("./doc-util/doc-ms");
 const doc_cli_option_1 = require("./doc-util/doc-cli-option");
+const time_1 = require("../util/time");
 async function getText(shell) {
     const rversion = (await shell.usedRVersion())?.format() ?? 'unknown';
     const now = performance.now();
@@ -67,7 +67,7 @@ Grayed-out parts are used for structuring the AST, grouping together related nod
 
 ${(0, doc_code_1.codeBlock)('mermaid', types.text)}
 
-_The generation of the class diagram required ${(0, doc_ms_1.printAsMs)(elapsed)}._
+_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')}), 

package/documentation/print-query-wiki.js

@@ -6,36 +6,41 @@ const log_1 = require("../../test/functionality/_helper/log");
 const query_1 = require("../queries/query");
 const doc_files_1 = require("./doc-util/doc-files");
 const doc_query_1 = require("./doc-util/doc-query");
-const call_context_query_format_1 = require("../queries/call-context-query/call-context-query-format");
+const call_context_query_format_1 = require("../queries/catalog/call-context-query/call-context-query-format");
 const schema_1 = require("../util/schema");
 const query_schema_1 = require("../queries/query-schema");
 const ansi_1 = require("../util/ansi");
-const call_context_query_executor_1 = require("../queries/call-context-query/call-context-query-executor");
+const call_context_query_executor_1 = require("../queries/catalog/call-context-query/call-context-query-executor");
 const compound_query_1 = require("../queries/virtual-query/compound-query");
 const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
 const example_query_code_1 = require("./data/query/example-query-code");
 const doc_structure_1 = require("./doc-util/doc-structure");
 const doc_code_1 = require("./doc-util/doc-code");
+const dataflow_query_executor_1 = require("../queries/catalog/dataflow-query/dataflow-query-executor");
+const id_map_query_executor_1 = require("../queries/catalog/id-map-query/id-map-query-executor");
+const normalized_ast_query_executor_1 = require("../queries/catalog/normalized-ast-query/normalized-ast-query-executor");
+const cluster_query_executor_1 = require("../queries/catalog/cluster-query/cluster-query-executor");
+const static_slice_query_executor_1 = require("../queries/catalog/static-slice-query/static-slice-query-executor");
 (0, doc_query_1.registerQueryDocumentation)('call-context', {
     name: 'Call-Context Query',
     type: 'active',
     shortDescription: 'Finds all calls in a set of files that matches specified criteria.',
     functionName: call_context_query_executor_1.executeCallContextQueries.name,
-    functionFile: '../queries/call-context-query/call-context-query-executor.ts',
+    functionFile: '../queries/catalog/call-context-query/call-context-query-executor.ts',
     buildExplanation: async (shell) => {
         return `
-Call context queries may be used to identify calls to specific functions that match criteria of your interest.
+Call context queries can be used to identify calls to specific functions that match criteria of your interest.
 For now, we support two criteria:
 
-1. **Function Name** (\`callName\`): The function name is specified by a regular expression. This allows you to find all calls to functions that match a specific pattern.
+1. **Function Name** (\`callName\`): The function name is specified by a regular expression. This allows you to find all calls to functions that match a specific pattern. Please note, that if you do not use Regex-Anchors, the query will match any function name that contains the given pattern (you can set the \`callNameExact\` property to \`true\` to automatically add the \`^...$\` anchors).
 2. **Call Targets**  (\`callTargets\`): This specifies to what the function call targets. For example, you may want to find all calls to a function that is not defined locally.
 
-Besides this we provide the following ways to automatically categorize and link identified invocations:
+Besides this, we provide the following ways to automatically categorize and link identified invocations:
 
 1. **Kind**         (\`kind\`): This is a general category that can be used to group calls together. For example, you may want to link all calls to \`plot\` to \`visualize\`.
 2. **Subkind**      (\`subkind\`): This is used to uniquely identify the respective call type when grouping the output. For example, you may want to link all calls to \`ggplot\` to \`plot\`.
 3. **Linked Calls** (\`linkTo\`): This links the current call to the last call of the given kind. This way, you can link a call like \`points\` to the latest graphics plot etc.
-   For now, we _only_offer support for linking to the last call_ as the current flow dependency over-approximation is not stable.
+   For now, we _only_ offer support for linking to the last call, as the current flow dependency over-approximation is not stable.
 4. **Aliases**      (\`includeAliases\`): Consider a case like \`f <- function_of_interest\`, do you want calls to \`f\` to be included in the results? There is probably no need to combine this with a global call target!
 
 Re-using the example code from above, the following query attaches all calls to \`mean\` to the kind \`visualize\` and the subkind \`text\`,
@@ -78,6 +83,89 @@ my_test_function()
 		`;
     }
 });
+(0, doc_query_1.registerQueryDocumentation)('dataflow', {
+    name: 'Dataflow Query',
+    type: 'active',
+    shortDescription: 'Returns the dataflow graph of the given code.',
+    functionName: dataflow_query_executor_1.executeDataflowQuery.name,
+    functionFile: '../queries/catalog/dataflow-query/dataflow-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'x + 1';
+        return `
+Maybe you want to handle only the result of the query execution, or you just need the [dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph) again.
+This query type does exactly that!
+
+Using the example code \`${exampleCode}\`, the following query returns the dataflow graph of the code:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'dataflow'
+            }], { showCode: true })}
+		`;
+    }
+});
+(0, doc_query_1.registerQueryDocumentation)('normalized-ast', {
+    name: 'Normalized AST Query',
+    type: 'active',
+    shortDescription: 'Returns the normalized AST of the given code.',
+    functionName: normalized_ast_query_executor_1.executeNormalizedAstQuery.name,
+    functionFile: '../queries/catalog/normalized-ast-query/normalized-ast-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'x + 1';
+        return `
+Maybe you want to handle only the result of the query execution, or you just need the [normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized%20AST) again.
+This query type does exactly that!
+
+Using the example code \`${exampleCode}\`, the following query returns the normalized AST of the code:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'normalized-ast'
+            }], { showCode: true })}
+		`;
+    }
+});
+(0, doc_query_1.registerQueryDocumentation)('dataflow-cluster', {
+    name: 'Dataflow Cluster Query',
+    type: 'active',
+    shortDescription: 'Calculates and returns all the clusters present in the dataflow graph.',
+    functionName: cluster_query_executor_1.executeDataflowClusterQuery.name,
+    functionFile: '../queries/catalog/cluster-query/cluster-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleA = 'x <- 1; x';
+        const exampleB = 'x <- 1; y';
+        return `
+This query automatically calculates clusters in flowR's dataflow graph 
+and returns a list of all clusters found. 
+Clusters are to be interpreted as literal clusters on the graph traversing
+edges in both directions. From this perspective, 
+the code \`${exampleA}\` has one cluster (given that all code is related), 
+while the code \`${exampleB}\` has two clusters (given that the \`y\` has no relation to the previous definition).
+
+${(0, doc_structure_1.details)('Example <code>' + exampleA + '</code>', await (0, doc_query_1.showQuery)(shell, exampleA, [{ type: 'dataflow-cluster' }], { showCode: false }))}
+${(0, doc_structure_1.details)('Example <code>' + exampleB + '</code>', await (0, doc_query_1.showQuery)(shell, exampleB, [{ type: 'dataflow-cluster' }], { showCode: false }))}
+
+Using the example code from above, the following query returns all clusters:
+${await (0, doc_query_1.showQuery)(shell, example_query_code_1.exampleQueryCode, [{
+                type: 'dataflow-cluster'
+            }], { showCode: false })}
+		`;
+    }
+});
+(0, doc_query_1.registerQueryDocumentation)('id-map', {
+    name: 'Id-Map Query',
+    type: 'active',
+    shortDescription: 'Returns the id-map of the normalized AST of the given code.',
+    functionName: id_map_query_executor_1.executeIdMapQuery.name,
+    functionFile: '../queries/catalog/id-map-query/id-map-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'x + 1';
+        return `
+This query provides access to all nodes in the [normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized%20AST) as a mapping from their id to the node itself. 
+
+Using the example code \`${exampleCode}\`, the following query returns all nodes from the code:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'id-map'
+            }], { showCode: true })}
+		`;
+    }
+});
 (0, doc_query_1.registerQueryDocumentation)('compound', {
     name: 'Compound Query',
     type: 'virtual',
@@ -113,7 +201,7 @@ ${await (0, doc_query_1.showQuery)(shell, example_query_code_1.exampleQueryCode,
         ], { showCode: false, collapseResult: true })}
 
 However, compound queries become more useful whenever common arguments can not be expressed as a union in one of their properties.
-Additionally, you can still overwrite default arguments. 
+Additionally, you can still overwrite default arguments.
 In the following, we (by default) want all calls to not resolve to a local definition, except for those to \`print\` for which we explicitly
 want to resolve to a local definition:
 
@@ -127,8 +215,45 @@ ${await (0, doc_query_1.showQuery)(shell, example_query_code_1.exampleQueryCode,
                 ]
             }], { showCode: false })}
 
-Now, the results no longer contain calls to \`plot\` that are not defined locally. 
+Now, the results no longer contain calls to \`plot\` that are not defined locally.
+
+		`;
+    }
+});
+(0, doc_query_1.registerQueryDocumentation)('static-slice', {
+    name: 'Static Slice Query',
+    type: 'active',
+    shortDescription: 'Slice the dataflow graph reducing the code to just the parts relevant for the given criteria.',
+    functionName: static_slice_query_executor_1.executeStaticSliceClusterQuery.name,
+    functionFile: '../queries/catalog/static-slice-query/static-slice-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'x <- 1\ny <- 2\nx';
+        return `
+To slice, _flowR_ needs one thing from you: a variable or a list of variables (function calls are supported to, referring to the anonymous
+return of the call) that you want to slice the dataflow graph for. 
+Given this, the slice is essentially the subpart of the program that may influence the value of the variables you are interested in.
+To specify a variable of interest, you have to present flowR with a [slicing criterion](${doc_files_1.FlowrWikiBaseRef}/Terminology#slicing-criterion) (or, respectively, an array of them).
+
+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:
+
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'static-slice',
+                criteria: ['3@x']
+            }], { showCode: false })}
+
+In general you may be uninterested in seeing the reconstructed version and want to save some computation time, for this,
+you can use the \`noReconstruction\` flag.
 
+${(0, doc_structure_1.details)('No Reconstruction Example', await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'static-slice',
+                criteria: ['3@x'],
+                noReconstruction: true
+            }], { showCode: false }))}
+
+You can disable [magic comments](${doc_files_1.FlowrWikiBaseRef}/Interface#slice-magic-comments) using the \`noMagicComments\` flag.
+This query replaces the old [\`request-slice\`](${doc_files_1.FlowrWikiBaseRef}/Interface#message-request-slice) message.
 		`;
     }
 });
@@ -139,6 +264,36 @@ async function getText(shell) {
 This page briefly summarizes flowR's query API, represented by the ${query_1.executeQueries.name} function in ${(0, doc_files_1.getFilePathMd)('../queries/query.ts')}.
 Please see the [Interface](${doc_files_1.FlowrWikiBaseRef}/Interface) wiki page for more information on how to access this API.
 
+## The Query Format
+
+Queries are JSON arrays of query objects, each of which uses a \`type\` property to specify the query type.
+In general, we separate two types of queries:
+
+1. **Active Queries**: Are exactly what you would expect from a query (e.g., the [Call-Context Query](#call-context-query)). They fetch information from the dataflow graph.
+2. **Virtual Queries**: Are used to structure your queries (e.g., the [Compound Query](#compound-query)). 
+
+We separate these from a concept perspective. 
+For now, we support the following **active** queries (which we will refer to simply as a \`query\`):
+
+${(0, doc_query_1.tocForQueryType)('active')}
+
+Similarly, we support the following **virtual** queries: 
+
+${(0, doc_query_1.tocForQueryType)('virtual')}
+
+<details>
+
+
+<summary>Detailed Query Format (Automatically Generated)</summary>
+
+Although it is probably better to consult the detailed explanations below, if you want to have a look at the scehma, here is its description:
+
+${(0, schema_1.describeSchema)(query_schema_1.QueriesSchema, ansi_1.markdownFormatter)}
+
+</details>
+
+### Why Queries?
+
 First, consider that you have a file like the following (of course, this is just a simple and artificial example):
 
 \`\`\`r
@@ -168,34 +323,6 @@ Just as an example, the following [Call-Context Query](#call-context-query) find
 
 ${await (0, doc_query_1.showQuery)(shell, example_query_code_1.exampleQueryCode, [{ type: 'call-context', callName: '^read_csv$', callTargets: call_context_query_format_1.CallTargets.OnlyGlobal, kind: 'input', subkind: 'csv-file' }], { showCode: false })}
 
-## The Query Format
-
-Queries are JSON arrays of query objects, each of which uses a \`type\` property to specify the query type.
-In general, we separate two types of queries:
-
-1. **Active Queries**: Are exactly what you would expect from a query (e.g., the [Call-Context Query](#call-context-query)). They fetch information from the dataflow graph.
-2. **Virtual Queries**: Are used to structure your queries (e.g., the [Compound Query](#compound-query)). 
-
-We separate these from a concept perspective. 
-For now, we support the following **active** queries (which we will refer to simply as a \`query\`):
-
-${(0, doc_query_1.tocForQueryType)('active')}
-
-Similarly, we support the following **virtual** queries: 
-
-${(0, doc_query_1.tocForQueryType)('virtual')}
-
-<details>
-
-
-<summary>Detailed Query Format (Automatically Generated)</summary>
-
-Although it is probably better to consult the detailed explanations below, if you want to have a look at the scehma, here is its description:
-
-${(0, schema_1.describeSchema)(query_schema_1.QueriesSchema, ansi_1.markdownFormatter)}
-
-</details>
-
 ${await (0, doc_query_1.explainQueries)(shell, 'active')}
 
 ${await (0, doc_query_1.explainQueries)(shell, 'virtual')}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/flowr",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {

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

@@ -1,11 +1,12 @@
 import type { CallContextQuery, CallContextQueryResult } from './call-context-query-format';
-import type { BasicQueryData } from '../query';
+import type { BasicQueryData } from '../../query';
 /**
  * Multi-stage call context query resolve.
  *
  * 1. Resolve all calls in the DF graph that match the respective {@link DefaultCallContextQueryFormat#callName} regex.
- * 2. Identify their respective call targets, if {@link DefaultCallContextQueryFormat#callTargets} is set to be non-any.
+ * 2. If there is an alias attached, consider all call traces.
+ * 3. Identify their respective call targets, if {@link DefaultCallContextQueryFormat#callTargets} is set to be non-any.
  *    This happens during the main resolution!
- * 3. Attach `linkTo` calls to the respective calls.
+ * 4. Attach `linkTo` calls to the respective calls.
  */
 export declare function executeCallContextQueries({ graph, ast }: BasicQueryData, queries: readonly CallContextQuery[]): CallContextQueryResult;

package/queries/{call-context-query → catalog/call-context-query}/call-context-query-executor.js

@@ -2,17 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeCallContextQueries = executeCallContextQueries;
 const call_context_query_format_1 = require("./call-context-query-format");
-const node_id_1 = require("../../r-bridge/lang-4.x/ast/model/processing/node-id");
-const vertex_1 = require("../../dataflow/graph/vertex");
-const assert_1 = require("../../util/assert");
-const edge_1 = require("../../dataflow/graph/edge");
-const resolve_by_name_1 = require("../../dataflow/environments/resolve-by-name");
-const built_in_1 = require("../../dataflow/environments/built-in");
-const cfg_1 = require("../../util/cfg/cfg");
-const two_layer_collector_1 = require("../two-layer-collector");
-const objects_1 = require("../../util/objects");
-const visitor_1 = require("../../util/cfg/visitor");
-const identifier_1 = require("../../dataflow/environments/identifier");
+const node_id_1 = require("../../../r-bridge/lang-4.x/ast/model/processing/node-id");
+const vertex_1 = require("../../../dataflow/graph/vertex");
+const assert_1 = require("../../../util/assert");
+const edge_1 = require("../../../dataflow/graph/edge");
+const resolve_by_name_1 = require("../../../dataflow/environments/resolve-by-name");
+const built_in_1 = require("../../../dataflow/environments/built-in");
+const cfg_1 = require("../../../util/cfg/cfg");
+const two_layer_collector_1 = require("../../two-layer-collector");
+const objects_1 = require("../../../util/objects");
+const visitor_1 = require("../../../util/cfg/visitor");
+const identifier_1 = require("../../../dataflow/environments/identifier");
 function satisfiesCallTargets(id, graph, callTarget) {
     const callVertex = graph.get(id);
     if (callVertex === undefined || callVertex[0].tag !== vertex_1.VertexType.FunctionCall) {
@@ -35,7 +35,7 @@ function satisfiesCallTargets(id, graph, callTarget) {
          * including any potential built-in mapping.
          */
         const reResolved = (0, resolve_by_name_1.resolveByName)(info.name, info.environment, identifier_1.ReferenceType.Unknown);
-        if (reResolved && reResolved.some(t => t.definedAt === built_in_1.BuiltIn)) {
+        if (reResolved?.some(t => t.definedAt === built_in_1.BuiltIn)) {
             builtIn = true;
         }
     }
@@ -92,6 +92,9 @@ function makeReport(collector) {
 function isSubCallQuery(query) {
     return 'linkTo' in query;
 }
+function exactCallNameRegex(name) {
+    return new RegExp(`^${name}$`);
+}
 function promoteQueryCallNames(queries) {
     let requiresCfg = false;
     const promotedQueries = queries.map(q => {
@@ -99,7 +102,8 @@ function promoteQueryCallNames(queries) {
             requiresCfg = true;
             return {
                 ...q,
-                callName: new RegExp(q.callName),
+                callName: q.callNameExact ? exactCallNameRegex(q.callName)
+                    : new RegExp(q.callName),
                 linkTo: {
                     ...q.linkTo,
                     /* we have to add another promotion layer whenever we add something without this call name */
@@ -110,7 +114,8 @@ function promoteQueryCallNames(queries) {
         else {
             return {
                 ...q,
-                callName: new RegExp(q.callName)
+                callName: q.callNameExact ? exactCallNameRegex(q.callName)
+                    : new RegExp(q.callName)
             };
         }
     });
@@ -186,9 +191,10 @@ function retrieveAllCallAliases(nodeId, graph) {
  * Multi-stage call context query resolve.
  *
  * 1. Resolve all calls in the DF graph that match the respective {@link DefaultCallContextQueryFormat#callName} regex.
- * 2. Identify their respective call targets, if {@link DefaultCallContextQueryFormat#callTargets} is set to be non-any.
+ * 2. If there is an alias attached, consider all call traces.
+ * 3. Identify their respective call targets, if {@link DefaultCallContextQueryFormat#callTargets} is set to be non-any.
  *    This happens during the main resolution!
- * 3. Attach `linkTo` calls to the respective calls.
+ * 4. Attach `linkTo` calls to the respective calls.
  */
 function executeCallContextQueries({ graph, ast }, queries) {
     /* omit performance page load */

package/queries/{call-context-query → catalog/call-context-query}/call-context-query-format.d.ts

@@ -1,5 +1,5 @@
-import type { BaseQueryFormat, BaseQueryResult } from '../base-query-format';
-import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
+import type { BaseQueryFormat, BaseQueryResult } from '../../base-query-format';
+import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
 export declare enum CallTargets {
     /** call targets a function that is not defined locally (e.g., the call targets a library function) */
     OnlyGlobal = "global",
@@ -16,6 +16,10 @@ export interface DefaultCallContextQueryFormat<CallName extends RegExp | string>
     readonly type: 'call-context';
     /** Regex regarding the function name, please note that strings will be interpreted as regular expressions too! */
     readonly callName: CallName;
+    /**
+     * Should we automatically add the `^` and `$` anchors to the regex to make it an exact match?
+     */
+    readonly callNameExact?: boolean;
     /** kind may be a step or anything that you attach to the call, this can be used to group calls together (e.g., linking `ggplot` to `visualize`). Defaults to `.` */
     readonly kind?: string;
     /** subkinds are used to uniquely identify the respective call type when grouping the output (e.g., the normalized name, linking `ggplot` to `plot`). Defaults to `.` */

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

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

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

@@ -0,0 +1,19 @@
+"use strict";
+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) {
+    if (queries.length !== 1) {
+        log_1.log.warn('The dataflow cluster query expects only up to one query, but got', queries.length);
+    }
+    const start = Date.now();
+    const clusters = (0, cluster_1.findAllClusters)(graph);
+    return {
+        '.meta': {
+            timing: Date.now() - start
+        },
+        clusters
+    };
+}
+//# sourceMappingURL=cluster-query-executor.js.map

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

@@ -0,0 +1,12 @@
+import type { BaseQueryFormat, BaseQueryResult } from '../../base-query-format';
+import type { DataflowGraphClusters } from '../../../dataflow/cluster';
+/**
+ * Calculates and returns all clusters encountered in the dataflow graph.
+ */
+export interface DataflowClusterQuery extends BaseQueryFormat {
+    readonly type: 'dataflow-cluster';
+}
+export interface DataflowClusterQueryResult extends BaseQueryResult {
+    /** All clusters found in the respective dataflow */
+    readonly clusters: DataflowGraphClusters;
+}

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=cluster-query-format.js.map

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

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

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

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

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

@@ -0,0 +1,12 @@
+import type { BaseQueryFormat, BaseQueryResult } from '../../base-query-format';
+import type { DataflowGraph } from '../../../dataflow/graph/graph';
+/**
+ * Simple re-returns the dataflow graph of the analysis.
+ */
+export interface DataflowQuery extends BaseQueryFormat {
+    readonly type: 'dataflow';
+}
+export interface DataflowQueryResult extends BaseQueryResult {
+    /** Please be aware that this is the graph in its JSON representation, use {@link DataflowGraph#fromJson} if the result is serialized */
+    readonly graph: DataflowGraph;
+}

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=dataflow-query-format.js.map

package/queries/catalog/id-map-query/id-map-query-executor.d.ts

@@ -0,0 +1,3 @@
+import type { BasicQueryData } from '../../query';
+import type { IdMapQuery, IdMapQueryResult } from './id-map-query-format';
+export declare function executeIdMapQuery({ ast }: BasicQueryData, queries: readonly IdMapQuery[]): IdMapQueryResult;