@eagleoutice/flowr 2.5.0 → 2.6.0

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

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrAnalyzerContext = void 0;
+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");
+/**
+ * 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})
+ * to get an idea of the capabilities provided by this context.
+ * Besides these, this layer only orchestrates the different steps and layers, providing a collection of convenience methods alongside the
+ * {@link resolvePreAnalysis} method that conducts all the steps that can be done before the main analysis run.
+ * In general, you do not have to worry about these details, as the {@link FlowrAnalyzerBuilder} and {@link FlowrAnalyzer} take care of them.
+ *
+ * To inspect, e.g., the loading order, you can do so via {@link files.loadingOrder.getLoadingOrder}. To get information on a specific library, use
+ * {@link deps.getDependency}.
+ * If you are just interested in inspecting the context, you can use {@link ReadOnlyFlowrAnalyzerContext} instead (e.g., via {@link inspect}).
+ */
+class FlowrAnalyzerContext {
+    files;
+    deps;
+    constructor(plugins) {
+        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) ?? []));
+    }
+    /** delegate request addition */
+    addRequests(requests) {
+        this.files.addRequests(requests);
+    }
+    /** this conducts all the step that can be done before the main analysis run */
+    resolvePreAnalysis() {
+        this.files.computeLoadingOrder();
+        this.deps.resolveStaticDependencies();
+    }
+    /**
+     * Get a read-only version of this context.
+     * This is useful if you want to pass the context to a place where you do not want it to be modified or just to reduce
+     * the available methods.
+     */
+    inspect() {
+        return this;
+    }
+}
+exports.FlowrAnalyzerContext = FlowrAnalyzerContext;
+//# sourceMappingURL=flowr-analyzer-context.js.map

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

@@ -0,0 +1,38 @@
+import { AbstractFlowrAnalyzerContext } from './abstract-flowr-analyzer-context';
+import { FlowrAnalyzerPackageVersionsPlugin } from '../plugins/package-version-plugins/flowr-analyzer-package-versions-plugin';
+import type { Package } from '../plugins/package-version-plugins/package';
+import type { FlowrAnalyzerContext } from './flowr-analyzer-context';
+/**
+ * This is a read-only interface to the {@link FlowrAnalyzerDependenciesContext}.
+ * It prevents you from modifying the dependencies, but allows you to inspect them (which is probably what you want when using the {@link FlowrAnalyzer}).
+ * If you are a {@link FlowrAnalyzerPackageVersionsPlugin} and want to modify the dependencies, you can use the {@link FlowrAnalyzerDependenciesContext} directly.
+ */
+export interface ReadOnlyFlowrAnalyzerDependenciesContext {
+    /**
+     * The name of this context.
+     */
+    readonly name: string;
+    /**
+     * 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.
+     */
+    getDependency(name: string): Package | undefined;
+}
+/**
+ * This context is responsible for managing the dependencies of the project, including their versions and interplays with {@link FlowrAnalyzerPackageVersionsPlugin}s.
+ *
+ * If you are interested in inspecting these dependencies, refer to {@link ReadOnlyFlowrAnalyzerDependenciesContext}.
+ */
+export declare class FlowrAnalyzerDependenciesContext extends AbstractFlowrAnalyzerContext<undefined, void, FlowrAnalyzerPackageVersionsPlugin> implements ReadOnlyFlowrAnalyzerDependenciesContext {
+    readonly name = "flowr-analyzer-dependencies-context";
+    private dependencies;
+    private staticsLoaded;
+    constructor(ctx: FlowrAnalyzerContext, plugins?: readonly FlowrAnalyzerPackageVersionsPlugin[]);
+    resolveStaticDependencies(): void;
+    addDependency(pkg: Package): void;
+    getDependency(name: string): Package | undefined;
+}

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

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrAnalyzerDependenciesContext = void 0;
+const abstract_flowr_analyzer_context_1 = require("./abstract-flowr-analyzer-context");
+const flowr_analyzer_package_versions_plugin_1 = require("../plugins/package-version-plugins/flowr-analyzer-package-versions-plugin");
+/**
+ * This context is responsible for managing the dependencies of the project, including their versions and interplays with {@link FlowrAnalyzerPackageVersionsPlugin}s.
+ *
+ * If you are interested in inspecting these dependencies, refer to {@link ReadOnlyFlowrAnalyzerDependenciesContext}.
+ */
+class FlowrAnalyzerDependenciesContext extends abstract_flowr_analyzer_context_1.AbstractFlowrAnalyzerContext {
+    name = 'flowr-analyzer-dependencies-context';
+    dependencies = new Map();
+    staticsLoaded = false;
+    constructor(ctx, plugins) {
+        super(ctx, flowr_analyzer_package_versions_plugin_1.FlowrAnalyzerPackageVersionsPlugin.defaultPlugin(), plugins);
+    }
+    resolveStaticDependencies() {
+        this.applyPlugins(undefined);
+        this.staticsLoaded = true;
+    }
+    addDependency(pkg) {
+        const p = this.dependencies.get(pkg.name);
+        if (p) {
+            p.mergeInPlace(pkg);
+        }
+        else {
+            this.dependencies.set(pkg.name, pkg);
+        }
+    }
+    getDependency(name) {
+        if (!this.staticsLoaded) {
+            this.resolveStaticDependencies();
+        }
+        return this.dependencies.get(name);
+    }
+}
+exports.FlowrAnalyzerDependenciesContext = FlowrAnalyzerDependenciesContext;
+//# sourceMappingURL=flowr-analyzer-dependencies-context.js.map

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

