@eagleoutice/flowr 2.1.10 → 2.1.12

package/search/flowr-search-builder.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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");
+/**
+ * This object holds all the methods to generate search queries.
+ * For compatibility, please use the {@link Q} identifier object to access these methods.
+ */
+exports.FlowrSearchGenerator = {
+    /**
+     * Initialize a search query with the given elements.
+     * <b>This is not intended to serialize well</b> wrt. the nodes,
+     * see {@link FlowrSearchGenerator.criterion} for a serializable alternative (passing the ids with `$id`).
+     */
+    from(from) {
+        return new FlowrSearchBuilder({ type: 'generator', name: 'from', args: { from } });
+    },
+    /**
+     * Returns all elements (nodes/dataflow vertices) from the given data.
+     */
+    all() {
+        return new FlowrSearchBuilder({ type: 'generator', name: 'all', args: undefined });
+    },
+    /**
+     * Returns all elements that match the given {@link FlowrSearchGetFilters|filters}.
+     * You may pass a negative line number to count from the back.
+     * Please note that this is currently only working for single files, it approximates over the nodes, and it is not to be used for "production".
+     */
+    get(filter) {
+        (0, assert_1.guard)(!filter.nameIsRegex || filter.name, 'If nameIsRegex is set, a name should be provided');
+        (0, assert_1.guard)(!filter.line || filter.line != 0, 'If line is set, it must be different from 0 as there is no 0 line');
+        (0, assert_1.guard)(!filter.column || filter.column > 0, 'If column is set, it must be greater than 0, but was ' + filter.column);
+        return new FlowrSearchBuilder({ type: 'generator', name: 'get', args: { filter } });
+    },
+    /**
+     * Returns all elements that match the given {@link SlicingCriteria|criteria}
+     * (e.g., `criterion('2@x', '3@<-')`,
+     * to retrieve the first use of `x` in the second line and the first `<-` assignment in the third line).
+     * This will throw an error, if any criteria cannot be resolved to an id.
+     */
+    criterion(...criterion) {
+        (0, assert_1.guard)(criterion.length > 0, 'At least one criterion must be provided');
+        return new FlowrSearchBuilder({ type: 'generator', name: 'criterion', args: { criterion } });
+    },
+    /**
+     * Short form of {@link get} with only the
+     * {@link FlowrSearchGetFilters#line|line} and {@link FlowrSearchGetFilters#column|column} filters:
+     * `get({line, column})`.
+     */
+    loc(line, column) {
+        return exports.FlowrSearchGenerator.get({ line, column });
+    },
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} and {@link FlowrSearchGetFilters#line|line} filters:
+     * `get({name, line})`.
+     */
+    varInLine(name, line) {
+        return exports.FlowrSearchGenerator.get({ name, line });
+    },
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} filter:
+     * `get({name})`.
+     */
+    var(name) {
+        return exports.FlowrSearchGenerator.get({ name });
+    },
+    /**
+     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#id|id} filter:
+     * `get({id})`.
+     */
+    id(id) {
+        return exports.FlowrSearchGenerator.get({ id });
+    }
+};
+/**
+ * This is the root object to use for creating searches.
+ * See the {@link FlowrSearchGenerator} for the available methods.
+ * After the query is generated,
+ * you can use what is provided by the {@link FlowrSearchBuilder} to further refine the search.
+ */
+exports.Q = exports.FlowrSearchGenerator;
+/**
+ * Allows you to construct a search query from a {@link FlowrSearchGeneratorNode}.
+ * Please use the {@link Q} object to create an object of this class!
+ * In the end, you _can_ freeze the search by calling {@link FlowrSearchBuilder#build},
+ * however, the search executors may do that for you.
+ *
+ * @see {@link FlowrSearchGenerator}
+ * @see {@link FlowrSearch}
+ * @see {@link FlowrSearchLike}
+ */
+class FlowrSearchBuilder {
+    generator;
+    search = [];
+    constructor(generator) {
+        this.generator = generator;
+    }
+    /**
+     * only returns the elements that match the given filter.
+     */
+    filter(filter) {
+        this.search.push({ type: 'transformer', name: 'filter', args: { filter: filter } });
+        return this;
+    }
+    /**
+     * first either returns the first element of the search or nothing, if no elements are present.
+     */
+    first() {
+        this.search.push({ type: 'transformer', name: 'first', args: undefined });
+        return this;
+    }
+    /**
+     * last either returns the last element of the search or nothing, if no elements are present.
+     */
+    last() {
+        this.search.push({ type: 'transformer', name: 'last', args: undefined });
+        return this;
+    }
+    /**
+     * index returns the element at the given index if it exists
+     */
+    index(index) {
+        (0, assert_1.guard)(index >= 0, 'Index must be greater or equal to 0, but was ' + index);
+        this.search.push({ type: 'transformer', name: 'index', args: { index } });
+        return this;
+    }
+    /**
+     * tail returns all elements of the search except the first one.
+     */
+    tail() {
+        this.search.push({ type: 'transformer', name: 'tail', args: undefined });
+        return this;
+    }
+    /**
+     * take returns the first `count` elements of the search.
+     */
+    take(count) {
+        (0, assert_1.guard)(count >= 0, 'Count must be greater or equal to 0, but was ' + count);
+        this.search.push({ type: 'transformer', name: 'take', args: { count } });
+        return this;
+    }
+    /**
+     * skip returns all elements of the search except the first `count` ones.
+     */
+    skip(count) {
+        (0, assert_1.guard)(count >= 0, 'Count must be greater or equal to 0, but was ' + count);
+        this.search.push({ type: 'transformer', name: 'skip', args: { count } });
+        return this;
+    }
+    /**
+     * select returns only the elements at the given indices.
+     */
+    select(...select) {
+        (0, assert_1.guard)(select.length > 0, 'At least one index must be provided');
+        (0, assert_1.guard)(select.every(i => i >= 0), () => 'All indices must be greater or equal to 0, but were ' + JSON.stringify(select));
+        this.search.push({ type: 'transformer', name: 'select', args: { select } });
+        return this;
+    }
+    /**
+     * merge combines the search results with those of another search.
+     */
+    merge(other /* | FlowrSearch<Info, Generator2, Transformers2, OtherElementType> */
+    // @ts-expect-error -- this works when merging, there is no info disparity
+    ) {
+        this.search.push({ type: 'transformer', name: 'merge', args: { generator: other.generator, search: other.search } });
+        return this;
+    }
+    /**
+     * Construct the final search (this may happen automatically with most search handlers).
+     *
+     * @param shouldOptimize - This may optimize the search.
+     */
+    build(shouldOptimize = true) {
+        return shouldOptimize ? (0, search_optimizer_1.optimize)(this.generator, this.search) : {
+            generator: this.generator,
+            search: this.search
+        };
+    }
+}
+exports.FlowrSearchBuilder = FlowrSearchBuilder;
+/**
+ * Freezes any accepted {@link FlowrSearchLike} into a {@link FlowrSearch}.
+ */
+function getFlowrSearch(search, optimizeIfBuild = true) {
+    if (search instanceof FlowrSearchBuilder) {
+        return search.build(optimizeIfBuild);
+    }
+    return search;
+}
+//# sourceMappingURL=flowr-search-builder.js.map

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

