@eagleoutice/flowr 2.5.0 → 2.6.0

package/project/context/flowr-file.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrInlineTextFile = exports.FlowrTextFile = exports.FlowrFile = exports.SpecialFileRole = void 0;
+const fs_1 = __importDefault(require("fs"));
+const assert_1 = require("../../util/assert");
+/**
+ * Some files have a special meaning in R projects, e.g., the `DESCRIPTION` file in R packages.
+ * This list may be extended in the future and reflects files that the {@link FlowrAnalyzer} can do something interesting with.
+ * If you add an interesting file that is only part of your plugin infrastructure, please use the `other` role.
+ */
+var SpecialFileRole;
+(function (SpecialFileRole) {
+    /** The `DESCRIPTION` file in R packages, this is the only currently supported special file. */
+    SpecialFileRole["Description"] = "description";
+    /** The `NAMESPACE` file in R packages, currently not specially supported. */
+    SpecialFileRole["Namespace"] = "namespace";
+    /** Data files, e.g., `R/sysdata.rda`, currently not specially supported. */
+    SpecialFileRole["Data"] = "data";
+    /** Other special files that are not specifically supported by flowR but may be interesting for some analyses. */
+    SpecialFileRole["Other"] = "other";
+})(SpecialFileRole || (exports.SpecialFileRole = SpecialFileRole = {}));
+/**
+ * A basic implementation of the {@link FlowrFileProvider} interface that caches the content after the first load (i.e., updates on disk are ignored).
+ *
+ * See {@link FlowrTextFile} for a text-file specific implementation and {@link FlowrInlineTextFile} for inline text files.
+ */
+class FlowrFile {
+    contentCache;
+    filePath;
+    role;
+    constructor(filePath, role) {
+        this.filePath = filePath;
+        this.role = role;
+    }
+    path() {
+        return this.filePath;
+    }
+    content() {
+        if (this.contentCache === undefined) {
+            this.contentCache = this.loadContent();
+        }
+        return this.contentCache;
+    }
+    assignRole(role) {
+        (0, assert_1.guard)(this.role === undefined || this.role === role, `File ${this.filePath.toString()} already has a role assigned: ${this.role}`);
+        this.role = role;
+    }
+}
+exports.FlowrFile = FlowrFile;
+/**
+ * A basic implementation of the {@link FlowrFileProvider} interface for text files that caches the content after the first load (i.e., updates on disk are ignored).
+ */
+class FlowrTextFile extends FlowrFile {
+    loadContent() {
+        return fs_1.default.readFileSync(this.filePath, 'utf8');
+    }
+}
+exports.FlowrTextFile = FlowrTextFile;
+/**
+ * A basic implementation of the {@link FlowrFileProvider} interface for (constant) inline text files.
+ * This is also useful for "special" files like the `DESCRIPTION` file in R packages that you want to pass in directly.
+ * These will be handled by the {@link FlowrAnalyzerDescriptionFilePlugin} (e.g., by using the {@link FlowrDescriptionFile#from} method decorator).
+ */
+class FlowrInlineTextFile extends FlowrFile {
+    contentStr;
+    constructor(path, content) {
+        super(path);
+        this.contentStr = content;
+    }
+    loadContent() {
+        return this.contentStr;
+    }
+}
+exports.FlowrInlineTextFile = FlowrInlineTextFile;
+//# sourceMappingURL=flowr-file.js.map

package/project/flowr-analyzer-builder.d.ts

