@eagleoutice/flowr 2.6.1 → 2.6.2

package/r-bridge/parser.d.ts

@@ -1,19 +1,39 @@
 import type { RParseRequest, RParseRequests } from './retriever';
-import type { RShell } from './shell';
+import type { OutputCollectorConfiguration, RShell } from './shell';
 import type { RShellExecutor } from './shell-executor';
 import type { TreeSitterExecutor } from './lang-4.x/tree-sitter/tree-sitter-executor';
+import type { Query, QueryCapture } from 'web-tree-sitter';
+import type { FlowrAnalysisProvider } from '../project/flowr-analyzer';
 interface ParserContent<T> {
     readonly name: string;
-    rVersion(): Promise<string | 'unknown' | 'none'>;
+    information(analyzer: FlowrAnalysisProvider): BaseParserInformation;
     parse(request: RParseRequest): T;
     close(): void;
 }
-export interface TreeSitterInformation {
-    name: TreeSitterExecutor['name'];
+export interface BaseParserInformation {
+    readonly name: KnownParserName;
 }
-export interface RShellInformation {
-    name: RShell['name'];
-    rVersion: string;
+export interface BaseRShellInformation extends BaseParserInformation {
+    readonly name: 'r-shell';
+    rVersion(): Promise<string>;
+}
+export interface RShellInformation extends BaseRShellInformation {
+    /**
+     * Sends a command to the underlying R engine and collects the output.
+     * @param command     - The command to send to the R engine.
+     * @param addonConfig - Additional configuration for the output collector.
+     */
+    sendCommandWithOutput(command: string, addonConfig?: Partial<OutputCollectorConfiguration>): Promise<string[]>;
+}
+export interface TreeSitterInformation extends BaseParserInformation {
+    readonly name: 'tree-sitter';
+    readonly grammarVersion: number;
+    /**
+     * Runs the given tree-sitter query using the underlying tree-sitter parser and returns the resulting capture.
+     * @param source - The tree-sitter query to run.
+     * @param force  - Do not use the cache, instead force a new parse.
+     */
+    treeSitterQuery(source: Query | string, force?: boolean): Promise<QueryCapture[]>;
 }
 export type SyncParser<T> = ParserContent<Awaited<T>> & {
     readonly async?: false;
@@ -24,6 +44,7 @@ export type AsyncParser<T> = ParserContent<Promise<T>> & {
 export type Parser<T> = SyncParser<T> | AsyncParser<T>;
 export type KnownParser = RShell | RShellExecutor | TreeSitterExecutor;
 export type KnownParserType = Awaited<ReturnType<KnownParser['parse']>>;
+export type KnownParserInformation = ReturnType<KnownParser['information']>;
 export type KnownParserName = KnownParser['name'];
 export interface ParseRequiredInput<T> {
     /** This is the {@link RShell}, {@link RShellExecutor} or {@link TreeSitterExecutor} connection to be used to obtain the original parses AST of the R code */

package/r-bridge/retriever.d.ts

@@ -1,7 +1,7 @@
 import { type RShell } from './shell';
 import type { AsyncOrSync } from 'ts-essentials';
 import { RShellExecutor } from './shell-executor';
-import type { NormalizedAst } from './lang-4.x/ast/model/processing/decorate';
+import { type NormalizedAst } from './lang-4.x/ast/model/processing/decorate';
 import type { SupportedFormats } from '../util/formats/adapter-format';
 export declare const fileProtocol = "file://";
 export interface ParseRequestAdditionalInfoBase {
@@ -46,15 +46,30 @@ export type RParseRequest = RParseRequestFromFile | RParseRequestFromText;
  * Several requests that can be passed along to {@link retrieveParseDataFromRCode}.
  */
 export type RParseRequests = RParseRequest | ReadonlyArray<RParseRequest>;
+/**
+ * Type guard for {@link RParseRequest}
+ */
 export declare function isParseRequest(request: unknown): request is RParseRequest;
 export declare function requestFromInput(input: `${typeof fileProtocol}${string}`): RParseRequestFromFile;
 export declare function requestFromInput(input: `${typeof fileProtocol}${string}`[]): RParseRequestFromFile[];
 export declare function requestFromInput(input: string): RParseRequestFromText;
 export declare function requestFromInput(input: readonly string[] | string): RParseRequests;
+/**
+ * Creates a {@link RParseRequestProvider} that reads from the file system.
+ * Uses `fs.existsSync` to check for file existence.
+ * @see {@link requestProviderFromText} for a provider that reads from a text map.
+ */
 export declare function requestProviderFromFile(): RParseRequestProvider;
+/**
+ * Creates a {@link RParseRequestProvider} that reads from the given text map.
+ * @see {@link requestProviderFromFile} for a provider that reads from the file system.
+ */
 export declare function requestProviderFromText(text: Readonly<{
     [path: string]: string;
 }>): RParseRequestProvider;
+/**
+ * Checks whether the given {@link RParseRequest} is empty (has no content).
+ */
 export declare function isEmptyRequest(request: RParseRequest): boolean;
 export declare function retrieveParseDataFromRCode(request: RParseRequest, shell: RShell): Promise<string>;
 export declare function retrieveParseDataFromRCode(request: RParseRequest, shell: RShellExecutor): string;

package/r-bridge/retriever.js

@@ -25,6 +25,9 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const adapter_1 = require("../util/formats/adapter");
 exports.fileProtocol = 'file://';
+/**
+ * Type guard for {@link RParseRequest}
+ */
 function isParseRequest(request) {
     if (typeof request !== 'object' || request === null) {
         return false;
@@ -50,6 +53,11 @@ function requestFromInput(input, fileTypeHint) {
         return (0, adapter_1.requestFromText)(content, fileTypeHint);
     }
 }
+/**
+ * Creates a {@link RParseRequestProvider} that reads from the file system.
+ * Uses `fs.existsSync` to check for file existence.
+ * @see {@link requestProviderFromText} for a provider that reads from a text map.
+ */
 function requestProviderFromFile() {
     return {
         exists(p, ignoreCase) {
@@ -76,6 +84,10 @@ function requestProviderFromFile() {
         }
     };
 }
+/**
+ * Creates a {@link RParseRequestProvider} that reads from the given text map.
+ * @see {@link requestProviderFromFile} for a provider that reads from the file system.
+ */
 function requestProviderFromText(text) {
     return {
         exists(path, ignoreCase) {
@@ -92,6 +104,9 @@ function requestProviderFromText(text) {
         }
     };
 }
+/**
+ * Checks whether the given {@link RParseRequest} is empty (has no content).
+ */
 function isEmptyRequest(request) {
     return request.content.trim().length === 0;
 }

package/r-bridge/shell-executor.d.ts

@@ -1,6 +1,6 @@
-import type { RShellExecutionOptions } from './shell';
+import { type RShellExecutionOptions } from './shell';
 import type { SemVer } from 'semver';
-import type { SyncParser } from './parser';
+import type { BaseRShellInformation, SyncParser } from './parser';
 import { type RParseRequest } from './retriever';
 /**
  * This is a synchronous alternative to the {@link RShell}.
@@ -23,12 +23,12 @@ export declare class RShellExecutor implements SyncParser<string> {
     addPrerequisites(commands: string | string[]): this;
     /**
      * @returns the version of the R interpreter available to this executor.
-     *
      * @see {@link RShellExecutor#usedRVersion}
      * @see {@link RShell#rVersion}
      * @see {@link RShell#usedRVersion}
      */
     rVersion(): Promise<string | 'unknown' | 'none'>;
+    information(): BaseRShellInformation;
     /**
      * Instead of returning a promise, this method returns the version of the R interpreter available to this executor,
      * in the SemVer format.

package/r-bridge/shell-executor.js

@@ -40,7 +40,6 @@ class RShellExecutor {
     }
     /**
      * @returns the version of the R interpreter available to this executor.
-     *
      * @see {@link RShellExecutor#usedRVersion}
      * @see {@link RShell#rVersion}
      * @see {@link RShell#usedRVersion}
@@ -48,6 +47,12 @@ class RShellExecutor {
     rVersion() {
         return Promise.resolve(this.usedRVersion()?.format() ?? 'unknown');
     }
+    information() {
+        return {
+            name: 'r-shell',
+            rVersion: () => Promise.resolve(this.rVersion())
+        };
+    }
     /**
      * Instead of returning a promise, this method returns the version of the R interpreter available to this executor,
      * in the SemVer format.

package/r-bridge/shell.d.ts

@@ -2,13 +2,13 @@ import { type MergeableRecord } from '../util/objects';
 import type { SemVer } from 'semver';
 import type { AsyncOrSync } from 'ts-essentials';
 import type { RShellEngineConfig } from '../config';
-import type { AsyncParser } from './parser';
-import type { RParseRequest } from './retriever';
+import type { AsyncParser, RShellInformation } from './parser';
+import { type RParseRequest } from './retriever';
 export type OutputStreamSelector = 'stdout' | 'stderr' | 'both';
 export interface CollectorTimeout extends MergeableRecord {
     /**
-   * number of milliseconds to wait for the collection to finish
-   */
+     * number of milliseconds to wait for the collection to finish
+     */
     ms: number;
     resetOnNewData: boolean;
     /**
@@ -24,9 +24,9 @@ export interface OutputCollectorConfiguration extends MergeableRecord {
     /** the streams to use to collect the output from */
     from: OutputStreamSelector;
     /**
-   * a string marker to signal that the command was executed successfully.
-   * must not appear as a standalone line in the output. this is our hacky way of ensuring that we are done.
-   */
+     * a string marker to signal that the command was executed successfully.
+     * must not appear as a standalone line in the output. this is our hacky way of ensuring that we are done.
+     */
     postamble: string;
     /** internal timeout configuration to use (see {@link CollectorTimeout}) */
     timeout: CollectorTimeout;
@@ -69,6 +69,9 @@ export interface RShellOptions extends RShellSessionOptions {
     readonly sessionName: string;
 }
 export declare const DEFAULT_R_PATH: string;
+/**
+ *
+ */
 export declare function getDefaultRShellOptions(config?: RShellEngineConfig): RShellOptions;
 /**
  * The `RShell` represents an interactive session with the R interpreter.
@@ -88,6 +91,7 @@ export declare class RShell implements AsyncParser<string> {
     private tempDirs;
     constructor(config?: RShellEngineConfig, options?: Partial<RShellOptions>);
     parse(request: RParseRequest): Promise<string>;
+    information(): RShellInformation;
     private revive;
     /**
      * sends the given command directly to the current R session
@@ -103,22 +107,20 @@ export declare class RShell implements AsyncParser<string> {
      */
     isPackageInstalled(packageName: string): Promise<boolean>;
     /**
-   * Send a command and collect the output
-   *
-   * @param command     - The R command to execute (similar to {@link sendCommand})
-   * @param addonConfig - Further configuration on how and what to collect: see {@link OutputCollectorConfiguration},
-   *                      defaults are set in {@link DEFAULT_OUTPUT_COLLECTOR_CONFIGURATION}
-   */
+     * Send a command and collect the output
+     * @param command     - The R command to execute (similar to {@link sendCommand})
+     * @param addonConfig - Further configuration on how and what to collect: see {@link OutputCollectorConfiguration},
+     *                      defaults are set in {@link DEFAULT_OUTPUT_COLLECTOR_CONFIGURATION}
+     */
     sendCommandWithOutput(command: string, addonConfig?: Partial<OutputCollectorConfiguration>): Promise<string[]>;
     /**
-   * execute multiple commands in order
-   *
-   * @see sendCommand
-   */
+     * execute multiple commands in order
+     * @see sendCommand
+     */
     sendCommands(...commands: readonly string[]): void;
     /**
-   * clears the R environment using the `rm` command.
-   */
+     * clears the R environment using the `rm` command.
+     */
     clearEnvironment(): void;
     /**
      * Obtain the temporary directory used by R.
@@ -126,10 +128,9 @@ export declare class RShell implements AsyncParser<string> {
      */
     obtainTmpDir(): Promise<string>;
     /**
-   * Close the current R session, makes the object effectively invalid (can no longer be reopened etc.)
-   *
-   * @returns true if the operation succeeds, false otherwise
-   */
+     * Close the current R session, makes the object effectively invalid (can no longer be reopened etc.)
+     * @returns true if the operation succeeds, false otherwise
+     */
     close(): boolean;
     private _sendCommand;
 }

package/r-bridge/shell.js

@@ -61,6 +61,9 @@ exports.DEFAULT_OUTPUT_COLLECTOR_CONFIGURATION = {
 };
 exports.DEFAULT_R_PATH = (0, os_1.getPlatform)() === 'windows' ? 'R.exe' : 'R';
 let DEFAULT_R_SHELL_OPTIONS = undefined;
+/**
+ *
+ */
 function getDefaultRShellOptions(config) {
     if (!DEFAULT_R_SHELL_OPTIONS) {
         DEFAULT_R_SHELL_OPTIONS = {
@@ -105,6 +108,15 @@ class RShell {
     parse(request) {
         return (0, retriever_1.retrieveParseDataFromRCode)(request, this);
     }
+    information() {
+        return {
+            name: 'r-shell',
+            rVersion: async () => await this.rVersion(),
+            sendCommandWithOutput: (command, addonConfig) => {
+                return this.sendCommandWithOutput(command, addonConfig);
+            }
+        };
+    }
     revive() {
         if (this.options.revive === 0 /* RShellReviveOptions.Never */) {
             return;
@@ -177,12 +189,11 @@ class RShell {
         return result.length === 1 && result[0] === 'TRUE';
     }
     /**
-   * Send a command and collect the output
-   *
-   * @param command     - The R command to execute (similar to {@link sendCommand})
-   * @param addonConfig - Further configuration on how and what to collect: see {@link OutputCollectorConfiguration},
-   *                      defaults are set in {@link DEFAULT_OUTPUT_COLLECTOR_CONFIGURATION}
-   */
+     * Send a command and collect the output
+     * @param command     - The R command to execute (similar to {@link sendCommand})
+     * @param addonConfig - Further configuration on how and what to collect: see {@link OutputCollectorConfiguration},
+     *                      defaults are set in {@link DEFAULT_OUTPUT_COLLECTOR_CONFIGURATION}
+     */
     async sendCommandWithOutput(command, addonConfig) {
         const config = (0, objects_1.deepMergeObject)(exports.DEFAULT_OUTPUT_COLLECTOR_CONFIGURATION, addonConfig);
         (0, log_1.expensiveTrace)(this.log, () => `> ${JSON.stringify(command)}`);
@@ -206,18 +217,17 @@ class RShell {
         }
     }
     /**
-   * execute multiple commands in order
-   *
-   * @see sendCommand
-   */
+     * execute multiple commands in order
+     * @see sendCommand
+     */
     sendCommands(...commands) {
         for (const element of commands) {
             this.sendCommand(element);
         }
     }
     /**
-   * clears the R environment using the `rm` command.
-   */
+     * clears the R environment using the `rm` command.
+     */
     clearEnvironment() {
         this.log.debug('clearing environment');
         // run rm(list=ls()) but ignore 'flowr_get_ast', which is the compile command installed
@@ -234,10 +244,9 @@ class RShell {
         return tempdir;
     }
     /**
-   * Close the current R session, makes the object effectively invalid (can no longer be reopened etc.)
-   *
-   * @returns true if the operation succeeds, false otherwise
-   */
+     * Close the current R session, makes the object effectively invalid (can no longer be reopened etc.)
+     * @returns true if the operation succeeds, false otherwise
+     */
     close() {
         return this.session.end([...this.tempDirs]);
     }
@@ -294,15 +303,14 @@ class RShellSession {
         this.write(`${data}${this.options.eol}`);
     }
     /**
-   * Collect lines from the selected streams until the given condition is met or the timeout is reached
-   *
-   * This method does allow other listeners to consume the same input
-   *
-   * @param from        - The stream(s) to collect the information from
-   * @param until       - If the predicate returns true, this will stop the collection and resolve the promise
-   * @param timeout     - Configuration for how and when to timeout
-   * @param action      - Event to be performed after all listeners are installed, this might be the action that triggers the output you want to collect
-   */
+     * Collect lines from the selected streams until the given condition is met or the timeout is reached
+     *
+     * This method does allow other listeners to consume the same input
+     * @param from        - The stream(s) to collect the information from
+     * @param until       - If the predicate returns true, this will stop the collection and resolve the promise
+     * @param timeout     - Configuration for how and when to timeout
+     * @param action      - Event to be performed after all listeners are installed, this might be the action that triggers the output you want to collect
+     */
     async collectLinesUntil(from, until, timeout, action) {
         const result = [];
         let handler;
@@ -344,13 +352,11 @@ class RShellSession {
         });
     }
     /**
-   * close the current R session, makes the object effectively invalid (can no longer be reopened etc.)
-   *
+     * close the current R session, makes the object effectively invalid (can no longer be reopened etc.)
      * @param filesToUnlink - If set, these files will be unlinked before closing the session (e.g., to clean up tempfiles)
-     *
-   * @returns true if the kill succeeds, false otherwise
-   * @see RShell#close
-   */
+     * @returns true if the kill succeeds, false otherwise
+     * @see RShell#close
+     */
     end(filesToUnlink) {
         if (filesToUnlink !== undefined) {
             log_1.log.info(`unlinking ${filesToUnlink.length} files (${JSON.stringify(filesToUnlink)})`);

package/reconstruct/auto-select/auto-select-defaults.d.ts

@@ -4,7 +4,6 @@ import type { ParentInformation, NormalizedAst } from '../../r-bridge/lang-4.x/a
  * The structure of the predicate that should be used to determine
  * if a given normalized node should be included in the reconstructed code,
  * independent of if it is selected by the slice or not.
- *
  * @see reconstructToCode
  * @see doNotAutoSelect
  * @see autoSelectLibrary

package/reconstruct/auto-select/magic-comments.d.ts

@@ -7,10 +7,9 @@ import type { AutoSelectPredicate } from './auto-select-defaults';
  * We support two formats:
  * - Line comments in the form of `# flowr@include_next_line` or `# flowr@include_this_line`.
  * - Block comments which start with `# flowr@include_start` and end with `# flowr@include_end`.
- *   This supports nesting, but they have to appear on a single line.
+ * This supports nesting, but they have to appear on a single line.
  *
  * Please note that these comments have to start exactly with this content to work.
- *
  * @param and - Predicate to composite this one with, If you do not pass a predicate, you may assume composition with
  *              {@link doNotAutoSelect}.
  */

package/reconstruct/auto-select/magic-comments.js

@@ -40,10 +40,9 @@ const commentTriggerRegex = / flowr@(\w+)/;
  * We support two formats:
  * - Line comments in the form of `# flowr@include_next_line` or `# flowr@include_this_line`.
  * - Block comments which start with `# flowr@include_start` and end with `# flowr@include_end`.
- *   This supports nesting, but they have to appear on a single line.
+ * This supports nesting, but they have to appear on a single line.
  *
  * Please note that these comments have to start exactly with this content to work.
- *
  * @param and - Predicate to composite this one with, If you do not pass a predicate, you may assume composition with
  *              {@link doNotAutoSelect}.
  */

package/reconstruct/reconstruct.d.ts

@@ -5,7 +5,7 @@
  */
 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 { AutoSelectPredicate } from './auto-select/auto-select-defaults';
+import { type AutoSelectPredicate } from './auto-select/auto-select-defaults';
 type Selection = ReadonlySet<NodeId>;
 export declare const reconstructLogger: import("tslog").Logger<import("tslog").ILogObj>;
 export interface ReconstructionResult {
@@ -15,11 +15,9 @@ export interface ReconstructionResult {
 }
 /**
  * Reconstructs parts of a normalized R ast into R code on an expression basis.
- *
  * @param ast          - The {@link NormalizedAst|normalized ast} to be used as a basis for reconstruction
  * @param selection    - The selection of nodes to be reconstructed (probably the {@link NodeId|NodeIds} identified by the slicer)
  * @param autoSelectIf - A predicate that can be used to force the reconstruction of a node (for example to reconstruct library call statements, see {@link autoSelectLibrary}, {@link doNotAutoSelect})
- *
  * @returns The number of lines for which `autoSelectIf` triggered, as well as the reconstructed code itself.
  */
 export declare function reconstructToCode(ast: NormalizedAst, selection: Selection, autoSelectIf?: AutoSelectPredicate): ReconstructionResult;

package/reconstruct/reconstruct.js

@@ -419,11 +419,9 @@ function removeOuterExpressionListIfApplicable(result, linesWithAutoSelected) {
 }
 /**
  * Reconstructs parts of a normalized R ast into R code on an expression basis.
- *
  * @param ast          - The {@link NormalizedAst|normalized ast} to be used as a basis for reconstruction
  * @param selection    - The selection of nodes to be reconstructed (probably the {@link NodeId|NodeIds} identified by the slicer)
  * @param autoSelectIf - A predicate that can be used to force the reconstruction of a node (for example to reconstruct library call statements, see {@link autoSelectLibrary}, {@link doNotAutoSelect})
- *
  * @returns The number of lines for which `autoSelectIf` triggered, as well as the reconstructed code itself.
  */
 function reconstructToCode(ast, selection, autoSelectIf = auto_select_defaults_1.doNotAutoSelect) {

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

@@ -6,9 +6,9 @@ import type { FlowrSearchTransformerNode, GetOutputOfTransformer, TransformerNam
 import type { SlicingCriteria } from '../slicing/criterion/parse';
 import type { ParentInformation } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
 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 MapperArguments, Mapper } from './search-executor/search-mappers';
 import type { Query } from '../queries/query';
+import type TreeSitter from 'web-tree-sitter';
 type FlowrCriteriaReturn<C extends SlicingCriteria> = FlowrSearchElements<ParentInformation, C extends [] ? never : C extends [infer _] ? [
     FlowrSearchElement<ParentInformation>
 ] : FlowrSearchElement<ParentInformation>[]>;
@@ -29,6 +29,11 @@ export declare const FlowrSearchGenerator: {
      * 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, FlowrSearchElement<ParentInformation>[]>>;
+    /**
+     * Initializes a new search query based on the results of the given tree-sitter syntax query.
+     * Please note that this search generator is incompatible with the {@link RShell} parser and only works when using flowR with the {@link TreeSitterExecutor}.
+     */
+    readonly syntax: (source: TreeSitter.Query | string, ...captures: readonly string[]) => FlowrSearchBuilder<"from-query", [], ParentInformation, FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>>;
     /**
      * Returns all elements (nodes/dataflow vertices) from the given data.
      */
@@ -87,6 +92,11 @@ export declare const Q: {
      * 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, FlowrSearchElement<ParentInformation>[]>>;
+    /**
+     * Initializes a new search query based on the results of the given tree-sitter syntax query.
+     * Please note that this search generator is incompatible with the {@link RShell} parser and only works when using flowR with the {@link TreeSitterExecutor}.
+     */
+    readonly syntax: (source: TreeSitter.Query | string, ...captures: readonly string[]) => FlowrSearchBuilder<"from-query", [], ParentInformation, FlowrSearchElements<ParentInformation, FlowrSearchElement<ParentInformation>[]>>;
     /**
      * Returns all elements (nodes/dataflow vertices) from the given data.
      */
@@ -130,7 +140,6 @@ export type FlowrSearchBuilderType<Generator extends GeneratorNames = GeneratorN
 /**
  * The search query is a combination of a generator and a list of transformers
  * and allows this view to pass such queries in a serialized form.
- *
  * @typeParam Transformers - The list of transformers that are applied to the generator's output.
  */
 export interface FlowrSearch<Info = ParentInformation, _Generator extends GeneratorNames = GeneratorNames, _Transformers extends readonly TransformerNames[] = readonly TransformerNames[], _ElementType = FlowrSearchElements<Info, FlowrSearchElement<Info>[]>> {
@@ -143,7 +152,6 @@ type FlowrSearchBuilderOut<Generator extends GeneratorNames, Transformers extend
  * 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}
@@ -207,7 +215,6 @@ export declare class FlowrSearchBuilder<Generator extends GeneratorNames, Transf
     unique(): FlowrSearchBuilderOut<Generator, Transformers, Info, 'unique'>;
     /**
      * Construct the final search (this may happen automatically with most search handlers).
-     *
      * @param shouldOptimize - This may optimize the search.
      */
     build(shouldOptimize?: boolean): FlowrSearch<Info, Generator, Transformers, ElementType>;

package/search/flowr-search-builder.js

@@ -26,6 +26,13 @@ exports.FlowrSearchGenerator = {
     fromQuery(...from) {
         return new FlowrSearchBuilder({ type: 'generator', name: 'from-query', args: { from } });
     },
+    /**
+     * Initializes a new search query based on the results of the given tree-sitter syntax query.
+     * Please note that this search generator is incompatible with the {@link RShell} parser and only works when using flowR with the {@link TreeSitterExecutor}.
+     */
+    syntax(source, ...captures) {
+        return new FlowrSearchBuilder({ type: 'generator', name: 'syntax', args: { source, captures } });
+    },
     /**
      * Returns all elements (nodes/dataflow vertices) from the given data.
      */
@@ -95,7 +102,6 @@ exports.Q = exports.FlowrSearchGenerator;
  * 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}
@@ -204,7 +210,6 @@ class FlowrSearchBuilder {
     }
     /**
      * Construct the final search (this may happen automatically with most search handlers).
-     *
      * @param shouldOptimize - This may optimize the search.
      */
     build(shouldOptimize = true) {

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

@@ -1,7 +1,7 @@
-import type { FlowrSearch, FlowrSearchLike, SearchOutput } from './flowr-search-builder';
-import type { FlowrAnalysisProvider } from '../project/flowr-analyzer';
+import { type FlowrSearch, type FlowrSearchLike, type SearchOutput } from './flowr-search-builder';
+import type { ReadonlyFlowrAnalysisProvider } from '../project/flowr-analyzer';
 export type GetSearchElements<S> = S extends FlowrSearch<infer _, infer _, infer _, infer Elements> ? Elements : never;
 /**
  * Run a search with the given search query and data.
  */
-export declare function runSearch<S extends FlowrSearchLike>(search: S, input: FlowrAnalysisProvider): Promise<GetSearchElements<SearchOutput<S>>>;
+export declare function runSearch<S extends FlowrSearchLike>(search: S, input: ReadonlyFlowrAnalysisProvider): Promise<GetSearchElements<SearchOutput<S>>>;

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

@@ -2,7 +2,7 @@ import { RType } from '../r-bridge/lang-4.x/ast/model/type';
 import { VertexType } from '../dataflow/graph/vertex';
 import type { ParentInformation } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { FlowrSearchElement } from './flowr-search';
-import type { Enrichment } from './search-executor/search-enrichers';
+import { type Enrichment } from './search-executor/search-enrichers';
 import type { BuiltInMappingName } from '../dataflow/environments/built-in';
 import type { DataflowInformation } from '../dataflow/info';
 export type FlowrFilterName = keyof typeof FlowrFilters;
@@ -52,6 +52,9 @@ export interface OriginKindArgs {
     matchType?: 'some' | 'every';
     keepNonFunctionCalls?: boolean;
 }
+/**
+ * Helper to create a regular expression that matches function names, ignoring their package.
+ */
 export declare function testFunctionsIgnoringPackage(functions: readonly string[]): RegExp;
 type ValidFilterTypes<F extends FlowrFilter = FlowrFilter> = FlowrFilterName | FlowrFilterWithArgs<F, FlowrFilterArgs<F>> | RType | VertexType;
 /**
@@ -100,7 +103,14 @@ export declare class FlowrFilterCombinator {
     private unpack;
     get(): BooleanNode;
 }
+/**
+ * Converts the given binary tree to a string representation.
+ */
 export declare function binaryTreeToString(tree: BooleanNode): string;
+/**
+ * Checks whether the given value is a binary tree combinator.
+ * @see {@link FlowrFilterCombinator}
+ */
 export declare function isBinaryTree(tree: unknown): tree is {
     tree: BooleanNode;
 };
@@ -110,5 +120,8 @@ interface FilterData {
         dataflow: DataflowInformation;
     };
 }
+/**
+ * Evaluates the given filter expression against the provided data.
+ */
 export declare function evalFilter<Filter extends FlowrFilter>(filter: FlowrFilterExpression<Filter>, data: FilterData): boolean;
 export {};