@eagleoutice/flowr 2.5.0 → 2.6.1

package/dataflow/extractor.js

@@ -59,14 +59,14 @@ exports.processors = {
     }
 };
 function resolveLinkToSideEffects(ast, graph) {
-    let cfg = undefined;
+    let cf = undefined;
     for (const s of graph.unknownSideEffects) {
         if (typeof s !== 'object') {
             continue;
         }
-        cfg ??= (0, extract_cfg_1.extractCfgQuick)(ast).graph;
+        cf ??= (0, extract_cfg_1.extractCfgQuick)(ast);
         /* this has to change whenever we add a new link to relations because we currently offer no abstraction for the type */
-        const potentials = (0, identify_link_to_last_call_relation_1.identifyLinkToLastCallRelation)(s.id, cfg, graph, s.linkTo);
+        const potentials = (0, identify_link_to_last_call_relation_1.identifyLinkToLastCallRelation)(s.id, cf?.graph, graph, s.linkTo);
         for (const pot of potentials) {
             graph.addEdge(s.id, pot, edge_1.EdgeType.Reads);
         }
@@ -74,6 +74,7 @@ function resolveLinkToSideEffects(ast, graph) {
             graph.unknownSideEffects.delete(s);
         }
     }
+    return cf;
 }
 /**
  * This is the main function to produce the dataflow graph from a given request and normalized AST.
@@ -114,7 +115,8 @@ function produceDataFlowGraph(parser, request, completeAst, config) {
     }
     // finally, resolve linkages
     (0, built_in_function_definition_1.updateNestedFunctionCalls)(df.graph, df.environment);
-    resolveLinkToSideEffects(completeAst, df.graph);
-    return df;
+    const cfgQuick = resolveLinkToSideEffects(completeAst, df.graph);
+    // performance optimization: return cfgQuick as part of the result to avoid recomputation
+    return { ...df, cfgQuick };
 }
 //# sourceMappingURL=extractor.js.map

package/dataflow/fn/higher-order-function.d.ts

@@ -0,0 +1,9 @@
+import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
+import type { DataflowGraph } from '../graph/graph';
+/**
+ * Determines whether the function with the given id is a higher-order function, i.e.,
+ * either takes a function as an argument or (may) returns a function.
+ * If the return is an identity, e.g., `function(x) x`, this is not considered higher-order,
+ * if no function is passed as an argument.
+ */
+export declare function isHigherOrder(id: NodeId, graph: DataflowGraph): boolean;