@@ -0,0 +1,106 @@
+import type { EngineConfig, FlowrConfigOptions } from '../config';
+import type { DeepWritable } from 'ts-essentials';
+import { fileProtocol, requestFromInput } from '../r-bridge/retriever';
+import { FlowrAnalyzer } from './flowr-analyzer';
+import type { KnownParser } from '../r-bridge/parser';
+import type { FlowrAnalyzerPlugin } from './plugins/flowr-analyzer-plugin';
+import type { NormalizeRequiredInput } from '../core/steps/all/core/10-normalize';
+import type { RAnalysisRequest } from './context/flowr-analyzer-files-context';
+/**
+ * Builder for the {@link FlowrAnalyzer}, use it to configure all analysis aspects before creating the analyzer instance
+ * with {@link FlowrAnalyzerBuilder#build|`.build()`} or {@link FlowrAnalyzerBuilder#buildSync|`.buildSync()`}.
+ *
+ * You can add new files and folders to analyze using the constructor or the {@link FlowrAnalyzerBuilder#add|`.add()`} method.
+ *
+ * @example Let's create an analyzer for a single R script file:
+ *
+ * ```ts
+ * const analyzer = new FlowrAnalyzerBuilder()
+ *                      .add('file:///path/to/script.R')
+ *                      .setParser(new TreeSitterExecutor())
+ *                      .buildSync();
+ * ```
+ *
+ * If you now want to get the dataflow information for the file, you can do this:
+ *
+ * ```ts
+ * const dfInfo = await analyzer.dataflow();
+ * console.log(dfInfo);
+ * ```
+ */
+export declare class FlowrAnalyzerBuilder {
+    private flowrConfig;
+    private parser?;
+    private request;
+    private input?;
+    private plugins;
+    /**
+     * Create a new builder instance.
+     * @param request - The code to analyze
+     */
+    constructor(request?: RAnalysisRequest | readonly RAnalysisRequest[]);
+    /**
+     * Add one or multiple requests to analyze.
+     * This is a convenience method that uses {@link addRequest} and {@link addRequestFromInput} internally.
+     * @param request - One or multiple requests or a file path (with the `file://` protocol). If you just enter a string, it will be interpreted as R code.
+     */
+    add(request: RAnalysisRequest | readonly RAnalysisRequest[] | `${typeof fileProtocol}${string}` | string): this;
+    /**
+     * Add one or multiple requests to analyze the builder.
+     */
+    addRequest(request: RAnalysisRequest | readonly RAnalysisRequest[]): this;
+    /**
+     * Add a request created from the given input.
+     * This is a convenience method that uses {@link requestFromInput} internally.
+     */
+    addRequestFromInput(input: Parameters<typeof requestFromInput>[0]): this;
+    /**
+     * Apply an amendment to the configuration the builder currently holds.
+     * Per default, the {@link defaultConfigOptions} are used.
+     * @param func - Receives the current configuration of the builder and allows for amendment.
+     */
+    amendConfig(func: (config: DeepWritable<FlowrConfigOptions>) => FlowrConfigOptions | void): this;
+    /**
+     * Overwrite the configuration used by the resulting analyzer.
+     * @param config - The new configuration.
+     */
+    setConfig(config: FlowrConfigOptions): this;
+    /**
+     * Set the parser instance used by the analyzer.
+     * This is an alternative to {@link FlowrAnalyzerBuilder#setEngine} if you already have a parser instance.
+     * Please be aware, that if you want to parallelize multiple analyzers, there should be separate parser instances.
+     */
+    setParser(parser: KnownParser): this;
+    /**
+     * Set the engine and hence the parser that will be used by the analyzer.
+     * This is an alternative to {@link FlowrAnalyzerBuilder#setParser} if you do not have a parser instance at hand.
+     */
+    setEngine(engine: EngineConfig['type']): this;
+    /**
+     * Additional parameters for the analyses.
+     * @param input - The input.
+     */
+    setInput(input: Omit<NormalizeRequiredInput, 'request'>): this;
+    /**
+     * Register one or multiple additional plugins.
+     *
+     * @see {@link FlowrAnalyzerBuilder#unregisterPlugins} to remove plugins.
+     */
+    registerPlugins(...plugin: readonly FlowrAnalyzerPlugin[]): this;
+    /**
+     * Remove one or multiple plugins.
+     */
+    unregisterPlugins(...plugin: readonly FlowrAnalyzerPlugin[]): this;
+    /**
+     * Create the {@link FlowrAnalyzer} instance using the given information.
+     * Please note that the only reason this is `async` is that if no parser is set,
+     * we need to retrieve the default engine instance which is an async operation.
+     * If you set the parser using {@link FlowrAnalyzerBuilder#setParser},
+     */
+    build(): Promise<FlowrAnalyzer>;
+    /**
+     * Synchronous version of {@link FlowrAnalyzerBuilder#build}, please only use this if you have set the parser using
+     * {@link FlowrAnalyzerBuilder#setParser} before, otherwise an error will be thrown.
+     */
+    buildSync(): FlowrAnalyzer;
+}

