@eagleoutice/flowr 2.1.3 → 2.1.4

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

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RegisteredQueries = void 0;
-exports.asciiSummaryOfQueryResult = asciiSummaryOfQueryResult;
 exports.showQuery = showQuery;
 exports.registerQueryDocumentation = registerQueryDocumentation;
+exports.linkToQueryOfName = linkToQueryOfName;
 exports.tocForQueryType = tocForQueryType;
 exports.explainQueries = explainQueries;
 const query_1 = require("../../queries/query");
@@ -16,154 +16,8 @@ const doc_files_1 = require("./doc-files");
 const doc_dfg_1 = require("./doc-dfg");
 const doc_code_1 = require("./doc-code");
 const time_1 = require("../../util/time");
-const built_in_1 = require("../../dataflow/environments/built-in");
-const dfg_1 = require("../../util/mermaid/dfg");
-const ast_1 = require("../../util/mermaid/ast");
-const doc_hover_over_1 = require("./doc-hover-over");
-function nodeString(id, formatter, processed) {
-    if (id === built_in_1.BuiltIn) {
-        return (0, ansi_1.italic)('built-in', formatter);
-    }
-    const node = processed.normalize.idMap.get(id);
-    if (node === undefined) {
-        return `UNKNOWN: ${id}`;
-    }
-    return `${(0, ansi_1.italic)('`' + (node.lexeme ?? node.info.fullLexeme ?? 'UNKNOWN') + '`', formatter)} (L.${node.location?.[0]})`;
-}
-function asciiCallContextSubHit(formatter, results, processed) {
-    const result = [];
-    for (const { id, calls = [], linkedIds = [], aliasRoots = [] } of results) {
-        const node = processed.normalize.idMap.get(id);
-        if (node === undefined) {
-            result.push(` ${(0, ansi_1.bold)('UNKNOWN: ' + JSON.stringify({ calls, linkedIds }))}`);
-            continue;
-        }
-        let line = nodeString(id, formatter, processed);
-        if (calls.length > 0) {
-            line += ` with ${calls.length} call${calls.length > 1 ? 's' : ''} (${calls.map(c => nodeString(c, formatter, processed)).join(', ')})`;
-        }
-        if (linkedIds.length > 0) {
-            line += ` with ${linkedIds.length} link${linkedIds.length > 1 ? 's' : ''} (${linkedIds.map(c => nodeString(c, formatter, processed)).join(', ')})`;
-        }
-        if (aliasRoots.length > 0) {
-            line += ` with ${aliasRoots.length} alias root${aliasRoots.length > 1 ? 's' : ''} (${aliasRoots.map(c => nodeString(c, formatter, processed)).join(', ')})`;
-        }
-        result.push(line);
-    }
-    return result.join(', ');
-}
-function asciiCallContext(formatter, results, processed) {
-    /* traverse over 'kinds' and within them 'subkinds' */
-    const result = [];
-    for (const [kind, { subkinds }] of Object.entries(results['kinds'])) {
-        result.push(`   ╰ ${(0, ansi_1.bold)(kind, formatter)}`);
-        for (const [subkind, values] of Object.entries(subkinds)) {
-            result.push(`     ╰ ${(0, ansi_1.bold)(subkind, formatter)}: ${asciiCallContextSubHit(formatter, values, processed)}`);
-        }
-    }
-    return result.join('\n');
-}
-function summarizeIdsIfTooLong(ids) {
-    const naive = ids.join(', ');
-    if (naive.length <= 20) {
-        return naive;
-    }
-    let acc = '';
-    let i = 0;
-    while (acc.length <= 20) {
-        acc += ids[i++] + ', ';
-    }
-    if (i < ids.length) {
-        acc += '... (see JSON below)';
-    }
-    return (0, doc_hover_over_1.textWithTooltip)(acc, JSON.stringify(ids));
-}
-function asciiSummaryOfQueryResult(formatter, totalInMs, results, processed) {
-    const result = [];
-    for (const [query, queryResults] of Object.entries(results)) {
-        if (query === '.meta') {
-            continue;
-        }
-        if (query === 'call-context') {
-            const out = queryResults;
-            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
-            result.push(asciiCallContext(formatter, out, processed));
-            continue;
-        }
-        else if (query === 'dataflow') {
-            const out = queryResults;
-            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
-            result.push(`   ╰ [Dataflow Graph](${(0, dfg_1.graphToMermaidUrl)(out.graph)})`);
-            continue;
-        }
-        else if (query === 'id-map') {
-            const out = queryResults;
-            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
-            result.push(`   ╰ Id List: {${summarizeIdsIfTooLong([...out.idMap.keys()])}}`);
-            continue;
-        }
-        else if (query === 'normalized-ast') {
-            const out = queryResults;
-            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
-            result.push(`   ╰ [Normalized AST](${(0, ast_1.normalizedAstToMermaidUrl)(out.normalized.ast)})`);
-            continue;
-        }
-        else if (query === 'static-slice') {
-            const out = queryResults;
-            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
-            for (const [fingerprint, obj] of Object.entries(out.results)) {
-                const { criteria, noMagicComments, noReconstruction } = JSON.parse(fingerprint);
-                const addons = [];
-                if (noReconstruction) {
-                    addons.push('no reconstruction');
-                }
-                if (noMagicComments) {
-                    addons.push('no magic comments');
-                }
-                result.push(`   ╰ Slice for {${criteria.join(', ')}} ${addons.join(', ')}`);
-                if ('reconstruct' in obj) {
-                    result.push('     ╰ Code (newline as <code>&#92;n</code>): <code>' + obj.reconstruct.code.split('\n').join('\\n') + '</code>');
-                }
-                else {
-                    result.push(`     ╰ Id List: {${summarizeIdsIfTooLong([...obj.slice.result])}}`);
-                }
-            }
-            continue;
-        }
-        else if (query === 'dataflow-cluster') {
-            const out = queryResults;
-            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${out['.meta'].timing.toFixed(0)}ms)`);
-            result.push(`   ╰ Found ${out.clusters.length} cluster${out.clusters.length === 1 ? '' : 's'}`);
-            for (const cluster of out.clusters) {
-                const unknownSideEffects = cluster.hasUnknownSideEffects ? '(has unknown side effect)' : '';
-                result.push(`      ╰ ${unknownSideEffects} {${summarizeIdsIfTooLong(cluster.members)}} ([marked](${(0, dfg_1.graphToMermaidUrl)(processed.dataflow.graph, false, new Set(cluster.members))}))`);
-            }
-            continue;
-        }
-        else if (query === 'lineage') {
-            const out = queryResults;
-            result.push(`Query: ${(0, ansi_1.bold)(query, formatter)} (${(0, time_1.printAsMs)(out['.meta'].timing, 0)})`);
-            for (const [criteria, lineage] of Object.entries(out.lineages)) {
-                result.push(`   ╰ ${criteria}: {${summarizeIdsIfTooLong([...lineage])}}`);
-            }
-            continue;
-        }
-        result.push(`Query: ${(0, ansi_1.bold)(query, formatter)}`);
-        let timing = -1;
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-        for (const [key, value] of Object.entries(queryResults)) {
-            if (key === '.meta') {
-                timing = value.timing;
-                continue;
-            }
-            result.push(` ╰ ${key}: ${JSON.stringify(value)}`);
-        }
-        result.push(`  - Took ${(0, time_1.printAsMs)(timing, 0)}`);
-    }
-    result.push((0, ansi_1.italic)(`All queries together required ≈${(0, time_1.printAsMs)(results['.meta'].timing, 0)} (1ms accuracy, total ${(0, time_1.printAsMs)(totalInMs, 0)})`, formatter));
-    return formatter.format(result.join('\n'));
-}
-async function showQuery(shell, code, queries, { showCode, collapseResult } = {}) {
+const query_print_1 = require("../../queries/query-print");
+async function showQuery(shell, code, queries, { showCode, collapseResult, collapseQuery } = {}) {
     const now = performance.now();
     const analysis = await new pipeline_executor_1.PipelineExecutor(default_pipelines_1.DEFAULT_DATAFLOW_PIPELINE, {
         shell,
@@ -174,17 +28,16 @@ async function showQuery(shell, code, queries, { showCode, collapseResult } = {}
     const metaInfo = `
 The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parsing and normalization and the query) within the generation environment.
 	`.trim();
+    const str = JSON.stringify(queries, json_1.jsonReplacer, collapseQuery ? ' ' : 2);
     return `
 
-\`\`\`json
-${JSON.stringify(queries, json_1.jsonReplacer, 2)}
-\`\`\`
+${(0, doc_code_1.codeBlock)('json', collapseQuery ? str.split('\n').join(' ').replace(/([{[])\s{2,}/g, '$1 ').replace(/\s{2,}([\]}])/g, ' $1') : str)}
 
 ${collapseResult ? ' <details> <summary style="color:gray">Show Results</summary>' : ''}
 
 _Results (prettified and summarized):_
 
-${asciiSummaryOfQueryResult(ansi_1.markdownFormatter, duration, results, analysis)}
+${(0, query_print_1.asciiSummaryOfQueryResult)(ansi_1.markdownFormatter, duration, results, analysis)}
 
 <details> <summary style="color:gray">Show Detailed Results as Json</summary>
 
@@ -223,6 +76,13 @@ function registerQueryDocumentation(query, doc) {
 function linkify(name) {
     return name.toLowerCase().replace(/ /g, '-');
 }
+function linkToQueryOfName(id) {
+    const query = exports.RegisteredQueries.active.get(id) ?? exports.RegisteredQueries.virtual.get(id);
+    if (!query) {
+        throw new Error(`Query ${id} not found`);
+    }
+    return `[${query.name}](#${linkify(query.name)})`;
+}
 function tocForQueryType(type) {
     const queries = [...exports.RegisteredQueries[type].entries()].sort(([, { name: a }], [, { name: b }]) => a.localeCompare(b));
     const result = [];
@@ -248,11 +108,11 @@ Responsible for the execution of the ${name} query is \`${functionName}\` in ${(
 `;
 }
 async function explainQueries(shell, type) {
-    const queries = exports.RegisteredQueries[type];
+    const queries = [...exports.RegisteredQueries[type].entries()].sort(([, { name: a }], [, { name: b }]) => a.localeCompare(b));
     const result = [];
-    for (const doc of queries.values()) {
+    for (const [, doc] of queries) {
         result.push(await explainQuery(shell, doc));
     }
-    return result.join('\n\n\n');
+    return result.join(`\n${'-'.repeat(5)}\n\n`);
 }
 //# sourceMappingURL=doc-query.js.map

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

@@ -4,7 +4,7 @@ exports.printReplHelpAsMarkdownTable = printReplHelpAsMarkdownTable;
 exports.documentReplSession = documentReplSession;
 const repl_commands_1 = require("../../cli/repl/commands/repl-commands");
 const doc_cli_option_1 = require("./doc-cli-option");
-const doc_hover_over_1 = require("./doc-hover-over");
+const html_hover_over_1 = require("../../util/html-hover-over");
 const core_1 = require("../../cli/repl/core");
 const ansi_1 = require("../../util/ansi");
 const doc_docker_1 = require("./doc-docker");
@@ -19,7 +19,7 @@ function printHelpForScript(script, starredVersion) {
         return base;
     }
     const aliases = script[1].aliases;
-    return `${base} (alias${aliases.length > 1 ? 'es' : ''}: ${aliases.map(a => '**:' + (0, doc_hover_over_1.textWithTooltip)(a, `Alias of ':${script[0]}'. ${script[1].description}`) + '**').join(', ')}) |`;
+    return `${base} (alias${aliases.length > 1 ? 'es' : ''}: ${aliases.map(a => '**:' + (0, html_hover_over_1.textWithTooltip)(a, `Alias of ':${script[0]}'. ${script[1].description}`) + '**').join(', ')}) |`;
 }
 function printReplHelpAsMarkdownTable() {
     const scriptHelp = [];

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

@@ -807,7 +807,8 @@ ${(0, doc_types_1.printHierarchy)({ program: vertexType.program, hierarchy: vert
 Let's start by looking at the properties of the dataflow information object: ${Object.keys(result.dataflow).map(k => `\`${k}\``).join(', ')}.
 
 ${(() => {
-            (0, assert_1.guard)(Object.keys(result.dataflow).length === 7, () => 'Update Dataflow Documentation!');
+            /* this includes the meta field for timing */
+            (0, assert_1.guard)(Object.keys(result.dataflow).length === 8, () => 'Update Dataflow Documentation!');
             return '';
         })()}
 

package/documentation/print-interface-wiki.js

@@ -18,6 +18,7 @@ const ansi_1 = require("../util/ansi");
 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");
 async function explainServer(shell) {
     (0, doc_data_server_messages_1.documentAllServerMessages)();
     return `
@@ -27,9 +28,13 @@ Additionally, the server is not well guarded against attacks (e.g., you can theo
 
 Every message has to be given in a single line (i.e., without a newline in-between) and end with a newline character. Nevertheless, we will pretty-print example given in the following segments for the ease of reading.
 
-> [!NOTE]
-> The default ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'server', false)} uses a simple [TCP](https://de.wikipedia.org/wiki/Transmission_Control_Protocol)
-> connection. If you want _flowR_ to expose a [WebSocket](https://de.wikipedia.org/wiki/WebSocket) server instead, add the ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'server', false)} flag (i.e., ${(0, doc_cli_option_1.multipleCliOptions)('flowr', 'server', 'ws')}) when starting _flowR_ from the command line.
+${(0, doc_structure_1.block)({
+        type: 'NOTE',
+        content: `
+The default ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'server', false)} uses a simple [TCP](https://de.wikipedia.org/wiki/Transmission_Control_Protocol)
+connection. If you want _flowR_ to expose a [WebSocket](https://de.wikipedia.org/wiki/WebSocket) server instead, add the ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'ws', false)} flag (i.e., ${(0, doc_cli_option_1.multipleCliOptions)('flowr', 'server', 'ws')}) when starting _flowR_ from the command line.
+			`
+    })}
 
 ${await (0, doc_server_message_1.printServerMessages)(shell)}
 

package/documentation/print-query-wiki.js

@@ -6,9 +6,7 @@ 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/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/catalog/call-context-query/call-context-query-executor");
 const compound_query_1 = require("../queries/virtual-query/compound-query");
@@ -22,6 +20,11 @@ const normalized_ast_query_executor_1 = require("../queries/catalog/normalized-a
 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");
 const lineage_query_executor_1 = require("../queries/catalog/lineage-query/lineage-query-executor");
+const dependencies_query_executor_1 = require("../queries/catalog/dependencies-query/dependencies-query-executor");
+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");
 (0, doc_query_1.registerQueryDocumentation)('call-context', {
     name: 'Call-Context Query',
     type: 'active',
@@ -54,7 +57,7 @@ ${await (0, doc_query_1.showQuery)(shell, example_query_code_1.exampleQueryCode,
                 callName: '^read_',
                 kind: 'input',
                 subkind: 'csv-file',
-                callTargets: call_context_query_format_1.CallTargets.OnlyGlobal
+                callTargets: identify_link_to_last_call_relation_1.CallTargets.OnlyGlobal
             },
             {
                 type: 'call-context',
@@ -67,7 +70,7 @@ ${await (0, doc_query_1.showQuery)(shell, example_query_code_1.exampleQueryCode,
 
 As you can see, all kinds and subkinds with the same name are grouped together.
 Yet, re-stating common arguments and kinds may be cumbersome (although you can already use clever regex patterns).
-See the [Compound Query](#compound-query) for a way to structure your queries more compactly if you think it gets too verbose. 
+See the ${(0, doc_query_1.linkToQueryOfName)('compound')} for a way to structure your queries more compactly if you think it gets too verbose. 
 
 ${await (async () => {
             const code = `
@@ -99,7 +102,7 @@ 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 })}
+            }], { showCode: true, collapseQuery: true })}
 		`;
     }
 });
@@ -118,7 +121,7 @@ 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 })}
+            }], { showCode: true, collapseQuery: true })}
 		`;
     }
 });
