@eagleoutice/flowr 2.2.13 → 2.2.14

package/search/flowr-search-builder.js

@@ -4,6 +4,7 @@ exports.FlowrSearchBuilder = exports.Q = exports.FlowrSearchGenerator = void 0;
 exports.getFlowrSearch = getFlowrSearch;
 const search_optimizer_1 = require("./search-optimizer/search-optimizer");
 const assert_1 = require("../util/assert");
+const search_mappers_1 = require("./search-executor/search-mappers");
 /**
  * This object holds all the methods to generate search queries.
  * For compatibility, please use the {@link Q} identifier object to access these methods.
@@ -17,6 +18,14 @@ exports.FlowrSearchGenerator = {
     from(from) {
         return new FlowrSearchBuilder({ type: 'generator', name: 'from', args: { from } });
     },
+    /**
+     * Initializes a new search query based on the results of the given JSON query or queries.
+     * 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.
+     */
+    fromQuery(...from) {
+        return new FlowrSearchBuilder({ type: 'generator', name: 'from-query', args: { from } });
+    },
     /**
      * Returns all elements (nodes/dataflow vertices) from the given data.
      */
@@ -158,6 +167,27 @@ class FlowrSearchBuilder {
         this.search.push({ type: 'transformer', name: 'select', args: { select } });
         return this;
     }
+    /**
+     * Adds the given enrichment to each element of the search.
+     * Added enrichments can later be retrieved using the {@link enrichmentContent} function.
+     */
+    with(enrichment, args) {
+        this.search.push({ type: 'transformer', name: 'with', args: { info: enrichment, args: args } });
+        return this;
+    }
+    /**
+     * Maps the elements of the search to new values using the given mapper function.
+     */
+    map(mapper, args) {
+        this.search.push({ type: 'transformer', name: 'map', args: { mapper: mapper, args: args } });
+        return this;
+    }
+    /**
+     * 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(enrichment, args) {
+        return this.with(enrichment, args).map(search_mappers_1.Mapper.Enrichment, enrichment);
+    }
     /**
      * merge combines the search results with those of another search.
      */

package/search/flowr-search.d.ts