@@ -0,0 +1,9 @@
+import type { FlowrSearch, FlowrSearchLike, SearchOutput } from './flowr-search-builder';
+import type { FlowrSearchElements, 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;
+/**
+ * Run a search with the given search query and data.
+ */
+export declare function runSearch<S extends FlowrSearchLike, P extends Pipeline>(search: S, data: FlowrSearchInput<P>): GetSearchElements<SearchOutput<S>>;
+export {};

package/search/flowr-search-executor.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSearch = runSearch;
+const flowr_search_builder_1 = require("./flowr-search-builder");
+const search_generators_1 = require("./search-executor/search-generators");
+const search_transformer_1 = require("./search-executor/search-transformer");
+/**
+ * Run a search with the given search query and data.
+ */
+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();
+}
+//# sourceMappingURL=flowr-search-executor.js.map

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

@@ -0,0 +1,74 @@
+import { RType } from '../r-bridge/lang-4.x/ast/model/type';
+import type { VertexType } from '../dataflow/graph/vertex';
+import type { NormalizedAst, ParentInformation } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { DataflowInformation } from '../dataflow/info';
+import type { RNode } from '../r-bridge/lang-4.x/ast/model/model';
+export type FlowrFilterName = keyof typeof FlowrFilters;
+export declare enum FlowrFilter {
+    DropEmptyArguments = "drop-empty-arguments"
+}
+export declare const ValidFlowrFilters: Set<string>;
+export declare const ValidFlowrFiltersReverse: {
+    [k: string]: string;
+};
+export declare const FlowrFilters: {
+    readonly "drop-empty-arguments": (n: RNode<ParentInformation>) => boolean;
+};
+type ValidFilterTypes = FlowrFilterName | RType | VertexType;
+/**
+ * By default, we provide filter for every {@link RType} and {@link VertexType}.
+ */
+export type FlowrFilterExpression = FlowrFilterCombinator | ValidFilterTypes;
+interface BooleanBinaryNode<Composite> {
+    readonly type: 'and' | 'or' | 'xor';
+    readonly left: Composite;
+    readonly right: Composite;
+}
+interface BooleanUnaryNode<Composite> {
+    readonly type: 'not';
+    readonly operand: Composite;
+}
+type LeafRType = {
+    readonly type: 'r-type';
+    readonly value: RType;
+};
+type LeafVertexType = {
+    readonly type: 'vertex-type';
+    readonly value: VertexType;
+};
+type LeafSpecial = {
+    readonly type: 'special';
+    readonly value: string;
+};
+type Leaf = LeafRType | LeafVertexType | LeafSpecial;
+type BooleanNode = BooleanBinaryNode<BooleanNode> | BooleanUnaryNode<BooleanNode> | Leaf;
+type BooleanNodeOrCombinator = BooleanNode | FlowrFilterCombinator;
+/**
+ * @see {@link FlowrFilterCombinator.is}
+ * @see {@link evalFilter}
+ * @see {@link binaryTreeToString}
+ */
+export declare class FlowrFilterCombinator {
+    private tree;
+    protected constructor(init: BooleanNodeOrCombinator);
+    static is(value: BooleanNodeOrCombinator | ValidFilterTypes): FlowrFilterCombinator;
+    and(right: BooleanNodeOrCombinator | ValidFilterTypes): this;
+    or(right: BooleanNodeOrCombinator | ValidFilterTypes): this;
+    xor(right: BooleanNodeOrCombinator | ValidFilterTypes): this;
+    private binaryRight;
+    not(): this;
+    private unary;
+    private unpack;
+    get(): BooleanNode;
+}
+export declare function binaryTreeToString(tree: BooleanNode): string;
+export declare function isBinaryTree(tree: unknown): tree is {
+    tree: BooleanNode;
+};
+interface FilterData {
+    readonly node: RNode<ParentInformation>;
+    readonly normalize: NormalizedAst;
+    readonly dataflow: DataflowInformation;
+}
+export declare function evalFilter(filter: FlowrFilterExpression, data: FilterData): boolean;
+export {};

