@eagleoutice/flowr 2.6.1 → 2.6.3

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

@@ -1,22 +1,18 @@
 import type { KnownParser } from '../../r-bridge/parser';
-import type { CacheInvalidationEvent } from './flowr-cache';
-import { FlowrCache } from './flowr-cache';
-import type { DEFAULT_DATAFLOW_PIPELINE, TREE_SITTER_DATAFLOW_PIPELINE } from '../../core/steps/pipeline/default-pipelines';
-import type { FlowrConfigOptions } from '../../config';
-import type { RParseRequests } from '../../r-bridge/retriever';
+import { type CacheInvalidationEvent, FlowrCache } from './flowr-cache';
+import { type DEFAULT_DATAFLOW_PIPELINE, type TREE_SITTER_DATAFLOW_PIPELINE } from '../../core/steps/pipeline/default-pipelines';
 import type { IdGenerator } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { NoInfo } from '../../r-bridge/lang-4.x/ast/model/model';
 import type { TreeSitterExecutor } from '../../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor';
 import type { PipelineOutput } from '../../core/steps/pipeline/pipeline';
 import type { CfgSimplificationPassName } from '../../control-flow/cfg-simplification';
 import type { ControlFlowInformation } from '../../control-flow/control-flow-graph';
-import { CfgKind } from '../cfg-kind';
+import type { CfgKind } from '../cfg-kind';
+import type { FlowrAnalyzerContext } from '../context/flowr-analyzer-context';
 interface FlowrAnalyzerCacheOptions<Parser extends KnownParser> {
     parser: Parser;
-    config: FlowrConfigOptions;
-    request: RParseRequests;
+    context: FlowrAnalyzerContext;
     getId?: IdGenerator<NoInfo>;
-    overwriteFilePath?: string;
 }
 export type AnalyzerCacheType<Parser extends KnownParser> = Parser extends TreeSitterExecutor ? Partial<PipelineOutput<typeof TREE_SITTER_DATAFLOW_PIPELINE>> : Partial<PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>>;
 /**
@@ -37,14 +33,12 @@ export declare class FlowrAnalyzerCache<Parser extends KnownParser> extends Flow
     /**
      * Get the parse output for the request, parsing if necessary.
      * @param force - Do not use the cache, instead force a new parse.
-     *
      * @see {@link FlowrAnalyzerCache#peekParse} - to get the parse output if already available without triggering a new parse.
      */
     parse(force?: boolean): Promise<NonNullable<AnalyzerCacheType<Parser>['parse']>>;
     /**
      * Get the parse output for the request if already available, otherwise return `undefined`.
      * This will not trigger a new parse.
-     *
      * @see {@link FlowrAnalyzerCache#parse} - to get the parse output, parsing if necessary.
      */
     peekParse(): NonNullable<AnalyzerCacheType<Parser>['parse']> | undefined;
@@ -57,36 +51,32 @@ export declare class FlowrAnalyzerCache<Parser extends KnownParser> extends Flow
     /**
      * Get the normalized abstract syntax tree for the request if already available, otherwise return `undefined`.
      * This will not trigger a new normalization.
-     *
      * @see {@link FlowrAnalyzerCache#normalize} - to get the normalized AST, normalizing if necessary.
      */
     peekNormalize(): NonNullable<AnalyzerCacheType<Parser>['normalize']> | undefined;
     /**
      * Get the dataflow graph for the request, computing if necessary.
      * @param force - Do not use the cache, instead force new analyses.
-     *
      * @see {@link FlowrAnalyzerCache#peekDataflow} - to get the dataflow graph if already available without triggering a new computation.
      */
     dataflow(force?: boolean): Promise<NonNullable<AnalyzerCacheType<Parser>['dataflow']>>;
     /**
      * Get the dataflow graph for the request if already available, otherwise return `undefined`.
      * This will not trigger a new computation.
-     *
      * @see {@link FlowrAnalyzerCache#dataflow} - to get the dataflow graph, computing if necessary.
      */
     peekDataflow(): NonNullable<AnalyzerCacheType<Parser>['dataflow']> | undefined;
     /**
      * Get the control flow graph (CFG) for the request, computing if necessary.
-     * @param force - Do not use the cache, instead force new analyses.
-     * @param kind - The kind of CFG that is requested.
+     * @param force           - Do not use the cache, instead force new analyses.
+     * @param kind            - The kind of CFG that is requested.
      * @param simplifications - Simplification passes to be applied to the CFG.
      */
