@eagleoutice/flowr 2.8.11 → 2.8.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagleoutice/flowr",
-  "version": "2.8.11",
+  "version": "2.8.12",
   "description": "Static Dataflow Analyzer and Program Slicer for the R Programming Language",
   "types": "dist/src/index.d.ts",
   "repository": {

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

@@ -6,6 +6,10 @@ import { Package, type PackageType } from '../../package-version-plugins/package
 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.
+ * Please use the static {@link FlowrDescriptionFile.from} method to create instances of this class.
+ * To access description specific fields, use the provided methods like {@link license}, {@link authors}, {@link suggests}, and {@link collate}.
+ * These methods parse and return the relevant information in structured formats.
+ * To access raw fields, use the {@link content} method inherited from {@link FlowrFile}.
  */
 export declare class FlowrDescriptionFile extends FlowrFile<DeepReadonly<DCF>> {
     private readonly wrapped;
@@ -31,7 +35,22 @@ export declare class FlowrDescriptionFile extends FlowrFile<DeepReadonly<DCF>> {
      * Returns the parsed authors from the `Authors@R` field in the DESCRIPTION file.
      */
     authors(): RAuthorInfo[] | undefined;
+    /**
+     * Returns the parsed suggested packages from the 'Suggests' field in the DESCRIPTION file.
+     */
     suggests(): Package[] | undefined;
+    /**
+     * Returns the 'Collate' field from the DESCRIPTION file.
+     */
+    collate(): readonly string[] | undefined;
+    /**
+     * Returns the parsed dependencies from the 'Depends' field in the DESCRIPTION file.
+     */
+    depends(): readonly Package[] | undefined;
+    /**
+     * Returns the parsed imports from the 'Imports' field in the DESCRIPTION file.
+     */
+    imports(): readonly Package[] | undefined;
 }
 /**
  * Parses the 'License' field from an R DESCRIPTION file into SPDX license expressions.

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

@@ -8,8 +8,13 @@ const r_author_1 = require("../../../../util/r-author");
 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");
 /**
  * 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.
+ * To access description specific fields, use the provided methods like {@link license}, {@link authors}, {@link suggests}, and {@link collate}.
+ * These methods parse and return the relevant information in structured formats.
+ * To access raw fields, use the {@link content} method inherited from {@link FlowrFile}.
  */
 class FlowrDescriptionFile extends flowr_file_1.FlowrFile {
     wrapped;
@@ -59,10 +64,35 @@ class FlowrDescriptionFile extends flowr_file_1.FlowrFile {
         const parsedAuthors = authors?.flatMap(a => (0, r_author_1.parseTextualAuthorString)(a, [r_author_1.AuthorRole.Author])) ?? [];
         return parsedAuthors.concat(this.content().get('Maintainer')?.flatMap(m => (0, r_author_1.parseTextualAuthorString)(m, [r_author_1.AuthorRole.Creator])) ?? []);
     }
+    /**
+     * Returns the parsed suggested packages from the 'Suggests' field in the DESCRIPTION file.
+     */
     suggests() {
         const suggests = this.content().get('Suggests');
         return suggests ? parsePackagesWithVersions(suggests, 'package') : undefined;
     }
+    /**
+     * Returns the 'Collate' field from the DESCRIPTION file.
+     */
+    collate() {
+        const c = this.content().get('Collate');
+        // we join newlines, and then split quote sensitive:
+        return c ? (0, args_1.splitAtEscapeSensitive)(c.join(' '), true, ' ').map(s => (0, retriever_1.removeRQuotes)(s).trim()).filter(s => s.length > 0) : undefined;
+    }
+    /**
+     * Returns the parsed dependencies from the 'Depends' field in the DESCRIPTION file.
+     */
+    depends() {
+        const deps = this.content().get('Depends');
+        return deps ? parsePackagesWithVersions(deps, 'r') : undefined;
+    }
+    /**
+     * Returns the parsed imports from the 'Imports' field in the DESCRIPTION file.
+     */
+    imports() {
+        const imps = this.content().get('Imports');
+        return imps ? parsePackagesWithVersions(imps, 'package') : undefined;
+    }
 }
 exports.FlowrDescriptionFile = FlowrDescriptionFile;
 /**
@@ -117,25 +147,26 @@ function cleanValues(values) {
         .map(s => s.trim())
         .filter(s => s.length > 0);
 }
-const VersionRegex = /^([a-zA-Z0-9.]+)(?:\s*\(([><=~!]+)\s*([^)]+)\))?$/;
+const VersionRegex = /([a-zA-Z0-9.]+)(?:\s*\(([><=~!]+)\s*([^)]+)\))?\s*/;
 /**
  * Parses package strings with optional version constraints into Package objects.
  * @param packageStrings - The package strings to parse
  * @param type           - The type of the packages (e.g., 'r' or 'package')
  */
 function parsePackagesWithVersions(packageStrings, type) {
+    let str = packageStrings.join(' ');
+    let match;
     const packages = [];
-    for (const entry of packageStrings) {
-        const match = VersionRegex.exec(entry);
-        if (match) {
-            const [, name, operator, version] = match;
-            const range = package_1.Package.parsePackageVersionRange(operator, version);
-            packages.push(new package_1.Package({
-                name: name,
-                type: type,
-                versionConstraints: range ? [range] : undefined
-            }));
-        }
+    // match until exhaustion
+    while ((match = VersionRegex.exec(str)) !== null) {
+        const [, name, operator, version] = match;
+        const range = package_1.Package.parsePackageVersionRange(operator, version);
+        packages.push(new package_1.Package({
+            name: name,
+            type: type,
+            versionConstraints: range ? [range] : undefined
+        }));
+        str = str.slice(match.index + match[0].length);
     }
     return packages;
 }

package/project/plugins/loading-order-plugins/flowr-analyzer-loading-order-description-file-plugin.js

@@ -5,7 +5,6 @@ const flowr_analyzer_description_file_plugin_1 = require("../file-plugins/flowr-
 const semver_1 = require("semver");
 const flowr_analyzer_loading_order_plugin_1 = require("./flowr-analyzer-loading-order-plugin");
 const flowr_file_1 = require("../../context/flowr-file");
-const retriever_1 = require("../../../r-bridge/retriever");
 /**
  * This plugin extracts loading order information from R `DESCRIPTION` files.
  * It looks at the `Collate` field to determine the order in which files should be loaded.
@@ -25,10 +24,8 @@ class FlowrAnalyzerLoadingOrderDescriptionFilePlugin extends flowr_analyzer_load
             flowr_analyzer_description_file_plugin_1.descriptionFileLog.warn(`Found ${descFiles.length} description files, expected exactly one.`);
         }
         /** this will do the caching etc. for me */
-        const deps = descFiles[0].content();
-        if (deps.has('Collate')) {
-            const collate = deps.get('Collate')?.map(f => (0, retriever_1.removeRQuotes)(f))
-                ?? [];
+        const collate = descFiles[0].collate();
+        if (collate) {
             /* we probably have to do some more guesswork here */
             const unordered = ctx.files.loadingOrder.getUnorderedRequests();
             // sort them by their path index in the Collate field

package/project/plugins/package-version-plugins/flowr-analyzer-package-versions-description-file-plugin.js

@@ -5,7 +5,6 @@ const flowr_analyzer_package_versions_plugin_1 = require("./flowr-analyzer-packa
 const flowr_analyzer_description_file_plugin_1 = require("../file-plugins/flowr-analyzer-description-file-plugin");
 const semver_1 = require("semver");
 const flowr_file_1 = require("../../context/flowr-file");
-const flowr_description_file_1 = require("../file-plugins/files/flowr-description-file");
 /**
  * This plugin extracts package versions from R `DESCRIPTION` files.
  * It looks at the `Depends` and `Imports` fields to find package names and their version constraints.
@@ -24,12 +23,12 @@ class FlowrAnalyzerPackageVersionsDescriptionFilePlugin extends flowr_analyzer_p
             flowr_analyzer_description_file_plugin_1.descriptionFileLog.warn(`Found ${descFiles.length} description files, expected exactly one.`);
         }
         /** this will do the caching etc. for me */
-        const deps = descFiles[0].content();
-        this.retrieveVersionsFromField(ctx, deps, 'Depends', 'r');
-        this.retrieveVersionsFromField(ctx, deps, 'Imports', 'package');
+        const deps = descFiles[0];
+        this.retrieveVersionsFromField(ctx, deps.depends() ?? []);
+        this.retrieveVersionsFromField(ctx, deps.imports() ?? []);
     }
-    retrieveVersionsFromField(ctx, file, field, type) {
-        for (const pkg of (0, flowr_description_file_1.parsePackagesWithVersions)(file.get(field) ?? [], type)) {
+    retrieveVersionsFromField(ctx, pkgs) {
+        for (const pkg of pkgs) {
             ctx.deps.addDependency(pkg);
         }
     }

package/queries/catalog/dependencies-query/dependencies-query-executor.js

@@ -36,12 +36,13 @@ async function executeDependenciesQuery({ analyzer, }, queries) {
     }
     const queryResults = functions.values().toArray().flat().length === 0 ? { kinds: {}, '.meta': { timing: 0 } } :
         await (0, query_1.executeQueriesOfSameType)(data, functions.entries().map(([c, f]) => makeCallContextQuery(f, c)).toArray().flat());
+    const g = (0, dependencies_query_format_1.getAllCategories)(queries);
     const results = Object.fromEntries(await Promise.all(functions.entries().map(async ([c, f]) => {
         const results = getResults(queries, { dataflow, config, normalize }, queryResults, c, f, data);
         // only default categories allow additional analyses, so we null-coalesce here!
         const enabled = query.enabledCategories;
         if (enabled === undefined || (enabled?.length > 0 && enabled.includes(c))) {
-            await dependencies_query_format_1.DefaultDependencyCategories[c]?.additionalAnalysis?.(data, ignoreDefault, f, queryResults, results);
+            await g[c]?.additionalAnalysis?.(data, ignoreDefault, f, queryResults, results);
         }
         return [c, results];
     })));

package/queries/catalog/dependencies-query/dependencies-query-format.d.ts

@@ -5,7 +5,7 @@ import { executeDependenciesQuery } from './dependencies-query-executor';
 import type { FunctionInfo } from './function-info/function-info';
 import type { CallContextQueryResult } from '../call-context-query/call-context-query-format';
 import type { Range } from 'semver';
-import type { AsyncOrSync } from 'ts-essentials';
+import type { AsyncOrSync, MarkOptional } from 'ts-essentials';
 import type { NamespaceInfo } from '../../../project/plugins/file-plugins/files/flowr-namespace-file';
 export declare const Unknown = "unknown";
 export interface DependencyCategorySettings {
@@ -13,6 +13,15 @@ export interface DependencyCategorySettings {
     functions: FunctionInfo[];
     /** this describes the global default value for this category, e.g., 'stdout' for write operations, please be aware, that this can be overwritten by a by-function default value */
     defaultValue?: string;
+    /**
+     * An optional additional analysis step that is executed after the main function-based analysis has been performed.
+     * To add or modify dependency info entries, simply modify the `result` array.
+     * @param data  - The basic query data.
+     * @param ignoreDefault - Whether the default functions were ignored.
+     * @param functions - The functions used for this category.
+     * @param queryResults - The results of the call context query.
+     * @param result - The current result array to which additional dependency info can be added.
+     */
     additionalAnalysis?: (data: BasicQueryData, ignoreDefault: boolean, functions: FunctionInfo[], queryResults: CallContextQueryResult, result: DependencyInfo[]) => AsyncOrSync<void>;
 }
 export declare const DefaultDependencyCategories: {
@@ -52,7 +61,7 @@ export interface DependenciesQuery extends BaseQueryFormat, Partial<Record<`${De
     readonly type: 'dependencies';
     readonly enabledCategories?: DependencyCategoryName[];
     readonly ignoreDefaultFunctions?: boolean;
-    readonly additionalCategories?: Record<string, Omit<DependencyCategorySettings, 'additionalAnalysis'>>;
+    readonly additionalCategories?: Record<string, MarkOptional<DependencyCategorySettings, 'additionalAnalysis'>>;
 }
 export type DependenciesQueryResult = BaseQueryResult & {
     [C in DefaultDependencyCategoryName]: DependencyInfo[];

package/util/version.js

@@ -6,7 +6,7 @@ exports.printVersionInformation = printVersionInformation;
 const semver_1 = require("semver");
 const assert_1 = require("./assert");
 // this is automatically replaced with the current version by release-it
-const version = '2.8.11';
+const version = '2.8.12';
 /**
  * Retrieves the current flowR version as a new {@link SemVer} object.
  */