package/search/flowr-search-filters.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrFilterCombinator = exports.FlowrFilters = exports.ValidFlowrFiltersReverse = exports.ValidFlowrFilters = exports.FlowrFilter = void 0;
+exports.binaryTreeToString = binaryTreeToString;
+exports.isBinaryTree = isBinaryTree;
+exports.evalFilter = evalFilter;
+const type_1 = require("../r-bridge/lang-4.x/ast/model/type");
+const vertex_1 = require("../dataflow/graph/vertex");
+var FlowrFilter;
+(function (FlowrFilter) {
+    FlowrFilter["DropEmptyArguments"] = "drop-empty-arguments";
+})(FlowrFilter || (exports.FlowrFilter = FlowrFilter = {}));
+exports.ValidFlowrFilters = new Set(Object.values(FlowrFilter));
+exports.ValidFlowrFiltersReverse = Object.fromEntries(Object.entries(FlowrFilter).map(([k, v]) => [v, k]));
+exports.FlowrFilters = {
+    [FlowrFilter.DropEmptyArguments]: (n) => {
+        return n.type !== type_1.RType.Argument || n.name !== undefined;
+    }
+};
+/**
+ * @see {@link FlowrFilterCombinator.is}
+ * @see {@link evalFilter}
+ * @see {@link binaryTreeToString}
+ */
+class FlowrFilterCombinator {
+    tree;
+    constructor(init) {
+        this.tree = this.unpack(init);
+    }
+    static is(value) {
+        if (typeof value === 'object') {
+            return new this(value);
+        }
+        else if (type_1.ValidRTypes.has(value)) {
+            return new this({ type: 'r-type', value: value });
+        }
+        else if (vertex_1.ValidVertexTypes.has(value)) {
+            return new this({ type: 'vertex-type', value: value });
+        }
+        else if (exports.ValidFlowrFilters.has(value)) {
+            return new this({ type: 'special', value: value });
+        }
+        else {
+            throw new Error(`Invalid filter value: ${value}`);
+        }
+    }
+    and(right) {
+        return this.binaryRight('and', right);
+    }
+    or(right) {
+        return this.binaryRight('or', right);
+    }
+    xor(right) {
+        return this.binaryRight('xor', right);
+    }
+    binaryRight(op, right) {
+        this.tree = {
+            type: op,
+            left: this.tree,
+            right: this.unpack(FlowrFilterCombinator.is(right))
+        };
+        return this;
+    }
+    not() {
+        return this.unary('not');
+    }
+    unary(op) {
+        this.tree = {
+            type: op,
+            operand: this.tree
+        };
+        return this;
+    }
+    unpack(val) {
+        return val instanceof FlowrFilterCombinator ? val.tree : val;
+    }
+    get() {
+        return this.tree;
+    }
+}
+exports.FlowrFilterCombinator = FlowrFilterCombinator;
+function binaryTreeToString(tree) {
+    const res = treeToStringImpl(tree, 0);
+    // drop outer parens
+    if (res.startsWith('(') && res.endsWith(')')) {
+        return res.slice(1, -1);
+    }
+    else {
+        return res;
+    }
+}
+const typeToSymbol = {
+    'and': '∧',
+    'or': '∨',
+    'xor': '⊕',
+    'not': '¬'
+};
+function treeToStringImpl(tree, depth) {
+    if (tree.type === 'r-type' || tree.type === 'vertex-type' || tree.type === 'special') {
+        return tree.value;
+    }
+    if (tree.type === 'not') {
+        return `${typeToSymbol[tree.type]}${treeToStringImpl(tree.operand, depth)}`;
+    }
+    const left = treeToStringImpl(tree.left, depth + 1);
+    const right = treeToStringImpl(tree.right, depth + 1);
+    return `(${left} ${typeToSymbol[tree.type]} ${right})`;
+}
+function isBinaryTree(tree) {
+    return typeof tree === 'object' && tree !== null && 'tree' in tree;
+}
+const evalVisit = {
+    and: ({ left, right }, data) => evalTree(left, data) && evalTree(right, data),
+    or: ({ left, right }, data) => evalTree(left, data) || evalTree(right, data),
+    xor: ({ left, right }, data) => evalTree(left, data) !== evalTree(right, data),
+    not: ({ operand }, data) => !evalTree(operand, data),
+    'r-type': ({ value }, { node }) => node.type === value,
+    'vertex-type': ({ value }, { dataflow: { graph }, node }) => graph.getVertex(node.info.id)?.tag === value,
+    'special': ({ value }, { node }) => {
+        const getHandler = exports.FlowrFilters[value];
+        if (getHandler) {
+            return getHandler(node);
+        }
+        throw new Error(`Special filter not implemented: ${value}`);
+    }
+};
+function evalTree(tree, data) {
+    /* we ensure that the types fit */
+    return evalVisit[tree.type](tree, data);
+}
+function evalFilter(filter, data) {
+    /* common lift, this can be improved easily :D */
+    const tree = FlowrFilterCombinator.is(filter);
+    return evalTree(tree.get(), data);
+}
+//# sourceMappingURL=flowr-search-filters.js.map

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