@@ -3,6 +3,8 @@ 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';
 /**
  * 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.
@@ -10,6 +12,10 @@ import type { DataflowInformation } from '../dataflow/info';
 export interface FlowrSearchElement<Info> {
     readonly node: RNode<Info>;
 }
+export interface FlowrSearchElementFromQuery<Info> extends FlowrSearchElement<Info> {
+    readonly query: Query['type'];
+    readonly queryResult: BaseQueryResult;
+}
 export interface FlowrSearchNodeBase<Type extends string, Name extends string, Args extends Record<string, unknown> | undefined> {
     readonly type: Type;
     readonly name: Name;
@@ -52,7 +58,7 @@ export declare class FlowrSearchElements<Info = NoInfo, Elements extends FlowrSe
     constructor(elements?: Elements);
     add(element: FlowrSearchElement<Info>): this;
     addAll(elements: FlowrSearchElement<Info>[]): this;
-    getElements(): readonly FlowrSearchElement<Info>[];
+    getElements(): Readonly<Elements>;
     mutate<OutElements extends Elements>(mutator: (elements: Elements) => OutElements): this;
 }
 export {};

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

@@ -0,0 +1,73 @@
+import type { FlowrSearchElement, 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> {
+    /**
+     * 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) => EnrichmentContent;
+    /**
+     * The mapping function used by the {@link Mapper.Enrichment} mapper.
+     */
+    readonly mapper: (c: EnrichmentContent) => 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;
+/**
+ * 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"
+}
+export interface CallTargetsContent extends MergeableRecord {
+    /**
+     * The call targets of the function call.
+     * For identifier call targets, the identifier is the name of the library function being called.
+     */
+    targets: (FlowrSearchElement<ParentInformation> | Identifier)[];
+}
+export interface LastCallContent extends MergeableRecord {
+    linkedIds: FlowrSearchElement<ParentInformation>[];
+}
+/**
+ * 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>>> & {
+            normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+            dataflow: import("../../dataflow/info").DataflowInformation;
+        }) => CallTargetsContent;
+        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>>> & {
+            normalize: import("../../r-bridge/lang-4.x/ast/model/processing/decorate").NormalizedAst;
+            dataflow: import("../../dataflow/info").DataflowInformation;
+        }, args: Omit<LinkToLastCall<string | RegExp>, "type">[] | undefined) => LastCallContent;
+        mapper: ({ linkedIds }: LastCallContent) => FlowrSearchElement<ParentInformation>[];
+    };
+};
+/**
+ * Returns the content of the given enrichment type from a {@link FlowrSearchElement}.
+ * If the search element is not enriched with the given enrichment, `undefined` is returned.
+ * @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;

package/search/search-executor/search-enrichers.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Enrichments = exports.Enrichment = void 0;
+exports.enrichmentContent = enrichmentContent;
+exports.enrich = enrich;
+const vertex_1 = require("../../dataflow/graph/vertex");
+const log_1 = require("../../util/log");
+const identify_link_to_last_call_relation_1 = require("../../queries/catalog/call-context-query/identify-link-to-last-call-relation");
+const assert_1 = require("../../util/assert");
+const extract_cfg_1 = require("../../control-flow/extract-cfg");
+const dfg_get_origin_1 = require("../../dataflow/origin/dfg-get-origin");
+/**
+ * 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.
+ */
+var Enrichment;
+(function (Enrichment) {
+    Enrichment["CallTargets"] = "call-targets";
+    Enrichment["LastCall"] = "last-call";
+})(Enrichment || (exports.Enrichment = Enrichment = {}));
+/**
+ * The registry of enrichments that are currently supported by the search.
+ * See {@link FlowrSearchBuilder.with} for more information on how to apply enrichments.
+ */
+exports.Enrichments = {
+    [Enrichment.CallTargets]: {
+        enrich: (e, data) => {
+            // we don't resolve aliases here yet!
+            const content = { targets: [] };
+            const callVertex = data.dataflow.graph.getVertex(e.node.info.id);
+            if (callVertex?.tag === vertex_1.VertexType.FunctionCall) {
+                const origins = (0, dfg_get_origin_1.getOriginInDfg)(data.dataflow.graph, callVertex.id);
+                if (!origins || origins.length === 0) {
+                    log_1.log.warn(`No origin found for call vertex ${callVertex.id}, cannot resolve call targets.`);
+                    return content;
+                }
+                // find call targets in user code (which have ids!)
+                content.targets = content.targets.concat(origins.map(o => {
+                    switch (o.type) {
+                        case 2 /* OriginType.FunctionCallOrigin */:
+                            return {
+                                node: data.normalize.idMap.get(o.id),
+                            };
+                        case 3 /* OriginType.BuiltInFunctionOrigin */:
+                            return o.fn.name;
+                        default:
+                            return undefined;
+                    }
+                }).filter(assert_1.isNotUndefined));
+            }
+            return content;
+        },
+        // as built-in call target enrichments are not nodes, we don't return them as part of the mapper!
+        mapper: ({ targets }) => targets.map(t => t).filter(t => t.node !== undefined)
+    },
+    [Enrichment.LastCall]: {
+        enrich: (e, data, args) => {
+            (0, assert_1.guard)(args && args.length, `${Enrichment.LastCall} enrichment requires at least one argument`);
+            const content = { linkedIds: [] };
+            const vertex = data.dataflow.graph.get(e.node.info.id);
+            if (vertex !== undefined && vertex[0].tag === vertex_1.VertexType.FunctionCall) {
+                const cfg = (0, extract_cfg_1.extractSimpleCfg)(data.normalize);
+                for (const arg of args) {
+                    const lastCalls = (0, identify_link_to_last_call_relation_1.identifyLinkToLastCallRelation)(vertex[0].id, cfg.graph, data.dataflow.graph, {
+                        ...arg,
+                        callName: new RegExp(arg.callName),
+                        type: 'link-to-last-call',
+                    });
+                    for (const lastCall of lastCalls) {
+                        content.linkedIds.push({ node: data.normalize.idMap.get(lastCall) });
+                    }
+                }
+            }
+            return content;
+        },
+        mapper: ({ linkedIds }) => linkedIds
+    },
+};
+/**
+ * Returns the content of the given enrichment type from a {@link FlowrSearchElement}.
+ * If the search element is not enriched with the given enrichment, `undefined` is returned.
+ * @param e - The search element whose enrichment content should be retrieved.
+ * @param enrichment - The enrichment content, if present, else `undefined`.
+ */
+function enrichmentContent(e, enrichment) {
+    return e?.enrichments?.[enrichment];
+}
+function enrich(e, data, enrichment, args) {
+    const enrichmentData = exports.Enrichments[enrichment];
+    return {
+        ...e,
+        enrichments: {
+            ...e?.enrichments ?? {},
+            [enrichment]: enrichmentData.enrich(e, data, args)
+        }
+    };
+}
+//# sourceMappingURL=search-enrichers.js.map

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

@@ -1,9 +1,10 @@
-import type { FlowrSearchElement, FlowrSearchGeneratorNodeBase, FlowrSearchGetFilter, FlowrSearchInput } from '../flowr-search';
+import type { FlowrSearchElement, FlowrSearchElementFromQuery, FlowrSearchGeneratorNodeBase, FlowrSearchGetFilter, FlowrSearchInput } from '../flowr-search';
 import { FlowrSearchElements } from '../flowr-search';
 import type { Pipeline } from '../../core/steps/pipeline/pipeline';
 import type { TailTypesOrUndefined } from '../../util/collections/arrays';
 import type { ParentInformation } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { SlicingCriteria } from '../../slicing/criterion/parse';