package/project/flowr-analyzer-builder.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrAnalyzerBuilder = void 0;
+const config_1 = require("../config");
+const retriever_1 = require("../r-bridge/retriever");
+const flowr_analyzer_1 = require("./flowr-analyzer");
+const engines_1 = require("../engines");
+const assert_1 = require("../util/assert");
+const files_1 = require("../util/files");
+const flowr_analyzer_context_1 = require("./context/flowr-analyzer-context");
+const flowr_analyzer_cache_1 = require("./cache/flowr-analyzer-cache");
+/**
+ * Builder for the {@link FlowrAnalyzer}, use it to configure all analysis aspects before creating the analyzer instance
+ * with {@link FlowrAnalyzerBuilder#build|`.build()`} or {@link FlowrAnalyzerBuilder#buildSync|`.buildSync()`}.
+ *
+ * You can add new files and folders to analyze using the constructor or the {@link FlowrAnalyzerBuilder#add|`.add()`} method.
+ *
+ * @example Let's create an analyzer for a single R script file:
+ *
+ * ```ts
+ * const analyzer = new FlowrAnalyzerBuilder()
+ *                      .add('file:///path/to/script.R')
+ *                      .setParser(new TreeSitterExecutor())
+ *                      .buildSync();
+ * ```
+ *
+ * If you now want to get the dataflow information for the file, you can do this:
+ *
+ * ```ts
+ * const dfInfo = await analyzer.dataflow();
+ * console.log(dfInfo);
+ * ```
+ */
+class FlowrAnalyzerBuilder {
+    flowrConfig = (0, config_1.cloneConfig)(config_1.defaultConfigOptions);
+    parser;
+    request;
+    input;
+    plugins = new Map();
+    /**
+     * Create a new builder instance.
+     * @param request - The code to analyze
+     */
+    constructor(request) {
+        this.addRequest(request ?? []);
+    }
+    /**
+     * Add one or multiple requests to analyze.
+     * This is a convenience method that uses {@link addRequest} and {@link addRequestFromInput} internally.
+     * @param request - One or multiple requests or a file path (with the `file://` protocol). If you just enter a string, it will be interpreted as R code.
+     */
+    add(request) {
+        if (Array.isArray(request) || (0, retriever_1.isParseRequest)(request)) {
+            this.addRequest(request);
+        }
+        else if (typeof request === 'string') {
+            const trimmed = request.substring(retriever_1.fileProtocol.length);
+            if (request.startsWith(retriever_1.fileProtocol) && !(0, files_1.isFilePath)(trimmed)) {
+                this.addRequest({ request: 'project', content: trimmed });
+            }
+            else {
+                this.addRequestFromInput(request);
+            }
+        }
+        else {
+            this.addRequest(request);
+        }
+        return this;
+    }
+    /**
+     * Add one or multiple requests to analyze the builder.
+     */
+    addRequest(request) {
+        const r = Array.isArray(request) ? request : [request];
+        if (this.request) {
+            this.request = this.request.concat(request);
+        }
+        else {
+            this.request = r;
+        }
+        return this;
+    }
+    /**
+     * Add a request created from the given input.
+     * This is a convenience method that uses {@link requestFromInput} internally.
+     */
+    addRequestFromInput(input) {
+        this.addRequest((0, retriever_1.requestFromInput)(input));
+        return this;
+    }
+    /**
+     * Apply an amendment to the configuration the builder currently holds.
+     * Per default, the {@link defaultConfigOptions} are used.
+     * @param func - Receives the current configuration of the builder and allows for amendment.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+    amendConfig(func) {
+        this.flowrConfig = (0, config_1.amendConfig)(this.flowrConfig, func);
+        return this;
+    }
+    /**
+     * Overwrite the configuration used by the resulting analyzer.
+     * @param config - The new configuration.
+     */
+    setConfig(config) {
+        this.flowrConfig = config;
+        return this;
+    }
+    /**
+     * Set the parser instance used by the analyzer.
+     * This is an alternative to {@link FlowrAnalyzerBuilder#setEngine} if you already have a parser instance.
+     * Please be aware, that if you want to parallelize multiple analyzers, there should be separate parser instances.
+     */
+    setParser(parser) {
+        this.parser = parser;
+        return this;
+    }
+    /**
+     * Set the engine and hence the parser that will be used by the analyzer.
+     * This is an alternative to {@link FlowrAnalyzerBuilder#setParser} if you do not have a parser instance at hand.
+     */
+    setEngine(engine) {
+        this.flowrConfig.defaultEngine = engine;
+        return this;
+    }
+    /**
+     * Additional parameters for the analyses.
+     * @param input - The input.
+     */
+    setInput(input) {
+        this.input = input;
+        return this;
+    }
+    /**
+     * Register one or multiple additional plugins.
+     *
+     * @see {@link FlowrAnalyzerBuilder#unregisterPlugins} to remove plugins.
+     */
+    registerPlugins(...plugin) {
+        for (const p of plugin) {
+            const g = this.plugins.get(p.type);
+            if (g === undefined) {
+                this.plugins.set(p.type, [p]);
+            }
+            else {
+                g.push(p);
+            }
+        }
+        return this;
+    }
+    /**
+     * Remove one or multiple plugins.
+     */
+    unregisterPlugins(...plugin) {
+        for (const p of plugin) {
+            const g = this.plugins.get(p.type);
+            if (g !== undefined) {
+                this.plugins.set(p.type, g.filter(x => x !== p));
+            }
+        }
+        return this;
+    }
+    /**
+     * Create the {@link FlowrAnalyzer} instance using the given information.
+     * Please note that the only reason this is `async` is that if no parser is set,
+     * we need to retrieve the default engine instance which is an async operation.
+     * If you set the parser using {@link FlowrAnalyzerBuilder#setParser},
+     */
+    async build() {
+        if (!this.parser) {
+            const engines = await (0, engines_1.retrieveEngineInstances)(this.flowrConfig, true);
+            this.parser = engines.engines[engines.default];
+        }
+        return this.buildSync();
+    }
+    /**
+     * Synchronous version of {@link FlowrAnalyzerBuilder#build}, please only use this if you have set the parser using
+     * {@link FlowrAnalyzerBuilder#setParser} before, otherwise an error will be thrown.
+     */
+    buildSync() {
+        (0, assert_1.guard)(this.parser !== undefined, 'No parser set, please use the setParser or setEngine method to set a parser before building the analyzer');
+        (0, assert_1.guard)(this.request !== undefined, 'Currently we require at least one request to build an analyzer, please provide one using the constructor or the addRequest method');
+        const context = new flowr_analyzer_context_1.FlowrAnalyzerContext(this.plugins);
+        context.addRequests(this.request);
+        // we do it here to save time later if the analyzer is to be duplicated
+        context.resolvePreAnalysis();
+        const cache = flowr_analyzer_cache_1.FlowrAnalyzerCache.create({
+            parser: this.parser,
+            config: this.flowrConfig,
+            request: context.files.computeLoadingOrder(),
+            ...(this.input ?? {})
+        });
+        return new flowr_analyzer_1.FlowrAnalyzer(this.flowrConfig, this.parser, context, cache);
+    }
+}
+exports.FlowrAnalyzerBuilder = FlowrAnalyzerBuilder;
+//# sourceMappingURL=flowr-analyzer-builder.js.map