package/dataflow/fn/higher-order-function.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHigherOrder = isHigherOrder;
+const vertex_1 = require("../graph/vertex");
+const assert_1 = require("../../util/assert");
+const edge_1 = require("../graph/edge");
+const alias_tracking_1 = require("../eval/resolve/alias-tracking");
+const config_1 = require("../../config");
+const r_function_call_1 = require("../../r-bridge/lang-4.x/ast/model/nodes/r-function-call");
+const general_1 = require("../eval/values/general");
+function isAnyReturnAFunction(def, graph) {
+    const workingQueue = def.exitPoints.map(d => graph.getVertex(d, true)).filter(assert_1.isNotUndefined);
+    const seen = new Set();
+    while (workingQueue.length > 0) {
+        const current = workingQueue.pop();
+        if (seen.has(current.id)) {
+            continue;
+        }
+        seen.add(current.id);
+        if ((0, vertex_1.isFunctionDefinitionVertex)(current)) {
+            return true;
+        }
+        const next = graph.outgoingEdges(current.id) ?? [];
+        for (const [t, { types }] of next) {
+            if ((0, edge_1.edgeIncludesType)(types, edge_1.EdgeType.Returns)) {
+                const v = graph.getVertex(t, true);
+                if (v) {
+                    workingQueue.push(v);
+                }
+            }
+        }
+    }
+    return false;
+}
+function inspectCallSitesArgumentsFns(def, graph) {
+    const callSites = graph.ingoingEdges(def.id);
+    for (const [callerId, { types }] of callSites ?? []) {
+        if (!(0, edge_1.edgeIncludesType)(types, edge_1.EdgeType.Calls)) {
+            continue;
+        }
+        const caller = graph.getVertex(callerId, true);
+        if (!caller || !(0, vertex_1.isFunctionCallVertex)(caller)) {
+            continue;
+        }
+        for (const arg of caller.args) {
+            if (arg === r_function_call_1.EmptyArgument) {
+                continue;
+            }
+            const value = (0, general_1.valueSetGuard)((0, alias_tracking_1.resolveIdToValue)(arg.nodeId, { graph, idMap: graph.idMap, resolve: config_1.VariableResolve.Alias, full: true }));
+            if (value?.elements.some(e => e.type === 'function-definition')) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Determines whether the function with the given id is a higher-order function, i.e.,
+ * either takes a function as an argument or (may) returns a function.
+ * If the return is an identity, e.g., `function(x) x`, this is not considered higher-order,
+ * if no function is passed as an argument.
+ */
+function isHigherOrder(id, graph) {
+    const vert = graph.getVertex(id);
+    if (!vert || !(0, vertex_1.isFunctionDefinitionVertex)(vert)) {
+        return false;
+    }
+    // 1. check whether any of the exit types is a function
+    if (isAnyReturnAFunction(vert, graph)) {
+        return true;
+    }
+    // 2. check whether any of the callsites passes a function
+    return inspectCallSitesArgumentsFns(vert, graph);
+}
+//# sourceMappingURL=higher-order-function.js.map

package/dataflow/graph/dataflowgraph-builder.d.ts

@@ -7,8 +7,7 @@ import type { DataflowGraphVertexAstLink, DataflowGraphVertexUse, FunctionOrigin
 import type { ControlDependency } from '../info';
 import type { LinkTo } from '../../queries/catalog/call-context-query/call-context-query-format';
 import type { FlowrSearchLike } from '../../search/flowr-search-builder';
-import type { Pipeline } from '../../core/steps/pipeline/pipeline';
-import type { FlowrSearchInput } from '../../search/flowr-search';
+import type { FlowrAnalysisProvider } from '../../project/flowr-analyzer';
 export declare function emptyGraph(idMap?: AstIdMap): DataflowGraphBuilder;
 export type DataflowGraphEdgeTarget = NodeId | (readonly NodeId[]);
 /**
@@ -103,9 +102,9 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      *
      * @param from - Either a node id or a query to find the node id.
      * @param to - Either a node id or a query to find the node id.
-     * @param data - The data to search in i.e. the dataflow graph.
+     * @param input - The input to search in i.e. the dataflow graph.
      */
-    readsQuery<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): this;
+    readsQuery(from: FromQueryParam, to: ToQueryParam, input: FlowrAnalysisProvider): Promise<this>;
     /**
      * Adds a **defined-by edge** with from as defined variable, and to
      * as a variable/function contributing to its definition.
@@ -118,7 +117,7 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      *
      * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters.
      */
-    definedByQuery<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): this;
+    definedByQuery(from: FromQueryParam, to: ToQueryParam, data: FlowrAnalysisProvider): Promise<this>;
     /**
      * Adds a **call edge** with from as caller, and to as callee.
      *
@@ -130,7 +129,7 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      *
      * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters.
      */
-    callsQuery<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): this;
+    callsQuery(from: FromQueryParam, to: ToQueryParam, data: FlowrAnalysisProvider): Promise<this>;
     /**
      * Adds a **return edge** with from as function, and to as exit point.
      *
@@ -142,7 +141,7 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      *
      * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters.
      */
-    returnsQuery<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): this;
+    returnsQuery(from: FromQueryParam, to: ToQueryParam, data: FlowrAnalysisProvider): Promise<this>;
     /**
      * Adds a **defines-on-call edge** with from as variable, and to as its definition
      *
@@ -154,7 +153,7 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      *
      * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters.
      */
