@eagleoutice/flowr 2.6.2 → 2.7.0

package/project/context/flowr-file.d.ts

@@ -1,4 +1,5 @@
 import type { PathLike } from 'fs';
+import type { RParseRequest } from '../../r-bridge/retriever';
 /**
  * Just a readable alias for file paths, mostly for documentation purposes.
  * We separate {@link PathLike} types from string paths that are used for project paths.
@@ -9,16 +10,26 @@ export type FilePath = string;
  * 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.
  */
-export declare enum SpecialFileRole {
+export declare enum FileRole {
     /** The `DESCRIPTION` file in R packages, this is the only currently supported special file. */
     Description = "description",
     /** The `NAMESPACE` file in R packages, currently not specially supported. */
     Namespace = "namespace",
     /** Data files, e.g., `R/sysdata.rda`, currently not specially supported. */
     Data = "data",
+    /**
+     * Catch-all for any file that provides usable R source code to incorporate into the analysis.
+     * Please note, that the loading order/inclusion and even potential relevance of these source files
+     * is determined by the loading order plugins (cf. {@link PluginType.LoadingOrder})
+     * in the {@link FlowrAnalyzerLoadingOrderContext}.
+     */
+    Source = "source",
     /** Other special files that are not specifically supported by flowR but may be interesting for some analyses. */
     Other = "other"
 }
+export type StringableContent = {
+    toString(): string;
+};
 /**
  * This is the basic interface for all files known to the FlowrAnalyzer.
  * You can implement this interface to provide custom file loading mechanisms.
@@ -30,19 +41,23 @@ export declare enum SpecialFileRole {
  * If you want to pass in inline text files, see {@link FlowrInlineTextFile}.
  * @typeParam Content - The type of the content returned by the `content()` method.
  */
-export interface FlowrFileProvider<Content = unknown> {
+export interface FlowrFileProvider<Content extends {
+    toString(): string;
+} = {
+    toString(): string;
+}> {
     /**
      * The role of this file, if any, in general your file should _not_ decide for itself what role it has in the project context,
      * this is for the loaders plugins to decide (cf. {@link PluginType}) as they can, e.g., respect ignore files, updated mappings, etc.
      * However, they will 1) set this role as soon as they decide on it (using {@link assignRole}) and 2) try to respect an already assigned role (however, user configurations may override this).
      */
-    role?: SpecialFileRole;
+    role?: FileRole;
     /**
      * The path to the file, this is used for identification and logging purposes.
      * If the file does not exist on disk, this can be a virtual path (e.g. for inline files).
      * Even though this is a getter, please make sure that the operation is cheap and deterministic (some decorators may overwrite the path, e.g., because they support other protocols).
      */
-    path(): PathLike;
+    path(): string;
     /**
      * The content of the file, this may be cached by the implementation and does not have to be expensive.
      * You can used stream based implementations but right now there is no external, project-wide expressions of life cycles for files.
@@ -53,22 +68,29 @@ export interface FlowrFileProvider<Content = unknown> {
      * Assign a role to this file, this should be done by the loader plugins (cf. {@link PluginType}).
      * **Do not call this method yourself unless you are a file-loader plugin and/or really know what you are doing, this may break plugin assumptions!**
      */
-    assignRole(role: SpecialFileRole): void;
+    assignRole(role: FileRole): void;
 }
 /**
  * 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.
  */
-export declare abstract class FlowrFile<Content = unknown> implements FlowrFileProvider<Content> {
+export declare abstract class FlowrFile<Content extends StringableContent = StringableContent> implements FlowrFileProvider<Content> {
     private contentCache;
     protected filePath: PathLike;
-    readonly role?: SpecialFileRole;
-    constructor(filePath: PathLike, role?: SpecialFileRole);
-    path(): PathLike;
+    readonly role?: FileRole;
+    static readonly INLINE_PATH = "@inline";
+    constructor(filePath: PathLike, role?: FileRole);
+    path(): string;
     content(): Content;
     protected abstract loadContent(): Content;
-    assignRole(role: SpecialFileRole): void;
+    assignRole(role: FileRole): void;
+    /**
+     * Creates a {@link FlowrFile} from a given {@link RParseRequest}.
+     * @see {@link FlowrTextFile}
+     * @see {@link FlowrInlineTextFile}
+     */
+    static fromRequest(request: RParseRequest): FlowrFile<string>;
 }
 /**
  * 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).

package/project/context/flowr-file.js

@@ -3,7 +3,7 @@ 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;
+exports.FlowrInlineTextFile = exports.FlowrTextFile = exports.FlowrFile = exports.FileRole = void 0;
 const fs_1 = __importDefault(require("fs"));
 const assert_1 = require("../../util/assert");
 /**
@@ -11,17 +11,24 @@ const assert_1 = require("../../util/assert");
  * 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) {
+var FileRole;
+(function (FileRole) {
     /** The `DESCRIPTION` file in R packages, this is the only currently supported special file. */
-    SpecialFileRole["Description"] = "description";
+    FileRole["Description"] = "description";
     /** The `NAMESPACE` file in R packages, currently not specially supported. */
-    SpecialFileRole["Namespace"] = "namespace";
+    FileRole["Namespace"] = "namespace";
     /** Data files, e.g., `R/sysdata.rda`, currently not specially supported. */
-    SpecialFileRole["Data"] = "data";
+    FileRole["Data"] = "data";
+    /**
+     * Catch-all for any file that provides usable R source code to incorporate into the analysis.
+     * Please note, that the loading order/inclusion and even potential relevance of these source files
+     * is determined by the loading order plugins (cf. {@link PluginType.LoadingOrder})
+     * in the {@link FlowrAnalyzerLoadingOrderContext}.
+     */
+    FileRole["Source"] = "source";
     /** Other special files that are not specifically supported by flowR but may be interesting for some analyses. */
-    SpecialFileRole["Other"] = "other";
-})(SpecialFileRole || (exports.SpecialFileRole = SpecialFileRole = {}));
+    FileRole["Other"] = "other";
+})(FileRole || (exports.FileRole = FileRole = {}));
 /**
  * A basic implementation of the {@link FlowrFileProvider} interface that caches the content after the first load (i.e., updates on disk are ignored).
  *
@@ -31,12 +38,13 @@ class FlowrFile {
     contentCache;
     filePath;
     role;
+    static INLINE_PATH = '@inline';
     constructor(filePath, role) {
         this.filePath = filePath;
         this.role = role;
     }
     path() {
-        return this.filePath;
+        return this.filePath.toString();
     }
     content() {
         if (this.contentCache === undefined) {
@@ -48,6 +56,19 @@ class FlowrFile {
         (0, assert_1.guard)(this.role === undefined || this.role === role, `File ${this.filePath.toString()} already has a role assigned: ${this.role}`);
         this.role = role;
     }
+    /**
+     * Creates a {@link FlowrFile} from a given {@link RParseRequest}.
+     * @see {@link FlowrTextFile}
+     * @see {@link FlowrInlineTextFile}
+     */
+    static fromRequest(request) {
+        if (request.request === 'file') {
+            return new FlowrTextFile(request.content);
+        }
+        else {
+            return new FlowrInlineTextFile(FlowrFile.INLINE_PATH, request.content);
+        }
+    }
 }
 exports.FlowrFile = FlowrFile;
 /**

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

@@ -1,23 +1,23 @@
 import { type EngineConfig, type 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';
+import type { BuiltInFlowrPluginName, PluginToRegister } from './plugins/plugin-registry';
 /**
  * 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.
+ * You can add new files and folders to analyze using the {@link FlowrAnalyzer#addRequest|`.addRequest()`} method on the resulting analyzer.
  * @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();
+ *                      .buildSync()
+ *                      .addRequest('file:///path/to/script.R')
+ *
  * ```
  *
  * If you now want to get the dataflow information for the file, you can do this:
@@ -26,33 +26,22 @@ import type { RAnalysisRequest } from './context/flowr-analyzer-files-context';
  * const dfInfo = await analyzer.dataflow();
  * console.log(dfInfo);
  * ```
+ * @see https://github.com/flowr-analysis/flowr/wiki/Analyzer
  */
 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.
