@eagleoutice/flowr 2.6.1 → 2.6.3

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

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowrAnalyzerFilesContext = void 0;
 const abstract_flowr_analyzer_context_1 = require("./abstract-flowr-analyzer-context");
@@ -8,23 +11,19 @@ const flowr_analyzer_project_discovery_plugin_1 = require("../plugins/project-di
 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 fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const fileLog = log_1.log.getSubLogger({ name: 'flowr-analyzer-files-context' });
-function obtainFileAndPath(file, role) {
-    let f;
-    let p;
+function wrapFile(file, role) {
     if (typeof file === 'string') {
-        f = new flowr_file_1.FlowrTextFile(file, role);
-        p = file;
+        return new flowr_file_1.FlowrTextFile(file, role);
     }
     else if ('request' in file) {
-        f = file;
-        p = file.content;
+        return flowr_file_1.FlowrFile.fromRequest(file);
     }
     else {
-        f = file;
-        p = file.path().toString();
+        return file;
     }
-    return { f, p };
 }
 /**
  * This is the analyzer file context to be modified by all plugins that affect the files.
@@ -34,15 +33,19 @@ function obtainFileAndPath(file, role) {
 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 */
+    /* all project files etc., this contains *all* (non-inline) files, loading orders etc. are to be handled by plugins */
     files = new Map();
+    inlineFiles = [];
     fileLoaders;
+    /** these are all the paths of files that have been considered by the dataflow graph (even if not added) */
+    consideredFiles = [];
     /* 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]: []
+    byRole = {
+        [flowr_file_1.FileRole.Description]: [],
+        [flowr_file_1.FileRole.Namespace]: [],
+        [flowr_file_1.FileRole.Source]: [],
+        [flowr_file_1.FileRole.Data]: [],
+        [flowr_file_1.FileRole.Other]: []
     };
     constructor(loadingOrder, plugins, fileLoaders) {
         super(loadingOrder.getAttachedContext(), flowr_analyzer_project_discovery_plugin_1.FlowrAnalyzerProjectDiscoveryPlugin.defaultPlugin(), plugins);
@@ -53,6 +56,18 @@ class FlowrAnalyzerFilesContext extends abstract_flowr_analyzer_context_1.Abstra
         this.loadingOrder.reset();
         this.files = new Map();
     }
+    /**
+     * Record that a file has been considered during dataflow analysis.
+     */
+    addConsideredFile(path) {
+        this.consideredFiles.push(path);
+    }
+    /**
+     * Get all files that have been considered during dataflow analysis.
+     */
+    consideredFilesList() {
+        return this.consideredFiles;
+    }
     /**
      * Add multiple requests to the context. This is just a convenience method that calls {@link addRequest} for each request.
      */
@@ -67,9 +82,6 @@ class FlowrAnalyzerFilesContext extends abstract_flowr_analyzer_context_1.Abstra
     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();
@@ -85,7 +97,7 @@ class FlowrAnalyzerFilesContext extends abstract_flowr_analyzer_context_1.Abstra
     /**
      * Add multiple files to the context. This is just a convenience method that calls {@link addFile} for each file.
      */
-    addFiles(...files) {
+    addFiles(files) {
         for (const file of files) {
             this.addFile(file);
         }
@@ -95,29 +107,88 @@ class FlowrAnalyzerFilesContext extends abstract_flowr_analyzer_context_1.Abstra
      * 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);
+        const f = this.fileLoadPlugins(wrapFile(file, role));
+        if (f.path() === flowr_file_1.FlowrFile.INLINE_PATH) {
+            this.inlineFiles.push(f);
+        }
+        else {
+            const exist = this.files.get(f.path());
+            (0, assert_1.guard)(exist === undefined || exist === f, `File ${f.path()} already added to the context.`);
+            this.files.set(f.path(), f);
+        }
+        if (f.role) {
+            this.byRole[f.role].push(f);
+        }
+        return f;
+    }
+    hasFile(path) {
+        return this.files.has(path)
+            || (this.ctx.config.project.resolveUnknownPathsOnDisk && fs_1.default.existsSync(path));
+    }
+    exists(p, ignoreCase) {
+        try {
+            if (!ignoreCase) {
+                return this.hasFile(p) ? p : undefined;
+            }
+            // walk the directory and find the first match
+            const dir = path_1.default.dirname(p);
+            const file = path_1.default.basename(p);
+            // try to find in local known files first
+            const localFound = Array.from(this.files.keys()).find(f => {
+                return path_1.default.dirname(f) === dir && path_1.default.basename(f).toLowerCase() === file.toLowerCase();
+            });
+            if (localFound) {
+                return localFound;
+            }
+            if (this.ctx.config.project.resolveUnknownPathsOnDisk) {
+                const files = fs_1.default.readdirSync(dir);
+                const found = files.find(f => f.toLowerCase() === file.toLowerCase());
+                return found ? path_1.default.join(dir, found) : undefined;
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
         }
     }
-    fileLoadPlugins(f, p) {
+    fileLoadPlugins(f) {
         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;
-                }
+        for (const loader of this.fileLoaders) {
+            if (loader.applies(f.path())) {
+                fileLog.debug(`Applying file loader ${loader.name} to file ${f.path()}`);
+                fFinal = loader.processor(this.ctx, f);
+                break;
+            }
+        }
+        return fFinal;
+    }
+    resolveRequest(r) {
+        if (r.request === 'text') {
+            return { r };
+        }
+        const file = this.files.get(r.content);
+        if (file === undefined && this.ctx.config.project.resolveUnknownPathsOnDisk) {
+            fileLog.debug(`File ${r.content} not found in context, trying to load from disk.`);
+            if (fs_1.default.existsSync(r.content)) {
+                const loadedFile = this.addFile(new flowr_file_1.FlowrTextFile(r.content));
+                return {
+                    r: {
+                        request: 'text',
+                        content: loadedFile.content().toString(),
+                    },
+                    path: loadedFile.path()
+                };
             }
         }
-        return { f: fFinal, p: pFinal };
+        (0, assert_1.guard)(file !== undefined && file !== null, `File ${r.content} not found in context.`);
+        const content = file.content();
+        return {
+            r: {
+                request: 'text',
+                content: typeof content === 'string' ? content : '',
+            },
+            path: file.path()
+        };
     }
     /**
      * Get all requests that have been added to this context.
@@ -127,7 +198,7 @@ class FlowrAnalyzerFilesContext extends abstract_flowr_analyzer_context_1.Abstra
         return this.loadingOrder.getLoadingOrder();
     }
     getFilesByRole(role) {
-        return this.specialFiles[role];
+        return this.byRole[role];
     }
 }
 exports.FlowrAnalyzerFilesContext = FlowrAnalyzerFilesContext;

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.
@@ -28,22 +39,25 @@ export declare enum SpecialFileRole {
  *
  * 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> {
+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.
@@ -54,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,24 +1,23 @@
-import type { EngineConfig, FlowrConfigOptions } from '../config';
+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:
@@ -27,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.
@@ -80,22 +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>;
     /**