@@ -0,0 +1,10 @@
+import type { FlowrSearchLike } from './flowr-search-builder';
+export interface FlowrSearchMermaidBuilderOptions {
+    header?: string;
+}
+/**
+ * Converts a {@link FlowrSearchLike} object to a mermaid flowchart.
+ */
+export declare function flowrSearchToMermaid(search: FlowrSearchLike, conf?: FlowrSearchMermaidBuilderOptions): string;
+export declare function flowrSearchToAscii(search: FlowrSearchLike): string;
+export declare function flowrSearchToCode(search: FlowrSearchLike): string;

package/search/flowr-search-printer.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flowrSearchToMermaid = flowrSearchToMermaid;
+exports.flowrSearchToAscii = flowrSearchToAscii;
+exports.flowrSearchToCode = flowrSearchToCode;
+const flowr_search_traverse_1 = require("./flowr-search-traverse");
+const mermaid_1 = require("../util/mermaid/mermaid");
+const flowr_search_filters_1 = require("./flowr-search-filters");
+const vertex_1 = require("../dataflow/graph/vertex");
+const type_1 = require("../r-bridge/lang-4.x/ast/model/type");
+/**
+ * Converts a {@link FlowrSearchLike} object to a mermaid flowchart.
+ */
+function flowrSearchToMermaid(search, conf) {
+    const out = [conf?.header ?? 'flowchart LR'];
+    let count = 0;
+    out.push((0, flowr_search_traverse_1.traverseFlowrSearchBuilderType)(search, ({ type, name, args }) => `${count}("<b>${name}</b>(${argsToMermaidString(args)})<br/>_${type}_")`, (acc, { name, args, type }) => `${acc} --> ${++count}["<b>${name}</b>(${argsToMermaidString(args)})<br/>_${type}_"]`));
+    return out.join('\n');
+}
+function argsToMermaidString(args) {
+    if (args === undefined) {
+        return '';
+    }
+    return Object.entries(args).map(([key, value]) => `${key}: ${(0, flowr_search_filters_1.isBinaryTree)(value) ? '_' + (0, mermaid_1.escapeMarkdown)((0, flowr_search_filters_1.binaryTreeToString)(value.tree)) + '_'
+        : (0, mermaid_1.escapeMarkdown)(JSON.stringify(value))}`)
+        .join(', ');
+}
+function argsToAsciiString(args) {
+    if (args === undefined) {
+        return '';
+    }
+    else if (Object.keys(args).length === 1) {
+        const key = Object.keys(args)[0];
+        const value = args[key];
+        return `${key}: ${(0, flowr_search_filters_1.isBinaryTree)(value) ? '_' + (0, flowr_search_filters_1.binaryTreeToString)(value.tree) + '_' : JSON.stringify(value)}`;
+    }
+    return Object.entries(args).map(([key, value]) => `${key}: ${(0, flowr_search_filters_1.isBinaryTree)(value) ? '_' + (0, flowr_search_filters_1.binaryTreeToString)(value.tree) + '_' : JSON.stringify(value)}`)
+        .join(', ');
+}
+function flowrSearchToAscii(search) {
+    return (0, flowr_search_traverse_1.traverseFlowrSearchBuilderType)(search, ({ name, args }) => `${name}(${argsToAsciiString(args)})`, (acc, { name, args }) => `${acc} --> ${name}(${argsToAsciiString(args)})`);
+}
+function argsToCodeString(args) {
+    if (args === undefined) {
+        return '';
+    }
+    return Object.entries(args).map(([, value]) => `${JSON.stringify(value)}`)
+        .join(', ');
+}
+function flowrSearchToCode(search) {
+    return (0, flowr_search_traverse_1.traverseFlowrSearchBuilderType)(search, (node) => `Q.${flowrGeneratorToCode(node)}`, (acc, node) => `${acc}.${flowrTransformerToCode(node)}`);
+}
+function flowrTransformerToCode(node) {
+    if (node.name === 'filter') {
+        const a = node.args.filter;
+        if (vertex_1.ValidVertexTypes.has(String(a))) {
+            return `${node.name}(VertexType.${vertex_1.ValidVertexTypeReverse[String(a)]})`;
+        }
+        else if (type_1.ValidRTypes.has(String(a))) {
+            return `${node.name}(RType.${type_1.ValidRTypesReverse[String(a)]})`;
+        }
+        else if (flowr_search_filters_1.ValidFlowrFilters.has(String(a))) {
+            return `${node.name}(FlowrFilter.${flowr_search_filters_1.ValidFlowrFiltersReverse[String(a)]})`;
+        }
+    }
+    return `${node.name}(${argsToCodeString(node.args)})`;
+}
+function flowrGeneratorToCode(node) {
+    if (node.name !== 'get') {
+        return `${node.name}(${argsToCodeString(node.args)})`;
+    }
+    const a = node.args.filter;
+    if (Object.keys(a).length === 1) {
+        if (a.name) {
+            return `var(${JSON.stringify(a.name)})`;
+        }
+    }
+    else if (Object.keys(a).length === 2) {
+        if (a.name && a.line) {
+            return `varInLine(${JSON.stringify(a.name)}, ${JSON.stringify(a.line)})`;
+        }
+    }
+    return `${node.name}(${argsToCodeString(node.args)})`;
+}
+//# sourceMappingURL=flowr-search-printer.js.map

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