@@ -176,7 +179,7 @@ ${(0, doc_structure_1.details)('Example <code>' + exampleB + '</code>', await (0
 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 })}
+            }], { showCode: false, collapseQuery: true })}
 		`;
     }
 });
@@ -194,7 +197,7 @@ This query provides access to all nodes in the [normalized AST](${doc_files_1.Fl
 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 })}
+            }], { showCode: true, collapseQuery: true })}
 		`;
     }
 });
@@ -240,10 +243,10 @@ want to resolve to a local definition:
 ${await (0, doc_query_1.showQuery)(shell, example_query_code_1.exampleQueryCode, [{
                 type: 'compound',
                 query: 'call-context',
-                commonArguments: { kind: 'visualize', subkind: 'text', callTargets: call_context_query_format_1.CallTargets.OnlyGlobal },
+                commonArguments: { kind: 'visualize', subkind: 'text', callTargets: identify_link_to_last_call_relation_1.CallTargets.OnlyGlobal },
                 arguments: [
                     { callName: '^mean$' },
-                    { callName: '^print$', callTargets: call_context_query_format_1.CallTargets.OnlyLocal }
+                    { callName: '^print$', callTargets: identify_link_to_last_call_relation_1.CallTargets.OnlyLocal }
                 ]
             }], { showCode: false })}
 
