@eagleoutice/flowr 2.1.11 → 2.1.12

package/README.md

@@ -73,3 +73,4 @@ We welcome every contribution! Please check out the [contributing guidelines](ht
 [GPLv3 License](LICENSE).
 
 ----
+# abstract-interpretation-ltx

package/cli/repl/commands/repl-query.js

@@ -61,7 +61,7 @@ async function processQueryArgs(line, shell, output) {
     }
     const processed = await getDataflow(shell, args.join(' '));
     return {
-        query: (0, query_1.executeQueries)({ graph: processed.dataflow.graph, ast: processed.normalize }, parsedQuery),
+        query: (0, query_1.executeQueries)({ dataflow: processed.dataflow, ast: processed.normalize }, parsedQuery),
         processed
     };
 }

package/cli/repl/server/connection.js

@@ -326,7 +326,7 @@ class FlowRServerConnection {
         const { dataflow: dfg, normalize: ast } = fileInformation.pipeline.getResults(true);
         (0, assert_1.guard)(dfg !== undefined, `Dataflow graph must be present (request: ${request.filetoken})`);
         (0, assert_1.guard)(ast !== undefined, `AST must be present (request: ${request.filetoken})`);
-        const results = (0, query_1.executeQueries)({ graph: dfg.graph, ast }, request.query);
+        const results = (0, query_1.executeQueries)({ dataflow: dfg, ast }, request.query);
         (0, send_1.sendMessage)(this.socket, {
             type: 'response-query',
             id: request.id,

package/core/steps/pipeline/default-pipelines.d.ts

@@ -227,6 +227,11 @@ export declare const DEFAULT_SLICE_WITHOUT_RECONSTRUCT_PIPELINE: import("./pipel
     readonly dependencies: readonly ["dataflow"];
     readonly requiredInput: import("../all/static-slicing/00-slice").SliceRequiredInput;
 }>;
+/**
+ * The default pipeline for working with flowr, including the dataflow step,
+ * see the {@link DEFAULT_NORMALIZE_PIPELINE} for the pipeline without the dataflow step,
+ * and the {@link DEFAULT_SLICE_AND_RECONSTRUCT_PIPELINE} for the pipeline with slicing and reconstructing steps
+ */
 export declare const DEFAULT_DATAFLOW_PIPELINE: import("./pipeline").Pipeline<{
     readonly name: "parse";
     readonly humanReadableName: "parse with R shell";
@@ -280,6 +285,7 @@ export declare const DEFAULT_DATAFLOW_PIPELINE: import("./pipeline").Pipeline<{
     };
     readonly dependencies: readonly ["normalize"];
 }>;
+/** The pipeline to use when you want to parse and normalize your R file, see {@link DEFAULT_DATAFLOW_PIPELINE} for the additional `dataflow` step */
 export declare const DEFAULT_NORMALIZE_PIPELINE: import("./pipeline").Pipeline<{
     readonly name: "parse";
     readonly humanReadableName: "parse with R shell";

package/core/steps/pipeline/default-pipelines.js

@@ -13,7 +13,13 @@ const _10_reconstruct_1 = require("../all/static-slicing/10-reconstruct");
 exports.DEFAULT_SLICING_PIPELINE = (0, pipeline_1.createPipeline)(_00_parse_1.PARSE_WITH_R_SHELL_STEP, _10_normalize_1.NORMALIZE, _20_dataflow_1.STATIC_DATAFLOW, _00_slice_1.STATIC_SLICE, _10_reconstruct_1.NAIVE_RECONSTRUCT);
 exports.DEFAULT_SLICE_AND_RECONSTRUCT_PIPELINE = exports.DEFAULT_SLICING_PIPELINE;
 exports.DEFAULT_SLICE_WITHOUT_RECONSTRUCT_PIPELINE = (0, pipeline_1.createPipeline)(_00_parse_1.PARSE_WITH_R_SHELL_STEP, _10_normalize_1.NORMALIZE, _20_dataflow_1.STATIC_DATAFLOW, _00_slice_1.STATIC_SLICE);
+/**
+ * The default pipeline for working with flowr, including the dataflow step,
+ * see the {@link DEFAULT_NORMALIZE_PIPELINE} for the pipeline without the dataflow step,
+ * and the {@link DEFAULT_SLICE_AND_RECONSTRUCT_PIPELINE} for the pipeline with slicing and reconstructing steps
+ */
 exports.DEFAULT_DATAFLOW_PIPELINE = (0, pipeline_1.createPipeline)(_00_parse_1.PARSE_WITH_R_SHELL_STEP, _10_normalize_1.NORMALIZE, _20_dataflow_1.STATIC_DATAFLOW);
+/** The pipeline to use when you want to parse and normalize your R file, see {@link DEFAULT_DATAFLOW_PIPELINE} for the additional `dataflow` step */
 exports.DEFAULT_NORMALIZE_PIPELINE = (0, pipeline_1.createPipeline)(_00_parse_1.PARSE_WITH_R_SHELL_STEP, _10_normalize_1.NORMALIZE);
 exports.DEFAULT_PARSE_PIPELINE = (0, pipeline_1.createPipeline)(_00_parse_1.PARSE_WITH_R_SHELL_STEP);
 //# sourceMappingURL=default-pipelines.js.map

package/dataflow/graph/vertex.d.ts

@@ -10,6 +10,10 @@ export declare enum VertexType {
     VariableDefinition = "variable-definition",
     FunctionDefinition = "function-definition"
 }
+export declare const ValidVertexTypes: Set<string>;
+export declare const ValidVertexTypeReverse: {
+    [k: string]: string;
+};
 /**
  * A single index of a container, which is not a container itself.
  *

package/dataflow/graph/vertex.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VertexType = void 0;
+exports.ValidVertexTypeReverse = exports.ValidVertexTypes = exports.VertexType = void 0;
 exports.isParentContainerIndex = isParentContainerIndex;
 exports.isValueVertex = isValueVertex;
 exports.isUseVertex = isUseVertex;
@@ -15,6 +15,8 @@ var VertexType;
     VertexType["VariableDefinition"] = "variable-definition";
     VertexType["FunctionDefinition"] = "function-definition";
 })(VertexType || (exports.VertexType = VertexType = {}));
+exports.ValidVertexTypes = new Set(Object.values(VertexType));
+exports.ValidVertexTypeReverse = Object.fromEntries(Object.entries(VertexType).map(([k, v]) => [v, k]));
 function isParentContainerIndex(index) {
     return 'subIndices' in index;
 }

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

@@ -42,7 +42,7 @@ async function printDfGraphForCode(shell, code, { mark, showCode = true, codeOpe
     if (switchCodeAndGraph) {
         (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)}_ (incl. parse and normalize) within the generation environment.`;
+    const metaInfo = `The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parse and normalize) within the generation environment.`;
     const dfGraph = printDfGraph(result.dataflow.graph, mark);
     let resultText = '\n\n';
     if (showCode) {

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

@@ -23,7 +23,7 @@ async function showQuery(shell, code, queries, { showCode, collapseResult, colla
         shell,
         request: (0, retriever_1.requestFromInput)(code)
     }).allRemainingSteps();
-    const results = (0, query_1.executeQueries)({ graph: analysis.dataflow.graph, ast: analysis.normalize }, queries);
+    const results = (0, query_1.executeQueries)({ dataflow: analysis.dataflow, ast: analysis.normalize }, 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.

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

@@ -0,0 +1,25 @@
+import type { RShell } from '../../r-bridge/shell';
+import type { SupportedQueryTypes } from '../../queries/query';
+import type { SupportedVirtualQueryTypes } from '../../queries/virtual-query/virtual-queries';
+import type { FlowrSearchLike } from '../../search/flowr-search-builder';
+export interface ShowSearchOptions {
+    readonly showCode?: boolean;
+    readonly collapseResult?: boolean;
+}
+export declare function showSearch(shell: RShell, code: string, search: FlowrSearchLike, { collapseResult }?: ShowSearchOptions): Promise<string>;
+export interface QueryDocumentation {
+    readonly name: string;
+    readonly type: 'virtual' | 'active';
+    readonly shortDescription: string;
+    readonly functionName: string;
+    readonly functionFile: string;
+    readonly buildExplanation: (shell: RShell) => Promise<string>;
+}
+export declare const RegisteredQueries: {
+    active: Map<string, QueryDocumentation>;
+    virtual: Map<string, QueryDocumentation>;
+};
+export declare function registerQueryDocumentation(query: SupportedQueryTypes | SupportedVirtualQueryTypes, doc: QueryDocumentation): void;
+export declare function linkToQueryOfName(id: SupportedQueryTypes | SupportedVirtualQueryTypes): string;
+export declare function tocForQueryType(type: 'active' | 'virtual'): string;
+export declare function explainQueries(shell: RShell, type: 'active' | 'virtual'): Promise<string>;

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

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegisteredQueries = void 0;
+exports.showSearch = showSearch;
+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/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");
+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, {
+        shell,
+        request: (0, retriever_1.requestFromInput)(code)
+    }).allRemainingSteps();
+    const result = (0, flowr_search_executor_1.runSearch)(search, analysis);
+    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();
+    return `
+
+${(0, doc_code_1.codeBlock)('ts', (0, flowr_search_printer_1.flowrSearchToCode)(search))}
+
+<details style="color:gray"> <summary>Search Visualization</summary>
+
+${(0, doc_code_1.codeBlock)('mermaid', (0, flowr_search_printer_1.flowrSearchToMermaid)(search))}
+
+In the code:
+
+${(0, doc_code_1.codeBlock)('r', code)}
+
+<details style="color:gray"> <summary>JSON Representation</summary>
+
+${(0, doc_code_1.codeBlock)('json', JSON.stringify(search, null, 2))}
+
+</details>
+
+</details>
+
+
+${collapseResult ? ' <details> <summary style="color:gray">Show Results</summary>' : ''}
+
+The query returns the following vetices (all references to \`x\` in the code):
+${result.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(', ')}
+
+${metaInfo}	
+
+The returned results are highlighted thick and blue within the dataflow graph:
+
+${await (0, doc_dfg_1.printDfGraphForCode)(shell, code, { showCode: false, switchCodeAndGraph: false, mark: new Set(result.map(({ node }) => node.info.id)) })}
+
+
+${collapseResult ? '</details>' : ''}
+
+	`;
+}
+exports.RegisteredQueries = {
+    'active': new Map(),
+    'virtual': new Map()
+};
+function registerQueryDocumentation(query, doc) {
+    const map = exports.RegisteredQueries[doc.type];
+    if (map.has(query)) {
+        throw new Error(`Query ${query} already registered`);
+    }
+    map.set(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 = [];
+    for (const [id, { name, shortDescription }] of queries) {
+        result.push(`1. [${name}](#${linkify(name)}) (\`${id}\`):\\\n    ${shortDescription}`);
+    }
+    return result.join('\n');
+}
+async function explainQuery(shell, { name, functionName, functionFile, buildExplanation }) {
+    return `
+### ${name}
+
+${await buildExplanation(shell)}
+
+<details> 
+
+<summary style="color:gray">Implementation Details</summary>
+
+Responsible for the execution of the ${name} query is \`${functionName}\` in ${(0, doc_files_1.getFilePathMd)(functionFile)}.
+
+</details>	
+
+`;
+}
+async function explainQueries(shell, type) {
+    const queries = [...exports.RegisteredQueries[type].entries()].sort(([, { name: a }], [, { name: b }]) => a.localeCompare(b));
+    const result = [];
+    for (const [, doc] of queries) {
+        result.push(await explainQuery(shell, doc));
+    }
+    return result.join(`\n${'-'.repeat(5)}\n\n`);
+}
+//# sourceMappingURL=doc-search.js.map

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

@@ -2,7 +2,7 @@ import ts from 'typescript';
 export interface TypeElementInSource {
     name: string;
     node: ts.Node;
-    kind: 'interface' | 'type' | 'enum' | 'class';
+    kind: 'interface' | 'type' | 'enum' | 'class' | 'variable';
     extends: string[];
     generics: string[];
     filePath: string;
@@ -25,7 +25,7 @@ export interface MermaidTypeReport {
     program: ts.Program;
 }
 export declare function getTypesFromFolderAsMermaid(options: GetTypesAsMermaidOption): MermaidTypeReport;
-export declare function implSnippet(node: TypeElementInSource | undefined, program: ts.Program, nesting?: number): string;
+export declare function implSnippet(node: TypeElementInSource | undefined, program: ts.Program, showName?: boolean, nesting?: number): string;
 export interface PrintHierarchyArguments {
     readonly program: ts.Program;
     readonly hierarchy: TypeElementInSource[];
@@ -36,3 +36,11 @@ export interface PrintHierarchyArguments {
 }
 export declare const mermaidHide: string[];
 export declare function printHierarchy({ program, hierarchy, root, collapseFromNesting, initialNesting, maxDepth }: PrintHierarchyArguments): 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)
+ * @param hierarchy - The hierarchy of types to search in
+ * @param codeStyle - Whether to use code style for the link
+ */
+export declare function shortLink(name: string, hierarchy: TypeElementInSource[], codeStyle?: boolean): string;
+export declare function getDocumentationForType(name: string, hierarchy: TypeElementInSource[]): string;

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

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

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

@@ -689,7 +689,7 @@ async function getText(shell) {
     });
     return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'dataflow graph', rVersion: rversion })}
 