@@ -0,0 +1,7 @@
+import type { FlowrSearchLike } from './flowr-search-builder';
+import type { FlowrSearchGeneratorNode } from './search-executor/search-generators';
+import type { FlowrSearchTransformerNode } from './search-executor/search-transformer';
+/**
+ * Allows you to traverse a {@link FlowrSearchLike} object.
+ */
+export declare function traverseFlowrSearchBuilderType<Accumulate, GeneratorVisit extends (generator: FlowrSearchGeneratorNode) => Accumulate, TransformerVisit extends (acc: Accumulate, transformer: FlowrSearchTransformerNode) => Accumulate>(search: FlowrSearchLike, gen: GeneratorVisit, trans: TransformerVisit): Accumulate;

package/search/flowr-search-traverse.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traverseFlowrSearchBuilderType = traverseFlowrSearchBuilderType;
+const flowr_search_builder_1 = require("./flowr-search-builder");
+/**
+ * Allows you to traverse a {@link FlowrSearchLike} object.
+ */
+function traverseFlowrSearchBuilderType(search, gen, trans) {
+    const s = (0, flowr_search_builder_1.getFlowrSearch)(search);
+    return s.search.reduce(trans, gen(s.generator));
+}
+//# sourceMappingURL=flowr-search-traverse.js.map

