@eagleoutice/flowr 2.7.6 → 2.8.0

package/dataflow/internal/process/process-value.js

@@ -5,9 +5,10 @@ const graph_1 = require("../../graph/graph");
 const vertex_1 = require("../../graph/vertex");
 const identifier_1 = require("../../environments/identifier");
 /**
- *
+ * Processes a value node in the AST for dataflow analysis.
+ * For example, literals like numbers.
  */
-function processValue({ info: { id } }, { controlDependencies, completeAst: { idMap }, ctx: { env }, environment }) {
+function processValue({ info: { id } }, { controlDependencies, completeAst: { idMap }, environment }) {
     return {
         unknownReferences: [],
         in: [{ nodeId: id, name: undefined, controlDependencies, type: identifier_1.ReferenceType.Constant }],
@@ -15,11 +16,12 @@ function processValue({ info: { id } }, { controlDependencies, completeAst: { id
         environment,
         graph: new graph_1.DataflowGraph(idMap).addVertex({
             tag: vertex_1.VertexType.Value,
-            id: id,
-            cds: controlDependencies
-        }, env.makeCleanEnv()),
+            id,
+            controlDependencies
+        }, undefined),
         exitPoints: [{ nodeId: id, type: 0 /* ExitPointType.Default */, controlDependencies }],
-        entryPoint: id
+        entryPoint: id,
+        hooks: []
     };
 }
 //# sourceMappingURL=process-value.js.map

package/dataflow/origin/dfg-get-origin.js

@@ -91,7 +91,8 @@ function getCallTarget(dfg, call) {
     })) : undefined;
     const targets = new Set((0, linker_1.getAllFunctionCallTargets)(call.id, dfg));
     if (targets.size === 0) {
-        return origins;
+        // resolve via variable use origin
+        return origins?.length === 0 ? getVariableUseOrigin(dfg, call) : origins;
     }
     origins = (origins ?? []).concat([...targets].map(target => {
         if ((0, built_in_1.isBuiltIn)(target)) {

package/dataflow/origin/dfg-get-symbol-refs.js

@@ -26,7 +26,7 @@ function getAllRefsToSymbol(graph, nodeId) {
     if (origins === undefined) {
         return undefined;
     }
-    const definitiveOrigins = origins.filter(o => (0, info_1.happensInEveryBranch)(graph.getVertex(o.id)?.cds));
+    const definitiveOrigins = origins.filter(o => (0, info_1.happensInEveryBranch)(graph.getVertex(o.id)?.controlDependencies));
     if (definitiveOrigins.length === 0) {
         return undefined;
     }

package/documentation/doc-readme.d.ts

@@ -5,5 +5,5 @@ import { DocMaker } from './wiki-mk/doc-maker';
  */
 export declare class DocReadme extends DocMaker<'README.md'> {
     constructor();
-    text({ treeSitter }: DocMakerArgs): Promise<string>;
+    text({ treeSitter, ctx }: DocMakerArgs): Promise<string>;
 }

package/documentation/doc-readme.js

@@ -119,7 +119,7 @@ class DocReadme extends doc_maker_1.DocMaker {
     constructor() {
         super('README.md', module.filename, 'flowR README', false);
     }
-    async text({ treeSitter }) {
+    async text({ treeSitter, ctx }) {
         const dateOptions = { year: 'numeric', month: 'short', day: 'numeric' };
         return `
 [![flowR logo](https://raw.githubusercontent.com/wiki/flowr-analysis/flowr/img/flowR.png)](${doc_files_1.FlowrGithubBaseRef}/flowr/wiki)\\
@@ -183,7 +183,7 @@ ${await (0, doc_repl_1.documentReplSession)(treeSitter, [{
    `), '    ')}
 
 * 📚 **dependency analysis**\\
-  Given your analysis project, flowR offers a plethora of so-called [queries](${doc_files_1.FlowrWikiBaseRef}/Query-API) to get more information about your code.
+  Given your analysis project, flowR offers a plethora of so-called ${ctx.linkPage('wiki/Query API', 'queries')} to get more information about your code.
   An important query is the [dependencies query](${doc_files_1.FlowrWikiBaseRef}/Query-API#dependencies-query), which shows you the library your project needs,
   the data files it reads, the scripts it sources, and the data it outputs.
   
@@ -192,12 +192,12 @@ The following showcases the dependency view of the [Visual Studio Code extension
 
 ![Dependency Analysis](https://raw.githubusercontent.com/flowr-analysis/vscode-flowr/refs/heads/main/media/dependencies.png)
   
-  `), '    ')}
+  `), '    ')} 
 
-* 🚀 **fast data- and control-flow graphs**\\
-  Within just ${'<i>' + (0, html_hover_over_1.textWithTooltip)((0, numbers_1.roundToDecimals)(await (0, doc_benchmarks_1.getLatestDfAnalysisTime)('"social-science" Benchmark Suite (tree-sitter)'), 1) + ' ms', 'This measurement is automatically fetched from the latest benchmark!') + '</i>'} (as of ${new Date(await (0, doc_benchmarks_1.getLastBenchmarkUpdate)()).toLocaleDateString('en-US', dateOptions)}), 
+* 🚀 **fast call-graph, data-, and control-flow graphs**\\
+  Within just [${'<i>' + (0, html_hover_over_1.textWithTooltip)((0, numbers_1.roundToDecimals)(await (0, doc_benchmarks_1.getLatestDfAnalysisTime)('"social-science" Benchmark Suite (tree-sitter)'), 1) + ' ms', 'This measurement is automatically fetched from the latest benchmark!') + '</i>'} (as of ${new Date(await (0, doc_benchmarks_1.getLastBenchmarkUpdate)()).toLocaleDateString('en-US', dateOptions)})](${doc_files_1.FlowrSiteBaseRef}/wiki/stats/benchmark), 
   _flowR_ can analyze the data- and control-flow of the average real-world R script. See the [benchmarks](https://flowr-analysis.github.io/flowr/wiki/stats/benchmark) for more information,
-  and consult the [wiki pages](${doc_files_1.FlowrWikiBaseRef}/Dataflow-Graph) for more details on the dataflow graph.
+  and consult the ${ctx.linkPage('wiki/Dataflow Graph', 'wiki pages')} for more details on the dataflow graphs as well as call graphs.
 
 ${(0, doc_general_1.prefixLines)((0, doc_structure_1.details)('Example: Generating a dataflow graph with flowR', `
 You can investigate flowR's analyses using the [REPL](${doc_files_1.FlowrWikiBaseRef}/Interface#using-the-repl).

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

@@ -18,7 +18,7 @@ const environment_1 = require("../../dataflow/environments/environment");
  * ```
  */
 function codeBlock(language, code) {
-    return `\n\`\`\`${language}\n${code?.trim() ?? ''}\n\`\`\`\n`;
+    return `\n\`\`\`${language}\n${code?.trimEnd() ?? ''}\n\`\`\`\n`;
 }
 /**
  * Produces an inline code span in markdown format.

package/documentation/doc-util/doc-dfg.d.ts

@@ -15,6 +15,7 @@ export interface PrintDataflowGraphOptions {
     readonly exposeResult?: boolean;
     readonly switchCodeAndGraph?: boolean;
     readonly simplified?: boolean;
+    readonly callGraph?: boolean;
 }
 /**
  * Visualizes a side effect for documentation purposes.

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

@@ -14,6 +14,7 @@ const time_1 = require("../../util/text/time");
 const doc_files_1 = require("./doc-files");
 const doc_code_1 = require("./doc-code");
 const flowr_analyzer_context_1 = require("../../project/context/flowr-analyzer-context");
+const call_graph_1 = require("../../dataflow/graph/call-graph");
 /**
  * Visualizes the dataflow graph as a mermaid graph inside a markdown code block.
  * Please use this only for documentation purposes, for programmatic usage use {@link graphToMermaid} directly.
@@ -44,7 +45,7 @@ function formatSideEffect(ef) {
  * This function returns a markdown string containing the dataflow graph as a mermaid code block,
  * along with the R code itself in a collapsible section.
  */
-async function printDfGraphForCode(parser, code, { simplified = false, mark, showCode = true, codeOpen = false, exposeResult, switchCodeAndGraph = false } = {}) {
+async function printDfGraphForCode(parser, code, { callGraph = false, simplified = false, mark, showCode = true, codeOpen = false, exposeResult, switchCodeAndGraph = false } = {}) {
     const now = performance.now();
     const result = await (0, default_pipelines_1.createDataflowPipeline)(parser, {
         context: (0, flowr_analyzer_context_1.contextFromInput)(code)
@@ -54,8 +55,10 @@ async function printDfGraphForCode(parser, code, { simplified = false, mark, sho
         (0, assert_1.guard)(showCode, 'can not switch code and graph if code is not shown');
     }
     const metaInfo = `The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parse and normalize, using the [${parser.name}](${doc_files_1.FlowrWikiBaseRef}/Engines) engine) within the generation environment.`;
-    const dfGraph = printDfGraph(result.dataflow.graph, mark, simplified);
+    const graph = callGraph ? (0, call_graph_1.computeCallGraph)(result.dataflow.graph) : result.dataflow.graph;
+    const dfGraph = printDfGraph(graph, mark, simplified);
     const simplyText = simplified ? '(simplified) ' : '';
+    const graphName = callGraph ? 'Call Graph' : 'Dataflow Graph';
     let resultText = '\n\n';
     if (showCode) {
         const codeText = (0, doc_code_1.codeBlock)('r', code);
@@ -63,10 +66,10 @@ async function printDfGraphForCode(parser, code, { simplified = false, mark, sho
         resultText += `
 <details${codeOpen ? ' open' : ''}>
 
-<summary style="color:gray">${switchCodeAndGraph ? `${simplyText}Dataflow Graph of the R Code` : `R Code of the ${simplyText}Dataflow Graph`}</summary>
+<summary style="color:gray">${switchCodeAndGraph ? `${simplyText}${graphName} of the R Code` : `R Code of the ${simplyText}${graphName}`}</summary>
 
 ${metaInfo} ${mark ? `The following marks are used in the graph to highlight sub-parts (uses ids): {${[...mark].join(', ')}}.` : ''}
-We encountered ${result.dataflow.graph.unknownSideEffects.size > 0 ? 'unknown side effects (with ids: ' + [...result.dataflow.graph.unknownSideEffects].map(formatSideEffect).join(', ') + ')' : 'no unknown side effects'} during the analysis.
+We encountered ${graph.unknownSideEffects.size > 0 ? 'unknown side effects (with ids: ' + [...graph.unknownSideEffects].map(formatSideEffect).join(', ') + ')' : 'no unknown side effects'} during the analysis.
 
 ${switchCodeAndGraph ? dfGraph : codeText}
 

package/documentation/doc-util/doc-query.d.ts

@@ -20,6 +20,7 @@ export interface QueryDocumentation {
     readonly type: 'virtual' | 'active';
     readonly shortDescription: string;
     readonly functionName: string;
+    /** Path to the file implementing the query function, the wiki generation will fail if this isn't found */
     readonly functionFile: string;
     readonly buildExplanation: (shell: RShell, ctx: GeneralDocContext) => Promise<string>;
 }

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

@@ -35,7 +35,7 @@ ${(0, doc_code_1.codeBlock)('json', collapseQuery ? str.split('\n').join(' ').re
 
 ${(function () {
         if ((queries.length === 1 && Object.keys(queries[0]).length === 1) || shorthand) {
-            return `(This query can be shortened to \`@${queries[0].type}${shorthand ? ' ' + shorthand : ''}\` when used within the REPL command ${(0, doc_cli_option_1.getReplCommand)('query')}).`;
+            return `(This can be shortened to \`@${queries[0].type}${shorthand ? ' ' + shorthand : ''}\` when used with the REPL command ${(0, doc_cli_option_1.getReplCommand)('query')}).`;
         }
         else {
             return '';

package/documentation/doc-util/doc-repl.d.ts

@@ -18,6 +18,7 @@ export interface DocumentReplCommand {
     description: string;
 }
 /**
- *
+ * Creates a documented REPL session for the given commands.
+ * This is intended for documentation purposes.
  */
 export declare function documentReplSession(parser: KnownParser, commands: readonly DocumentReplCommand[], options?: DocumentReplSessionOptions): Promise<string>;

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

@@ -42,8 +42,16 @@ function printReplHelpAsMarkdownTable() {
 ${scriptHelp.sort().join('\n')}
 `;
 }
+function dropAnsiEscapeCodesAndCodeTags(input) {
+    // eslint-disable-next-line no-control-regex
+    return input.replace(/\x1B\[[0-9;]*[mK]/g, '')
+        .replace(/<\/?code>/g, '')
+        .replace(/\**([^*]+)\**/g, '$1')
+        .replace(/_([^_]+)_/g, '$1');
+}
 /**
- *
+ * Creates a documented REPL session for the given commands.
+ * This is intended for documentation purposes.
  */
 async function documentReplSession(parser, commands, options) {
     const collect = [];
@@ -52,10 +60,10 @@ async function documentReplSession(parser, commands, options) {
         const collectingOutput = {
             formatter: ansi_1.voidFormatter,
             stdout(msg) {
-                entry.lines.push(msg);
+                entry.lines.push(dropAnsiEscapeCodesAndCodeTags(msg));
             },
             stderr(msg) {
-                entry.lines.push(msg);
+                entry.lines.push(dropAnsiEscapeCodesAndCodeTags(msg));
             }
         };
         const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder()

package/documentation/wiki-analyzer.js

@@ -148,6 +148,8 @@ Likewise, ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'peekNormalize', { codeFon
 Again, ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'peekDataflow', { codeFont: true, realNameWrapper: 'i' })} allows you to inspect the dataflow graph if it was already computed (but without triggering a computation).
 * ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'controlflow')} to compute the [Control Flow Graph](${doc_files_1.FlowrWikiBaseRef}/Control%20Flow%20Graph)\\
 Also, ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'peekControlflow', { codeFont: true, realNameWrapper: 'i' })} returns the control flow graph if it was already computed but without triggering a computation.
+* ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'callGraph')} to compute the ${ctx.linkPage('wiki/Dataflow Graph', 'call graph', 'perspectives-cg')} of the analyzed code\\
+Likewise, ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'peekCallGraph', { codeFont: true, realNameWrapper: 'i' })} allows you to inspect the call graph if it was already computed (but without triggering a computation).
 * ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'query')} to run [queries](${doc_files_1.FlowrWikiBaseRef}/Query-API) on the analyzed code.
 * ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'runSearch')} to run a search query on the analyzed code using the [search API](${doc_files_1.FlowrWikiBaseRef}/Search%20API)
 

package/documentation/wiki-dataflow-graph.js

@@ -37,6 +37,7 @@ const environment_builder_1 = require("../../test/functionality/_helper/dataflow
 const flowr_analyzer_builder_1 = require("../project/flowr-analyzer-builder");
 const flowr_analyzer_context_1 = require("../project/context/flowr-analyzer-context");
 const doc_maker_1 = require("./wiki-mk/doc-maker");
+const flowr_analyzer_1 = require("../project/flowr-analyzer");
 async function subExplanation(parser, { description, code, expectedSubgraph }) {
     expectedSubgraph = await (0, doc_dfg_1.verifyExpectedSubgraph)(parser, code, expectedSubgraph);
     const marks = [];
@@ -70,6 +71,7 @@ async function explanation({ name, type, description, code, expectedSubgraph },
     await (0, doc_dfg_1.verifyExpectedSubgraph)(parser, code, expectedSubgraph);
     return `
 <a id='${name.toLowerCase().replaceAll(' ', '-')}'> </a>
+<a id='${String(type).toLowerCase().replaceAll(' ', '-')}-vertex'> </a>
 ### ${index}) ${name}
 
 Type: \`${type}\` (this is the bit-flag value, e.g., when looking at the serialization)
@@ -425,7 +427,7 @@ As you can see, _flowR_ is able to recognize that the initial definition of \`x\
             name: 'Function Definition Vertex',
             type: vertex_1.VertexType.FunctionDefinition,
             description: `
-Defining a function does do a lot of things: 1) it creates a new scope, 2) it may introduce parameters which act as promises and which are only evaluated if they are actually required in the body, 3) it may access the enclosing environments and the callstack.
+Defining a function does do a lot of things:  1) it creates a new scope,  2) it may introduce parameters which act as promises and which are only evaluated if they are actually required in the body,  3) it may access the enclosing environments and the callstack.
 The vertex object in the dataflow graph stores multiple things, including all exit points, the enclosing environment if necessary, and the information of the subflow (the "body" of the function).
 
 ${ctx.hierarchy('DataflowGraphVertexFunctionDefinition')}
@@ -434,7 +436,6 @@ ${ctx.hierarchy('DataflowFunctionFlowInformation')}
 And if you are interested in the exit points, they are defined like this:
 ${ctx.hierarchy('ExitPoint')}
 
-
 Whenever we visualize a function definition, we use a dedicated node to represent the anonymous function object,
 and a subgraph (usually with the name \`"function <id>"\`) to encompass the body of the function (they are linked with a dotted line).
 
@@ -498,7 +499,7 @@ Besides this being a theoretically "shorter" way of defining a function, this be
 
 `,
             code: 'function() 1',
-            expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().defineFunction('1@function', [0], { graph: new Set('0'), in: [], out: [], unknownReferences: [], entryPoint: 0, environment: (0, environment_builder_1.defaultEnv)() })
+            expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().defineFunction('1@function', [0], { hooks: [], graph: new Set('0'), in: [{ nodeId: 0, controlDependencies: [], type: identifier_1.ReferenceType.Constant, name: undefined }], out: [], unknownReferences: [], entryPoint: 0, environment: (0, environment_builder_1.defaultEnv)() })
         }, []]);
     const results = [];
     let i = 0;
@@ -581,7 +582,9 @@ However, nested definitions can carry it (in the nested case, \`x\` is defined b
             name: 'Calls Edge',
             type: edge_1.EdgeType.Calls,
             description: `Link the [function call](#function-call-vertex) to the [function definition](#function-definition-vertex) that is called. To find all called definitions, 
-		please use the ${ctx.link(dfg_get_origin_1.getOriginInDfg.name)} function, as explained in [working with the dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Working%20with%20the%20Dataflow%20Graph).`,
+		please use the ${ctx.link(dfg_get_origin_1.getOriginInDfg.name)} function, as explained in ${ctx.linkPage('wiki/Dataflow Graph', 'working with the dataflow graph', 'Working-with-the-Dataflow-Graph')}.
+		If you are interested in the call graph, refer to ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'callGraph')} and consult the ${ctx.linkPage('wiki/Dataflow Graph', 'call graph wiki', 'perspectives-cg')} for more information.
+		`,
             code: 'foo <- function() {}\nfoo()',
             expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().calls('2@foo', '1@function')
         }, []]);
@@ -747,6 +750,8 @@ In summary, we discuss the following topics:
 - [Control Dependencies](#control-dependencies)
 - [Dataflow Information](#dataflow-information)
 	- [Unknown Side Effects](#unknown-side-effects)
+- [Perspectives on the Dataflow Graph](#perspectives)
+    - [Call Graph Perspective](#perspectives-cg)
 - [Working with the Dataflow Graph](#dfg-working)
 
 Please be aware that the accompanied [dataflow information](#dataflow-information) (${ctx.link('DataflowInformation')}) returned by _flowR_ contains things besides the graph,
@@ -761,6 +766,8 @@ wiki page if you are unsure.
 > you can either use the [Visual Studio Code extension](${doc_files_1.FlowrVsCode}) or the ${ctx.replCmd('dataflow*')}
 > command in the REPL (see the ${ctx.linkPage('wiki/Interface', 'Interface wiki page')} for more information). 
 > There is also a simplified perspective available with ${ctx.replCmd('dataflowsimple*')} that does not show everything but is easier to read.
+> For small graphs, you can also use ${ctx.replCmd('dataflowascii')} to print the graph as ASCII art.
+>
 > 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 ${ctx.linkM(graph_1.DataflowGraph, 'fromJson', { realNameWrapper: 'i', codeFont: true })} to retrieve the graph from the JSON representation.
@@ -821,7 +828,7 @@ ${(0, doc_general_1.prefixLines)((0, doc_code_1.codeBlock)('ts', `const name = $
 
 ${(0, doc_structure_1.section)('Vertices', 2, 'vertices')}
 
-1. ${(0, doc_data_dfg_util_1.getAllVertices)().map(([k, v], index) => `[\`${k}\`](#${index + 1}-${v.toLowerCase().replace(/\s/g, '-')}-vertex)`).join('\n1. ')}
+1. ${(0, doc_data_dfg_util_1.getAllVertices)().map(([k, v]) => `[\`${k}\`](#${v.toLowerCase().replace(/\s/g, '-')}-vertex)`).join('\n1. ')}
 
 ${await getVertexExplanations(treeSitter, ctx)}
 
@@ -949,18 +956,55 @@ Additionally, we express this by a ${linkEdgeName(edge_1.EdgeType.Reads)} edge.
 	`;
             })()}
  
+${(0, doc_structure_1.section)('Perspectives on the Dataflow Graph', 2, 'perspectives')}
+
+For certain questions, handling the *full* dataflow graph may be too complex or unnecessary, given that you might have to consider edge interactions, or trace
+transitive relationships by yourself.
+Perspectives are simplified views on the dataflow graph, tailored to specific questions, which still comply with the ${ctx.link(graph_1.DataflowGraph)} interface
+so you can use them as drop-in replacements for the full dataflow graph. Although, please be aware that this does not mean that every function will work correctly&mdash;a
+call graph will no longer contain information on variables, for example.
+
+${(0, doc_structure_1.section)('Call Graphs', 3, 'perspectives-cg')}
+
+These are simplified views on the dataflow graph, following the ${ctx.link('CallGraph')} type.
+It can be obtained, e.g., by ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'callGraph')}.
+These graphs only contain function definitions and function calls as vertices, and ${linkEdgeName(edge_1.EdgeType.Calls)} edges.
+Consider the following example:
+
+${(0, doc_code_1.codeBlock)('r', 'f <- function() f()')}
+
+The resulting call graph looks like this:
+
+${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'f <- function() f()', { callGraph: true })}
+
+Please note, that, due to the over-approximative nature of call-graphs, the call-graph may label some function calls that are *not*
+marked as such in the full dataflow graph (which may have more precise information).
+For example, if we call an unknown alias:
+
+${(0, doc_code_1.codeBlock)('r', 'alias <- unknown\nalias(print)')}
+
+The resulting call graph looks like this:
+
+${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'alias <- unknown\nalias()', { callGraph: true })}
+
+Here, \`unknown\` is a function call, while it is a symbol in the full dataflow graph (as we cannot resolve it):
+
+${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'alias <- unknown\nalias()', { callGraph: false })}
+
+
 ${(0, doc_structure_1.section)('Working with the Dataflow Graph', 2, 'dfg-working')}
 
 The ${ctx.link('DataflowInformation')} is the core result of _flowR_ and summarizes a lot of information.
 Depending on what you are interested in, there exists a plethora of functions and queries to help you out, answering the most important questions:
 
-* The **[Query API](${doc_files_1.FlowrWikiBaseRef}/Query%20API)** provides many functions to query the dataflow graph for specific information (dependencies, calls, slices, clusters, ...)
-* The **[Search API](${doc_files_1.FlowrWikiBaseRef}/Search%20API)** allows you to search for specific vertices or edges in the dataflow graph or the original program
-* ${ctx.link(node_id_1.recoverName.name)} and ${ctx.link(node_id_1.recoverContent.name)} to get the name or content of a vertex in the dataflow graph
-* ${ctx.link(alias_tracking_1.resolveIdToValue.name)} to resolve the value of a variable or id (if possible, see [below](#dfg-resolving-values))
-* ${ctx.link(edge_1.edgeIncludesType.name)} to check if an edge includes a specific type and ${ctx.link(edge_1.splitEdgeTypes.name)} to split the bitmask of edges into its types (see [below](#dfg-resolving-values))
-* ${ctx.link(identify_link_to_last_call_relation_1.getValueOfArgument.name)} to get the (syntactical) value of an argument in a function call 
-* ${ctx.link(dfg_get_origin_1.getOriginInDfg.name)} to get information about where a read, call, ... comes from (see [below](#dfg-resolving-values))
+* The **${ctx.linkPage('wiki/Query API')}** provides many functions to query the dataflow graph for specific information (dependencies, calls, slices, clusters, ...)
+* The **${ctx.linkPage('wiki/Search API')}** allows you to search for specific vertices or edges in the dataflow graph or the original program
+* ${ctx.link(node_id_1.recoverName)} and ${ctx.link(node_id_1.recoverContent)} to get the name or content of a vertex in the dataflow graph
+* ${ctx.link(alias_tracking_1.resolveIdToValue)} to resolve the value of a variable or id (if possible, see [below](#dfg-resolving-values))
+* ${ctx.link(alias_tracking_1.getAliases)} to get all (potentially currently) aliases of a given definition
+* ${ctx.link(edge_1.edgeIncludesType)} to check if an edge includes a specific type and ${ctx.link(edge_1.splitEdgeTypes)} to split the bitmask of edges into its types (see [below](#dfg-resolving-values))
+* ${ctx.link(identify_link_to_last_call_relation_1.getValueOfArgument)} to get the (syntactical) value of an argument in a function call 
+* ${ctx.link(dfg_get_origin_1.getOriginInDfg)} to get information about where a read, call, ... comes from (see [below](#dfg-resolving-values))
 
 Some of these functions have been explained in their respective wiki pages. However, some are part of the [Dataflow Graph API](${doc_files_1.FlowrWikiBaseRef}/Dataflow-Graph) and so we explain them here.
 If you are interested in which features we support and which features are still to be worked on, please refer to our [capabilities](${doc_files_1.FlowrWikiBaseRef}/Capabilities) page.
@@ -970,12 +1014,12 @@ ${(0, doc_structure_1.section)('Resolving Values', 3, 'dfg-resolving-values')}
 FlowR supports a [configurable](${doc_files_1.FlowrWikiBaseRef}/Interface#configuring-flowr) level of value tracking&mdash;all with the goal of knowing the static value domain of a variable.
 These capabilities are exposed by the [resolve value Query](${doc_files_1.FlowrWikiBaseRef}/Query-API#resolve-value-query) and backed by two important functions:
 
-${ctx.link(alias_tracking_1.resolveIdToValue.name)} provides an environment-sensitive (see ${ctx.link('REnvironmentInformation')})
+${ctx.link(alias_tracking_1.resolveIdToValue)} provides an environment-sensitive (see ${ctx.link('REnvironmentInformation')})
 value resolution depending on if the environment is provided.
-The idea of ${ctx.link(alias_tracking_1.resolveIdToValue.name)} is to provide a compromise between precision and performance, to
+The idea of ${ctx.link(alias_tracking_1.resolveIdToValue)} is to provide a compromise between precision and performance, to
 be used _during_ and _after_ the core analysis. After the dataflow analysis completes, there are much more expensive queries possible (such as the resolution of the data frame shape, see the [Query API](${doc_files_1.FlowrWikiBaseRef}/Query-API)).
 
-Additionally, to ${ctx.link(alias_tracking_1.resolveIdToValue.name)}, we offer the aforementioned ${ctx.link(identify_link_to_last_call_relation_1.getValueOfArgument.name)} to retrieve the value of an argument in a function call.
+Additionally, to ${ctx.link(alias_tracking_1.resolveIdToValue)}, we offer the aforementioned ${ctx.link(identify_link_to_last_call_relation_1.getValueOfArgument)} to retrieve the value of an argument in a function call.
 Be aware, that this function is currently not optimized for speed, so if you frequently require the values of multiple arguments of the same function call, you may want to open [an issue](${doc_issue_1.NewIssueUrl}) to request support for resolving
 multiple arguments at once.
 
@@ -1019,7 +1063,6 @@ ${['SimpleOrigin', 'FunctionCallOrigin', 'BuiltInFunctionOrigin'].sort().map(key
 Please note, the current structure of this function is biased by what implementations already exist in flowR.
 Hence, we do not just track definitions and constants, but also the origins of function calls, albeit we do not yet track the origins of values (only resorting to
 a constant origin). If you are confused by this please start a discussion&mdash;in a way we are still deciding on a good API for this.
-
 	`;
         })()}
 

package/documentation/wiki-interface.js

@@ -139,6 +139,10 @@ the REPL will re-use previously obtained information and not re-parse the code a
 		`
     })}
 
+Generally, many commands offer shortcut versions in the REPL. Many queries, for example, offer a shortened format (see the example below).
+Of special note, the ${ctx.linkPage('wiki/Query API', 'Config Query', 'Config-Query')}
+can be used to also modify the currently active configuration of _flowR_ within the REPL (see the ${ctx.linkPage('wiki/Query API', 'wiki page', 'Config-Query')} for more information).
+
 ### Example: Retrieving the Dataflow Graph
 
 To retrieve a URL to the [mermaid](https://mermaid.js.org/) diagram of the dataflow of a given expression, 
@@ -149,6 +153,13 @@ ${await (0, doc_repl_1.documentReplSession)(parser, [{
             description: `Retrieve the dataflow graph of the expression \`y <- 1 + x\`. It looks like this:\n${await (0, doc_dfg_1.printDfGraphForCode)(parser, 'y <- 1 + x')}`
         }])}
 
+For small graphs like this, ${ctx.replCmd('dataflowascii')} also provides an ASCII representation directly in the REPL:
+
+${await (0, doc_repl_1.documentReplSession)(parser, [{
+            command: ':df! y <- 1 + x',
+            description: 'Retrieve the dataflow graph of the expression `y <- 1 + x` as ASCII art.'
+        }], { openOutput: true })}
+
 For the slicing with ${ctx.replCmd('slicer')}, you have access to the same [magic comments](#slice-magic-comments) as with the [slice request](#message-request-slice).
 
 ### Example: Interfacing with the File System
@@ -172,6 +183,22 @@ ${(0, doc_code_1.codeBlock)('r', (0, doc_files_1.getFileContentFromRoot)('test/t
 As _flowR_ directly transforms this AST the output focuses on being human-readable instead of being machine-readable. 
 		`
         }])}
+
+### Example: Run a Query
+
+You can run any query supported by _flowR_ using the ${ctx.replCmd('query')} command.
+For example, to obtain the shapes of all data frames in a given piece of code, you can run:
+${await (0, doc_repl_1.documentReplSession)(parser, [{
+            command: ':query @df-shape "x <- data.frame(a = 1:10, b = 1:10)\\ny <- x$a"',
+            description: 'Retrieve the shapes of all data frames in the given code.'
+        }], { openOutput: true })}
+To run the linter on a file, you can use (in this example, we just issue the \`dead-code\` linter on a small piece of code):
+${await (0, doc_repl_1.documentReplSession)(parser, [{
+            command: ':query @linter rules:dead-code "if(FALSE) x <- 2"',
+            description: 'Run the linter on the given code, with only the `dead-code` rule enabled.'
+        }], { openOutput: true })}
+
+For more information on the available queries, please check out the ${ctx.linkPage('wiki/Query API', 'Query API')}.
 `;
 }
 function explainConfigFile() {
@@ -443,20 +470,21 @@ Although far from being as detailed as the in-depth explanation of ${ctx.linkPag
 this wiki page explains how to interface with _flowR_ in more detail.
 In general, command line arguments and other options provide short descriptions on hover over.
 
-* [💬 Communicating with the Server](#communicating-with-the-server)
 * [💻 Using the REPL](#using-the-repl)
+* [💬 Communicating with the Server](#communicating-with-the-server)
 * [⚙️ Configuring FlowR](#configuring-flowr)
 * [⚒️ Writing Code](#writing-code)
 
+<a id='using-the-repl'></a>
+## 💻 Using the REPL
+
+${await explainRepl(treeSitter, ctx)}
+
 <a id='communicating-with-the-server'></a>
 ## 💬 Communicating with the Server
 
 ${await explainServer(shell)}
 
-<a id='using-the-repl'></a>
-## 💻 Using the REPL
-
-${await explainRepl(treeSitter, ctx)}
 
 <a id='configuring-flowr'></a>
 ## ⚙️ Configuring FlowR

package/documentation/wiki-mk/doc-context.d.ts

@@ -186,8 +186,9 @@ export interface GeneralDocContext {
      * Creates a link to the `wiki/Setup` wiki page with the link text `Setup`.
      * @param pageName - The name of the wiki page to link to.
      * @param linkText - Optional text to display for the link. If not provided, the page name will be used.
+     * @param segment  - An optional segment within the page to link to (e.g., a header anchor).
      */
-    linkPage(pageName: ValidWikiDocumentTargetsNoSuffix, linkText?: string): string;
+    linkPage(pageName: ValidWikiDocumentTargetsNoSuffix, linkText?: string, segment?: string): string;
     /**
      * Generates a link to a code file in the code base.
      * @param path       - The path to the code file.

package/documentation/wiki-mk/doc-context.js

@@ -81,10 +81,10 @@ function makeDocContextForTypes(shell, ...rootFolders) {
                 inlineTypes
             });
         },
-        linkPage(pageName, linkText) {
+        linkPage(pageName, linkText, segment) {
             const text = linkText ?? pageName.split('/').pop() ?? pageName;
             const link = pageName.toLowerCase().replace(/ /g, '-');
-            return `[${text}](${doc_files_1.FlowrGithubRef}/${link})`;
+            return `[${text}](${doc_files_1.FlowrGithubRef}/${link}${segment ? `#${segment}` : ''})`;
         },
         linkCode(path, lineNumber) {
             const lnk = lineNumber ? `${path.toString()}#L${lineNumber}` : path.toString();

package/documentation/wiki-mk/doc-maker.js

@@ -11,7 +11,7 @@ const DefaultReplacementPatterns = [
     // eslint-disable-next-line no-irregular-whitespace -- we may produce it in output
     [/[0-9]+(\.[0-9]+)?( |\s*)?ms/g, ''],
     [/tmp[%A-Za-z0-9-]+/g, ''],
-    [/"(timing|searchTimeMs|processTimeMs|id|treeSitterId)":\s*[0-9]+(\.[0-9])?,?/g, ''],
+    [/"?(timing|searchTimeMs|processTimeMs|id|treeSitterId)"?:\s*[0-9]+(\.[0-9])?,?/g, ''],
     [/"format":"compact".+/gmius, ''],
     [/%%\s*\d*-+/g, ''],
     [/"[rR]": "\d+\.\d+\.\d+.*?"/g, ''],
@@ -19,8 +19,9 @@ const DefaultReplacementPatterns = [
     [/v\d+\.\d+\.\d+/g, ''],
     // clean paths
     [/%2Fhome%2F([a-zA-Z0-9._-]+%2F)*/g, ''],
-    // async wrapper depends on whether the promise got forfilled already
-    [/async|%20/g, '']
+    // async wrapper depends on whether the promise got fulfilled already
+    [/async|%20/g, ''],
+    [/\s*Copied mermaid url to clipboard\s*\([^)]+\)/gmi, '']
 ];
 /**
  * Abstract base class for generating wiki files.

package/documentation/wiki-normalized-ast.js

@@ -17,6 +17,7 @@ const flowr_analyzer_1 = require("../project/flowr-analyzer");
 const flowr_analyzer_builder_1 = require("../project/flowr-analyzer-builder");
 const flowr_file_1 = require("../project/context/flowr-file");
 const doc_maker_1 = require("./wiki-mk/doc-maker");
+const roxygen_parse_1 = require("../r-bridge/roxygen2/roxygen-parse");
 async function quickNormalizedAstMultipleFiles() {
     const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder()
         .setEngine('tree-sitter')
@@ -95,6 +96,11 @@ The following segments intend to give you an overview of how to work with the no
 * [How to get a Normalized AST](#how-to-get-a-normalized-ast)
 * [Visitors and Folds](#visitors-and-folds)
 
+> [!TIP]
+> If you want to get more information on roxygen comments attached to AST nodes,
+> check out ${ctx.link(roxygen_parse_1.parseRoxygenCommentsOfNode)}.
+
+
 ## How to Get a Normalized AST
 
 As explained alongside the [Interface](${doc_files_1.FlowrWikiBaseRef}/Interface#creating-flowr-analyses) wiki page, you can use an instance of