@@ -289,6 +292,85 @@ This query replaces the old [\`request-slice\`](${doc_files_1.FlowrWikiBaseRef}/
 		`;
     }
 });
+(0, doc_query_1.registerQueryDocumentation)('dependencies', {
+    name: 'Dependencies Query',
+    type: 'active',
+    shortDescription: 'Returns all direct dependencies (in- and outputs) of a given R script',
+    functionName: dependencies_query_executor_1.executeDependenciesQuery.name,
+    functionFile: '../queries/catalog/dependencies-query/dependencies-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'library(x)';
+        const longerCode = `
+source("sample.R")
+foo <- loadNamespace("bar")
+
+data <- read.csv("data.csv")
+
+#' @importFrom ggplot2 ggplot geom_point aes
+ggplot(data, aes(x=x, y=y)) + geom_point()
+
+better::write.csv(data, "data2.csv")
+print("hello world!")
+		`;
+        return `
+This query extracts all dependencies from an R script, using a combination of a ${(0, doc_query_1.linkToQueryOfName)('call-context')}
+and more advanced tracking in the [Dataflow Graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph).  
+
+In other words, if you have a script simply reading: \`${exampleCode}\`, the following query returns the loaded library:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'dependencies'
+            }], { showCode: false, collapseQuery: true })}
+
+Of course, this works for more complicated scripts too. The query offers information on the loaded _libraries_, _sourced_ files, data which is _read_ and data which is _written_.
+For example, consider the following script:
+${(0, doc_code_1.codeBlock)('r', longerCode)}
+The following query returns the dependencies of the script.
+${await (0, doc_query_1.showQuery)(shell, longerCode, [{
+                type: 'dependencies'
+            }], { showCode: false, collapseQuery: true, collapseResult: true })}
+
+Currently the dependency extraction may fail as it is essentially a set of heuristics guessing the dependencies.
+We welcome any feedback on this (consider opening a [new issue](${doc_issue_1.NewIssueUrl})).
+
+In the meantime we offer several properties to overwrite the default behavior (e.g., function names that should be collected)
+
+${await (0, doc_query_1.showQuery)(shell, longerCode, [{
+                type: 'dependencies',
+                ignoreDefaultFunctions: true,
+                libraryFunctions: [{ name: 'print', argIdx: 0, argName: 'library' }],
+                sourceFunctions: [],
+                readFunctions: [],
+                writeFunctions: []
+            }], { showCode: false, collapseQuery: false, collapseResult: true })}
+
+		`;
+    }
+});
+(0, doc_query_1.registerQueryDocumentation)('location-map', {
+    name: 'Location Map Query',
+    type: 'active',
+    shortDescription: 'Returns a simple mapping of ids to their location in the source file',
+    functionName: location_map_query_executor_1.executeLocationMapQuery.name,
+    functionFile: '../queries/catalog/location-map-query/location-map-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'x + 1\nx * 2';
+        return `
+A query like the ${(0, doc_query_1.linkToQueryOfName)('id-map')} query can return a really big result, especially for larger scripts.
+If you are not interested in all of the information contained within the full map, you can use the location map query to get a simple mapping of ids to their location in the source file.   
+
+Consider you have the following code:
+
+${(0, doc_code_1.codeBlock)('r', exampleCode)}
+
+The following query then gives you the aforementioned mapping:
+
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'location-map'
+            }], { showCode: false, collapseQuery: true })}
+
+		`;
+    }
+});
 async function getText(shell) {
     const rversion = (await shell.usedRVersion())?.format() ?? 'unknown';
     return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'query API', rVersion: rversion })}