package/project/flowr-analyzer.d.ts

@@ -0,0 +1,125 @@
+import type { FlowrConfigOptions } from '../config';
+import type { KnownParser, KnownParserName, ParseStepOutput } from '../r-bridge/parser';
+import type { Queries, QueryResults, SupportedQueryTypes } from '../queries/query';
+import type { ControlFlowInformation } from '../control-flow/control-flow-graph';
+import type { NormalizedAst } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { DataflowInformation } from '../dataflow/info';
+import type { CfgSimplificationPassName } from '../control-flow/cfg-simplification';
+import type { PipelinePerStepMetaInformation } from '../core/steps/pipeline/pipeline';
+import type { FlowrAnalyzerCache } from './cache/flowr-analyzer-cache';
+import type { FlowrSearchLike, SearchOutput } from '../search/flowr-search-builder';
+import type { GetSearchElements } from '../search/flowr-search-executor';
+import type { FlowrAnalyzerContext, ReadOnlyFlowrAnalyzerContext } from './context/flowr-analyzer-context';
+/**
+ * Exposes the central analyses and information provided by the {@link FlowrAnalyzer} to the linter, search, and query APIs.
+ * This allows us to exchange the underlying implementation of the analyzer without affecting the APIs.
+ */
+export interface FlowrAnalysisProvider {
+    /**
+     * Get the name of the parser used by the analyzer.
+     */
+    parserName(): string;
+    /**
+     * Returns project context information.
+     * If you are a user that wants to inspect the context, prefer {@link inspectContext} instead.
+     * Please be aware that modifications to the context may break analyzer assumptions.
+     */
+    context(): FlowrAnalyzerContext;
+    /**
+     * Returns a read-only version of the project context information.
+     * This is the preferred method for users that want to inspect the context.
+     */
+    inspectContext(): ReadOnlyFlowrAnalyzerContext;
+    /**
+     * Get the parse output for the request.
+     *
+     * The parse result type depends on the {@link KnownParser} used by the analyzer.
+     * @param force - Do not use the cache, instead force a new parse.
+     */
+    parse(force?: boolean): Promise<ParseStepOutput<Awaited<ReturnType<KnownParser['parse']>>> & PipelinePerStepMetaInformation>;
+    /**
+     * Get the normalized abstract syntax tree for the request.
+     * @param force - Do not use the cache, instead force new analyses.
+     */
+    normalize(force?: boolean): Promise<NormalizedAst & PipelinePerStepMetaInformation>;
+    /**
+     * Get the dataflow graph for the request.
+     * @param force - Do not use the cache, instead force new analyses.
+     */
+    dataflow(force?: boolean): Promise<DataflowInformation & PipelinePerStepMetaInformation>;
+    /**
+     * Get the control flow graph (CFG) for the request.
+     * @param simplifications - Simplification passes to be applied to the CFG.
+     * @param useDataflow     - Whether to use the dataflow graph for the creation of the CFG.
+     * @param force           - Do not use the cache, instead force new analyses.
+     */
+    controlflow(simplifications?: readonly CfgSimplificationPassName[], useDataflow?: boolean, force?: boolean): Promise<ControlFlowInformation>;
+    /**
+     * Get a quick and dirty control flow graph (CFG) for the request.
+     * This does not use the dataflow information and does not apply any simplifications.
+     *
+     * @param force - Do not use the cache, instead force new analyses.
+     */
+    controlflowQuick(force?: boolean): Promise<ControlFlowInformation>;
+    /**
+     * Access the query API for the request.
+     * @param query - The list of queries.
+     */
+    query<Types extends SupportedQueryTypes = SupportedQueryTypes>(query: Queries<Types>): Promise<QueryResults<Types>>;
+    /**
+     * Run a search on the current analysis.
+     */
+    runSearch<Search extends FlowrSearchLike>(search: Search): Promise<GetSearchElements<SearchOutput<Search>>>;
+    /**
+     * This executes all steps of the core analysis (parse, normalize, dataflow).
+     */
+    runFull(force?: boolean): Promise<void>;
+    /**
+     * Reset all caches used by the analyzer and effectively force all analyses to be redone.
+     */
+    reset(): void;
+    /** This is the config used for the analyzer */
+    flowrConfig: FlowrConfigOptions;
+}
+/**
+ * Central class for conducting analyses with FlowR.
+ * Use the {@link FlowrAnalyzerBuilder} to create a new instance.
+ *
+ * If you want the original pattern of creating a pipeline and running all steps, you can still do this with {@link FlowrAnalyzer#runFull}.
+ *
+ * To inspect the context of the analyzer, use {@link FlowrAnalyzer#inspectContext} (if you are a plugin and need to modify it, use {@link FlowrAnalyzer#context} instead).
+ */
+export declare class FlowrAnalyzer<Parser extends KnownParser = KnownParser> implements FlowrAnalysisProvider {
+    readonly flowrConfig: FlowrConfigOptions;
+    /** The parser and engine backend */
+    private readonly parser;
+    /** The cache used for storing analysis results */
+    private readonly cache;
+    private readonly ctx;
+    /**
+     * Create a new analyzer instance.
+     * **Prefer the use of the {@link FlowrAnalyzerBuilder} instead of calling this constructor directly.**
+     *
+     * @param config - The FlowR config to use for the analyses
+     * @param parser - The parser to use for parsing the given request.
+     * @param ctx    - The context to use for the analyses.
+     * @param cache  - The caching layer to use for storing analysis results.
+     */
+    constructor(config: FlowrConfigOptions, parser: Parser, ctx: FlowrAnalyzerContext, cache: FlowrAnalyzerCache<Parser>);
+    context(): FlowrAnalyzerContext;
+    inspectContext(): ReadOnlyFlowrAnalyzerContext;
+    reset(): void;
+    parserName(): KnownParserName;
+    parse(force?: boolean): ReturnType<typeof this.cache.parse>;
+    normalize(force?: boolean): ReturnType<typeof this.cache.normalize>;
+    dataflow(force?: boolean): ReturnType<typeof this.cache.dataflow>;
+    runFull(force?: boolean): Promise<void>;
+    controlflow(simplifications?: readonly CfgSimplificationPassName[], useDataflow?: boolean, force?: boolean): Promise<ControlFlowInformation>;
+    controlflowQuick(force?: boolean): Promise<ControlFlowInformation>;
+    query<Types extends SupportedQueryTypes = SupportedQueryTypes>(query: Queries<Types>): Promise<QueryResults<Types>>;
+    runSearch<Search extends FlowrSearchLike>(search: Search): Promise<GetSearchElements<SearchOutput<Search>>>;
+    /**
+     * Close the parser if it was created by this builder. This is only required if you rely on an RShell/remote engine.
+     */
+    close(): boolean | void;
+}