@@ -0,0 +1,86 @@
+import { AbstractFlowrAnalyzerContext } from './abstract-flowr-analyzer-context';
+import type { 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 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.
+ */
+export interface RProjectAnalysisRequest {
+    readonly request: 'project';
+    /**
+     * The path to the root folder (an absolute path is probably best here).
+     */
+    readonly content: string;
+}
+export type RAnalysisRequest = RParseRequest | RProjectAnalysisRequest;
+export type SpecialFiles = {
+    [SpecialFileRole.Description]: FlowrDescriptionFile[];
+    [SpecialFileRole.Namespace]: FlowrFileProvider[];
+    [SpecialFileRole.Data]: FlowrFileProvider[];
+    [SpecialFileRole.Other]: FlowrFileProvider[];
+};
+/**
+ * This is the read-only interface for the files context, which is used to manage all files known to the {@link FlowrAnalyzer}.
+ * It prevents you from modifying the available files, but allows you to inspect them (which is probably what you want when using the {@link FlowrAnalyzer}).
+ * If you are a {@link FlowrAnalyzerProjectDiscoveryPlugin} and want to modify the available files, you can use the {@link FlowrAnalyzerFilesContext} directly.
+ */
+export interface ReadOnlyFlowrAnalyzerFilesContext {
+    /**
+     * The name of this context.
+     */
+    readonly name: string;
+    /**
+     * The loading order context provides access to the loading order of script files in the project.
+     */
+    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];
+}
+/**
+ * This is the analyzer file context to be modified by all plugins that affect the files.
+ * If you are interested in inspecting these files, refer to {@link ReadOnlyFlowrAnalyzerFilesContext}.
+ * Plugins, however, can use this context directly to modify files.
+ */
+export declare class FlowrAnalyzerFilesContext extends AbstractFlowrAnalyzerContext<RProjectAnalysisRequest, (RParseRequest | FlowrFile<string>)[], FlowrAnalyzerProjectDiscoveryPlugin> implements ReadOnlyFlowrAnalyzerFilesContext {
+    readonly name = "flowr-analyzer-files-context";
+    readonly loadingOrder: FlowrAnalyzerLoadingOrderContext;
+    private files;
+    private readonly fileLoaders;
+    private specialFiles;
+    constructor(loadingOrder: FlowrAnalyzerLoadingOrderContext, plugins: readonly FlowrAnalyzerProjectDiscoveryPlugin[], fileLoaders: readonly FlowrAnalyzerFilePlugin[]);
+    /**
+     * Add multiple requests to the context. This is just a convenience method that calls {@link addRequest} for each request.
+     */
+    addRequests(requests: readonly RAnalysisRequest[]): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    private fileLoadPlugins;
+    /**
+     * 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];
+}

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

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrAnalyzerFilesContext = void 0;
+const abstract_flowr_analyzer_context_1 = require("./abstract-flowr-analyzer-context");
+const retriever_1 = require("../../r-bridge/retriever");
+const assert_1 = require("../../util/assert");
+const flowr_analyzer_project_discovery_plugin_1 = require("../plugins/project-discovery/flowr-analyzer-project-discovery-plugin");
+const flowr_analyzer_file_plugin_1 = require("../plugins/file-plugins/flowr-analyzer-file-plugin");
+const flowr_file_1 = require("./flowr-file");
+const log_1 = require("../../util/log");
+const fileLog = log_1.log.getSubLogger({ name: 'flowr-analyzer-files-context' });
+function obtainFileAndPath(file, role) {
+    let f;
+    let p;
+    if (typeof file === 'string') {
+        f = new flowr_file_1.FlowrTextFile(file, role);
+        p = file;
+    }
+    else if ('request' in file) {
+        f = file;
+        p = file.content;
+    }
+    else {
+        f = file;
+        p = file.path().toString();
+    }
+    return { f, p };
+}
+/**
+ * This is the analyzer file context to be modified by all plugins that affect the files.
+ * If you are interested in inspecting these files, refer to {@link ReadOnlyFlowrAnalyzerFilesContext}.
+ * Plugins, however, can use this context directly to modify files.
+ */
+class FlowrAnalyzerFilesContext extends abstract_flowr_analyzer_context_1.AbstractFlowrAnalyzerContext {
+    name = 'flowr-analyzer-files-context';
+    loadingOrder;
+    /* all project files etc., this contains *all* files, loading orders etc. are to be handled by plugins */
+    files = new Map();
+    fileLoaders;
+    /* files that are part of the analysis, e.g. source files */
+    specialFiles = {
+        [flowr_file_1.SpecialFileRole.Description]: [],
+        [flowr_file_1.SpecialFileRole.Namespace]: [],
+        [flowr_file_1.SpecialFileRole.Data]: [],
+        [flowr_file_1.SpecialFileRole.Other]: []
+    };
+    constructor(loadingOrder, plugins, fileLoaders) {
+        super(loadingOrder.getAttachedContext(), flowr_analyzer_project_discovery_plugin_1.FlowrAnalyzerProjectDiscoveryPlugin.defaultPlugin(), plugins);
+        this.fileLoaders = [...fileLoaders, flowr_analyzer_file_plugin_1.FlowrAnalyzerFilePlugin.defaultPlugin()];
+        this.loadingOrder = loadingOrder;
+    }
+    /**
+     * Add multiple requests to the context. This is just a convenience method that calls {@link addRequest} for each request.
+     */
+    addRequests(requests) {
+        for (const request of requests) {
+            this.addRequest(request);
+        }
+    }
+    /**
+     * 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) {
+        if (request.request !== 'project') {
+            this.loadingOrder.addRequest(request);
+            if (request.request === 'file') {
+                this.files.set(request.content, request);
+            }
+            return;
+        }
+        const expandedRequests = this.applyPlugins(request).flat();
+        for (const req of expandedRequests) {
+            if ((0, retriever_1.isParseRequest)(req)) {
+                this.addRequest(req);
+            }
+            else {
+                this.addFile(req, req.role);
+            }
+        }
+    }
+    /**
+     * Add multiple files to the context. This is just a convenience method that calls {@link addFile} for each file.
+     */
+    addFiles(...files) {
+        for (const file of files) {
+            this.addFile(file);
+        }
+    }
+    /**
+     * 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, role) {
+        const { f, p } = obtainFileAndPath(file, role);
+        const { f: fA, p: pA } = this.fileLoadPlugins(f, p);
+        const exist = this.files.get(pA);
+        (0, assert_1.guard)(exist === undefined || exist === fA, `File ${pA} already added to the context.`);
+        this.files.set(pA, fA);
+        if (!(0, retriever_1.isParseRequest)(fA) && fA.role) {
+            this.specialFiles[fA.role].push(fA);
+        }
+    }
+    fileLoadPlugins(f, p) {
+        let fFinal = f;
+        let pFinal = p;
+        if (!(0, retriever_1.isParseRequest)(f)) { // we have to change the types when we integrate the adapters
+            for (const loader of this.fileLoaders) {
+                if (loader.applies(p)) {
+                    fileLog.debug(`Applying file loader ${loader.name} to file ${p}`);
+                    fFinal = loader.processor(this.ctx, f);
+                    pFinal = f.path().toString();
+                    break;
+                }
+            }
+        }
+        return { f: fFinal, p: pFinal };
+    }
+    /**
+     * Get all requests that have been added to this context.
+     * This is a convenience method that calls {@link FlowrAnalyzerLoadingOrderContext.getLoadingOrder}.
+     */
+    computeLoadingOrder() {
+        return this.loadingOrder.getLoadingOrder();
+    }
+    getFilesByRole(role) {
+        return this.specialFiles[role];
+    }
+}
+exports.FlowrAnalyzerFilesContext = FlowrAnalyzerFilesContext;
+//# sourceMappingURL=flowr-analyzer-files-context.js.map

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

@@ -0,0 +1,76 @@
+import { AbstractFlowrAnalyzerContext } from './abstract-flowr-analyzer-context';
+import type { RParseRequest } from '../../r-bridge/retriever';
+import { FlowrAnalyzerLoadingOrderPlugin } from '../plugins/loading-order-plugins/flowr-analyzer-loading-order-plugin';
+import type { FlowrAnalyzerContext } from './flowr-analyzer-context';
+/**
+ * Read-only interface for the loading order context, which is used to determine the order in which script files are loaded in a project.
+ *
+ * This interface prevents you from modifying the available files, but allows you to inspect them (which is probably what you want when using the {@link FlowrAnalyzer}).
+ * If you are a {@link FlowrAnalyzerLoadingOrderPlugin} and want to modify the available orders, you can use the {@link FlowrAnalyzerLoadingOrderContext} directly.
+ */
+export interface ReadOnlyFlowrAnalyzerLoadingOrderContext {
+    /**
+     * The name of this context.
+     */
+    readonly name: string;
+    /**
+     * Peek whether we have a loading order known or guessed, this does not trigger any plugin runs.
+     * If you want to get the current loading order, including potential recompoutations, use {@link getLoadingOrder} instead.
+     */
+    peekLoadingOrder(): readonly RParseRequest[] | undefined;
+    /**
+     * Get the current loading order of requests, potentially triggering a re-computation if new requests have been added since the last computation.
+     */
+    getLoadingOrder(): readonly RParseRequest[];
+    /**
+     * Get all requests that have been added to this context, but for which no loading order is known or guessed.
+     */
+    getUnorderedRequests(): readonly RParseRequest[];
+    /**
+     * Get the current guesses for the loading order, if any. These are populated by {@link FlowrAnalyzerLoadingOrderPlugin}s.
+     */
+    currentGuesses(): readonly RParseRequest[][];
+    /**
+     * Get the current known loading order, if any. This is populated by {@link FlowrAnalyzerLoadingOrderPlugin}s if they have a source of identifying the order definitively.
+     */
+    currentKnownOrder(): readonly RParseRequest[] | undefined;
+}
+/**
+ * This context is responsible for managing the loading order of script files in a project, including guesses and known orders provided by {@link FlowrAnalyzerLoadingOrderPlugin}s.
+ *
+ * If you are interested in inspecting these orders, refer to {@link ReadOnlyFlowrAnalyzerLoadingOrderContext}.
+ * Plugins, however, can use this context directly to modify order guesses.
+ */
+export declare class FlowrAnalyzerLoadingOrderContext extends AbstractFlowrAnalyzerContext<undefined, void, FlowrAnalyzerLoadingOrderPlugin> implements ReadOnlyFlowrAnalyzerLoadingOrderContext {
+    readonly name = "flowr-analyzer-loading-order-context";
+    private rerunRequired;
+    constructor(ctx: FlowrAnalyzerContext, plugins: readonly FlowrAnalyzerLoadingOrderPlugin[] | undefined);
+    private knownOrder?;
+    private guesses;
+    /** just the base collection of requests we know nothing about the order! */
+    private unordered;
+    /**
+     * Add one or multiple requests to the context.
+     * These are considered unordered (i.e., ordered implicitly by the order of addition) until a plugin provides either a guess or a known order.
+     *
+     * This is a batched version of {@link addRequest}.
+     */
+    addRequests(requests: readonly RParseRequest[]): void;
+    /**
+     * Add a single request to the context.
+     * This is considered unordered (i.e., ordered implicitly by the order of addition) until a plugin provides either a guess or a known order.
+     *
+     * If you want to add multiple requests, consider using {@link addRequests} instead for efficiency.
+     */
+    addRequest(request: RParseRequest): void;
+    /**
+     * Add a guess for the loading order. This is mostly for plugins to use.
+     * In case you have a certain order, use the `certain` flag to indicate this -- but please take care of *really* being certain!
+     */
+    addGuess(guess: readonly RParseRequest[], certain?: boolean): void;
+    currentGuesses(): readonly RParseRequest[][];
+    currentKnownOrder(): readonly RParseRequest[] | undefined;
+    peekLoadingOrder(): readonly RParseRequest[] | undefined;
+    getUnorderedRequests(): readonly RParseRequest[];
+    getLoadingOrder(): readonly RParseRequest[];
+}

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

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrAnalyzerLoadingOrderContext = void 0;
+const abstract_flowr_analyzer_context_1 = require("./abstract-flowr-analyzer-context");
+const log_1 = require("../../util/log");
+const arrays_1 = require("../../util/collections/arrays");
+const flowr_analyzer_loading_order_plugin_1 = require("../plugins/loading-order-plugins/flowr-analyzer-loading-order-plugin");
+const loadingOrderLog = log_1.log.getSubLogger({ name: 'loading-order' });
+/**
+ * This context is responsible for managing the loading order of script files in a project, including guesses and known orders provided by {@link FlowrAnalyzerLoadingOrderPlugin}s.
+ *
+ * If you are interested in inspecting these orders, refer to {@link ReadOnlyFlowrAnalyzerLoadingOrderContext}.
+ * Plugins, however, can use this context directly to modify order guesses.
+ */
+class FlowrAnalyzerLoadingOrderContext extends abstract_flowr_analyzer_context_1.AbstractFlowrAnalyzerContext {
+    name = 'flowr-analyzer-loading-order-context';
+    rerunRequired;
+    constructor(ctx, plugins) {
+        super(ctx, flowr_analyzer_loading_order_plugin_1.FlowrAnalyzerLoadingOrderPlugin.defaultPlugin(), plugins);
+        this.rerunRequired = this.plugins.length > 0;
+    }
+    knownOrder;
+    guesses = [];
+    /** just the base collection of requests we know nothing about the order! */
+    unordered = [];
+    /**
+     * Add one or multiple requests to the context.
+     * These are considered unordered (i.e., ordered implicitly by the order of addition) until a plugin provides either a guess or a known order.
+     *
+     * This is a batched version of {@link addRequest}.
+     */
+    addRequests(requests) {
+        this.unordered.push(...requests);
+        if (this.knownOrder || this.guesses.length > 0) {
+            loadingOrderLog.warn(`Adding requests ${requests.map(r => r.request).join(', ')} after known order!`);
+            this.rerunRequired = true;
+        }
+    }
+    /**
+     * Add a single request to the context.
+     * This is considered unordered (i.e., ordered implicitly by the order of addition) until a plugin provides either a guess or a known order.
+     *
+     * If you want to add multiple requests, consider using {@link addRequests} instead for efficiency.
+     */
+    addRequest(request) {
+        this.unordered.push(request);
+        if (this.knownOrder || this.guesses.length > 0) {
+            loadingOrderLog.warn(`Adding request ${request.request} ${request.content} after known order!`);
+            this.rerunRequired = true;
+        }
+    }
+    /**
+     * Add a guess for the loading order. This is mostly for plugins to use.
+     * In case you have a certain order, use the `certain` flag to indicate this -- but please take care of *really* being certain!
+     */
+    addGuess(guess, certain) {
+        if (certain) {
+            if (this.knownOrder) {
+                loadingOrderLog.warn(`Adding certain guess ${guess.map(g => g.request).join(', ')} after known order!`);
+                if (!(0, arrays_1.arrayEqual)(this.knownOrder, guess)) {
+                    loadingOrderLog.error(`Certain guess ${guess.map(g => g.request).join(', ')} does not match known order ${this.knownOrder.map(g => g.request).join(', ')}`);
+                }
+            }
+            else {
+                this.knownOrder = guess;
+            }
+        }
+    }
+    currentGuesses() {
+        return this.guesses;
+    }
+    currentKnownOrder() {
+        return this.knownOrder;
+    }
+    peekLoadingOrder() {
+        return this.knownOrder ?? (this.guesses.length > 0 ? this.guesses[0] : undefined);
+    }
+    getUnorderedRequests() {
+        return this.unordered;
+    }
+    getLoadingOrder() {
+        if (this.rerunRequired) {
+            this.rerunRequired = false;
+            this.applyPlugins(undefined);
+        }
+        return this.peekLoadingOrder() ?? this.unordered;
+    }
+}
+exports.FlowrAnalyzerLoadingOrderContext = FlowrAnalyzerLoadingOrderContext;
+//# sourceMappingURL=flowr-analyzer-loading-order-context.js.map

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

@@ -0,0 +1,89 @@
+import type { PathLike } from 'fs';
+/**
+ * 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.
+ */
+export type FilePath = string;
+/**
+ * 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.
+ */
+export declare enum SpecialFileRole {
+    /** 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",
+    /** Other special files that are not specifically supported by flowR but may be interesting for some analyses. */
+    Other = "other"
+}
+/**
+ * This is the basic interface for all files known to the FlowrAnalyzer.
+ * You can implement this interface to provide custom file loading mechanisms.
+ * Mostly, we will be interested in text files (or decorations thereof).
+ * If you want to load other file types, you either have to transform them into a presentation supported by flowR
+ * or add your own file loader plugin (similar to the {@link FlowrAnalyzerDescriptionFilePlugin}).
+ *
+ * See {@link FlowrFile} for a basic single-cache implementation and {@link FlowrTextFile} for a text-file specific implementation.
+ * 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> {
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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.
+     * So make sure your implementation closes the resource as soon as possible.
+     */
+    content(): Content;
+    /**
+     * 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;
+}
+/**
+ * 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> {
+    private contentCache;
+    protected filePath: PathLike;
+    readonly role?: SpecialFileRole;
+    constructor(filePath: PathLike, role?: SpecialFileRole);
+    path(): PathLike;
+    content(): Content;
+    protected abstract loadContent(): Content;
+    assignRole(role: SpecialFileRole): void;
+}
+/**
+ * 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).
+ */
+export declare class FlowrTextFile extends FlowrFile<string> {
+    protected loadContent(): string;
+}
+/**
+ * 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).
+ */
+export declare class FlowrInlineTextFile extends FlowrFile<string> {
+    private readonly contentStr;
+    constructor(path: PathLike, content: string);
+    protected loadContent(): string;
+}