-This page briefly summarizes flowR's dataflow graph, represented by ${graph_1.DataflowGraph.name} in ${(0, doc_files_1.getFilePathMd)('../dataflow/graph/graph.ts')}.
+This page briefly summarizes flowR's dataflow graph, represented by ${(0, doc_types_1.shortLink)('DataflowGraph', vertexType.info)} in ${(0, doc_files_1.getFilePathMd)('../dataflow/graph/graph.ts')}.
 In case you want to manually build such a graph (e.g., for testing), you can use the builder in ${(0, doc_files_1.getFilePathMd)('../dataflow/graph/dataflowgraph-builder.ts')}.
 This wiki page focuses on explaining what such a dataflow graph looks like!
 

package/documentation/print-interface-wiki.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const shell_1 = require("../r-bridge/shell");
 const log_1 = require("../../test/functionality/_helper/log");
@@ -19,6 +22,8 @@ const flowr_main_options_1 = require("../cli/flowr-main-options");
 const doc_issue_1 = require("./doc-util/doc-issue");
 const pipeline_executor_1 = require("../core/pipeline-executor");
 const doc_structure_1 = require("./doc-util/doc-structure");
+const doc_types_1 = require("./doc-util/doc-types");
+const path_1 = __importDefault(require("path"));
 async function explainServer(shell) {
     (0, doc_data_server_messages_1.documentAllServerMessages)();
     return `
@@ -234,37 +239,43 @@ ${(0, schema_1.describeSchema)(config_1.flowrConfigFileSchema, ansi_1.markdownFo
 	`;
 }
 function explainWritingCode(shell) {
+    const types = (0, doc_types_1.getTypesFromFolderAsMermaid)({
+        rootFolder: path_1.default.resolve('./src/r-bridge/'),
+        files: [path_1.default.resolve('./src/core/pipeline-executor.ts'), path_1.default.resolve('./src/core/steps/pipeline/default-pipelines.ts')],
+        typeName: 'RShell',
+        inlineTypes: doc_types_1.mermaidHide
+    });
     return `
 
 
 _flowR_ can be used as a [module](${doc_files_1.FlowrNpmRef}) and offers several main classes and interfaces that are interesting for extension writers 
 (see the [Visual Studio Code extension](${doc_files_1.FlowrGithubBaseRef}/vscode-flowr) or the [core](${doc_files_1.FlowrWikiBaseRef}/Core) wiki page for more information).
 
-### Using the \`${shell_1.RShell.name}\` to Interact with R
+### Using the ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} to Interact with R
 
-The \`${shell_1.RShell.name}\` class allows to interface with the \`R\` ecosystem installed on the host system.
+The ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} class allows interfacing with the \`R\` ecosystem installed on the host system.
 For now, there are no (real) alternatives, although we plan on providing more flexible drop-in replacements.
 
 > [!IMPORTANT]
-> Each \`${shell_1.RShell.name}\` controls a new instance of the R interpreter, make sure to call \`${shell_1.RShell.name}::${shell.close.name}()\` when you’re done.
+> Each ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} controls a new instance of the R&nbsp;interpreter, make sure to call <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.close.name}()</code> when you’re done.
 
-You can start a new "session" simply by constructing a new object with \`new ${shell_1.RShell.name}()\`.
+You can start a new "session" simply by constructing a new object with <code>new ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}()</code>.
 
-However, there are several options which may be of interest (e.g., to automatically revive the shell in case of errors or to control the name location of the R process on the system).
+However, there are several options that may be of interest (e.g., to automatically revive the shell in case of errors or to control the name location of the R process on the system).
 
-With a shell object (let's call it \`shell\`), you can execute R code by using \`${shell_1.RShell.name}::${shell.sendCommand.name}\`, 
+With a shell object (let's call it \`shell\`), you can execute R code by using <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.sendCommand.name}</code>, 
 for example \`shell.${shell.sendCommand.name}("1 + 1")\`. 
-However, this does not return anything, so if you want to collect the output of your command, use \`${shell_1.RShell.name}::${shell.sendCommandWithOutput.name}\` instead.
+However, this does not return anything, so if you want to collect the output of your command, use <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.sendCommandWithOutput.name}</code> instead.
 
-Besides that, the command \`${shell_1.RShell.name}::${shell.tryToInjectHomeLibPath.name}\` may be of interest, as it enables all libraries available on the host system.
+Besides that, the command <code>${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info, false)}::${shell.tryToInjectHomeLibPath.name}</code> may be of interest, as it enables all libraries available on the host system.
 
 ### The Pipeline Executor
 
 Once, in the beginning, _flowR_ was meant to produce a dataflow graph merely to provide *program slices*. 
-However, with continuous updates, the [dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow&20Graph) repeatedly proves to be the more interesting part.
+However, with continuous updates, the [dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph) repeatedly proves to be the more interesting part.
 With this, we restructured _flowR_'s originally *hardcoded* pipeline to be far more flexible. 
 Now, it can be theoretically extended or replaced with arbitrary steps, optional steps, and what we call 'decorations' of these steps. 
-In short, if you still "just want to slice" you can do it like this:
+In short, if you still "just want to slice" you can do it like this with the ${(0, doc_types_1.shortLink)(pipeline_executor_1.PipelineExecutor.name, types.info)}:
 
 ${(0, doc_code_1.codeBlock)('ts', `
 const slicer = new ${pipeline_executor_1.PipelineExecutor.name}(DEFAULT_SLICING_PIPELINE, {
@@ -281,9 +292,9 @@ const slice = await slicer.allRemainingSteps()
 <summary style='color:gray'>More Information</summary>
 
 If you compare this, with what you would have done with the old (and removed) \`SteppingSlicer\`, 
-this essentially just requires you to replace the \`SteppingSlicer\` with the \`${pipeline_executor_1.PipelineExecutor.name}\` 
-and to pass the \`DEFAULT_SLICING_PIPELINE\` as the first argument.
-The \`${pipeline_executor_1.PipelineExecutor.name}\`...
+this essentially just requires you to replace the \`SteppingSlicer\` with the ${(0, doc_types_1.shortLink)(pipeline_executor_1.PipelineExecutor.name, types.info)}
+and to pass the ${(0, doc_types_1.shortLink)('DEFAULT_SLICING_PIPELINE', types.info)} as the first argument.
+The ${(0, doc_types_1.shortLink)(pipeline_executor_1.PipelineExecutor.name, types.info)}...
 
 1. allows investigating the results of all intermediate steps
 2. Can be executed step-by-step

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

@@ -24,7 +24,7 @@ async function getText(shell) {
     const now = performance.now();
     const types = (0, doc_types_1.getTypesFromFolderAsMermaid)({
         rootFolder: path_1.default.resolve('./src/r-bridge/lang-4.x/ast/model/'),
-        files: [path_1.default.resolve('./src/abstract-interpretation/normalized-ast-fold.ts')],
+        files: [path_1.default.resolve('./src/abstract-interpretation/normalized-ast-fold.ts'), path_1.default.resolve('./src/core/steps/pipeline/default-pipelines.ts')],
         typeName: 'RNode',
         inlineTypes: doc_types_1.mermaidHide
     });
@@ -77,7 +77,7 @@ ${(0, doc_code_1.codeBlock)('mermaid', types.text)}
 _The generation of the class diagram required ${(0, time_1.printAsMs)(elapsed)}._
 </details>
 
-Node types are controlled by the \`${'RType'}\` enum (see ${(0, doc_files_1.getFilePathMd)('../r-bridge/lang-4.x/ast/model/type.ts')}), 
+Node types are controlled by the ${(0, doc_types_1.shortLink)('RType', types.info)} enum (see ${(0, doc_files_1.getFilePathMd)('../r-bridge/lang-4.x/ast/model/type.ts')}), 
 which is used to distinguish between different types of nodes.
 Additionally, every AST node is generic with respect to the \`Info\` type which allows for arbitrary decorations (e.g., parent inforamtion or dataflow constraints).
 Most notably, the \`info\` field holds the \`id\` of the node, which is used to reference the node in the [dataflow graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph).
@@ -94,8 +94,8 @@ The following segments intend to give you an overview of how to work with the no
 ## How Get a Normalized AST
 
 As explained alongside the [Interface](${doc_files_1.FlowrWikiBaseRef}/Interface#the-pipeline-executor) wiki page, you can use the 
-\`${pipeline_executor_1.PipelineExecutor.name}\` to get the normalized AST. If you are only interested in the normalization,
-a pipeline like the \`DEFAULT_NORMALIZE_PIPELINE\` suffices:
+\`${pipeline_executor_1.PipelineExecutor.name}\` to get the ${(0, doc_types_1.shortLink)('NormalizedAst', types.info)}. If you are only interested in the normalization,
+a pipeline like the ${(0, doc_types_1.shortLink)('DEFAULT_NORMALIZE_PIPELINE', types.info)} suffices:
 
 ${(0, doc_code_1.codeBlock)('ts', `
 async function getAst(code: string): Promise<RNode> {

package/documentation/print-query-wiki.js

@@ -26,6 +26,9 @@ const doc_issue_1 = require("./doc-util/doc-issue");
 const location_map_query_executor_1 = require("../queries/catalog/location-map-query/location-map-query-executor");
 const identify_link_to_last_call_relation_1 = require("../queries/catalog/call-context-query/identify-link-to-last-call-relation");
 const config_query_executor_1 = require("../queries/catalog/config-query/config-query-executor");
+const search_query_executor_1 = require("../queries/catalog/search-query/search-query-executor");
+const flowr_search_builder_1 = require("../search/flowr-search-builder");
+const vertex_1 = require("../dataflow/graph/vertex");
 (0, doc_query_1.registerQueryDocumentation)('call-context', {
     name: 'Call-Context Query',
     type: 'active',
@@ -191,6 +194,25 @@ ${await (0, doc_query_1.showQuery)(shell, example_query_code_1.exampleQueryCode,
 		`;
     }
 });
+(0, doc_query_1.registerQueryDocumentation)('search', {
+    name: 'Search Query',
+    type: 'active',
+    shortDescription: 'Provides access to flowR\'s search API',
+    functionName: search_query_executor_1.executeSearch.name,
+    functionFile: '../queries/catalog/search-query/search-query-executor.ts',
+    buildExplanation: async (shell) => {
+        const exampleCode = 'x + 1';
+        return `
+With this query you can use the [Search API](${doc_files_1.FlowrWikiBaseRef}/Search%20API) to conduct searches on the flowR analysis result. 
+
+Using the example code \`${exampleCode}\`, the following query returns all uses of 'x' in the code:
+${await (0, doc_query_1.showQuery)(shell, exampleCode, [{
+                type: 'search',
+                search: flowr_search_builder_1.Q.var('x').filter(vertex_1.VertexType.Use).build()
+            }], { showCode: true, collapseQuery: false })}
+		`;
+    }
+});
 (0, doc_query_1.registerQueryDocumentation)('id-map', {
     name: 'Id-Map Query',
     type: 'active',

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

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