package/project/flowr-analyzer.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrAnalyzer = void 0;
+const query_1 = require("../queries/query");
+const flowr_search_executor_1 = require("../search/flowr-search-executor");
+/**
+ * Central class for conducting analyses with FlowR.
+ * Use the {@link FlowrAnalyzerBuilder} to create a new instance.
+ *
+ * If you want the original pattern of creating a pipeline and running all steps, you can still do this with {@link FlowrAnalyzer#runFull}.
+ *
+ * To inspect the context of the analyzer, use {@link FlowrAnalyzer#inspectContext} (if you are a plugin and need to modify it, use {@link FlowrAnalyzer#context} instead).
+ */
+class FlowrAnalyzer {
+    flowrConfig;
+    /** The parser and engine backend */
+    parser;
+    /** The cache used for storing analysis results */
+    cache;
+    ctx;
+    /**
+     * Create a new analyzer instance.
+     * **Prefer the use of the {@link FlowrAnalyzerBuilder} instead of calling this constructor directly.**
+     *
+     * @param config - The FlowR config to use for the analyses
+     * @param parser - The parser to use for parsing the given request.
+     * @param ctx    - The context to use for the analyses.
+     * @param cache  - The caching layer to use for storing analysis results.
+     */
+    constructor(config, parser, ctx, cache) {
+        this.flowrConfig = config;
+        this.parser = parser;
+        this.ctx = ctx;
+        this.cache = cache;
+    }
+    context() {
+        return this.ctx;
+    }
+    inspectContext() {
+        return this.ctx.inspect();
+    }
+    reset() {
+        this.cache.reset();
+    }
+    parserName() {
+        return this.parser.name;
+    }
+    async parse(force) {
+        return this.cache.parse(force);
+    }
+    async normalize(force) {
+        return this.cache.normalize(force);
+    }
+    async dataflow(force) {
+        return this.cache.dataflow(force);
+    }
+    async runFull(force) {
+        await this.dataflow(force);
+        return;
+    }
+    async controlflow(simplifications, useDataflow, force) {
+        return this.cache.controlflow(force, useDataflow ?? false, simplifications);
+    }
+    async controlflowQuick(force) {
+        return this.controlflow(undefined, false, force);
+    }
+    async query(query) {
+        return (0, query_1.executeQueries)({ analyzer: this }, query);
+    }
+    async runSearch(search) {
+        return (0, flowr_search_executor_1.runSearch)(search, this);
+    }
+    /**
+     * Close the parser if it was created by this builder. This is only required if you rely on an RShell/remote engine.
+     */
+    close() {
+        return this.parser?.close();
+    }
+}
+exports.FlowrAnalyzer = FlowrAnalyzer;
+//# sourceMappingURL=flowr-analyzer.js.map

