@eagleoutice/flowr 2.3.0 → 2.4.1

package/queries/catalog/location-map-query/location-map-query-executor.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeLocationMapQuery = executeLocationMapQuery;
-const log_1 = require("../../../util/log");
+const parse_1 = require("../../../slicing/criterion/parse");
+const assert_1 = require("../../../util/assert");
 const fileIdRegex = /^(?<file>.*(\.[rR]))-/;
 function fuzzyFindFile(node, idMap) {
     if (node?.info.file) {
@@ -22,10 +23,11 @@ function fuzzyFindFile(node, idMap) {
     return '<inline>';
 }
 function executeLocationMapQuery({ ast, dataflow: { graph } }, queries) {
-    if (queries.length !== 1) {
-        log_1.log.warn('Id-Map query expects only up to one query, but got', queries.length);
-    }
     const start = Date.now();
+    const criteriaOfInterest = new Set(queries
+        .flatMap(q => q.ids ?? [])
+        .map(c => (0, parse_1.tryResolveSliceCriterionToId)(c, ast.idMap))
+        .filter(assert_1.isNotUndefined));
     const locationMap = {
         files: {},
         ids: {}
@@ -38,7 +40,7 @@ function executeLocationMapQuery({ ast, dataflow: { graph } }, queries) {
         count++;
     }
     for (const [id, node] of ast.idMap.entries()) {
-        if (node.location) {
+        if (node.location && (criteriaOfInterest.size === 0 || criteriaOfInterest.has(id))) {
             const file = fuzzyFindFile(node, ast.idMap);
             locationMap.ids[id] = [
                 inverseMap.get(file) ?? -1,

package/queries/catalog/location-map-query/location-map-query-format.d.ts

@@ -4,8 +4,11 @@ import { type OutputFormatter } from '../../../util/text/ansi';
 import Joi from 'joi';
 import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { SourceRange } from '../../../util/range';
+import type { SingleSlicingCriterion } from '../../../slicing/criterion/parse';
 export interface LocationMapQuery extends BaseQueryFormat {
     readonly type: 'location-map';
+    /** Optional list of ids to filter the results by. If not provided, all ids will be included. */
+    readonly ids?: readonly SingleSlicingCriterion[];
 }
 export type FileId = number & {
     readonly __fileId?: unique symbol;

package/queries/catalog/location-map-query/location-map-query-format.js

@@ -23,6 +23,7 @@ exports.LocationMapQueryDefinition = {
     },
     schema: joi_1.default.object({
         type: joi_1.default.string().valid('location-map').required().description('The type of the query.'),
+        ids: joi_1.default.array().items(joi_1.default.string()).optional().description('Optional list of ids to filter the results by.')
     }).description('The location map query retrieves the location of every id in the ast.'),
     flattenInvolvedNodes: () => []
 };

package/queries/catalog/search-query/search-query-executor.js

@@ -9,7 +9,7 @@ function executeSearch({ ast, dataflow, config }, queries) {
         const { search } = query;
         results.push({
             ids: (0, flowr_search_executor_1.runSearch)(search, { normalize: ast, dataflow, config })
-                .map(({ node }) => node.info.id),
+                .getElements().map(({ node }) => node.info.id),
             search
         });
     }

package/queries/catalog/static-slice-query/static-slice-query-executor.d.ts

@@ -1,4 +1,4 @@
 import type { StaticSliceQuery, StaticSliceQueryResult } from './static-slice-query-format';
 import type { BasicQueryData } from '../../base-query-format';
 export declare function fingerPrintOfQuery(query: StaticSliceQuery): string;
-export declare function executeStaticSliceQuery({ dataflow: { graph }, ast, config }: BasicQueryData, queries: readonly StaticSliceQuery[]): StaticSliceQueryResult;
+export declare function executeStaticSliceQuery({ dataflow, ast, config }: BasicQueryData, queries: readonly StaticSliceQuery[]): StaticSliceQueryResult;

package/queries/catalog/static-slice-query/static-slice-query-executor.js

@@ -7,10 +7,11 @@ const reconstruct_1 = require("../../../reconstruct/reconstruct");
 const auto_select_defaults_1 = require("../../../reconstruct/auto-select/auto-select-defaults");
 const magic_comments_1 = require("../../../reconstruct/auto-select/magic-comments");
 const log_1 = require("../../../util/log");
+const _00_slice_1 = require("../../../core/steps/all/static-slicing/00-slice");
 function fingerPrintOfQuery(query) {
     return JSON.stringify(query);
 }
-function executeStaticSliceQuery({ dataflow: { graph }, ast, config }, queries) {
+function executeStaticSliceQuery({ dataflow, ast, config }, queries) {
     const start = Date.now();
     const results = {};
     for (const query of queries) {
@@ -20,7 +21,7 @@ function executeStaticSliceQuery({ dataflow: { graph }, ast, config }, queries)
         }
         const { criteria, noReconstruction, noMagicComments } = query;
         const sliceStart = Date.now();
-        const slice = (0, static_slicer_1.staticSlicing)(graph, ast, criteria, config.solver.slicer?.threshold);
+        const slice = (0, static_slicer_1.staticSlice)(dataflow, ast, criteria, query.direction ?? _00_slice_1.SliceDirection.Backward, config.solver.slicer?.threshold);
         const sliceEnd = Date.now();
         if (noReconstruction) {
             results[key] = { slice: { ...slice, '.meta': { timing: sliceEnd - sliceStart } } };

package/queries/catalog/static-slice-query/static-slice-query-format.d.ts

@@ -4,6 +4,7 @@ import type { DEFAULT_DATAFLOW_PIPELINE, DEFAULT_SLICE_WITHOUT_RECONSTRUCT_PIPEL
 import type { SlicingCriteria } from '../../../slicing/criterion/parse';
 import Joi from 'joi';
 import { executeStaticSliceQuery } from './static-slice-query-executor';
+import { SliceDirection } from '../../../core/steps/all/static-slicing/00-slice';
 import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
 /** Calculates and returns all clusters encountered in the dataflow graph. */
 export interface StaticSliceQuery extends BaseQueryFormat {
@@ -14,6 +15,8 @@ export interface StaticSliceQuery extends BaseQueryFormat {
     readonly noReconstruction?: boolean;
     /** Should the magic comments (force-including lines within the slice) be ignored? */
     readonly noMagicComments?: boolean;
+    /** The direction to slice in. Defaults to backward slicing if unset. */
+    readonly direction?: SliceDirection;
 }
 export interface StaticSliceQueryResult extends BaseQueryResult {
     /**

package/queries/catalog/static-slice-query/static-slice-query-format.js

@@ -9,6 +9,7 @@ const time_1 = require("../../../util/text/time");
 const joi_1 = __importDefault(require("joi"));
 const static_slice_query_executor_1 = require("./static-slice-query-executor");
 const query_print_1 = require("../../query-print");
+const _00_slice_1 = require("../../../core/steps/all/static-slicing/00-slice");
 exports.StaticSliceQueryDefinition = {
     executor: static_slice_query_executor_1.executeStaticSliceQuery,
     asciiSummarizer: (formatter, _processed, queryResults, result) => {
@@ -37,7 +38,8 @@ exports.StaticSliceQueryDefinition = {
         type: joi_1.default.string().valid('static-slice').required().description('The type of the query.'),
         criteria: joi_1.default.array().items(joi_1.default.string()).min(0).required().description('The slicing criteria to use.'),
         noReconstruction: joi_1.default.boolean().optional().description('Do not reconstruct the slice into readable code.'),
-        noMagicComments: joi_1.default.boolean().optional().description('Should the magic comments (force-including lines within the slice) be ignored?')
+        noMagicComments: joi_1.default.boolean().optional().description('Should the magic comments (force-including lines within the slice) be ignored?'),
+        direction: joi_1.default.string().valid(...Object.values(_00_slice_1.SliceDirection)).optional().description('The direction to slice in. Defaults to backward slicing if unset.')
     }).description('Slice query used to slice the dataflow graph'),
     flattenInvolvedNodes: (queryResults) => {
         const flattened = [];

package/queries/query-print.d.ts

@@ -5,4 +5,4 @@ import type { DEFAULT_DATAFLOW_PIPELINE } from '../core/steps/pipeline/default-p
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
 export declare function asciiCallContext(formatter: OutputFormatter, results: QueryResults<'call-context'>['call-context'], processed: PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>): string;
 export declare function summarizeIdsIfTooLong(formatter: OutputFormatter, ids: readonly NodeId[]): string;
-export declare function asciiSummaryOfQueryResult(formatter: OutputFormatter, totalInMs: number, results: QueryResults<SupportedQueryTypes>, processed: PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>): string;
+export declare function asciiSummaryOfQueryResult<S extends SupportedQueryTypes>(formatter: OutputFormatter, totalInMs: number, results: Awaited<QueryResults<S>>, processed: PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>): string;

package/queries/query-print.js

@@ -81,7 +81,6 @@ function asciiSummaryOfQueryResult(formatter, totalInMs, results, processed) {
         }
         result.push(`Query: ${(0, ansi_1.bold)(query, formatter)}`);
         let timing = -1;
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
         for (const [key, value] of Object.entries(queryResults)) {
             if (key === '.meta') {
                 timing = value.timing;

package/queries/query.d.ts

@@ -25,11 +25,20 @@ import type { LinterQuery } from './catalog/linter-query/linter-query-format';
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { ControlFlowQuery } from './catalog/control-flow-query/control-flow-query-format';
 import type { DfShapeQuery } from './catalog/df-shape-query/df-shape-query-format';
+import type { AsyncOrSync, AsyncOrSyncType } from 'ts-essentials';
+/**
+ * These are all queries that can be executed from within flowR
+ * {@link SynchronousQuery} are queries that can be executed synchronously, i.e., they do not return a Promise.
+ */
 export type Query = CallContextQuery | ConfigQuery | SearchQuery | DataflowQuery | ControlFlowQuery | DataflowLensQuery | DfShapeQuery | NormalizedAstQuery | IdMapQuery | DataflowClusterQuery | StaticSliceQuery | LineageQuery | DependenciesQuery | LocationMapQuery | HappensBeforeQuery | ResolveValueQuery | ProjectQuery | OriginQuery | LinterQuery;
+export type SynchronousQuery = Exclude<Query, {
+    executor: (query: Query) => Promise<unknown>;
+}>;
+export type SupportedSynchronousQueryTypes = SynchronousQuery['type'];
 export type QueryArgumentsWithType<QueryType extends BaseQueryFormat['type']> = Query & {
     type: QueryType;
 };
-export type QueryExecutor<Query extends BaseQueryFormat, Result extends BaseQueryResult> = (data: BasicQueryData, query: readonly Query[]) => Result;
+export type QueryExecutor<Query extends BaseQueryFormat, Result extends BaseQueryResult> = (data: BasicQueryData, query: readonly Query[]) => AsyncOrSync<Result>;
 type SupportedQueries = {
     [QueryType in Query['type']]: SupportedQuery<QueryType>;
 };
@@ -1008,17 +1017,19 @@ export declare const SupportedQueries: {
     };
 };
 export type SupportedQueryTypes = keyof typeof SupportedQueries;
-export type QueryResult<Type extends Query['type']> = ReturnType<typeof SupportedQueries[Type]['executor']>;
-export declare function executeQueriesOfSameType<SpecificQuery extends Query>(data: BasicQueryData, ...queries: readonly SpecificQuery[]): QueryResult<SpecificQuery['type']>;
+export type QueryResult<Type extends Query['type']> = AsyncOrSync<ReturnType<typeof SupportedQueries[Type]['executor']>>;
+export declare function executeQueriesOfSameType<SpecificQuery extends SynchronousQuery>(data: BasicQueryData, queries: readonly SpecificQuery[]): AsyncOrSyncType<QueryResult<SpecificQuery['type']>>;
+export declare function executeQueriesOfSameType<SpecificQuery extends Query>(data: BasicQueryData, queries: readonly SpecificQuery[]): QueryResult<SpecificQuery['type']>;
 export type QueryResults<Base extends SupportedQueryTypes> = {
-    readonly [QueryType in Base]: QueryResult<QueryType>;
+    readonly [QueryType in Base]: Awaited<QueryResult<QueryType>>;
 } & BaseQueryResult;
 type OmitFromValues<T, K extends string | number | symbol> = {
     [P in keyof T]?: Omit<T[P], K>;
 };
 export type QueryResultsWithoutMeta<Queries extends Query> = OmitFromValues<Omit<QueryResults<Queries['type']>, '.meta'>, '.meta'>;
 export type Queries<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>> = readonly (QueryArgumentsWithType<Base> | VirtualQueryArgumentsWithType<Base, VirtualArguments>)[];
-export declare function executeQueries<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>>(data: BasicQueryData, queries: Queries<Base, VirtualArguments>): QueryResults<Base>;
+export declare function executeQueries<Base extends SupportedSynchronousQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>>(data: BasicQueryData, queries: Queries<Base, VirtualArguments>): QueryResults<Base>;
+export declare function executeQueries<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>>(data: BasicQueryData, queries: Queries<Base, VirtualArguments>): AsyncOrSync<QueryResults<Base>>;
 export declare function SupportedQueriesSchema(): Joi.AlternativesSchema<any>;
 export declare const CompoundQuerySchema: Joi.ObjectSchema<any>;
 export declare function VirtualQuerySchema(): Joi.AlternativesSchema<any>;

package/queries/query.js

@@ -53,7 +53,7 @@ exports.SupportedQueries = {
     'origin': origin_query_format_1.OriginQueryDefinition,
     'linter': linter_query_format_1.LinterQueryDefinition
 };
-function executeQueriesOfSameType(data, ...queries) {
+function executeQueriesOfSameType(data, queries) {
     (0, assert_1.guard)(queries.length > 0, 'At least one query must be provided');
     /* every query must have the same type */
     (0, assert_1.guard)(queries.every(q => q.type === queries[0].type), 'All queries must have the same type');
@@ -67,9 +67,7 @@ function isVirtualQuery(query) {
 function groupQueriesByType(queries) {
     const grouped = {};
     function addQuery(query) {
-        if (grouped[query.type] === undefined) {
-            grouped[query.type] = [];
-        }
+        grouped[query.type] ??= [];
         grouped[query.type].push(query);
     }
     for (const query of queries) {
@@ -86,17 +84,32 @@ function groupQueriesByType(queries) {
     }
     return grouped;
 }
+function isPromiseLike(value) {
+    return value !== null && typeof value === 'object' && typeof value.then === 'function';
+}
+/**
+ * This is the main query execution function that takes a set of queries and executes them on the given data.
+ */
 function executeQueries(data, queries) {
     const now = Date.now();
     const grouped = groupQueriesByType(queries);
-    const results = {};
-    for (const type of Object.keys(grouped)) {
-        results[type] = executeQueriesOfSameType(data, ...grouped[type]);
+    const entries = Object.entries(grouped);
+    const results = entries.map(([type, group]) => [type, executeQueriesOfSameType(data, group)]);
+    if (results.length === 0 || results.every(([_, r]) => !isPromiseLike(r))) {
+        // all results are synchronous, we can return them directly
+        const r = Object.fromEntries(results);
+        r['.meta'] = {
+            timing: Date.now() - now
+        };
+        return r;
     }
-    results['.meta'] = {
-        timing: Date.now() - now
-    };
-    return results;
+    return Promise.all(results.map(([type, result]) => Promise.resolve(result).then(resolvedResult => [type, resolvedResult]))).then(resultsArray => {
+        const results = Object.fromEntries(resultsArray);
+        results['.meta'] = {
+            timing: Date.now() - now
+        };
+        return results;
+    });
 }
 function SupportedQueriesSchema() {
     return joi_1.default.alternatives(Object.values(exports.SupportedQueries).map(q => q.schema)).description('Supported queries');

package/search/flowr-search-builder.d.ts

@@ -1,11 +1,11 @@
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
-import type { FlowrSearchElement, FlowrSearchElementFromQuery, FlowrSearchElements, FlowrSearchGetFilter } from './flowr-search';
+import type { FlowrSearchElement, FlowrSearchElements, FlowrSearchGetFilter } from './flowr-search';
 import type { FlowrFilter, FlowrFilterExpression } from './flowr-search-filters';
 import type { FlowrSearchGeneratorNode, GeneratorNames } from './search-executor/search-generators';
 import type { FlowrSearchTransformerNode, GetOutputOfTransformer, TransformerNames } from './search-executor/search-transformer';
 import type { SlicingCriteria } from '../slicing/criterion/parse';
 import type { ParentInformation } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
-import type { Enrichment, EnrichmentArguments } from './search-executor/search-enrichers';
+import type { Enrichment, EnrichmentElementArguments } from './search-executor/search-enrichers';
 import type { MapperArguments } from './search-executor/search-mappers';
 import { Mapper } from './search-executor/search-mappers';
 import type { Query } from '../queries/query';
@@ -28,7 +28,7 @@ export declare const FlowrSearchGenerator: {
      * Internally, the {@link SupportedQuery#flattenInvolvedNodes} function is used to flatten the resulting nodes of the query.
      * Please note that, due to the fact that not every query involves dataflow nodes, the search may not contain any elements at all for certain queries.
      */
-    readonly fromQuery: (...from: readonly Query[]) => FlowrSearchBuilder<"from-query", [], ParentInformation, FlowrSearchElements<ParentInformation, FlowrSearchElementFromQuery<ParentInformation>[]>>;
+    readonly fromQuery: (...from: readonly Query[]) => FlowrSearchBuilder<"from-query", [], ParentInformation, FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>>;
     /**
      * Returns all elements (nodes/dataflow vertices) from the given data.
      */
@@ -86,7 +86,7 @@ export declare const Q: {
      * Internally, the {@link SupportedQuery#flattenInvolvedNodes} function is used to flatten the resulting nodes of the query.
      * Please note that, due to the fact that not every query involves dataflow nodes, the search may not contain any elements at all for certain queries.
      */
-    readonly fromQuery: (...from: readonly Query[]) => FlowrSearchBuilder<"from-query", [], ParentInformation, FlowrSearchElements<ParentInformation, FlowrSearchElementFromQuery<ParentInformation>[]>>;
+    readonly fromQuery: (...from: readonly Query[]) => FlowrSearchBuilder<"from-query", [], ParentInformation, FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>>;
     /**
      * Returns all elements (nodes/dataflow vertices) from the given data.
      */
@@ -188,7 +188,7 @@ export declare class FlowrSearchBuilder<Generator extends GeneratorNames, Transf
      * Adds the given enrichment to each element of the search.
      * Added enrichments can later be retrieved using the {@link enrichmentContent} function.
      */
-    with<ConcreteEnrichment extends Enrichment>(enrichment: ConcreteEnrichment, args?: EnrichmentArguments<ConcreteEnrichment>): FlowrSearchBuilderOut<Generator, Transformers, Info, 'with'>;
+    with<ConcreteEnrichment extends Enrichment>(enrichment: ConcreteEnrichment, args?: EnrichmentElementArguments<ConcreteEnrichment>): FlowrSearchBuilderOut<Generator, Transformers, Info, 'with'>;
     /**
      * Maps the elements of the search to new values using the given mapper function.
      */
@@ -196,7 +196,7 @@ export declare class FlowrSearchBuilder<Generator extends GeneratorNames, Transf
     /**
      * A convenience function that combines {@link with} and the {@link Mapper.Enrichment} mapper to immediately add an enrichment and then map to its value(s).
      */
-    get<ConcreteEnrichment extends Enrichment>(enrichment: ConcreteEnrichment, args?: EnrichmentArguments<ConcreteEnrichment>): FlowrSearchBuilderOut<Generator, Transformers, Info, 'with' | 'map'>;
+    get<ConcreteEnrichment extends Enrichment>(enrichment: ConcreteEnrichment, args?: EnrichmentElementArguments<ConcreteEnrichment>): FlowrSearchBuilderOut<Generator, Transformers, Info, 'with' | 'map'>;
     /**
      * merge combines the search results with those of another search.
      */

package/search/flowr-search-executor.d.ts

@@ -1,7 +1,7 @@
 import type { FlowrSearch, FlowrSearchLike, SearchOutput } from './flowr-search-builder';
-import type { FlowrSearchElements, FlowrSearchInput } from './flowr-search';
+import type { FlowrSearchInput } from './flowr-search';
 import type { Pipeline } from '../core/steps/pipeline/pipeline';
-type GetSearchElements<S> = S extends FlowrSearch<infer _, infer _, infer _, infer Elements> ? Elements extends FlowrSearchElements<infer _, infer E> ? E : never : never;
+type GetSearchElements<S> = S extends FlowrSearch<infer _, infer _, infer _, infer Elements> ? Elements : never;
 /**
  * Run a search with the given search query and data.
  */

package/search/flowr-search-executor.js

@@ -11,6 +11,6 @@ function runSearch(search, data) {
     const s = (0, flowr_search_builder_1.getFlowrSearch)(search);
     return s.search.reduce((acc, transformer) => (0, search_transformer_1.getTransformer)(transformer.name)(data, acc, transformer.args), 
     /* support multiple arguments may be abstracted away in search frontend */
-    (0, search_generators_1.getGenerator)(s.generator.name)(data, s.generator.args)).getElements();
+    (0, search_generators_1.getGenerator)(s.generator.name)(data, s.generator.args));
 }
 //# sourceMappingURL=flowr-search-executor.js.map

package/search/flowr-search.d.ts

@@ -3,22 +3,18 @@ import type { Pipeline, PipelineOutput, PipelineStepOutputWithName } from '../co
 import type { NormalizedAst } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { DataflowInformation } from '../dataflow/info';
-import type { BaseQueryResult } from '../queries/base-query-format';
-import type { Query } from '../queries/query';
 import type { FlowrConfigOptions } from '../config';
-import type { MarkOptional } from 'ts-essentials';
+import type { Enrichment, EnrichmentSearchArguments, EnrichmentElementContent, EnrichmentSearchContent } from './search-executor/search-enrichers';
 /**
  * Yes, for now we do technically not need a wrapper around the RNode, but this allows us to attach caches etc.
  * just for the respective search.
  */
 export interface FlowrSearchElement<Info> {
     readonly node: RNode<Info>;
+    readonly enrichments?: {
+        [E in Enrichment]?: EnrichmentElementContent<E>;
+    };
 }
-export interface FlowrSearchElementFromQuery<Info> extends FlowrSearchElement<Info> {
-    readonly query: Query['type'];
-    readonly queryResult: BaseQueryResult;
-}
-export type FlowrSearchElementMaybeFromQuery<Info> = MarkOptional<FlowrSearchElementFromQuery<Info>, 'query' | 'queryResult'>;
 export interface FlowrSearchNodeBase<Type extends string, Name extends string, Args extends Record<string, unknown> | undefined> {
     readonly type: Type;
     readonly name: Name;
@@ -59,10 +55,19 @@ export type FlowrSearchInput<P extends Pipeline> = MinimumInputForFlowrSearch<P>
 /** Intentionally, we abstract away from an array to avoid the use of conventional typescript operations */
 export declare class FlowrSearchElements<Info = NoInfo, Elements extends FlowrSearchElement<Info>[] = FlowrSearchElement<Info>[]> {
     private elements;
+    private enrichments;
     constructor(elements?: Elements);
     add(element: FlowrSearchElement<Info>): this;
     addAll(elements: FlowrSearchElement<Info>[]): this;
     getElements(): Readonly<Elements>;
     mutate<OutElements extends Elements>(mutator: (elements: Elements) => OutElements): this;
+    /**
+     * Enriches this flowr search element collection with the given enrichment.
+     * To retrieve enrichment content for a given enrichment type, use {@link enrichmentContent}.
+     *
+     * Please note that this function does not also enrich individual elements, which is done through {@link enrichElement}. Both functions are called in a consise manner in {@link FlowrSearchBuilder.with}, which is the preferred way to add enrichments to a search.
+     */
+    enrich<E extends Enrichment>(data: FlowrSearchInput<Pipeline>, enrichment: E, args?: EnrichmentSearchArguments<E>): this;
+    enrichmentContent<E extends Enrichment>(enrichment: E): EnrichmentSearchContent<E>;
 }
 export {};

package/search/flowr-search.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowrSearchElements = void 0;
+const search_enrichers_1 = require("./search-executor/search-enrichers");
 /** Intentionally, we abstract away from an array to avoid the use of conventional typescript operations */
 class FlowrSearchElements {
     elements = [];
+    enrichments = {};
     constructor(elements) {
         if (elements) {
             this.elements = elements;
@@ -24,6 +26,25 @@ class FlowrSearchElements {
         this.elements = mutator(this.elements);
         return this;
     }
+    /**
+     * Enriches this flowr search element collection with the given enrichment.
+     * To retrieve enrichment content for a given enrichment type, use {@link enrichmentContent}.
+     *
+     * Please note that this function does not also enrich individual elements, which is done through {@link enrichElement}. Both functions are called in a consise manner in {@link FlowrSearchBuilder.with}, which is the preferred way to add enrichments to a search.
+     */
+    enrich(data, enrichment, args) {
+        const enrichmentData = search_enrichers_1.Enrichments[enrichment];
+        if (enrichmentData.enrichSearch !== undefined) {
+            this.enrichments = {
+                ...this.enrichments ?? {},
+                [enrichment]: enrichmentData.enrichSearch(this, data, args, this.enrichments?.[enrichment])
+            };
+        }
+        return this;
+    }
+    enrichmentContent(enrichment) {
+        return this.enrichments?.[enrichment];
+    }
 }
 exports.FlowrSearchElements = FlowrSearchElements;
 //# sourceMappingURL=flowr-search.js.map

package/search/search-executor/search-enrichers.d.ts

@@ -1,37 +1,38 @@
-import type { FlowrSearchElement, FlowrSearchInput } from '../flowr-search';
+import type { FlowrSearchElement, FlowrSearchElements, FlowrSearchInput } from '../flowr-search';
 import type { ParentInformation } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { Pipeline } from '../../core/steps/pipeline/pipeline';
 import type { MergeableRecord } from '../../util/objects';
 import type { Identifier } from '../../dataflow/environments/identifier';
 import type { LinkToLastCall } from '../../queries/catalog/call-context-query/call-context-query-format';
-/**
- * A {@link FlowrSearchElement} that is enriched with a set of enrichments through {@link FlowrSearchBuilder.with}.
- * Enrichments can be retrieved easily from an element through {@link enrichmentContent}.
- */
-export interface EnrichedFlowrSearchElement<Info> extends FlowrSearchElement<Info> {
-    enrichments: {
-        [E in Enrichment]?: EnrichmentContent<E>;
-    };
-}
-export interface EnrichmentData<EnrichmentContent extends MergeableRecord, EnrichmentArguments = undefined> {
+import { type NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
+import type { ControlFlowInformation } from '../../control-flow/control-flow-graph';
+import type { QueryResult, SynchronousQuery } from '../../queries/query';
+import type { CfgSimplificationPassName } from '../../control-flow/cfg-simplification';
+import type { AsyncOrSyncType } from 'ts-essentials';
+export interface EnrichmentData<ElementContent extends MergeableRecord, ElementArguments = undefined, SearchContent extends MergeableRecord = never, SearchArguments = ElementArguments> {
     /**
      * A function that is applied to each element of the search to enrich it with additional data.
      */
-    readonly enrich: (e: FlowrSearchElement<ParentInformation>, data: FlowrSearchInput<Pipeline>, args: EnrichmentArguments | undefined, previousValue: EnrichmentContent | undefined) => EnrichmentContent;
+    readonly enrichElement?: (element: FlowrSearchElement<ParentInformation>, search: FlowrSearchElements<ParentInformation>, data: FlowrSearchInput<Pipeline>, args: ElementArguments | undefined, previousValue: ElementContent | undefined) => ElementContent;
+    readonly enrichSearch?: (search: FlowrSearchElements<ParentInformation>, data: FlowrSearchInput<Pipeline>, args: SearchArguments | undefined, previousValue: SearchContent | undefined) => SearchContent;
     /**
      * The mapping function used by the {@link Mapper.Enrichment} mapper.
      */
-    readonly mapper: (c: EnrichmentContent) => FlowrSearchElement<ParentInformation>[];
+    readonly mapper?: (content: ElementContent) => FlowrSearchElement<ParentInformation>[];
 }
-export type EnrichmentContent<E extends Enrichment> = typeof Enrichments[E] extends EnrichmentData<infer Content, infer _Args> ? Content : never;
-export type EnrichmentArguments<E extends Enrichment> = typeof Enrichments[E] extends EnrichmentData<infer _Content, infer Args> ? Args : never;
+export type EnrichmentElementContent<E extends Enrichment> = typeof Enrichments[E] extends EnrichmentData<infer EC, infer _EA, infer _SC, infer _SA> ? EC : never;
+export type EnrichmentElementArguments<E extends Enrichment> = typeof Enrichments[E] extends EnrichmentData<infer _EC, infer EA, infer _SC, infer _SA> ? EA : never;
+export type EnrichmentSearchContent<E extends Enrichment> = typeof Enrichments[E] extends EnrichmentData<infer _EC, infer _EA, infer SC, infer _SA> ? SC : never;
+export type EnrichmentSearchArguments<E extends Enrichment> = typeof Enrichments[E] extends EnrichmentData<infer _EC, infer _EA, infer _SC, infer SA> ? SA : never;
 /**
  * An enumeration that stores the names of the available enrichments that can be applied to a set of search elements.
  * See {@link FlowrSearchBuilder.with} for more information on how to apply enrichments.
  */
 export declare enum Enrichment {
     CallTargets = "call-targets",
-    LastCall = "last-call"
+    LastCall = "last-call",
+    CfgInformation = "cfg-information",
+    QueryData = "query-data"
 }
 export interface CallTargetsContent extends MergeableRecord {
     /**
@@ -43,13 +44,52 @@ export interface CallTargetsContent extends MergeableRecord {
 export interface LastCallContent extends MergeableRecord {
     linkedIds: FlowrSearchElement<ParentInformation>[];
 }
+export interface CfgInformationElementContent extends MergeableRecord {
+    /**
+     * Whether the current node is a root node in the CFG, which is a node that is not contained inside of a function definition.
+     */
+    isRoot: boolean;
+    /**
+     * Whether the current node is reachable from the root of the CFG.
+     * Only has a value if {@link CfgInformationArguments.checkReachable} was true.
+     */
+    isReachable?: boolean;
+}
+export interface CfgInformationSearchContent extends MergeableRecord {
+    /**
+     * The CFG attached to the search, extracted using {@link extractCfg}.
+     */
+    cfg: ControlFlowInformation;
+    /**
+     * The set of all nodes that are reachable from the root of the CFG, extracted using {@link visitCfgInOrder}.
+     * Only has a value if {@link CfgInformationArguments.checkReachable} was true.
+     */
+    reachableNodes?: Set<NodeId>;
+}
+export interface CfgInformationArguments extends MergeableRecord {
+    /** Whether to recalculate the CFG information if it already exists on the current search. Defaults to `false`. */
+    forceRefresh?: boolean;
+    /** The simplification passes that should be run on the extracted CFG. Defaults to the entries of {@link DefaultCfgSimplificationOrder}. */
+    simplificationPasses?: CfgSimplificationPassName[];
+    /** Whether to check nodes for reachability, and subsequently set {@link CfgInformationSearchContent.reachableNodes} and {@link CfgInformationElementContent.isReachable}. Defaults to `false`. */
+    checkReachable?: boolean;
+}
+export interface QueryDataElementContent extends MergeableRecord {
+    /** The name of the query that this element originated from. To get each query's data, see {@link QueryDataSearchContent}. */
+    query: SynchronousQuery['type'];
+}
+export interface QueryDataSearchContent extends MergeableRecord {
+    queries: {
+        [QueryType in SynchronousQuery['type']]: AsyncOrSyncType<QueryResult<QueryType>>;
+    };
+}
 /**
  * The registry of enrichments that are currently supported by the search.
  * See {@link FlowrSearchBuilder.with} for more information on how to apply enrichments.
  */
 export declare const Enrichments: {
     readonly "call-targets": {
-        enrich: (e: FlowrSearchElement<ParentInformation>, data: import("../../core/steps/pipeline/pipeline").PipelineOutput<Pipeline<import("../../core/steps/pipeline-step").IPipelineStep<import("../../core/steps/pipeline-step").PipelineStepName, (...args: any[]) => any>>> & {
+        enrichElement: (e: FlowrSearchElement<ParentInformation>, _s: FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, data: import("../../core/steps/pipeline/pipeline").PipelineOutput<Pipeline<import("../../core/steps/pipeline-step").IPipelineStep<import("../../core/steps/pipeline-step").PipelineStepName, (...args: any[]) => any>>> & {
             normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
             dataflow: import("../../dataflow/info").DataflowInformation;
             config: import("../../config").FlowrConfigOptions;
@@ -59,13 +99,40 @@ export declare const Enrichments: {
         mapper: ({ targets }: CallTargetsContent) => FlowrSearchElement<ParentInformation>[];
     };
     readonly "last-call": {
-        enrich: (e: FlowrSearchElement<ParentInformation>, data: import("../../core/steps/pipeline/pipeline").PipelineOutput<Pipeline<import("../../core/steps/pipeline-step").IPipelineStep<import("../../core/steps/pipeline-step").PipelineStepName, (...args: any[]) => any>>> & {
+        enrichElement: (e: FlowrSearchElement<ParentInformation>, _s: FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, data: import("../../core/steps/pipeline/pipeline").PipelineOutput<Pipeline<import("../../core/steps/pipeline-step").IPipelineStep<import("../../core/steps/pipeline-step").PipelineStepName, (...args: any[]) => any>>> & {
             normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
             dataflow: import("../../dataflow/info").DataflowInformation;
             config: import("../../config").FlowrConfigOptions;
         }, args: Omit<LinkToLastCall<string | RegExp>, "type">[] | undefined, prev: LastCallContent | undefined) => LastCallContent;
         mapper: ({ linkedIds }: LastCallContent) => FlowrSearchElement<ParentInformation>[];
     };
+    readonly "cfg-information": {
+        enrichElement: (e: FlowrSearchElement<ParentInformation>, search: FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, _data: import("../../core/steps/pipeline/pipeline").PipelineOutput<Pipeline<import("../../core/steps/pipeline-step").IPipelineStep<import("../../core/steps/pipeline-step").PipelineStepName, (...args: any[]) => any>>> & {
+            normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+            dataflow: import("../../dataflow/info").DataflowInformation;
+            config: import("../../config").FlowrConfigOptions;
+        }, _args: CfgInformationArguments | undefined, prev: CfgInformationElementContent | undefined) => {
+            isRoot: boolean;
+            isReachable: boolean | undefined;
+        };
+        enrichSearch: (_search: FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, data: import("../../core/steps/pipeline/pipeline").PipelineOutput<Pipeline<import("../../core/steps/pipeline-step").IPipelineStep<import("../../core/steps/pipeline-step").PipelineStepName, (...args: any[]) => any>>> & {
+            normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+            dataflow: import("../../dataflow/info").DataflowInformation;
+            config: import("../../config").FlowrConfigOptions;
+        }, args: CfgInformationArguments | undefined, prev: CfgInformationSearchContent | undefined) => CfgInformationSearchContent;
+    };
+    readonly "query-data": {
+        enrichElement: (_e: FlowrSearchElement<ParentInformation>, _search: FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, _data: import("../../core/steps/pipeline/pipeline").PipelineOutput<Pipeline<import("../../core/steps/pipeline-step").IPipelineStep<import("../../core/steps/pipeline-step").PipelineStepName, (...args: any[]) => any>>> & {
+            normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+            dataflow: import("../../dataflow/info").DataflowInformation;
+            config: import("../../config").FlowrConfigOptions;
+        }, args: QueryDataElementContent | undefined, prev: QueryDataElementContent | undefined) => QueryDataElementContent;
+        enrichSearch: (_search: FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, _data: import("../../core/steps/pipeline/pipeline").PipelineOutput<Pipeline<import("../../core/steps/pipeline-step").IPipelineStep<import("../../core/steps/pipeline-step").PipelineStepName, (...args: any[]) => any>>> & {
+            normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+            dataflow: import("../../dataflow/info").DataflowInformation;
+            config: import("../../config").FlowrConfigOptions;
+        }, args: QueryDataSearchContent | undefined, prev: QueryDataSearchContent | undefined) => Required<QueryDataSearchContent>;
+    };
 };
 /**
  * Returns the content of the given enrichment type from a {@link FlowrSearchElement}.
@@ -73,5 +140,5 @@ export declare const Enrichments: {
  * @param e - The search element whose enrichment content should be retrieved.
  * @param enrichment - The enrichment content, if present, else `undefined`.
  */
-export declare function enrichmentContent<E extends Enrichment>(e: FlowrSearchElement<ParentInformation>, enrichment: E): EnrichmentContent<E>;
-export declare function enrich<ElementIn extends FlowrSearchElement<ParentInformation>, ElementOut extends ElementIn & EnrichedFlowrSearchElement<ParentInformation>, ConcreteEnrichment extends Enrichment>(e: ElementIn, data: FlowrSearchInput<Pipeline>, enrichment: ConcreteEnrichment, args?: EnrichmentArguments<ConcreteEnrichment>): ElementOut;
+export declare function enrichmentContent<E extends Enrichment>(e: FlowrSearchElement<ParentInformation>, enrichment: E): EnrichmentElementContent<E>;
+export declare function enrichElement<Element extends FlowrSearchElement<ParentInformation>, E extends Enrichment>(e: Element, s: FlowrSearchElements<ParentInformation>, data: FlowrSearchInput<Pipeline>, enrichment: E, args?: EnrichmentElementArguments<E>): Element;