-    controlflow(force: boolean | undefined, kind: CfgKind, simplifications: readonly CfgSimplificationPassName[] | undefined): Promise<ControlFlowInformation>;
+    controlflow(force: boolean | undefined, kind: CfgKind, simplifications?: readonly CfgSimplificationPassName[]): Promise<ControlFlowInformation>;
     /**
      * Get the control flow graph (CFG) for the request if already available, otherwise return `undefined`.
-     * @param kind - The kind of CFG that is requested.
+     * @param kind            - The kind of CFG that is requested.
      * @param simplifications - Simplification passes to be applied to the CFG.
-     *
      * @see {@link FlowrAnalyzerCache#controlflow} - to get the control flow graph, computing if necessary.
      */
     peekControlflow(kind: CfgKind, simplifications: readonly CfgSimplificationPassName[] | undefined): ControlFlowInformation | undefined;

package/project/cache/flowr-analyzer-cache.js

@@ -4,9 +4,7 @@ exports.FlowrAnalyzerCache = void 0;
 const flowr_cache_1 = require("./flowr-cache");
 const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
 const assert_1 = require("../../util/assert");
-const objectmap_1 = require("../../util/collections/objectmap");
-const extract_cfg_1 = require("../../control-flow/extract-cfg");
-const cfg_kind_1 = require("../cfg-kind");
+const flowr_analyzer_controlflow_cache_1 = require("./flowr-analyzer-controlflow-cache");
 /**
  * This provides the full analyzer caching layer, please avoid using this directly
  * and prefer the {@link FlowrAnalyzer}.
@@ -22,13 +20,10 @@ class FlowrAnalyzerCache extends flowr_cache_1.FlowrCache {
     }
     initCacheProviders() {
         this.pipeline = (0, default_pipelines_1.createDataflowPipeline)(this.args.parser, {
-            request: this.args.request,
-            getId: this.args.getId,
-            overwriteFilePath: this.args.overwriteFilePath
-        }, this.args.config);
-        this.controlFlowCache = {
-            simplified: new objectmap_1.ObjectMap(),
-        };
+            context: this.args.context,
+            getId: this.args.getId
+        });
+        this.controlFlowCache = new flowr_analyzer_controlflow_cache_1.FlowrAnalyzerControlFlowCache();
     }
     static create(data) {
         return new FlowrAnalyzerCache(data);
@@ -51,7 +46,7 @@ class FlowrAnalyzerCache extends flowr_cache_1.FlowrCache {
         this.receive({ type: "full" /* CacheInvalidationEventType.Full */ });
     }
     async runTapeUntil(force, until) {
-        (0, assert_1.guard)(this.args.request && (Array.isArray(this.args.request) ? this.args.request.length > 0 : true), 'At least one request must be set to run the analysis pipeline');
+        (0, assert_1.guard)(this.args.context.files.loadingOrder.getUnorderedRequests().length > 0, 'At least one request must be set to run the analysis pipeline');
         if (force) {
             this.reset();
         }
@@ -65,7 +60,6 @@ class FlowrAnalyzerCache extends flowr_cache_1.FlowrCache {
     /**
      * Get the parse output for the request, parsing if necessary.
      * @param force - Do not use the cache, instead force a new parse.
-     *
      * @see {@link FlowrAnalyzerCache#peekParse} - to get the parse output if already available without triggering a new parse.
      */
     async parse(force) {
@@ -75,7 +69,6 @@ class FlowrAnalyzerCache extends flowr_cache_1.FlowrCache {
     /**
      * Get the parse output for the request if already available, otherwise return `undefined`.
      * This will not trigger a new parse.
-     *
      * @see {@link FlowrAnalyzerCache#parse} - to get the parse output, parsing if necessary.
      */
     peekParse() {
@@ -93,7 +86,6 @@ class FlowrAnalyzerCache extends flowr_cache_1.FlowrCache {
     /**
      * Get the normalized abstract syntax tree for the request if already available, otherwise return `undefined`.
      * This will not trigger a new normalization.
-     *
      * @see {@link FlowrAnalyzerCache#normalize} - to get the normalized AST, normalizing if necessary.
      */
     peekNormalize() {
@@ -102,7 +94,6 @@ class FlowrAnalyzerCache extends flowr_cache_1.FlowrCache {
     /**
      * Get the dataflow graph for the request, computing if necessary.
      * @param force - Do not use the cache, instead force new analyses.
-     *
      * @see {@link FlowrAnalyzerCache#peekDataflow} - to get the dataflow graph if already available without triggering a new computation.
      */
     async dataflow(force) {
@@ -112,7 +103,6 @@ class FlowrAnalyzerCache extends flowr_cache_1.FlowrCache {
     /**
      * Get the dataflow graph for the request if already available, otherwise return `undefined`.
      * This will not trigger a new computation.
-     *
      * @see {@link FlowrAnalyzerCache#dataflow} - to get the dataflow graph, computing if necessary.
      */
     peekDataflow() {
@@ -120,44 +110,27 @@ class FlowrAnalyzerCache extends flowr_cache_1.FlowrCache {
     }
     /**
      * Get the control flow graph (CFG) for the request, computing if necessary.
-     * @param force - Do not use the cache, instead force new analyses.
-     * @param kind - The kind of CFG that is requested.
+     * @param force           - Do not use the cache, instead force new analyses.
+     * @param kind            - The kind of CFG that is requested.
      * @param simplifications - Simplification passes to be applied to the CFG.
      */
     async controlflow(force, kind, simplifications) {
-        (0, assert_1.guard)(kind === cfg_kind_1.CfgKind.Quick ? simplifications === undefined : true, 'Cannot apply simplifications to quick CFG');
-        simplifications ??= [];
-        if (!force) {
-            const value = this.controlFlowCache.simplified.get([simplifications, kind]);
-            if (value !== undefined) {
-                return value;
-            }
-        }
-        const normalized = await this.normalize(force);
-        let result;
-        switch (kind) {
-            case cfg_kind_1.CfgKind.WithDataflow:
-                result = (0, extract_cfg_1.extractCfg)(normalized, this.args.config, (await this.dataflow()).graph, simplifications);
-                break;
-            case cfg_kind_1.CfgKind.NoDataflow:
-                result = (0, extract_cfg_1.extractCfg)(normalized, this.args.config, undefined, simplifications);
-                break;
-            case cfg_kind_1.CfgKind.Quick:
-                result = this.peekDataflow()?.cfgQuick ?? (0, extract_cfg_1.extractCfgQuick)(normalized);
-                break;
-        }
-        this.controlFlowCache.simplified.set([simplifications, kind], result);
-        return result;
+        const cfgInfo = {
+            ctx: this.args.context,
+            cfgQuick: this.peekDataflow()?.cfgQuick,
+            ast: async () => await this.normalize(),
+            dfg: async () => await this.dataflow()
+        };
+        return this.controlFlowCache.get(force, kind, cfgInfo, simplifications);
     }
     /**
      * Get the control flow graph (CFG) for the request if already available, otherwise return `undefined`.
-     * @param kind - The kind of CFG that is requested.
+     * @param kind            - The kind of CFG that is requested.
      * @param simplifications - Simplification passes to be applied to the CFG.
-     *
      * @see {@link FlowrAnalyzerCache#controlflow} - to get the control flow graph, computing if necessary.
      */
     peekControlflow(kind, simplifications) {
-        return this.controlFlowCache.simplified.get([simplifications ?? [], kind]);
+        return this.controlFlowCache.peek(kind, simplifications);
     }
 }
 exports.FlowrAnalyzerCache = FlowrAnalyzerCache;

package/project/cache/flowr-analyzer-controlflow-cache.d.ts

@@ -0,0 +1,34 @@
+import type { CfgSimplificationPassName } from '../../control-flow/cfg-simplification';
+import { CfgKind } from '../cfg-kind';
+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 { FlowrAnalyzerContext } from '../context/flowr-analyzer-context';
+interface CfgInfo {
+    ctx: FlowrAnalyzerContext;
+    cfgQuick: ControlFlowInformation | undefined;
+    dfg: () => Promise<DataflowInformation>;
+    ast: () => Promise<NormalizedAst>;
+}
+export declare class FlowrAnalyzerControlFlowCache {
+    private readonly cache;
+    peek(kind: CfgKind, simplifications: readonly CfgSimplificationPassName[] | undefined): ControlFlowInformation | undefined;
+    get(force: boolean | undefined, kind: CfgKind, cfgCacheInfo: CfgInfo, simplifications?: readonly CfgSimplificationPassName[]): Promise<ControlFlowInformation>;
+    /**
+     * Create and cache the base CFG without simplifications.
+     */
+    private createAndCacheBaseCfg;
+    /**
+     * Try to get a cached CFG with some of the requested simplifications already applied.
+     * Matches the longest prefix of simplifications available.
+     * @returns The cached CFG and the missing simplifications to be applied, or `undefined` if no cached CFG is available.
+     */
+    private tryGetCachedCfg;
+    /**
+     * Normalize the order of simplification passes.
+     * Is currently an identity function, but may be extended in the future to enforce a specific order using heuristics.
+     * @param simplifications - the requested simplification passes.
+     */
+    private normalizeSimplificationOrder;
+}
+export {};

package/project/cache/flowr-analyzer-controlflow-cache.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrAnalyzerControlFlowCache = void 0;
+const objectmap_1 = require("../../util/collections/objectmap");
+const cfg_simplification_1 = require("../../control-flow/cfg-simplification");
+const cfg_kind_1 = require("../cfg-kind");
+const assert_1 = require("../../util/assert");
+const extract_cfg_1 = require("../../control-flow/extract-cfg");
+class FlowrAnalyzerControlFlowCache {
+    cache = new objectmap_1.ObjectMap();
+    peek(kind, simplifications) {
+        return this.cache.get([simplifications ?? [], kind]);
+    }
+    async get(force, kind, cfgCacheInfo, simplifications) {
+        (0, assert_1.guard)(kind === cfg_kind_1.CfgKind.Quick ? simplifications === undefined : true, 'Cannot apply simplifications to quick CFG');
+        simplifications ??= [];
+        const orderedSimplifications = this.normalizeSimplificationOrder(simplifications);
+        const cached = force ?
+            { cfg: undefined, missingSimplifications: orderedSimplifications }
+            : this.tryGetCachedCfg(orderedSimplifications, kind);
+        let cfg = cached.cfg;
+        if (!cfg) {
+            cfg = await this.createAndCacheBaseCfg(kind, cfgCacheInfo);
+        }
+        if (cached.missingSimplifications.length > 0) {
+            const cfgPassInfo = { dfg: (await cfgCacheInfo.dfg()).graph, ctx: cfgCacheInfo.ctx, ast: await cfgCacheInfo.ast() };
+            cfg = (0, cfg_simplification_1.simplifyControlFlowInformation)(cfg, cfgPassInfo, cached.missingSimplifications);
+        }
+        this.cache.set([orderedSimplifications, kind], cfg);
+        return cfg;
+    }
+    /**
+     * Create and cache the base CFG without simplifications.
+     */
+    async createAndCacheBaseCfg(kind, { cfgQuick, dfg, ctx, ast }) {
+        let result;
+        switch (kind) {
+            case cfg_kind_1.CfgKind.WithDataflow:
+                result = (0, extract_cfg_1.extractCfg)(await ast(), ctx, (await dfg()).graph);
+                break;
+            case cfg_kind_1.CfgKind.NoDataflow:
+                result = (0, extract_cfg_1.extractCfg)(await ast(), ctx);
+                break;
+            case cfg_kind_1.CfgKind.Quick:
+                result = cfgQuick ?? (0, extract_cfg_1.extractCfgQuick)(await ast());
+                break;
+        }
+        this.cache.set([[], kind], result);
+        return result;
+    }
+    /**
+     * Try to get a cached CFG with some of the requested simplifications already applied.
+     * Matches the longest prefix of simplifications available.
+     * @returns The cached CFG and the missing simplifications to be applied, or `undefined` if no cached CFG is available.
+     */
+    tryGetCachedCfg(simplifications, kind) {
+        for (let prefixLen = simplifications.length; prefixLen >= 0; prefixLen--) {
+            const prefix = simplifications.slice(0, prefixLen);
+            const cached = this.cache.get([prefix, kind]);
+            if (cached !== undefined) {
+                return {
+                    cfg: cached,
+                    missingSimplifications: simplifications.slice(prefixLen)
+                };
+            }
+        }
+        return { cfg: undefined, missingSimplifications: simplifications };
+    }
+    /**
+     * Normalize the order of simplification passes.
+     * Is currently an identity function, but may be extended in the future to enforce a specific order using heuristics.
+     * @param simplifications - the requested simplification passes.
+     */
+    normalizeSimplificationOrder(simplifications) {
+        return simplifications;
+    }
+}
+exports.FlowrAnalyzerControlFlowCache = FlowrAnalyzerControlFlowCache;
+//# sourceMappingURL=flowr-analyzer-controlflow-cache.js.map

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

@@ -1,9 +1,9 @@
-import type { RAnalysisRequest, ReadOnlyFlowrAnalyzerFilesContext } from './flowr-analyzer-files-context';
-import { FlowrAnalyzerFilesContext } from './flowr-analyzer-files-context';
-import type { ReadOnlyFlowrAnalyzerDependenciesContext } from './flowr-analyzer-dependencies-context';
-import { FlowrAnalyzerDependenciesContext } from './flowr-analyzer-dependencies-context';
-import type { FlowrAnalyzerPlugin } from '../plugins/flowr-analyzer-plugin';
-import { PluginType } from '../plugins/flowr-analyzer-plugin';
+import { FlowrAnalyzerFilesContext, type RAnalysisRequest, type ReadOnlyFlowrAnalyzerFilesContext } from './flowr-analyzer-files-context';
+import { FlowrAnalyzerDependenciesContext, type ReadOnlyFlowrAnalyzerDependenciesContext } from './flowr-analyzer-dependencies-context';
+import { type FlowrAnalyzerPlugin, PluginType } from '../plugins/flowr-analyzer-plugin';
+import type { fileProtocol, RParseRequestFromFile, RParseRequests } from '../../r-bridge/retriever';
+import type { FlowrConfigOptions } from '../../config';
+import type { FlowrFileProvider } from './flowr-file';
 /**
  * This is a read-only interface to the {@link FlowrAnalyzerContext}.
  * It prevents you from modifying the context, but allows you to inspect it (which is probably what you want when using the {@link FlowrAnalyzer}).
@@ -18,6 +18,10 @@ export interface ReadOnlyFlowrAnalyzerContext {
      * The dependencies context provides access to the identified dependencies and their versions.
      */
     readonly deps: ReadOnlyFlowrAnalyzerDependenciesContext;
+    /**
+     * The configuration options used by the analyzer.
+     */
+    readonly config: FlowrConfigOptions;
 }
 /**
  * This summarizes the other context layers used by the {@link FlowrAnalyzer}.
@@ -34,11 +38,12 @@ export interface ReadOnlyFlowrAnalyzerContext {
 export declare class FlowrAnalyzerContext implements ReadOnlyFlowrAnalyzerContext {
     readonly files: FlowrAnalyzerFilesContext;
     readonly deps: FlowrAnalyzerDependenciesContext;
-    constructor(plugins: ReadonlyMap<PluginType, readonly FlowrAnalyzerPlugin[]>);
+    readonly config: FlowrConfigOptions;
+    constructor(config: FlowrConfigOptions, plugins: ReadonlyMap<PluginType, readonly FlowrAnalyzerPlugin[]>);
     /** delegate request addition */
     addRequests(requests: readonly RAnalysisRequest[]): void;
-    /** delegate request addition */
-    addRequest(request: RAnalysisRequest): void;
+    addFile(f: string | FlowrFileProvider | RParseRequestFromFile): void;
+    addFiles(f: (string | FlowrFileProvider | RParseRequestFromFile)[]): void;
     /** this conducts all the step that can be done before the main analysis run */
     resolvePreAnalysis(): void;
     /**
@@ -52,3 +57,20 @@ export declare class FlowrAnalyzerContext implements ReadOnlyFlowrAnalyzerContex
      */
     reset(): void;
 }
+/**
+ * Lifting {@link requestFromInput} to create a full {@link FlowrAnalyzerContext} from input requests.
+ * Please use this only for a "quick" setup, or to have compatibility with the pre-project flowR era.
+ * Otherwise, refer to a {@link FlowrAnalyzerBuilder} to create a fully customized {@link FlowrAnalyzer} instance.
+ * @see {@link requestFromInput} - for details on how inputs are processed into requests.
+ * @see {@link contextFromSources} - to create a context from source code strings directly.
+ */
+export declare function contextFromInput(input: `${typeof fileProtocol}${string}` | string | readonly string[] | RParseRequests, config?: FlowrConfigOptions, plugins?: FlowrAnalyzerPlugin[]): FlowrAnalyzerContext;
+/**
+ * Create a {@link FlowrAnalyzerContext} from a set of source code strings.
+ * @param sources - A record mapping file paths to their source code content.
+ * @param config  - Configuration options for the analyzer.
+ * @param plugins - Optional plugins to extend the analyzer's functionality.
+ * @see {@link contextFromInput}    - to create a context from input requests.
+ * @see {@link FlowrInlineTextFile} - to create inline text files for the sources.
+ */
+export declare function contextFromSources(sources: Record<string, string>, config?: FlowrConfigOptions, plugins?: FlowrAnalyzerPlugin[]): FlowrAnalyzerContext;

package/project/context/flowr-analyzer-context.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowrAnalyzerContext = void 0;
+exports.contextFromInput = contextFromInput;
+exports.contextFromSources = contextFromSources;
 const flowr_analyzer_files_context_1 = require("./flowr-analyzer-files-context");
 const flowr_analyzer_dependencies_context_1 = require("./flowr-analyzer-dependencies-context");
 const flowr_analyzer_plugin_1 = require("../plugins/flowr-analyzer-plugin");
 const flowr_analyzer_loading_order_context_1 = require("./flowr-analyzer-loading-order-context");
+const arrays_1 = require("../../util/collections/arrays");
+const retriever_1 = require("../../r-bridge/retriever");
+const config_1 = require("../../config");
+const flowr_file_1 = require("./flowr-file");
 /**
  * This summarizes the other context layers used by the {@link FlowrAnalyzer}.
  * Have a look at the attributes and layers listed below (e.g., {@link files} and {@link deps})
@@ -20,7 +26,9 @@ const flowr_analyzer_loading_order_context_1 = require("./flowr-analyzer-loading
 class FlowrAnalyzerContext {
     files;
     deps;
-    constructor(plugins) {
+    config;
+    constructor(config, plugins) {
+        this.config = config;
         const loadingOrder = new flowr_analyzer_loading_order_context_1.FlowrAnalyzerLoadingOrderContext(this, plugins.get(flowr_analyzer_plugin_1.PluginType.LoadingOrder));
         this.files = new flowr_analyzer_files_context_1.FlowrAnalyzerFilesContext(loadingOrder, (plugins.get(flowr_analyzer_plugin_1.PluginType.ProjectDiscovery) ?? []), (plugins.get(flowr_analyzer_plugin_1.PluginType.FileLoad) ?? []));
         this.deps = new flowr_analyzer_dependencies_context_1.FlowrAnalyzerDependenciesContext(this, (plugins.get(flowr_analyzer_plugin_1.PluginType.DependencyIdentification) ?? []));
@@ -29,9 +37,11 @@ class FlowrAnalyzerContext {
     addRequests(requests) {
         this.files.addRequests(requests);
     }
-    /** delegate request addition */
-    addRequest(request) {
-        this.files.addRequest(request);
+    addFile(f) {
+        this.files.addFile(f);
+    }
+    addFiles(f) {
+        this.files.addFiles(f);
     }
     /** this conducts all the step that can be done before the main analysis run */
     resolvePreAnalysis() {
@@ -55,4 +65,38 @@ class FlowrAnalyzerContext {
     }
 }
 exports.FlowrAnalyzerContext = FlowrAnalyzerContext;
+/**
+ * Lifting {@link requestFromInput} to create a full {@link FlowrAnalyzerContext} from input requests.
+ * Please use this only for a "quick" setup, or to have compatibility with the pre-project flowR era.
+ * Otherwise, refer to a {@link FlowrAnalyzerBuilder} to create a fully customized {@link FlowrAnalyzer} instance.
+ * @see {@link requestFromInput} - for details on how inputs are processed into requests.
+ * @see {@link contextFromSources} - to create a context from source code strings directly.
+ */
+function contextFromInput(input, config = config_1.defaultConfigOptions, plugins) {
+    const context = new FlowrAnalyzerContext(config, (0, arrays_1.arraysGroupBy)(plugins ?? [], (p) => p.type));
+    if (typeof input === 'string' || Array.isArray(input) && input.every(i => typeof i === 'string')) {
+        const requests = (0, retriever_1.requestFromInput)(input);
+        context.addRequests(Array.isArray(requests) ? requests : [requests]);
+    }
+    else {
+        const requests = Array.isArray(input) ? input : [input];
+        context.addRequests(requests);
+    }
+    return context;
+}
+/**
+ * Create a {@link FlowrAnalyzerContext} from a set of source code strings.
+ * @param sources - A record mapping file paths to their source code content.
+ * @param config  - Configuration options for the analyzer.
+ * @param plugins - Optional plugins to extend the analyzer's functionality.
+ * @see {@link contextFromInput}    - to create a context from input requests.
+ * @see {@link FlowrInlineTextFile} - to create inline text files for the sources.
+ */
+function contextFromSources(sources, config = config_1.defaultConfigOptions, plugins) {
+    const context = new FlowrAnalyzerContext(config, (0, arrays_1.arraysGroupBy)(plugins ?? [], (p) => p.type));
+    for (const [p, c] of Object.entries(sources)) {
+        context.addFile(new flowr_file_1.FlowrInlineTextFile(p, c));
+    }
+    return context;
+}
 //# sourceMappingURL=flowr-analyzer-context.js.map

package/project/context/flowr-analyzer-dependencies-context.d.ts

@@ -16,7 +16,6 @@ export interface ReadOnlyFlowrAnalyzerDependenciesContext {
      * Get the dependency with the given name, if it exists.
      *
      * If the static dependencies have not yet been loaded, this may trigger a resolution step.
-     *
      * @param name - The name of the dependency to get.
      * @returns The dependency with the given name, or undefined if it does not exist.
      */

package/project/context/flowr-analyzer-files-context.d.ts

@@ -1,10 +1,9 @@
 import { AbstractFlowrAnalyzerContext } from './abstract-flowr-analyzer-context';
-import type { RParseRequest, RParseRequestFromFile } from '../../r-bridge/retriever';
+import type { RParseRequestFromText, RParseRequest, RParseRequestFromFile } from '../../r-bridge/retriever';
 import type { FlowrAnalyzerLoadingOrderContext, ReadOnlyFlowrAnalyzerLoadingOrderContext } from './flowr-analyzer-loading-order-context';
 import { FlowrAnalyzerProjectDiscoveryPlugin } from '../plugins/project-discovery/flowr-analyzer-project-discovery-plugin';
 import { FlowrAnalyzerFilePlugin } from '../plugins/file-plugins/flowr-analyzer-file-plugin';
-import type { FlowrFile, FlowrFileProvider } from './flowr-file';
-import { SpecialFileRole } from './flowr-file';
+import { FlowrFile, type FlowrFileProvider, FileRole } from './flowr-file';
 import type { FlowrDescriptionFile } from '../plugins/file-plugins/flowr-description-file';
 /**
  * This is a request to process a folder as a project, which will be expanded by the registered {@link FlowrAnalyzerProjectDiscoveryPlugin}s.
@@ -17,11 +16,12 @@ export interface RProjectAnalysisRequest {
     readonly content: string;
 }
 export type RAnalysisRequest = RParseRequest | RProjectAnalysisRequest;
-export type SpecialFiles = {
-    [SpecialFileRole.Description]: FlowrDescriptionFile[];
-    [SpecialFileRole.Namespace]: FlowrFileProvider[];
-    [SpecialFileRole.Data]: FlowrFileProvider[];
-    [SpecialFileRole.Other]: FlowrFileProvider[];
+export type RoleBasedFiles = {
+    [FileRole.Description]: FlowrDescriptionFile[];
+    [FileRole.Namespace]: FlowrFileProvider[];
+    [FileRole.Source]: FlowrFileProvider[];
+    [FileRole.Data]: FlowrFileProvider[];
+    [FileRole.Other]: FlowrFileProvider[];
 };
 /**
  * This is the read-only interface for the files context, which is used to manage all files known to the {@link FlowrAnalyzer}.
@@ -39,13 +39,42 @@ export interface ReadOnlyFlowrAnalyzerFilesContext {
     readonly loadingOrder: ReadOnlyFlowrAnalyzerLoadingOrderContext;
     /**
      * Get all requests that have been added to this context.
-     *
      * @example If you want to obtain all description files, use
      * ```ts
      * getFilesByRole(SpecialFileRole.Description)
      * ```
      */
-    getFilesByRole<Role extends SpecialFileRole>(role: Role): SpecialFiles[Role];
+    getFilesByRole<Role extends FileRole>(role: Role): RoleBasedFiles[Role];
+    /**
+     * Check if the context has a file with the given path.
+     * Please note, that this may also check the file system, depending on the configuration
+     * (see {@link FlowrConfigOptions.project.resolveUnknownPathsOnDisk}).
+     * @param path - The path to the file.
+     *
+     * If you do not know the exact path or, e.g., casing of the file, use {@link exists} instead.
+     */
+    hasFile(path: string): boolean;
+    /**
+     * Check if a file exists at the given path, optionally ignoring case.
+     * @param path - The path to the file.
+     * @param ignoreCase - Whether to ignore case when checking for the file.
+     *
+     * Please note that this method checks the file system based on the configuration (see {@link FlowrConfigOptions.project.resolveUnknownPathsOnDisk}).
+     * @returns The actual path of the file if it exists, otherwise `undefined`.
+     */
+    exists(path: string, ignoreCase: boolean): string | undefined;
+    /**
+     * Until parsers support multiple request types from the virtual context system,
+     * we resolve their contents.
+     */
+    resolveRequest(r: RParseRequest): {
+        r: RParseRequestFromText;
+        path?: string;
+    };
+    /**
+     * Get all files that have been considered during dataflow analysis.
+     */
+    consideredFilesList(): readonly string[];
 }
 /**
  * This is the analyzer file context to be modified by all plugins that affect the files.
@@ -56,10 +85,21 @@ export declare class FlowrAnalyzerFilesContext extends AbstractFlowrAnalyzerCont
     readonly name = "flowr-analyzer-files-context";
     readonly loadingOrder: FlowrAnalyzerLoadingOrderContext;
     private files;
+    private inlineFiles;
     private readonly fileLoaders;
-    private specialFiles;
+    /** these are all the paths of files that have been considered by the dataflow graph (even if not added) */
+    private readonly consideredFiles;
+    private byRole;
     constructor(loadingOrder: FlowrAnalyzerLoadingOrderContext, plugins: readonly FlowrAnalyzerProjectDiscoveryPlugin[], fileLoaders: readonly FlowrAnalyzerFilePlugin[]);
     reset(): void;
+    /**
+     * Record that a file has been considered during dataflow analysis.
+     */
+    addConsideredFile(path: string): void;
+    /**
+     * Get all files that have been considered during dataflow analysis.
+     */
+    consideredFilesList(): readonly string[];
     /**
      * Add multiple requests to the context. This is just a convenience method that calls {@link addRequest} for each request.
      */
@@ -67,21 +107,29 @@ export declare class FlowrAnalyzerFilesContext extends AbstractFlowrAnalyzerCont
     /**
      * Add a request to the context. If the request is of type `project`, it will be expanded using the registered {@link FlowrAnalyzerProjectDiscoveryPlugin}s.
      */
-    addRequest(request: RAnalysisRequest): void;
+    private addRequest;
     /**
      * Add multiple files to the context. This is just a convenience method that calls {@link addFile} for each file.
      */
-    addFiles(...files: (string | FlowrFileProvider<string> | RParseRequestFromFile)[]): void;
+    addFiles(files: (string | FlowrFileProvider | RParseRequestFromFile)[]): void;
     /**
      * Add a file to the context. If the file has a special role, it will be added to the corresponding list of special files.
      * This method also applies any registered {@link FlowrAnalyzerFilePlugin}s to the file before adding it to the context.
      */
-    addFile(file: string | FlowrFileProvider<string> | RParseRequestFromFile, role?: SpecialFileRole): void;
+    addFile(file: string | FlowrFileProvider | RParseRequestFromFile, role?: FileRole): FlowrFileProvider<{
+        toString(): string;
+    }>;
+    hasFile(path: string): boolean;
+    exists(p: string, ignoreCase: boolean): string | undefined;
     private fileLoadPlugins;
+    resolveRequest(r: RParseRequest): {
+        r: RParseRequestFromText;
+        path?: string;
+    };
     /**
      * Get all requests that have been added to this context.
      * This is a convenience method that calls {@link FlowrAnalyzerLoadingOrderContext.getLoadingOrder}.
      */
     computeLoadingOrder(): readonly RParseRequest[];
-    getFilesByRole<Role extends SpecialFileRole>(role: Role): SpecialFiles[Role];
+    getFilesByRole<Role extends FileRole>(role: Role): RoleBasedFiles[Role];
 }