@eagleoutice/flowr 2.8.15 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/flowr",
-  "version": "2.8.15",
+  "version": "2.9.0",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -166,9 +166,9 @@
   "devDependencies": {
     "@commitlint/cli": "^19.7.1",
     "@commitlint/config-angular": "^19.7.1",
-    "@eagleoutice/eslint-config-flowr": "^1.0.27",
-    "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.34.0",
+    "@eagleoutice/eslint-config-flowr": "^1.0.36",
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "^9.39.2",
     "@j-ulrich/release-it-regex-bumper": "^5.3.0",
     "@types/command-line-args": "^5.2.3",
     "@types/command-line-usage": "^5.0.4",
@@ -184,7 +184,7 @@
     "@typescript-eslint/eslint-plugin": "^8.40.0",
     "@vitest/coverage-v8": "^3.2.4",
     "esbuild": "^0.27.2",
-    "eslint": "^9.34.0",
+    "eslint": "^9.39.2",
     "license-checker-rseidelsohn": "^4.4.2",
     "npm-run-all": "^4.1.5",
     "release-it": "^19.2.3",

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

@@ -6,12 +6,19 @@ import type { FlowrConfigOptions } from '../../config';
 import type { FlowrFileProvider } from './flowr-file';
 import type { ReadOnlyFlowrAnalyzerEnvironmentContext } from './flowr-analyzer-environment-context';
 import { FlowrAnalyzerEnvironmentContext } from './flowr-analyzer-environment-context';
+import type { ReadOnlyFlowrAnalyzerMetaContext } from './flowr-analyzer-meta-context';
+import { FlowrAnalyzerMetaContext } from './flowr-analyzer-meta-context';
+import type { FlowrAnalyzer } from '../flowr-analyzer';
 /**
  * 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}).
  * If you are a {@link FlowrAnalyzerPlugin} and want to modify the context, you can use the {@link FlowrAnalyzerContext} directly.
  */
 export interface ReadOnlyFlowrAnalyzerContext {
+    /**
+     * The meta context provides access to the project metadata such as name, version, and namespace.
+     */
+    readonly meta: ReadOnlyFlowrAnalyzerMetaContext;
     /**
      * The files context provides access to the files to be analyzed and their loading order.
      */
@@ -46,11 +53,20 @@ export interface ReadOnlyFlowrAnalyzerContext {
  * If you are just interested in inspecting the context, you can use {@link ReadOnlyFlowrAnalyzerContext} instead (e.g., via {@link inspect}).
  */
 export declare class FlowrAnalyzerContext implements ReadOnlyFlowrAnalyzerContext {
+    readonly meta: FlowrAnalyzerMetaContext;
     readonly files: FlowrAnalyzerFilesContext;
     readonly deps: FlowrAnalyzerDependenciesContext;
     readonly env: FlowrAnalyzerEnvironmentContext;
+    private _analyzer;
     readonly config: FlowrConfigOptions;
     constructor(config: FlowrConfigOptions, plugins: ReadonlyMap<PluginType, readonly FlowrAnalyzerPlugin[]>);
+    /**
+     * Provides the analyzer associated with this context, if any.
+     * This is usually set when the context is used within an analyzer instance.
+     * Please note, that this may be `undefined` if the context is used standalone (e.g., during setup or in plugins that do not have access to the analyzer).
+     */
+    get analyzer(): FlowrAnalyzer | undefined;
+    setAnalyzer(analyzer: FlowrAnalyzer): void;
     /** delegate request addition */
     addRequests(requests: readonly RAnalysisRequest[]): void;
     addFile(f: string | FlowrFileProvider | RParseRequestFromFile): void;
@@ -64,7 +80,7 @@ export declare class FlowrAnalyzerContext implements ReadOnlyFlowrAnalyzerContex
      */
     inspect(): ReadOnlyFlowrAnalyzerContext;
     /**
-     * Reset the context to its initial state, removing all files, dependencies, and loading orders.
+     * Reset the context to its initial state, e.g., removing all files, dependencies, and loading orders.
      */
     reset(): void;
 }

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

@@ -13,6 +13,7 @@ const retriever_1 = require("../../r-bridge/retriever");
 const config_1 = require("../../config");
 const flowr_file_1 = require("./flowr-file");
 const flowr_analyzer_environment_context_1 = require("./flowr-analyzer-environment-context");
+const flowr_analyzer_meta_context_1 = require("./flowr-analyzer-meta-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})
@@ -26,9 +27,11 @@ const flowr_analyzer_environment_context_1 = require("./flowr-analyzer-environme
  * If you are just interested in inspecting the context, you can use {@link ReadOnlyFlowrAnalyzerContext} instead (e.g., via {@link inspect}).
  */
 class FlowrAnalyzerContext {
+    meta;
     files;
     deps;
     env;
+    _analyzer;
     config;
     constructor(config, plugins) {
         this.config = config;
@@ -37,6 +40,18 @@ class FlowrAnalyzerContext {
         this.env = new flowr_analyzer_environment_context_1.FlowrAnalyzerEnvironmentContext(this);
         const functions = new flowr_analyzer_functions_context_1.FlowrAnalyzerFunctionsContext(this);
         this.deps = new flowr_analyzer_dependencies_context_1.FlowrAnalyzerDependenciesContext(functions, (plugins.get(flowr_analyzer_plugin_1.PluginType.DependencyIdentification) ?? []));
+        this.meta = new flowr_analyzer_meta_context_1.FlowrAnalyzerMetaContext();
+    }
+    /**
+     * Provides the analyzer associated with this context, if any.
+     * This is usually set when the context is used within an analyzer instance.
+     * Please note, that this may be `undefined` if the context is used standalone (e.g., during setup or in plugins that do not have access to the analyzer).
+     */
+    get analyzer() {
+        return this._analyzer;
+    }
+    setAnalyzer(analyzer) {
+        this._analyzer = analyzer;
     }
     /** delegate request addition */
     addRequests(requests) {
@@ -62,11 +77,12 @@ class FlowrAnalyzerContext {
         return this;
     }
     /**
-     * Reset the context to its initial state, removing all files, dependencies, and loading orders.
+     * Reset the context to its initial state, e.g., removing all files, dependencies, and loading orders.
      */
     reset() {
         this.files.reset();
         this.deps.reset();
+        this.meta.reset();
     }
 }
 exports.FlowrAnalyzerContext = FlowrAnalyzerContext;

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

@@ -0,0 +1,51 @@
+import type { SemVer } from 'semver';
+export interface ReadOnlyFlowrAnalyzerMetaContext {
+    /**
+     * The name of this context.
+     */
+    readonly name: string;
+    /**
+     * Get the project name.
+     */
+    getProjectName(): string | undefined;
+    /**
+     * Get the project title.
+     */
+    getProjectTitle(): string | undefined;
+    /**
+     * Get the project version.
+     */
+    getProjectVersion(): SemVer & {
+        str: string;
+    } | undefined;
+    /**
+     * Get the project namespace.
+     * Any symbol resolve like `a::b` will resolve against this, if `a` matches the namespace.
+     */
+    getNamespace(): string | undefined;
+}
+/**
+ * This is the context responsible for managing the project metadata such as name, version, title, and namespace.
+ *
+ * If you are interested in inspecting this metadata, refer to {@link ReadOnlyFlowrAnalyzerMetaContext}.
+ */
+export declare class FlowrAnalyzerMetaContext implements ReadOnlyFlowrAnalyzerMetaContext {
+    readonly name = "flowr-analyzer-meta-context";
+    private projectName;
+    private projectTitle;
+    private projectVersion;
+    private namespace;
+    reset(): void;
+    setProjectName(name: string): void;
+    getProjectName(): string | undefined;
+    setProjectTitle(title: string): void;
+    getProjectTitle(): string | undefined;
+    setProjectVersion(version: SemVer & {
+        str: string;
+    }): void;
+    getProjectVersion(): SemVer & {
+        str: string;
+    } | undefined;
+    setNamespace(namespace: string): void;
+    getNamespace(): string | undefined;
+}

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

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowrAnalyzerMetaContext = void 0;
+/**
+ * This is the context responsible for managing the project metadata such as name, version, title, and namespace.
+ *
+ * If you are interested in inspecting this metadata, refer to {@link ReadOnlyFlowrAnalyzerMetaContext}.
+ */
+class FlowrAnalyzerMetaContext {
+    name = 'flowr-analyzer-meta-context';
+    projectName;
+    projectTitle;
+    projectVersion;
+    namespace;
+    reset() {
+        this.projectName = undefined;
+        this.projectTitle = undefined;
+        this.projectVersion = undefined;
+        this.namespace = undefined;
+    }
+    setProjectName(name) {
+        this.projectName = name;
+    }
+    getProjectName() {
+        return this.projectName;
+    }
+    setProjectTitle(title) {
+        this.projectTitle = title;
+    }
+    getProjectTitle() {
+        return this.projectTitle;
+    }
+    setProjectVersion(version) {
+        this.projectVersion = version;
+    }
+    getProjectVersion() {
+        return this.projectVersion;
+    }
+    setNamespace(namespace) {
+        this.namespace = namespace;
+    }
+    getNamespace() {
+        return this.namespace;
+    }
+}
+exports.FlowrAnalyzerMetaContext = FlowrAnalyzerMetaContext;
+//# sourceMappingURL=flowr-analyzer-meta-context.js.map

package/project/flowr-analyzer.d.ts

@@ -12,10 +12,11 @@ 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 type { RParseRequest, RParseRequestFromFile } from '../r-bridge/retriever';
 import { fileProtocol } from '../r-bridge/retriever';
 import type { FlowrFileProvider } from './context/flowr-file';
 import type { CallGraph } from '../dataflow/graph/call-graph';
+import type { Tree } from 'web-tree-sitter';
 /**
  * Extends the {@link ReadonlyFlowrAnalysisProvider} with methods that allow modifying the analyzer state.
  */
@@ -47,6 +48,7 @@ export interface FlowrAnalysisProvider<Parser extends KnownParser = KnownParser>
 /**
  * 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.
+ * You can also use {@link ReadonlyFlowrAnalysisProvider#parseStandalone|parseStandalone} to parse standalone R code snippets.
  */
 export interface ReadonlyFlowrAnalysisProvider<Parser extends KnownParser = KnownParser> {
     /**
@@ -71,6 +73,12 @@ export interface ReadonlyFlowrAnalysisProvider<Parser extends KnownParser = Know
      * Peek at the parse output for the request, if it was already computed.
      */
     peekParse(): NonNullable<AnalyzerCacheType<Parser>['parse']> | undefined;
+    /**
+     * Parse standalone R code provided as a string or via the `file://` protocol.
+     * @note this method will always use the {@link TreeSitterExecutor} internally, make sure it is initialized!
+     * @param data - The R code to parse, either as a string or as a `file://` URL.
+     */
+    parseStandalone(data: `${typeof fileProtocol}${string}` | string | RParseRequest): Tree;
     /**
      * Get the normalized abstract syntax tree for the request.
      * @param force - Do not use the cache, instead force new analyses.
@@ -81,6 +89,12 @@ export interface ReadonlyFlowrAnalysisProvider<Parser extends KnownParser = Know
      * Peek at the normalized abstract syntax tree for the request, if it was already computed.
      */
     peekNormalize(): NormalizedAst & PipelinePerStepMetaInformation | undefined;
+    /**
+     * Normalize standalone R code provided as a string or via the `file://` protocol.
+     * @note this method will always use the {@link TreeSitterExecutor} internally, make sure it is initialized!
+     * @param data - The R code to normalize, either as a string or as a `file://` URL.
+     */
+    normalizeStandalone(data: `${typeof fileProtocol}${string}` | string | RParseRequest): NormalizedAst;
     /**
      * Get the dataflow graph for the request.
      * @param force - Do not use the cache, instead force new analyses.
@@ -156,6 +170,8 @@ export declare class FlowrAnalyzer<Parser extends KnownParser = KnownParser> imp
     parserInformation(): KnownParserInformation;
     inspectContext(): ReadOnlyFlowrAnalyzerContext;
     reset(): void;
+    parseStandalone(data: `${typeof fileProtocol}${string}` | string | RParseRequest): Tree;
+    normalizeStandalone(data: `${typeof fileProtocol}${string}` | string | RParseRequest): NormalizedAst;
     addRequest(...request: (RAnalysisRequest | readonly RAnalysisRequest[] | `${typeof fileProtocol}${string}` | string)[]): this;
     addFile(...f: (string | FlowrFileProvider | RParseRequestFromFile)[]): this;
     /**

package/project/flowr-analyzer.js

@@ -2,10 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowrAnalyzer = void 0;
 const query_1 = require("../queries/query");
+const decorate_1 = require("../r-bridge/lang-4.x/ast/model/processing/decorate");
 const flowr_search_executor_1 = require("../search/flowr-search-executor");
 const cfg_kind_1 = require("./cfg-kind");
 const retriever_1 = require("../r-bridge/retriever");
 const files_1 = require("../util/files");
+const tree_sitter_normalize_1 = require("../r-bridge/lang-4.x/tree-sitter/tree-sitter-normalize");
+const tree_sitter_executor_1 = require("../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor");
 /**
  * Central class for conducting analyses with FlowR.
  * Use the {@link FlowrAnalyzerBuilder} to create a new instance.
@@ -32,6 +35,7 @@ class FlowrAnalyzer {
     constructor(parser, ctx, cache) {
         this.parser = parser;
         this.ctx = ctx;
+        ctx.setAnalyzer(this);
         this.cache = cache;
     }
     get flowrConfig() {
@@ -51,6 +55,20 @@ class FlowrAnalyzer {
         this.ctx.reset();
         this.cache.reset();
     }
+    parseStandalone(data) {
+        const request = (0, retriever_1.isParseRequest)(data) ? data : (0, retriever_1.requestFromInput)(data);
+        if (this.parser.name === 'tree-sitter') {
+            return this.parser.parse(request);
+        }
+        else {
+            const ts = new tree_sitter_executor_1.TreeSitterExecutor();
+            return ts.parse(request);
+        }
+    }
+    normalizeStandalone(data) {
+        const parse = this.parseStandalone(data);
+        return (0, decorate_1.decorateAst)((0, tree_sitter_normalize_1.normalizeTreeSitterTreeToAst)([{ parsed: parse, filePath: undefined }], true), {});
+    }
     addRequest(...request) {
         for (const r of request) {
             if (typeof r === 'string') {

package/project/plugins/file-plugins/files/flowr-description-file.d.ts

@@ -3,6 +3,7 @@ import type { RAuthorInfo } from '../../../../util/r-author';
 import type { DeepReadonly } from 'ts-essentials';
 import type { RLicenseElementInfo } from '../../../../util/r-license';
 import { Package, type PackageType } from '../../package-version-plugins/package';
+import type { SemVer } from 'semver';
 export type DCF = Map<string, string[]>;
 /**
  * This decorates a text file and provides access to its content as a DCF (Debian Control File)-like structure.
@@ -31,6 +32,12 @@ export declare class FlowrDescriptionFile extends FlowrFile<DeepReadonly<DCF>> {
      * Returns the parsed license information from the 'License' field in the DESCRIPTION file.
      */
     license(): RLicenseElementInfo[] | undefined;
+    /**
+     * Returns the parsed version from the 'Version' field in the DESCRIPTION file.
+     */
+    version(): SemVer & {
+        str: string;
+    } | undefined;
     /**
      * Returns the parsed authors from the `Authors@R` field in the DESCRIPTION file.
      */
@@ -51,6 +58,14 @@ export declare class FlowrDescriptionFile extends FlowrFile<DeepReadonly<DCF>> {
      * Returns the parsed imports from the 'Imports' field in the DESCRIPTION file.
      */
     imports(): readonly Package[] | undefined;
+    /**
+     * Returns the package name from the 'Package' field in the DESCRIPTION file.
+     */
+    packageName(): string | undefined;
+    /**
+     * Returns the package title from the 'Title' field in the DESCRIPTION file.
+     */
+    packageTitle(): string | undefined;
 }
 /**
  * Parses the 'License' field from an R DESCRIPTION file into SPDX license expressions.

package/project/plugins/file-plugins/files/flowr-description-file.js

@@ -9,6 +9,7 @@ const args_1 = require("../../../../util/text/args");
 const r_license_1 = require("../../../../util/r-license");
 const package_1 = require("../../package-version-plugins/package");
 const retriever_1 = require("../../../../r-bridge/retriever");
+const r_version_1 = require("../../../../util/r-version");
 /**
  * This decorates a text file and provides access to its content as a DCF (Debian Control File)-like structure.
  * Please use the static {@link FlowrDescriptionFile.from} method to create instances of this class.
@@ -52,6 +53,17 @@ class FlowrDescriptionFile extends flowr_file_1.FlowrFile {
         }
         return parseRLicenseField(...licenses);
     }
+    /**
+     * Returns the parsed version from the 'Version' field in the DESCRIPTION file.
+     */
+    version() {
+        const v = this.content().get('Version');
+        if (!v || v.length === 0) {
+            return undefined;
+        }
+        const verStr = v[0].trim();
+        return (0, r_version_1.parseRVersion)(verStr);
+    }
     /**
      * Returns the parsed authors from the `Authors@R` field in the DESCRIPTION file.
      */
@@ -93,6 +105,20 @@ class FlowrDescriptionFile extends flowr_file_1.FlowrFile {
         const imps = this.content().get('Imports');
         return imps ? parsePackagesWithVersions(imps, 'package') : undefined;
     }
+    /**
+     * Returns the package name from the 'Package' field in the DESCRIPTION file.
+     */
+    packageName() {
+        const names = this.content().get('Package');
+        return names && names.length > 0 ? names[0] : names?.join(' ');
+    }
+    /**
+     * Returns the package title from the 'Title' field in the DESCRIPTION file.
+     */
+    packageTitle() {
+        const titles = this.content().get('Title');
+        return titles && titles.length > 0 ? titles[0] : titles?.join(' ');
+    }
 }
 exports.FlowrDescriptionFile = FlowrDescriptionFile;
 /**

package/project/plugins/file-plugins/files/flowr-namespace-file.d.ts

@@ -1,5 +1,7 @@
 import type { FileRole, FlowrFileProvider } from '../../../context/flowr-file';
 import { FlowrFile } from '../../../context/flowr-file';
+import type { RNode } from '../../../../r-bridge/lang-4.x/ast/model/model';
+import type { FlowrAnalyzerContext } from '../../../context/flowr-analyzer-context';
 export interface NamespaceInfo {
     exportedSymbols: string[];
     exportedFunctions: string[];
@@ -7,6 +9,11 @@ export interface NamespaceInfo {
     exportedPatterns: string[];
     importedPackages: Map<string, string[] | 'all'>;
     loadsWithSideEffects: boolean;
+    /**
+     * This will only be present in complex parsed NAMESPACE files and tell you
+     * about which parts are only active with given conditions!
+     */
+    conditional?: Map<RNode, NamespaceInfo>;
 }
 export interface NamespaceFormat {
     current: NamespaceInfo;
@@ -14,21 +21,28 @@ export interface NamespaceFormat {
 }
 /**
  * This decorates a text file and provides access to its content in the {@link NamespaceFormat}.
+ * Namespace files can be parsed in a simple mode which is much quicker, but does not support `if`/other R-constructs!
  */
 export declare class FlowrNamespaceFile extends FlowrFile<NamespaceFormat> {
     private readonly wrapped;
+    private readonly ctx;
     /**
      * Prefer the static {@link FlowrNamespaceFile.from} method to create instances of this class as it will not re-create if already a namespace file
      * and handle role assignments.
      */
-    constructor(file: FlowrFileProvider);
+    constructor(file: FlowrFileProvider, ctx?: FlowrAnalyzerContext);
     /**
      * Loads and parses the content of the wrapped file in the {@link NamespaceFormat}.
-     * @see {@link parseNamespace} for details on the parsing logic.
+     * @see {@link parseNamespaceSimple} for details on the parsing logic.
+     * @see {@link parseNamespaceComplex} for a more complex parser.
      */
     protected loadContent(): NamespaceFormat;
     /**
      * Namespace file lifter, this does not re-create if already a namespace file
+     * and handles role assignments.
+     * @param file - The file to lift or return if already a namespace file
+     * @param ctx - An optional analyzer context to use for complex parsing
+     * @param role - An optional role to assign to the file
      */
-    static from(file: FlowrFileProvider | FlowrNamespaceFile, role?: FileRole): FlowrNamespaceFile;
+    static from(file: FlowrFileProvider | FlowrNamespaceFile, ctx?: FlowrAnalyzerContext, role?: FileRole): FlowrNamespaceFile;
 }