@@ -296,13 +378,22 @@ 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.
 
+${(0, doc_structure_1.block)({
+        type: 'NOTE',
+        content: `
+There are many ways to query a dataflow graph created by flowR.
+For example, you can use the [\`request-query\`](${doc_files_1.FlowrWikiBaseRef}/Interface#message-request-query) message
+with a running flowR server, or the ${(0, doc_cli_option_1.getReplCommand)('query')} command in the flowR [REPL](${doc_files_1.FlowrWikiBaseRef}/Interface#repl).	
+			`.trim()
+    })}
+
 ## 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)). 
+1. **Active Queries**: Are exactly what you would expect from a query (e.g., the ${(0, doc_query_1.linkToQueryOfName)('call-context')}). They fetch information from the dataflow graph.
+2. **Virtual Queries**: Are used to structure your queries (e.g., the ${(0, doc_query_1.linkToQueryOfName)('compound')}). 
 
 We separate these from a concept perspective. 
 For now, we support the following **active** queries (which we will refer to simply as a \`query\`):
@@ -320,7 +411,7 @@ ${(0, doc_query_1.tocForQueryType)('virtual')}
 
 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)}
+${(0, schema_1.describeSchema)(query_1.QueriesSchema, ansi_1.markdownFormatter)}
 
 </details>
 
@@ -349,11 +440,11 @@ However, this fails to incorporate
 3. Context information (e.g., calls like \`points\` may link to the current plot)
 
 To solve this, flowR provides a query API which allows you to specify queries on the dataflow graph.
-For the specific use-case stated, you could use the [Call-Context Query](#call-context-query) to find all calls to \`read_csv\` which refer functions that are not overwritten.
+For the specific use-case stated, you could use the ${(0, doc_query_1.linkToQueryOfName)('call-context')} to find all calls to \`read_csv\` which refer functions that are not overwritten.
 
-Just as an example, the following [Call-Context Query](#call-context-query) finds all calls to \`read_csv\` that are not overwritten:
+Just as an example, the following ${(0, doc_query_1.linkToQueryOfName)('call-context')} finds all calls to \`read_csv\` that are not overwritten:
 
-${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 })}
+${await (0, doc_query_1.showQuery)(shell, example_query_code_1.exampleQueryCode, [{ type: 'call-context', callName: '^read_csv$', callTargets: identify_link_to_last_call_relation_1.CallTargets.OnlyGlobal, kind: 'input', subkind: 'csv-file' }], { showCode: false })}
 
 ${await (0, doc_query_1.explainQueries)(shell, 'active')}
 

package/package.json

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

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

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

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

@@ -1,5 +1,5 @@
 import type { CallContextQuery, CallContextQueryResult } from './call-context-query-format';
-import type { BasicQueryData } from '../../query';
+import type { BasicQueryData } from '../../base-query-format';
 /**
  * Multi-stage call context query resolve.
  *