package/search/flowr-search.d.ts

@@ -0,0 +1,58 @@
+import type { NoInfo, RNode } from '../r-bridge/lang-4.x/ast/model/model';
+import type { Pipeline, PipelineOutput, PipelineStepOutputWithName } from '../core/steps/pipeline/pipeline';
+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';
+/**
+ * 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>;
+}
+export interface FlowrSearchNodeBase<Type extends string, Name extends string, Args extends Record<string, unknown> | undefined> {
+    readonly type: Type;
+    readonly name: Name;
+    readonly args: Args;
+}
+export type FlowrSearchGeneratorNodeBase<Name extends string, Args extends Record<string, unknown> | undefined> = FlowrSearchNodeBase<'generator', Name, Args>;
+export type FlowrSearchTransformerNodeBase<Name extends string, Args extends Record<string, unknown> | undefined> = FlowrSearchNodeBase<'transformer', Name, Args>;
+export interface FlowrSearchGetFilter extends Record<string, unknown> {
+    /**
+     * The node must be in the given line.
+     */
+    readonly line?: number;
+    /**
+     * The node must be in the given column.
+     */
+    readonly column?: number;
+    /**
+     * The node must have the given name.
+     * To treat this name as a regular expression, set {@link FlowrSearchGetFilter#nameIsRegex} to true.
+     */
+    readonly name?: string;
+    /**
+     * Only useful in combination with `name`. If true, the name is treated as a regular expression.
+     */
+    readonly nameIsRegex?: boolean;
+    /**
+     * The node must have the given id.
+     */
+    readonly id?: NodeId;
+}
+type MinimumInputForFlowrSearch<P extends Pipeline> = PipelineStepOutputWithName<P, 'normalize'> extends NormalizedAst ? (PipelineStepOutputWithName<P, 'dataflow'> extends DataflowInformation ? PipelineOutput<P> & {
+    normalize: NormalizedAst;
+    dataflow: DataflowInformation;
+} : never) : never;
+/** we allow any pipeline, which provides us with a 'normalize' and 'dataflow' step */
+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;
+    constructor(elements?: Elements);
+    add(element: FlowrSearchElement<Info>): this;
+    addAll(elements: FlowrSearchElement<Info>[]): this;
+    getElements(): readonly FlowrSearchElement<Info>[];
+    mutate<OutElements extends Elements>(mutator: (elements: Elements) => OutElements): this;
+}
+export {};

