@eagleoutice/flowr 2.1.10 → 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/flowr.js

@@ -21,6 +21,7 @@ const core_1 = require("./repl/core");
 const repl_version_1 = require("./repl/commands/repl-version");
 const print_version_1 = require("./repl/print-version");
 const flowr_main_options_1 = require("./flowr-main-options");
+const fs_1 = __importDefault(require("fs"));
 exports.toolName = 'flowr';
 exports.optionHelp = [
     {
@@ -59,6 +60,13 @@ if (options['config-json']) {
     }
 }
 if (!usedConfig) {
+    if (options['config-file']) {
+        // validate it exists
+        if (!fs_1.default.existsSync(options['config-file'])) {
+            log_1.log.error(`Config file '${options['config-file']}' does not exist`);
+            process.exit(1);
+        }
+    }
     (0, config_1.setConfigFile)(options['config-file'] ?? flowr_main_options_1.defaultConfigFile, undefined, true);
 }
 function retrieveShell() {

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

@@ -21,8 +21,10 @@ function printHelp(output) {
     output.stdout('The query is an array of query objects to represent multiple queries. Each query object may have the following properties:');
     output.stdout((0, schema_1.describeSchema)((0, query_1.AnyQuerySchema)(), output.formatter));
     output.stdout(`\n\nThe example ${(0, ansi_1.italic)(':query "[{\\"type\\": \\"call-context\\", \\"callName\\": \\"mean\\" }]" mean(1:10)', output.formatter)} would return the call context of the mean function.`);
-    output.stdout('As a convenience, we interpret any (non-help) string not starting with \'[\' as a regex for the simple call-context query.');
+    output.stdout('As a convenience, we interpret any (non-help, non-@) string not starting with \'[\' as a regex for the simple call-context query.');
     output.stdout(`Hence, ${(0, ansi_1.italic)(':query "mean" mean(1:10)', output.formatter)} is equivalent to the above example.`);
+    output.stdout(`Similarly, '@<type>' is interpreted as a query of the given type.`);
+    output.stdout(`With this, ${(0, ansi_1.italic)(':query @config', output.formatter)} prints the result of the config query.`);
 }
 async function processQueryArgs(line, shell, output) {
     const args = (0, args_1.splitAtEscapeSensitive)(line);
@@ -36,7 +38,16 @@ async function processQueryArgs(line, shell, output) {
         return;
     }
     let parsedQuery = [];
-    if (query.startsWith('[')) {
+    if (query.startsWith('@')) {
+        parsedQuery = [{ type: query.slice(1) }];
+        const validationResult = (0, query_1.QueriesSchema)().validate(parsedQuery);
+        if (validationResult.error) {
+            output.stderr(`Invalid query: ${validationResult.error.message}`);
+            printHelp(output);
+            return;
+        }
+    }
+    else if (query.startsWith('[')) {
         parsedQuery = JSON.parse(query);
         const validationResult = (0, query_1.QueriesSchema)().validate(parsedQuery);
         if (validationResult.error) {
@@ -50,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/environments/resolve-by-name.d.ts

@@ -11,7 +11,8 @@ import type { DataflowGraph } from '../graph/graph';
  * @param environment  - The current environment used for name resolution
  * @param target       - The target (meta) type of the identifier to resolve
  *
- * @returns A list of possible definitions of the identifier (one if the definition location is exactly and always known), or `undefined` if the identifier is undefined in the current scope/with the current environment information.
+ * @returns A list of possible identifier definitions (one if the definition location is exactly and always known), or `undefined`
+ *          if the identifier is undefined in the current scope/with the current environment information.
  */
 export declare function resolveByName(name: Identifier, environment: REnvironmentInformation, target?: ReferenceType): IdentifierDefinition[] | undefined;
 export declare function resolvesToBuiltInConstant(name: Identifier | undefined, environment: REnvironmentInformation, wantedValue: unknown): Ternary;

package/dataflow/environments/resolve-by-name.js

@@ -35,7 +35,8 @@ const TargetTypePredicate = {
  * @param environment  - The current environment used for name resolution
  * @param target       - The target (meta) type of the identifier to resolve
  *
- * @returns A list of possible definitions of the identifier (one if the definition location is exactly and always known), or `undefined` if the identifier is undefined in the current scope/with the current environment information.
+ * @returns A list of possible identifier definitions (one if the definition location is exactly and always known), or `undefined`
+ *          if the identifier is undefined in the current scope/with the current environment information.
  */
 function resolveByName(name, environment, target = identifier_1.ReferenceType.Unknown) {
     let current = environment.current;

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/dataflow/internal/process/functions/call/built-in/built-in-access.js

@@ -13,6 +13,7 @@ const built_in_assignment_1 = require("./built-in-assignment");
 const identifier_1 = require("../../../../../environments/identifier");
 const vertex_1 = require("../../../../../graph/vertex");
 const list_access_1 = require("../../../../../../util/list-access");
+const config_1 = require("../../../../../../config");
 function tableAssignmentProcessor(name, args, rootId, data, outInfo) {
     outInfo.definitionRootNodes.push(rootId);
     return (0, known_call_handling_1.processKnownFunctionCall)({ name, args, rootId, data }).information;
@@ -147,34 +148,36 @@ function processStringBasedAccess(args, data, name, rootId, config) {
     if (accessedArg === undefined || accessArg === undefined) {
         return fnCall;
     }
-    let accessedIndicesCollection;
-    // If the accessedArg is a symbol, it's either a simple access or the base case of a nested access
-    if (accessedArg.value?.type === type_1.RType.Symbol) {
-        accessedIndicesCollection = (0, list_access_1.resolveSingleIndex)(accessedArg, accessArg, data.environment);
-    }
-    else {
-        // Higher access call
-        const underlyingAccessId = accessedArg.value?.info.id ?? -1;
-        const vertex = fnCall.information.graph.getVertex(underlyingAccessId);
-        const subIndices = vertex?.indicesCollection
-            ?.flatMap(indices => indices.indices)
-            ?.flatMap(index => index?.subIndices ?? []);
-        if (subIndices) {
-            accessedIndicesCollection = (0, list_access_1.filterIndices)(subIndices, accessArg);
+    if ((0, config_1.getConfig)().solver.pointerTracking) {
+        let accessedIndicesCollection;
+        // If the accessedArg is a symbol, it's either a simple access or the base case of a nested access
+        if (accessedArg.value?.type === type_1.RType.Symbol) {
+            accessedIndicesCollection = (0, list_access_1.resolveSingleIndex)(accessedArg, accessArg, data.environment);
         }
-    }
-    // Add indices to vertex afterward
-    if (accessedIndicesCollection) {
-        const vertex = fnCall.information.graph.getVertex(rootId);
-        if (vertex) {
-            vertex.indicesCollection = accessedIndicesCollection;
+        else {
+            // Higher access call
+            const underlyingAccessId = accessedArg.value?.info.id ?? -1;
+            const vertex = fnCall.information.graph.getVertex(underlyingAccessId);
+            const subIndices = vertex?.indicesCollection
+                ?.flatMap(indices => indices.indices)
+                ?.flatMap(index => index?.subIndices ?? []);
+            if (subIndices) {
+                accessedIndicesCollection = (0, list_access_1.filterIndices)(subIndices, accessArg);
+            }
         }
-        // When access has no access as parent, it's the top most
-        const rootNode = data.completeAst.idMap.get(rootId);
-        const parentNode = data.completeAst.idMap.get(rootNode?.info.parent ?? -1);
-        if (parentNode?.type !== type_1.RType.Access) {
-            // Only reference indices in top most access
-            referenceIndices(accessedIndicesCollection, fnCall, name.info.id);
+        // Add indices to vertex afterward
+        if (accessedIndicesCollection) {
+            const vertex = fnCall.information.graph.getVertex(rootId);
+            if (vertex) {
+                vertex.indicesCollection = accessedIndicesCollection;
+            }
+            // When access has no access as parent, it's the top most
+            const rootNode = data.completeAst.idMap.get(rootId);
+            const parentNode = data.completeAst.idMap.get(rootNode?.info.parent ?? -1);
+            if (parentNode?.type !== type_1.RType.Access) {
+                // Only reference indices in top most access
+                referenceIndices(accessedIndicesCollection, fnCall, name.info.id);
+            }
         }
     }
     return fnCall;

package/dataflow/internal/process/functions/call/built-in/built-in-assignment.d.ts

@@ -42,8 +42,7 @@ export interface AssignmentToSymbolParameters<OtherInfo> extends AssignmentConfi
  * @param nodeToDefine       - `x`
  * @param sourceIds          - `v`
  * @param rootIdOfAssignment - `<-`
- * @param quoteSource        - whether to quote the source (i.e., define `x` without a direct reference to `v`)
- * @param superAssignment    - whether this is a super assignment (i.e., `<<-`)
+ * @param config             - configuration for the assignment processing
  */
 export declare function markAsAssignment(information: {
     environment: REnvironmentInformation;

package/dataflow/internal/process/functions/call/built-in/built-in-assignment.js

@@ -18,6 +18,7 @@ const define_1 = require("../../../../../environments/define");
 const edge_1 = require("../../../../../graph/edge");
 const resolve_by_name_1 = require("../../../../../environments/resolve-by-name");
 const list_access_1 = require("../../../../../../util/list-access");
+const config_1 = require("../../../../../../config");
 function toReplacementSymbol(target, prefix, superAssignment) {
     return {
         type: type_1.RType.Symbol,
@@ -184,29 +185,30 @@ function checkTargetReferenceType(source, sourceInfo) {
  * @param nodeToDefine       - `x`
  * @param sourceIds          - `v`
  * @param rootIdOfAssignment - `<-`
- * @param quoteSource        - whether to quote the source (i.e., define `x` without a direct reference to `v`)
- * @param superAssignment    - whether this is a super assignment (i.e., `<<-`)
+ * @param config             - configuration for the assignment processing
  */
 function markAsAssignment(information, nodeToDefine, sourceIds, rootIdOfAssignment, config) {
-    let indicesCollection = undefined;
-    if (sourceIds.length === 1) {
-        // support for tracking indices
-        // Indices were defined for the vertex e.g. a <- list(c = 1) or a$b <- list(c = 1)
-        indicesCollection = information.graph.getVertex(sourceIds[0])?.indicesCollection;
-    }
-    // Indices defined by replacement operation e.g. $<-
-    if (config?.indicesCollection !== undefined) {
-        // If there were indices stored in the vertex, then a container was defined
-        // and assigned to the index of another container e.g. a$b <- list(c = 1)
-        if (indicesCollection) {
-            indicesCollection = (0, list_access_1.addSubIndicesToLeafIndices)(config.indicesCollection, indicesCollection);
+    if ((0, config_1.getConfig)().solver.pointerTracking) {
+        let indicesCollection = undefined;
+        if (sourceIds.length === 1) {
+            // support for tracking indices
+            // Indices were defined for the vertex e.g. a <- list(c = 1) or a$b <- list(c = 1)
+            indicesCollection = information.graph.getVertex(sourceIds[0])?.indicesCollection;
         }
-        else {
-            // No indices were defined for the vertex e.g. a$b <- 2
-            indicesCollection = config.indicesCollection;
+        // Indices defined by replacement operation e.g. $<-
+        if (config?.indicesCollection !== undefined) {
+            // If there were indices stored in the vertex, then a container was defined
+            // and assigned to the index of another container e.g. a$b <- list(c = 1)
+            if (indicesCollection) {
+                indicesCollection = (0, list_access_1.addSubIndicesToLeafIndices)(config.indicesCollection, indicesCollection);
+            }
+            else {
+                // No indices were defined for the vertex e.g. a$b <- 2
+                indicesCollection = config.indicesCollection;
+            }
         }
+        nodeToDefine.indicesCollection ??= indicesCollection;
     }
-    nodeToDefine.indicesCollection ??= indicesCollection;
     information.environment = (0, define_1.define)(nodeToDefine, config?.superAssignment, information.environment);
     information.graph.setDefinitionOfVertex(nodeToDefine);
     if (!config?.quoteSource) {
@@ -215,12 +217,14 @@ function markAsAssignment(information, nodeToDefine, sourceIds, rootIdOfAssignme
         }
     }
     information.graph.addEdge(nodeToDefine, rootIdOfAssignment, edge_1.EdgeType.DefinedBy);
-    // kinda dirty, but we have to remove existing read edges for the symbol, added by the child
-    const out = information.graph.outgoingEdges(nodeToDefine.nodeId);
-    for (const [id, edge] of (out ?? [])) {
-        edge.types &= ~edge_1.EdgeType.Reads;
-        if (edge.types == 0) {
-            out?.delete(id);
+    if ((0, config_1.getConfig)().solver.pointerTracking) {
+        // kinda dirty, but we have to remove existing read edges for the symbol, added by the child
+        const out = information.graph.outgoingEdges(nodeToDefine.nodeId);
+        for (const [id, edge] of (out ?? [])) {
+            edge.types &= ~edge_1.EdgeType.Reads;
+            if (edge.types == 0) {
+                out?.delete(id);
+            }
         }
     }
 }

package/dataflow/internal/process/functions/call/built-in/built-in-replacement.js

@@ -15,6 +15,7 @@ const edge_1 = require("../../../../../graph/edge");
 const dfg_1 = require("../../../../../../util/mermaid/dfg");
 const type_1 = require("../../../../../../r-bridge/lang-4.x/ast/model/type");
 const list_access_1 = require("../../../../../../util/list-access");
+const config_1 = require("../../../../../../config");
 function processReplacementFunction(name, 
 /** The last one has to be the value */
 args, rootId, data, config) {
@@ -25,7 +26,7 @@ args, rootId, data, config) {
     /* we only get here if <-, <<-, ... or whatever is part of the replacement is not overwritten */
     (0, log_1.expensiveTrace)(logger_1.dataflowLogger, () => `Replacement ${name.content} with ${JSON.stringify(args)}, processing`);
     let indices = undefined;
-    if (name.content === '$<-') {
+    if (name.content === '$<-' && (0, config_1.getConfig)().solver.pointerTracking) {
         const nonEmptyArgs = args.filter(arg => arg !== r_function_call_1.EmptyArgument);
         const accessedArg = nonEmptyArgs.find(arg => arg.info.role === "accessed" /* RoleInParent.Accessed */);
         const accessArg = nonEmptyArgs.find(arg => arg.info.role === "index-access" /* RoleInParent.IndexAccess */);

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;