package/project/plugins/file-plugins/flowr-analyzer-description-file-plugin.d.ts

@@ -0,0 +1,17 @@
+import { FlowrAnalyzerFilePlugin } from './flowr-analyzer-file-plugin';
+import { SemVer } from 'semver';
+import type { PathLike } from 'fs';
+import type { FlowrAnalyzerContext } from '../../context/flowr-analyzer-context';
+import { FlowrDescriptionFile } from './flowr-description-file';
+import type { FlowrFileProvider } from '../../context/flowr-file';
+export declare const descriptionFileLog: import("tslog").Logger<import("tslog").ILogObj>;
+/**
+ * This plugin provides support for R `DESCRIPTION` files.
+ */
+export declare class FlowrAnalyzerDescriptionFilePlugin extends FlowrAnalyzerFilePlugin {
+    readonly name = "flowr-analyzer-description-file-plugin";
+    readonly description = "This plugin provides support for DESCRIPTION files and extracts their content into key-value(s) pairs.";
+    readonly version: SemVer;
+    applies(file: PathLike): boolean;
+    process(_ctx: FlowrAnalyzerContext, file: FlowrFileProvider<string>): FlowrDescriptionFile;
+}

package/project/plugins/file-plugins/flowr-analyzer-description-file-plugin.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrAnalyzerDescriptionFilePlugin = exports.descriptionFileLog = void 0;
+const flowr_analyzer_file_plugin_1 = require("./flowr-analyzer-file-plugin");
+const semver_1 = require("semver");
+const log_1 = require("../../../util/log");
+const flowr_description_file_1 = require("./flowr-description-file");
+const flowr_file_1 = require("../../context/flowr-file");
+exports.descriptionFileLog = log_1.log.getSubLogger({ name: 'flowr-analyzer-loading-order-description-file-plugin' });
+/**
+ * This plugin provides support for R `DESCRIPTION` files.
+ */
+class FlowrAnalyzerDescriptionFilePlugin extends flowr_analyzer_file_plugin_1.FlowrAnalyzerFilePlugin {
+    name = 'flowr-analyzer-description-file-plugin';
+    description = 'This plugin provides support for DESCRIPTION files and extracts their content into key-value(s) pairs.';
+    version = new semver_1.SemVer('0.1.0');
+    applies(file) {
+        return /^(DESCRIPTION|DESCRIPTION\.txt)$/i.test(file.toString().split(/[/\\]/).pop() ?? '');
+    }
+    process(_ctx, file) {
+        const f = flowr_description_file_1.FlowrDescriptionFile.from(file, flowr_file_1.SpecialFileRole.Description);
+        // already load it here
+        f.content();
+        return f;
+    }
+}
+exports.FlowrAnalyzerDescriptionFilePlugin = FlowrAnalyzerDescriptionFilePlugin;
+//# sourceMappingURL=flowr-analyzer-description-file-plugin.js.map