-    definesOnCallQuery<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): this;
+    definesOnCallQuery(from: FromQueryParam, to: ToQueryParam, data: FlowrAnalysisProvider): Promise<this>;
     /**
      * Adds a **defined-by-on-call edge** with from as definition, and to as variable.
      *
@@ -166,7 +165,7 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      *
      * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters.
      */
-    definedByOnCallQuery<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): this;
+    definedByOnCallQuery(from: FromQueryParam, to: ToQueryParam, data: FlowrAnalysisProvider): Promise<this>;
     /**
      * Adds an **argument edge** with from as function call, and to as argument.
      *
@@ -178,7 +177,7 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      *
      * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters.
      */
-    argumentQuery<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): this;
+    argumentQuery(from: FromQueryParam, to: ToQueryParam, data: FlowrAnalysisProvider): Promise<this>;
     /**
      * Adds a **non-standard evaluation edge** with from as vertex, and to as vertex.
      *
@@ -190,7 +189,7 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      *
      * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters.
      */
-    nseQuery<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): this;
+    nseQuery(from: FromQueryParam, to: ToQueryParam, data: FlowrAnalysisProvider): Promise<this>;
     /**
      * Adds a **side-effect-on-call edge** with from as vertex, and to as vertex.
      *
@@ -202,7 +201,7 @@ export declare class DataflowGraphBuilder extends DataflowGraph {
      *
      * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters.
      */
-    sideEffectOnCallQuery<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): this;
+    sideEffectOnCallQuery(from: FromQueryParam, to: ToQueryParam, data: FlowrAnalysisProvider): Promise<this>;
     /**
      * explicitly overwrite the root ids of the graph,
      * this is just an easier variant in case you working with a lot of functions this saves you a lot of `false` flags.

package/dataflow/graph/dataflowgraph-builder.js

@@ -174,13 +174,13 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
         }
         return this.addEdge((0, node_id_1.normalizeIdToNumberIfPossible)(from), (0, node_id_1.normalizeIdToNumberIfPossible)(to), type);
     }
-    queryHelper(from, to, data, type) {
+    async queryHelper(from, to, data, type) {
         let fromId;
         if ('nodeId' in from) {
             fromId = from.nodeId;
         }
         else {
-            const result = (0, flowr_search_executor_1.runSearch)(from.query, data).getElements();
+            const result = (await (0, flowr_search_executor_1.runSearch)(from.query, data)).getElements();
             (0, assert_1.guard)(result.length === 1, `from query result should yield exactly one node, but yielded ${result.length}`);
             fromId = result[0].node.info.id;
         }
@@ -189,7 +189,7 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
             toIds = to.target;
         }
         else {
-            const result = (0, flowr_search_executor_1.runSearch)(to.query, data).getElements();
+            const result = (await (0, flowr_search_executor_1.runSearch)(to.query, data)).getElements();
             toIds = result.map(r => r.node.info.id);
         }
         return this.edgeHelper(fromId, toIds, type);
@@ -209,10 +209,10 @@ class DataflowGraphBuilder extends graph_1.DataflowGraph {
      *
      * @param from - Either a node id or a query to find the node id.
      * @param to - Either a node id or a query to find the node id.
-     * @param data - The data to search in i.e. the dataflow graph.
+     * @param input - The input to search in i.e. the dataflow graph.
      */