+import type { Query } from '../../queries/query';
 /**
  * This is a union of all possible generator node types
  */
@@ -22,6 +23,7 @@ export declare const generators: {
     readonly get: typeof generateGet;
     readonly criterion: typeof generateCriterion;
     readonly from: typeof generateFrom;
+    readonly 'from-query': typeof generateFromQuery;
 };
 declare function generateAll(data: FlowrSearchInput<Pipeline>): FlowrSearchElements<ParentInformation>;
 declare function generateGet(data: FlowrSearchInput<Pipeline>, { filter: { line, column, id, name, nameIsRegex } }: {
@@ -30,6 +32,9 @@ declare function generateGet(data: FlowrSearchInput<Pipeline>, { filter: { line,
 declare function generateFrom(data: FlowrSearchInput<Pipeline>, args: {
     from: FlowrSearchElement<ParentInformation> | FlowrSearchElement<ParentInformation>[];
 }): FlowrSearchElements<ParentInformation>;
+declare function generateFromQuery(data: FlowrSearchInput<Pipeline>, args: {
+    from: readonly Query[];
+}): FlowrSearchElements<ParentInformation, FlowrSearchElementFromQuery<ParentInformation>[]>;
 declare function generateCriterion(data: FlowrSearchInput<Pipeline>, args: {
     criterion: SlicingCriteria;
 }): FlowrSearchElements<ParentInformation>;

package/search/search-executor/search-generators.js

@@ -5,6 +5,7 @@ exports.getGenerator = getGenerator;
 const flowr_search_1 = require("../flowr-search");
 const parse_1 = require("../../slicing/criterion/parse");
 const assert_1 = require("../../util/assert");
+const query_1 = require("../../queries/query");
 /**
  * All supported generators!
  */
@@ -12,7 +13,8 @@ exports.generators = {
     all: generateAll,
     get: generateGet,
     criterion: generateCriterion,
-    from: generateFrom
+    from: generateFrom,
+    'from-query': generateFromQuery
 };
 function generateAll(data) {
     return new flowr_search_1.FlowrSearchElements(getAllNodes(data)
@@ -52,6 +54,24 @@ function generateGet(data, { filter: { line, column, id, name, nameIsRegex } })
 function generateFrom(data, args) {
     return new flowr_search_1.FlowrSearchElements(Array.isArray(args.from) ? args.from : [args.from]);
 }
+function generateFromQuery(data, args) {
+    const nodes = new Set();
+    const result = (0, query_1.executeQueries)({ ast: data.normalize, dataflow: data.dataflow }, args.from);
+    for (const [query, content] of Object.entries(result)) {
+        if (query === '.meta') {
+            continue;
+        }
+        const queryDef = query_1.SupportedQueries[query];
+        for (const node of queryDef.flattenInvolvedNodes(content)) {
+            nodes.add({
+                node: data.normalize.idMap.get(node),
+                query: query,
+                queryResult: content
+            });
+        }
+    }
+    return new flowr_search_1.FlowrSearchElements([...nodes]);
+}
 function generateCriterion(data, args) {
     return new flowr_search_1.FlowrSearchElements(args.criterion.map(c => ({ node: data.normalize.idMap.get((0, parse_1.slicingCriterionToId)(c, data.normalize.idMap)) })));
 }

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

@@ -0,0 +1,19 @@
+import type { FlowrSearchElement, FlowrSearchInput } from '../flowr-search';
+import type { ParentInformation } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { Enrichment } from './search-enrichers';
+import type { MergeableRecord } from '../../util/objects';
+import type { Pipeline } from '../../core/steps/pipeline/pipeline';
+export declare enum Mapper {
+    Enrichment = "enrichment"
+}
+export interface MapperData<Arguments extends string | MergeableRecord> {
+    mapper: (e: FlowrSearchElement<ParentInformation>, data: FlowrSearchInput<Pipeline>, args: Arguments) => FlowrSearchElement<ParentInformation>[];
+}
+export type MapperArguments<M extends Mapper> = typeof Mappers[M] extends MapperData<infer Arguments> ? Arguments : never;
+declare const Mappers: {
+    readonly enrichment: {
+        mapper: (e: FlowrSearchElement<ParentInformation>, _data: FlowrSearchInput<Pipeline>, enrichment: Enrichment) => FlowrSearchElement<ParentInformation>[];
+    };
+};
+export declare function map<Element extends FlowrSearchElement<ParentInformation>, MapperType extends Mapper>(e: Element, data: FlowrSearchInput<Pipeline>, mapper: MapperType, args: MapperArguments<MapperType>): Element[];
+export {};

package/search/search-executor/search-mappers.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mapper = void 0;
+exports.map = map;
+const search_enrichers_1 = require("./search-enrichers");
+var Mapper;
+(function (Mapper) {
+    Mapper["Enrichment"] = "enrichment";
+})(Mapper || (exports.Mapper = Mapper = {}));
+const Mappers = {
+    [Mapper.Enrichment]: {
+        mapper: (e, _data, enrichment) => {
+            const data = (0, search_enrichers_1.enrichmentContent)(e, enrichment);
+            return data !== undefined ? search_enrichers_1.Enrichments[enrichment].mapper(data) : [];
+        }
+    }
+};
+function map(e, data, mapper, args) {
+    return Mappers[mapper].mapper(e, data, args);
+}
+//# sourceMappingURL=search-mappers.js.map

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

@@ -4,6 +4,8 @@ import type { LastOfArray, Tail2TypesOrUndefined, TailOfArray } from '../../util
 import type { FlowrFilterExpression } from '../flowr-search-filters';
 import type { FlowrSearchGeneratorNode } from './search-generators';
 import type { ParentInformation } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { EnrichedFlowrSearchElement, Enrichment, EnrichmentArguments } from './search-enrichers';
+import type { Mapper, MapperArguments } from './search-mappers';
 /**
  * This is a union of all possible transformer node types
  */
@@ -28,6 +30,8 @@ export declare const transformers: {
     readonly filter: typeof getFilter;
     readonly merge: typeof getMerge;
     readonly select: typeof getSelect;
+    readonly with: typeof getWith;
+    readonly map: typeof getMap;
 };
 export declare function getTransformer<Name extends TransformerNames>(name: Name): typeof transformers[Name];
 /** If we already have no more elements, cascade will not add any but keep the empty elements, otherwise it will now be NewElements */
@@ -50,6 +54,14 @@ declare function getSkip<Elements extends FlowrSearchElement<ParentInformation>[
 declare function getFilter<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrSearchInput<Pipeline>, elements: FSE, { filter }: {
     filter: FlowrFilterExpression;
 }): CascadeEmpty<Elements, Elements | []>;
+declare function getWith<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrSearchInput<Pipeline>, elements: FSE, { info, args }: {
+    info: Enrichment;
+    args?: EnrichmentArguments<Enrichment>;
+}): FlowrSearchElements<ParentInformation, EnrichedFlowrSearchElement<ParentInformation>[]>;
+declare function getMap<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrSearchInput<Pipeline>, elements: FSE, { mapper, args }: {
+    mapper: Mapper;
+    args: MapperArguments<Mapper>;
+}): FlowrSearchElements<ParentInformation, Elements>;
 declare function getMerge<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrSearchInput<Pipeline>, elements: FSE, other: {
     search: unknown[];
     generator: FlowrSearchGeneratorNode;

package/search/search-executor/search-transformer.js

@@ -5,6 +5,8 @@ exports.getTransformer = getTransformer;
 const flowr_search_filters_1 = require("../flowr-search-filters");
 const flowr_search_executor_1 = require("../flowr-search-executor");
 const assert_1 = require("../../util/assert");
+const search_enrichers_1 = require("./search-enrichers");
+const search_mappers_1 = require("./search-mappers");
 /**
  * All supported generators!
  */
@@ -17,7 +19,9 @@ exports.transformers = {
     skip: getSkip,
     filter: getFilter,
     merge: getMerge,
-    select: getSelect
+    select: getSelect,
+    with: getWith,
+    map: getMap
 };
 function getTransformer(name) {
     if (!exports.transformers[name]) {
@@ -90,6 +94,12 @@ function getSkip(data, elements, { count }) {
 function getFilter(data, elements, { filter }) {
     return elements.mutate(e => e.filter(({ node }) => (0, flowr_search_filters_1.evalFilter)(filter, { node, normalize: data.normalize, dataflow: data.dataflow })));
 }
+function getWith(data, elements, { info, args }) {
+    return elements.mutate(elements => elements.map(e => (0, search_enrichers_1.enrich)(e, data, info, args)));
+}
+function getMap(data, elements, { mapper, args }) {
+    return elements.mutate(elements => elements.flatMap(e => (0, search_mappers_1.map)(e, data, mapper, args)));
+}
 function getMerge(
 /* search has to be unknown because it is a recursive type */
 data, elements, other) {

package/util/version.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.flowrVersion = flowrVersion;
 const semver_1 = require("semver");
 // this is automatically replaced with the current version by release-it
-const version = '2.2.13';
+const version = '2.2.14';
 function flowrVersion() {
     return new semver_1.SemVer(version);
 }