package/project/plugins/file-plugins/flowr-analyzer-file-plugin.d.ts

@@ -0,0 +1,21 @@
+import { FlowrAnalyzerPlugin, PluginType } from '../flowr-analyzer-plugin';
+import type { PathLike } from 'fs';
+import type { FlowrFileProvider } from '../../context/flowr-file';
+/**
+ * This is the base class for all plugins that load and possibly transform files when they are loaded.
+ * Different from other plugins, these plugins trigger for each file that is loaded (if they {@link applies} to the file).
+ * See the {@link FlowrAnalyzerFilesContext.addFile} for more information on how files are loaded and managed.
+ *
+ * It is upt to the construction to ensure that no two file plugins {@link applies} to the same file, otherwise, the loading order
+ * of these plugins will determine which plugin gets to process the file.
+ *
+ * See {@link DefaultFlowrAnalyzerFilePlugin} for the no-op default implementation.
+ */
+export declare abstract class FlowrAnalyzerFilePlugin extends FlowrAnalyzerPlugin<FlowrFileProvider<string>, FlowrFileProvider> {
+    readonly type = PluginType.FileLoad;
+    /**
+     * Determine whether this plugin applies to the given file.
+     */
+    abstract applies(file: PathLike): boolean;
+    static defaultPlugin(): FlowrAnalyzerFilePlugin;
+}