+     * Creates a new builder for the {@link FlowrAnalyzer}.
+     * By default, the standard set of plugins as returned by {@link FlowrAnalyzerPluginDefaults} are registered.
+     * @param withDefaultPlugins - Whether to register the default plugins upon creation. Default is `true`.
+     * @see {@link FlowrAnalyzerPluginDefaults} - for the default plugin set.
+     * @see {@link FlowrAnalyzerBuilder#registerPlugins} - to add more plugins.
+     * @see {@link FlowrAnalyzerBuilder#unregisterPlugins} - to remove plugins.
      */
-    addRequestFromInput(input: Parameters<typeof requestFromInput>[0]): this;
+    constructor(withDefaultPlugins?: boolean);
     /**
      * Apply an amendment to the configuration the builder currently holds.
      * Per default, the {@link defaultConfigOptions} are used.
@@ -79,21 +68,26 @@ export declare class FlowrAnalyzerBuilder {
      * Additional parameters for the analyses.
      * @param input - The input.
      */
-    setInput(input: Omit<NormalizeRequiredInput, 'request'>): this;
+    setInput(input: Omit<NormalizeRequiredInput, 'context'>): this;
     /**
      * Register one or multiple additional plugins.
+     * For the default plugin set, please refer to {@link FlowrAnalyzerPluginDefaults}, they can be registered
+     * by passing `true` to the {@link FlowrAnalyzerBuilder} constructor.
+     * @param plugin - One or multiple plugins to register.
      * @see {@link FlowrAnalyzerBuilder#unregisterPlugins} to remove plugins.
      */
-    registerPlugins(...plugin: readonly FlowrAnalyzerPlugin[]): this;
+    registerPlugins<T extends BuiltInFlowrPluginName | string>(...plugin: readonly PluginToRegister<T>[]): this;
     /**
      * Remove one or multiple plugins.
+     * @see {@link FlowrAnalyzerBuilder#registerPlugins} to add plugins.
      */
-    unregisterPlugins(...plugin: readonly FlowrAnalyzerPlugin[]): this;
+    unregisterPlugins(...plugin: readonly (FlowrAnalyzerPlugin | string | BuiltInFlowrPluginName)[]): 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},
+     * If you have already initialized the engine (e.g., with {@link TreeSitterExecutor#initTreeSitter}),
+     * you can use the synchronous version {@link FlowrAnalyzerBuilder#buildSync} instead.
      */
     build(): Promise<FlowrAnalyzer>;
     /**

package/project/flowr-analyzer-builder.js

@@ -2,25 +2,26 @@
 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");
+const flowr_analyzer_plugin_defaults_1 = require("./plugins/flowr-analyzer-plugin-defaults");
+const plugin_registry_1 = require("./plugins/plugin-registry");
 /**
  * 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.
+ * You can add new files and folders to analyze using the {@link FlowrAnalyzer#addRequest|`.addRequest()`} method on the resulting analyzer.
  * @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();
+ *                      .buildSync()
+ *                      .addRequest('file:///path/to/script.R')
+ *
  * ```
  *
  * If you now want to get the dataflow information for the file, you can do this:
@@ -29,63 +30,25 @@ const flowr_analyzer_cache_1 = require("./cache/flowr-analyzer-cache");
  * const dfInfo = await analyzer.dataflow();
  * console.log(dfInfo);
  * ```
+ * @see https://github.com/flowr-analysis/flowr/wiki/Analyzer
  */
 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.
+     * Creates a new builder for the {@link FlowrAnalyzer}.
+     * By default, the standard set of plugins as returned by {@link FlowrAnalyzerPluginDefaults} are registered.
+     * @param withDefaultPlugins - Whether to register the default plugins upon creation. Default is `true`.
+     * @see {@link FlowrAnalyzerPluginDefaults} - for the default plugin set.
+     * @see {@link FlowrAnalyzerBuilder#registerPlugins} - to add more plugins.
+     * @see {@link FlowrAnalyzerBuilder#unregisterPlugins} - to remove plugins.
      */
-    add(request) {
-        if (Array.isArray(request) || (0, retriever_1.isParseRequest)(request)) {
-            this.addRequest(request);
+    constructor(withDefaultPlugins = true) {
+        if (withDefaultPlugins) {
+            this.registerPlugins(...(0, flowr_analyzer_plugin_defaults_1.FlowrAnalyzerPluginDefaults)());
         }
-        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.
@@ -132,28 +95,29 @@ class FlowrAnalyzerBuilder {
     }
     /**
      * Register one or multiple additional plugins.
+     * For the default plugin set, please refer to {@link FlowrAnalyzerPluginDefaults}, they can be registered
+     * by passing `true` to the {@link FlowrAnalyzerBuilder} constructor.
+     * @param plugin - One or multiple plugins to register.
      * @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);
-            }
+            const s = (0, plugin_registry_1.makePlugin)(p);
+            const g = this.plugins.get(s.type) ?? [];
+            g.push(s);
+            this.plugins.set(s.type, g);
         }
         return this;
     }
     /**
      * Remove one or multiple plugins.
+     * @see {@link FlowrAnalyzerBuilder#registerPlugins} to add 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));
+            const name = typeof p === 'string' ? p : p.name;
+            for (const [type, plugins] of this.plugins) {
+                this.plugins.set(type, plugins.filter((pl) => pl.name !== name));
             }
         }
         return this;
@@ -162,7 +126,8 @@ class FlowrAnalyzerBuilder {
      * 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},
+     * If you have already initialized the engine (e.g., with {@link TreeSitterExecutor#initTreeSitter}),
+     * you can use the synchronous version {@link FlowrAnalyzerBuilder#buildSync} instead.
      */
     async build() {
         if (!this.parser) {
@@ -177,16 +142,13 @@ class FlowrAnalyzerBuilder {
      */
     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);
+        const context = new flowr_analyzer_context_1.FlowrAnalyzerContext(this.flowrConfig, this.plugins);
         const cache = flowr_analyzer_cache_1.FlowrAnalyzerCache.create({
             parser: this.parser,
-            config: this.flowrConfig,
-            request: context.files.computeLoadingOrder(),
+            context,
             ...(this.input ?? {})
         });
-        const analyzer = new flowr_analyzer_1.FlowrAnalyzer(this.flowrConfig, this.parser, context, cache);
-        analyzer.addRequests(this.request);
+        const analyzer = new flowr_analyzer_1.FlowrAnalyzer(this.parser, context, cache);
         // we do it here to save time later if the analyzer is to be duplicated
         context.resolvePreAnalysis();
         return analyzer;

package/project/flowr-analyzer.d.ts

@@ -1,5 +1,5 @@
 import type { FlowrConfigOptions } from '../config';
-import type { KnownParser, KnownParserInformation, ParseStepOutput } from '../r-bridge/parser';
+import type { KnownParser, KnownParserInformation } from '../r-bridge/parser';
 import { type Queries, type QueryResults, type 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';
@@ -12,10 +12,13 @@ import { type GetSearchElements } from '../search/flowr-search-executor';
 import type { FlowrAnalyzerContext, ReadOnlyFlowrAnalyzerContext } from './context/flowr-analyzer-context';
 import { CfgKind } from './cfg-kind';
 import type { RAnalysisRequest } from './context/flowr-analyzer-files-context';
+import type { RParseRequestFromFile } from '../r-bridge/retriever';
+import { fileProtocol } from '../r-bridge/retriever';
+import type { FlowrFileProvider } from './context/flowr-file';
 /**
  * Extends the {@link ReadonlyFlowrAnalysisProvider} with methods that allow modifying the analyzer state.
  */
-export interface FlowrAnalysisProvider extends ReadonlyFlowrAnalysisProvider {
+export interface FlowrAnalysisProvider<Parser extends KnownParser = KnownParser> extends ReadonlyFlowrAnalysisProvider<Parser> {
     /**
      * Returns project context information.
      * If you are a user that wants to inspect the context, prefer {@link inspectContext} instead.
@@ -23,13 +26,18 @@ export interface FlowrAnalysisProvider extends ReadonlyFlowrAnalysisProvider {
      */
     context(): FlowrAnalyzerContext;
     /**
-     * Add multiple analysis requests to the analyzer instance
+     * Add one or multiple requests to analyze.
+     * @param request - One or multiple requests or a file path (with the `file://` protocol). If you just enter a string without the {@link fileProtocol}, it will be interpreted as R code.
+     * @see {@link FlowrAnalysisProvider.addFile|addFile} - for adding files to the analyzer's context.
      */
-    addRequests(requests: readonly RAnalysisRequest[]): void;
+    addRequest(...request: (RAnalysisRequest | `${typeof fileProtocol}${string}` | string)[]): void;
     /**
-     * Add a single analysis request to the analyzer instance
+     * Add one or multiple files to the analyzer's context.
+     * @param f - One or multiple file paths, file providers, or parse requests from file.
+     * @see {@link FlowrFileProvider} - for creating custom file providers.
+     * @see {@link FlowrAnalysisProvider.addRequest|addRequest} - for adding analysis requests to the analyzer.
      */
-    addRequest(request: RAnalysisRequest): void;
+    addFile(...f: (string | FlowrFileProvider<string> | RParseRequestFromFile)[]): void;
     /**
      * Reset the analyzer state, including the context and the cache.
      */
@@ -39,7 +47,7 @@ export interface FlowrAnalysisProvider extends ReadonlyFlowrAnalysisProvider {
  * 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 ReadonlyFlowrAnalysisProvider {
+export interface ReadonlyFlowrAnalysisProvider<Parser extends KnownParser = KnownParser> {
     /**
      * Returns a set of additional data and helper functions exposed by the underlying {@link KnownParser},
      * including the parser's {@link BaseParserInformation.name} and corresponding version information.
@@ -55,25 +63,45 @@ export interface ReadonlyFlowrAnalysisProvider {
      *
      * 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.
+     * @see {@link ReadonlyFlowrAnalysisProvider#peekParse} - to get the parse output if already available without triggering a new computation.
      */
-    parse(force?: boolean): Promise<ParseStepOutput<Awaited<ReturnType<KnownParser['parse']>>> & PipelinePerStepMetaInformation>;
+    parse(force?: boolean): Promise<NonNullable<AnalyzerCacheType<Parser>['parse']>>;
+    /**
+     * Peek at the parse output for the request, if it was already computed.
+     */
+    peekParse(): NonNullable<AnalyzerCacheType<Parser>['parse']> | undefined;
     /**
      * Get the normalized abstract syntax tree for the request.
      * @param force - Do not use the cache, instead force new analyses.
+     * @see {@link ReadonlyFlowrAnalysisProvider#peekNormalize} - to get the normalized AST if already available without triggering a new computation.
      */
     normalize(force?: boolean): Promise<NormalizedAst & PipelinePerStepMetaInformation>;
+    /**
+     * Peek at the normalized abstract syntax tree for the request, if it was already computed.
+     */
+    peekNormalize(): NormalizedAst & PipelinePerStepMetaInformation | undefined;
     /**
      * Get the dataflow graph for the request.
      * @param force - Do not use the cache, instead force new analyses.
+     * @see {@link ReadonlyFlowrAnalysisProvider#peekDataflow} - to get the dataflow graph if already available without triggering a new computation.
      */
     dataflow(force?: boolean): Promise<DataflowInformation & PipelinePerStepMetaInformation>;
+    /**
+     * Peek at the dataflow graph for the request, if it was already computed.
+     */
+    peekDataflow(): DataflowInformation & PipelinePerStepMetaInformation | undefined;
     /**
      * Get the control flow graph (CFG) for the request.
      * @param simplifications - Simplification passes to be applied to the CFG.
      * @param kind            - The kind of CFG that is requested. By default, the CFG without dataflow information is returned.
      * @param force           - Do not use the cache, instead force new analyses.
+     * @see {@link ReadonlyFlowrAnalysisProvider#peekControlflow} - to get the CFG if already available without triggering a new computation.
      */
     controlflow(simplifications?: readonly CfgSimplificationPassName[], kind?: CfgKind, force?: boolean): Promise<ControlFlowInformation>;
+    /**
+     * Peek at the control flow graph (CFG) for the request, if it was already computed.
+     */
+    peekControlflow(simplifications?: readonly CfgSimplificationPassName[], kind?: CfgKind): ControlFlowInformation | undefined;
     /**
      * Access the query API for the request.
      * @param query - The list of queries.
@@ -97,9 +125,9 @@ export interface ReadonlyFlowrAnalysisProvider {
  * 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).
+ * @see https://github.com/flowr-analysis/flowr/wiki/Analyzer
  */
-export declare class FlowrAnalyzer<Parser extends KnownParser = KnownParser> implements ReadonlyFlowrAnalysisProvider {
-    readonly flowrConfig: FlowrConfigOptions;
+export declare class FlowrAnalyzer<Parser extends KnownParser = KnownParser> implements ReadonlyFlowrAnalysisProvider<Parser> {
     /** The parser and engine backend */
     private readonly parser;
     /** The cache used for storing analysis results */
@@ -109,23 +137,36 @@ export declare class FlowrAnalyzer<Parser extends KnownParser = KnownParser> imp
     /**
      * 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>);
+    constructor(parser: Parser, ctx: FlowrAnalyzerContext, cache: FlowrAnalyzerCache<Parser>);
+    get flowrConfig(): FlowrConfigOptions;
     context(): FlowrAnalyzerContext;
     parserInformation(): KnownParserInformation;
     inspectContext(): ReadOnlyFlowrAnalyzerContext;
     reset(): void;
-    addRequests(requests: readonly RAnalysisRequest[]): void;
-    addRequest(request: RAnalysisRequest): void;
+    addRequest(...request: (RAnalysisRequest | readonly RAnalysisRequest[] | `${typeof fileProtocol}${string}` | string)[]): this;
+    addFile(...f: (string | FlowrFileProvider | RParseRequestFromFile)[]): this;
+    /**
+     * Add a request created from the given input.
+     * This is a convenience method that uses {@link requestFromInput} internally.
+     */
+    private addRequestFromInput;
+    /**
+     * Add one or multiple requests to analyze the builder.
+     */
+    private addAnalysisRequest;
     parse(force?: boolean): Promise<NonNullable<AnalyzerCacheType<Parser>['parse']>>;
+    peekParse(): NonNullable<AnalyzerCacheType<Parser>['parse']> | undefined;
     normalize(force?: boolean): Promise<NonNullable<AnalyzerCacheType<Parser>['normalize']>>;
+    peekNormalize(): NonNullable<AnalyzerCacheType<Parser>['normalize']> | undefined;
     dataflow(force?: boolean): Promise<NonNullable<AnalyzerCacheType<Parser>['dataflow']>>;
+    peekDataflow(): NonNullable<AnalyzerCacheType<Parser>['dataflow']> | undefined;
     runFull(force?: boolean): Promise<void>;
     controlflow(simplifications?: readonly CfgSimplificationPassName[], kind?: CfgKind, force?: boolean): Promise<ControlFlowInformation>;
+    peekControlflow(simplifications?: readonly CfgSimplificationPassName[], kind?: CfgKind): ControlFlowInformation | undefined;
     query<Types extends SupportedQueryTypes = SupportedQueryTypes>(query: Queries<Types>): Promise<QueryResults<Types>>;
     runSearch<Search extends FlowrSearchLike>(search: Search): Promise<GetSearchElements<SearchOutput<Search>>>;
     /**