-    readsQuery(from, to, data) {
-        return this.queryHelper(from, to, data, edge_1.EdgeType.Reads);
+    readsQuery(from, to, input) {
+        return this.queryHelper(from, to, input, edge_1.EdgeType.Reads);
     }
     /**
      * Adds a **defined-by edge** with from as defined variable, and to

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

@@ -1,16 +1,13 @@
 import type { RShell } from '../../r-bridge/shell';
-import type { Queries, QueryResults, SupportedQueryTypes } from '../../queries/query';
-import { DEFAULT_DATAFLOW_PIPELINE } from '../../core/steps/pipeline/default-pipelines';
+import type { Queries, SupportedQueryTypes } from '../../queries/query';
 import type { SupportedVirtualQueryTypes } from '../../queries/virtual-query/virtual-queries';
 import type { VirtualCompoundConstraint } from '../../queries/virtual-query/compound-query';
-import type { PipelineOutput } from '../../core/steps/pipeline/pipeline';
-export interface ShowQueryOptions<Base extends SupportedQueryTypes> {
+export interface ShowQueryOptions {
     readonly showCode?: boolean;
     readonly collapseResult?: boolean;
     readonly collapseQuery?: boolean;
-    readonly addOutput?: (result: QueryResults<Base>, pipeline: PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>) => string;
 }
-export declare function showQuery<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>>(shell: RShell, code: string, queries: Queries<Base, VirtualArguments>, { showCode, collapseResult, collapseQuery, addOutput }?: ShowQueryOptions<Base>): Promise<string>;
+export declare function showQuery<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>>(shell: RShell, code: string, queries: Queries<Base, VirtualArguments>, { showCode, collapseResult, collapseQuery }?: ShowQueryOptions): Promise<string>;
 export interface QueryDocumentation {
     readonly name: string;
     readonly type: 'virtual' | 'active';

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

@@ -6,9 +6,6 @@ exports.registerQueryDocumentation = registerQueryDocumentation;
 exports.linkToQueryOfName = linkToQueryOfName;
 exports.tocForQueryType = tocForQueryType;
 exports.explainQueries = explainQueries;
-const query_1 = require("../../queries/query");
-const pipeline_executor_1 = require("../../core/pipeline-executor");
-const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
 const retriever_1 = require("../../r-bridge/retriever");
 const json_1 = require("../../util/json");
 const ansi_1 = require("../../util/text/ansi");
@@ -17,19 +14,12 @@ const doc_dfg_1 = require("./doc-dfg");
 const doc_code_1 = require("./doc-code");
 const time_1 = require("../../util/text/time");
 const query_print_1 = require("../../queries/query-print");
+const flowr_analyzer_builder_1 = require("../../project/flowr-analyzer-builder");
 const doc_cli_option_1 = require("./doc-cli-option");
-const config_1 = require("../../config");
-async function showQuery(shell, code, queries, { showCode, collapseResult, collapseQuery, addOutput = () => '' } = {}) {
+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, {
-        parser: shell,
-        request: (0, retriever_1.requestFromInput)(code)
-    }, config_1.defaultConfigOptions).allRemainingSteps();
-    const results = await Promise.resolve((0, query_1.executeQueries)({
-        dataflow: analysis.dataflow,
-        ast: analysis.normalize,
-        config: (0, config_1.cloneConfig)(config_1.defaultConfigOptions)
-    }, queries));
+    const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder((0, retriever_1.requestFromInput)(code)).setParser(shell).build();
+    const results = await analyzer.query(queries);
     const duration = performance.now() - now;
     const metaInfo = `
 The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parsing and normalization and the query) within the generation environment.
@@ -52,7 +42,7 @@ ${collapseResult ? ' <details> <summary style="color:gray">Show Results</summary
 
 _Results (prettified and summarized):_
 
-${(0, query_print_1.asciiSummaryOfQueryResult)(ansi_1.markdownFormatter, duration, results, analysis, queries)}
+${await (0, query_print_1.asciiSummaryOfQueryResult)(ansi_1.markdownFormatter, duration, results, analyzer, queries)}
 
 <details> <summary style="color:gray">Show Detailed Results as Json</summary>
 
@@ -75,8 +65,6 @@ ${await (0, doc_dfg_1.printDfGraphForCode)(shell, code, { switchCodeAndGraph: tr
 
 ${collapseResult ? '</details>' : ''}
 
-${addOutput(results, analysis)}
-
 	`;
 }
 exports.RegisteredQueries = {

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

@@ -11,7 +11,7 @@ const doc_docker_1 = require("./doc-docker");
 const prompt_1 = require("../../cli/repl/prompt");
 const doc_code_1 = require("./doc-code");
 const print_version_1 = require("../../cli/repl/print-version");
-const config_1 = require("../../config");
+const flowr_analyzer_builder_1 = require("../../project/flowr-analyzer-builder");
 function printHelpForScript(script, starredVersion) {
     let base = `| **${(0, doc_cli_option_1.getReplCommand)(script[0], false, starredVersion !== undefined)}** | ${script[1].description}`;
     if (starredVersion) {
@@ -52,7 +52,10 @@ async function documentReplSession(parser, commands, options) {
                 entry.lines.push(msg);
             }
         };
-        await (0, core_1.replProcessAnswer)(config_1.defaultConfigOptions, collectingOutput, command.command, parser, options?.allowRSessionAccess ?? false);
+        const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder()
+            .setParser(parser)
+            .build();
+        await (0, core_1.replProcessAnswer)(analyzer, collectingOutput, command.command, options?.allowRSessionAccess ?? false);
         collect.push(entry);
     }
     let result = '';

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

@@ -6,29 +6,26 @@ exports.registerQueryDocumentation = registerQueryDocumentation;
 exports.linkToQueryOfName = linkToQueryOfName;
 exports.tocForQueryType = tocForQueryType;
 exports.explainQueries = explainQueries;
-const pipeline_executor_1 = require("../../core/pipeline-executor");
-const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
 const retriever_1 = require("../../r-bridge/retriever");
 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/text/time");
-const flowr_search_executor_1 = require("../../search/flowr-search-executor");
 const flowr_search_printer_1 = require("../../search/flowr-search-printer");
 const node_id_1 = require("../../r-bridge/lang-4.x/ast/model/processing/node-id");
 const dfg_1 = require("../../util/mermaid/dfg");
-const config_1 = require("../../config");
+const flowr_analyzer_builder_1 = require("../../project/flowr-analyzer-builder");
 async function showSearch(shell, code, search, { collapseResult = true } = {}) {
     const now = performance.now();
-    const analysis = await new pipeline_executor_1.PipelineExecutor(default_pipelines_1.DEFAULT_DATAFLOW_PIPELINE, {
-        parser: shell,
-        request: (0, retriever_1.requestFromInput)(code)
-    }, config_1.defaultConfigOptions).allRemainingSteps();
-    const result = (0, flowr_search_executor_1.runSearch)(search, { ...analysis, config: config_1.defaultConfigOptions });
+    const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder((0, retriever_1.requestFromInput)(code))
+        .setParser(shell)
+        .build();
+    const result = await analyzer.runSearch(search);
     const duration = performance.now() - now;
     const metaInfo = `
 The search required _${(0, time_1.printAsMs)(duration)}_ (including parsing and normalization and the query) within the generation environment.
 	`.trim();
+    const dataflow = await analyzer.dataflow();
     return `
 
 ${(0, doc_code_1.codeBlock)('ts', (0, flowr_search_printer_1.flowrSearchToCode)(search))}
@@ -53,7 +50,7 @@ ${(0, doc_code_1.codeBlock)('json', JSON.stringify(search, null, 2))}
 ${collapseResult ? ' <details> <summary style="color:gray">Show Results</summary>' : ''}
 
 The query returns the following vetices (all references to \`x\` in the code):
-${result.getElements().map(({ node }) => `<b>${node.info.id} ('${(0, node_id_1.recoverContent)(node.info.id, analysis.dataflow.graph)}')</b> at L${(0, dfg_1.formatRange)(node.location)}`).join(', ')}
+${result.getElements().map(({ node }) => `<b>${node.info.id} ('${(0, node_id_1.recoverContent)(node.info.id, dataflow.graph)}')</b> at L${(0, dfg_1.formatRange)(node.location)}`).join(', ')}
 
 ${metaInfo}	
 

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

@@ -11,3 +11,7 @@ export interface BlockOptions {
 }
 export declare function block({ type, content }: BlockOptions): string;
 export declare function section(title: string, depth?: 1 | 2 | 3 | 4 | 5 | 6, anchor?: string): string;
+/**
+ * Supported pattern: `Name@link`
+ */
+export declare function collapsibleToc(content: Record<string, Record<string, Record<string, undefined> | undefined> | undefined>): string;

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

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.details = details;
 exports.block = block;
 exports.section = section;
+exports.collapsibleToc = collapsibleToc;
 const doc_general_1 = require("./doc-general");
 const mermaid_1 = require("../../util/mermaid/mermaid");
+const strings_1 = require("../../util/text/strings");
 function details(title, content, { color, open = false, hideIfEmpty = true, prefixInit = '' } = {}) {
     return hideIfEmpty && content.trim().length === 0 ? '' : `
 ${prefixInit}<details${open ? ' open' : ''}><summary style="${color ? 'color:' + color : ''}">${title}</summary>
@@ -23,4 +25,30 @@ ${(0, doc_general_1.prefixLines)(content, '> ')}
 function section(title, depth = 2, anchor = (0, mermaid_1.escapeId)(title)) {
     return `<h${depth} id="${anchor}">${title}</h${depth}>`;
 }
+function strToLink(str) {
+    const match = str.match(/^(.*?)@(.*)$/);
+    if (match) {
+        const [, name, link] = match;
+        return `[${name}](${link})`;
+    }
+    return `[${str}](#${(0, mermaid_1.escapeId)(str)})`;
+}
+/**
+ * Supported pattern: `Name@link`
+ */
+function collapsibleToc(content) {
+    let output = '';
+    for (const [section, subsections] of Object.entries(content)) {
+        output += `- ${strToLink(section)}\n`;
+        if (subsections) {
+            for (const [subsection, items] of Object.entries(subsections)) {
+                output += `  - ${strToLink(subsection)}  \n`;
+                if (items) {
+                    output += `    ${(0, strings_1.joinWithLast)(Object.keys(items).map(strToLink))}\n`;
+                }
+            }
+        }
+    }
+    return output;
+}
 //# sourceMappingURL=doc-structure.js.map

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

@@ -62,8 +62,12 @@ export declare function printHierarchy({ program, info, root, collapseFromNestin
 interface FnInfo {
     info: TypeElementInSource[];
     program: ts.Program;
+    dropLinesStart?: number;
+    dropLinesEnd?: number;
+    doNotAutoGobble?: boolean;
+    hideDefinedAt?: boolean;
 }
-export declare function printCodeOfElement({ program, info }: FnInfo, name: string): string;
+export declare function printCodeOfElement({ program, info, dropLinesEnd, dropLinesStart, doNotAutoGobble, hideDefinedAt }: FnInfo, name: string): string;
 /**
  * Create a short link to a type in the documentation
  * @param name      - The name of the type, e.g. `MyType`, may include a container, e.g.,`MyContainer::MyType` (this works with function nestings too)

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

@@ -387,14 +387,40 @@ function printHierarchy({ program, info, root, collapseFromNesting = 1, initialN
         return thisLine + (out ? '\n' + out : '');
     }
 }
-function printCodeOfElement({ program, info }, name) {
+function printCodeOfElement({ program, info, dropLinesEnd = 0, dropLinesStart = 0, doNotAutoGobble, hideDefinedAt }, name) {
     const node = info.find(e => e.name === name);
     if (!node) {
         console.error(`Could not find node ${name} when resolving function!`);
         return '';
     }
-    const code = node.node.getFullText(program.getSourceFile(node.node.getSourceFile().fileName));
-    return `${(0, doc_code_1.codeBlock)('ts', code)}\n<i>Defined at <a href="${getTypePathLink(node)}">${getTypePathLink(node, '.')}</a></i>\n`;
+    let code = node.node.getFullText(program.getSourceFile(node.node.getSourceFile().fileName)).trim();
+    if (dropLinesStart > 0 || dropLinesEnd > 0) {
+        const lines = code.split(/\n/g);
+        if (dropLinesStart + dropLinesEnd >= lines.length) {
+            return '';
+        }
+        code = lines.slice(dropLinesStart, lines.length - dropLinesEnd).join('\n');
+    }
+    if (!doNotAutoGobble) {
+        // gobble leading spaces
+        const lines = code.replaceAll('\t', '    ').split(/\n/g);
+        let gobble = Number.POSITIVE_INFINITY;
+        for (const line of lines) {
+            const match = line.match(/^(\s+)\S+/);
+            if (match) {
+                gobble = Math.min(gobble, match[1].length);
+            }
+        }
+        if (gobble !== Number.POSITIVE_INFINITY && gobble > 0) {
+            code = lines.map(line => line.startsWith(' '.repeat(gobble)) ? line.slice(gobble) : line).join('\n');
+        }
+    }
+    if (hideDefinedAt) {
+        return (0, doc_code_1.codeBlock)('ts', code);
+    }
+    else {
+        return `${(0, doc_code_1.codeBlock)('ts', code)}\n<i>Defined at <a href="${getTypePathLink(node)}">${getTypePathLink(node, '.')}</a></i>\n`;
+    }
 }
 function fuzzyCompare(a, b) {
     const aStr = a.toLowerCase().replace(/[^a-z0-9]/g, '-').trim();

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

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

package/documentation/print-analyzer-wiki.js

@@ -0,0 +1,137 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const shell_1 = require("../r-bridge/shell");
+const log_1 = require("../../test/functionality/_helper/log");
+const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
+const doc_types_1 = require("./doc-util/doc-types");
+const path_1 = __importDefault(require("path"));
+const flowr_analyzer_1 = require("../project/flowr-analyzer");
+const flowr_analyzer_builder_1 = require("../project/flowr-analyzer-builder");
+const doc_structure_1 = require("./doc-util/doc-structure");
+const doc_files_1 = require("./doc-util/doc-files");
+async function analyzerQuickExample() {
+    const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder()
+        .addRequestFromInput('x <- 1; print(x)')
+        .setEngine('tree-sitter')
+        .build();
+    // get the dataflow
+    const df = await analyzer.dataflow();
+    // obtain the identified loading order
+    console.log(analyzer.inspectContext().files.loadingOrder.getLoadingOrder());
+    // run a dependency query
+    const results = await analyzer.query([{ type: 'dependencies' }]);
+    return { analyzer, df, results };
+}
+async function getText(shell) {
+    const rversion = (await shell.usedRVersion())?.format() ?? 'unknown';
+    const types = (0, doc_types_1.getTypesFromFolder)({
+        rootFolder: path_1.default.resolve('src/'),
+        inlineTypes: doc_types_1.mermaidHide
+    });
+    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'analyzer', rVersion: rversion })}
+
+We are currently working on documenting the capabilities of the analyzer (with the plugins, their loading order, etc.). In general, the code documentation
+starting with the ${(0, doc_types_1.shortLink)(flowr_analyzer_1.FlowrAnalyzer.name, types.info)} and the ${(0, doc_types_1.shortLink)(flowr_analyzer_builder_1.FlowrAnalyzerBuilder.name, types.info)} 
+should be the best starting point.
+
+${(0, doc_structure_1.collapsibleToc)({
+        'Overview': undefined,
+        'Builder Configuration': undefined,
+        'Plugins': {
+            'Plugin Types': {
+                'Dependency Identification': undefined,
+                'Project Discovery': undefined,
+                'File Loading': undefined,
+                'Loading Order': undefined
+            },
+            'How to add a new plugin': undefined,
+            'How to add a new plugin type': undefined
+        },
+        'Context Information': {
+            'Files Context': undefined,
+            'Loading Order Context': undefined,
+            'Dependencies Context': undefined
+        },
+        'Analyzer Internals': undefined
+    })}
+
+
+${(0, doc_structure_1.section)('Overview', 2)}
+
+No matter whether you want to analyze a single R script, a couple of R notebooks, or a complete project,
+your journey starts with the ${(0, doc_types_1.shortLink)(flowr_analyzer_builder_1.FlowrAnalyzerBuilder.name, types.info)} (further described in [Builder Configuration](#builder-configuration) below).
+This builder allows you to configure the analysis in many different ways, for example, by specifying which files to analyze, which plugins to use, or
+what [Engine](${doc_files_1.FlowrWikiBaseRef}/Engines) to use for the analysis.
+ 
+${(0, doc_structure_1.block)({
+        type: 'NOTE',
+        content: `If you want to quickly try out the analyzer, you can use the following code snippet that analyzes a simple R expression:
+	
+${(0, doc_types_1.printCodeOfElement)({ program: types.program, info: types.info, dropLinesStart: 1, dropLinesEnd: 2, hideDefinedAt: true }, analyzerQuickExample.name)}
+		`
+    })} 
+
+**TODO**: mention [Context](#Context_Information) 
+
+${(0, doc_structure_1.section)('Builder Configuration', 2)}
+
+**TODO** also explain buildSync and that TreeSitter has to be initialized for this 
+
+${(0, doc_structure_1.section)('Plugins', 2)}
+
+${(0, doc_structure_1.section)('Plugin Types', 3)}
+
+During the construction of a new ${(0, doc_types_1.shortLink)(flowr_analyzer_1.FlowrAnalyzer.name, types.info)}, plugins of different types are applied at different stages of the analysis.
+These plugins are grouped by their ${(0, doc_types_1.shortLink)('PluginType', types.info)} and are applied in the following order (as shown in the documentation of the ${(0, doc_types_1.shortLink)('PluginType', types.info)}):
+
+${(() => {
+        const doc = (0, doc_types_1.getDocumentationForType)('PluginType', types.info);
+        // skip until the first ```text
+        const lines = doc.split('\n');
+        const start = lines.findIndex(l => l.trim().startsWith('```text'));
+        const end = lines.findIndex((l, i) => i > start && l.trim().startsWith('```'));
+        // github rendering pls fix xD
+        return start >= 0 && end > start ? '```text\n' + lines.slice(start + 1, end).join('\n').replaceAll('▶', '>') + '\n```' : doc;
+    })()}
+
+We describe the different plugin types in more detail below.
+
+
+${(0, doc_structure_1.section)('Project Discovery', 4)}
+
+${(0, doc_structure_1.section)('File Loading', 4)}
+
+${(0, doc_structure_1.section)('Dependency Identification', 4)}
+
+${(0, doc_structure_1.section)('Loading Order', 4)}
+
+${(0, doc_structure_1.section)('How to add a new plugin', 3)}
+
+${(0, doc_structure_1.section)('How to add a new plugin type', 3)}
+
+${(0, doc_structure_1.section)('Context Information', 2)}
+
+${(0, doc_structure_1.section)('Files Context', 3)}
+
+${(0, doc_structure_1.section)('Loading Order Context', 3)}
+
+${(0, doc_structure_1.section)('Dependencies Context', 3)}
+
+${(0, doc_structure_1.section)('Analyzer Internals', 2)}
+
+`;
+}
+/** if we run this script, we want a Markdown representation of the capabilities */
+if (require.main === module) {
+    (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
+    const shell = new shell_1.RShell();
+    void getText(shell).then(str => {
+        console.log(str);
+    }).finally(() => {
+        shell.close();
+    });
+}
+//# sourceMappingURL=print-analyzer-wiki.js.map