package/search/flowr-search.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrSearchElements = void 0;
+/** Intentionally, we abstract away from an array to avoid the use of conventional typescript operations */
+class FlowrSearchElements {
+    elements = [];
+    constructor(elements) {
+        if (elements) {
+            this.elements = elements;
+        }
+    }
+    add(element) {
+        this.elements.push(element);
+        return this;
+    }
+    addAll(elements) {
+        this.elements.push(...elements);
+        return this;
+    }
+    getElements() {
+        return this.elements;
+    }
+    mutate(mutator) {
+        this.elements = mutator(this.elements);
+        return this;
+    }
+}
+exports.FlowrSearchElements = FlowrSearchElements;
+//# sourceMappingURL=flowr-search.js.map

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

@@ -0,0 +1,37 @@
+import type { FlowrSearchElement, FlowrSearchGeneratorNodeBase, FlowrSearchGetFilter, FlowrSearchInput } from '../flowr-search';
+import { FlowrSearchElements } from '../flowr-search';
+import type { Pipeline } from '../../core/steps/pipeline/pipeline';
+import type { TailTypesOrUndefined } from '../../util/arrays';
+import type { ParentInformation } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { SlicingCriteria } from '../../slicing/criterion/parse';
+/**
+ * This is a union of all possible generator node types
+ */
+export type FlowrSearchGeneratorNode = {
+    [K in GeneratorNames]: FlowrSearchGeneratorNodeBase<K, TailTypesOrUndefined<Parameters<typeof generators[K]>>>;
+}[GeneratorNames];
+export type GeneratorNames = keyof typeof generators;
+export type GetGenerator<Name extends GeneratorNames> = FlowrSearchGeneratorNode & {
+    name: Name;
+};
+/**
+ * All supported generators!
+ */
+export declare const generators: {
+    readonly all: typeof generateAll;
+    readonly get: typeof generateGet;
+    readonly criterion: typeof generateCriterion;
+    readonly from: typeof generateFrom;
+};
+declare function generateAll(data: FlowrSearchInput<Pipeline>): FlowrSearchElements<ParentInformation>;
+declare function generateGet(data: FlowrSearchInput<Pipeline>, { filter: { line, column, id, name, nameIsRegex } }: {
+    filter: FlowrSearchGetFilter;
+}): FlowrSearchElements<ParentInformation>;
+declare function generateFrom(data: FlowrSearchInput<Pipeline>, args: {
+    from: FlowrSearchElement<ParentInformation> | FlowrSearchElement<ParentInformation>[];
+}): FlowrSearchElements<ParentInformation>;
+declare function generateCriterion(data: FlowrSearchInput<Pipeline>, args: {
+    criterion: SlicingCriteria;
+}): FlowrSearchElements<ParentInformation>;
+export declare function getGenerator<Name extends GeneratorNames>(name: Name): typeof generators[Name];
+export {};