@eagleoutice/flowr 2.6.1 → 2.6.2

package/search/flowr-search-filters.js

@@ -49,6 +49,9 @@ exports.FlowrFilters = {
         return args.matchType === 'every' ? origins.every(match) : origins.some(match);
     })
 };
+/**
+ * Helper to create a regular expression that matches function names, ignoring their package.
+ */
 function testFunctionsIgnoringPackage(functions) {
     return new RegExp(`"(.+:::?)?(${functions.join('|')})"`);
 }
@@ -120,6 +123,9 @@ class FlowrFilterCombinator {
     }
 }
 exports.FlowrFilterCombinator = FlowrFilterCombinator;
+/**
+ * Converts the given binary tree to a string representation.
+ */
 function binaryTreeToString(tree) {
     const res = treeToStringImpl(tree, 0);
     // drop outer parens
@@ -147,6 +153,10 @@ function treeToStringImpl(tree, depth) {
     const right = treeToStringImpl(tree.right, depth + 1);
     return `(${left} ${typeToSymbol[tree.type]} ${right})`;
 }
+/**
+ * Checks whether the given value is a binary tree combinator.
+ * @see {@link FlowrFilterCombinator}
+ */
 function isBinaryTree(tree) {
     return typeof tree === 'object' && tree !== null && 'tree' in tree;
 }
@@ -171,6 +181,9 @@ function evalTree(tree, data) {
     /* we ensure that the types fit */
     return evalVisit[tree.type](tree, data);
 }
+/**
+ * Evaluates the given filter expression against the provided data.
+ */
 function evalFilter(filter, data) {
     /* common lift, this can be improved easily :D */
     const tree = FlowrFilterCombinator.is(filter);

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

@@ -6,5 +6,11 @@ export interface FlowrSearchMermaidBuilderOptions {
  * Converts a {@link FlowrSearchLike} object to a mermaid flowchart.
  */
 export declare function flowrSearchToMermaid(search: FlowrSearchLike, conf?: FlowrSearchMermaidBuilderOptions): string;
+/**
+ * Converts a {@link FlowrSearchLike} object to an ASCII representation.
+ */
 export declare function flowrSearchToAscii(search: FlowrSearchLike): string;
+/**
+ * Converts a {@link FlowrSearchLike} object to code that can be used to recreate it.
+ */
 export declare function flowrSearchToCode(search: FlowrSearchLike): string;

package/search/flowr-search-printer.js

@@ -37,6 +37,9 @@ function argsToAsciiString(args) {
     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(', ');
 }
+/**
+ * Converts a {@link FlowrSearchLike} object to an ASCII representation.
+ */
 function flowrSearchToAscii(search) {
     return (0, flowr_search_traverse_1.traverseFlowrSearchBuilderType)(search, ({ name, args }) => `${name}(${argsToAsciiString(args)})`, (acc, { name, args }) => `${acc} --> ${name}(${argsToAsciiString(args)})`);
 }
@@ -47,6 +50,9 @@ function argsToCodeString(args) {
     return Object.entries(args).map(([, value]) => `${JSON.stringify(value)}`)
         .join(', ');
 }
+/**
+ * Converts a {@link FlowrSearchLike} object to code that can be used to recreate it.
+ */
 function flowrSearchToCode(search) {
     return (0, flowr_search_traverse_1.traverseFlowrSearchBuilderType)(search, (node) => `Q.${flowrGeneratorToCode(node)}`, (acc, node) => `${acc}.${flowrTransformerToCode(node)}`);
 }

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

@@ -1,4 +1,4 @@
-import type { FlowrSearchLike } from './flowr-search-builder';
+import { type FlowrSearchLike } from './flowr-search-builder';
 import type { FlowrSearchGeneratorNode } from './search-executor/search-generators';
 import type { FlowrSearchTransformerNode } from './search-executor/search-transformer';
 /**

package/search/flowr-search.d.ts

@@ -1,7 +1,7 @@
 import type { NoInfo, RNode } from '../r-bridge/lang-4.x/ast/model/model';
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
-import type { Enrichment, EnrichmentElementContent, EnrichmentSearchArguments, EnrichmentSearchContent } from './search-executor/search-enrichers';
-import type { FlowrAnalysisProvider } from '../project/flowr-analyzer';
+import { type Enrichment, type EnrichmentElementContent, type EnrichmentSearchArguments, type EnrichmentSearchContent } from './search-executor/search-enrichers';
+import type { ReadonlyFlowrAnalysisProvider } from '../project/flowr-analyzer';
 /**
  * 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.
@@ -57,6 +57,6 @@ export declare class FlowrSearchElements<Info = NoInfo, Elements extends FlowrSe
      *
      * Please note that this function does not also enrich individual elements, which is done through {@link enrichElement}. Both functions are called in a concise manner in {@link FlowrSearchBuilder.with}, which is the preferred way to add enrichments to a search.
      */
-    enrich<E extends Enrichment>(data: FlowrAnalysisProvider, enrichment: E, args?: EnrichmentSearchArguments<E>): Promise<this>;
+    enrich<E extends Enrichment>(data: ReadonlyFlowrAnalysisProvider, enrichment: E, args?: EnrichmentSearchArguments<E>): Promise<this>;
     enrichmentContent<E extends Enrichment>(enrichment: E): EnrichmentSearchContent<E>;
 }

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

@@ -1,14 +1,14 @@
 import type { FlowrSearchElement, FlowrSearchElements } from '../flowr-search';
 import type { NormalizedAst, ParentInformation } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
-import type { MergeableRecord } from '../../util/objects';
+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';
 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 { Query, QueryResult } from '../../queries/query';
-import type { CfgSimplificationPassName } from '../../control-flow/cfg-simplification';
+import { type CfgSimplificationPassName } from '../../control-flow/cfg-simplification';
 import type { AsyncOrSync } from 'ts-essentials';
-import type { FlowrAnalysisProvider } from '../../project/flowr-analyzer';
+import type { ReadonlyFlowrAnalysisProvider } from '../../project/flowr-analyzer';
 import type { DataflowInformation } from '../../dataflow/info';
 export interface EnrichmentData<ElementContent extends MergeableRecord, ElementArguments = undefined, SearchContent extends MergeableRecord = never, SearchArguments = ElementArguments> {
     /**
@@ -19,7 +19,7 @@ export interface EnrichmentData<ElementContent extends MergeableRecord, ElementA
         normalize: NormalizedAst;
         cfg: ControlFlowInformation;
     }, args: ElementArguments | undefined, previousValue: ElementContent | undefined) => AsyncOrSync<ElementContent>;
-    readonly enrichSearch?: (search: FlowrSearchElements<ParentInformation>, data: FlowrAnalysisProvider, args: SearchArguments | undefined, previousValue: SearchContent | undefined) => AsyncOrSync<SearchContent>;
+    readonly enrichSearch?: (search: FlowrSearchElements<ParentInformation>, data: ReadonlyFlowrAnalysisProvider, args: SearchArguments | undefined, previousValue: SearchContent | undefined) => AsyncOrSync<SearchContent>;
     /**
      * The mapping function used by the {@link Mapper.Enrichment} mapper.
      */
@@ -120,7 +120,7 @@ export declare const Enrichments: {
             isRoot: boolean;
             isReachable: boolean | undefined;
         };
-        enrichSearch: (_search: FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, data: FlowrAnalysisProvider, args: CfgInformationArguments | undefined, prev: CfgInformationSearchContent | undefined) => Promise<CfgInformationSearchContent>;
+        enrichSearch: (_search: FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, data: ReadonlyFlowrAnalysisProvider, args: CfgInformationArguments | undefined, prev: CfgInformationSearchContent | undefined) => Promise<CfgInformationSearchContent>;
     };
     readonly "query-data": {
         enrichElement: (_e: FlowrSearchElement<ParentInformation>, _search: FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, _data: {
@@ -128,7 +128,7 @@ export declare const Enrichments: {
             normalize: NormalizedAst;
             cfg: ControlFlowInformation;
         }, args: QueryDataElementContent | undefined, prev: QueryDataElementContent | undefined) => QueryDataElementContent;
-        enrichSearch: (_search: FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, _data: FlowrAnalysisProvider, args: QueryDataSearchContent | undefined, prev: QueryDataSearchContent | undefined) => Required<QueryDataSearchContent>;
+        enrichSearch: (_search: FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>, _data: ReadonlyFlowrAnalysisProvider, args: QueryDataSearchContent | undefined, prev: QueryDataSearchContent | undefined) => Required<QueryDataSearchContent>;
     };
 };
 /**
@@ -138,6 +138,9 @@ export declare const Enrichments: {
  * @param enrichment - The enrichment content, if present, else `undefined`.
  */
 export declare function enrichmentContent<E extends Enrichment>(e: FlowrSearchElement<ParentInformation>, enrichment: E): EnrichmentElementContent<E>;
+/**
+ * Enriches the given search element with the given enrichment type, using the provided analysis data.
+ */
 export declare function enrichElement<Element extends FlowrSearchElement<ParentInformation>, E extends Enrichment>(e: Element, s: FlowrSearchElements<ParentInformation>, data: {
     dataflow: DataflowInformation;
     normalize: NormalizedAst;

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

@@ -137,6 +137,9 @@ exports.Enrichments = {
 function enrichmentContent(e, enrichment) {
     return e?.enrichments?.[enrichment];
 }
+/**
+ * Enriches the given search element with the given enrichment type, using the provided analysis data.
+ */
 async function enrichElement(e, s, data, enrichment, args) {
     const enrichmentData = exports.Enrichments[enrichment];
     const prev = e?.enrichments;

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

@@ -1,10 +1,11 @@
-import type { FlowrSearchElement, FlowrSearchGeneratorNodeBase, FlowrSearchGetFilter } from '../flowr-search';
-import { FlowrSearchElements } from '../flowr-search';
+import { type FlowrSearchElement, type FlowrSearchGeneratorNodeBase, type FlowrSearchGetFilter, FlowrSearchElements } from '../flowr-search';
 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';
-import type { FlowrAnalysisProvider } from '../../project/flowr-analyzer';
+import { type SlicingCriteria } from '../../slicing/criterion/parse';
+import { type Query } from '../../queries/query';
+import type { ReadonlyFlowrAnalysisProvider } from '../../project/flowr-analyzer';
+import type TreeSitter from 'web-tree-sitter';
+export declare const searchLogger: import("tslog").Logger<import("tslog").ILogObj>;
 /**
  * This is a union of all possible generator node types
  */
@@ -24,19 +25,27 @@ export declare const generators: {
     readonly criterion: typeof generateCriterion;
     readonly from: typeof generateFrom;
     readonly 'from-query': typeof generateFromQuery;
+    readonly syntax: typeof generateSyntax;
 };
-declare function generateAll(data: FlowrAnalysisProvider): Promise<FlowrSearchElements<ParentInformation>>;
-declare function generateGet(input: FlowrAnalysisProvider, { filter: { line, column, id, name, nameIsRegex } }: {
+declare function generateAll(data: ReadonlyFlowrAnalysisProvider): Promise<FlowrSearchElements<ParentInformation>>;
+declare function generateGet(input: ReadonlyFlowrAnalysisProvider, { filter: { line, column, id, name, nameIsRegex } }: {
     filter: FlowrSearchGetFilter;
 }): Promise<FlowrSearchElements<ParentInformation>>;
-declare function generateFrom(_input: FlowrAnalysisProvider, args: {
+declare function generateFrom(_input: ReadonlyFlowrAnalysisProvider, args: {
     from: FlowrSearchElement<ParentInformation> | FlowrSearchElement<ParentInformation>[];
 }): FlowrSearchElements<ParentInformation>;
-declare function generateFromQuery(input: FlowrAnalysisProvider, args: {
+declare function generateFromQuery(input: ReadonlyFlowrAnalysisProvider, args: {
     from: readonly Query[];
 }): Promise<FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>>;
-declare function generateCriterion(input: FlowrAnalysisProvider, args: {
+declare function generateSyntax(input: ReadonlyFlowrAnalysisProvider, args: {
+    source: TreeSitter.Query | string;
+    captures: readonly string[];
+}): Promise<FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>>;
+declare function generateCriterion(input: ReadonlyFlowrAnalysisProvider, args: {
     criterion: SlicingCriteria;
 }): Promise<FlowrSearchElements<ParentInformation>>;
+/**
+ * Gets the search generator function for the given name
+ */
 export declare function getGenerator<Name extends GeneratorNames>(name: Name): typeof generators[Name];
 export {};

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

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generators = void 0;
+exports.generators = exports.searchLogger = void 0;
 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");
 const search_enrichers_1 = require("./search-enrichers");
+const visitor_1 = require("../../r-bridge/lang-4.x/ast/model/processing/visitor");
+const log_1 = require("../../util/log");
+exports.searchLogger = log_1.log.getSubLogger({ name: 'search' });
 /**
  * All supported generators!
  */
@@ -15,7 +18,8 @@ exports.generators = {
     get: generateGet,
     criterion: generateCriterion,
     from: generateFrom,
-    'from-query': generateFromQuery
+    'from-query': generateFromQuery,
+    syntax: generateSyntax
 };
 async function generateAll(data) {
     return new flowr_search_1.FlowrSearchElements((await getAllNodes(data))
@@ -84,10 +88,53 @@ async function generateFromQuery(input, args) {
         return await (0, search_enrichers_1.enrichElement)(e, elements, { normalize, dataflow, cfg }, search_enrichers_1.Enrichment.QueryData, { query });
     })));
 }
+async function generateSyntax(input, args) {
+    // if the user didn't specify a specific capture, we want to capture the outermost item
+    if (!args.captures?.length) {
+        (0, assert_1.guard)(typeof args.source === 'string', `Cannot use default capture name for pre-compiled query ${JSON.stringify(args.source)}, specify captures explicitly`);
+        const defaultCaptureName = 'defaultCapture';
+        args.source += ` @${defaultCaptureName}`;
+        args.captures = [defaultCaptureName];
+    }
+    // allow specifying capture names with or without the @ in front :)
+    const captures = new Set(args.captures.map(c => c.startsWith('@') ? c.substring(1) : c));
+    const info = input.parserInformation();
+    (0, assert_1.guard)(info.name === 'tree-sitter', 'treeSitterQuery can only be used with TreeSitterExecutor parsers!');
+    const result = await info.treeSitterQuery(args.source);
+    const relevant = result.filter(c => captures.has(c.name));
+    if (!relevant.length) {
+        exports.searchLogger.debug(`empty tree-sitter query result for query ${JSON.stringify(args)}`);
+        return new flowr_search_1.FlowrSearchElements([]);
+    }
+    const nodesByTreeSitterId = new Map();
+    (0, visitor_1.visitAst)((await input.normalize()).ast, node => {
+        const treeSitterInfo = node.info;
+        if (treeSitterInfo.treeSitterId) {
+            nodesByTreeSitterId.set(treeSitterInfo.treeSitterId, node);
+        }
+        else {
+            exports.searchLogger.debug(`normalized ast node ${node.lexeme} with type ${node.type} does not have a tree-sitter id`);
+        }
+    });
+    const ret = [];
+    for (const capture of relevant) {
+        const node = nodesByTreeSitterId.get(capture.node.id);
+        if (node) {
+            ret.push({ node });
+        }
+        else {
+            exports.searchLogger.debug(`tree-sitter node ${capture.node.id} with type ${capture.node.type} does not have a corresponding normalized ast node`);
+        }
+    }
+    return new flowr_search_1.FlowrSearchElements(ret);
+}
 async function generateCriterion(input, args) {
     const idMap = (await input.normalize()).idMap;
     return new flowr_search_1.FlowrSearchElements(args.criterion.map(c => ({ node: idMap.get((0, parse_1.slicingCriterionToId)(c, idMap)) })));
 }
+/**
+ * Gets the search generator function for the given name
+ */
 function getGenerator(name) {
     if (!exports.generators[name]) {
         throw new Error(`Unknown generator: ${name}`);

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

@@ -1,19 +1,22 @@
 import type { FlowrSearchElement } from '../flowr-search';
 import type { ParentInformation } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
-import type { Enrichment } from './search-enrichers';
+import { type Enrichment } from './search-enrichers';
 import type { MergeableRecord } from '../../util/objects';
-import type { FlowrAnalysisProvider } from '../../project/flowr-analyzer';
+import type { ReadonlyFlowrAnalysisProvider } from '../../project/flowr-analyzer';
 export declare enum Mapper {
     Enrichment = "enrichment"
 }
 export interface MapperData<Arguments extends string | MergeableRecord> {
-    mapper: (e: FlowrSearchElement<ParentInformation>, data: FlowrAnalysisProvider, args: Arguments) => FlowrSearchElement<ParentInformation>[];
+    mapper: (e: FlowrSearchElement<ParentInformation>, data: ReadonlyFlowrAnalysisProvider, 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: FlowrAnalysisProvider, enrichment: Enrichment) => FlowrSearchElement<ParentInformation>[];
+        mapper: (e: FlowrSearchElement<ParentInformation>, _data: ReadonlyFlowrAnalysisProvider, enrichment: Enrichment) => FlowrSearchElement<ParentInformation>[];
     };
 };
-export declare function map<Element extends FlowrSearchElement<ParentInformation>, MapperType extends Mapper>(e: Element, data: FlowrAnalysisProvider, mapper: MapperType, args: MapperArguments<MapperType>): Element[];
+/**
+ * Maps the given search element using the specified mapper and arguments.
+ */
+export declare function map<Element extends FlowrSearchElement<ParentInformation>, MapperType extends Mapper>(e: Element, data: ReadonlyFlowrAnalysisProvider, mapper: MapperType, args: MapperArguments<MapperType>): Element[];
 export {};

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

@@ -16,6 +16,9 @@ const Mappers = {
         }
     }
 };
+/**
+ * Maps the given search element using the specified mapper and arguments.
+ */
 function map(e, data, mapper, args) {
     return Mappers[mapper].mapper(e, data, args);
 }

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

@@ -1,11 +1,11 @@
 import type { FlowrSearchElement, FlowrSearchElements, FlowrSearchTransformerNodeBase } from '../flowr-search';
 import type { LastOfArray, Tail2TypesOrUndefined, TailOfArray } from '../../util/collections/arrays';
-import type { FlowrFilterExpression } from '../flowr-search-filters';
+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 { Enrichment, EnrichmentElementArguments } from './search-enrichers';
-import type { Mapper, MapperArguments } from './search-mappers';
-import type { FlowrAnalysisProvider } from '../../project/flowr-analyzer';
+import { type Enrichment, type EnrichmentElementArguments } from './search-enrichers';
+import { type Mapper, type MapperArguments } from './search-mappers';
+import type { ReadonlyFlowrAnalysisProvider } from '../../project/flowr-analyzer';
 /**
  * This is a union of all possible transformer node types
  */
@@ -34,38 +34,41 @@ export declare const transformers: {
     readonly with: typeof getWith;
     readonly map: typeof getMap;
 };
+/**
+ * Gets a search-api transformer function for the given name.
+ */
 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 */
 type CascadeEmpty<Elements extends FlowrSearchElement<ParentInformation>[], NewElements extends FlowrSearchElement<ParentInformation>[]> = Elements extends [] ? FlowrSearchElements<ParentInformation, []> : FlowrSearchElements<ParentInformation, NewElements>;
-declare function getFirst<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrAnalysisProvider, elements: FSE): CascadeEmpty<Elements, [Elements[0]]>;
-declare function getLast<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrAnalysisProvider, elements: FSE): CascadeEmpty<Elements, [LastOfArray<Elements>]>;
-declare function getIndex<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrAnalysisProvider, elements: FSE, { index }: {
+declare function getFirst<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: ReadonlyFlowrAnalysisProvider, elements: FSE): CascadeEmpty<Elements, [Elements[0]]>;
+declare function getLast<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: ReadonlyFlowrAnalysisProvider, elements: FSE): CascadeEmpty<Elements, [LastOfArray<Elements>]>;
+declare function getIndex<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: ReadonlyFlowrAnalysisProvider, elements: FSE, { index }: {
     index: number;
 }): CascadeEmpty<Elements, [Elements[number]]>;
-declare function getSelect<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrAnalysisProvider, elements: FSE, { select }: {
+declare function getSelect<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: ReadonlyFlowrAnalysisProvider, elements: FSE, { select }: {
     select: number[];
 }): CascadeEmpty<Elements, Elements>;
-declare function getTail<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrAnalysisProvider, elements: FSE): CascadeEmpty<Elements, TailOfArray<Elements>>;
-declare function getTake<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrAnalysisProvider, elements: FSE, { count }: {
+declare function getTail<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: ReadonlyFlowrAnalysisProvider, elements: FSE): CascadeEmpty<Elements, TailOfArray<Elements>>;
+declare function getTake<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: ReadonlyFlowrAnalysisProvider, elements: FSE, { count }: {
     count: number;
 }): CascadeEmpty<Elements, TailOfArray<Elements>>;
-declare function getSkip<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrAnalysisProvider, elements: FSE, { count }: {
+declare function getSkip<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: ReadonlyFlowrAnalysisProvider, elements: FSE, { count }: {
     count: number;
 }): CascadeEmpty<Elements, TailOfArray<Elements>>;
-declare function getFilter<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrAnalysisProvider, elements: FSE, { filter }: {
+declare function getFilter<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: ReadonlyFlowrAnalysisProvider, elements: FSE, { filter }: {
     filter: FlowrFilterExpression;
 }): Promise<CascadeEmpty<Elements, Elements | []>>;
-declare function getWith<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(input: FlowrAnalysisProvider, elements: FSE, { info, args }: {
+declare function getWith<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(input: ReadonlyFlowrAnalysisProvider, elements: FSE, { info, args }: {
     info: Enrichment;
     args?: EnrichmentElementArguments<Enrichment>;
 }): Promise<FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>>;
-declare function getMap<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrAnalysisProvider, elements: FSE, { mapper, args }: {
+declare function getMap<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: ReadonlyFlowrAnalysisProvider, 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: FlowrAnalysisProvider, elements: FSE, other: {
+declare function getMerge<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: ReadonlyFlowrAnalysisProvider, elements: FSE, other: {
     search: unknown[];
     generator: FlowrSearchGeneratorNode;
 }): Promise<FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>>;
-declare function getUnique<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: FlowrAnalysisProvider, elements: FSE): CascadeEmpty<Elements, Elements>;
+declare function getUnique<Elements extends FlowrSearchElement<ParentInformation>[], FSE extends FlowrSearchElements<ParentInformation, Elements>>(data: ReadonlyFlowrAnalysisProvider, elements: FSE): CascadeEmpty<Elements, Elements>;
 export {};

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

@@ -24,6 +24,9 @@ exports.transformers = {
     with: getWith,
     map: getMap
 };
+/**
+ * Gets a search-api transformer function for the given name.
+ */
 function getTransformer(name) {
     if (!exports.transformers[name]) {
         throw new Error(`Unknown transformer: ${name}`);

package/slicing/criterion/collect-all.d.ts

@@ -13,20 +13,20 @@ import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-i
  */
 export interface SlicingCriteriaFilter extends MergeableRecord {
     /**
-   * Inclusive minimum size of the slicing criteria (number of included slice points).
-   * Should be at least `1` to make sense (and of course at most {@link SlicingCriteriaFilter#maximumSize|maximum size}).
-   */
+     * Inclusive minimum size of the slicing criteria (number of included slice points).
+     * Should be at least `1` to make sense (and of course at most {@link SlicingCriteriaFilter#maximumSize|maximum size}).
+     */
     minimumSize: number;
     /**
-   * Inclusive maximum size of the slicing criteria (number of included slice points).
-   * Should be at least `1` to make sense (and of course at least {@link SlicingCriteriaFilter#minimumSize|minimum size}).
-   * <p>
-   * Be really careful with this one, as the number of possible slicing criteria can grow exponentially with the maximum size.
-   */
+     * Inclusive maximum size of the slicing criteria (number of included slice points).
+     * Should be at least `1` to make sense (and of course at least {@link SlicingCriteriaFilter#minimumSize|minimum size}).
+     * <p>
+     * Be really careful with this one, as the number of possible slicing criteria can grow exponentially with the maximum size.
+     */
     maximumSize: number;
     /**
-   * Function that determines the ids of all nodes that can be used as slicing criteria.
-   */
+     * Function that determines the ids of all nodes that can be used as slicing criteria.
+     */
     collectAll: (root: RNodeWithParent) => NodeId[];
 }
 /**

package/slicing/criterion/parse.d.ts

@@ -11,13 +11,11 @@ export declare class CriteriaParseError extends Error {
 }
 /**
  * Takes a criterion in the form of `line:column` or `line@variable-name` and returns the corresponding node id
- *
  * @see {@link tryResolveSliceCriterionToId} for a version that does not throw an error
  */
 export declare function slicingCriterionToId(criterion: SingleSlicingCriterion, idMap: AstIdMap): NodeId;
 /**
  * Tries to resolve a slicing criterion to an id, but does not throw an error if it fails.
- *
  * @see {@link slicingCriterionToId} for the version that throws an error
  */
 export declare function tryResolveSliceCriterionToId(criterion: string | NodeId, idMap: AstIdMap): NodeId | undefined;
@@ -26,4 +24,8 @@ export interface DecodedCriterion {
     id: NodeId;
 }
 export type DecodedCriteria = ReadonlyArray<DecodedCriterion>;
+/**
+ * Converts all slicing criteria to their corresponding node ids
+ * @throws CriteriaParseError if any of the criteria can not be resolved
+ */
 export declare function convertAllSlicingCriteriaToIds(criteria: SlicingCriteria, decorated: AstIdMap): DecodedCriteria;

package/slicing/criterion/parse.js

@@ -20,7 +20,6 @@ class CriteriaParseError extends Error {
 exports.CriteriaParseError = CriteriaParseError;
 /**
  * Takes a criterion in the form of `line:column` or `line@variable-name` and returns the corresponding node id
- *
  * @see {@link tryResolveSliceCriterionToId} for a version that does not throw an error
  */
 function slicingCriterionToId(criterion, idMap) {
@@ -43,7 +42,6 @@ function slicingCriterionToId(criterion, idMap) {
 }
 /**
  * Tries to resolve a slicing criterion to an id, but does not throw an error if it fails.
- *
  * @see {@link slicingCriterionToId} for the version that throws an error
  */
 function tryResolveSliceCriterionToId(criterion, idMap) {
@@ -96,6 +94,10 @@ function conventionalCriteriaToId(line, name, dataflowIdMap) {
     }
     return id;
 }
+/**
+ * Converts all slicing criteria to their corresponding node ids
+ * @throws CriteriaParseError if any of the criteria can not be resolved
+ */
 function convertAllSlicingCriteriaToIds(criteria, decorated) {
     return criteria.map(l => ({ criterion: l, id: slicingCriterionToId(l, decorated) }));
 }

package/slicing/static/fingerprint.d.ts

@@ -1,5 +1,13 @@
-import type { REnvironmentInformation } from '../../dataflow/environments/environment';
+import { type REnvironmentInformation } from '../../dataflow/environments/environment';
 import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
 export type Fingerprint = string;
+/**
+ * Calculate a fingerprint for the given R environment information
+ * @see {@link fingerprint}
+ */
 export declare function envFingerprint(env: REnvironmentInformation): Fingerprint;
+/**
+ * Calculate a fingerprint for the given node id and environment fingerprint
+ * @see {@link envFingerprint}
+ */
 export declare function fingerprint(id: NodeId, envFingerprint: Fingerprint, onlyForSideEffects: boolean): Fingerprint;

package/slicing/static/fingerprint.js

@@ -7,6 +7,10 @@ exports.envFingerprint = envFingerprint;
 exports.fingerprint = fingerprint;
 const object_hash_1 = __importDefault(require("object-hash"));
 const environment_1 = require("../../dataflow/environments/environment");
+/**
+ * Calculate a fingerprint for the given R environment information
+ * @see {@link fingerprint}
+ */
 function envFingerprint(env) {
     return (0, object_hash_1.default)(env, {
         algorithm: 'md5',
@@ -17,6 +21,10 @@ function envFingerprint(env) {
         replacer: (v) => (0, environment_1.isDefaultBuiltInEnvironment)(v) ? undefined : v
     });
 }
+/**
+ * Calculate a fingerprint for the given node id and environment fingerprint
+ * @see {@link envFingerprint}
+ */
 function fingerprint(id, envFingerprint, onlyForSideEffects) {
     return `${id}-${envFingerprint}-${onlyForSideEffects ? '0' : '1'}`;
 }

package/slicing/static/slice-call.d.ts

@@ -1,9 +1,9 @@
 import type { NodeToSlice } from './slicer-types';
 import type { VisitingQueue } from './visiting-queue';
-import type { Fingerprint } from './fingerprint';
+import { type Fingerprint } from './fingerprint';
 import type { DataflowGraphVertexFunctionCall, DataflowGraphVertexInfo } from '../../dataflow/graph/vertex';
 import type { REnvironmentInformation } from '../../dataflow/environments/environment';
-import type { DataflowGraph, OutgoingEdges } from '../../dataflow/graph/graph';
+import { type DataflowGraph, type OutgoingEdges } from '../../dataflow/graph/graph';
 import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import type { DataflowInformation } from '../../dataflow/info';
 /**

package/slicing/static/static-slicer.d.ts

@@ -1,9 +1,9 @@
 import type { SliceResult } from './slicer-types';
-import type { Fingerprint } from './fingerprint';
+import { type Fingerprint } from './fingerprint';
 import { VisitingQueue } from './visiting-queue';
 import type { NormalizedAst } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
-import type { SlicingCriteria } from '../criterion/parse';
-import type { REnvironmentInformation } from '../../dataflow/environments/environment';
+import { type SlicingCriteria } from '../criterion/parse';
+import { type REnvironmentInformation } from '../../dataflow/environments/environment';
 import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
 import { SliceDirection } from '../../core/steps/all/static-slicing/00-slice';
 import type { DataflowInformation } from '../../dataflow/info';
@@ -12,12 +12,16 @@ export declare const slicerLogger: import("tslog").Logger<import("tslog").ILogOb
  * This returns the ids to include in the static slice of the given type, when slicing with the given seed id's (must be at least one).
  * <p>
  * The returned ids can be used to {@link reconstructToCode|reconstruct the slice to R code}.
- *
  * @param info      - The dataflow information used for slicing.
+ * @param idMap     - The mapping from node ids to their information in the AST.
  * @param criteria  - The criteria to slice on.
  * @param direction - The direction to slice in.
  * @param threshold - The maximum number of nodes to visit in the graph. If the threshold is reached, the slice will side with inclusion and drop its minimal guarantee. The limit ensures that the algorithm halts.
  * @param cache     - A cache to store the results of the slice. If provided, the slice may use this cache to speed up the slicing process.
  */
 export declare function staticSlice(info: DataflowInformation, { idMap }: NormalizedAst, criteria: SlicingCriteria, direction: SliceDirection, threshold?: number, cache?: Map<Fingerprint, Set<NodeId>>): Readonly<SliceResult>;
+/**
+ * Updates the potential addition for the given target node in the visiting queue.
+ * This describes vertices that might be added *if* another path reaches them.
+ */
 export declare function updatePotentialAddition(queue: VisitingQueue, id: NodeId, target: NodeId, baseEnvironment: REnvironmentInformation, envFingerprint: string): void;

package/slicing/static/static-slicer.js

@@ -19,8 +19,8 @@ exports.slicerLogger = log_1.log.getSubLogger({ name: 'slicer' });
  * This returns the ids to include in the static slice of the given type, when slicing with the given seed id's (must be at least one).
  * <p>
  * The returned ids can be used to {@link reconstructToCode|reconstruct the slice to R code}.
- *
  * @param info      - The dataflow information used for slicing.
+ * @param idMap     - The mapping from node ids to their information in the AST.
  * @param criteria  - The criteria to slice on.
  * @param direction - The direction to slice in.
  * @param threshold - The maximum number of nodes to visit in the graph. If the threshold is reached, the slice will side with inclusion and drop its minimal guarantee. The limit ensures that the algorithm halts.
@@ -105,6 +105,10 @@ function staticSlice(info, { idMap }, criteria, direction, threshold = 75, cache
     }
     return { ...queue.status(), decodedCriteria };
 }
+/**
+ * Updates the potential addition for the given target node in the visiting queue.
+ * This describes vertices that might be added *if* another path reaches them.
+ */
 function updatePotentialAddition(queue, id, target, baseEnvironment, envFingerprint) {
     const n = queue.potentialAdditions.get(target);
     if (n) {

package/slicing/static/visiting-queue.d.ts

@@ -1,4 +1,4 @@
-import type { Fingerprint } from './fingerprint';
+import { type Fingerprint } from './fingerprint';
 import type { NodeToSlice, SliceResult } from './slicer-types';
 import type { REnvironmentInformation } from '../../dataflow/environments/environment';
 import type { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';